Hermes Agent Memory
MemorySync as a native memory provider for Hermes Agent, Nous Research’s self-improving AI agent: select it once and every session gets persistent profiles, background turn synchronization, and zero-latency prefetched recall — with the only zero-dependency provider in the ecosystem.
What the provider does
| Pillar | How it works |
|---|---|
| Persistent profiles | A static system-prompt block announces the active identity; the memorysync-profile tool returns the durable cross-session profile; memory is scoped per Hermes identity (hermes::<identity>) while your memories stay shared with every other MemorySync surface. |
| Background synchronization | Every completed turn queues onto a bounded daemon worker and persists verbatim with cross-adapter content-hash seeds — replays converge on one stored row and the conversation thread is never blocked. Built-in MEMORY.md/USER.md writes are mirrored too. |
| Prefetched context | Recall for the NEXT turn runs in the background between turns; the next turn injects the cached result with zero added latency. Hermes shows its deterministic “🧠 recalled N memories” indicator from the provider’s recall status. |
| Safety rails | Cron, subagent and flush contexts are fully passive (background prompts must never corrupt a profile); session switches (/resume, /branch, /reset, compression) rescope correctly; a circuit breaker stops repeat pain; no lifecycle path can raise into Hermes. |
| Mem0 | Supermemory | Zep | MemorySync | |
|---|---|---|---|---|
| Hermes provider exists | ✓ bundled | ✓ bundled | ✗ nothing | ✓ installer today, upstream PR pending |
| pip dependencies | mem0ai SDK | supermemory SDK | — | ✓ ZERO — pure standard library, can never disturb the runtime |
| Verbatim history + extraction | ✗ extraction only | △ one ingest per session | — | ✓ verbatim turns with converging seeds; the platform distils server-side |
| Non-primary context gating | partial | partial | — | ✓ cron/subagent/flush fully passive, tested |
| Monthly-quota behaviour | untested | untested | — | ✓ both server modes tested — silence, never errors |
| Secret refusal in tools | ✗ | ✗ | — | ✓ credential-looking text refused client-side |
Install
# 0. Get an API key at https://app.memorysync.io# 1. Copy the provider into your Hermes profile:npx -y memorysync-hermes install# 2. Select and configure it (paste the key when asked):hermes memory setup # choose "memorysync"# 3. Confirm:hermes memory status # "memorysync" active
The wizard writes the key to ~/.hermes/.env (MEMORYSYNC_API_KEY) and non-secret settings to ~/.hermes/memorysync.json — the provider never stores secrets in the config file. Manual setup: hermes config set memory.provider memorysync plus the env var. Only one memory provider is active at a time; selecting MemorySync replaces the built-in memory-core backend.
What runs when
| Moment | What happens |
|---|---|
| System prompt assembly | A short static block: active identity, scope, and how to use the tools. |
| Between turns | Background recall for the next turn (queue_prefetch) — the API call completes while you type. |
| Before each turn | The cached recall injects with zero added latency (hard 2.5s cap if the background call is still in flight — then the turn proceeds memoryless, never blocked). |
| After each turn | The verbatim exchange queues onto the ingest worker and persists with fnv1a64 idempotency seeds. |
| Built-in memory writes | MEMORY.md / USER.md entries mirror to MemorySync so nothing lives in only one place. |
| Subagent completes | The parent records the delegated task and its result. |
| Cron / subagent / flush contexts | Fully passive — no reads, no writes. |
| Any failure — no key, network down, monthly quota exhausted | Silent skip; breaker pauses after repeated failures. Nothing ever raises into Hermes. |
# Same operation as sync_turn performs, shown as the raw MemorySync REST call(s).## Turns store under the hermes::<identity> transcript scope — one per# Hermes identity, same shared memories everywhere.curl --request POST https://api.memorysync.io/v1/memory/add_turn \--header "X-API-Key: $MEMORYSYNC_API_KEY" \--header "Content-Type: application/json" \--data '{"tenant_id":"acme","user_id":"rafay","source":"hermes","text":"human: switch the dashboard to teal","speaker":"human@hermes::default#h<content-hash>","metadata":{"session_id":"hermes::default"}}'
Tools
| Tool | What it does |
|---|---|
memorysync-search | Semantic search over long-term memory. |
memorysync-save | Store one durable fact — refuses credential-looking text client-side. |
memorysync-profile | The persistent cross-session profile: durable preferences, decisions, context. |
memorysync-forget | Delete one memory by id. There is deliberately no delete-all. |
Kebab-case names with snake_case aliases (memorysync_search, …) — the Hermes convention. Set memory_mode to context (injection only) or tools (tools only) in memorysync.json; hybrid runs both. Failures answer with friendly JSON, never tracebacks.
Supported versions
| Surface | Requires | Verified on |
|---|---|---|
memorysync-hermes 1.0.0 | Hermes Agent (Python 3.11 runtime), Node.js 18+ for the installer | 20/20 pytest contract tests driving the upstream MemoryProvider lifecycle against a real threaded mock — prefetch budgets, non-blocking sync, passive contexts, session switching, wizard schema, both quota modes, breaker |
CI re-runs the full suite on every push. An upstream pull request to bundle the provider in NousResearch/hermes-agent (the way Mem0 and Supermemory ship) is pending — installer users get it today either way.