CP Memory

CP Memory

面向 AI 编码 Agent 的本地优先、可治理记忆。
跨会话记住项目规则，只回忆重要内容，并在不隐藏历史记录的前提下纠正错误记忆。

简体中文 | English

---

为什么选择 CP Memory

如需了解可复现的软件包、协议和召回检查，请参阅验证证据与限制。

• **本地优先：**记忆默认保存在 ~/.cp-memory/memory.db 中。
• **可治理：**可以检查、审核、纠正、限定范围或弃用记忆，而不是悄悄覆盖它。
• **支持 MCP，增强 Codex：**stdio MCP 服务提供可移植的基础功能；Codex 插件则新增 Skills 和生命周期 Hooks。

快速开始 — 可移植 MCP

安装 Python 3.10+ 和 uv 后，任何 stdio MCP 客户端都可以通过以下方式启动 CP Memory：

uvx cp-memory-mcp

公开的软件包已通过干净缓存下的 MCP 握手测试，包含全部 40 个工具，以及写入／搜索／纠正流程。Codex、Claude Code、Cursor、VS Code 和 Gemini CLI 的示例，请参阅 MCP 客户端设置。

如需使用带有生命周期 Hooks 和 Skills 的增强型 Codex 集成，请安装插件：

codex plugin marketplace add CJhuochai/cp-memory
codex plugin add cp-memory@cp-memory

安装后重启 Codex；如果出现提示，请批准生命周期 Hooks。

30 秒查看效果

1. 告诉 Codex 一条项目规则，例如：“发布必须从一个分支开始，运行测试，并通过 PR 合并。”
2. 在后续会话中，CP Memory 会从本地主要存储中恢复相关规则，让 Codex 可以继续遵循。
3. 如果规则有误，可以保留纠正历史，并将旧记录标记为错误、过时或限定范围，而不是悄悄覆盖它。

CP Memory 是面向 Codex 的本地优先记忆插件。它会将事实、偏好、进行中的工作、经历、决策和对话检查点存储在本地 SQLite 数据库中，然后通过 MCP 工具和生命周期 Hooks 恢复相关上下文。

目标不是尽可能多地记住内容，而是让记忆在长期使用后依然可信：可解释、可审核、可纠正、可治理。

当前功能

• 上下文恢复：在启动时及符合条件的提示词中恢复相关的本地主存储记忆。
• 自动提取：根据明确表述，保守地创建长期个人记忆候选项。
• 项目范围：通过 repo:、project: 和 workspace: 范围，优先使用当前项目的记忆。
• 可审核治理：支持审核收件箱、审核摘要、冲突建议、纠正状态和启动提醒。
• 安全维护：每周维护仅运行健康检查、治理预检和低风险过期清理。

30 秒示例

你告诉 Codex：

Remember this: releases for this project must start on a branch, run tests, and merge through a PR.

在后续会话中，你询问：

What are the release rules for this plugin?

CP Memory 会优先从本地主存储中恢复相关记忆，Codex 随后遵循该规则。如果记忆有误，你可以将其标记为错误或过时，也可以写入修正后的版本。

更多匿名示例请参阅 docs/examples.md。

如需 GIF、短视频或发布帖，请使用经过清理的 30 秒演示脚本。

安装

对于任何 stdio MCP 客户端，请使用经过验证的公开软件包：

uvx cp-memory-mcp

客户端专用的命令和 JSON 文件位于 docs/mcp-clients.md。

对于 Windows，推荐通过 GitHub Marketplace 安装：

codex plugin marketplace add CJhuochai/cp-memory
codex plugin add cp-memory@cp-memory

安装后重启 Codex。如果 Codex 提示你信任 hooks，请在 hooks 视图中批准 CP Memory 生命周期 hooks。

对于 macOS/Linux，请使用源代码安装程序。它会为插件创建专用的 Python 运行环境，并安装 MCP 依赖项：

git clone https://github.com/CJhuochai/cp-memory.git
cd cp-memory
sh ./install.sh

安装完成后重启 Codex。不要将 macOS/Linux 上通过 GitHub Marketplace 安装视为同等经过验证的方式：Marketplace 不会运行 install.sh，因此不会创建该专用运行环境。

平台支持

平台	推荐安装方式	验证范围
Windows	GitHub Marketplace；本地开发使用 install.ps1	单元测试、隔离安装验证和 GitHub Actions CI 均已通过
macOS	源代码安装程序：sh ./install.sh	GitHub Actions macOS CI 已通过单元测试和隔离安装/MCP 启动验证
Linux	源代码安装程序：sh ./install.sh	GitHub Actions Ubuntu CI 已通过单元测试和隔离安装/MCP 启动验证

由于尚无法访问实体设备，macOS/Linux 上对真实 Codex 桌面端 Hook 注入的手动冒烟测试仍待完成。本次发布通过了三平台 CI 验收；这一限制不影响已覆盖的安装程序和 MCP 启动检查，但不能替代完整的桌面端手动验收。

安全

• 不要提交真实的 memory.db、日志、私人摘要或环境文件。
• 自动提取采用了审慎策略。生成的记忆可供审核和修正，也可标记为过时或错误。
• 记忆需要审核时，当前版本会在助手上下文中注入提醒。这不是面向用户的弹窗或可见审核面板，也不会自动删除记忆或自动解决冲突。
• 每周维护只运行健康检查、治理预检和低风险过期清理；长期个人记忆、任务和决策默认受到保护。
• 示例和截图使用经过脱敏的内容，因此你无需暴露真实的记忆数据库。

对比

如果你了解其他记忆项目，请从 docs/comparison.md 开始。CP Memory 的主要区别在于 Codex 生命周期集成和记忆治理，而不只是存储和搜索。

路线图

未来方向请参阅 docs/roadmap.md。路线图优先考虑本地优先行为、可解释性、可纠正性和隐私安全。

版本历史请参阅 CHANGELOG.md。

本地开发

Windows 用户通常无需运行 install.ps1。它主要用于本地开发、刷新个人 Marketplace 缓存，以及迁移早期版本遗留的全局 hook 配置。

在 macOS/Linux 上进行本地开发时，请运行：

sh ./install.sh
sh ./scripts/test-install.sh

PATH 中必须有 Python 3 的 python3。安装程序会在插件目录中创建专用虚拟环境并安装运行时依赖项；这是目前经过验证的 macOS/Linux 安装方式。

运行测试套件：

python -m unittest discover -s tests -p test_cp_memory.py

在隔离的临时配置文件中验证安装程序，不会触及真实的 Codex 配置：

powershell -ExecutionPolicy Bypass -File .\scripts\test-install.ps1

许可证

MIT