codex-mem

Codex CLI 的跨会话持久记忆插件，基于 claude-mem Worker API，与 Claude Code 双向共享记忆。

为什么需要这个

Codex CLI 的会话是无状态的 —— 每次开新对话，之前所有的上下文都丢了。codex-mem 解决这个问题：

• 自动记录你每个会话里做的每一件事
• 新会话开始时自动注入相关的历史上下文
• 随时搜索所有过去的工作记录

记忆存储在本地 ~/.claude-mem/claude-mem.db（SQLite），与 Claude Code 双向共享 —— Codex 里记录的内容在 Claude Code 里能搜到，反过来也一样。

功能一览

架构

┌─────────────────────────────────────────────────────────┐
│                      Codex CLI                          │
│                                                         │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐   │
│  │ SessionStart │  │ PostToolUse  │  │  MCP Bridge  │   │
│  │    Hook      │  │    Hook      │  │  (9 tools)   │   │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘   │
│         │                 │                 │           │
│         │  HTTP POST      │  HTTP POST      │  HTTP     │
│         │  /sessions/init │  /sessions/     │  GET/POST │
│         │                 │  observations   │           │
└─────────┼─────────────────┼─────────────────┼───────────┘
          │                 │                 │
          ▼                 ▼                 ▼
┌─────────────────────────────────────────────────────────┐
│        claude-mem Worker API (localhost:37777)          │
│        Managed by Claude Code's claude-mem plugin       │
├─────────────────────────────────────────────────────────┤
│  ~/.claude-mem/claude-mem.db (SQLite)                   │
│  Observations / Sessions / Summaries / Prompts          │
│  <-- Shared with Claude Code sessions -->               │
└─────────────────────────────────────────────────────────┘

数据流

1. 会话开始 —— SessionStart hook 触发时：

   • 检测 Worker API 是否在运行（Windows 上会做端口绑定探测）
   • 如果需要，尝试一次冷启动（smart-install → bun-runner → worker-service）
   • 调用 POST /api/sessions/init 创建会话
   • 调用 GET /api/context/inject 获取相关历史记忆
   • 通过 additional_context JSON 输出注入到 Codex 上下文

2. 用户提问 —— 每次用户发送 prompt 时，模型会：

   • 在回复开头用 heredoc + node 将原始 prompt 记录为 observation（保留原文语言）
   • 每 3-5 轮 prompt 后额外生成一条英文摘要，提升跨语言搜索命中率

3. 工作过程中 —— 每次工具调用后，PostToolUse hook：

   • 从 stdin 读取工具执行数据
   • 调用 POST /api/sessions/observations 记录观察
   • 异步执行，不阻塞 Codex

4. 搜索 / 保存 —— 需要查找过去的工作时：

   • 模型使用 mem_search MCP 工具 → mcp-bridge.mjs → Worker API
   • 如果 MCP 被 Codex 审批设置拦截，降级使用 curl / PowerShell 直接调 API

前置条件

安装

1. 克隆仓库

git clone https://github.com/PapainTea/codex-mem.git
cd codex-mem

2. 安装依赖

npm install

3. 部署到 Codex 插件目录

Linux / macOS：

mkdir -p ~/.codex/.tmp/plugins/plugins/claude-mem
cp -r .codex-plugin hooks scripts skills package.json package-lock.json \
  ~/.codex/.tmp/plugins/plugins/claude-mem/
cd ~/.codex/.tmp/plugins/plugins/claude-mem && npm install --production

Windows（Git Bash）：

mkdir -p "$HOME/.codex/.tmp/plugins/plugins/claude-mem"
cp -r .codex-plugin hooks scripts skills package.json package-lock.json \
  "$HOME/.codex/.tmp/plugins/plugins/claude-mem/"
cd "$HOME/.codex/.tmp/plugins/plugins/claude-mem" && npm install --production

4. 注册 MCP 服务

codex mcp add claude-mem -- node "$HOME/.codex/.tmp/plugins/plugins/claude-mem/scripts/mcp-bridge.mjs"

5. 启用 hooks（实验性功能）

codex features enable codex_hooks

6. 验证

重启 Codex，启动时应该看到：

Loaded: 1 plugin · skills · hooks · 1 MCP server

Windows 安全策略

在 Windows 上，Bun（claude-mem Worker 的运行时）存在已知的 TCP socket 泄漏问题：进程被杀后内核可能不释放端口，导致 EADDRINUSE，只有重启电脑才能恢复。

本插件实现了**失败即停止（fail-closed）**策略，避免雪上加霜：

端口探测使用 Node.js net.createServer() 测试端口是否真正可绑定，能检测到 netstat 可能遗漏的幽灵 socket。

搜索记忆

通过 MCP 工具（首选）

mem_search({ query: "认证中间件重构", limit: 20 })
mem_timeline({ query: "数据库迁移", depth_before: 10, depth_after: 10 })
mem_get_observations({ ids: [123, 456] })

通过 Direct API（MCP 被拦截时的降级方案）

curl（Git Bash）：

curl -s -G "http://127.0.0.1:37777/api/search" \
  --data-urlencode "query=认证中间件" \
  --data-urlencode "limit=20"

PowerShell：

$q = [uri]::EscapeDataString("认证中间件")
Invoke-RestMethod "http://127.0.0.1:37777/api/search?query=$q&limit=20"

完整的 API 端点和示例见 SKILL.md。

文件结构

codex-mem/
├── .codex-plugin/
│   └── plugin.json           # 插件清单 —— 声明 hooks + skills
├── hooks/
│   ├── hooks.json            # Hook 定义（SessionStart + PostToolUse）
│   ├── session-start         # 初始化会话、冷启动 Worker、注入上下文
│   ├── post-tool-use         # 自动捕获工具调用观察记录
│   └── run-hook.cmd          # Windows polyglot wrapper（查找 Git Bash）
├── scripts/
│   ├── mcp-bridge.mjs        # MCP 服务 —— 9 个记忆工具，通过 stdio 通信
│   └── mcp-bridge.cmd        # Windows batch 启动器
├── skills/
│   └── claude-mem/
│       ├── SKILL.md          # 模型指令（prompt 记录、搜索、保存、降级方案）
│       └── agents/openai.yaml # MCP 工具声明
├── package.json              # 依赖（@modelcontextprotocol/sdk）
├── LICENSE                   # MIT
├── README.md                 # 本文件
└── README_EN.md              # English version

MCP 工具参考

自动？ = hooks 是否自动处理。标记"是"的工具仍然可以手动使用，但你不需要主动调用 —— hooks 会帮你做。

常见问题

已知限制

• 依赖 Worker —— 需要 claude-mem Worker API 在 localhost:37777 运行。没有它，所有记忆操作会优雅失败但不会记录数据。
• 退出时无自动摘要 —— Codex 的 Stop hook 支持尚未验证；会话可能不会生成 AI 摘要。如需要请手动调用 mem_session_end。
• PostToolUse 静默丢失 —— 如果 Worker 在会话中途崩溃，观察记录会静默丢失（不重试）。
• Windows Bun socket 泄漏 —— 如果 Worker 进入僵死状态，只有重启电脑才能释放被锁定的端口。
• codex_hooks 是实验性功能 —— hook 行为可能随 Codex 版本变化。

致谢

• claude-mem by Alex Newman —— Worker API 和记忆引擎
• Codex CLI by OpenAI —— 宿主 CLI
• Model Context Protocol SDK —— MCP bridge 实现

许可证

MIT