memory-lean

memory-lean

为 AI 编码 Agent 提供长期记忆，不会占满上下文窗口。
Agent 可低成本搜索的知识图谱，以及可查看和编辑全部内容的 Web UI。

快速开始 · Web UI · 工作原理 · 工具 · 为 12 种 Agent 配置 · 参与贡献

memory-lean 是一个 MCP 服务，为 Claude Code、Codex、Cursor、MiMo Code 和其他 MCP 客户端提供跨会话持久记忆：有哪些项目、项目之间的依赖关系、发布了哪个版本、还有哪些待办事项，以及从实践中学到的规则。它可直接替换参考记忆服务 （@modelcontextprotocol/server-memory）， 使用相同的文件名和工具名，但回答内容约精简 40 倍。

亮点

回答精简约 40 倍。 搜索会返回排序后的名称列表和匹配行，而不是完整的所有实体，因此 Agent 可以在每项任务开始前查询记忆。	面向用户的 Web UI。 查看按类型分组的整个图谱、追踪关系，还可以添加、编辑或删除任意内容。Agent 写入的内容会实时显示。
可直接替换。 使用与参考服务相同的 memory.jsonl 文件和九种工具。随时切换，也可以随时切回。	适用于各种 Agent。 提供 Claude Code、MiMo Code、Codex、Cursor、Copilot、Gemini CLI、Zed、JetBrains 等工具的复制粘贴式配置，以及教 Agent 如何使用它的说明。
自动保持精简。 使用简短事实、为每个实体设置上限，并将溢出内容归档，避免图谱膨胀成一堵文字墙。	隐私安全。 使用纯本地文件、每日备份、支持并行会话的写入锁，且不访问网络。单个服务文件，零依赖。

## 数字

在包含 237 个实体、355 个关系和 1,160 条事实的真实图谱上测量得出 （Token 数 ≈ 字符数 ÷ 4）：

调用	参考服务	memory-lean
read_graph	~77,800 个 Token	~2,000 个 Token	缩小 40 倍
search_nodes，对 5 个常见词取平均	~31,000 个 Token	~770 个 Token	缩小 40 倍

匹配一两个实体的窄范围搜索，节省的内容较少，因为可精简的部分不多。要测量自己的图谱，请在克隆的仓库中运行 node tools/bench.mjs；该命令只读，并会输出大小，绝不输出内容。

快速开始

Claude Code：安装插件。它会添加服务、作为技能的说明、每个会话开始时的简短提醒，以及 /memory-ui。

/plugin marketplace add zamansheikh/memory-lean
/plugin install memory-lean@memory-lean

其他 Agent：将服务添加到其 MCP 配置中，然后提供说明。

{
  "mcpServers": {
    "memory": { "command": "npx", "args": ["-y", "memory-lean"] }
  }
}

npx -y memory-lean --protocol >> AGENTS.md   # into the rules file your agent reads

只是想看看？ 打开网页 UI，查看一个虚构示例图谱：

npx -y memory-lean --ui --demo

各 Agent 的设置

Agent	服务配置	说明
Claude Code	插件	插件内含
Xiaomi MiMo Code	mimocode.jsonc	技能或 AGENTS.md
opencode	opencode.json	AGENTS.md
OpenAI Codex CLI	codex mcp add	AGENTS.md
Cursor	.cursor/mcp.json	AGENTS.md 或规则
VS Code (Copilot)	.vscode/mcp.json	copilot-instructions.md
Gemini CLI	settings.json	GEMINI.md
Windsurf	mcp_config.json	规则
Cline	cline_mcp_settings.json	.clinerules/
Zed	settings.json	AGENTS.md 或 .rules
JetBrains IDEs	AI Assistant 设置	规则或指南
Claude Desktop	claude_desktop_config.json	项目说明

无论哪个 Agent 首次写入，图谱都会创建在 ~/.claude/memory-graph/memory.jsonl。这样，所有 Agent 都能共享同一份记忆。设置 MEMORY_FILE_PATH 可将其保存到其他位置。

Web UI

npx -y memory-lean --ui

这会在浏览器中打开你的记忆。Agent 能做的所有事情，你都可以在这里完成：

• 探索。 每种类型都有自己的气泡。点击一个实体即可高亮显示与之关联的所有内容；拖动节点可调整位置，滚动可缩放视图。 搜索会匹配名称、类型和事实。
• 编辑。 添加、编辑和删除事实，重命名实体或更改其类型，添加和移除关系，创建和删除实体，以及恢复已归档的事实。 每项更改都会通过与 Agent 工具相同的检查。
• 查看动态。 Agent 所做的更改会在两秒内显示。
• 发现问题。 概览会列出待处理工作、关联最多的实体，以及任何超出预算的内容；超出预算的内容也会在图中标出。

顺着关联查看。 选择一个实体即可查看其事实和关系。	查找任何内容。 一次搜索即可匹配名称、类型和事实。
就地编辑。 字符数限制与 Agent 相同，均为 300 个字符。	浅色或深色。 页面会跟随你的系统设置，也可以自行选择。

此页面仅在你的机器上运行（127.0.0.1），并需要使用它打印出的链接中的一次性密钥，因此其他网站无法读取或更改你的记忆。任何内容都不会上传到其他地方。

工作原理

先搜索，再打开

参考服务会以完整的格式化 JSON 返回所有匹配的实体。memory-lean 则会返回按相关性排序的名称列表，以及匹配到的行：

> search_nodes { "query": "deploy" }

57 match "deploy", top 10 shown (narrow the query or raise limit). open_nodes for full entities.
- shop-backend [service] 12 obs, 6 rel
    › 2026-03-02: deployed 2.4.0 to production
    › deploy with scripts/release.sh, never by hand
- PENDING shop-backend 2.4.0 [pending] 2 obs, 3 rel
    › …mobile apps still call the old endpoint until the deploy of 2.4.0 reaches them

然后，Agent 只打开所需的内容：

> open_nodes { "names": ["shop-backend"] }

## shop-backend [service] (3 archived)
- NestJS API behind api.example.com
- 2026-03-02: deployed 2.4.0 to production

## relations
shop-app -talks_to-> shop-backend
PENDING shop-backend 2.4.0 -blocks-> shop-app

为什么它能保持精简

限制	含义
简短的响应	search_nodes 最多返回 10 个名称及其摘要，read_graph 返回名称索引，只有 open_nodes 会返回完整实体。
简短的事实	超过 300 个字符的观察会被拒绝，并提示 Agent 将其拆分，或把详细内容放入仓库。
每个实体的上限	一个实体最多保留 15 条观察。超过后，最早的带日期观察会移至 archive/<entity>.md。内容不会被删除：可以列出并恢复这些观察；无日期的事实（身份事实）始终保留。
逐步缩小范围的搜索	每个词都必须在实体的某处匹配，因此增加一个词就会缩小结果范围。参考服务会将查询视为一个完整短语进行精确匹配。

如何保护你的数据安全

防护措施	含义
可安全共享	写入程序会使用锁文件，因此多个 Agent 会话可以共用一张图，而不会相互覆盖。每次写入都会以原子方式替换文件。
每日备份	每天会将一份副本存入 backups/；保留最近 7 份。
保留损坏的行	无法读取的行会在下次写入时移至 memory.jsonl.unreadable，并报告出来，绝不会被悄悄丢弃。
纯文本文件	图数据采用 JSON Lines 格式，归档文件为 Markdown，备份则是副本。你可以手动读取、搜索和编辑所有内容。

工具

工具	返回内容
search_nodes	按排名排列的实体名称列表，包含计数和最多两个匹配片段。每个词都必须与名称、类型、某条观察记录或与该实体相连的关系类型匹配。
open_nodes	以紧凑文本形式返回你指定的完整实体，以及与其相连的所有关系和归档计数。未知名称会返回“你是不是想找”建议。
read_graph	索引：按类型分组的实体名称及其观察记录数量。不包含观察记录本身。
create_entities	创建实体；跳过已存在的名称。
create_relations	在现有实体之间创建关系；跳过重复项。
add_observations	向实体添加事实，并强制执行长度限制和每个实体的数量上限。
delete_observations	按完全匹配的文本删除观察记录。
delete_relations	删除指定的关系。
delete_entities	删除实体及与其相连的所有关系。
rename_entity	重命名实体，同时保留其观察记录、关系和归档。参考服务中不提供此工具。
archived_observations	列出某个实体的归档内容，可按条件筛选，并恢复选定事实。参考服务中不提供此工具。

三个读取工具均标记为只读，因此支持此功能的客户端可以在不询问的情况下运行它们。

命令行

命令	功能
memory-lean	通过 stdio 运行 MCP 服务。这是 Agent 启动的命令。
memory-lean --ui [port]	打开 Web UI。--no-open 只打印链接；--demo 使用一份临时的虚构图副本。
memory-lean --protocol	打印 Agent 指令，可直接追加到 AGENTS.md、CLAUDE.md 或 GEMINI.md。
memory-lean --skill <dir>	将相同的指令作为 Agent Skill 写入 <dir>/memory-graph。
memory-lean --lint	报告图中超出预算的内容。只读。
memory-lean --compact	备份图，然后将超出限制的观察记录移至归档。
memory-lean --version	打印版本号。

使用 npx 时，在前面加上 npx -y：npx -y memory-lean --ui。

教会你的 Agent 使用它

只有 Agent 会在开始工作前读取记忆服务器，并在发生变化时写入信息，记忆服务器才能发挥作用。docs/AGENT-PROTOCOL.md 是一套可直接使用的指令：说明任务开始时要查找什么、要记录什么、如何命名，以及哪些内容绝不能存储。Claude Code 插件已包含这套指令。对于其他所有 Agent，只需运行一条命令即可安装：

npx -y memory-lean --protocol >> AGENTS.md     # into a rules file: always on
npx -y memory-lean --skill .agents/skills      # as an Agent Skill: loaded when relevant

根据你自己的工作调整其中的实体类型和名称。

从参考记忆服务器迁移

将 MEMORY_FILE_PATH 指向现有的 memory.jsonl，并替换命令即可。文件格式完全相同，因此你可以随时切换回去。超过 300 个字符的现有观察记录会原样保留；只有新写入的内容会经过检查。若要查看哪些内容超出限制，并选择性地修复：

npx -y memory-lean --lint      # report only
npx -y memory-lean --compact   # back up, then move overflow to archive/

设置

所有设置均为可选项，请在服务端将其设为环境变量：

变量	默认值	含义
MEMORY_FILE_PATH	~/.claude/memory-graph/memory.jsonl	图的存储位置
MEMORY_OBS_MAX_CHARS	300	可接受的观察记录的最长字符数
MEMORY_OBS_MAX	15	每个实体的观察记录数量上限；超出时将最早的带日期记录归档
MEMORY_SEARCH_LIMIT	10	默认搜索结果数量
MEMORY_BACKUPS_KEPT	7	保留的每日备份数量

常见问题

我的记忆会被发送到别处吗？

不会。服务只会读写本地文件，不会发起网络请求。Web UI 仅监听 127.0.0.1。请勿将图谱提交到 git，也不要在其中存储密码、密钥或令牌：只记录机密信息存放的位置，不要记录其值。

多个 Agent 或会话可以共用一个图谱吗？

可以。每次写入都会获取锁、重新读取文件并以原子方式替换，因此并行会话（以及 Web UI）不会相互覆盖。

为什么使用纯文本搜索，而不是嵌入向量？

它无需模型、索引或依赖项，而且 Agent 的查询大多是它已经知道的名称。好的实体名称比巧妙的查询更重要。

旧事实会如何处理？

当某个实体的事实超过 15 条时，最早的有日期事实会移至图谱旁的 archive/<entity>.md。archived_observations 或 Web UI 中的 Archive 部分会列出这些事实，并可将其恢复。

路线图

• 提供服务、技能和 /memory-ui 的 Claude Code 插件
• 适用于 12 个 Agent 的设置指南
• rename_entity 和归档恢复
• 用于探索和编辑图谱的 Web UI
• 已列入官方 MCP 注册表
• 列入 Claude Code 插件目录
• 搜索所有实体的归档事实
• 在 Web UI 中撤销操作

贡献

欢迎提出想法、报告错误和提交拉取请求。服务只有一个文件且没有依赖项，Web UI 只有一个 HTML 文件，运行 npm test 只需几秒，因此很快就能完成首次修改。CONTRIBUTING.md 介绍了项目布局、基本规则和适合新手的贡献任务。

如果 memory-lean 帮你节省了令牌，点个 ⭐ 就能帮助其他人发现它。

支持

memory-lean 免费使用，并采用 MIT 许可证。如果它对你有帮助，可以支持这项工作：

作者

由 Silifton 的 Zaman Sheikh 创建并维护。

基于 Model Context Protocol 参考记忆服务 的文件格式和工具名称构建。

许可证

MIT © 2026 Zaman Sheikh。可免费使用、修改和分享，包括用于商业用途；请保留版权声明。