Cross-Agent Memory

跨 Agent 记忆

为所有 AI 编码 Agent 提供一份本地记忆。
你的 Claude Code 历史记录、Codex 会话、Cursor 工作内容、项目文档和决策—— 只需索引一次，即可供每个 Agent 搜索，且永远由你掌控。

English | 中文

🎬 ▶ 播放完整演示（2 分钟，普通话旁白）

https://github.com/user-attachments/assets/a8d5d77c-98bc-42f7-9c58-7b48295875fe

实际运行：安装 → 验证 → 存储 → 搜索。并非演示样片。点击海报即可播放 2 分钟的旁白演示。

---

问题所在

每个 AI 编码工具都从零开始。

你花一周时间使用 Claude Code 设计架构，下一周切换到 Codex，而它对你的决策及其原因一无所知。你又得粘贴上下文、重新解释项目。再用三个工具后，同样的对话已经重复了五次，却没有任何内容可供搜索。

**cross-agent-memory 解决了这个问题。**它会运行一个小型本地记忆服务，用于：

1. 摄取你在任何 AI 工具（Claude Code / Codex 风格的 CLI / OpenCode / ZCode / …）中的会话历史，以及你指定的任何项目文件夹。
2. 索引所有内容，通过本地嵌入存入一个可搜索的存储库。
3. 通过 HTTP API 或直接作为 MCP 工具，将记忆提供给每个 Agent——任何支持 MCP 的 Agent 都能回想起其他 Agent（以及你）已经发现的内容。

无需云服务，无需账户。任何内容都不会离开你的设备。

功能

• 🔒 本地优先，隐私设计为先 — 嵌入和搜索都在你的设备上运行（Ollama + SQLite + sqlite-vec）。支持飞行模式。
• 🧠 为跨工具使用而设计 — 支持 Claude Code、OpenCode 和 ZCode 会话存储的连接器，以及适用于任何项目或文档文件夹的通用文件监视器。无论内容由哪种工具生成，Agent 都共享同一份记忆。
• 🔌 一行即可集成 MCP — 通过 Model Context Protocol 提供 memory_search、memory_write 和 memory_stats。Claude Code、Codex CLI、Cursor 以及其他任何支持 MCP 的工具如今都能使用。
• ⚡ 真实规模下依然快速 — 专为大型语料库打造：使用 sqlite-vec vec0 KNN，结合 1 位粗召回预筛选和热／温／冷分层。参考部署可在 0.36–1.20 秒内搜索 2,000,000+ 个文本块（参见实测数据）。
• 🛠 包含运维功能 — 健康状态和监控端点、滚动窗口降级检测、备份与恢复、快照归档、分层维护脚本。
• 📈 经受实战检验 — 提取自一个持续运行的多 Agent 系统；其中四种不同的 AI 工具每天共享一份记忆，包含数百万个文本块，并进行每日增量索引。

架构

        Claude Code      Codex-style CLI     OpenCode / ZCode      any project
             │                  │                  │                  │
             ▼                  ▼                  ▼                  ▼
      ┌────────────────────────────────────────────────────────────────────┐
      │                         Connectors / Indexers                      │
      │   incremental watermarks · content-hash dedup · active-session     │
      │   skip · unified chunker · local embeddings (Ollama, e.g. bge-m3)  │
      └────────────────────────────────────────────────────────────────────┘
                                      │
                                      ▼
      ┌────────────────────────────────────────────────────────────────────┐
      │                      SQLite memory store (single file)             │
      │   chunks (source of truth)  ├─ vec0 KNN index (sqlite-vec)         │
      │   FTS-ready metadata        ├─ 1-bit recall codes (Hamming)        │
      │                             └─ hot / warm / cold tier tables       │
      └────────────────────────────────────────────────────────────────────┘
                                      │
                    ┌─────────────────┴───────────────────┐
                    ▼                                     ▼
        HTTP API (port 5370)                    MCP server (stdio)
        /api/search /api/memories               memory_search
        /api/stats  /api/health ...             memory_write / memory_stats
                    ▲                                     ▲
                    └─────────────────┬───────────────────┘
                                      │
                    every agent you use, in any language/tool

设计说明和完整的检索流程详见 docs/ARCHITECTURE.md。

🤖 让你的 AI Agent 来安装（一键粘贴）

最快的方式：在 AI 编码助手中打开此仓库，然后粘贴下面的代码块。 它会在本地安装所有内容——venv、依赖项和全新隔离的数据库——验证一次真实的写入/搜索往返，并报告确切的命令和结果。不会向任何地方发送数据；Agent 只会在你的机器上运行。

Install this repository locally. Read AGENTS.md and INSTALL-FOR-AI.md first.
Use ./install.sh --dry-run, then ./install.sh. Keep all runtime data isolated
from existing databases and bind only 127.0.0.1. Verify initialization twice,
Ollama bge-m3, health, and a real write/search round trip using examples/run.py.
Add the client instructions from examples/client-instructions.md. Report exact
commands, results and blockers; do not claim success from health alone.
Do not import personal projects, restore backups or change system services.

想自己动手？手动安装方式就在下方。INSTALL-FOR-AI.md 和 AGENTS.md 中也为 Agent 记录了相同的协议。

快速入门

0. 前提条件

• macOS 或 Linux（暂不支持 Windows——连接器使用 POSIX 文件锁）
• Python 3.10+
• 本地运行的 Ollama（用于生成嵌入）

ollama pull bge-m3            # ~1.2 GB, good multilingual embedding model

1. 安装

git clone https://github.com/indamices/cross-agent-memory.git
cd cross-agent-memory
python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt

2. 启动服务

python3 server.py
# Server listening on 127.0.0.1:5370

3. 添加要记住的内容

注册任意项目文件夹（文档、决策、笔记）：

curl -s -X POST http://127.0.0.1:5370/api/register \
  -H 'Content-Type: application/json' \
  -d '{"root": "/path/to/your/project"}'

文件夹需要包含 .memory-service.yaml，否则将使用合理的默认值——详见 examples/。文件会立即编入索引；之后的更改会在防抖时间窗口内批量处理（默认 1 hour，MEMSVC_WATCH_DEBOUNCE）。若要立即处理：POST /api/reindex {"project": "..."}，或使用 MEMSVC_WATCH_DEBOUNCE=0 启动。

也可以通过连接器导入 AI 工具的会话历史：

python3 connectors/index_claude_code.py     # ~/.claude/projects/**/*.jsonl
python3 connectors/index_opencode.py        # ~/.local/share/opencode/opencode.db
python3 connectors/index_zcode.py           # ~/.zcode/v2/tasks-index.sqlite

4. 随时随地搜索

curl -s -X POST http://127.0.0.1:5370/api/search \
  -H 'Content-Type: application/json' \
  -d '{"query": "why did we choose the tiered storage design", "n_results": 5}'

也可以直接写入记忆（决策、见解——非常适合 Agent 钩子）：

curl -s -X POST http://127.0.0.1:5370/api/memories \
  -H 'Content-Type: application/json' \
  -d '{"items": [{"type": "decision", "content": "We picked sqlite-vec over a server-based vector DB for local-first operation."}]}'

连接你的 Agent（MCP）

mcp_server.py 是一个零依赖的 MCP（stdio）服务，可将记忆 API 作为工具提供。将你的 Agent 指向它：

Claude Code

claude mcp add memory -- python3 /ABS/PATH/cross-agent-memory/mcp_server.py

或在 .mcp.json 中配置：

{
  "mcpServers": {
    "memory": {
      "command": "python3",
      "args": ["/ABS/PATH/cross-agent-memory/mcp_server.py"],
      "env": { "MEMORY_SERVICE_URL": "http://127.0.0.1:5370" }
    }
  }
}

Codex CLI（~/.codex/config.toml）

[mcp_servers.memory]
command = "python3"
args = ["/ABS/PATH/cross-agent-memory/mcp_server.py"]
env = { MEMORY_SERVICE_URL = "http://127.0.0.1:5370" }

Cursor / 其他 MCP Agent——在该工具的 MCP 设置中使用相同的服务命令和参数。如果你在启动服务时设置了 MEMSVC_TOKEN，也要为 MCP 服务设置 MEMORY_SERVICE_TOKEN。

连接后，你的 Agent 将获得：

工具	功能
memory_search	对所有工具的全部已编入索引的会话/项目进行语义搜索
memory_write	存储决策 / 见解 / 发现，供后续会话使用
memory_stats	列出集合及其大小

检索原理

每次 /api/search 请求都会执行分阶段的处理流程：

1. 查询嵌入——在本地计算（Ollama），并按文本哈希缓存。
2. 粗略召回——为每个区块生成每维 1 位的编码，并按汉明距离预筛选（小型集合会自动跳过）。
3. 精确 KNN——对候选列表使用 sqlite-vec vec0 进行余弦 KNN 搜索 （sqlite-vec 不可用时，则回退到 numpy 暴力搜索）。
4. 重新排序——时间衰减（半衰期 30 天）+ MMR 多样性 + 少量 helpful 反馈因子。
5. 结果——每条命中包含文本 + 来源 + 距离 + 分数。

在底层，它还会处理那些不起眼但至关重要的工作：内容哈希去重、每个连接器的增量水位线、跳过仍在写入的会话、批量写入节流、WAL 调优，以及陈旧索引的自动修复。

实测数据

来自参考部署（Mac mini M4 Pro，每周 7 天、每天 24 小时运行此服务，用于多 Agent 配置）：

指标	数值
已编入索引的区块	2,013,030，分布在 16 个集合中
共享同一记忆的工具	4 个（Claude Code、OpenCode、ZCode、OpenClaw）
抽样的 /api/search 延迟	0.36 s – 1.20 s（5 次生产环境查询，缓存已预热）
嵌入模型	bge-m3（1024 维），本地 Ollama
存储	单个 SQLite 文件 + 派生的 vec0 索引（随时可重建）

这些是来自庞大、杂乱且持续增长的语料库的真实数据——并非玩具基准测试。你的数据会因语料库规模和硬件而异；使用全新数据库时，所有操作都能在 100 ms 内完成。

API 概览

Endpoint	Method	Description
/api/ping	GET	存活状态（不访问数据库）
/api/health	GET	健康状态，包括嵌入状态、磁盘和降级原因
/api/stats	GET	集合和分块数量
/api/projects	GET	已配置的项目
/api/monitor	GET	延迟／缓存／磁盘指标
/api/search	POST	语义搜索（query、n_results?、project?）
/api/memories	POST	直接捕获记忆项
/api/feedback	POST	将分块标记为 helpful／unhelpful（会影响排序）
/api/register	POST	注册用于索引的项目目录
/api/reindex	POST	强制重新索引（单个项目或全部项目）
/api/backup / /api/restore	POST	备份／恢复数据库
/api/archive-snapshots	POST	压缩旧快照文件

包含请求／响应示例的完整参考文档：docs/API.md。

配置

所有功能均可使用默认设置；需要时可通过环境变量进行调整：

Variable	Default	Purpose
MEMSVC_PORT	5370	HTTP 端口
MEMSVC_DB	./memory.db	SQLite 数据库路径
MEMSVC_SEARCH_MODE	vec	vec（sqlite-vec）或 legacy（numpy）
MEMSVC_BIT_RECALL	on	1 位粗略召回预筛选（设为 off 可禁用）
MEMSVC_MAX_CONCURRENCY	8	HTTP 工作线程上限（超过后快速返回 503）
MEMSVC_STALL_WATCHDOG	on	搜索停滞时转储堆栈
MEMSVC_AUTH	(未设置)	设为 1 可启用 bearer-token 身份验证（写入操作需要 Authorization: Bearer <token>）
MEMSVC_API_TOKEN	(未设置)	Bearer 密钥；设置后也会启用身份验证
MEMSVC_READ_REQUIRES_TOKEN	(未设置)	设为 1 后，读取操作也需要令牌
MEMSVC_BACKUP_DIR	backups	数据库备份目录
MEMSVC_SLOW_THRESHOLD_MS	8000	健康检查的慢查询阈值
MEMORY_MISS_LEDGER	(已禁用)	零结果／低质量结果的 JSONL（回写候选项）
MEMORY_HITS_LEDGER	(已禁用)	按查询采样记录排名靠前的命中项
CLAUDE_PROJECTS_DIR	~/.claude/projects	Claude Code 连接器源
OPENCODE_DB / OPENCODE_DBS	~/.local/share/opencode/…	OpenCode 连接器源
ZCODE_DB	~/.zcode/v2/tasks-index.sqlite	ZCode 连接器源
MEMORY_SERVICE_URL	http://127.0.0.1:5370	供 MCP 服务使用
MEMORY_SERVICE_TOKEN	(未设置)	启用身份验证时使用的 Bearer 令牌

运维

• 健康状态：GET /api/health 会报告 status、磁盘使用量、嵌入可用性和降级原因（例如慢查询、磁盘压力）——专为 cron／监控抓取而设计，可避免误报。
• 备份：使用 scripts/backup_silent.py（适用于 cron）或 POST /api/backup。使用 POST /api/restore 恢复。
• 分层（可选）：scripts/migrate_to_vec0.py 会构建 vec0 索引；scripts/tier_rebuild.py 会构建 hot／warm／cold 分层表，以便在超大语料库中保持 hot 集合较小。
• 快照归档：scripts/archive_silent.py。
• 带告警的健康检查 cron：scripts/health_check.py（内置可选的飞书 webhook 支持——配置 .alert.env）。

设计选择（及非目标）

• 使用 SQLite，而非向量服务。 单个文件、无需运行任何服务、备份极其简单，并且可离线运行。vec 索引可从源数据派生并重新构建。
• 使用本地嵌入，而非 API。 保护隐私且没有边际成本；如需使用其他模型，可在 config.py 中替换。
• 文件是事实来源。 所有已索引内容都可以从源文件重新摄取；删除数据库不会丢失磁盘上已有的任何内容。
• 不是云同步产品。 这是供单台机器使用的本地服务（多个 Agent，共用一份记忆）。多用户／服务端模式已列入路线图。
• 不是向量数据库基准测试项目。 相较于原始 ANN 吞吐量，它更注重精简依赖和易于运维。

路线图

• Web 控制台（浏览／搜索／整理记忆）
• 更多连接器：Codex CLI 会话存储、Cursor、Aider、通用 JSONL
• 一流的记忆类型（事实／经验教训／代码更改上下文），以及 提取流程
• 为跨设备工作的用户提供多设备同步
• Python 包／Docker 镜像，实现一键安装

欢迎提交问题和 PR，尤其是新的连接器。请参阅 CONTRIBUTING.md。

致谢

本项目建立在优秀工具的基础之上：SQLite、 sqlite-vec、 Ollama、numpy、 watchdog。

许可证

MIT © 2026 indamices