Power your agent
The publisher's own command. Not a PlugMCP endpoint.
Host a copy with our keys and logs.
npx -y [email protected]Claude Code has no install link for a local command. Copy the command below and run it in a terminal.
claude mcp add ai-hist -- npx -y ai-hist@0.59.0Run in a terminal.
{ "mcpServers": { "ai-hist": { "command": "npx", "args": [ "-y", "[email protected]" ] } }}claude_desktop_config.json
Remote URL or a command on your machine? How the two installs differ
Run on PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
LaunchFrom the publisher
ai-hist)Search, resume, and hand off every coding-agent session — across every harness on your machine.
Local memory for Claude Code, Codex, Cursor, Grok, Muse Code, OpenCode, and Devin CLI. Your agent sessions are indexed into one local SQLite database. Search them all at once, jump back into a session with its harness's native resume command, and hand a compact context pack to another agent — or to a teammate's agent — to continue the work.
Local history ingestion, storage, evidence, SDK, CLI and MCP server.
ai-hist search "auth rewrite"
# → matches across every codex/claude/cursor session on this machine
ai-hist resume "auth rewrite"
# → prints `codex resume 29284179-c09f-44f2-b9ec-16f678dc1832`
ai-hist pack "auth rewrite" --tokens 1500
# → a token-budgeted context pack, ready to paste into another agent
ai-hist search "the thing I was working on" finds it, whichever CLI you used.ai-hist pack "the feature" produces a compact context pack; ai-hist resume "the feature" prints the native resume command. Great for switching from Claude to Codex mid-work, or picking up a teammate's session.ai-hist-mcp into Claude Code / Cursor / Codex and the agent can query its own past sessions while it's running — search, session events, tool calls, file edits.ai-history.db through the ai-hist crate, so the two tools share one ingest and agree on what a session is. Pricing and cost stay in burn. See the sourcing ADR.npm install -g ai-hist
ai-hist # first run discovers and indexes your recent sessions
ai-hist search "the thing i was working on"
The bare ai-hist command bootstraps a searchable database on first use: it discovers your most recent local sessions and indexes their evidence, then tells you what it found. It leaves an already-populated database alone. Run ai-hist sync any time you want a full re-ingest rather than the bounded first-run pass.
RelayHistory follows each harness's configured state directory. Set CLAUDE_CONFIG_DIR, CODEX_HOME, or GROK_HOME to relocate Claude Code, Codex, or Grok data; unset or empty values fall back to ~/.claude, ~/.codex, and ~/.grok. Muse Code sessions are read from $XDG_DATA_HOME/muse/sessions (~/.local/share/muse/sessions when XDG_DATA_HOME is unset). OpenCode uses OPENCODE_DB, defaulting to ~/.local/share/opencode/opencode.db. Devin CLI sessions are read from $XDG_DATA_HOME/devin/cli/sessions.db, defaulting to ~/.local/share/devin/cli/sessions.db.
Node.js 20 or 22 is required. npm install pulls a prebuilt native addon for macOS (arm64, x64), Linux glibc ≥ 2.28 and musl (arm64, x64), and Windows (x64, arm64) — no Rust toolchain, compiler, or separate binary download. The glibc floor covers Debian 12, Ubuntu 22.04, Amazon Linux 2023, and RHEL/Alma 9; releases are smoke-tested on node:22-bookworm-slim and ubuntu:22.04.
Rust embedders depend on the ai-hist crate on crates.io (SessionStore::open / sync / sessions / session / changes_since) on its default features — no raw database connection, no feature flags. Read docs/sourcing-sdk.md, the embedder guide, alongside crates/ai-hist/README.md, and start from examples/rust-consumer, a standalone Cargo project that stages the fixture corpus into a throwaway HOME, syncs, and prints per-session usage totals by model. CI builds that example against the workspace crate on every pull request and against the published crate nightly, and diffs the crate's public API against crates/ai-hist/public-api.txt.
ai-hist search "auth rewrite" # full-text search across every harness
ai-hist sessions list # your most recent sessions, newest first
ai-hist resume "auth rewrite" # print the native resume command
ai-hist pack "auth rewrite" --tokens 1500 # compact context to hand another agent
ai-hist sessions tree <harness> <id> # walk the parent/subagent tree
ai-hist sessions relationships <harness> <id> # which sessions spawned which
ai-hist recent 20 # the last N prompts, newest first
ai-hist stats # how much history is indexed, by source and project
<harness> is the session's source — claude, codex, cursor, grok, muse, opencode, or devin — and is required alongside the ID, because session IDs collide across providers. ai-hist sessions list prints both.
ai-hist resume prints a native resume command for Claude Code, Codex, Cursor, Grok, and Muse Code sessions. OpenCode and Devin CLI sessions are searchable and packable, but have no native resume command to print, so use ai-hist pack to carry that context forward instead.
OpenCode is read from whichever of its two stores the machine has: the SQLite
opencode.db that current releases write (OPENCODE_DB), or the older JSON
tree under storage/ (OPENCODE_STORAGE_DIR). Either way you get the full
turn — text, tool calls and their results, file edits, per-message token
counts, the provider-qualified model, why the turn stopped, compaction
boundaries, and the link from a subagent session to the session that spawned
it.
npx -y ai-hist-mcp
Exposes search_history, list_sessions, get_session_events, get_session_tool_calls, get_session_file_edits, get_session_tree, history_stats, and more as MCP tools. list_relay_agents lists live Agent Relay participants (not history) through the local desktop app's Unix socket. relay_status reports whether the local session hosting the MCP server is reachable; join_relay makes that session reachable by teammates and agents, with optional public name and description; leave_relay removes it again. Wire it into any MCP-capable agent so it can query its own history and participate on the relay mid-session.
Workspace handoffs need no installed receiver skill. create_handoff(intent)
returns one pointer whose existing intent field is itself the continuation
prompt: it tells the receiving agent to call
resume_handoff(source=..., session_id=...) through the ai-hist MCP and then
continue the original intent. Send that exact intent as the Agent Relay DM
text and the full pointer as kind="handoff" metadata; do not add a second text
field or inline the transcript. Before sending, call resume_handoff once with
the pointer to verify that Agent Relay desktop has uploaded the session to the
current workspace.
The MCP server reads local history only, plus any source plugins named by AI_HIST_PLUGIN_CONFIG. The relay roster, status, join, and leave tools are also local: they use AGENT_RELAY_SOCKET, then ~/.agentworkforce/desktop/relay-socket, then the platform socket defaults. They never load cloud credentials. If the desktop app is absent, the tools return a non-fatal instruction to open it or use the Agent Relay MCP. A connected desktop gets a 15-second local response deadline. Read-only roster and status calls that exceed it report timeout instead of claiming the app is absent. A sent join_relay or leave_relay mutation reports indeterminate_result because the desktop may have completed it, and directs the caller to relay_status. If the app setting disallows self-registration, join_relay returns the desktop's readable not_allowed guidance.
Cached reads such as search, recent, sessions list, resume, pack, and stats,
and acquisition commands such as discovery, hydration, and sync, take a location scope: --local (the default), --remote, or --all.
ai-hist sessions discover --remote --config history.json # explicitly installed source plugins
ai-hist sync --all --config history.json # local history plus selected plugins
ai-hist search "auth rewrite" --all # search both at once
Commands that address one session by identity do not take a scope, and reject one rather than guessing — they already name a single session. They split by how they take that identity:
ai-hist sessions tree SOURCE SESSION_ID # also relationships, tools, edits, markers, usage
ai-hist session SESSION_ID [--source SOURCE] # session and events take the id alone
ai-hist events SESSION_ID [--source SOURCE] # --source only narrows a reused id
sessions tree, sessions relationships, sessions tools, sessions edits, sessions markers and sessions usage require both positionals and fail without SOURCE. session and events take SESSION_ID on its own and reject a SOURCE positional; pass --source only to disambiguate an id two harnesses happen to share. (sessions hydrate also takes SOURCE SESSION_ID, but it is an acquisition command and does accept a scope.)
Install @relayhistory/provider-sources and configure it explicitly for
remote provider acquisition. Its connectors reuse sign-ins you already have: claude-web lists your claude.ai/code sessions from the Claude Code CLI's stored OAuth token, and codex-cloud lists Codex cloud tasks through codex cloud list --json. With no connector configured, --remote fails loudly rather than silently falling back to local. See remote connectors.
ai-hist export --selection FILE writes a selected slice of history as NDJSON for your own tooling. See export.
Team uploads come from the Agent Relay desktop app, not from this repository.
ai-histfull, partial, or shallow_only per session, so you can tell thin coverage from a thing that never happened. Where a harness records less than the others, the gap is named. Cursor transcripts carry the assistant's prose and every tool call, but no tool output, model id, token usage or timestamp field — those are reported as unavailable, and a turn whose injected <timestamp> tag cannot be read is stamped from the file mtime with CURSOR_TIMESTAMP_FROM_MTIME. Older Grok builds log no per-turn billing tokens, so their only token fact is a context-window proxy, and hydration says so; newer builds' per-turn usage breakdown is recorded beside it, never added to it. The per-field detail is in the session catalog.pack and resume are first-class commands, not afterthoughts.Docs: getting started · architecture · source plugins · export · migration
Local history ingestion, storage, evidence, SDK, CLI and MCP server.
{ "mcpServers": { "ai-hist": { "command": "npx", "args": [ "-y", "[email protected]" ] } }}Tools
No tool list yet. Remote servers get one after the first health check.
FAQ
Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.
No required environment variable is listed on this record.
Ai Hist runs locally over stdio.
Last checked 2026-11-14. Local history ingestion, storage, evidence, SDK, CLI and MCP server.