Codex Mem
No description available
Ask AI about Codex Mem
Powered by Claude · Grounded in docs
I know everything about Codex Mem. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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 里能搜到,反过来也一样。
功能一览
| 功能 | 实现方式 |
|---|---|
| 自动记录工具调用 | PostToolUse hook 自动捕获每次工具执行 |
| 自动注入历史上下文 | SessionStart hook 在启动时加载相关记忆 |
| 记录用户 prompt | 每次回复前记录原始 prompt(保留原文语言) |
| 定期英文摘要 | 每 3-5 轮 prompt 生成英文总结,提升跨语言搜索命中率 |
| 跨平台搜索 | 9 个 MCP 工具 + curl / PowerShell 降级方案 |
| 跨工具记忆共享 | 与 Claude Code 的 claude-mem 共用同一个 SQLite 数据库 |
| Windows 安全冷启动 | 端口探测 + 单次启动 + 失败即停止 |
| 无需手动管理生命周期 | hooks 自动处理 session 初始化和观察记录 |
架构
┌─────────────────────────────────────────────────────────┐
│ 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 --> │
└─────────────────────────────────────────────────────────┘
数据流
-
会话开始 —— SessionStart hook 触发时:
- 检测 Worker API 是否在运行(Windows 上会做端口绑定探测)
- 如果需要,尝试一次冷启动(smart-install → bun-runner → worker-service)
- 调用
POST /api/sessions/init创建会话 - 调用
GET /api/context/inject获取相关历史记忆 - 通过
additional_contextJSON 输出注入到 Codex 上下文
-
用户提问 —— 每次用户发送 prompt 时,模型会:
- 在回复开头用 heredoc + node 将原始 prompt 记录为 observation(保留原文语言)
- 每 3-5 轮 prompt 后额外生成一条英文摘要,提升跨语言搜索命中率
-
工作过程中 —— 每次工具调用后,PostToolUse hook:
- 从 stdin 读取工具执行数据
- 调用
POST /api/sessions/observations记录观察 - 异步执行,不阻塞 Codex
-
搜索 / 保存 —— 需要查找过去的工作时:
- 模型使用
mem_searchMCP 工具 → mcp-bridge.mjs → Worker API - 如果 MCP 被 Codex 审批设置拦截,降级使用 curl / PowerShell 直接调 API
- 模型使用
前置条件
| 依赖 | 说明 |
|---|---|
| Codex CLI | 本插件扩展的宿主 CLI |
| Claude Code + claude-mem | 提供 Worker API 和 SQLite 数据库 |
| Node.js >= 18 | 运行 MCP bridge 和 hook 辅助脚本 |
| Git Bash(仅 Windows) | hooks 是 bash 脚本;run-hook.cmd 会自动查找 Git Bash |
安装
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)**策略,避免雪上加霜:
| 场景 | 行为 |
|---|---|
| Worker 运行中且健康 | 直接使用 |
| Worker 未运行 + 端口空闲 | 尝试一次冷启动 |
| Worker 未运行 + 端口被占 | 什么都不做 —— 输出 {},静默跳过 |
| 冷启动超时 | 什么都不做 —— 不重试,不循环 |
| MCP 工具失败 | 返回清晰错误信息,建议使用 Direct API 降级方案 |
端口探测使用 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 工具参考
| 工具 | 描述 | 自动? |
|---|---|---|
mem_session_start | 初始化记忆会话 | 是(hook) |
mem_post_tool_use | 记录工具使用观察 | 是(hook) |
mem_session_end | 结束会话,触发摘要生成 | 否(可选) |
mem_search | 全文搜索所有记忆 | 否(手动) |
mem_timeline | 查看某个事件前后的时间线 | 否(手动) |
mem_get_observations | 按 ID 获取观察记录详情 | 否(手动) |
mem_save | 手动保存笔记或决策 | 否(手动) |
mem_context | 获取项目的近期上下文 | 否(手动) |
mem_stats | 数据库统计(大小、数量、运行时间) | 否(手动) |
自动? = hooks 是否自动处理。标记"是"的工具仍然可以手动使用,但你不需要主动调用 —— hooks 会帮你做。
常见问题
| 问题 | 原因 | 解决方案 |
|---|---|---|
| MCP 工具返回 "Worker unavailable" | Worker API 没有运行 | 启动 Claude Code,或检查 curl http://127.0.0.1:37777/api/readiness |
| Hooks 不触发 | codex_hooks 功能未启用 | 执行 codex features enable codex_hooks |
| 会话启动卡住 | smart-install.js 正在下载 Bun/依赖 | 等待(仅首次,最长约 60 秒超时) |
| 端口 37777 被锁死 | Bun TCP socket 泄漏(Windows) | 重启电脑。不要尝试强制启动新的 Worker。 |
| mem_session_end 报 "No active session" | 之前的 init 失败了 | 检查 Worker 是否健康,先试 mem_session_start |
| 搜索没有结果 | 项目过滤条件错误或数据库为空 | 用 mem_stats 检查数据库是否有数据 |
已知限制
- 依赖 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 实现
