快速接入

先看主来源和安装命令，再打开仓库或文档；下面只保留这个条目的关键接入事实。

命令预览

pip install git+https://github.com/monishkumarvr/agent-history-mcp.git

详细介绍

代理历史mcp

本地内存搜索Codex和Claude Code对话。

agent-history-mcp 是一个本地MCP服务器，允许编码代理在多个位置搜索您过去的AI编码会话 OpenAI Codex命令行界面 和 克劳德代码。它将历史记录保存在您的计算机上，构建本地图索引，并返回紧凑的证据，而不是将完整的对话转储到上下文中。

为什么存在

编码代理解决了一次性聊天中的有用问题，然后这些知识就会消失在JSONL历史中。此项目将这些旧会话转换为可搜索的本地内存层：

查找以前的修复程序、命令、API、错误和文件路径
从Claude Code搜索Codex历史，从兼容Codex的MCP客户端搜索Claude历史
当确切关键字不同时，使用图搜索进行“相似问题”检索
表面重复的工作流程，可以成为可重用的技能

没有上传聊天记录。Codex和Claude历史文件是只读的；只写入导出的本地索引。

特性

混合搜索：SQLite FTS5关键字搜索加模糊回退。
本地图形搜索：提取会话、消息、主题、命令、API、路径和错误之间的关系。
技能建议：基于重复聊天模式的可重用技能的有证据支持的想法。
增量索引：根据需要解析更改的JSONL文件；不需要后台守护进程。
隐私第一：没有网络调用或模型调用用于索引。

快速开始

1.安装

来自GitHub：

pip install git+https://github.com/monishkumarvr/agent-history-mcp.git

从本地克隆：

git clone https://github.com/monishkumarvr/agent-history-mcp.git
cd agent-history-mcp
pip install .

2.用克劳德代码注册

将此添加到 ~/.claude/.mcp.json:

{
  "mcpServers": {
    "agent-history": {
      "command": "python3",
      "args": ["-m", "agent_history_mcp"]
    }
  }
}

Claude Code在需要时自动启动服务器。

3.运行第一个查询

询问克劳德代码：

Search my history for CUDA illegal address

其他有用提示：

Use graph search for a similar Redis migration timeout
Did I solve a similar HMAC issue before?
Suggest skills I should create from my recent chats
List my recent Codex sessions
Get the full session where I fixed the GStreamer pipeline stall

4.可选：重建派生索引

refresh_history_index(rebuild=true)

这将仅删除和重新创建派生的SQLite图形数据库。它从不修改Codex或Claude的历史文件。

工具

工具	它做什么
`search_history`	跨过去会话的混合搜索。使用关键字/模糊搜索加上图形相关性。
`search_graph`	面向关系的图搜索相关的bug、API、命令、文件和主题。
`suggest_skills`	从重复的聊天模式中提出有证据支持的可重用技能想法。
`list_sessions`	列出带有标题、日期、来源和消息计数的会话。
`get_session`	检索特定会话的有界部分。
`refresh_history_index`	手动刷新或重建导出的本地图索引。

输出示例

`search_history`

Found 2 session(s) matching "CUDA illegal address":

-- Result 1 ------------------------------------------
Source : CODEX
Session: Fix CUDA kernel crash
Date   : 2026-05-07
ID     : rollout-2026-05-07...

[YOU ASKED]
Fix CUDA illegal address after kernel launch

[ANSWER]
Add synchronization around the kernel launch and rerun the focused pytest case.

`search_graph`

Found 1 graph result(s) matching "similar Redis migration timeout":

-- Graph Result 1 ------------------------------------
Source : CLAUDE
Session: Redis migration debugging
Why    : Matched extracted topics: topic:Redis, error:timeout
Related: command:docker compose logs api, api:redis.asyncio

`suggest_skills`

1. Azure Deployment Troubleshooting
   ID: skill-4f3a1b2c9e10
   Slug: azure-deployment-troubleshooting
   Confidence: 0.84
   When to use: azure deployment, app service logs, az webapp
   Evidence: 4 sessions, 2 source(s)
   Why: Repeated deployment/debug workflow with recurring commands and failure modes.

技能建议不是生成的技能文件。它们是经过排名的、有证据支持的想法，你可以在创建实际想法之前对其进行审查 SKILL.md.

支持的历史源

源	默认位置
OpenAI Codex命令行界面	`~/.codex/sessions/`
克劳德代码	`~/.claude/projects/`

用环境变量覆盖默认值：

{
  "mcpServers": {
    "agent-history": {
      "command": "python3",
      "args": ["-m", "agent_history_mcp"],
      "env": {
        "CODEX_PATH": "/custom/path/.codex",
        "CLAUDE_PATH": "/custom/path/.claude",
        "AGENT_HISTORY_GRAPH_DB": "/custom/path/history_graph.sqlite"
      }
    }
  }
}

如果 AGENT_HISTORY_GRAPH_DB 如果未设置，则在以下位置创建图形数据库：

~/.agent-history-mcp/history_graph.sqlite

运作原理

Claude Code or another MCP client
    calls an MCP tool
agent-history-mcp
    refreshes the local graph index for changed JSONL files
    parses Codex and Claude sessions into one message shape
    searches FTS5/fuzzy index
    searches persistent graph index
    returns concise excerpts, evidence, and graph explanations

图索引提取确定性局部实体：

会话
信息和问答环节
技术主题
文件路径
命令
包/API名称
错误字符串

它存储确定性 EXTRACTED 关系：

会话包含消息
消息提到主题/路径/命令/API/错误
助理回答问题
主题在问答配对中同时出现
会话通过共享提取的主题进行关联

新聊天更新

每次MCP工具调用都会执行轻量级刷新：

探索Codex和Claude JSONL文件。
按路径、大小和修改时间比较已知文件。
仅将新的或更改的文件解析到图形索引中。
删除已删除历史文件的索引行。
仅当文件发生更改时，才使内存中的关键字缓存无效。

下次Claude或Codex调用MCP工具时，新的聊天记录将变得可搜索。

基准测试

运行本地基准测试：

python benchmarks/benchmark_retrieval.py

基准比较：

完全JSONL解析
内存FTS索引构建和查询
冷图索引构建
温图刷新，文件不变
图形搜索查询时间
仅绘制候选扩展与FTS结果的关系图
技能建议时间

本地基准结果

这些数字是在一台本地Windows笔记本电脑上根据其保存的Codex/Claude历史记录进行测量的。它们可用作方向信号，而不是通用的性能声明。

语料库：43个会话，2434条解析消息，2741934个消息字符
查看的历史文件：48
查询重复次数：5
每次查询的最大结果数：5

操作	平均/经过时间	备注
解析JSONL会话	676.1毫秒	完整解析器传递Codex和Claude历史
内置内存FTS索引	28.5毫秒	SQLite FTS5超过解析消息
冷图索引构建	15958.6 ms	43个索引会话的一次性导出图构建
温图刷新	20.7ms	元数据检查的未更改文件；无JSONL重解析
原始JSONL+FTS重建+搜索	1324.1 ms	平均超过3个代表性冷查询
技能建议通过	7376.1毫秒	返回5名候选人

查询	FTS查询ms	图形查询ms	FTS命中率	图形命中率	仅图形命中率
`history search graph`	0.53	3.23	5	5	4
`git push`	0.73	22.35	5	5	4
`permission denied`	0.35	12.06	5	5	1
`pytest fixture`	0.46	0.32	0	0	0
`redis migration timeout`	0.32	22.85	2	5	3
`azure deployment`	0.15	0.24	3	0	0
`CUDA illegal address`	0.31	18.13	4	5	4

在这些基准查询中，FTS返回了24个查询结果会话，图搜索返回了25个。图层为同一查询集添加了16个关键字搜索未返回的纯图候选会话。

释义：

速度的胜利不是图查询击败了已经很热的FTS查询。热FTS非常快。
实际的速度优势是热刷新：重复的MCP调用在大约20毫秒内检查未更改的文件，而不是重新解析JSONL并重建搜索状态。
检索的胜利是候选扩展：即使确切的关键字不同，图搜索也可以通过提取的关系来显示相关会话。
仅图表点击是额外的证据支持的候选人，不能保证正确答案。

安全和隐私

历史源是只读的： ~/.codex 和 ~/.claude 永远不会被修改。
索引仅限于本地：不使用网络调用或模型调用。
未读取凭据： ~/.codex/auth.json 永远无法访问。
导出的图形数据库可以包含提取的术语和消息摘要，用于本地搜索。

如果过去的对话包含秘密，搜索可以浮出水面，因为它会搜索你的本地历史。

局限性

确定性图提取可能会有噪声，特别是对于广泛或通用的主题。
技能建议是候选人，不能保证完整的技能。
对于大型历史记录，第一次索引构建可能需要时间。
搜索质量取决于您保存的Codex和Claude JSONL文件的结构和内容。

发展

运行测试：

python -m unittest discover -s tests

编译检查：

python -m py_compile src/agent_history_mcp/*.py tests/*.py

包装检查：

python -m pip install . --dry-run --no-deps

基准检查：

python benchmarks/benchmark_retrieval.py

文件结构

agent-history-mcp/
  pyproject.toml
  README.md
  LICENSE
  benchmarks/
    benchmark_retrieval.py
  src/
    agent_history_mcp/
      __init__.py
      __main__.py
      graph.py
      parsers.py
      search.py
      server.py
      skills.py
  tests/
    test_graph.py
    test_skills.py

许可证

麻省理工学院

目录标签

本地搜索PythonClaude隐私保护本地部署AI会话管理编码辅助工具增量索引

支持客户端

Claude

接入字段

传输方式（transport，传输协议）

stdio

鉴权方式（authType，认证方式）

session

工具数量（toolCount，工具数）

6

资源数量（resourceCount，资源数）

0

提示词数量（promptCount，提示词数）

0

权限和风险

stdiosession部署方式未说明

接入前请确认传输方式、认证方式和部署位置，并根据实际工具能力限制访问范围。

安装前确认

不要直接授予不必要的文件、网络或账号权限；先核对安装命令和配置内容。

来源信息

MCP World

mcpworld.com

/detail/c89b1f8940dad3731b5a394bcd6d42b5

agent-history-mcp 是一个本地MCP服务器，允许编码代理搜索您在OpenAI Codex CLI和Claude Code中的过去AI编码会话，提供本地图形索引和紧凑证据返回。

继续浏览同类 MCP

更多搜索检索 MCP（7,303）返回 MCP 目录

上一个 MCP

Agent Framework Starters

提供用于构建代理的启动项目和参考模式，包括RAG、工具、多代理编排和MCP等，适用于学习、实验、快速原型设计和内部知识共享。

下一个 MCP

Agentic 5fea3293

全面解析Agentic CsaMCP Server的核心功能、安装配置和实用案例。作为顶级Model Context Protocol服务器，Agentic Csa能让AI助手访问实时数据、执行操作，为您提供更智能的工作体验和自动化解决方案。

Agent History MCP