目录

给 Codex 装上长期记忆:ai-memory 从零到可用完整实战

每次换会话、换机器,AI 编码助手就会「失忆」——架构讲过、坑踩过、决策做过,下次还得再解释一遍。
ai-memory 正是为解决这个问题而生:用一套可 Git 追踪的 Markdown 知识库,给 Claude Code、Codex、Cursor 等编码 Agent 提供跨会话、跨机器的长期记忆。

本文记录一次完整落地过程:服务端用 1Panel + Docker 部署,本地 macOS 对接 Codex,并用 AIGoCode 提供 LLM 整理能力。


核心能力可以概括为四步:

  1. 捕获:通过生命周期 hooks 记录提示词、工具调用、会话边界
  2. 整理:会话结束后把观察写成可读的 Markdown 页面
  3. 召回:下次会话拿到简报,并能搜索全文、实体、链接
  4. 交接:同一项目在不同 Agent / 机器之间无缝续上

默认零 LLM 也能工作(捕获、搜索、交接都可用)。开启 LLM 后,会多出结构化整理、自动改进、矛盾检测等能力,记忆从「流水账」变成「可复用的项目知识库」。

架构上支持「一台中心服务 + 多台本地客户端」,适合个人多机或小团队共享记忆。


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

镜像以 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。

开启 LLM 主要用于会话结束后的结构化整理(决策、踩坑、流程拆页),不是最重推理任务。

场景 建议
日常推荐 gpt-6-sol / gpt-6.1-sol(若通道支持)
更省钱 gpt-5.6-luna 等小模型
一般不必 旗舰 Astra 级(性价比偏低)

走 AIGoCode 时,Provider 必须写 openai-compat,Key 环境变量名是 LLM_API_KEY。


官方一键脚本:

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

装了 ChatGPT 桌面版 ≠ 有 codex 命令。需要单独装 CLI:

curl -fsSL https://chatgpt.com/codex/install.sh | sh

验证:

which codex
codex --version

本地指向服务端(按你的实际域名/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。


配置通了只说明链路就绪;要证明有效,必须走完整闭环:

捕获 → 写入服务端 → 下次能召回

  1. 进入真实项目目录,启动 Codex,信任 hooks
  2. 故意写入可验证信息,例如:
    请记住:这个项目数据库是 PostgreSQL,部署端口 8080。
    或埋一个暗号:验证码是 BLUE-42
  3. 正常退出(不要强杀)
  4. 执行 ai-memory status,观察:
    • sessions / observations 是否从 0 增加
    • ingest accepted、last write 是否有更新
  5. 打开服务端网页,确认出现对应 session 页面
  6. 新开一次同项目 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 打开同一项目,不必再从「这个项目是干嘛的」讲起。对长期维护的代码库,这点连续性往往比再多一个模型更有用。