mnemon

Mnemon

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. The mnemon memory path remains one local binary with zero API keys and one setup command.

Mnemon ships one executable with two separate surfaces. Memory stays at the mnemon root; Agency Preview lives at mnemon agency ... and adds durable, project-local responsibility and effect admission to an existing Pi agent. Agency does not replace Memory or the Agent Runtime.

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.

Pattern · LLM Role · Representative LLM-Embedded · Executor inside the pipeline · Mem0, Letta File Injection · None — reads file at session start · Claude Code Memory MCP Server · Tool provider via MCP protocol · claude-mem LLM-Supervised · External supervisor of a standalone binary · Mnemon

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.

The LLM-Supervised pattern: hooks drive the lifecycle, the host LLM makes judgment calls, the binary handles deterministic computation.

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.

A real knowledge graph built by Mnemon — 87 insights, 2150 edges across four graph types.

See Design & Architecture for details.

Web knowledge workspace

Browse the knowledge accumulated by your agents in a standalone local website:

mnemon web
# Open http://127.0.0.1:8484

Explore a searchable memory library, readable memory pages, a relationship graph, entities, and recorded activity. Select a memory store in the sidebar while agents continue writing through the existing CLI. Browsing preserves memory content, access counts, retention weights, and the CLI's active-store selection.

Use mnemon web --store --port 8485 to choose the initial store and port. The interface ships inside the Mnemon executable and uses bundled local assets. See the web workspace guide for usage, live-read behavior, and frontend development.

Quick Start

Install

npm (recommended; macOS / Linux / Windows, Node.js 22+):

npm install --global @mnemon-dev/mnemon

Upgrade the npm-managed CLI at any time:

mnemon update

The npm package installs the matching native Go executable for the host OS and CPU. Mnemon's engine remains a single native binary; Node.js is used only by the npm launcher and package manager.

Alternative installers:

brew install --cask mnemon-dev/tap/mnemon
go install github.com/mnemon-dev/mnemon@latest

Homebrew, go install, source builds, and other Node package managers must continue to use their original installation method. To migrate one of these installations, run the npm install command once and ensure the npm global bin directory precedes the old executable on PATH; subsequent mnemon update calls are npm-managed.

Windows supports the core Memory commands. Agency remains unavailable on Windows until its local authority boundary has native Windows security.

From source (macOS / Linux):

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

Verify installation:

mnemon --version
mnemon agency --version

Agency (Preview · Pi-first)

mnemon agency setup --runtime pi --project-root .

Set up each project once, then use Pi normally. Agency is available on macOS and Linux and remains independent from Memory: mnemon setup --target pi --yes enables Memory, while the command above enables Agency. See the Agency guide for its operating model, Preview compatibility boundary, and optional peers.

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.

ZCode

mnemon setup --target zcode --global --yes

ZCode installs the Mnemon skill under ~/.zcode/skills/ and registers user-level lifecycle hooks in ~/.zcode/cli/config.json. The hooks prime new sessions, add recall guidance before model calls, and prompt for durable-memory writeback at stop. Without --global, setup installs only the project skill; ZCode currently ignores project-level hook configuration.

The Stop hook honors stop_hook_active to avoid repeated reminders. Its completion fallback recognizes mnemon, durable memory, 持久记忆, and 写入记忆; the reminder asks for a [mnemon] marker so evaluations in any language can finish without another reminder. Windows hooks decode stdin as UTF-8, and the PowerShell script containing Chinese tokens includes a UTF-8 BOM for Windows PowerShell 5.1. Re-run setup and start a new ZCode session to update previously installed hooks.

MiniMax Code

mnemon setup --target minimax-code --yes

One command deploys the Mnemon skill to .minimax/skills/mnemon/SKILL.md. Add --global to use ~/.minimax/skills/mnemon/SKILL.md across projects. Current MiniMax Code releases discover both roots natively. The integration is intentionally skill-only: in MiniMax Code 3.0.65, the local Agent V2 path does not dispatch the user-prompt lifecycle hook required for dependable automatic recall.

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.

The plugin supports OpenCode v2 and v1.18.29 or newer. After updating Mnemon, rerun setup with the same scope (add --global for a user-wide installation), then restart OpenCode to replace an older plugin. See the OpenCode setup notes for runtime requirements.

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.