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

Mnemon

English · 中文

由 LLM 监督、为 AI 智能体提供持久记忆。

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

Mnemon 给你的智能体装上持久、跨会话的记忆——一个四图知识库，支持意图感知召回、重要性衰减和自动去重。mnemon 记忆路径仍然只是一个本地二进制，零 API key，一条命令完成安装。

Mnemon 只发布一个可执行文件，带两个彼此独立的界面。记忆功能留在 mnemon 根路径；Agency Preview 位于 mnemon agency ...，为已有的 Pi 智能体加上持久、项目本地的责任与效果准入。Agency 不替代 Memory，也不替代 Agent Runtime。

你是 Claude Max / Pro 订阅用户？ Mnemon 完全走你现有的订阅——不需要单独的 API key。你的 LLM 订阅就是智能层。两条命令搞定。

为什么选 Mnemon？

多数记忆工具把自家的 LLM 塞进流水线里。Mnemon 换了个思路：你的宿主 LLM 就是监督者。 二进制负责确定性计算（存储、图索引、搜索、衰减）；LLM 负责判断（记什么、怎么连、何时忘）。没有中间商，没有额外推理成本。

| 模式 | LLM 角色 | 代表 |
| LLM-Embedded | 流水线内的执行器 | Mem0、Letta |
| File Injection | 无——会话开始时读取文件 | Claude Code Memory |
| MCP Server | 通过 MCP 协议提供工具 | claude-mem |
| LLM-Supervised | 独立二进制文件的外部监督者 | Mnemon |

Mnemon 还填补了协议栈中的一处空白。MCP 标准化了 LLM 发现和调用工具的方式。ODBC/JDBC 标准化了应用访问数据库的方式。但 LLM 如何以记忆语义与数据库交互——这一层还没有协议。Mnemon 的三个原语——remember、link、recall——构成一套意图原生协议：命令名对应 LLM 的认知词汇（用 remember 而非 INSERT，用 recall 而非 SELECT），输出是结构化 JSON，信号透明，而不是原始数据库行。

LLM-Supervised 模式：钩子驱动生命周期，宿主 LLM 做判断，二进制文件负责确定性计算。

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

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

详见设计与架构。

Web 知识工作区

在独立的本地网站里浏览智能体积累的知识：

mnemon web
Open http://127.0.0.1:8484

Optional: shared Memory service and paper strategy, with composable records indexes.

浏览可搜索的记忆库、可读的记忆页面、关系图、实体和记录的活动。智能体继续通过现有命令行写入时，你可以在侧边栏选择记忆存储。浏览不会改动记忆内容、访问计数、保留权重，也不影响命令行当前选中的存储。

用 mnemon web --store <name> --port 8485 指定初始存储和端口。界面打包在 Mnemon 可执行文件内，使用内置本地资源。用法、实时读取行为和前端开发见 Web 工作区指南。

快速开始

安装

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

npm install --global @mnemon-dev/mnemon

随时升级 npm 管理的命令行：

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。有关其运行模型、预览版兼容性边界和可选对等端，请参阅 Agency 指南。

Claude Code

mnemon setup

mnemon setup 会自动检测 Claude Code，然后交互式部署技能、钩子和行为指南。启动新会话——记忆即刻生效。

Codex

mnemon setup --target codex --yes

一条命令即可在 .codex/hooks.json 中部署 mnemon 技能、提示词文件和 Codex 生命周期钩子（SessionStart、UserPromptSubmit、Stop）。

Cursor

mnemon setup --target cursor --yes

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

ZCode

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

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

Stop 钩子会遵循 stop_hook_active 以避免重复提醒。其完成回退逻辑能识别 mnemon、durable memory、持久记忆 和 写入记忆；提醒会要求一个 [mnemon] 标记，以便任何语言的评估都能完成而无需再次提醒。Windows 钩子将 stdin 解码为文件用 UTF-8 编码，含中文 token 的 PowerShell 脚本带 UTF-8 BOM，供 Windows PowerShell 5.1 使用。重新运行 setup，再开一个新 ZCode 会话，更新之前装好的钩子。

MiniMax Code

mnemon setup --target minimax-code --yes

一条命令把 Mnemon 技能部署到 .minimax/skills/mnemon/SKILL.md。加 --global，改用 ~/.minimax/skills/mnemon/SKILL.md，跨项目生效。当前 MiniMax Code 版本原生识别这两个根目录。集成刻意只做技能：在 MiniMax Code 3.0.65 里，本地 Agent V2 路径不派发 user-prompt 生命周期钩子，而可靠的自动召回需要这个钩子。

TRAE（TRAE Work）

mnemon setup --target trae --yes

一条命令把 mnemon 技能、提示词文件和 TRAE 原生钩子部署到 .trae/，TRAE IDE 和 TRAE Work 都适用。集成使用 .trae/hooks.json 里的 SessionStart、UserPromptSubmit 和 Stop 钩子。

Qoder（QoderWork）

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

Qoder 把 mnemon 技能、提示词文件和原生钩子部署到 .qoder/ 或 ~/.qoder/。QoderWork 用自带的用户配置目录 ~/.qoderwork/。两个集成都在 settings.json 里注册 SessionStart、UserPromptSubmit 和 Stop 钩子。

CodeBuddy

mnemon setup --target codebuddy --yes

CodeBuddy 把 mnemon 技能、提示词文件和原生钩子部署到 .codebuddy/ 或 ~/.codebuddy/。集成在 settings.json 里注册 SessionStart、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 的 instructions 注册生成的指南，并在 .opencode/plugins/ 里安装原生插件。插件在聊天请求前注入召回上下文，还会把 Mnemon 指南加进会话压缩。

插件支持 OpenCode v2 和 v1.18.29 或更高版本。更新 Mnemon 后，用相同范围重跑 setup（用户级安装加 --global），然后重启 OpenCode，替换旧插件。运行时要求见 OpenCode setup notes。

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 钩子。

Alma

mnemon setup --target alma --yes

一条命令把 mnemon 技能、mem shim 和单个 app.ready 钩子部署到 ~/.config/alma/。Alma 钩子的 stdout 不会注入模型上下文——只消费最后一行 JSON 里的 decision、reason 和 updatedInput——所以这个集成的形态刻意不同于生命周期钩子类目标：钩子只做一件事（刷新 MEMORY.md 里一个生成的块，Alma 每次请求都会把它注入系统提示词），召回则交给模型通过技能完成。该块用 / 界定，标记之外的内容逐字节保留，因为 Alma 自己的提示词也让模型写同一个文件。

Alma 没有项目级钩子配置，所以这个目标仅限用户全局。

DeepSeek Harness

DeepSeek Harness（DSH）通过 dsh-mnemon 插件集成，把 DSH 的运行时记忆、托管项目文档和 Mnemon 的长期记忆空间叠加成一套受监管的三层记忆系统。

主机上装好 mnemon（见 Install）后，添加插件并重启 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 标签页创建或激活记忆空间。召回只读取活跃的记忆空间；持久写入由受监督的子代理完成。

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 key
- 多框架支持 — Claude Code、Codex、Cursor、ZCode、TRAE/TRAE Work、Qoder/QoderWork、CodeBuddy、WorkBuddy、Kimi Code、OpenCode，以及 Hermes Agent（钩子/插件）、OpenClaw（插件）、Pi（扩展）、Alma（技能 + app.ready 钩子）、MiniMax Code 和 Nanobot（技能）、DeepSeek Harness（通过 dsh-mnemon 插件）等
- 运行时原生集成 — 各运行时专属的 SKILL.md、共享的 guide.md，以及受支持的钩子或扩展
- 四图架构 — 时间、实体、因果、语义四类边，不只是向量相似度
- 意图原生协议 — 三个原语（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 ◀── shared memory
OpenCode ──────────┤
│
Gemini CLI ────────┘

基础已经就位：一个 ~/.mnemon 数据库，任何智能体都能读写。Claude Code、Codex、Cursor、ZCode、TRAE/TRAE Work、Qoder/QoderWork、CodeBuddy、WorkBuddy、Kimi Code、OpenCode 和 Hermes Agent 的安装流程会自动装好钩子/插件；OpenClaw 可以用插件钩子；Pi 通过原生技能和 TypeScript 生命周期扩展集成；MiniMax Code 和 Nanobot 通过技能文件集成；NanoClaw 通过容器技能和卷挂载集成。同一套集成包可以装进任何支持技能、规则、系统提示词或事件钩子的 LLM 命令行。

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

FAQ

不同会话共享记忆吗？ 共享。默认情况下，所有会话都用同一个 default 存储——在某个会话里记住的决策，之后每个会话都能用。

可以按项目或智能体隔离记忆吗？ 可以。用命名存储把记忆分开：

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

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

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

怎么自定义行为？ 编辑生成的指南文件（当前安装流程下是 ~/.mnemon/prompt/guide.md）。技能文件应只聚焦命令语法。

什么是子代理委派？ 子代理委派是可选项。运行时支持时，主智能体可以决定记住什么，再让更便宜或隔离的 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 |

每次自动删除都是软删除，会以 prune 操作出现在 oplog 中，并在触发命令的 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 兼容服务器用的 Bearer token（oMLX、vLLM 等） |
| MNEMON_EMBED_KEEP_ALIVE | 30m | Ollama 每次请求后把嵌入模型保留在内存里多久（OpenAI 兼容服务器忽略此项） |
| MNEMON_EMBED_DIMENSIONS | （原生） | 可选的 Matryoshka 维度截断 |

嵌入客户端默认走 Ollama API；端点以 /v1 结尾时（或设置了 MNEMON_EMBED_PROTOCOL=openai 时）走 OpenAI 兼容的 embeddings API。
OpenAI 兼容服务器通常通过 models 路由探测；不提供该路由的服务器（例如 Voyage AI）改用一次 embeddings 往返来检测。
例如，本地服务器 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 嵌入和发布配置见 开发与部署。

可选的 Memory Agent 与 AML 后端

Memory Agent 通过显式的 mnemon memory-agent ... 命令暴露 v0.3.4 AML 评估引擎。它保存原始记录，构建带来源链接的记忆索引，返回证据供智能体据此作答。读取和整合需要单独配置模型。

现有的 remember、recall、search、setup、钩子和 Web 库继续使用原生 Memory 和 mnemon.db。不会自动迁移、激活模型或切换默认引擎。
要用这些新命令，需构建本分支；开 PR 不会更新已发布的命令行或 npm 发行版。

mnemon memory-agent aml-serve 增加 AML Add/Search API，支持按用户隔离存储、有界后台整合、认证和预算。其运维面包括就绪检查、指标、脱敏日志、追踪和只读检查。见 AML 适配器运行手册、 Admin API 和 Inspect API。
独立的托管控制台、前端 UI/UX、设计原型和私有评测数据不在本次源码快照范围内。

文档

- Agency Preview — 成熟度边界、Pi 配置、运行模型、完成语义和可选对等节点
- Go Engineering Standard — 可维护性、并发、持久化、测试和评审阈值
- Design & Architecture — 当前引擎架构、算法、集成设计
- Memory Usage & Reference — 根 Memory 命令、导入、回执和嵌入支持
- Optional Memory Agent — v0.3.4 基线、显式配置、记录与证据视图
- Memory Import Guide — 导入历史聊天所需的 schema 和 LLM 提示词
- Architecture Diagrams — 系统架构、流水线、生命周期管理
- Memory Agent (experimental) — Mnemon 作为 DSH 上记忆智能体的研究预览，Jev 是其 System 1 决策模型；含论文、代码和运行记录
- AML adapter runbook — 把 Agent Memory Leaderboard 服务当作记忆云实例：安装、打开、运维、告警、数据删除
- Admin API — 实例的管理监听器：token、私有绑定、指标、就绪检查、状态和存储概览

Star History

参考文献

Mnemon 结合了两篇论文的范式与方法论，其结构洞见是：图记忆与 LLM 注意力同构。详见理论基础。

- RLM — Zhang, Kraska & Khattab. Recursive Language Models. 2025. 确立范式：LLM 作为外部环境的编排者，比作为直接的数据处理器更有效。
- MAGMA — Zou et al. A Multi-Graph based Agentic Memory Architecture. 2025. 提供方法论：四图模型（时序、实体、因果、语义），配合意图自适应检索。
- Graph-LLM 结构洞察 — Joshi & Zhu。用 Transformer 构建强大的 GNN。2025；以及基于图的智能体记忆综述（Chang Yang 等，2026）。这证实了 LLM 注意力在计算上等价于 GNN 运算——图记忆是结构上的匹配，而不是工程上的便利。

许可证

Copyright 2026 Grivn and Mnemon contributors.

Apache-2.0

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