Skip to main content
Glama
AI Agent History RAG MCP Server

AI Agent History RAG MCP Server

by velenzaboc

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

history-ragd start --config /app/history-ragd.json

Docker owns process restart; /live is its healthcheck.

macOS

scripts/install-launchd.sh

Per-user LaunchAgent runs history-ragd supervise.

Linux

scripts/install-systemd.sh

Per-user systemd unit runs history-ragd supervise.

Windows

scripts/install-windows.ps1

Per-user logon task runs history-ragd.exe supervise.

MCP

scripts/history-rag-mcp-native.sh

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-ragd

Production 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

~/.claude/projects

Codex

~/.codex/sessions

Gemini

~/.gemini/tmp

Antigravity

~/.gemini/antigravity

ChatGPT export

~/.claude-history-rag/imports/chatgpt

Claude app export

~/.claude-history-rag/imports/claude-app

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:local

The 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.sh

See launchd operator notes.

Linux

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.sh

See systemd operator notes.

Windows

.\scripts\install-windows.ps1 -HistoryRagdPath "$PWD\bin\history-ragd.exe"
.\scripts\uninstall-windows.ps1

See 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/live

GET /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/health

MCP 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.sh

Troubleshooting

  • /live fails: inspect the platform service manager and its native process.

  • /live succeeds but /health returns 503: confirm Spanner reachability and that all six watcher roots are available to the service user.

  • /health returns 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 tools
get_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

    A4.1/5.0

    Scored across 5 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern with underscores (get_* and search_*), making them predictable and clear.

    Tool Count5/5

    Five tools cover the necessary functionality for a RAG memory system without being too few or too many, earning each tool's place.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Provides 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.
      8
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides AI coding agents with persistent, graph-connected memory across projects, enabling cross-project context retrieval via synaptic connections and hybrid search.
      6 npm
      8
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides 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.
      8
      MIT