# agent-history-mcp

A tiny, generic [MCP](https://modelcontextprotocol.io) 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

```bash
# 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:

```json
{
  "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`:

```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](https://tailscale.com) tailnet** —
federated, private, WireGuard-encrypted, no public ports. See [ROADMAP.md](ROADMAP.md).

## License

MIT