feat(integrations): Hermes memory provider core

[raman325]

Per @igorls I am splitting #1684 into two separate PRs and this is the first — the provider core and tests, as recommended. I attempted to resolve all of your blockers but may have missed e.g. some helpers that are available for use — I gave Fable a good run at it though!

What this adds

A MemPalace memory provider for Hermes (NousResearch/hermes-agent #6323): a Python class implementing Hermes' MemoryProvider ABC, exposing the full 27-tool MCP surface, with lifecycle hooks (sync_turn, on_session_end, on_pre_compress, session-switch bookkeeping), a cron/flush context guard so system-generated turns don't poison the palace, a bounded background worker so filing never blocks the conversation, and an AAAK wake-up cache.

The mempalace hermes install command, session backfill, and docs land in a stacked follow-up PR so this one stays reviewable.

Beyond the provider itself, this touches two core modules:

• convo_miner.py: new file_conversation_exchange() — a canonical write path for filing one verbatim exchange as a drawer, carrying the same metadata the convo miner writes (hall, entities, authored_at, ingest_mode, extract_mode, normalize_version, id_recipe). This exists so live integration writes and their backfills route through one implementation instead of two hand-rolled copies.
• ids.py: new make_exchange_drawer_id() alongside the existing recipes.

How the review blockers were addressed

• Conflicts with develop — rebuilt on the current develop tip; no conflicts.
• Paths bypassing backend/write helpers — all ChromaDB access goes through ChromaBackend.get_or_create_collection() (embedding function stays centralized, no dimension drift; writes inherit mine_palace_lock via ChromaCollection). Live turn filing routes through the new file_conversation_exchange() instead of a hand-rolled col.upsert. Tool calls delegate to mempalace.mcp_server.tool_* entry points rather than reimplementing them.
• Live/historical ingest parity — file_conversation_exchange() is the single write path both will share; the stacked backfill PR routes through it and has a regression test pinning wing-routing parity.
• Large-palace status/list operations — metadata scans in status/list_wings/list_rooms are capped (STATUS_SCAN_LIMIT = 5000) with structured truncation fields (truncated, scan coverage) so the model knows when a breakdown is partial.
• Packaging from a wheel — the integration lives at mempalace/integrations/hermes/ so it ships automatically via packages = ["mempalace"]; nothing depends on top-level files being adjacent to the installed package.

Why this lives at mempalace/integrations/hermes/ and not top-level integrations/hermes/

Top-level integrations/openclaw/ exists and the natural read is "put it next to that one." The asymmetry comes from how each integration is consumed at runtime:

• openclaw is a Claude Code skill — a single SKILL.md that Claude Code reads from the source repo. It doesn't need to be importable Python and it doesn't need to ship in the wheel.
• The Hermes integration is a Python class implementing the MemoryProvider ABC — Hermes' plugin loader imports the module and calls methods on it. mempalace hermes install has to find the source files at runtime after a wheel install in order to copy them into ~/.hermes/plugins/mempalace/ (the install command itself lands in the follow-up PR).

Tests

42 new tests in tests/test_hermes_integration.py covering the tool surface, lifecycle/worker behavior, wing routing, canonical drawer metadata, and the ChromaBackend round-trip that regression-checks the dimension-mismatch bug from prior in-tree Hermes attempts.

Backfill + install + docs PR to follow, stacked on this branch.

Behavior note: wing/room validation falls back instead of erroring

file_conversation_exchange() validates wing/room with the same sanitize_name rules the MCP write tools apply (blocks /, .., null bytes, over-length names). Unlike the MCP tools — which return an error to their caller — this path falls back on an invalid name: wing → wing_general, room → conversations, with a warning logged. Rationale: this function files live turns, and dropping a turn over a config typo would violate the verbatim / 100%-recall promise. Misrouted-but-recallable beats gone. (Raised in review; documented in the integration README in the follow-up PR.)

[gemini-code-assist]

Code Review

This pull request implements the MemPalace memory provider integration for Hermes, adding the file_conversation_exchange function, custom drawer ID generation, the MempalaceProvider class with background worker processing and tool dispatching, and a comprehensive test suite. The review feedback focuses on enhancing robustness and idiomatic Python usage, specifically suggesting to handle potential None elements in metadata scans, add type checks for parsed JSON configurations and keyword lists, utilize the context manager protocol for KnowledgeGraph instances, and wrap file system operations in try...except OSError blocks to prevent unexpected crashes.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[Copilot]

Pull request overview

This PR introduces the core of a Hermes MemoryProvider implementation backed by MemPalace, enabling Hermes to access MemPalace’s MCP tool surface and persist conversation turns without blocking the agent loop. It also adds a canonical conversation-exchange filing path and a new ID recipe to ensure live integration writes match the existing convo-miner metadata conventions.

Changes:

• Added MempalaceProvider for Hermes with lifecycle hooks, bounded background worker, and 27-tool MCP surface exposure.
• Added file_conversation_exchange() as the canonical write path for one verbatim exchange (shared by live integrations/backfills) plus a new make_exchange_drawer_id() recipe.
• Added a comprehensive test suite covering provider/tool behavior, lifecycle/worker behavior, wing routing, and canonical metadata expectations.

Reviewed changes

Copilot reviewed 4 out of 5 changed files in this pull request and generated 5 comments.

File	Description
tests/test_hermes_integration.py	New end-to-end and unit coverage for Hermes provider surface, lifecycle, and persistence behavior.
mempalace/integrations/hermes/init.py	New Hermes provider implementation and tool schema/dispatch logic.
mempalace/ids.py	Adds make_exchange_drawer_id() to avoid upsert collisions for exchange drawers.
mempalace/convo_miner.py	Adds file_conversation_exchange() canonical exchange filing helper used by integrations.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[igorls]

Thanks for splitting this out. Overall this is a strong direction: keeping the Hermes provider inside the package makes sense for wheel installs, routing live writes through a shared file_conversation_exchange() path is the right abstraction, and I appreciate the added coverage around lifecycle behavior, ChromaBackend usage, cron/flush guards, and canonical metadata.

I don’t think this is quite ready to merge yet, but it feels close. The main blockers I’d like fixed first are:

1. Duplicate filing across normal session lifecycle

   Hermes calls sync_turn() after completed turns, and then on_session_end() receives the full transcript at the session boundary. This provider currently files both paths, so the same user/assistant exchange can be written twice. Since make_exchange_drawer_id() includes filed_at, those duplicates usually become distinct drawers rather than idempotent rewrites.

   That would pollute recall over time, especially for long-running Hermes users. I think we need either:

   • on_session_end() to file only turns that were not already handled by sync_turn(), or
   • sync_turn() to be the live path and on_session_end() to avoid re-mining already-synced turns.

2. Passthrough tools can target a different palace than the provider

   The provider initializes live writes/search/status against self._palace_path, but many exposed tools delegate directly to mempalace.mcp_server.tool_*, which uses MemPalace’s global config. That means a Hermes profile configured with a custom palace_path can search one palace while mempalace_add_drawer, drawer CRUD, duplicate checks, tunnels, etc. read/write another.

   That is a pretty sharp footgun and could easily look like lost memories. I think the passthrough path needs to be made palace-scoped, or those tools should stay unexposed until they can honor the provider’s configured palace.

A couple of smaller follow-ups I noticed:

• on_memory_write() only mirrors target == "user", but Hermes’ memory tool defaults to target="memory" when omitted, so ordinary memory writes may not get mirrored.
• The provider stores state outside HERMES_HOME by default (~/.mempalace/...) but does not implement backup_paths(), so hermes backup would not include the actual MemPalace state.

So: I’m positive on the shape of this PR, but I’d request changes on the two lifecycle/config-path issues before merge.

[GoXLd]

Split off a fix for the two blockers @igorls raised above (duplicate filing between sync_turn()/on_session_end(), and passthrough tools bypassing the provider's configured palace_path), plus the two smaller follow-ups (on_memory_write default target, backup_paths()). Sent as raman325#2, stacked on this branch.

[raman325]

Thanks for the thorough review @igorls — all four points were real, and all four are now addressed. Point by point:

1. Duplicate filing across the session lifecycle — fixed in e6bb4b8; the capture side split to a follow-up to keep this PR scoped.

We took your second option and went a step further: sync_turn is now the sole filing path. on_session_end files nothing (it keeps only the wake-up-cache refresh) and on_pre_compress returns "" so it never promises persistence it didn't perform. _mine_session and the worker's re-filing branches are gone; tests pin the no-duplicate behavior.

The "file only what sync_turn missed" safety net is deliberately not in this PR. Doing it correctly turned out to be subtle: exact-text matching between sync_turn drawers and the raw transcript can never work — Hermes hands sync_turn the cleaned user message and think-stripped final response, while the raw message list carries injected skill content and tool traffic. The follow-up correlates turns via a content fingerprint of the raw user message stored in drawer metadata, scans the session's existing drawers (plus /branch lineage) at session end, and files only uncovered turns, with loss-safe fallbacks (no session id or failed scan → file rather than skip; the failure direction is always a duplicate, never a lost turn). That's designed and partially built, and will come as its own reviewable PR. In the meantime nothing duplicates and nothing durable is lost: every completed turn is filed exactly once by sync_turn.

2. Passthrough tools targeting a different palace — fixed in 73b3b31.

Three parts:

• initialize() now publishes the provider's resolved palace to MEMPALACE_PALACE_PATH — mcp_server's own override mechanism (its --palace flag sets exactly this variable, and its config re-reads it on every access). All drawer CRUD / duplicate-check / tunnel / taxonomy passthroughs now resolve the provider's palace. Ownership of the env write is tracked, so a stale bridge from a previous session never outranks freshly edited config, and a genuinely user-set env var is never claimed or cleared.
• The KG passthroughs (kg_invalidate, kg_timeline, kg_stats) could not be fixed by the bridge — mcp_server resolves its KG from DEFAULT_KG_PATH unless its own CLI flag was given — so they're now native handlers hitting the same <palace>/../knowledge_graph.sqlite3 as kg_query/kg_add, with the same input validation as their mcp_server counterparts.
• While closing this we found the same split one level down: collection_name. The provider wrote the hardcoded default collection while search_memories (and the passthrough) honor ~/.mempalace/config.json — a customized collection name would have made live turns invisible to recall. The provider now reads collection_name (and the unset-palace default) from MempalaceConfig, so the embedded provider follows the same single resolution chain the standalone MCP server does. Still intentionally not configurable on the Hermes side — a second knob would let the write and read sides diverge again.

3. on_memory_write target filter — fixed in 9edcec2.

Confirmed against the Hermes source: memory_tool defaults to target="memory", so the target == "user" filter was dropping the majority of writes. Both targets now mirror into the knowledge graph under distinct subjects — user → asserted → <fact> for user facts, hermes → noted → <fact> for the agent's own notes — so kg_query("user") never surfaces environment quirks. (replace/remove actions still don't mirror; mapping them onto kg_invalidate requires content matching we'd rather design deliberately in the follow-up than guess at here.)

4. backup_paths() — no such hook exists to implement; documented the boundary instead.

We searched the Hermes tree: MemoryProvider has no backup_paths() (or equivalent), and hermes backup walks only $HERMES_HOME — there's currently no way for a provider to contribute external paths. Substantively, we'd also argue the palace shouldn't ride along in a Hermes backup: ~/.mempalace/ is the user's central memory shared across agents (OpenClaw, Claude Code, etc.), not per-agent Hermes state. The module docstring now documents this boundary and post_setup explicitly tells users hermes backup does not cover ~/.mempalace/. If a backup_paths()-style hook lands upstream, we'll implement it.

All 58 provider tests pass (3,273 across the suite), lint clean, CI green.

🤖 Generated with Claude Code

[GoXLd]

Thanks for the detailed writeup, @raman325 - the direction you landed on is cleaner than what I had in raman325#2: making sync_turn the sole filing path (rather than de-duping across two paths) sidesteps the whole fragile correlation problem, and the env-bridge + collection_name unification for point 2 closes a gap I hadn't even caught in #2.

Happy to help with the sync_turn/on_session_end correlation follow-up once it's ready for review —-the content-fingerprint approach you outlined sounds like the right way to avoid the exact-text-match trap.

[vavush]

Hey @igorls — just checking in on this one. All four review blockers were addressed back on July 6 (duplicate filing, passthrough tools bypassing palace_path, sync_turn as sole filing path, KG mirroring). The PR is mergeable and has been sitting for two weeks. Is there anything else needed before it can land? Happy to rebase or adjust if something changed on develop in the meantime.

[alistairwalsh]

Thanks for pushing this stack forward. I maintain a separately developed native Hermes/MemPalace provider that is running in production on Hermes 0.20.0 and MemPalace 3.6.0 against authenticated Qdrant, with more than 25,000 drawers.

I reviewed #1915, #1941, and #1942. I do not intend to open a competing Hermes provider; this series is clearly the right upstream integration point.

Our independently tested line may be useful for focused follow-ups in two areas:

1. Backend-neutral / Qdrant operation

   • profile-scoped Qdrant namespaces;
   • an explicit backend marker and fail-closed startup rather than silent Chroma fallback;
   • authenticated health, collection-identity, and semantic-query checks;
   • production verification that multiple Hermes execution contexts do not cross-write profiles.

2. Crash and update durability

   • durable turn spooling before asynchronous filing;
   • replay/recovery of uncommitted spool entries;
   • atomic, fsynced transcript archival;
   • execution-context guards for cron/flush/system turns;
   • a compatibility gate that checks the Hermes MemoryProvider contract, MemPalace dependency line, resolved backend, namespace identity, non-shrinking drawer count, semantic retrieval, and a fresh-process Hermes tool call.

The current upstream stack's use of ChromaBackend is internally consistent and well tested. If Qdrant/backend-neutral operation is wanted, I can adapt the relevant pieces to this architecture rather than importing our deployment-specific provider wholesale. I would keep profile names, local paths, watchdog language, and operational history out of the patch, and preserve the existing authorship and design.

@raman325 @igorls, which sequencing would you prefer?

• focused follow-up PR after this stack lands; or
• patches based on the top of feat(hermes): backfill, install command, and docs #1942 once its base conflict is resolved?

I can also start with a compact backend contract test so storage abstraction expectations are agreed before implementation.

[raman325]

I'd prefer to land my stack and to queue up any additional changes for after as it would reduce merge conflict churn, but I will leave it to your and Igor's discretion!

[igorls]

Wave 2 for 3.7.0: LGTM after review. Merging into develop for the release train.