给 Codex 装上长期记忆:ai-memory 从零到可用完整实战
每次换会话、换机器,AI 编码助手就会「失忆」——架构讲过、坑踩过、决策做过,下次还得再解释一遍。
ai-memory 正是为解决这个问题而生:用一套可 Git 追踪的 Markdown 知识库,给 Claude Code、Codex、Cursor 等编码 Agent 提供跨会话、跨机器的长期记忆。
本文记录一次完整落地过程:服务端用 1Panel + Docker 部署,本地 macOS 对接 Codex,并用 AIGoCode 提供 LLM 整理能力。
一、ai-memory 能做什么
核心能力可以概括为四步:
- 捕获:通过生命周期 hooks 记录提示词、工具调用、会话边界
- 整理:会话结束后把观察写成可读的 Markdown 页面
- 召回:下次会话拿到简报,并能搜索全文、实体、链接
- 交接:同一项目在不同 Agent / 机器之间无缝续上
默认零 LLM 也能工作(捕获、搜索、交接都可用)。开启 LLM 后,会多出结构化整理、自动改进、矛盾检测等能力,记忆从「流水账」变成「可复用的项目知识库」。
架构上支持「一台中心服务 + 多台本地客户端」,适合个人多机或小团队共享记忆。
二、服务端:1Panel + Docker
1. docker-compose.yml 示例
services:
ai-memory:
image: akitaonrails/ai-memory:3.0.0
container_name: ai-memory
restart: unless-stopped
user: "1000:1000"
ports:
- "127.0.0.1:49374:49374"
volumes:
- ./data:/data
environment:
AI_MEMORY_AUTH_TOKEN: "你的强随机Token"
AI_MEMORY_ALLOWED_HOSTS: "你的服务器IP,你的域名,localhost,127.0.0.1"
# 使用 AIGoCode(OpenAI 兼容)
AI_MEMORY_LLM_PROVIDER: openai-compat
AI_MEMORY_LLM_BASE_URL: "服务商提供的 base_url"
AI_MEMORY_LLM_MODEL: gpt-6.1-sol
LLM_API_KEY: "sk-你的AIGoCode_Key"
healthcheck:
test: ["CMD", "curl", "-f", "http://127.0.0.1:49374/healthz"]
interval: 30s
timeout: 5s
retries: 3
start_period: 15s
生成 Token:
docker run --rm akitaonrails/ai-memory:latest generate-auth-token
2. 数据目录权限(最常见坑)
镜像以 UID 1000 运行。若数据目录属主是 root,会出现:
Error: opening serve lock /data/.serve.lock
Permission denied (os error 13)
处理:
mkdir -p ./data
sudo chown -R 1000:1000 ./data
sudo chmod -R 775 ./data
docker compose up -d
用命名卷时,先 docker volume inspect 找到 Mountpoint,再对实际路径做同样的 chown 1000:1000。
3. LLM 选哪个模型?
开启 LLM 主要用于会话结束后的结构化整理(决策、踩坑、流程拆页),不是最重推理任务。
| 场景 | 建议 |
|---|---|
| 日常推荐 | gpt-6-sol / gpt-6.1-sol(若通道支持) |
| 更省钱 | gpt-5.6-luna 等小模型 |
| 一般不必 | 旗舰 Astra 级(性价比偏低) |
走 AIGoCode 时,Provider 必须写 openai-compat,Key 环境变量名是 LLM_API_KEY。
三、macOS 本地安装
1. 安装 ai-memory CLI
官方一键脚本:
curl -fsSL https://github.com/akitaonrails/ai-memory/releases/latest/download/install.sh | sh
若遇到 ~/.local 权限问题:
mkdir -p ~/.local/bin ~/.local/lib
sudo chown -R $(whoami) ~/.local
chmod -R u+rwX ~/.local
然后把 PATH 写进 shell:
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
ai-memory --version
2. 安装 Codex CLI
装了 ChatGPT 桌面版 ≠ 有 codex 命令。需要单独装 CLI:
curl -fsSL https://chatgpt.com/codex/install.sh | sh
验证:
which codex
codex --version
3. 对接远程服务端 + 安装 hooks
本地指向服务端(按你的实际域名/Token 修改):
export AI_MEMORY_SERVER_URL="https://aimem.example.com"
export AI_MEMORY_AUTH_TOKEN="你的Token"
安装 MCP 与 hooks:
ai-memory install-mcp --client codex --apply
ai-memory install-hooks --agent codex --apply
成功时大致会看到:
- 更新了
~/.codex/config.toml - 生成了 hooks 脚本与
~/.codex/hooks.json
首次启动 Codex 时,若提示 Hooks need review,选择 Trust all and continue。
四、如何确认「记忆真的生效」
配置通了只说明链路就绪;要证明有效,必须走完整闭环:
捕获 → 写入服务端 → 下次能召回
步骤
- 进入真实项目目录,启动 Codex,信任 hooks
- 故意写入可验证信息,例如:
请记住:这个项目数据库是 PostgreSQL,部署端口 8080。
或埋一个暗号:验证码是 BLUE-42 - 正常退出(不要强杀)
- 执行
ai-memory status,观察:sessions/observations是否从 0 增加ingest accepted、last write是否有更新
- 打开服务端网页,确认出现对应 session 页面
- 新开一次同项目 Codex,直接问:
我们上次说这个项目用什么数据库?端口是多少?
或上次的验证暗号是什么?
能准确答出 → 记忆链路真正生效。
数字一直为 0 → 优先检查 hooks 是否信任、项目路径是否一致、Token/ALLOWED_HOSTS 是否匹配。
辅助命令:
ai-memory status
ai-memory doctor
ls ~/.codex/hooks.json
五、实践中踩过的坑速查
| 现象 | 原因 | 处理 |
|---|---|---|
/data/.serve.lock Permission denied |
数据目录属主不是 1000 | chown -R 1000:1000 数据目录 |
mkdir: ~/.local/... Permission denied |
macOS 目录属主/权限异常 | chown + mkdir -p 后重装 |
zsh: command not found: codex |
只装了 ChatGPT App | 安装 Codex CLI |
managed codex executable not found |
PATH 里没有 codex | 同上,并确认 ~/.local/bin 在 PATH |
| status 里 sessions 一直为 0 | hooks 未信任或未触发 | 启动时 Trust all;正常结束会话 |
六、小结
- 服务端:Docker 部署,注意 UID 1000 权限;按需开启 LLM 做知识整理
- 客户端:macOS 装好 ai-memory + Codex CLI,用
install-mcp/install-hooks对接远程 - 验证:埋暗号 → 退出看 status → 再开会话能否答对,才是「真正生效」的标准
搭好之后,换机器、换 Agent 打开同一项目,不必再从「这个项目是干嘛的」讲起。对长期维护的代码库,这点连续性往往比再多一个模型更有用。