跨智能体记忆库 Haoran656/agentmem

agentmem

为你的 AI 智能体提供全机器共享记忆。 一个只读 MCP 服务器，索引本机每个编码/聊天智能体的会话历史，让任意一个智能体都能搜索其他智能体已经做过的事——决策、修复、配置、命令参数、经验教训——可回溯、本地运行、写入时即脱敏。

你的智能体本来就会把对话写到磁盘。agentmem 读取全部内容，把六种截然不同的私有存储格式归一成一份事件索引，在提交任何一行之前先剥掉 API 密钥，再把正确的记忆交还给你正在对话的那个智能体。

deja-vu 为西方命令行智能体生态（Claude Code / Codex / Cursor……）做了这件事。
agentmem 是同一思路，面向中国桌面智能体生态（WorkBuddy / DeepSeek Harness / Kilo / OpenCode），另外还多了两样别人没有的东西：计费级 token 对账（对照服务商账单验证误差 ±0%）和审计闸门（脱敏审计不通过，服务器拒绝提供服务）。

为什么需要它

多智能体工作流会漏掉记忆。你在某个工具里修好一个棘手的 Unity NavMesh 限制，几个月后另一个工具又从零重解一遍。你在 Codex 里配好一个中继端点，然后还得再告诉 Claude Code 一遍。每个智能体都忘了其他智能体学到的东西。

agentmem 给整个智能体集群一份可搜索的记忆，且不要求任何智能体改变工作方式：

- 可回溯、零注入——不在智能体的热循环里挂钩子，不做逐轮捕获调用。它解析已有的会话文件。今天装上，上个月的历史在第一次查询时就能搜到。
- 深度解析，不是记笔记——真实的事件流（user / assistant / tool_call），智能体能还原究竟是哪条命令修好的，而不是摘要的摘要。
- 隐私优先，强制执行——写入时脱敏；每天做一次全库审计，确认零残留；审计没通过，MCP 服务器就不启动。数据永不离开你的机器。

支持的智能体

| 智能体 | 数据源（索引） | MCP 客户端（召回） |
| WorkBuddy | ✅（JSONL 转录 + credit/token） | ✅ |
| Codex | ✅（rollout JSONL） | ✅（config.toml） |
| Claude Code | ✅（~/.claude/projects JSONL） | ✅（.claude.json） |
| Kilo | ✅（SQLite kilo.db） | ✅（kilo.json） |
| OpenCode | ✅（SQLite opencode.db） | ✅（opencode.json） |
| DeepSeek Harness | ✅（zstd 事件流） | ✅（dsh-mcp-client 补丁） |
| Claude Desktop | ❌ 无本地转录（云端） | ✅ 基于配置 |
| 其他任何来源 | 放入一个 parsers/<app>.py（见下文） | ✅ |

新增一个来源只需一个文件：复制 parsers/_template.py，把它的记录映射到 SessionBundle，完事——流水线发现、脱敏、审计、FTS 和 MCP 服务器都会自动接上，无需改动核心代码。

快速开始

pip install -r requirements.txt # only zstandard (optional, for DeepSeek Harness)
python agentmem.py detect # what agents/clients are on this machine?
python agentmem.py init --agents workbuddy,codex,claude,kilo,opencode,dsh
python agentmem.py connect --all # diff shown first; --yes writes after backup

restart your agents → they can now search each other's history via the agentmem tools

connect 遵循严格策略：先打印将要添加的确切条目，备份配置，然后只合并自己的 key —— 绝不碰你其他的 MCP 服务器。

工作原理

6 agents' private stores ──► parsers/.py ──► sanitize ──► agentmem.db
(JSONL / SQLite / zstd) (pluggable) (keys out) (sessions/events/usage
+ trigram FTS index)
│
MCP stdio server (read-only, gated) ◄───────┘
search_events / get_session / timeline /
find_sessions / activity_stats

- 渐进式披露 —— search_events 默认返回轻量的会话卡片（detail=index），按需展开为片段（context）或完整行（full），这样召回不会撑爆你的上下文窗口。
- 洞察层 —— 除了原始对话记录，智能体还可以沉淀提炼后的 decision / fact / artifact / lesson 行，并附带指回源会话的指针，于是「我们当时决定了什么？」成为一等公民的答案。
- 惰性新鲜度 —— 每次查询都会在子进程中触发一次限流（约 45 秒）的增量重新同步，所以刚结束的对话已经可搜索。服务器本身始终保持物理只读（PRAGMA query_only）。

工具（MCP）

| 工具 | 作用 |
| search_events | 对所有智能体的历史做全文（CJK + 子串）搜索，支持过滤 |
| get_session | 展开单个会话的事件流（分页，可按角色过滤） |
| timeline | 以某个锚点为中心的会话 —— 「那时我还在做什么？」 |
| find_sessions | 按项目/智能体/模型/日期列出会话（项目别名会展开） |
| activity_stats | 近期活动汇总 |

安全模型

- 物理只读。 MCP 服务器以 mode=ro + query_only 打开数据库；写入尝试会报错。同步在单独的子进程中完成。
- 启动门禁。 如果 audit_secrets.py 最近没有通过，服务器会以退出码 2 退出，而不是继续提供服务。未经审计的数据永远不会从这扇门流出。
- 输出有界。 片段有硬性上限；没有 SELECT 这种逃生通道。
- 写入时脱敏。 API key / bearer token / AK-secret 对 / data-URL 在行提交前就被替换；每日审计会重新扫描整个数据库，发现问题就大声报错。
- 仅本地。 无网络、无遥测、无云端。

仓库结构

agentmem.py unified CLI (detect/init/sync/status/search/serve/connect)
core.py pipeline.py session-level idempotent writer + orchestrator (plugin discovery)
parsers/*.py one per agent source (_template.py = copy to add one)
sanitize.py audit_secrets.py write-time redaction + full-DB gate
agentmem_db.py querylib.py 表结构（+FTS/trigram/insights/projects）+ 共享搜索 mcp_agentmem.py MCP stdio 服务器（只读） connect.py prescan.py 可选客户端接入（diff+backup+merge）+ 发布隐私门禁 dashboard.py hook_session_start.py 静态仪表盘 + 自动注入召回

agentmem.db、dashboard.html、备份和 agentmem.config.json 都在 gitignore 里—— 你的真实历史永远不会进入仓库。

基准测试

recall_eval.py 直接从你自己的语料生成自测：它从会话文本里提取有辨识度的短语（unique 档 = 短语只出现在一个会话里；ambiguous 档 = 出现在 2–3 个会话里），然后测量目标会话在 MCP 服务器所用的同一条 detail=index 结果路径里排到第几位。
一条命令就能在你机器上完整复现；问题来自私有数据，所以只有汇总数字可以公开——问题转储在 gitignore 里。

作者语料上的结果（6 个智能体、156 个会话 / 29,488 个事件，144 道自动生成的问题）：

| 档位 | hit@1 | hit@3 | recall@20 | MRR |
| unique（找出那一个会话） | 100% | 100% | 100% | 1.00 |
| ambiguous（正确的那条排第一） | 66.7% | 100% | 100% | 0.83 |
| 总体 | 83.3% | 100% | 100% | 0.91 |

查询延迟：中位数 0.1 ms，p95 1.3 ms。

python recall_eval.py --run --n 20 # your numbers on your corpus

局限 / 实话实说

- Windows 优先（处理了路径和几个中文 Windows 的 stdio 怪癖）。macOS/Linux 的检测目前只有接口。
- DeepSeek Harness 需要 zstandard；没有就跳过这个来源，其他来源照常。
- Claude Desktop 和云端聊天应用（比如豆包）没有本地对话记录：它们可以当召回客户端，但不能当索引来源。
- 这是个人规模的工具（几万个事件 → 毫秒级查询）；要是历史有 GB 级，就得走向量索引那条路，目前留作有文档的下一步。

许可证

MIT。