Codex History Hub

简体中文 | English

Local-first、源数据只读的 Codex 会话聚合器。它将一个或多个 CODEX_HOME 索引到独立 SQLite 数据库，并通过本地网页和 MCP 提供跨项目、归档与子代理历史查询。

当前为 alpha 版本。请先阅读隐私与安全，不要上传 Hub 数据库或真实会话文件。

能力与边界

• 以 Codex 的 state_5.sqlite 为线程索引，按 rollout_path 增量读取 sessions/ 和 archived_sessions/。
• 覆盖主会话、归档会话、子代理、用户/助手消息及工具事件。
• 提供本地只读网页，以及 5 个 MCP 工具用于近期上下文、搜索、线程读取和项目总览。
• 不读取 auth.json、Cookie、API Key 或 logs_2.sqlite，不修改 Codex 原始数据库、JSONL 或侧栏。
• 不合并或改写 Codex 原生账号会话库；所有索引和长期总结仅写入 Hub 自己的数据库。

安装

需要 Python 3.10 或更新版本，无第三方运行时依赖。

git clone <YOUR_REPOSITORY_URL>
cd codex-history-hub
python -m venv .venv
.\.venv\Scripts\python -m pip install -e .

注册当前 Windows 用户的 Codex Home：

codex-history-hub --db data/history-hub.db add-source `
  --name local-codex `
  --path "$env:USERPROFILE\.codex"

codex-history-hub --db data/history-hub.db sync
codex-history-hub --db data/history-hub.db status

macOS/Linux 可将路径写为 ${CODEX_HOME:-$HOME/.codex}。另一个独立 CODEX_HOME 可用不同 --name 再次注册；旧式纯 JSONL 目录使用 --type jsonl。

也可通过环境变量设置数据库位置：

$env:HISTORY_HUB_DB = "D:\private\codex-history\history-hub.db"
codex-history-hub status

本地网页

Windows 用户可双击 open-history-hub.cmd。也可以运行：

codex-history-hub --db data/history-hub.db serve

然后访问 http://127.0.0.1:8765。服务立即同步一次，此后默认每 30 秒增量同步。页面包含主会话、子代理、归档、来源、模型提供方、项目和关键词筛选，工具事件默认折叠。

网页只允许绑定 localhost、127.0.0.1 或 ::1。项目没有远程认证机制，因此会拒绝 0.0.0.0 和其他非回环地址。

全局 MCP 配置

将下列配置加入用户级 Codex config.toml。所有路径都应替换为本机实际的绝对路径；建议直接使用虚拟环境的 Python，避免依赖当前工作目录或系统 PATH。

[mcp_servers.history_hub]
command = "D:\\path\\to\\codex-history-hub\\.venv\\Scripts\\python.exe"
args = [
  "-m", "history_hub",
  "--db", "D:\\private\\codex-history\\history-hub.db",
  "mcp"
]

重启 Codex 或新开任务后，可调用：

• history_get_recent_context：项目总览和最近 3 条主会话；子代理默认排除。
• history_search：搜索全部会话，包括归档和子代理。
• history_get_thread：按需读取选中线程；工具输出默认排除。
• history_get_project_summary：读取长期项目总览。
• history_update_project_summary：仅更新 Hub 数据库中的项目总览。

每次 MCP 工具调用前都会执行增量同步，因此网页无需常驻。

隐私与安全

Hub 在写入和输出时对常见 API Key、访问令牌、私钥、JWT、邮箱和用户主目录路径进行脱敏。Web/MCP 输出还会移除源根目录、rollout 文件路径和可能带凭据的 Git URL。升级后的数据库会执行一次 Hub 内部脱敏迁移；原始 Codex 文件始终不变。

这些规则不能识别所有自然语言中的个人信息。请遵守以下原则：

• data/、*.db、SQLite sidecar 和日志已被 .gitignore 排除，永远不要强制提交。
• Hub 数据库仍包含完整聊天内容，以及增量同步必需的本机源路径；应将其视为敏感文件。
• 分享截图、导出结果或数据库前必须人工复核。
• 不要将本地网页通过端口转发、代理或公网地址直接暴露。
• 安全问题请按 SECURITY.md 私下报告，不要在 issue 中粘贴真实会话或凭据。

开发与验证

python -m compileall -q history_hub tests
python -m unittest discover -s tests -v

CI 会在 Windows 与 Ubuntu、Python 3.10 和 3.13 上执行安装、编译和全部测试。贡献要求与隐私测试规范见 CONTRIBUTING.md。

许可证

本项目采用 MIT License。版本号遵循语义化版本，本次安全与通用化升级为 0.3.0。