agent-history-mcp

A tiny, generic MCP server that does semantic search over your local AI-agent session logs and returns the most relevant chunks — never whole transcripts.

Most "search my Claude history" tools are hardcoded to ~/.claude/projects and do keyword matching. This one is multi-agent (Claude Code + Hermes out of the box, plus any extra JSONL log dir you point it at) and semantic (local embeddings + vector similarity), so you can ask what you meant rather than what you typed.

What it searches

Agent	Source	Notes
Claude Code	~/.claude/projects/*/*.jsonl	One session per file.
Hermes	~/.hermes/state.db (SQLite)	Opened read-only.
Anything else	extraRoots in config	Any directory of *.jsonl session files.

Everything runs locally. The embedding model (Xenova/all-MiniLM-L6-v2, ~25 MB) downloads once on first run and is cached; after that it works offline. The index and model cache live in ~/.agent-history-mcp/ — nothing about your conversations ever leaves your machine, and none of it is part of this repo.

Install

# from npm (once published)
claude mcp add agent-history -s user -- npx -y agent-history-mcp

# or from a local checkout
npm install
npm run build
claude mcp add agent-history -s user -- node /absolute/path/to/agent-history-mcp/dist/index.js

Any MCP client works — the config is just a stdio command:

{
  "mcpServers": {
    "agent-history": { "command": "npx", "args": ["-y", "agent-history-mcp"] }
  }
}

Tools

• search(query, k?=8, agent?, project?) — semantic search; returns ranked chunks, each with a chunkId, agent, session id, cwd, and timestamp.
• get_context(chunkId, radius?=2) — expand a hit into its neighboring chunks from the same session (bounded — still not the whole transcript).
• list_agents() — which stores are present locally and how many sessions/chunks are indexed.

Configuration (optional)

Create ~/.agent-history-mcp/config.json:

{
  "claudeRoot": "~/.claude/projects",
  "hermesDb": "~/.hermes/state.db",
  "extraRoots": [{ "agent": "codex", "dir": "/path/to/codex/sessions" }],
  "model": "Xenova/all-MiniLM-L6-v2",
  "maxChunkChars": 1200
}

Set AGENT_HISTORY_HOME to relocate the cache/index directory.

How it works

1. Discover sessions cheaply (file mtime/size, or SQLite row counts) — no content read.
2. Chunk each changed session into role-prefixed, size-bounded chunks.
3. Embed each chunk locally (mean-pooled, L2-normalized → cosine = dot product).
4. Cache per session as a sidecar JSON under ~/.agent-history-mcp/index/; only new/changed sessions are re-embedded on later runs.
5. Search by embedding the query and brute-forcing cosine over the in-memory vectors — exact and plenty fast at personal scale.

No server, no external vector DB, no API keys.

Roadmap

Today it's local-only. The plan is to run it as a small daemon on every machine and search your entire cross-device agent memory over your Tailscale tailnet — federated, private, WireGuard-encrypted, no public ports. See ROADMAP.md.

License

MIT