agent-history-mcp

Local memory, handoff, analytics and skill mining across your coding agents.

agent-history-mcp is a local MCP server and CLI that reads the session history of Claude Code, OpenAI Codex CLI, Gemini CLI, OpenCode and Cursor. It indexes everything into one local graph, then lets any of those agents:

• search what was solved before, in any agent

• pick up where another agent stopped in the same repository (handoff briefs and checkpoints)

• survive context compaction in Claude Code and Codex: checkpoint the session before it compacts, put the checkpoint back after, and recall the exact text the summary dropped

• keep instructions in sync across CLAUDE.md, AGENTS.md, GEMINI.md and auto-memory

• analyze sessions for time, tokens, failing commands and friction

• turn repeated workflows into skills: mine, draft a SKILL.md, install it for every agent, then track whether it is actually used

Everything runs locally and deterministically. There are no network calls, no model calls, and no API keys. History files are read-only. The only writes outside ~/.agent-history-mcp happen when you pass apply=true.

Why

Claude Code, Codex, Gemini CLI, Cursor and OpenCode all keep their own transcripts, memories and instruction files, and none of them reads the others'. If you switch tools mid-task, the next agent starts cold. Fixes you made with one agent get rediscovered by another. Workflows you repeat every week never become reusable skills. Each tool now speaks the open Agent Skills format and MCP, so one local layer can bridge all of them.

Related MCP server: callimachus

Quick start

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

If the agent-history and agent-history-mcp launchers don't end up on your PATH (this happens on Windows), use python -m agent_history_mcp in their place everywhere below, for example python -m agent_history_mcp hook pre-compact. Use the full path to python.exe in agent configs.

Claude Code (~/.claude/.mcp.json or claude mcp add agent-history -- agent-history-mcp):

{
  "mcpServers": {
    "agent-history": { "command": "agent-history-mcp" }
  }
}

Codex CLI (~/.codex/config.toml):

[mcp_servers.agent-history]
command = "agent-history-mcp"

Gemini CLI (~/.gemini/settings.json), Cursor (~/.cursor/mcp.json) and OpenCode all accept the same command in their MCP server settings.

Then ask any agent:

Where did the last agent stop in this repo?            -> handoff_brief
Did I solve a similar Redis timeout before?            -> search_history
What did I spend this week on, and where did I struggle? -> analyze_sessions / history_report
Which of my workflows should become skills?            -> suggest_skills -> draft_skill -> install_skill
Are my skills actually being used?                     -> skill_health
Which rules does Codex know that Claude doesn't?       -> list_agent_memory -> sync_memory
What exactly did I ask before the last compaction?    -> session_recall

Clients that support MCP prompts expose /handoff, /draft-skill and /weekly-review as slash commands.

Tools

CLI

The agent-history command exposes the same features:

agent-history handoff --project .            # brief for this repo
agent-history checkpoint "Paused: waiting on API keys"
agent-history analyze --days-back 7 --group-by source
agent-history report                         # HTML report path
agent-history token-report --days-back 0      # cache hits, idle re-writes, compactions, re-sent output
agent-history skills suggest
agent-history skills draft wf-1a2b3c4d5e6f > SKILL.md
agent-history skills install --file SKILL.md --apply
agent-history skills health
agent-history memory                         # instruction files and drift
agent-history rules --min-sessions 2
agent-history sync-memory                    # dry-run diff
agent-history hook pre-compact               # PreCompact hook (--source codex for Codex)
agent-history hook session-start             # SessionStart hook: handoff, or the checkpoint after compaction
agent-history hook pre-tool-use              # PreToolUse hook (matcher Read): stop re-reading unchanged files
agent-history reread-guard off               # switch that hook off (on / status)
agent-history                                # runs the MCP server

Automatic handoff in Claude Code

To start every Claude Code session with what other agents last did in the repo, add a SessionStart hook to ~/.claude/settings.json:

{
  "hooks": {
    "SessionStart": [
      { "hooks": [{ "type": "command", "command": "agent-history hook session-start" }] }
    ]
  }
}

The hook prints nothing when there is no other-agent history for the directory. For Codex, Gemini CLI, Cursor or OpenCode, add one line to AGENTS.md or GEMINI.md: "At the start of a task, call the agent-history handoff_brief tool for this repository."

Compaction without losing context

Compaction swaps a long conversation for a short summary. On real history it kept a median 12% of tokens in Claude Code and 23% in Codex, and Claude re-read thousands of files it had read before compacting. The transcript on disk still has everything, so two hooks and one tool bring it back:

1. hook pre-compact builds a checkpoint from the transcript just before compaction (no model call; about 2 s and under 2k tokens on a 113 MB session). It holds the latest user messages, open todos, files touched, command outcomes, unresolved errors and dead ends.

2. hook session-start sees "source": "compact" and puts that checkpoint back into context.

3. The checkpoint tells the agent to call session_recall for anything it still needs word for word.

For Claude Code, add both hooks to ~/.claude/settings.json (the SessionStart entry also covers the handoff above):

{
  "hooks": {
    "PreCompact": [
      { "hooks": [{ "type": "command", "command": "agent-history hook pre-compact", "timeout": 120 }] }
    ],
    "SessionStart": [
      { "hooks": [{ "type": "command", "command": "agent-history hook session-start" }] }
    ]
  }
}

A # Compact instructions section in CLAUDE.md also steers what the summary keeps.

Codex (0.150 and later) has the same two events, with the same input and output, in ~/.codex/hooks.json. Approve the new hooks once with /hooks:

{
  "hooks": {
    "PreCompact": [
      { "hooks": [{ "type": "command", "command": "agent-history hook pre-compact --source codex", "timeout": 120 }] }
    ],
    "SessionStart": [
      { "matcher": "compact", "hooks": [{ "type": "command", "command": "agent-history hook session-start --source codex" }] }
    ]
  }
}

compact_prompt in ~/.codex/config.toml steers what the Codex summary keeps.

Stop re-reading unchanged files (Claude Code)

On real history about half of Claude's Read calls fetched a path the session had already read, with no edit or compaction in between. Each copy stays in context and is re-sent on every later call. hook pre-tool-use remembers each Read (path, line range, file mtime and size) and denies a repeat of the same range of an unchanged file, saying when it was read. Repeating the Read lets it through, for when the earlier output is really gone from context. A subagent keeps its own list, and hook pre-compact clears the list, since compaction drops the earlier reads.

{
  "hooks": {
    "PreToolUse": [
      { "matcher": "Read", "hooks": [{ "type": "command", "command": "agent-history hook pre-tool-use" }] }
    ]
  }
}

It adds about 0.3 s per Read. agent-history reread-guard off turns it off (and on back on) from the next Read, without editing settings. Codex reads files through shell commands, so there is no Codex version.

Supported sources

Override locations with environment variables, and limit sources with AGENT_HISTORY_SOURCES (e.g. claude,codex):

{
  "mcpServers": {
    "agent-history": {
      "command": "agent-history-mcp",
      "env": {
        "CLAUDE_PATH": "/custom/.claude",
        "CODEX_PATH": "/custom/.codex",
        "GEMINI_PATH": "/custom/.gemini",
        "OPENCODE_DB": "/custom/opencode",
        "CURSOR_PATH": "/custom/Cursor/User",
        "AGENT_HISTORY_HOME": "/custom/agent-history-data",
        "AGENT_HISTORY_GRAPH_DB": "/custom/history_graph.sqlite"
      }
    }
  }
}

Derived data (index, checkpoints, compaction checkpoints, reports) lives in ~/.agent-history-mcp/ unless AGENT_HISTORY_HOME is set.

How it works

source adapters (claude, codex, gemini, opencode, cursor)
    -> one event model: messages, tool calls/results, commands, paths, exit codes,
       todos, skills, user signals (corrections, interrupts, rejections), cwd, tokens
    -> incremental SQLite index (unchanged units are skipped by change token)
       sessions · messages · events · graph nodes/edges · installed_skills
    -> search · handoff · memory sync · analytics · workflow mining · skill health

• Workflow mining turns each session into an action skeleton: shell commands normalized to git commit, npm run build and so on, edits by file type, MCP calls and skills, with read-only noise removed. It counts contiguous step sequences shared across sessions, drops patterns that appear almost everywhere, and keeps only the longest pattern that covers a given set of sessions. Patterns seen in several projects are marked global.

• Skill overlap compares a candidate's key terms with installed skills' names, descriptions and bodies, so you update an existing skill instead of adding a near-duplicate.

• Skill health detects use through the Skill tool, /slash-commands and reads of …/skills/<name>/SKILL.md. It finds missed triggers by matching the installed workflow's steps, or the skill's name, against later sessions.

• Compaction checkpoints are built from the transcript, not by a model, in about 2 s for a 100 MB session. session_recall reads the transcript file directly, so it also sees the session that is still running.

• Handoff summarizes events. It does not summarize with a model, so a brief costs a few hundred tokens and is reproducible.

• Memory sync only edits the text between <!-- agent-history:begin --> and <!-- agent-history:end -->.

The index is rebuilt automatically when its schema version changes. You can also run refresh_history_index(rebuild=true) to rebuild it.

Security and privacy

• History is read-only. Agent transcripts and databases are never modified; SQLite stores are opened in read-only mode.

• There are no network or model calls.

• Every tool output passes through secret redaction: API keys, GitHub, Slack and AWS tokens, JWTs, bearer tokens, private keys, password= pairs and URL credentials. Set AGENT_HISTORY_REDACT=0 to disable it.

• Writes are opt-in. install_skill, sync_memory and save_checkpoint(apply=true) show a dry run or diff first and write only with apply=true. Project-scope writes land in your repository, so review them before committing.

• Credentials files such as ~/.codex/auth.json are never read.

• The derived index and compaction checkpoints contain message excerpts, so treat ~/.agent-history-mcp/ like your history directories.

Limitations

• The Cursor and OpenCode formats are undocumented or change between versions. Their parsers degrade to skipping, with a note in refresh_history_index.

• Extraction is deterministic, so topics can be noisy. Skill candidates and rule candidates are suggestions to review.

• Cross-agent comparisons and skill outcome numbers are directional, not controlled experiments.

• Session scorecards are rule-based heuristics, not a measure of final code quality.

• The first index build over a large history can take a while. Later refreshes only parse changed units.

• session_recall searches full message text but only the first 500 characters of each tool output, and it re-reads the transcript on every call.

• Compaction checkpoints need the agent's hooks: Claude Code, or Codex 0.150 and later. Gemini CLI, Cursor and OpenCode are not covered.

See docs/ROADMAP.md for the landscape research and planned work.

Benchmarks

Run the local benchmark:

python benchmarks/benchmark_retrieval.py

The benchmark compares:

• full JSONL parsing

• in-memory FTS index build and query

• cold graph index build

• warm graph refresh with unchanged files

• graph search query time

• graph-only candidate expansion versus FTS results

• skill suggestion time

Local Benchmark Results (v0.3, Codex + Claude only)

These numbers were measured on one local Windows laptop against its saved Codex/Claude histories. They are useful as a directional signal, not a universal performance claim.

• Corpus: 43 sessions, 2,434 parsed messages, 2,741,934 message characters

• History files seen: 48

• Query repeat count: 5

• Max results per query: 5

Across these benchmark queries, FTS returned 24 query-result sessions and graph search returned 25. The graph layer added 16 graph-only candidate sessions that keyword search did not return for the same query set.

Interpretation:

• The speed win is not that graph query beats an already-hot FTS query. Hot FTS is extremely fast.

• The practical speed win is warm refresh: repeated MCP calls check unchanged files in about 20 ms instead of reparsing JSONL and rebuilding search state.

• The retrieval win is candidate expansion: graph search can surface related sessions through extracted relationships even when exact keywords differ.

• Graph-only hits are additional evidence-backed candidates, not guaranteed correct answers.

Development

pip install -e .
python -m unittest discover -s tests
python -m py_compile src/agent_history_mcp/*.py src/agent_history_mcp/sources/*.py tests/*.py
python benchmarks/benchmark_retrieval.py

tests/fixtures.py writes realistic synthetic histories for all five agents. New features should be tested against more than one source.

File structure

src/agent_history_mcp/
  server.py        MCP tools and prompts
  cli.py           agent-history CLI and hooks
  model.py         unified session/event model, canonical tools, command signatures
  sources/         claude, codex, gemini, opencode, cursor adapters
  graph.py         incremental SQLite index and graph search
  search.py        FTS5 + fuzzy keyword search and formatting
  handoff.py       handoff briefs and checkpoints
  compaction.py    pre-compaction checkpoints and session_recall
  memory_sync.py   instruction/memory discovery, drift, rule mining, managed-block sync
  analytics.py     session analytics and HTML report
  analysis.py      per-session scorecards and instruction suggestions
  workflows.py     workflow pattern mining
  skills.py        skill candidates, overlap, SKILL.md drafts, skill health
  skill_store.py   installed-skill discovery, usage detection, installation
  redact.py        secret redaction
tests/             unittest suites + multi-agent fixtures
benchmarks/        retrieval benchmark
docs/ROADMAP.md    research notes and next steps

License

MIT