智能体持久记忆mnemon-dev/mnemon

Mnemon

English · 中文

面向 AI 智能体的 LLM 监督式持久记忆。

LLM 智能体在会话之间会遗忘一切。上下文压缩会丢弃关键决策，跨会话知识会消失，长对话会将早期信息挤出上下文窗口。

Mnemon 为你的智能体提供持久化的跨会话记忆——一个四图知识存储，具备意图感知召回、重要性衰减和自动去重功能。mnemon 记忆路径仍然是一个本地二进制文件，无需 API 密钥，只需一条设置命令。

Mnemon 以一个可执行文件的形式发布，包含两个独立的界面。记忆功能位于
mnemon 根路径；Agency Preview 位于 mnemon agency ...，为现有的 Pi
智能体添加持久的、项目本地的责任与效果准入机制。Agency 不会取代 Memory 或 Agent Runtime。

Claude Max / Pro 订阅用户？ Mnemon 完全通过你现有的订阅运行——无需单独的 API 密钥。你的 LLM 订阅就是智能层。两条命令即可完成。

为什么选择 Mnemon？

大多数记忆工具将自有的 LLM 嵌入到流程内部。Mnemon 采用了不同的方法：你的宿主 LLM 就是监督者。 二进制文件负责确定性计算（存储、图索引、搜索、衰减）；LLM 负责做出判断（记住什么、如何关联、何时遗忘）。没有中间商，没有额外的推理成本。

| 模式 | LLM 角色 | 代表 |
|---|---|---|
| LLM 嵌入式 | 流程内部的执行者 | Mem0、Letta |
| 文件注入式 | 无——在会话开始时读取文件 | Claude Code Memory |
| MCP 服务器 | 通过 MCP 协议提供工具 | claude-mem |
| LLM 监督式 | 独立二进制文件的外部监督者 | Mnemon |
Mnemon 还填补了协议栈中的一处空白。MCP 标准化了 LLM 如何发现和调用工具。ODBC/JDBC 标准化了应用程序如何访问数据库。但 LLM 如何使用记忆语义与数据库交互——这一层没有协议。Mnemon 的三个原语——remember、link、recall——构成了一种意图原生协议：命令名称映射到 LLM 的认知词汇（用 remember 而非 INSERT，用 recall 而非 SELECT），输出是带有信号透明度的结构化 JSON，而不是原始数据库行。

LLM 监督式模式：钩子驱动生命周期，宿主 LLM 做出判断，二进制程序处理确定性计算。

记忆具有复利效应——积累的时间越长，其价值越大。LLM 引擎不断迭代，技能文件的编写成本几乎为零，但记忆是随用户一同成长的私有资产。它是智能体生态系统中唯一值得深度投入的组件。

由 Mnemon 构建的真实知识图谱——87 条洞察，2150 条边，跨越四种图类型。

详见设计与架构。

快速开始

安装

npm（推荐；macOS / Linux / Windows，Node.js 22+）：

npm install --global @mnemon-dev/mnemon

随时升级由 npm 管理的 CLI：

mnemon update

npm 包会安装与宿主操作系统和 CPU 匹配的原生 Go 可执行文件。Mnemon 的引擎仍然是单个原生二进制文件；Node.js 仅由 npm 启动器和包管理器使用。

替代安装方式：

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

Homebrew、go install、源码构建以及其他 Node 包管理器必须继续使用其原始安装方式。要迁移这些安装方式之一，请运行一次 npm 安装命令，并确保 npm 全局 bin 目录在 PATH 中位于旧可执行文件之前；后续的 mnemon update 调用将由 npm 管理。

Windows 支持核心 Memory 命令。Agency 在 Windows 上仍不可用，直到其本地权限边界具备原生 Windows 安全性。

从源码安装（macOS / Linux）：

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

验证安装：

mnemon --version
mnemon agency --version

Agency（预览版 · Pi 优先）

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

为每个项目设置一次，然后正常使用 Pi。Agency 在 macOS 上可用
并且 Linux，且保持独立于 Memory：mnemon setup --target pi --yes
启用 Memory，而上方的命令启用 Agency。有关其运行模型、Preview 兼容性
边界以及可选对等节点，请参阅
Agency 指南。

Claude Code

mnemon setup

mnemon setup 会自动检测 Claude Code，然后以交互方式部署 skill、hooks 和行为指南。启动一个新会话——memory 即可直接使用。

Codex

mnemon setup --target codex --yes

一条命令即可在 .codex/hooks.json 中部署 mnemon skill、prompt 文件和 Codex 生命周期 hooks
（SessionStart、UserPromptSubmit、Stop）。

Cursor

mnemon setup --target cursor --yes

一条命令即可将 mnemon skill、prompt 文件和 Cursor 生命周期 hooks
部署到 .cursor/。该集成会为新 agent 会话预先注入 Mnemon 指南
和 memory 状态，然后在响应后提示进行持久记忆回写。

ZCode

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

ZCode 会将 Mnemon skill 安装到 ~/.zcode/skills/ 下，并在
~/.zcode/cli/config.json 中注册用户级生命周期 hooks。这些 hooks 会为新
会话预先注入内容，在模型调用前添加召回指南，并在停止时提示进行持久记忆
回写。如果不使用 --global，setup 仅安装项目 skill；
ZCode 目前会忽略项目级 hook 配置。

MiniMax Code

mnemon setup --target minimax-code --yes

一条命令即可将 Mnemon skill 部署到
.minimax/skills/mnemon/SKILL.md。添加 --global 可使用
~/.minimax/skills/mnemon/SKILL.md 跨项目使用。当前的 MiniMax Code
版本会原生发现这两个根目录。该集成有意仅提供 skill：在 MiniMax Code 3.0.65 中，本地 Agent V2 路径不会分发
可靠自动召回所需的用户提示生命周期 hook。

TRAE（TRAE Work）

mnemon setup --target trae --yes

一条命令即可将 mnemon skill、prompt 文件以及 TRAE 原生 hooks 部署到
TRAE IDE 和 TRAE Work 的 .trae/。该集成使用 .trae/hooks.json 中的 SessionStart、
UserPromptSubmit 和 Stop hooks。

Qoder（QoderWork）

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

Qoder 会将 mnemon skill、prompt 文件和原生 hooks 部署到 .qoder/
或 ~/.qoder/。QoderWork 使用其位于 ~/.qoderwork/ 的原生用户配置。
这两个集成都会在 settings.json 中注册 SessionStart、UserPromptSubmit 和 Stop
hooks。

CodeBuddy

mnemon setup --target codebuddy --yes

CodeBuddy 会将 mnemon skill、prompt 文件和原生 hooks 部署到
.codebuddy/ 或 ~/.codebuddy/。该集成会注册 SessionStart、
settings.json 中的 UserPromptSubmit 和 Stop 钩子。

WorkBuddy

mnemon setup --target workbuddy --yes

WorkBuddy 将 mnemon 技能、提示文件和原生钩子部署到
.workbuddy/ 或 ~/.workbuddy/。该集成会在 settings.json 中注册 SessionStart、
UserPromptSubmit 和 Stop 钩子。

Kimi Code

mnemon setup --target kimi --yes

Kimi Code 将 mnemon 技能、提示文件和原生生命周期钩子部署到
~/.kimi-code/ 或 $KIMI_CODE_HOME/。该集成会在 config.toml 中注册
SessionStart、UserPromptSubmit 和 Stop 钩子。

OpenCode

mnemon setup --target opencode --yes

OpenCode 将 mnemon 技能部署到 .opencode/skills/，通过 opencode.json 指令注册
生成的指南，并在 .opencode/plugins/ 中安装原生插件。该插件会在聊天请求前注入
召回上下文，并将 Mnemon 指南添加到会话压缩中。

OpenClaw

mnemon setup --target openclaw --yes

一条命令即可将技能、钩子、插件和行为指南部署到 ~/.openclaw/。重启 OpenClaw 网关以激活。

Pi

mnemon setup --target pi --yes

一条命令即可将 mnemon 技能、提示文件和 Pi TypeScript 扩展
部署到 .pi/。该扩展将 Mnemon 的生命周期提醒映射到 Pi 事件
（resources_discover、before_agent_start、agent_end、
session_before_compact）。启动新的 Pi 会话或运行 /reload 以激活。

Hermes Agent

mnemon setup --target hermes --yes

一条命令即可将 mnemon 技能、提示文件和 Hermes shell 钩子部署到
~/.hermes/。该集成使用 Hermes 的原生生命周期钩子：
on_session_start、pre_llm_call、post_llm_call，以及可选的
on_session_finalize。Hermes 可能会提示一次以批准已安装的 shell
钩子。

DeepSeek Harness

DeepSeek Harness（DSH）通过 dsh-mnemon 插件进行集成，该插件将 DSH 的运行时记忆、受管理的项目文档和 Mnemon 的长期记忆空间分层组合为一个受监督的三层记忆系统。

在主机上安装 mnemon 后（参见安装），添加该插件并重启你的 DSH Web 配置文件：

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

Mnemon 仓库也是一个直接的 GitHub 安装源。未发布的
插件构建仍可从专用仓库安装，本地
开发检出使用绝对路径：

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"
Mnemon 仓库中的新安装会解析 dsh-mnemon 的 latest npm 发布版本，因此发布新的插件版本不需要在此仓库中做相应的更改。现有安装会保持在其已解析的版本上，直到插件被重新安装或更新。

然后打开 DSH 的 Settings → Plugin Config → Mnemon 以选择存储范围，并在会话中使用 Memory System 标签页来创建或激活记忆空间。Recall 仅从活跃的记忆空间读取；持久写入通过受监督的子代理进行。

NanoClaw

NanoClaw 在 Linux 容器内运行代理。使用 /add-mnemon 技能进行集成：

1. 在主机上安装 mnemon（见上文）
2. 在你的 NanoClaw 项目中，运行 /add-mnemon —— Claude Code 将修改 Dockerfile、添加容器技能并设置卷挂载
3. 每个 WhatsApp 群组获得自己隔离的记忆存储，并可选择全局共享记忆（只读）

该技能位于 NanoClaw 仓库中的 .claude/skills/add-mnemon/。

Nanobot

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

一条命令即可将技能文件写入 ~/.nanobot/workspace/skills/mnemon/SKILL.md。记忆在所有 Nanobot 会话和项目之间共享。使用 --global（推荐），因为 Nanobot 从全局工作区目录发现技能。

卸载

mnemon setup --eject

工作原理

设置完成后，Memory 通过轻量级运行时投影运作：特定于运行时的 SKILL.md 教授命令，共享的 guide.md（默认为 ~/.mnemon/prompt/guide.md）承载判断指导，原生钩子或扩展在支持的生命周期边界处呈现提醒。mnemon 二进制文件执行确定性的记忆操作，而 mnemon setup 为每个受支持的运行时安装最接近的原生映射。

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

这四个钩子阶段是提醒，而非硬性工作流。Prime 使技能、指南和活跃存储可见。Remind 提示做出召回决策。Nudge 提示做出写回决策。Compact 在上下文压缩前仅保留关键连续性。

你不会自己运行 mnemon 命令。当指南表明记忆有用时，代理会运行它们。

特性

- 零用户侧操作 —— 安装一次；受支持的运行时可以使用钩子，最小化运行时可以使用持久规则
- LLM 监督 —— 宿主 LLM 决定记住、更新和遗忘什么；无嵌入式 LLM，无 API 密钥
- 多框架支持 — Claude Code、Codex、Cursor、ZCode、TRAE/TRAE Work、Qoder/QoderWork、CodeBuddy、WorkBuddy、Kimi Code、OpenCode 和 Hermes Agent（hooks/plugins）、OpenClaw（plugins）、Pi（extensions）、MiniMax Code 和 Nanobot（skills）、DeepSeek Harness（通过 dsh-mnemon 插件）等
- 运行时原生集成 — 运行时专属的 SKILL.md、共享的 guide.md，以及受支持的 hooks 或 extensions
- 四图架构 — 时间、实体、因果和语义边，而不仅仅是向量相似度
- 意图原生协议 — 三个原语（remember、link、recall）映射到 LLM 的认知词汇，而非数据库语法；结构化 JSON 输出并具备信号透明性
- 意图感知召回 — 图遍历 + 可选向量搜索（RRF 融合），默认对所有查询启用
- 内置去重 — remember 和 import 跳过完全重复的内容并保留不同的事实；相似度建议引导审查
- 保留生命周期 — 重要性衰减、访问计数提升和垃圾回收
- 隐私安全回执 — 导出哈希操作回执用于记忆边界审计，不包含原始记忆内容或查询
- 可选嵌入 — 在没有嵌入提供程序的情况下也能完全正常工作；添加本地 Ollama 或 OpenAI 兼容服务器以增强向量+关键词混合搜索

愿景

你所有的本地智能体 AI —— 跨会话和框架 —— 共享一个实时记忆池。

Claude Code ───────┐
│
Codex ─────────────┤
│
Cursor ────────────┤
│
ZCode ─────────────┤
│
MiniMax Code ──────┤
│
TRAE ──────────────┤
│
TRAE Work ─────────┤
│
Qoder ─────────────┤
│
QoderWork ─────────┤
│
CodeBuddy ─────────┤
│
WorkBuddy ─────────┤
│
Kimi Code ─────────┤
│
Hermes Agent ──────┤
│
DeepSeek Harness ──┤
│
OpenClaw ──────────┤
│
Pi ────────────────┤
│
Nanobot ───────────┤
│
NanoClaw ──────────┤
├──▶  ~/.mnemon  ◀── 共享记忆
OpenCode ──────────┤
│
Gemini CLI ────────┘

基础已经就位：一个单一的 ~/.mnemon 数据库，任何智能体都可以
读写。Claude Code、Codex、Cursor、ZCode、TRAE/TRAE Work、Qoder/QoderWork、
CodeBuddy、WorkBuddy、Kimi Code、OpenCode 和 Hermes Agent 的设置可自动完成 hook/plugin 安装；
OpenClaw 可以使用 plugin hooks；Pi 通过原生 skills 和 TypeScript
生命周期 extensions 集成；MiniMax Code 和 Nanobot 通过 skill 文件集成；NanoClaw 通过
容器 skills 和卷挂载集成。同一个集成包可以安装在任何
支持技能、规则、系统提示或事件钩子的 LLM CLI。

更长期的方向是记忆网关：协议与存储引擎解耦。当前的 SQLite 后端是第一个适配器；协议接口（remember / link / recall）可以架设在 PostgreSQL、Neo4j 或任何图数据库之上。Agent 侧优化（何时召回、记住什么）和存储侧优化（索引、图算法）独立演进。详见未来方向。

常见问题

不同会话之间会共享记忆吗？
会。默认情况下，所有会话使用同一个 default 存储——在一个会话中记住的决策，在未来的每个会话中都可用。

我可以按项目或 agent 隔离记忆吗？
可以。使用命名存储来隔离记忆：

mnemon store create work        # 创建一个新存储
mnemon store set work           # 设为默认
MNEMON_STORE=work mnemon recall "query"  # 或按进程使用环境变量

不同的 agent/进程可以通过 MNEMON_STORE 环境变量使用不同的存储——没有全局状态争用。

本地模式还是全局模式？
mnemon setup 默认使用本地模式（项目作用域的 .claude/），推荐大多数用户使用。全局模式（mnemon setup --global，安装到 ~/.claude/）会在所有项目中激活 mnemon——如果你想让其他框架（例如 OpenClaw）通过 Claude Code CLI 转发请求来共享记忆，这会很方便，但可能会增加维护开销。

如何自定义行为？
编辑生成的指南（在当前设置流程中为 ~/.mnemon/prompt/guide.md）。技能文件应专注于命令语法。

什么是子 agent 委派？
子 agent 委派是可选的。当运行时支持时，主 agent 可以决定记住什么，并让一个更廉价或隔离的 worker 来执行 mnemon remember。这是一种有用的执行策略，而不是 Mnemon 架构的必需部分。

配置

| 环境变量 | 默认值 | 描述 |
|---|---|---|
| MNEMON_DATA_DIR | ~/.mnemon | 基础数据目录 |
| MNEMON_STORE | （活动文件或 default） | 用于数据隔离的命名记忆存储 |

保留策略：

| 环境变量 | 默认值 | 描述 |
|---|---|---|
| MNEMON_MAX_INSIGHTS | 1000 | 活跃洞察上限；0 禁用自动修剪 |
| MNEMON_AUTO_PRUNE_MIN_AGE | 24h | 洞察可被自动修剪前的宽限期；接受 24h、7d 或 0 |

每次自动删除都是软删除，在 oplog 中显示为 prune 操作，并在触发命令的 auto_pruned_ids 字段中按 ID 报告。

嵌入（仅在使用嵌入时相关）：

| 环境变量 | 默认值 | 描述 |
|---|---|---|
| MNEMON_EMBED_ENDPOINT | http://localhost:11434 | 嵌入 API 端点 |
| MNEMON_EMBED_MODEL | nomic-embed-text | 嵌入模型名称 |
| MNEMON_EMBED_PROTOCOL | （自动检测） | ollama 或 openai；从以 /v1 结尾的端点自动检测 |
| MNEMON_EMBED_API_KEY | （无） | 用于 OpenAI 兼容服务器（oMLX、vLLM 等）的 Bearer 令牌 |
| MNEMON_EMBED_DIMENSIONS | （原生） | 可选的 Matryoshka 维度截断 |

嵌入客户端默认使用 Ollama API，当端点以 /v1 结尾时（或设置了
MNEMON_EMBED_PROTOCOL=openai 时）则使用 OpenAI 兼容的嵌入 API。
OpenAI 兼容服务器通常通过其 models 路由进行探测；不提供该
路由的服务器（例如 Voyage AI）则通过
一次嵌入往返来检测。例如，像 oMLX 这样的本地
服务器可以这样配置：

export MNEMON_EMBED_ENDPOINT=http://127.0.0.1:18000/v1
export MNEMON_EMBED_MODEL=bge-m3-mlx-8bit
export MNEMON_EMBED_API_KEY=sk-... # omit for keyless local servers
mnemon embed --status

像 Voyage AI 这样的托管提供商只需要端点、模型和密钥：

export MNEMON_EMBED_ENDPOINT=https://api.voyageai.com/v1
export MNEMON_EMBED_MODEL=voyage-3.5
export MNEMON_EMBED_API_KEY=pa-...
mnemon embed --status

开发

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

依赖项：Go 1.24+、modernc.org/sqlite、spf13/cobra、google/uuid

有关 Docker、Compose、Ollama 嵌入和发布设置，请参阅开发与部署。

文档

- Agency 预览 — 成熟度边界、Pi 设置、运营模型、完成语义以及可选对等方
- Go 工程标准 — 可维护性、并发、持久化、测试和审查阈值
- 设计与架构 — 当前引擎架构、算法、集成设计
- 内存使用与参考 — 根 Memory 命令、导入、回执和嵌入支持
- 内存导入指南 — 用于导入历史聊天的 schema 和 LLM 提示
- 架构图 — 系统架构、流水线、生命周期管理

Star 历史

参考资料
Mnemon 将一篇论文的范式与另一篇论文的方法论相结合，其基础是图记忆与 LLM 注意力同构这一结构性洞见。详见理论基础。

- RLM — Zhang、Kraska 与 Khattab。递归语言模型。2025 年。确立了该范式：LLM 作为外部环境的编排者比作为直接数据处理器更有效。
- MAGMA — Zou 等。一种基于多图的智能体记忆架构。2025 年。提供了该方法论：四图模型（时间、实体、因果、语义）与意图自适应检索。
- 图-LLM 结构性洞见 — Joshi 与 Zhu。从 Transformer 构建强大的 GNN。2025 年；以及基于图的智能体记忆综述（Chang Yang 等，2026 年）。证实了 LLM 注意力在计算上等价于 GNN 操作——图记忆是一种结构性匹配，而非工程上的便利。

许可证

版权所有 2026 Grivn 与 Mnemon 贡献者。

Apache-2.0

LICENSE 末尾附近的方括号版权示例是 Apache 2.0 标准应用附录的一部分；本节载有项目的实际版权声明。