codex-lcm

面向 OpenAI Codex CLI 的本地、无损上下文管理。

codex-lcm 通过 SQLite 捕获 Codex 对话事件，将较旧的上下文压缩为层级摘要（不删除源消息），在会话启动时恢复相关上下文，并通过本地 MCP 服务器提供词汇召回。

“无损”的含义： 源内容在按配置进行机密信息脱敏后予以保留。可搜索的工具预览有界，而完整脱敏后的工具输入和输出可通过分页展开获得。

状态与平台

codex-lcm 是适用于 macOS 的测试版软件。它依赖 Codex hooks 和 POSIX flock；目前不支持也不声称支持 Windows 和 Linux。

Related MCP server: ClaudeX

功能

• 实时捕获： 通过 Codex hooks 捕获用户提示、助手响应和工具活动。

• 持久本地存储： WAL 模式下的 SQLite 存储原始消息、结构化消息部件、摘要和 FTS5 索引。

• 层级压缩： 较旧的消息变为叶摘要；符合条件的摘要运行可被浓缩为更深的 DAG 节点。源行永远不会被自动删除。

• 上下文恢复： 在会话启动时，在严格的大小限制内注入活动摘要和最新的未摘要消息。

• 本地召回： 六个 stdio MCP 工具提供词汇搜索、最近会话查找、元数据检查和分页源展开。

• 故障开放 hooks： 捕获或压缩失败不会阻塞 Codex 回合。

• 安全控制： 机密信息脱敏、每会话压缩锁、原子消息/FTS 写入、提供方调用预留、进度检查和默认私有文件权限。

从仓库检出安装

python3 -m venv ~/.codex-lcm/venv
~/.codex-lcm/venv/bin/python -m pip install .
~/.codex-lcm/venv/bin/codex-lcm install
~/.codex-lcm/venv/bin/codex-lcm doctor

安装后重启 Codex。在 Codex 中使用 /hooks 检查并信任已安装的 hooks。

安装程序会将 codex-lcm 条目合并到 ~/.codex/hooks.json 和 ~/.codex/config.toml。在修改现有文件之前，它会创建带时间戳的备份。再次运行安装程序是幂等的。

源码检出还包含 scripts/install.sh，它执行相同的隔离安装和验证。

可选的 LLM 摘要

在 Python 3.11+ 上，核心包没有第三方运行时依赖。Python 3.10 会安装 tomli 兼容性反向移植，以安全处理 TOML 配置。如果没有 LLM 客户端，压缩将使用确定性的头部/尾部截断。

要启用 OpenAI 兼容的摘要，请安装可选附加组件并配置凭据：

~/.codex-lcm/venv/bin/python -m pip install ".[llm]"
export CODEX_LCM_API_KEY="..."

OPENAI_API_KEY 也被识别。使用 CODEX_LCM_BASE_URL 或 OPENAI_BASE_URL 作为 OpenAI 兼容端点。CODEX_LCM_* 提供方设置被视为一对，并作为一对优先，因此全局密钥永远不会发送到作用域端点。当设置了 CODEX_LCM_BASE_URL 时，也请配置 CODEX_LCM_API_KEY。

CLI

codex-lcm install                       Wire hooks and the MCP server into Codex
codex-lcm uninstall                     Remove codex-lcm wiring and keep stored data
codex-lcm status                        Show database statistics
codex-lcm doctor                        Verify package, database, hooks, and MCP wiring
codex-lcm compact --session <id>        Compact one session synchronously
codex-lcm compact --all                 Compact every recorded session synchronously

卸载不会删除 ~/.codex-lcm/ 或其数据库。

MCP 工具

召回是词汇性的，而非语义性的：此版本不包含嵌入或向量相似性声明。

配置

配置从环境变量读取。

默认数据目录模式为 0700；在 POSIX 系统上，数据库、WAL 侧车文件、锁文件和压缩日志模式为 0600。

数据与安全边界

• 在持久化之前，对已知 API 密钥、令牌、授权头、密码/机密赋值、JWT 和 PEM 私钥进行脱敏。

• 包含凭据的 Git 远程 URL 在存储时不包含用户信息、查询参数或片段。

• 脱敏是纵深防御，而非保证能识别所有可能的机密格式。

• 完整脱敏后的工具负载仍可能包含私有对话或项目数据。请相应保护本地账户和数据库备份。

• 除非安装了可选客户端并配置了提供方凭据或基础 URL，否则不会向 LLM 提供方发送任何数据。

• 有意不提供自动保留和删除功能。应用程序不会静默丢弃源历史。

开发

使用项目本地环境；测试永远不需要实时 Codex 配置文件或数据库。

python3 -m venv .venv
.venv/bin/python -m pip install -e ".[dev]"
.venv/bin/python -m pytest -q
.venv/bin/python tests/smoke_test.py
.venv/bin/python tests/reliability_test.py
.venv/bin/python tests/package_test.py
.venv/bin/ruff check .
.venv/bin/bandit -q -r codex_lcm

包测试构建并安装到一次性主目录和虚拟环境中。冒烟和可靠性脚本也使用临时数据库。

有关存储模型、不变量、hook 流程和失败行为，请参阅 DESIGN.md。

许可证

MIT