Mnemon

English | 中文

LLM-supervised persistent memory for AI agents.

LLM agents forget everything between sessions. Context compaction drops critical decisions, cross-session knowledge vanishes, and long conversations push early information out of the window.

Mnemon gives your agent persistent, cross-session memory — a four-graph knowledge store with intent-aware recall, importance decay, and automatic deduplication. Single binary, zero API keys, one setup command.

Experimental beta: this repository also includes mnemon-harness, a source-built beta for project-local host-agent lifecycle state. It is separate from the stable mnemon CLI, not production-ready, and may make breaking changes at any time. See harness/README.md.

Claude Max / Pro subscriber? Mnemon works entirely through your existing subscription — no separate API key required. Your LLM subscription is the intelligence layer. Two commands and you're done.

Why Mnemon?

Most memory tools embed their own LLM inside the pipeline. Mnemon takes a different approach: your host LLM is the supervisor. The binary handles deterministic computation (storage, graph indexing, search, decay); the LLM makes judgment calls (what to remember, how to link, when to forget). No middleman, no extra inference cost.

Mnemon also addresses a gap in the protocol stack. MCP standardizes how LLMs discover and invoke tools. ODBC/JDBC standardizes how applications access databases. But how LLMs interact with databases using memory semantics — this layer has no protocol. Mnemon's three primitives — remember, link, recall — form an intent-native protocol: command names map to the LLM's cognitive vocabulary (remember not INSERT, recall not SELECT), and output is structured JSON with signal transparency rather than raw database rows.

Memory has a compound interest effect — the longer it accumulates, the greater its value. LLM engines iterate constantly, skill files cost nearly nothing to write, but memory is a private asset that grows with the user. It is the only component in the agent ecosystem worth deep investment.

See Design & Architecture for details.

Quick Start

Install

Homebrew (macOS / Linux):

brew install mnemon-dev/tap/mnemon

Go install:

go install github.com/mnemon-dev/mnemon@latest

From source:

git clone https://github.com/mnemon-dev/mnemon.git && cd mnemon
make install

Verify installation:

mnemon --version

Claude Code

mnemon setup

mnemon setup auto-detects Claude Code, then interactively deploys skill, hooks, and behavioral guide. Start a new session — memory just works.

Codex

mnemon setup --target codex --yes

One command deploys the mnemon skill, prompt files, and Codex lifecycle hooks (SessionStart, UserPromptSubmit, Stop) in .codex/hooks.json.

Cursor

mnemon setup --target cursor --yes

One command deploys the mnemon skill, prompt files, and Cursor lifecycle hooks to .cursor/. The integration primes new agent sessions with Mnemon guidance and memory status, then nudges for durable-memory writeback after responses.

TRAE (TRAE Work)

mnemon setup --target trae --yes

One command deploys the mnemon skill, prompt files, and TRAE native hooks for both TRAE IDE and TRAE Work to .trae/. The integration uses SessionStart, UserPromptSubmit, and Stop hooks in .trae/hooks.json.

Qoder (QoderWork)

mnemon setup --target qoder --yes
mnemon setup --target qoderwork --yes

Qoder deploys the mnemon skill, prompt files, and native hooks to .qoder/ or ~/.qoder/. QoderWork uses its native user config at ~/.qoderwork/. Both integrations register SessionStart, UserPromptSubmit, and Stop hooks in settings.json.

CodeBuddy

mnemon setup --target codebuddy --yes

CodeBuddy deploys the mnemon skill, prompt files, and native hooks to .codebuddy/ or ~/.codebuddy/. The integration registers SessionStart, UserPromptSubmit, and Stop hooks in settings.json.

WorkBuddy

mnemon setup --target workbuddy --yes

WorkBuddy deploys the mnemon skill, prompt files, and native hooks to .workbuddy/ or ~/.workbuddy/. The integration registers SessionStart, UserPromptSubmit, and Stop hooks in settings.json.

Kimi Code

mnemon setup --target kimi --yes

Kimi Code deploys the mnemon skill, prompt files, and native lifecycle hooks to ~/.kimi-code/ or $KIMI_CODE_HOME/. The integration registers SessionStart, UserPromptSubmit, and Stop hooks in config.toml.

OpenCode

mnemon setup --target opencode --yes

OpenCode deploys the mnemon skill to .opencode/skills/, registers the generated guide through opencode.json instructions, and installs a native plugin in .opencode/plugins/. The plugin injects recall context before chat requests and adds Mnemon guidance to session compaction.

OpenClaw

mnemon setup --target openclaw --yes

One command deploys skill, hook, plugin, and behavioral guide to ~/.openclaw/. Restart the OpenClaw gateway to activate.

Pi

mnemon setup --target pi --yes

One command deploys the mnemon skill, prompt files, and a Pi TypeScript extension to .pi/. The extension maps Mnemon's lifecycle reminders onto Pi events (resources_discover, before_agent_start, agent_end, session_before_compact). Start a new Pi session or run /reload to activate.

Hermes Agent

mnemon setup --target hermes --yes

One command deploys the mnemon skill, prompt files, and Hermes shell hooks to ~/.hermes/. The integration uses Hermes' native lifecycle hooks: on_session_start, pre_llm_call, post_llm_call, and optional on_session_finalize. Hermes may prompt once to approve the installed shell hooks.

NanoClaw

NanoClaw runs agents inside Linux containers. Use the /add-mnemon skill to integrate:

1. Install mnemon on the host (see above)
2. In your NanoClaw project, run /add-mnemon — Claude Code will modify the Dockerfile, add a container skill, and set up volume mounts
3. Each WhatsApp group gets its own isolated memory store, with optional global shared memory (read-only)

The skill is available at .claude/skills/add-mnemon/ in the NanoClaw repo.

Nanobot

mnemon setup --target nanobot --global --yes

One command writes a skill file to ~/.nanobot/workspace/skills/mnemon/SKILL.md. Memory is shared across all Nanobot sessions and projects. Use --global (recommended) because Nanobot discovers skills from the global workspace directory.

Uninstall

mnemon setup --eject

How it works

Once set up, memory operates through a lightweight harness: SKILL.md teaches commands, GUIDELINE.md teaches judgment, hooks remind the agent at lifecycle boundaries, and the mnemon binary executes deterministic memory operations. Supported setup commands automate this, but the harness is installable from markdown alone.

Session starts
    |
    v
  Prime   -> make skill, guideline, and active store visible
    |
    v
User prompt arrives
    |
    v
  Remind  -> decide whether recall could change this task
    |
    v
Agent works and calls Mnemon only when useful
    |
    v
  Nudge   -> decide whether durable writeback is justified
    |
    v
Before context compaction
    |
    v
  Compact -> preserve only critical continuity

The four hook phases are reminders, not a hard workflow. Prime makes the skill, guideline, and active store visible. Remind prompts a recall decision. Nudge prompts a writeback decision. Compact preserves only critical continuity before context compression.

You don't run mnemon commands yourself. The agent