Skip to main content
Glama

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 自己的数据库。

Related MCP server: chist

安装

需要 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 秒增量同步;网页也会每 30 秒静默更新联动数量和当前列表,并保留筛选、页码和已打开详情。

页面按 50 条分页,来源、模型提供方、项目和会话类型的数量会随其他条件联动。活动筛选可单独移除或全部清除。搜索按会话去重,默认只查用户与 Codex 正文;“搜索设置”可分别开启工具输出、Developer 指令、System 消息和 Event 事件,这些偏好只保存在当前浏览器。详情正文分页读取,技术记录在展开时才加载,不会静默截断长会话。

网页只允许绑定 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:搜索全部会话,包括归档和子代理;默认仅搜索用户与助手正文,可显式设置 include_technical。

  • 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
npm ci
npx playwright install chromium
npm run test:e2e

CI 会在 Windows 与 Ubuntu、Python 3.10 和 3.13 上执行安装、编译和后端测试,并在 Ubuntu 上运行 Playwright 网页交互测试。Playwright 仅为开发依赖,History Hub 运行时仍无第三方 Python 依赖。贡献要求与隐私测试规范见 CONTRIBUTING.md。

许可证

本项目采用 MIT License。版本号遵循语义化版本,当前网页与搜索稳定性版本为 0.4.0。

Available Tools

5 tools
history_get_project_summaryA

Get the durable overview of a project without loading conversation transcripts.

Inputs: project.

history_get_recent_contextB

Get a project overview plus recent primary conversation summaries. Subagents are excluded by default.

Inputs: limit, source, project, include_subagents.

history_get_threadB

Read a selected history thread after identifying it via recent context or search. Full mode should be used only when the user explicitly requests the full thread.

Inputs: thread_id (required), mode, query, max_chars, +1 more.

history_update_project_summaryA

Update the confirmed durable project overview in the independent Hub only. Never writes to any source Codex account/session store.

Inputs: project (required), summary (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool targets a distinct operation: recent context retrieval, cross-account search, thread reading, project summary retrieval, and project summary update. The overlap between recent context and project summary is intentional, and descriptions clarify the difference.

    Naming Consistency4/5

    All tools share the 'history_' prefix and mostly follow a verb_noun pattern (get_recent_context, get_thread, get_project_summary, update_project_summary). The exception is 'history_search' which lacks an explicit object, but the pattern remains clear.

    Tool Count5/5

    With five tools, the set is well-scoped for a history hub: retrieval, search, and update operations. Each tool serves a clear purpose without redundancy.

    Completeness4/5

    The surface covers core history workflows: recent context, search, thread retrieval, and project summary read/update. A minor gap is the lack of an explicit list projects tool, but search and recent context can compensate.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP server for unified full-text search across chat histories from Claude Code, Codex, Cursor CLI, and Antigravity CLI, using SQLite FTS5. Provides read-only tools to search sessions, list conversations, and retrieve session details.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Indexes git history, shell commands with exit codes, project docs, and opt-in assistant transcripts into a local SQLite database, then serves ranked, token-budgeted context back over MCP. Uniquely links a failed shell command to the commit that fixed it, so agents can recall what was already tried and what worked.
      6
      66 npm
      14
      MIT