AI导哈

持久内存工具

Codex-mem是一款为Codex CLI、Claude Code和MCP客户端设计的持久内存工具，提供跨会话记忆存储、智能搜索和隐私控制功能。

  • by KeystoneScience
  • TypeScript
  • 本地部署
  • 12 星标
  • 更新于
在 GitHub 查看 KeystoneScience/codex-mem

使用说明

Codex-mem

Codex CLI、Claude Code和MCP客户端的持久内存。

Codex mem是Codex的第一个港口 克劳德·梅 亚历克斯·纽曼(@多特马克).上游项目正确地构建了核心内存架构。该回购通过官方的Codex集成表面，被动地推进了Codex的工作 MEMORY.md 召回和单行设置。

通知 解释了上游信贷和许可证的连续性。

快速开始

Codex CLI

npx codex-mem-cli@latest codex setup

设置后，正常启动Codex：

codex

这一个命令：

  • 安装Bun， uv，以及运行时依赖关系（如果需要）
  • 将运行时复制到稳定的本地安装目录中
  • 更新 ~/.codex/config.toml 和 notify 和 [mcp_servers.codex_mem]
  • 保存和链接现有 notify 当它可以安全地执行命令时
  • 启动worker并在退出前验证运行状况

npm注意：注册表包是 codex-mem-cli 因为 codex-mem 已经在npm上使用了。GitHub项目和已安装的CLI命令都是 codex-mem.

克劳德代码

Codex mem仍然继承了上游的Claude Code集成模型。如果你想要原始的Claude插件工作流程，请上游安装 克劳德·梅 或者使此仓库中的插件资产适应您的Claude插件环境。

OpenClaw网关

安装OpenClaw集成：

curl -fsSL https://install.cmem.ai/openclaw.sh | bash

为什么它存在

  • Codex CLI现在可以读取MCP内存，但写入捕获需要Codex本地摄入表面。
  • claudemem已经证明了worker、搜索和渐进式回忆模型。
  • 食品法典委员会成员补充道 notify, codex exec --json，以及 codex app-server 捕获，因此相同的内存架构在Codex中运行良好。

主要特点

  • 具有SQLite、FTS5和可选矢量搜索的持久跨会话内存
  • 通过食品法典委员会本地摄入 notify, exec --json，以及 app-server
  • 通过令牌高效召回 bootstrap_memory, search, timeline，以及 get_observations
  • 根 MEMORY.md 食品法典委员会被动召回预测
  • 打开Web查看器 http://localhost:37777
  • 隐私控制包括 <private> 持久化前剥离

文档

📚 查看完整文档 -浏览官方网站

入门指南

最佳实践

建筑

配置与开发

运作原理

核心组件：

  1. 5个生命周期挂钩 -SessionStart、UserPromptSubmit、PostToolUse、Stop、SessionEnd（6个钩子脚本）
  2. 智能安装 -缓存依赖性检查器（预挂钩脚本，而不是生命周期挂钩）
  3. 工人服务 -端口37777上的HTTP API，带有web查看器UI和10个搜索端点，由Bun管理
  4. SQLite数据库 -存储会话、观察、总结
  5. 成员搜索技能 -具有渐进式披露的自然语言查询
  6. 色度矢量数据库 -混合语义+关键字搜索实现智能上下文检索

看 架构概述 了解详情。

MCP搜索工具

Codex mem通过以下方式提供智能内存搜索 4个MCP工具 遵循令牌高效 4步工作流模式:

工作流程：

  1. bootstrap_memory -为当前项目/任务构建一个紧凑的内存简报
  2. search -获取带有ID的紧凑索引（~50-100个令牌/结果）
  3. timeline -围绕有趣的结果获取按时间顺序排列的上下文
  4. get_observations -仅获取筛选ID的完整详细信息（~500-1000个令牌/结果）

工作原理：

  • Claude和Codex可以使用MCP工具搜索你的记忆
  • 从...开始 bootstrap_memory 在新会话中恢复工作时
  • 更喜欢传球 cwd 回购意识召回； project 仅此一项就是遗留问题的退路
  • 从...开始 search 获取结果索引
  • 使用 timeline 看看具体观察结果周围发生了什么
  • 使用 get_observations 获取相关ID的完整详细信息
  • 约10倍的代币节省 在获取详细信息之前进行过滤

可用的MCP工具：

  1. bootstrap_memory -通过以下方式压缩项目内存简报，包括后续观察ID和支持仓库的范围 cwd/repoRoot
  2. search -使用全文查询搜索内存索引，按类型/日期/项目筛选
  3. timeline -获取特定观察或查询的时间顺序上下文
  4. get_observations -按ID获取完整的观察细节（始终批量处理多个ID）

示例用法：

// Step 1: Build a brief
bootstrap_memory(goal="resume auth refactor", cwd="/path/to/repo")

// Step 2: Search for index
search(query="authentication bug", type="bugfix", limit=10)

// Step 3: Review index, identify relevant IDs (e.g., #123, #456)

// Step 4: Fetch full details
get_observations(ids=[123, 456])

看 搜索工具指南 用于上游工作流背景。

Codex CLI

Codex CLI的快速安装：

npx codex-mem-cli@latest codex setup

这一个命令：

  • 将捆绑的运行时复制到 ~/.claude-mem/codex
  • 安装Bun， uv，以及运行时依赖关系（如果需要）
  • 更新 ~/.codex/config.toml 和 notify 加 [mcp_servers.codex_mem]
  • 保存和链接现有 notify 当它是标准字符串数组配置时，使用命令
  • 启动worker并验证其健康状况 http://127.0.0.1:37777

安装后的健康检查：

npx codex-mem-cli@latest codex doctor

设置后，继续使用 codex 通常。观众可在以下网址观看 http://localhost:37777.

手动/高级设置：

该工作人员现在支持三条Codex摄入通道：

  1. notify 对于库存Codex CLI，完成捕获
  2. exec --json 用于CI/自动化摄取
  3. app-server 用于更高保真的流媒体事件

今天安全的MCP设置（stdio传输）：

[mcp_servers.codex_mem]
command = "/ABS/PATH/TO/node"
args = ["/Users/YOU/.claude-mem/codex/scripts/mcp-server.cjs"]
enabled = true
required = false

食品法典委员会通知示例：

notify = ["/ABS/PATH/TO/node", "/Users/YOU/.claude-mem/codex/scripts/codex-notify.js"]

自动化/CI摄取示例：

codex exec --json "implement X" | node ~/.claude-mem/codex/scripts/bun-runner.js ~/.claude-mem/codex/scripts/worker-service.cjs codex exec-json

被动回忆：

  • 启用 CLAUDE_MEM_MEMORY_MD_ENABLED=true 保持根 MEMORY.md 预测已更新。
  • 添加 "MEMORY.md" 食品法典委员会 project_doc_fallback_filenames 如果你想让Codex自动加载该投影。

系统要求

  • Node.js：18.0.0或更高
  • 克劳德代码：支持插件的最新版本
  • 包子：JavaScript运行时和进程管理器（如果缺少，则自动安装）
  • 紫外线：用于矢量搜索的Python包管理器（如果缺少，则自动安装）
  • SQLite 3：用于持久存储（捆绑）

Windows安装说明

如果您看到以下错误：

npm : The term 'npm' is not recognized as the name of a cmdlet

确保Node.js和npm已安装并添加到您的PATH中。从下载最新的Node.js安装程序https://nodejs.org安装后重新启动终端。

配置

设置在中管理 ~/.claude-mem/settings.json （首次运行时自动创建默认值）。为了兼容性，该路径继承自上游的claude-mem架构。

看 配置指南 对于所有可用的设置和示例。

发展

看 开发指南 用于构建说明、测试和贡献工作流。

出版

npm包名为 codex-mem-cli.

对于新包的第一个npm版本，添加一个 NPM_TOKEN 存储库密钥，并在上运行发布工作流 v* 标签。

包在npm上存在后，您可以切换到npm可信发布 KeystoneScience/codex-mem 和 .github/workflows/npm-publish.yml，然后删除 NPM_TOKEN.

手动发布仍然有效：

npm adduser
npm publish --access public --provenance

故障排除

如果遇到问题，请向Claude描述问题，故障排除技能将自动诊断并提供修复。

看 故障排除指南 常见问题和解决方案。

错误报告

使用自动生成器创建全面的错误报告：

cd ~/.claude/plugins/marketplaces/thedotmack
npm run bug-report

贡献

欢迎投稿！拜托：

  1. 分叉存储库
  2. 创建要素分支
  3. 通过测试进行更改
  4. 更新文档
  5. 提交拉取请求

看 开发指南 用于贡献工作流程。

许可证

该项目根据 GNU Affero通用公共许可证v3.0 （AGPL-3.0）。

版权所有（C）2025亚历克斯·纽曼（@thedotmack）。保留所有权利。

看 许可证 文件以获取完整详细信息。

这意味着：

  • 您可以自由使用、修改和分发此软件
  • 如果在网络服务器上进行修改和部署，则必须使源代码可用
  • 衍生作品也必须根据AGPL-3.0获得许可
  • 此软件不提供任何担保

关于Ragtime的说明：The ragtime/ 目录在下单独获得许可 PolyForm非商业许可证1.0.0。参见 ragtime/许可证 了解详情。

支持

使用Claude Agent SDK构建 | 由Claude Code提供技术支持 | 使用TypeScript制作

相关 MCP