一句话定位

mnemon 把 DSH Web 装配成一款带持久记忆的 AI 客户端：宿主 LLM 仍是判断者，mnemon 二进制负责把对话沉淀成本地图谱记忆，下次开会话时再召回到上下文里。

核心能力

• 在 DSH 会话中注入三层监督式记忆：DSH 自带的运行时热记忆、受管项目档案，以及 Mnemon 的长期记忆空间
• 用 remember/link/recall 三原语代替数据库 INSERT/SELECT，把记忆操作对齐到 LLM 的认知词汇
• 在图谱上做四类关系检索（时间、实体、因果、语义），召回时自动去重与冲突合并
• 会话窗口压缩前自动保留关键连续性，避免长对话把早期决定挤出上下文
• 跨会话持久：一次写入，所有后续会话都能在 default 库中读到
• 支持可选的本地 Ollama 向量检索，无需联网也不消耗推理配额

技术实现

• 语言: Go 1.24.6（外加仓库根 package.json 描述 DSH 装配契约）
• 关键依赖: modernc.org/sqlite（纯 Go SQLite，无需 CGo）、spf13/cobra（CLI 框架）、google/uuid、go.yaml.in/yaml/v3
• 架构模式: 以 cordis.patch.yml 把 dsh-mnemon 子插件挂载到 DSH 宿主；插件内部调用主机上的 mnemon 二进制完成存储与检索，二进制与 LLM 之间由宿主裁决写入与召回
• 入口文件: DSH 侧由 cordis.patch.yml 声明；Go 二进制侧由 main.go + cmd/memory/root.go 启动

适用场景

你常用 DSH Web 处理跨会话的连续工作（多轮迭代、长线重构、长期客户/项目档案），却发现重要决定和上下文总被压缩或遗忘。装上 mnemon 后，每次新开会话会自动召回上次的记忆，结束时再决定是否落库。日常开发中如果你还要在 Claude Code / Cursor / Codex 等其他 runtime 之间共享记忆，可以同时跑 mnemon setup --target <runtime>，背后读的是同一个 ~/.mnemon 数据库。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:mnemon-dev/mnemon

配置项

DSH 侧插件层配置（由 cordis.patch.yml 注入，可在 DSH 的 Plugin Config → Mnemon 中调整）：

mnemon 二进制侧的环境变量（一般无需修改）：

常见问题

Q: 这个插件需要在系统里先装什么？

A: 需要在主机上先装好 mnemon 二进制（推荐 brew install --cask mnemon-dev/tap/mnemon 或 go install github.com/mnemon-dev/mnemon@latest）。DSH 这边的插件只是把 mnemon 接到 Web 客户端上，没有主程序就跑不起来。

Q: 是否需要额外申请 API Key？

A: 不需要。Mnemon 把记忆判断完全交给宿主 LLM，二进制只负责存储和检索这些确定性工作；只有在你额外启用 Ollama 向量增强时才涉及本地模型。

Q: 不同会话之间会共享记忆吗？

A: 默认会。所有会话共享一个名为 default 的库，一次写入后续都能读到。需要项目级隔离的话用 mnemon store create <name> 建库，再用 mnemon store set <name> 切换，或临时通过 MNEMON_STORE=work 启动进程。

Q: 想自定义记忆判断规则去哪里改？

A: 改 ~/.mnemon/prompt/guide.md（DSH Plugin Config 中挂载的就是它），这里写的是"什么时候该 recall、什么时候该 remember"的人话规则。SKILL.md 只描述命令语法，不要混在一起改。

Q: macOS/Windows/Linux 都能用吗？

A: 记忆核心功能在三个平台都能用。Windows 上 mnemon agency … 这一组命令目前未开放（源码里 cmd/agency/*.go 用 //go:build !windows 限定），需要 Agency 能力请在 macOS 或 Linux 上跑。

Q: 是否必须启动本地 Ollama？

A: 不是。无 Ollama 时 Mnemon 只跑图谱检索（时间、实体、因果、语义四类边），召回质量已经足够日常使用；想再加上向量相似度召回再启 Ollama。

Q: 想完全卸载怎么办？

A: 在 DSH 的 Plugin Config 中卸载 dsh-mnemon；再在主机上跑一次 mnemon setup --eject，会清除所有 runtime 下发的 hook、skill 和 guide 文件。

上手难度

入门 — 只跑一条 dsh plugin --profile web add … 加上主机一行 mnemon setup 即可；默认值已经把常用钩子和标签页全部开启，普通用户基本不需要再改配置。

已知问题与限制

• Windows 暂不支持 mnemon agency … 子命令族（cmd/agency/serve.go:1、cmd/agency/setup.go:1 等以 //go:build !windows 限定），仅记忆核心可用。
• 依赖主机上预装 mnemon 二进制；DSH 这边的插件不自带二进制，必须先安装或链接到本机版本。
• 若启用 Ollama 向量增强，需要本地 Ollama 服务可用且模型名匹配 MNEMON_EMBED_MODEL，否则降级为纯图谱检索（功能可用但召回质量下降）。
• DSH 的具体最低兼容版本在 package.json 中未声明，需在 Web 端实际验证。

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. 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.

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.

Quick Start

Install

Homebrew Cask (macOS):

brew install --cask mnemon-dev/tap/mnemon

Go install (macOS / Linux / Windows):

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

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.

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.

DeepSeek Harness

DeepSeek Harness (DSH) integrates through the dsh-mnemon plugin, which layers DSH's runtime memory, managed project documents, and Mnemon's long-term memory spaces into one supervised three-tier memory system.

With mnemon installed on the host (see Install), add the plugin and restart your DSH Web profile:

dsh plugin --profile web add dsh-mnemon
dsh --profile web

The Mnemon repository is also a direct GitHub installation source. Unreleased plugin builds can still be installed from the dedicated repository, and local development checkouts use an absolute path:

dsh plugin --profile web add github:mnemon-dev/mnemon
dsh plugin --profile web add "github:omdsh-dev/dsh-mnemon"
dsh plugin --profile web add "link:/absolute/path/to/dsh-mnemon"

Then open DSH's Settings → Plugin Config → Mnemon to pick a storage scope, and use the Memory System tab in a session to create or activate memory spaces. Recall reads only from active memory spaces; durable writes go through supervised sub-agents.

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 lightweight runtime projections: a runtime-specific SKILL.md teaches commands, a shared guide.md (by default ~/.mnemon/prompt/guide.md) carries judgment guidance, and native hooks or extensions surface reminders at supported lifecycle boundaries. The mnemon binary executes deterministic memory operations, while mnemon setup installs the closest native mapping for each supported runtime.

Session starts
    |
    v
  Prime   -> make skill, guide, 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, guide, 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 does when the guide says memory is useful.

Features

• Zero user-side operation — install once; supported runtimes can use hooks, minimal runtimes can use persistent rules
• LLM-supervised — the host LLM decides what to remember, update, and forget; no embedded LLM, no API keys
• Multi-framework support — Claude Code, Codex, Cursor, TRAE/TRAE Work, Qoder/QoderWork, CodeBuddy, WorkBuddy, Kimi Code, OpenCode, and Hermes Agent (hooks/plugins), OpenClaw (plugins), Pi (extensions), Nanobot (skills), DeepSeek Harness (via the dsh-mnemon plugin), and more
• Runtime-native integration — runtime-specific SKILL.md, shared guide.md, and supported hooks or extensions
• Four-graph architecture — temporal, entity, causal, and semantic edges, not just vector similarity
• Intent-native protocol — three primitives (remember, link, recall) map to the LLM's cognitive vocabulary, not database syntax; structured JSON output with signal transparency
• Intent-aware recall — graph traversal + optional vector search (RRF fusion), enabled by default for all queries
• Built-in deduplication — remember auto-detects duplicates and conflicts; skips or auto-replaces
• Retention lifecycle — importance decay, access-count boosting, and garbage collection
• Privacy-safe receipts — export hashed operation receipts for memory-boundary audits without raw memory contents or queries
• Optional embeddings — works fully without Ollama; add local Ollama for enhanced vector+keyword hybrid search

Vision

All your local agentic AIs — across sessions and frameworks — sharing one pool of live memory.

  Claude Code ──┐
                │
  Codex ────────┤
                │
  Cursor ───────┤
                │
  TRAE ─────────┤
                │
  TRAE Work ────┤
                │
  Qoder ────────┤
                │
  QoderWork ────┤
                │
  CodeBuddy ────┤
                │
  WorkBuddy ────┤
                │
  Kimi Code ────┤
                │
  Hermes Agent ─┤
                │
  OpenClaw ─────┤
                │
  Pi ───────────┤
                │
  Nanobot ──────┤
                │
  NanoClaw ─────┤
                ├──▶  ~/.mnemon  ◀── shared memory
  OpenCode ─────┤
                │
  Gemini CLI ───┘

The foundation is in place: a single ~/.mnemon database that any agent can read and write. Claude Code, Codex, Cursor, TRAE/TRAE Work, Qoder/QoderWork, CodeBuddy, WorkBuddy, Kimi Code, OpenCode, and Hermes Agent setup automate hook/plugin installation; OpenClaw can use plugin hooks; Pi integrates via native skills and TypeScript lifecycle extensions; Nanobot integrates via skill files; NanoClaw integrates via container skills and volume mounts. The same integration bundle can be installed in any LLM CLI that supports skills, rules, system prompts, or event hooks.

The longer-term direction is a memory gateway: protocol decoupled from storage engine. The current SQLite backend is the first adapter; the protocol surface (remember / link / recall) can sit on top of PostgreSQL, Neo4j, or any graph database. Agent-side optimization (when to recall, what to remember) and storage-side optimization (indexing, graph algorithms) evolve independently. See Future Direction for details.

FAQ

Do different sessions share memory? Yes. By default, all sessions use the same default store — a decision remembered in one session is available in every future session.

Can I isolate memory per project or agent? Yes. Use named stores to separate memory:

mnemon store create work        # create a new store
mnemon store set work           # set as default
MNEMON_STORE=work mnemon recall "query"  # or use env var per-process

Different agents/processes can use different stores via the MNEMON_STORE environment variable — no global state contention.

Local or global mode? mnemon setup defaults to local (project-scoped .claude/), recommended for most users. Global (mnemon setup --global, installed to ~/.claude/) activates mnemon across all projects — convenient if you want other frameworks (e.g., OpenClaw) to share memory by forwarding requests through Claude Code CLI, but may add maintenance overhead.

How do I customize the behavior? Edit the generated guideline (~/.mnemon/prompt/guide.md in current setup flows). Skill files should stay focused on command syntax.

What is sub-agent delegation? Sub-agent delegation is optional. When a runtime supports it, the main agent can decide what to remember and ask a cheaper or isolated worker to execute mnemon remember. It is a useful execution strategy, not a required part of the Mnemon architecture.

Configuration

Ollama-specific (only relevant if using embeddings):

Development

make build          # build the single mnemon executable
make install        # build + install to $GOBIN
make test           # run deterministic CI tests
make test-integration  # opt-in CLI E2E and Agency boundary tests
mnemon setup        # interactive setup
mnemon setup --eject  # remove all integrations
make help           # show all targets

Dependencies: Go 1.24+, modernc.org/sqlite, spf13/cobra, google/uuid

See Development and Deployment for Docker, Compose, Ollama embedding, and release setup.

Documentation

• Agency Preview — maturity boundary, Pi setup, operating model, completion semantics, and optional peers
• Go Engineering Standard — maintainability, concurrency, persistence, testing, and review thresholds
• Design & Architecture — current engine architecture, algorithms, integration design
• Memory Usage & Reference — root Memory commands, import, receipts, and embedding support
• Memory Import Guide — schema and LLM prompt for importing historical chats
• Architecture Diagrams — system architecture, pipelines, lifecycle management

References

Mnemon combines the paradigm of one paper with the methodology of another, grounded in the structural insight that graph memory is isomorphic to LLM attention. See Theoretical Foundations for details.

• RLM — Zhang, Kraska & Khattab. Recursive Language Models. 2025. Establishes the paradigm: LLMs are more effective as orchestrators of external environments than as direct data processors.
• MAGMA — Zou et al. A Multi-Graph based Agentic Memory Architecture. 2025. Provides the methodology: four-graph model (temporal, entity, causal, semantic) with intent-adaptive retrieval.
• Graph-LLM Structural Insight — Joshi & Zhu. Building Powerful GNNs from Transformers. 2025; and the Graph-based Agent Memory survey (Chang Yang et al., 2026). Confirms that LLM attention is computationally equivalent to GNN operations — graph memory is a structural match, not an engineering convenience.

License

Copyright 2026 Grivn and Mnemon contributors.

Apache-2.0