AI Agent History RAG MCP Server
This MCP server exposes search and status tools over ingested AI assistant conversation history.
Search conversation history by natural-language query with project, date, hybrid-search, analysis, synthesis, and debug options.
Find file changes by file path, semantic query, project, operation type, and date range.
Summarize specific or recent conversation sessions, optionally filtered by project.
Check RAG index status, including indexed chunks, projects, watched/pending files, health, and cache statistics.
Check MCP server health and detailed metrics covering database, indexing, performance, cache, embedder, file watcher, errors, and configuration.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@AI Agent History RAG MCP Server search my Claude Code sessions for the fix I applied to the payment service"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
AI Agent History RAG
AI Agent History RAG is a native Go daemon and MCP proxy for searchable history from Claude Code, Codex, Gemini, Antigravity, ChatGPT exports, and Claude app exports. Production storage is Cloud Spanner with a registered Vertex embedding model. The daemon has no local-storage or unauthenticated production mode.
Supported native entrypoints
Platform | Operator entrypoint | Lifecycle |
Container |
| Docker owns process restart; |
macOS |
| Per-user LaunchAgent runs |
Linux |
| Per-user systemd unit runs |
Windows |
| Per-user logon task runs |
MCP |
| Authenticated STDIO proxy to the loopback daemon. |
The repository's Compose file is retained as a compatibility artifact and is not a supported native production operator entrypoint. Use the Dockerfile or a platform installer until that artifact is separately migrated.
Related MCP server: hive-memory
Build
go build -o bin/history-ragd ./cmd/history-ragd
go test ./...For a Windows binary from another platform:
CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build -o bin/history-ragd.exe ./cmd/history-ragdProduction contract
Every service installer validates the following values before registering a native process. Deployment identities are inputs; never place real values in repository files.
CLAUDE_HISTORY_RAG_RUNTIME_CONTRACT=production
CLAUDE_HISTORY_RAG_STORAGE_BACKEND=spanner
CLAUDE_HISTORY_RAG_SPANNER_PROJECT=<project>
CLAUDE_HISTORY_RAG_SPANNER_INSTANCE=<instance>
CLAUDE_HISTORY_RAG_SPANNER_DATABASE=<database>
CLAUDE_HISTORY_RAG_SPANNER_EMBEDDING_MODE=spanner
CLAUDE_HISTORY_RAG_SPANNER_EMBEDDING_MODEL_ID=ConversationEmbeddingModel
CLAUDE_HISTORY_RAG_EMBEDDING_PROVIDER=vertex
CLAUDE_HISTORY_RAG_EMBEDDING_MODEL=gemini-embedding-001
CLAUDE_HISTORY_RAG_EMBEDDING_DIMENSION=3072
CLAUDE_HISTORY_RAG_STATUS_SERVER_HOST=127.0.0.1
CLAUDE_HISTORY_RAG_STATUS_SERVER_PORT=4680
CLAUDE_HISTORY_RAG_CREDENTIALS_SOURCE=application_default
CLAUDE_HISTORY_RAG_CREDENTIALS_PROFILE=impersonated_service_account
CLAUDE_HISTORY_RAG_CREDENTIALS_IDENTITY=<service-account-email>
CLAUDE_HISTORY_RAG_SERVER_PSK=<bearer-secret>The host runtime uses the well-known, owner-protected impersonated ADC carrier.
Credential-file overrides, emulator configuration, and ambient Cloud SDK
configuration are rejected. In particular, leave GOOGLE_APPLICATION_CREDENTIALS,
CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE, CLOUDSDK_CONFIG, and
SPANNER_EMULATOR_HOST unset.
The carrier may retain the legacy authorized_user source or use a
device-bound service_account source. The latter is accepted only inside the
validated impersonation carrier; its target identity, scope, quota project,
source shape, and owner-only file ACL are checked before any Google client is
constructed. Do not commit a carrier, private key, refresh token, or machine
path to this repository.
Source roots
The daemon watches exactly these six source families. Platform installers create missing directories and generate owner-protected native configuration.
Source | Default root |
Claude Code |
|
Codex |
|
Gemini |
|
Antigravity |
|
ChatGPT export |
|
Claude app export |
|
ChatGPT and Claude app exports belong in their respective drop folders. The watcher preserves source identity and rejects unsafe path changes.
Native workstation deployments pin eight roots: the six defaults above plus stable Claude and Codex provider-profile parent directories. This lets newly created profiles become visible without replacing the persisted root set; non-transcript credential JSON remains outside the registry's source grammar.
On first enablement, the daemon records every already-present recognized source path as a permanent exclusion and persists a per-host cutoff before it can upload anything. Only complete conversations whose source-record timestamps are at or after that cutoff are captured. Existing paths, copied older sessions, and records without provable source timestamps are never backfilled.
Container
Copy .env.docker.example to a private environment file, replace each
placeholder, then build and run the native image:
docker build --tag history-ragd:local .
docker run --rm --env-file .env.docker -p 4680:4680 history-ragd:localThe container binds 0.0.0.0:4680 only inside its network namespace and
requires authentication. Its Docker healthcheck calls /live; it does not
pretend a missing Spanner dependency is ready. Mount persistent source and state
volumes when operating beyond a smoke test.
Host service installation
Every Velenza workstation maps its Meridian root at ~/Meridian ($HOME/Meridian) and checks out this repository at ~/Meridian/repos/ai-agent-history-rag-mcp with the compiled binary at ~/Meridian/repos/ai-agent-history-rag-mcp/bin/history-ragd. Each workstation authenticates directly as its own kopia-<host>@jeeves-486102.iam.gserviceaccount.com identity from ~/.config/no13-backup/kopia-<host>.json under CLAUDE_HISTORY_RAG_CREDENTIALS_PROFILE=device_service_account (accepting either a service_account key or an external_account X.509 certificate config without a synthetic credential-home directory or per-host flags).
Host ingestion services bind only 127.0.0.1:4680; do not open that listener to the
network. Build the binary first, export CLAUDE_HISTORY_RAG_SERVER_PSK, then install from ~/Meridian/repos/ai-agent-history-rag-mcp.
macOS
cd ~/Meridian/repos/ai-agent-history-rag-mcp
CLAUDE_HISTORY_RAG_SERVER_PSK="$CLAUDE_HISTORY_RAG_SERVER_PSK" HISTORY_RAGD_BIN="$PWD/bin/history-ragd" ./scripts/install-launchd.sh
./scripts/uninstall-launchd.shLinux
cd ~/Meridian/repos/ai-agent-history-rag-mcp
CLAUDE_HISTORY_RAG_SERVER_PSK="$CLAUDE_HISTORY_RAG_SERVER_PSK" HISTORY_RAGD_BIN="$PWD/bin/history-ragd" ./scripts/install-systemd.sh
./scripts/uninstall-systemd.shWindows
.\scripts\install-windows.ps1 -HistoryRagdPath "$PWD\bin\history-ragd.exe"
.\scripts\uninstall-windows.ps1See Windows operator notes. Windows Task Scheduler validation requires a Windows host; the repository cross-build verifies only that the native executable can be produced.
Liveness and readiness
For search against an existing corpus, the explicit read-only host mode binds
127.0.0.1:4681 and never starts a watcher. Set CLAUDE_HISTORY_RAG_READ_ONLY=true
and CLAUDE_HISTORY_RAG_STATUS_SERVER_PORT=4681 in both daemon and MCP environments.
The device_service_account credential profile uses the existing device source
nested in private well-known ADC, bound to its exact source email, without
changing the carrier or impersonating its target. See launchd setup.
Read-only readiness reports storage only, with no ingestion claim.
GET /live is intentionally unauthenticated and answers only whether the
process listener is alive:
curl --fail http://127.0.0.1:4680/liveGET /health and GET /status require a bearer credential. They are readiness
checks: they return 200 only when both Spanner storage and the source watcher
are ready, otherwise 503. They never expose credentials or source paths.
curl --fail -H "Authorization: Bearer $CLAUDE_HISTORY_RAG_SERVER_PSK" \
http://127.0.0.1:4680/healthMCP proxy
Use the native STDIO proxy only after the loopback daemon is running with the same production contract:
./scripts/history-rag-mcp-native.sh --validate-only
./scripts/history-rag-mcp-native.shTroubleshooting
/livefails: inspect the platform service manager and its native process./livesucceeds but/healthreturns 503: confirm Spanner reachability and that all six watcher roots are available to the service user./healthreturns 401: supply the configured bearer secret; do not disable authentication to diagnose the issue.Installer rejects credentials: remove the forbidden ambient credential and emulator overrides, then verify the well-known impersonated ADC carrier.
A source root is rejected: replace links with an owned real directory; the watcher intentionally refuses identity changes.
Verification
./scripts/docs-native-contract.test.sh
go test -race ./internal/history/config ./internal/history/watch ./internal/history/api ./cmd/history-ragd
go vet ./...
go build ./...
go test ./...The exact native contract and its bounded API surface are recorded in docs/NATIVE_COMPATIBILITY_CONTRACT.md.
Certificate workload federation for a central search container
The explicit workload_identity_federation profile accepts the host's existing
X.509 external_account carrier selected process-locally by
GOOGLE_APPLICATION_CREDENTIALS. Set
CLAUDE_HISTORY_RAG_CREDENTIALS_IDENTITY to this container's scoped search identity,
and CLAUDE_HISTORY_RAG_CREDENTIALS_AUDIENCE to the exact provider resource URI.
The carrier's STS endpoint and service impersonation URL must be canonical
Google mTLS endpoints, with the carrier impersonation URL naming exactly the
declared search identity. Leave CLAUDE_HISTORY_RAG_CREDENTIALS_BASE_IDENTITY
unset; this profile never mints a shared host token. The certificate
configuration, certificate and key must
be explicit owner-only regular files; executable, file-token and ambient
certificate discovery are refused. The daemon uses the already-pinned modern
Google auth SDK for direct X.509 federation into the scoped target. Mount only
this container's own service carrier and certificate, with provider subject
access granted only to its corresponding search identity. Existing profiles
and local capture remain unchanged.
A read-only container may set container_mode:true, read_only:true,
listen:"127.0.0.1:4681", auth_enabled:true and an empty watch_roots list.
It starts no watcher and requires an existing corpus. Preserve workstation
capture services and their forward-only cutoffs. Deploy the native daemon and
scripts/history-rag-mcp-native.sh side by side with bash, curl and jq. The proxy
calls the co-located daemon's validate-workload-credentials command before
serving MCP, sharing the Go credential validator without a shell credential
parser. This command validates local configuration only; it neither exchanges
tokens nor proves backend access. Apply the same environment to the daemon and
proxy. Keep runtime credential mounts read-only and PSK state private; never
embed credentials or PSKs in an image.
Verification and delivery
During implementation and repair, run focused local checks for touched behavior
and direct dependencies on the working machine (any remote run uses
/home/lab/Meridian/bin/velenza-remote-guard.py --host <arcserver1|arcserver2|arcserver4>,
never arcserver3). When the complete submission candidate is ready and
independent acceptance passes, .github/workflows/ci.yml runs the full Go,
shell, and mutation test suite on push, pull_request, and merge_group.
Available Tools
5 toolsget_index_statusA
Get status of the RAG index.
Use when user asks about memory system health or
why something isn't being found.
Returns:
Dict with index statistics including:
- total_chunks: Number of indexed chunks
- projects_indexed: Number of unique projects
- watched_files: Number of files being tracked
- pending_files: Number of files in queue for processing
- status: Overall health status
- cache_stats: Search cache statistics (if enabled)
Inputs: no named parameters.
get_server_statusA
Get comprehensive MCP server status and health information.
Use when you need to check server health, performance metrics,
indexing progress, or debug issues with the memory system.
Args:
detail_level: "basic" for summary info, "full" for detailed metrics
including performance, cache stats, and errors
Returns:
Dict with comprehensive server status including:
- server: Version, uptime, PID, platform info
- health: Overall status (healthy/degraded/unhealthy) and component checks
- database: Chunk counts, size (full detail only)
- indexing: Progress, files pending/indexed/failed (full detail only)
- performance: Memory, CPU, query metrics (full detail only)
- cache: Hit rates, size (full detail only)
- embedder: Model info, loaded status (full detail only)
- file_watcher: Running status, queue info (full detail only)
- errors: Recent errors and counts (full detail only)
- configuration: Current settings (full detail only)
Inputs: detail_level.
get_session_summaryA
Get summary of conversation session(s).
Use for:
- "What did we work on in the last session?"
- "Summarize our recent conversations"
Args:
session_id: Specific session ID, or None for recent
project_filter: Limit to specific project
count: Number of sessions to summarize
Returns:
Dict with session summaries
Inputs: count, session_id, project_filter.
search_conversationsA
Search conversation history for relevant context.
Use this to find:
- Previous discussions about a topic
- Decisions made in earlier sessions
- Context that was compacted away
Args:
query: Natural language query
project_filter: Limit to specific project path
date_from: Inclusive lower timestamp bound. Accepts ISO-8601 datetime
or date-only values such as 2026-06-13.
date_to: Inclusive upper timestamp bound. Accepts ISO-8601 datetime
or date-only values such as 2026-06-15.
limit: Maximum results (default 5, min 1, max 50)
use_hybrid: Use hybrid search (vector + BM25) for better results
(default True)
enable_analysis: Enable query analysis and result evaluation for
improved relevance (default True). Adds 'analysis' and 'evaluation'
to response.
enable_synthesis: Enable result synthesis to combine multiple results
into a coherent summary (default False). Adds 'synthesis' to response
with key_points and deduplicated content.
include_debug: Include detailed timing metrics and decision tracking
in response (default False). Useful for debugging and performance
analysis. Adds 'metrics' to response.
Returns:
Dict with results list and metadata. When enable_analysis=True, includes:
- analysis: Query intent, detected technologies, key terms
- evaluation: Relevance score, completeness assessment
When enable_synthesis=True, includes:
- synthesis: Primary content, key points, code snippets
When include_debug=True, includes:
- metrics: Timing data (query_analysis_ms, search_ms, etc.), decisions made
Inputs: query (required), limit, date_to, date_from, +5 more.
search_file_changesA
Find file modifications in conversation history.
Use this when user asks:
- "What did we change in auth.dart?"
- "Show me recent edits to the config files"
- "What files did we create?"
Args:
file_path: Filter by file path (supports partial match)
query: Semantic query about changes
project_filter: Limit to specific project
operation_filter: Filter by "edit" or "write"
date_from: Inclusive lower timestamp bound. Accepts ISO-8601 datetime
or date-only values such as 2026-06-13.
date_to: Inclusive upper timestamp bound. Accepts ISO-8601 datetime
or date-only values such as 2026-06-15.
limit: Maximum results (default 10, min 1, max 50)
Returns:
Dict with file change results
Inputs: limit, query, date_to, date_from, +3 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Most tools have distinct purposes, but get_index_status and get_server_status overlap in indexing and database information, potentially causing confusion. Detailed descriptions help differentiate them.
All tool names follow a consistent verb_noun pattern with underscores (get_* and search_*), making them predictable and clear.
Five tools cover the necessary functionality for a RAG memory system without being too few or too many, earning each tool's place.
The tool set covers monitoring and search operations well, but lacks a tool to retrieve full conversation transcripts or manage indexing, which are minor gaps.
Maintenance
Related MCP Connectors
Persistent memory for AI agents. Search, store, and recall across sessions.
Shared memory for coding agents. Stop re-explaining your codebase every session.
Universal persistent memory and knowledge retrieval layer for AI agents and LLMs.
Universal memory for AI agents and tools. Save, organize and search context anywhere.
Related MCP Servers
- AlicenseAqualityDmaintenanceProvides persistent memory for AI agents using hybrid search (vector embeddings + BM25) with neural reranking, enabling storage and retrieval of insights, debugging solutions, and patterns across coding sessions.8MIT
- AlicenseNot gradedqualityDmaintenanceProvides AI coding agents with persistent, graph-connected memory across projects, enabling cross-project context retrieval via synaptic connections and hybrid search.6 npm8MIT
- AlicenseNot gradedqualityDmaintenanceProvides long-term memory for AI coding agents, enabling them to remember, search, and organize information across sessions and platforms like Claude Code, ChatGPT, and Cursor.8MIT
- AlicenseNot gradedqualityBmaintenanceProvides persistent long-term memory (semantic RAG) for AI coding assistants, enabling them to store and semantically search code and documentation across chat sessions without token limits.5MIT