Mnemosyne for Hermes Agent

Local-first memory provider for Hermes Agent. 23 tools. Zero cloud. Zero latency.

Mnemosyne gives Hermes Agent a local-first memory layer that captures conversation, tool calls, execution paths, decisions, outcomes, and corrections. Then surfaces it all with intent-aware hybrid recall. SQLite on your machine. No cloud. No API keys. No latency.

The Problem

Agent workflows lose context across sessions. A few ways this bites:

• Prior decisions and constraints vanish between sessions
• Tool-call context isn't preserved in raw transcripts
• Failures get repeated because nobody remembered the fix
• Project context gets buried in long chat history
• Cross-session memory becomes noise without structure
• Conversation-only memory misses the execution path: what the agent did, not just what was said

What Mnemosyne Changes

Mnemosyne adds structured, local-first, agent-native memory to Hermes through the mnemosyne memory provider.

It gives Hermes:

• Automatic capture: every turn, in the background, after the response is sent. Conversation, decisions, tool calls, outcomes.
• Hybrid search: vector similarity + FTS5 full-text + importance scoring. All tunable per-query. Bias toward recency, relevance, or both.
• Episodic consolidation: mnemosyne_sleep compresses old working memories into long-term summaries so the working set stays small and recall stays sharp.
• Knowledge graph: subject-predicate-object triples with BFS graph traversal. Link memories semantically.
• Multi-agent validation: agents can attest, update, or invalidate each other's memories with provenance tracking.
• Shared surface: compact cross-agent metadata for multi-agent workflows.
• Zero cloud: SQLite on your machine. No network calls. No API keys. No quota limits.

When using Mnemosyne, disable Hermes' built-in MEMORY.md/USER.md system to avoid duplication. Do NOT use hermes tools disable memory — that also kills all 23 Mnemosyne-registered tools (the memory toolset gates both built-in AND provider injection at agent_init.py:1163-1172).

Edit ~/.hermes/config.yaml:

memory:
  memory_enabled: false
user_profile_enabled: false

Mnemosyne handles everything: capture, recall, consolidation, knowledge graph, multi-agent validation. The built-in MEMORY.md/USER.md system is redundant and just burns tokens. One provider. One memory layer.

How It Works

Mnemosyne runs on three stages:

1. Capture

After Hermes completes a turn, the Mnemosyne provider stores the full interaction (user message, assistant response, tool calls, and available execution context) in a local SQLite database with vector embeddings.

Each memory gets tagged with importance (0.0-1.0), scope (session or global), veracity (stated, inferred, tool, or imported), and optional metadata. Memories can carry expiration dates and named entities for fuzzy recall.

This is how Hermes builds memory from what it says and what it does.

2. Recall

Recall is intentional. Agents decide when to recall, what scope, and how many results. There is no automatic retrieval dumping context into every prompt.

When mnemosyne_recall fires, Mnemosyne runs hybrid search: vector similarity finds semantic matches, FTS5 full-text finds keyword matches, and importance scoring boosts what matters. All three weights are tunable per-query so you can bias toward recency, relevance, or both.

Returned context can include prior decisions, constraints, failure modes, project patterns, and execution outcomes: without stuffing irrelevant history into the prompt.

3. Consolidate

mnemosyne_sleep compresses old working memories into episodic summaries. Think of it as a nightly cleanup that knows what to keep and what to summarize. The working set stays small. Recall stays sharp. Long-running agents don't drown in their own history.

Session lifecycle

The provider follows Hermes session changes without requiring a provider restart. After /new, /resume, /branch, undo, or context compression, the active BeamMemory session is rebound before the next memory operation, keeping writes and tool calls attributed to the current conversation.

Non-empty session IDs supplied to per-turn prefetch and sync calls scope that individual operation; empty values preserve the active session. A configured gateway_session_key remains the stable scope across both paths and across session changes, so a branch or compression switch does not adopt the child session ID.

Provider lifecycle hooks are fail-soft. Database or disk failures during prefetch, turn sync, session-end or automatic consolidation, and wrapper or audit cleanup are logged and suppressed so Hermes can continue without a lifecycle exception surfacing to the user.

Quickstart

Prerequisites: Hermes Agent (pipx install), Python 3.10+, no API keys needed.

Install

pipx install mnemosyne-hermes
hermes config set memory.provider mnemosyne
hermes memory status

To install only at the selected Hermes home without linking opted-in child profiles, use:

mnemosyne-hermes install --no-profile-links

The default continues to link opted-in child profiles for backward compatibility.

That's it. The entry point in mnemosyne-hermes registers with Hermes' memory provider discovery system (hermes_agent.memory_providers). No symlinks. No directory copying. No plugin.yaml gymnastics. The provider surfaces automatically on the next Hermes start.

Verify:

hermes memory status
# Should show:
#   Provider:  mnemosyne
#   Plugin:    installed ✓

Selecting Hermes' interpreter

mnemosyne-hermes install finds Hermes' Python by following the hermes launcher on PATH, through symlinks and through the exec handoff of a shell-wrapper launcher, and accepts the interpreter sitting beside it only when that directory is a real virtual environment. It then checks the known install roots ($HERMES_HOME/hermes-agent, ~/hermes-agent, /opt/hermes/hermes-agent, /usr/local/lib/hermes-agent, /usr/lib/hermes-agent), which are held to the same bar.

Wrapper resolution is deliberately bounded: it reads a limited prefix of the launcher, follows a limited number of hops, and understands a fixed set of forms (exec /path/to/hermes, a relative or bare target, and env/VAR=val prefixes). Anything outside that, such as exec env -u VAR ... or a launcher that starts Hermes without exec, is not followed, and discovery moves on to the install roots rather than guessing. Layouts that end there need --python.

On the default path, if none of those yields a virtual environment the install stops rather than guessing. An interpreter that merely sits next to the launcher is usually a Homebrew or system Python, and installing mnemosyne-hermes[all] into it leaves Hermes' own environment untouched while reporting success. A Hermes installed outside a virtual environment therefore needs --python.

--no-bootstrap is the deliberate exception. It already means "do not install anything into Hermes' venv", so there is no wrong-interpreter install left to prevent. When discovery finds nothing there, the installer says so, skips dependency validation, and continues. The plugin is linked, but nothing has confirmed that Hermes can import it, so a --no-bootstrap install is not a validated one. Verify it separately:

hermes memory status

Pass --python to skip discovery entirely when your layout is unusual or the wrong interpreter is being picked:

mnemosyne-hermes install --python /path/to/hermes/venv/bin/python
mnemosyne-hermes install --dry-run          # shows which interpreter would be used

--python is authoritative in both install modes: it overrides discovery for a symlink install, and selects the site-packages a --mode wrapper install imports from.

Wrapper validation timeout

For a wrapper install, --import-timeout SECONDS sets the timeout for both selected---python validation probes. It defaults to 60 seconds. Use it when that selected interpreter needs longer to resolve its site-packages or import mnemosyne_hermes. SECONDS must be positive and finite: zero, negative, NaN, and infinite values are rejected.

mnemosyne-hermes install --mode wrapper --python /path/to/hermes/venv/bin/python --import-timeout 90
mnemosyne-hermes install --mode wrapper --python /path/to/hermes/venv/bin/python --no-bootstrap --import-timeout 90

The second form still validates the selected wrapper interpreter; --no-bootstrap only skips automatic package installation. mnemosyne-hermes status intentionally uses its fixed 60-second validation policy, independent of an install-time override.

The installer also deploys the bundled mnemosyne-memory-override skill to $HERMES_HOME/skills/memory/mnemosyne-memory-override/SKILL.md. The skill is a behavioral guardrail that nudges agents away from the legacy memory tool for durable facts. Existing user-edited copies are skipped by default; install --force overwrites the skill only after writing SKILL.md.bak next to it.

How it works

When you install via pipx, the package registers two entry points:

• hermes_agent.memory_providers - discovered by Hermes' discover_memory_providers() so hermes memory status sees it as an installed plugin
• hermes_agent.plugins - discovered by Hermes' PluginManager for tool and CLI registration

Hermes checks pipx-installed packages alongside directory-based plugins. No extra setup steps needed.

Development install

git clone https://github.com/AxDSan/mnemosyne.git
cd mnemosyne
pip install -e .
pipx install -e integrations/hermes   # replaces hook with editable path

Configuration

No required config. Everything defaults to ~/.mnemosyne/. Optional overrides:

Or in ~/.hermes/config.yaml:

memory:
  provider: mnemosyne
  mnemosyne:
    auto_sleep: true
    sleep_threshold: 30

Tools

23 tools. All surfaced through Hermes' tool system.

Core memory: remember, recall, sleep, stats, get, update, forget, invalidate, validate

Knowledge graph: triple_add, triple_query, graph_query, graph_link

Multi-agent: shared_remember, shared_recall, shared_forget, shared_stats

Working notes: scratchpad_write, scratchpad_read, scratchpad_clear

Ops: export, import, diagnose

Test the Memory Loop

Ask Hermes to do a multi-step task:

"Investigate why the payment sync test is failing and fix it."

Hermes inspects files, runs commands, identifies a failing fixture, makes a decision, applies a fix, and observes the result.

After the turn, Mnemosyne stores the full execution path: the failure, the decision, the fix, the outcome, and the pattern.

In a new session:

"A similar payment sync test is failing again. Check prior fixes before changing anything."

Hermes calls mnemosyne_recall, finds the relevant prior failure and fix, and doesn't repeat the mistake.

Fail-Soft By Design

If Mnemosyne's database is unavailable or disk is full, the provider logs the error and Hermes continues answering. Memory is additive: it never blocks the user.

Memory issues are logged but never surface as user-facing errors.

Contributing

We welcome contributions. See the Contributing Guidelines for code style, standards, and submitting pull requests.

To build from source:

git clone https://github.com/AxDSan/mnemosyne.git
cd mnemosyne

pip install -e .
pip install -e integrations/hermes

Support

• Documentation
• Discord
• Issues

License

MIT

Optional self-echo suppression

Self-echo suppression is off by default. To opt in, set MNEMOSYNE_SELF_ECHO_ENABLED=1 in the environment of the process running Hermes, then start a new provider instance (normally by restarting that process). Unset it or set it to 0 to disable the feature. This option applies to both Hermes provider packages; it does not change explicit memory-tool recall.

The integration uses Hermes' existing on_pre_compress(messages, **kwargs) callback automatically; users should not call it manually. Merely enabling the flag is not sufficient: until the provider has actually observed the callback, automatic recall remains ordinary recall. Hosts without the callback, or cores without the optional ledger capability, continue ordinary capture and recall.

Every callback releases all previous exclusions, even if compression keeps some text, does nothing, or fails. Newly captured, unchanged provider-owned rows can be suppressed only when the sync transcript proves they follow the observed boundary. Missing or ambiguous transcript evidence means ordinary recall, not dropped memories. Imported/legacy rows are not retroactively marked or rewritten. Python 3.10 is supported with a conservative SQLite parameter budget; exceeding that budget or losing proof also means ordinary recall.

This is best-effort duplicate reduction, not exact live-context tracking or a durable v2 checkpoint guarantee. A provider restart discards suppression state. An already-returned per-turn prefetch string cannot be rewritten by the plugin; released memories become available on the next user-turn prefetch. No Hermes host modification or database migration is required.