ai-memory：让 Claude Code、Codex、Cursor 共用项目记忆

在 Claude Code、Codex、Cursor 之间切换时，最麻烦的往往不是代码本身，而是“为什么这么改、试过什么、下一步做什么”这些上下文。ai-memory 提供一套独立的共享记忆服务，把项目记忆保存成 Git 管理的 Markdown Wiki，让不同编程助手可以围绕同一项目继续工作。

先理解它的定位

ai-memory 负责保存和检索“项目记忆”，例如架构结论、排错过程、失败尝试和待办。它不会帮你同步代码、依赖或运行环境，这些仍然要依靠 Git、镜像、文件同步或自己的开发环境。

为什么需要跨 Agent 的共享记忆

实际开发中，经常会出现这样的流程：

1. 先用 Claude Code 开发一段时间
2. 遇到额度、上下文或排查瓶颈
3. 切到 Codex 或 Cursor 继续
4. 新客户端重新读取仓库
5. 又要把之前的架构决策、失败方案和剩余任务解释一遍

真正容易丢失的通常包括：

• 项目架构结论
• 已经尝试过但失败的方法
• 某个报错排查到了哪一步
• 为什么选择当前实现
• 还有哪些待办没有完成

ai-memory 的仓库是：

akitaonrails/ai-memory

它在各个编程助手之外运行一套共享记忆服务，大致流程是：

1. 通过 Hooks 记录提示、工具调用和会话边界
2. 把有价值的信息整理成 Git 管理的 Markdown Wiki
3. 使用 SQLite 保存全文和实体索引
4. 新的 Agent 在同一项目中查询这些记忆
5. 通过 Handoff 等机制继续上一次工作

Markdown Wiki 是事实来源，因此即使索引损坏，也可以从文件重新构建。

和 CLAUDE.md、Cursor Rules 有什么区别

很多开发工具本身已经提供项目规则或记忆文件。

它们和 ai-memory 的定位并不完全一样。

如果长期只使用一种工具，原生规则和记忆通常已经够用。

如果经常在 Claude Code、Codex、Cursor 或多台机器之间切换，共享记忆服务会更有价值。

从 Claude Code 切到 Codex，能交接什么

要实现真正的交接，两边需要连接到：

• 同一套 ai-memory
• 同一个项目

同一台机器、同一个目录

这种情况最简单。

新的 Agent 可以直接读取当前工作区，包括：

• 已提交代码
• 未提交修改
• 配置文件
• 当前 Git 状态

ai-memory 主要补充代码里看不到的上下文：

• 为什么这样设计
• 哪些方案已经失败
• 排错做到哪里
• 下一步准备做什么

不同机器

跨机器时，记忆服务可以放在 Homelab 或 VPS 上集中共享。

但需要注意：

ai-memory 共享的是记忆，不会自动同步工作区代码。

因此还需要另外同步：

• Git commit / branch
• 未提交修改
• 环境变量
• 本地依赖
• 容器和运行环境

如果一台机器上存在没有 push 的代码改动，仅靠共享记忆无法让另一台机器获得这些代码。

Handoff 是什么

Handoff 可以理解成一次会话交接摘要。

它适合记录：

• 当前任务是什么
• 已经完成了什么
• 哪些问题还没解决
• 下一步应该从哪里继续

这样切换到另一个 Agent 后，不需要重新翻完整聊天记录。

managed workstreams 等能力属于进一步增强，但不会把旧客户端的完整运行状态原样复制到另一个客户端。

Codex 一侧如果缺少自动“会话结束”Hook，需要生成最终 Handoff 时，可以按照当前项目文档执行对应的 finalize 命令。

具体命令名称请以当前 CLI 帮助为准。

支持哪些客户端

公开支持矩阵覆盖多种 Agent。

常见客户端包括：

实际支持情况请查看仓库 README 或 Support Matrix。

是否一定要接外部 LLM

不一定。

ai-memory 的基础能力可以在不配置云端 LLM 的情况下使用。

基础模式通常可以提供：

• Markdown Wiki
• SQLite
• 全文搜索
• 实体索引
• 基于规则的摘要
• 基础 Handoff

全新安装时，如果没有指定 embedding provider，项目可能尝试使用本地小型 embedding 模型。

如果本地 embedding 无法使用，也可以退回全文检索。

什么时候需要额外模型

如果希望模型参与：

• 记忆整理
• 摘要
• embedding
• 语义检索

可以进一步配置：

• Anthropic
• OpenAI
• Voyage
• Gemini
• Ollama
• LM Studio
• 其他兼容端点

隐私需要注意什么

“自托管”不代表所有数据一定完全不出网。

如果启用了云端摘要或 embedding：

• 相关内容会发送给对应服务商

即使 ai-memory 本身完全本地：

• Claude Code
• Codex
• Cursor

这些 Agent 自己在调用模型时，也仍可能把项目上下文发送给各自的模型服务。

所以使用前要分别考虑：

1. ai-memory 数据保存在哪里
2. embedding / summary 用的是什么 Provider
3. 编程助手本身会把哪些代码上下文发送给模型

Docker 快速开始

环境要求：

• Docker 或 Podman
• 至少一个受支持的 Agent CLI

1. 安装 CLI 包装脚本

下面示例会下载最新 wrapper，并先校验 SHA256：

mkdir -p ~/.local/bin
wrapper_tmp="$(mktemp -d)"
trap 'rm -rf "$wrapper_tmp"' EXIT

wrapper_base=https://github.com/akitaonrails/ai-memory/releases/latest/download/ai-memory-wrapper

curl -fsSL "$wrapper_base"   -o "$wrapper_tmp/ai-memory-wrapper"

curl -fsSL "$wrapper_base.sha256"   -o "$wrapper_tmp/ai-memory-wrapper.sha256"

expected="$(awk 'NR == 1 { print $1 }'   "$wrapper_tmp/ai-memory-wrapper.sha256")"

if command -v sha256sum >/dev/null 2>&1; then
  actual="$(sha256sum "$wrapper_tmp/ai-memory-wrapper" | awk '{ print $1 }')"
else
  actual="$(shasum -a 256 "$wrapper_tmp/ai-memory-wrapper" | awk '{ print $1 }')"
fi

[ -n "$expected" ] && [ "$actual" = "$expected" ] || {
  echo "wrapper checksum mismatch" >&2
  exit 1
}

install -m 0755   "$wrapper_tmp/ai-memory-wrapper"   ~/.local/bin/ai-memory

rm -rf "$wrapper_tmp"
trap - EXIT

安装完成后检查：

which ai-memory

如果找不到命令，需要把：

~/.local/bin

加入 PATH。

启动 ai-memory 服务

如果只是本机使用，默认建议只绑定回环地址。

下面示例同时配置了外部 LLM 和 embedding Provider：

docker run -d   --name ai-memory   --restart unless-stopped   -p 127.0.0.1:49374:49374   -v ai-memory-data:/data   -e AI_MEMORY_LLM_PROVIDER=anthropic   -e ANTHROPIC_API_KEY=sk-ant-...   -e AI_MEMORY_EMBEDDING_PROVIDER=openai   -e OPENAI_API_KEY=sk-...   docker.io/akitaonrails/ai-memory:latest

如果只想使用本地 Wiki 和全文检索，可以按照项目文档去掉 Provider 和 API Key 相关环境变量。

本机快速开始时，如果服务只绑定：

127.0.0.1:49374

通常可以先不启用额外鉴权。

如果要开放到局域网或公网，安全要求会完全不同。

接入 Claude Code

服务启动后，可以安装 MCP 和 Hooks：

ai-memory install-mcp   --client claude-code   --apply

ai-memory install-hooks   --agent claude-code   --apply

完成后，Claude Code 就可以连接到这套共享记忆服务。

接入 Codex 或 Cursor

切换其他 Agent 时，基本思路相同。

把：

--client claude-code
--agent claude-code

替换成目标客户端对应的值。

具体名称请以：

ai-memory --help

和项目当前文档为准。

项目还提供可选的托管工作流入口，例如：

ai-memory run claude
ai-memory run codex
ai-memory continue

这些命令更适合希望统一管理会话交接的场景。

如何卸载

如果以后不再使用：

ai-memory uninstall --apply

该命令用于清理 ai-memory 自己安装的配置。

执行前仍建议查看当前版本帮助，确认具体影响范围。

局域网或多机部署

如果你有 NAS、Homelab 或服务器，可以把 ai-memory 服务集中部署，然后让多台开发机器连接同一实例。

典型结构：

MacBook / Claude Code
        │
MacBook / Codex
        │
Windows / Cursor
        │
        ▼
Homelab / ai-memory
        │
        ├── Markdown Wiki
        └── SQLite Index

服务端一般需要考虑：

• 监听 0.0.0.0:49374
• 配置认证 Token
• 限制允许访问的 Host
• 使用 HTTPS
• 定期备份数据

可以通过 Caddy、Nginx 或 Cloudflare Tunnel 等方式提供 HTTPS。

具体环境变量名称请以项目当前部署文档为准。

客户端连接远程实例

客户端可以配置服务地址和 Token，例如：

export AI_MEMORY_SERVER_URL="http://<服务器IP>:49374"
export AI_MEMORY_AUTH_TOKEN="$TOKEN"

ai-memory install-mcp   --client claude-code   --apply

ai-memory install-hooks   --agent claude-code   --apply

如果通过公网或不可信网络访问，应把地址改成 HTTPS。

Bearer Token 只能解决身份验证，不提供传输加密。

所以公网使用时仍然应该配置 HTTPS。

多用户使用时需要注意

项目支持多用户认证与审计能力。

但从数据架构角度看，它仍更接近单租户共享记忆服务。

因此比较适合：

• 个人
• 家庭实验室
• 小团队
• 彼此信任的协作环境

不建议直接把它当成面向互不信任用户的公共知识库。

哪些人比较适合 ai-memory

比较适合：

• 经常在 Claude Code、Codex、Cursor 之间切换
• 多台电脑或多套开发环境
• 经常需要重复解释项目背景
• 想长期保存架构决策和排错记录
• 希望记忆本身是可读的 Markdown
• 希望把记忆纳入 Git 管理
• 可以自己维护认证、备份和服务

哪些情况不一定需要

如果符合下面情况，可能暂时没有必要额外部署：

• 长期只使用一种 Agent
• 原生项目规则已经够用
• 很少跨会话工作
• 很少跨电脑开发
• 不希望再维护一套服务

还有一种情况尤其需要区分：

如果真正的问题是“代码没有同步”，ai-memory 并不能解决。

代码同步仍然应该依靠 Git、文件同步、远程开发环境或其他工具。

怎么判断它值不值得部署

可以回想最近几次切换开发工具时，有没有频繁出现这些情况：

• 又要解释一次架构
• 又要说明某个方案已经试过
• 又要告诉新 Agent 当前报错排查到哪里
• 又要重新整理下一步任务

如果这种重复解释经常发生，ai-memory 才可能真正节省时间。

如果几乎没有这些问题，增加一套记忆服务反而会增加维护成本。

项目资源

服务启动并安装好 MCP / Hooks 后，可以先做一个非常简单的测试：

1. 用 Claude Code 在项目里完成一个小改动
2. 正常结束会话并生成 Handoff
3. 打开 Codex
4. 询问“上次做到哪里，还有哪些事情没完成”

如果 Codex 能正确回答关键背景，说明共享记忆链路已经正常工作。