feat: MemPalace memory provider (96.6% LongMemEval, local, free)

[ZK-Snarky]

Adds MemPalace as a built-in Hermes memory provider.

MemPalace is the highest-scoring AI memory system ever benchmarked — 100% LongMemEval R@5 with Haiku rerank, 96.6% raw, no API key, no cloud, fully local.

Usage

# ~/.hermes/config.yaml
memory:
  provider: mempalace

pip install mempalace
mempalace init ~/your-project  # sets up wings + identity
hermes gateway start

Or use the one-command installer from the MemPalace side: mempalace hermes install

How it works

Hook	What happens
initialize()	Loads wing config + identity from ~/.mempalace/, starts background worker, warms ChromaDB
system_prompt_block()	Injects AAAK L0+L1 wake-up (~170 tokens) at every session start
prefetch()	Semantic search before each turn, wing-narrowed when context matches
sync_turn()	Files every exchange to the palace non-blocking — available in the next session immediately
on_session_end()	Full session mining + L1 AAAK layer regeneration
on_pre_compress()	Extracts key exchanges before context window compression
on_memory_write()	Mirrors explicit mcp_memory writes into the palace

8 tools exposed: mempalace_search, mempalace_status, mempalace_list_wings, mempalace_list_rooms, mempalace_kg_query, mempalace_kg_add, mempalace_diary_write, mempalace_diary_read

Implementation notes

Zero hardcoded config. Wings and identity load from ~/.mempalace/wing_config.json and ~/.mempalace/identity.txt if they exist. Ships with empty defaults. Run mempalace init to configure.

Non-blocking by design. All palace I/O runs in a background worker thread (bounded queue, maxsize=500). The agent loop never waits on storage.

Circuit breaker. After 5 consecutive failures the plugin backs off for 120s and logs a warning. Degraded gracefully — the agent keeps running, just without palace context.

Storage safety. ChromaDB client created once in initialize() via get_or_create_collection(). Dedup uses SHA-256 over full content (not a prefix hash). Collection errors disable palace writes without crashing the agent.

Hermes-home scoped. Palace path, diary, and KG respect hermes_home from initialize() kwargs, with get_hermes_home() fallback. Multiple profiles stay isolated.

Review process

This PR went through four rounds of review before submission:

1. Initial build against agent/memory_provider.py ABC and all 7 existing providers
2. Convention audit — verified against every plugin.yaml, config pattern, registration pattern, tool naming convention, and hook declaration across the full plugin set
3. Threading and exception hardening — queue bounds, logging levels, None guards, shutdown drain warning
4. Dual adversarial audit (two independent agents) — caught: unguarded ChromaDB init, MD5 prefix dedup causing silent data loss, on_memory_write missing from plugin.yaml, sys.path.insert inserting HOME into path, wake_up() None crash, wrong log levels in worker, tuple unpack outside try/finally, magic numbers

All findings fixed before submission. Smoke-tested end-to-end: import, init, sync_turn, prefetch, tool dispatch, shutdown.

Dependencies: mempalace>=3.0.0, chromadb>=0.4.0 (declared in plugin.yaml)

Companion PR adding the integration to the MemPalace repo: MemPalace/mempalace#3

[BadTechBandit]

this would be a really amazing addition for hermes memory! any timeline on
review?

[nextwa]

I would like to use this

[Motokiyo]

Bug report: embedding dimension mismatch on existing MemPalace collections

Hi @ZK-Snarky, thanks for this PR — I cherry-picked it locally to integrate Hermes with my existing MemPalace install and hit a blocker worth reporting. TL;DR: the plugin opens the Chroma collection without specifying an embedding_function, so it falls back to all-MiniLM-L6-v2 (384-dim) and breaks any pre-existing collection created by the upstream MemPalace CLI/MCP server (which uses OllamaEmbeddingFunction(model="bge-m3"), 1024-dim).

Symptom (every conversational turn):

WARNING plugins.memory.mempalace: MemPalace sync_turn failed:
Collection expecting embedding with dimension of 1024, got 384

Result: _do_sync_turn silently fails, no drawer is filed automatically. Explicit mempalace_kg_add and mempalace_diary_write tool calls still work because they go through the upstream MemPalace package (which loads its own EF), so the bug is invisible until you tail the logs and notice that automatic turn persistence is dead.

Root cause — plugins/memory/mempalace/__init__.py lines 503-507:

self._chroma_client = chromadb.PersistentClient(path=str(self._palace_path))
self._chroma_collection = self._chroma_client.get_or_create_collection(
    "mempalace_drawers"   # no embedding_function → Chroma default = MiniLM 384
)

Compare with the upstream MemPalace package (mempalace/mcp_server.py, miner.py, searcher.py):

from mempalace.ollama_embedding import OllamaEmbeddingFunction
ef = OllamaEmbeddingFunction(model="bge-m3")
col = client.get_or_create_collection("mempalace_drawers", embedding_function=ef)

Fix — 3-line patch:

from mempalace.ollama_embedding import OllamaEmbeddingFunction
ef = OllamaEmbeddingFunction(model="bge-m3")
self._chroma_client = chromadb.PersistentClient(path=str(self._palace_path))
self._chroma_collection = self._chroma_client.get_or_create_collection(
    "mempalace_drawers",
    embedding_function=ef,
)

Tested locally (Hermes gateway + MemPalace 1024-dim collection, ~68k drawers). After patch + gateway restart, a Telegram turn produced the expected log:

INFO plugins.memory.mempalace: MemPalace: filed drawer wing_general/test-post-fix/hall_events (drawer_wing_general_test-post-fix_ffbeed9fef0bb6d4b38c4004)

Sync now works as designed. Same bug exists in #12203 and #9761.

Open design question — should the plugin fall back gracefully if mempalace.ollama_embedding import fails (e.g. user runs Hermes without the upstream MemPalace package installed, or without Ollama running)? The current ChromaDB init is already wrapped in try/except that disables palace writes — adding a try-import for the EF and logging "MemPalace EF unavailable, palace writes disabled" would keep the same shape. Happy to open a follow-up PR if you'd like.

[alt-glitch]

Likely duplicate of #12203 — same MemPalace memory provider plugin, more recent PR with triage notes referencing this one.

[alt-glitch]

Likely duplicate of #12203

[Motokiyo]

Thanks for the triage @alt-glitch — you're right, I'll repost this on #12203 since it's the canonical one with active triage. Leaving this thread alone after this. Apologies for the noise.

[Bartok9]

Salvage PR at #21017 — rebased the MemPalace provider implementation onto current main.

[ZK-Snarky]

Closing in favor of #21017 — thanks @Bartok9 for the rebase. Happy for that to be the canonical version.

[Bartok9]

Thanks @ZK-Snarky — appreciate you pointing people to #21017 and the kind words. The core implementation is yours; I just rebased it and picked up the review feedback. Hope to see it land soon.