Use Palimem with Hermes

The Palimem Hermes adapter (ai-memory) implements the Hermes MemoryProvider contract. It backs Hermes agents with the same governed SQLite store used by the MCP integration — same write-ahead log, same supersession semantics, same audit export.

Registration name: ai-memory
Config key: memory.provider: ai-memory
Recall modes: hybrid, context, tools
Backing store: in-process MemoryService — same SQLite store as MCP

Prerequisites

Hermes agent framework installed
Python 3.13+
Repository cloned: git clone https://github.com/palimem/palimem

Recommended install

Install the adapter package into your Python environment:

python3 -m pip install -e adapters/hermes

mkdir -p ~/.hermes/plugins/memory/ai-memory
cat > ~/.hermes/plugins/memory/ai-memory/__init__.py <<'PY'
from ai_memory_hermes import register
PY

This creates the Hermes plugin discovery shim. Hermes discovers memory providers from ~/.hermes/plugins/memory/<provider>/.

Config block

In your Hermes config.yaml:

memory:
  provider: ai-memory

Native provider config at ~/.hermes/plugins/memory/ai-memory/config.json (written by hermes memory setup):

{
  "data_dir": ".ai-memory/data",
  "namespace": "my-project",
  "recall_mode": "hybrid",
  "mirror_builtin_memory": false,
  "prefetch_limit": 5,
  "sync_turn_enabled": true
}

Sample config: adapters/hermes/ai-memory.config.sample.json

Hermes memory setup

Run the interactive setup wizard:

hermes memory setup

Accepted config keys:

Key	Default	Notes
`data_dir`	`<workspace>/.ai-memory/data`	Overridden by `MEMORY_SERVICE_DATA_DIR`
`namespace`	workspace basename	Repository namespace prefix
`recall_mode`	`hybrid`	`hybrid`, `context`, or `tools`
`mirror_builtin_memory`	`false`	Import `USER.md` on start and mirror built-in memory writes
`prefetch_limit`	`5`	Total prefetched results per turn
`sync_turn_enabled`	`true`	Queue completed turns as `episode` records
`profile_engine_enabled`	`false`	Opt-in background profile extraction

Verification

Run the provider smoke test (simulates hermes memory setup):

bash examples/claude-code/demo/phase3-smoke.sh

Validation-bridge smoke:

python3 adapters/hermes/smoke-hermes-bridge.py

Programmatic test without a full Hermes runtime:

from pathlib import Path
import tempfile
from ai_memory_hermes import AiMemoryProvider

workspace = Path(tempfile.mkdtemp(prefix="ai-memory-hermes-"))
hermes_home = workspace / ".hermes-home"
provider = AiMemoryProvider()
provider.initialize("session-1", hermes_home=str(hermes_home), workspace_root=str(workspace))
print(provider.system_prompt_block())
provider.shutdown()

Agent prompt

Paste this into your Hermes agent session to configure Palimem:

Set up Palimem as the Hermes memory provider for this session.

- Package: install -e adapters/hermes
- Config: memory.provider: ai-memory in config.yaml
- Data directory: .ai-memory/data (or MEMORY_SERVICE_DATA_DIR)
- Recall mode: hybrid
- Verify: system_prompt_block() returns without error; prefetch() returns governed results

Do not enable cloud services.

Adapter behavior

Method	Behavior
`initialize(session_id, **kwargs)`	Opens local governed store; caches workspace/session identity
`system_prompt_block()`	Emits short usage hint + bounded user-profile shelf
`prefetch()`	Searches `user` and `session` scopes; formats bounded context block
`sync_turn()`	Persists completed turns as `episode` records on a background daemon thread
`get_tool_schemas()`	Exposes tool-mode access to the same Section 10 MCP envelopes
`handle_tool_call()`	Routes tool calls to governed memory operations
`on_session_end()`	Optional: logs `memory_consolidate` dry-run stats
`on_pre_compress()`	Writes repository compaction-checkpoint facts

Troubleshooting

Provider not found by Hermes

Check that the discovery shim exists: cat ~/.hermes/plugins/memory/ai-memory/__init__.py. It should contain from ai_memory_hermes import register.

ModuleNotFoundError: ai_memory_hermes

Install the adapter: python3 -m pip install -e adapters/hermes.

Prefetch returns empty results

No memory has been stored yet. Store a fact via handle_tool_call("memory_remember", {...}) or seed from Markdown files.

Next steps

Palimpsest model — how supersession and layered memory work
Scopes — user, session, and repository memory
MCP tools reference — all 11 tools with arguments
Export & import — audit export and Markdown import