Codex Mem

Persistent memory MCP server for Codex, local-first and SQLite-backed.

🇺🇸 English • 🇪🇸 Español • 🇩🇪 Deutsch

Quick Start • Documentation • Automatic Mode • Architecture Design • How It Works • MCP Search Tools • System Requirements • Contributing • License

______________________________________________________________________

codex-mem 通过实用的渐进式检索工作流程，在Codex会话中保留项目内存。

快速开始

一个命令自动安装：

npm run mcp:install

安装程序选项：

bash scripts/install-mcp.sh --help
bash scripts/install-mcp.sh --dry-run
bash scripts/install-mcp.sh --dry-run --no-register
bash scripts/install-mcp.sh --name codex-mem --db-path .memory/codex-mem.db

自动工作流助手：

npm run auto:mode -- start --ingest --project codex-mem
npm run auto:mode -- end --summary "Completed MCP setup docs and tests."
npm run auto:mode -- commit
npm run auto:install-hooks -- --project codex-mem

手动安装路径：

npm install
export MEMORY_DB_PATH=.memory/codex-mem.db
npm run migrate
npm run mcp:start

VS代码MCP设置值：

• 姓名： codex-mem
• 运输： STDIO
• 命令： npm
• 论据： run, mcp:start, --silent
• 环境变量： MEMORY_DB_PATH=.memory/codex-mem.db
• 工作目录：指向您的绝对路径 codex-mem 仓库

文档

根

• README.md
• 贡献.md
• 许可证
• scripts/install-mcp.sh
• scripts/auto-memory.sh
• scripts/install-git-hoks.sh
• 安全.md
• 更改日志.md
• .env.示例

GitHub协作

文档索引

• docs/README.md

规划和产品

• docs/project-plan.md
• docs/roadmap.md
• 文件/要求.md
• docs/mvp-spec.md
• docs/delivery-plan.md
• docs/implementation-kickoff.md

建筑与设计

• docs/architecture.md
• 文档/架构图.mmd
• docs/data-model.md
• docs/数据模型图.mmd
• 文档/技术设计.md
• docs/运行时决策.md

API和操作

• docs/mcp-api-spec.md
• docs/auto-mode.md
• docs/auto-capture-wrapper.md
• docs/setup-guide.md
• docs/usage-guide.md
• docs/故障排除.md
• 文档/操作-runbook.md
• docs/security-baseline.md
• docs/测试策略.md

项目日志

• docs/decisions.md
• docs/session-log.md

国际化

• docs/i18n/README.es.md
• 文档/i18n/README.de.md

品牌资产

• docs/public/codex-mem.png
• docs/public/codex-mem-wordmark.svg

自动模式

codex-mem 目前支持实用的半自动工作流程：

npm run auto:mode -- start --project codex-mem --ingest
npm run auto:mode -- end --project codex-mem --summary "Session handoff summary."
npm run auto:mode -- commit --project codex-mem
npm run auto:install-hooks -- --project codex-mem

请参阅 docs/auto-mode.md.

建筑设计

flowchart LR
  User["User / Codex Session"] --> MCP["MCP Interface"]
  MCP --> Service["Memory Service"]

  Service --> Policy["Policy Layer"]
  Policy --> Storage["Storage Layer (SQLite + FTS)"]

  Service --> Ingest["Ingestion Layer"]
  Ingest --> Sources["Project Sources (docs, logs)"]
  Ingest --> Policy

  Service --> Search["Search Flow"]
  Search --> Storage

  Service --> Timeline["Timeline Flow"]
  Timeline --> Storage

  Service --> Details["Details Flow"]
  Details --> Storage

  Service --> Save["Save Flow"]
  Save --> Policy

  subgraph LocalRuntime["Local Runtime"]
    MCP
    Service
    Policy
    Storage
    Ingest
  end

运作原理

1. save_memory 存储关键决策、修复和约束。
2. search 返回紧凑的索引条目以实现低成本发现。
3. timeline 扩展锚点条目周围的上下文。
4. get_entries 仅获取选定ID的完整详细信息。
5. ingest_docs 导入带有源/哈希重复数据消除的文档。
6. retention_dry_run 报告在不删除数据的情况下清理候选对象。

MCP搜索工具

推荐检索流程：

1. search
2. timeline
3. get_entries

可用的MCP工具：

• save_memory
• search
• timeline
• get_entries
• ingest_docs
• retention_dry_run

系统要求

• Node.js 20+
• npm
• 本地文件系统写访问权限 .memory/
• SQLite运行时支持（通过捆绑依赖关系）

贡献

1. 分叉存储库
2. 创建要素分支
3. 添加或更新测试
4. 更新行为更改文档
5. 打开拉取请求

看 贡献.md.

许可证

根据以下许可 AGPL-3.0.

看 许可证.