feat(memory) add observational memory provider

[intertwine]

What does this PR do?

Adds Observational Memory as a first-class Hermes memory provider on top of current main, split out from the broader mixed-scope branch in #4787.

This version keeps the scope to the OM integration itself:

• adds plugins/memory/observational_memory/ as a memory provider plugin
• adds provider tests in tests/agent/test_observational_memory_provider.py
• wires the provider into Hermes memory setup/help/docs
• bumps the OM dependency floor to observational-memory>=0.5.1

Related Issue

Follow-up split of #4787.

Type of Change

• ✨ New feature (non-breaking change that adds functionality)
• 📝 Documentation update
• ✅ Tests (adding or improving test coverage)

Changes Made

• added plugins/memory/observational_memory/init.py-style provider integration for shared local OM memory
• added provider docs and plugin metadata under plugins/memory/observational_memory/
• added focused provider coverage in tests/agent/test_observational_memory_provider.py
• updated Hermes memory setup/help/docs to include Observational Memory in the current provider lineup
• refreshed the OM dependency floor to 0.5.1 so Hermes writeback inherits OM's GPT-5/o-series OpenAI compatibility fix

How to Test

1. Install OM into the Hermes environment: pip install "observational-memory>=0.5.1"
2. Run hermes memory setup and select observational_memory
3. Run the focused provider validation:

PYTHONPATH=/path/to/observational-memory/src \
uv run --extra dev python -m pytest -o addopts='' \
  tests/agent/test_observational_memory_provider.py \
  tests/agent/test_memory_provider.py \
  tests/run_agent/test_memory_provider_init.py -q

Expected result: 67 passed

Platforms Tested

• macOS (local targeted validation)
• Linux via GitHub Actions

Checklist

• I've read the Contributing Guide
• My PR contains only changes related to this feature
• I've added tests for my changes
• I've updated relevant documentation
• I've run pytest tests/ -q and all tests pass locally

[intertwine]

Carrying over a short positioning note from the now-closed #4787 because it helps frame where this provider fits in the Hermes memory lineup.

Observational Memory is strongest when the goal is cross-agent continuity that stays local and inspectable. In practice that means Hermes can share the same markdown memory store with Claude Code and Codex, while still giving users readable files, local search, compact startup context, and optional writeback.

Relative to the other providers:

• compared with Honcho, Mem0, and RetainDB, this is much more local and transparent, with less SaaS / black-box behavior
• compared with OpenViking, Hindsight, and ByteRover, this is less about hierarchy / graph-style knowledge management and more about stable session continuity plus derived startup context
• compared with Holographic, this is less of a local fact DB and more of a shared observation layer across multiple agent tools

The underlying observational-memory package is based on Mastra's Observational Memory pattern: an Observer + Reflector that compresses conversation history into a stable observation log and compact startup memory, instead of depending only on per-turn dynamic retrieval.

Mastra's published results for that underlying OM architecture report 84.23% on LongMemEval with gpt-4o and 94.87% with gpt-5-mini. Important precision note: those benchmark numbers are for the underlying OM approach, not for this Hermes provider implementation specifically, but they are the main reason I thought it was worth bringing this pattern into Hermes.

I also added a longer version of this positioning note to the standalone plugin README here:
https://github.com/intertwine/hermes-observational-memory

[intertwine]

@ZaynJarvis this is ready for an OM-focused review when you have a window.

I refreshed the split PR onto current main (6fdbf2f2) without broadening the diff. The PR still only touches the Observational Memory provider, its focused tests, and the memory docs/setup wiring:

• plugins/memory/observational_memory/
• tests/agent/test_observational_memory_provider.py
• hermes_cli memory setup/help wiring
• memory provider docs

Current validation:

• Focused OM/local memory validation: 67 passed
• docs-site-checks: passing
• e2e: passing
• Nix macOS/Ubuntu: passing
• attribution / supply-chain / lockfile checks: passing

The only remaining red check is the full test job. I compared it against the latest main push at 6fdbf2f2, and the same 14 failures are present there as baseline failures. None are in the OM provider or touched files; they are in MiniMax/provider, gateway cache, skills config, tips, concurrent interrupt, browser/CDP, file tools, MCP shutdown, write-deny, and zombie cleanup tests.

So from the perspective of this PR's scope: the stale docs/Docker blockers are gone, the OM-specific coverage is green, and the remaining full-suite red is current-main baseline rather than introduced by this diff.

This PR is the scoped replacement for #4787 and now satisfies the split requested there: OM only, no redaction/gateway/CI hardening changes bundled in.

[ZaynJarvis]

for new plugin support. recommend go to Discord #developer channel to submit feature request, would probably be discussed thoroughly

[intertwine]

Update: I followed Zayn's suggestion and posted the native-provider discussion in the Discord plugin channel/thread.

I also refreshed this PR onto current main (7d66d30d7) and narrowed the diff further. It now only touches the OM provider, plugin metadata/README, Hermes memory setup/help wiring, and focused OM tests. I removed the website docs changes so this PR no longer triggers the unrelated docs-site check.

Current validation:

• Focused OM/provider validation: 69 passed
• e2e: passing
• Nix macOS/Ubuntu: passing
• attribution / supply-chain: passing
• focused ruff/format/ty on OM files: passing

Remaining red checks appear unrelated to this diff:

• Full test: same 41 failures as current main at 7d66d30d7; no OM/touched-file failures and no PR-only failure set.
• ruff + ty diff: ruff has 0 new issues and ty has 0 new issues; the job fails only when actions/github-script tries to create/update the lint PR comment from this fork and GitHub returns 403 Resource not accessible by integration.

So the OM-specific surface is green; the remaining red is current-main baseline plus a fork-permission issue in the advisory lint-comment step.

[kshitijk4poor]

Thanks for the contribution!

Per the updated CONTRIBUTING.md, new memory providers are no longer accepted as in-tree additions to plugins/memory/:

Memory Providers: CLOSED to new in-tree additions
PRs adding to plugins/memory/ will be closed. Publish as standalone plugin into ~/.hermes/plugins/ or via pip entry point. Must implement MemoryProvider ABC (sync_turn, prefetch, shutdown, optional post_setup).

Closing this in line with that policy. The path forward is to publish it as a standalone plugin so users can install it directly without touching the Hermes source tree. Once it's published, a small docs PR adding it to the Community plugins section of the README is welcome.

Sorry for the bump — appreciate the time you put into this.