feat(integrations): MemMesh memory provider for Hermes Agent

[rrader26]

Makes MemMesh a drop-in memory backend for Hermes Agent. Ships as a pip entry point (hermes_agent.memory_providers) — their bundled plugins/memory/ is closed to new providers, and an entry point still gets the dashboard config panel and hermes memmesh subcommands.

Their built-in memory is two char-capped files (MEMORY.md 2,200 chars, USER.md 1,375) frozen into the system prompt at session start, with no auto-compaction. That constraint is the whole reason the provider socket exists, and local mode makes replacing it free — no key, no account, no network.

pip install memmesh-hermes && hermes config set memory.provider memmesh

9 tests passing, no network or Hermes checkout required.

---

The two findings that shaped the design

Local mode speaks MCP, not REST

The obvious design is one HTTP client and a configurable base URL — both deployments expose /observe, both expose /search. That's a trap, and it's worth being precise about where it springs.

Our OSS binary serves two different search paths:

Route	Implementation	What it actually does
POST /search	storage.query()	MemoryFilter — scope, ids, status, text_match LIKE. Storage order.
POST /mcp -> memory_search	memory_storage::search()	semantic + lexical + recency hybrid

/search is a filter endpoint that happens to accept text. A plugin pointed at it would work, return plausible-looking rows, and quietly deliver substring matching where the user expected semantic recall. Nothing errors, nothing logs. So local mode talks to memmesh serve-mcp over JSON-RPC, and the two deployments get real adapters rather than one client written to the lowest common denominator of both.

(Worth considering separately: whether REST /search should route through the hybrid searcher too. It's a surprising asymmetry for anyone integrating against the REST surface, and I'd expect us to trip over it again.)

Only cloud mode declares the compaction checkpoint

Hermes offers an opt-in contract: pre_compress_checkpoint_api_version = 2 promises that every successful on_pre_compress() means the transcript is durably committed, and an operator who sets compression.checkpoint_required: true gets fail-closed compaction on the strength of it.

It's declared per instance, not on the class. The OSS binary has no durable transcript archive, so local mode doesn't make the claim. Advertising a guarantee the backend can't honour is worse than not offering it — the operator would have configured compaction to depend on it.

That's also the one path in the plugin that fails closed. Everything else fails soft: recall returns empty, writes drop from a full queue rather than blocking a turn, a dying background writer can't take the session with it — a lost observation costs one memory, a blocked turn costs the conversation. The checkpoint raises instead, so compaction is blocked and the uncompressed transcript survives. Compaction is irreversible; a provider whose job is holding the evidence must not let it be destroyed best-effort.

Checkpoints are keyed by SHA-256 of the transcript, salted with the bank id. After a fail-closed block Hermes re-calls with a transcript that's grown only slightly, so attempts carry overlapping evidence — the content digest is what makes a retry a no-op instead of a duplicate archive.

Hooks

Hook	Behaviour
prefetch	recall injected pre-turn, gated by Hermes' own is_trivial_prompt
sync_turn	turn queued to observe on a background thread
on_pre_compress	cloud only — durable archive before compaction, fail-closed
on_delegation	subagent (task -> result) recorded as a reasoning trace
on_memory_write	mirrors Hermes' own MEMORY.md / USER.md writes into MemMesh
recall_status	deterministic "MemMesh — recalled N memories" indicator
backup_paths	declares the local DB — hermes backup only walks HERMES_HOME, and in local mode that DB is the memory
tools	memmesh_search, memmesh_observe

Smaller deliberate choices

• The trivial-prompt predicate is imported from Hermes, not reimplemented. Two copies of that regex would drift, and the drift is invisible: recall silently stops happening for some word nobody thought to test. It gates automatic recall only — an explicit memmesh_search for "ok" still runs.
• on_delegation omits verified rather than sending false. Their API treats false as "checked and found wrong" and keeps it as a counterexample. A subagent returning a result isn't evidence it was correct, and false would mislabel every delegation as a known failure — removing it from procedure induction entirely, which is the opposite of the point.
• Bank ids collapse empty placeholders, so hermes-{user} with no user is hermes, not hermes-. A dangling separator is a different bank, and the symptom is an agent that appears to have lost its memory rather than an error anyone can see. Tested.
• The managed daemon binds loopback only and is token-gated even there, because every other process on the machine can reach loopback. Refcounted and left running after the last release so /reset doesn't pay a cold start; atexit reclaims it.

Tests

Scoped to the logic that fails quietly: bank-id scoping, MCP result parsing (junk must degrade to empty recall, never an exception), and digest stability including field-boundary confusion. requests and the Hermes runtime are both stubbed.

Not verified here

Not yet run against a live Hermes install — the hooks are written against their MemoryProvider ABC and their published contracts, but end-to-end wiring (daemon spawn under a real agent, the checkpoint under compression.checkpoint_required) needs a Hermes checkout to exercise. Cloud mode's routes target the hosted API's current shape; skipTrivialQueries and the trust-scoring work it pairs with are in flight in memory-thinkfleet #393/#394.