AI Agent History RAG MCP Server

An MCP (Model Context Protocol) server that provides RAG (Retrieval-Augmented Generation) over AI coding agent and chat history (Claude Code, Codex, Gemini CLI, Antigravity, ChatGPT exports, and Claude app exports). It solves the compaction problem where long sessions lose context by providing persistent, searchable memory across all sessions and tools.

Features

• Multi-Agent History: Ingests Claude Code, Codex, Gemini CLI, Google Antigravity, ChatGPT exports, and Claude app exports

• Semantic Search: Find relevant context from past conversations using natural language queries

• Hybrid Search: Combines vector similarity and BM25 full-text search with RRF reranking

• File Change Tracking: Search for specific file modifications across all sessions

• Session Summaries: Retrieve summaries of past sessions

• Real-time Indexing: Automatically watches and indexes new conversation data

• Incremental Updates: Only processes new content, not entire files

• Multi-Machine Support: Centralize history from multiple machines to a single server

• Offline Resilience: Client mode queues uploads when server is unavailable

• Client Registry: Track connected clients, last uploads, and reindex status

• Server-Triggered Reindex: One click to reindex server + notify clients

• Diagnostic Tool: Built-in doctor command for troubleshooting (cross-platform)

• Installation Wizard: Interactive setup with automatic verification

Related MCP server: hive-memory

Supported Sources

• Claude Code: ~/.claude/projects/**/*.jsonl

• Codex: ~/.codex/sessions/**/*.jsonl

• Gemini CLI: ~/.gemini/tmp/**/chats/*.json and ~/.gemini/tmp/**/logs.json

• Google Antigravity: ~/.gemini/antigravity/brain/**/.system_generated/logs/transcript_full.jsonl with legacy ~/.gemini/antigravity/conversations/*.pb fallback

• ChatGPT web/Desktop: official export conversations.json dropped under ~/.claude-history-rag/imports/chatgpt/**/conversations.json

• Claude web/Desktop app: official export conversations.json dropped under ~/.claude-history-rag/imports/claude-app/**/conversations.json

All sources are ingested fully (user, assistant, tool calls, and tool outputs). The only difference between sources is how we parse their on-disk formats and where we watch for files.

ChatGPT and Claude app do not currently provide a stable supported local transcript folder comparable to Claude Code/Codex/Gemini CLI. Their watchers are live drop-folder watchers for official exports: export from the app/web UI, extract the ZIP, and place the extracted folder under the configured import directory. The watcher indexes new or replaced conversations.json files automatically.

About diffs and file changes

Diffs are ingested when the tool provides them:

• Codex: apply_patch tool calls include the patch diff in arguments.

• Gemini CLI: tool calls may include diffs in args.patch or resultDisplay.

• Claude Code: tool logs include file operations and edit snippets, but full diffs are not guaranteed unless the tool output contains them.

We always store full tool outputs; no truncation.

Architecture Overview

The system supports two deployment modes:

Single-Machine Mode (Default)

Everything runs locally - embeddings, storage, and search all happen on one machine.

┌─────────────────────────────────────────────────────────────┐
│                     Local Machine                            │
│                                                              │
│  Claude Code ──► MCP Server ──► Daemon ──► LanceDB          │
│                                    │                         │
│                              Embeddings (Ollama/OpenAI API) │
└─────────────────────────────────────────────────────────────┘

Multi-Machine Mode (Client/Server)

Consolidate conversation history from multiple machines to a central server:

┌─────────────────────────┐     ┌─────────────────────────┐
│      Machine 1          │     │      Machine 2          │
│                         │     │                         │
│  Claude Code            │     │  Claude Code            │
│       │                 │     │       │                 │
│       ▼                 │     │       ▼                 │
│  MCP Client ────────────┼─────┼─► MCP Client            │
│  (chunks only)          │     │  (chunks only)          │
└─────────────────────────┘     └─────────────────────────┘
              │                           │
              │      HTTP POST            │
              ▼                           ▼
┌─────────────────────────────────────────────────────────────┐
│                    Central Server                            │
│                                                              │
│  API Endpoints ◄── Status Server (port 4680)                │
│       │                                                      │
│       ▼                                                      │
│  Embedder ──► LanceDB ──► Search API                        │
│  (Ollama/vLLM/OpenAI)                                       │
└─────────────────────────────────────────────────────────────┘

Benefits of multi-machine mode:

• Search across all your machines' conversation history from any machine

• Centralized embeddings - only one machine needs GPU/compute resources

• Offline resilience - clients queue uploads when server is unavailable

• Catch-up sync - reconnecting clients automatically upload missed content

Installation

Prerequisites

The server uses an OpenAI-compatible embeddings API for generating vectors. This works with:

• Ollama (recommended for local use)

• vLLM

• text-embeddings-inference

• OpenAI API

• LiteLLM

• Any other service implementing the /v1/embeddings endpoint

Using uv (recommended)

# Clone the repository
git clone https://github.com/bmeyer99/claude-history-rag-mcp.git
cd claude-history-rag-mcp

# Install all dependencies (both server and client)
uv sync --all-extras

# Or install only what you need:
uv sync --extra server   # Server mode (embeddings + storage)
uv sync --extra client   # Client mode (lightweight, uploads only)

Using pip

# Full installation
pip install -e ".[all]"

# Server only
pip install -e ".[server]"

# Client only (lightweight)
pip install -e ".[client]"

Quick Start

Native MCP Install

The retired Python wizard is not a supported installation path. Configure the daemon with the platform service scripts, then install the production MCP STDIO proxy only through its native, production-gated installer. After exporting the complete production environment shown below, write the proxy into a JSON client config with:

./scripts/history-rag-mcp-native.sh \
  --install-json "$HOME/.claude.json" \
  "$(pwd)/scripts/history-rag-mcp-native.sh"

The native installer validates the same production shape as the daemon before writing the client entry. It preserves unrelated JSON keys, writes an owner-only file, and never embeds the daemon PSK. An impersonated ADC profile is accepted only when its nested source is a keyless authorized_user profile with no private-key fields, delegates, target drift, symlink, or permissive file mode. JSON clients with a different wrapper shape must be migrated explicitly; the installer does not guess or rewrite them.

Docker (Server Only)

1. Start Ollama on your host machine:

   ollama serve
   ollama pull bge-m3

2. Start the container:

   docker compose up -d

Access the dashboard at http://localhost:4680/dashboard

The container connects to Ollama on your host via host.docker.internal. On Linux with custom Docker networks, host.docker.internal may not resolve—either keep the default bridge network or point the embedding URL to your host’s IP address.

Configuration: Create a .env file to customize the embedding server:

# Use a different embedding server (default: host.docker.internal:11434)
CLAUDE_HISTORY_RAG_EMBEDDING_BASE_URL=http://192.168.1.100:11434/v1

PSK Authentication (recommended behind TLS):

# Enable PSK auth and set a server key override
CLAUDE_HISTORY_RAG_AUTH_ENABLED=true
CLAUDE_HISTORY_RAG_SERVER_PSK=change-me

Use the environment variable reference below for the full option list.

Client machines can connect to this Docker server:

export CLAUDE_HISTORY_RAG_SERVER_URL=http://docker-host:4680
uv run ai-agent-history-rag-daemon start

Single-Machine Setup (Default)

1. Start Ollama (or another embeddings server):

   ollama serve
   ollama pull nomic-embed-text

2. Start the daemon:

   uv run ai-agent-history-rag-daemon start

3. Configure Claude Code (see Configuration section below)

Multi-Machine Setup

On the Central Server

1. Start the embeddings server (Ollama example):

   ollama serve
   ollama pull nomic-embed-text

2. Start the daemon in server mode (no SERVER_URL set):

   # Bind to all interfaces to accept remote connections
   CLAUDE_HISTORY_RAG_STATUS_SERVER_HOST=0.0.0.0 \
   uv run ai-agent-history-rag-daemon start

3. The server exposes:

   • Dashboard: http://server-ip:4680/dashboard

   • API: http://server-ip:4680/api/

On Each Client Machine

1. Configure to point to the server:

   export CLAUDE_HISTORY_RAG_SERVER_URL=http://192.168.1.100:4680
   export CLAUDE_HISTORY_RAG_MACHINE_ID=my-laptop  # Optional, defaults to hostname
   export CLAUDE_HISTORY_RAG_CLIENT_NAME="Brandon MacBook"  # Optional label

2. Start the daemon in client mode:

   uv run ai-agent-history-rag-daemon start

3. Configure Claude Code to use the MCP server (see Configuration section)

Velenza Production Spanner Runtime

The Velenza production daemon runs in server mode against the shared Spanner DB. It must be explicit: do not rely on the local LanceDB default for production status or search.

export CLAUDE_HISTORY_RAG_RUNTIME_CONTRACT=production
export CLAUDE_HISTORY_RAG_STORAGE_BACKEND=spanner
export CLAUDE_HISTORY_RAG_SPANNER_PROJECT=<your-gcp-project>
export CLAUDE_HISTORY_RAG_SPANNER_INSTANCE=<your-spanner-instance>
export CLAUDE_HISTORY_RAG_SPANNER_DATABASE=ai-agent-history-rag
export CLAUDE_HISTORY_RAG_SPANNER_EMBEDDING_MODE=spanner
export CLAUDE_HISTORY_RAG_SPANNER_EMBEDDING_MODEL_ID=ConversationEmbeddingModel
export CLAUDE_HISTORY_RAG_EMBEDDING_PROVIDER=vertex
export CLAUDE_HISTORY_RAG_EMBEDDING_MODEL=gemini-embedding-001
export CLAUDE_HISTORY_RAG_EMBEDDING_DIMENSION=3072
export CLAUDE_HISTORY_RAG_STATUS_SERVER_HOST=127.0.0.1
export CLAUDE_HISTORY_RAG_STATUS_SERVER_PORT=4680
export CLAUDE_HISTORY_RAG_CREDENTIALS_SOURCE=application_default
export CLAUDE_HISTORY_RAG_CREDENTIALS_PROFILE=impersonated_service_account
export CLAUDE_HISTORY_RAG_CREDENTIALS_IDENTITY=<dedicated-runtime-service-account>
export GOOGLE_APPLICATION_CREDENTIALS=<path-to-keyless-impersonated-adc-profile.json>
export GOOGLE_CLOUD_PROJECT=<your-gcp-project>
uv run ai-agent-history-rag-daemon start

These are deployment-specific and this repository is public, so it ships placeholders rather than any real project or instance. scripts/install-launchd.sh reads the same variables from your environment and fails with a readable message if they are unset, instead of generating a launch agent pointed at somebody else's project.

The launchd source at scripts/com.ai-agent-history-rag.daemon.plist.template pins the same contract, including:

• watch roots: ~/.claude/projects, ~/.codex/sessions, ~/.gemini/tmp, ~/.gemini/antigravity, ~/.claude-history-rag/imports/chatgpt, and ~/.claude-history-rag/imports/claude-app

• state/auth roots: ~/.claude-history-rag/*.json

• credentials: a short-lived, exact-target impersonated ADC profile for the local daemon; GOOGLE_APPLICATION_CREDENTIALS is only the standard ADC carrier and the runtime rejects service-account-key JSON, private-key fields, target drift, and broad gcloud-user fallback

On another workstation, point at that server and use a stable machine id:

export CLAUDE_HISTORY_RAG_SERVER_URL=http://<server-ip>:4680
export CLAUDE_HISTORY_RAG_MACHINE_ID=<workstation-name>
export CLAUDE_HISTORY_RAG_CLIENT_NAME="<human readable name>"
uv run ai-agent-history-rag-daemon start

Each workstation watches its local Claude Code, Codex, Gemini, Antigravity, ChatGPT export, and Claude app export roots, then uploads chunks to the central server. Rows keep their machine_id, so search spans all machines while purge/reindex can remain machine-scoped.

Configuration

Claude Code MCP Settings

Option 1: Using claude mcp add-json

The daemon must already be running under the production contract. Point the client at the native proxy and project the same non-secret production environment:

claude mcp add-json ai-agent-history-rag '{
  "command": "/path/to/claude-history-rag-mcp/scripts/history-rag-mcp-native.sh",
  "args": [],
  "env": {
    "CLAUDE_HISTORY_RAG_RUNTIME_CONTRACT": "production",
    "CLAUDE_HISTORY_RAG_STORAGE_BACKEND": "spanner",
    "CLAUDE_HISTORY_RAG_SPANNER_PROJECT": "<your-gcp-project>",
    "CLAUDE_HISTORY_RAG_SPANNER_INSTANCE": "<your-spanner-instance>",
    "CLAUDE_HISTORY_RAG_SPANNER_DATABASE": "ai-agent-history-rag",
    "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": "<dedicated-runtime-service-account>",
    "GOOGLE_APPLICATION_CREDENTIALS": "<path-to-keyless-impersonated-adc-profile.json>"
  }
}'

Replace /path/to/claude-history-rag-mcp with your actual project path.

Option 2: Manual Configuration

Add to ~/.config/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "ai-agent-history-rag": {
      "command": "/path/to/claude-history-rag-mcp/scripts/history-rag-mcp-native.sh",
      "args": [],
      "env": {
        "CLAUDE_HISTORY_RAG_RUNTIME_CONTRACT": "production",
        "CLAUDE_HISTORY_RAG_STORAGE_BACKEND": "spanner",
        "CLAUDE_HISTORY_RAG_SPANNER_PROJECT": "<your-gcp-project>",
        "CLAUDE_HISTORY_RAG_SPANNER_INSTANCE": "<your-spanner-instance>",
        "CLAUDE_HISTORY_RAG_SPANNER_DATABASE": "ai-agent-history-rag",
        "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": "<dedicated-runtime-service-account>",
        "GOOGLE_APPLICATION_CREDENTIALS": "<path-to-keyless-impersonated-adc-profile.json>"
      }
    }
  }
}

Environment Variables

Core Settings

Client/Server Mode

Embedding Settings

Example URLs:

• Ollama: http://localhost:11434/v1

• vLLM: http://localhost:8000/v1

• OpenAI: https://api.openai.com/v1

• text-embeddings-inference: http://localhost:8080/v1

Vertex AI example:

export CLAUDE_HISTORY_RAG_EMBEDDING_PROVIDER=vertex
export CLAUDE_HISTORY_RAG_EMBEDDING_MODEL=gemini-embedding-001
export CLAUDE_HISTORY_RAG_EMBEDDING_DIMENSION=3072
export CLAUDE_HISTORY_RAG_VERTEX_PROJECT=<your-gcp-project>
export CLAUDE_HISTORY_RAG_VERTEX_LOCATION=us-central1

Storage Settings

Spanner example:

export CLAUDE_HISTORY_RAG_STORAGE_BACKEND=spanner
export CLAUDE_HISTORY_RAG_SPANNER_PROJECT=<your-gcp-project>
export CLAUDE_HISTORY_RAG_SPANNER_INSTANCE=<your-spanner-instance>
export CLAUDE_HISTORY_RAG_SPANNER_DATABASE=<your-rag-database>

Spanner + Vertex native embedding example:

export CLAUDE_HISTORY_RAG_STORAGE_BACKEND=spanner
export CLAUDE_HISTORY_RAG_SPANNER_PROJECT=<your-gcp-project>
export CLAUDE_HISTORY_RAG_SPANNER_INSTANCE=<your-spanner-instance>
export CLAUDE_HISTORY_RAG_SPANNER_DATABASE=<your-rag-database>
export CLAUDE_HISTORY_RAG_SPANNER_EMBEDDING_MODE=spanner
export CLAUDE_HISTORY_RAG_SPANNER_EMBEDDING_MODEL_ID=ConversationEmbeddingModel
export CLAUDE_HISTORY_RAG_EMBEDDING_PROVIDER=vertex
export CLAUDE_HISTORY_RAG_EMBEDDING_MODEL=gemini-embedding-001
export CLAUDE_HISTORY_RAG_EMBEDDING_DIMENSION=3072

Status Server Settings

Auth (PSK) Settings

Performance Settings

Embedding Model Selection

The server supports multiple embedding models. Choose based on your priorities:

Switching models requires re-indexing:

# Delete existing index
rm -rf ~/.claude-history-rag/lancedb/

# Set new model
export CLAUDE_HISTORY_RAG_EMBEDDING_MODEL=mxbai-embed-large

# Pull the model (if using Ollama)
ollama pull mxbai-embed-large

# Restart daemon
uv run ai-agent-history-rag-daemon restart

CLI Commands

The daemon package provides its existing management tools. Production MCP uses the separate native proxy:

Run daemon-management commands with their existing package launcher. MCP clients must execute the native proxy directly.

Running Modes

Daemon Mode (Recommended)

Run the indexer and status server as a standalone background daemon:

# Start the daemon
uv run ai-agent-history-rag-daemon start

# Check daemon status
uv run ai-agent-history-rag-daemon status

# Stop the daemon
uv run ai-agent-history-rag-daemon stop

# Restart the daemon
uv run ai-agent-history-rag-daemon restart

The daemon:

• Runs in the foreground (use & or a process manager for background)

• Writes PID to ~/.claude-history-rag/daemon.pid

• Logs to ~/.claude-history-rag/daemon.log

• Provides the dashboard at http://127.0.0.1:4680/dashboard

Server mode log output:

Starting daemon [SERVER] | db=~/.claude-history-rag/lancedb | embedding_url=http://localhost:11434/v1 | embedding_model=nomic-embed-text

Client mode log output:

Starting daemon [CLIENT] | server_url=http://192.168.1.100:4680 | machine_id=my-laptop

MCP Process Model

The MCP process is intentionally not a standalone indexer. It validates the full production runtime and credential contract before entering the STDIO loop, then proxies the five tools to the already-running loopback daemon. The retired Python console path fails closed and cannot reach Spanner or Vertex.

Auto-start on Boot

Auto-start services use ai-agent-history-rag-daemon supervise, which replaces any PID-file daemon before staying in the foreground for the service manager. Use start for manual foreground runs.

macOS (launchd)

./scripts/install-launchd.sh

To configure for client mode, edit ~/Library/LaunchAgents/com.ai-agent-history-rag.daemon.plist after installation.

Linux (systemd)

./scripts/install-systemd.sh

To configure environment variables:

# Edit the service file
nano ~/.config/systemd/user/ai-agent-history-rag.service

# Reload and restart
systemctl --user daemon-reload
systemctl --user restart ai-agent-history-rag

Windows (Scheduled Task)

.\scripts\install-windows.ps1

To configure for client mode, set user environment variables (CLAUDE_HISTORY_RAG_SERVER_URL) and restart the task.

Status Monitoring

The status server provides monitoring endpoints:

• Dashboard: http://127.0.0.1:4680/dashboard - Auto-refreshing web UI

• Health Check: http://127.0.0.1:4680/health - Simple health status

• Status API: http://127.0.0.1:4680/status - JSON status

• Prometheus Metrics: http://127.0.0.1:4680/metrics - Prometheus format

• Client Registry: Included in /status?detail=full under clients

PSK Authentication & Rotation

All status server endpoints (dashboard + API + health/metrics) require a pre-shared key (PSK) by default. Clients send:

Authorization: Bearer <psk>

TLS required: Run the status server behind HTTPS (e.g., Traefik). The PSK is sent raw over the wire and is only protected by TLS.

Server storage (auth.json):

• The active key is stored hashed for validation.

• The active key is also stored in plaintext to support dashboard reveal and rotation flows.

• If you set CLAUDE_HISTORY_RAG_SERVER_PSK, the dashboard disables rotation (tooltip: “PSK assigned in .env — rotate in your .env and rebuild”).

Client storage (client_auth.json):

• Clients store the raw PSK locally for requests.

• The client auth file is written with 0600 permissions on macOS/Linux (best-effort on Windows).

Rotation flow:

• “Rotate PSK” lets you select existing clients to temporarily keep using the old key for X days.

• New/unknown clients must use the new key.

• Clients receive a rotation hint, retry immediately with the new key, and ack success.

• If rotation fails, the client falls back to the old key and reports an error; the dashboard shows a red Error key status with an “Allow stay” button (temporary allowlist, expires after X days).

Dashboard key reveal:

• You must unlock the dashboard with the current PSK to access protected endpoints.

• The dashboard stores a hash in localStorage to authorize key reveal; the PSK itself is only held in-memory while the reveal modal is open.

• Auto-refresh is paused while the key modal is open.

Key status column:

• Current (green): using the active key

• Awaiting Rotation (yellow): allowlisted to use old key

• Old (orange): old key expired or removed

• Error (red): failed rotation

Security limitations:

• The PSK is plaintext in server auth.json to support dashboard reveal/rotation.

• Protect your host and auth.json file; restrict filesystem access.

• Do not expose the status server without TLS.

Re-index Behavior (Server Mode)

Using the dashboard Re-index button will:

1. Clear the server database and reset server-side file positions

2. Set a reindex request flag for all clients

3. Clients acknowledge the request, clear their local positions, and re-upload

4. Clients send a completed ack after uploads finish

You can see client ack status in the dashboard Clients panel.

Client registry data is stored under the configured state directory (e.g., ~/.claude-history-rag/client_registry.json or /data/state in Docker) so it survives upgrades/reinstalls.

API Endpoints (Server Mode)

When running in server mode, additional API endpoints are available for client machines:

MCP Tools

search_conversations

Search conversation history for relevant context.

Arguments:
  query: str           - Natural language query
  project_filter: str  - Limit to specific project (optional)
  date_from: str       - Inclusive lower timestamp bound, ISO date/datetime (optional)
  date_to: str         - Inclusive upper timestamp bound, ISO date/datetime (optional)
  limit: int           - Maximum results (default: 5)
  use_hybrid: bool     - Use hybrid search (default: True)

search_file_changes

Find file modifications in conversation history.

Arguments:
  file_path: str       - Filter by file path (optional, supports partial match)
  query: str           - Semantic query about changes (optional)
  project_filter: str  - Limit to specific project (optional)
  operation_filter: str - Filter by "edit" or "write" (optional)
  date_from: str       - Inclusive lower timestamp bound, ISO date/datetime (optional)
  date_to: str         - Inclusive upper timestamp bound, ISO date/datetime (optional)
  limit: int           - Maximum results (default: 10)

get_session_summary

Get summary of conversation session(s).

Arguments:
  session_id: str      - Specific session ID (optional)
  project_filter: str  - Limit to specific project (optional)
  count: int           - Number of sessions (default: 1)

get_index_status

Get status of the RAG index.

Returns:
  mode: str                    - "server" or "client"
  total_chunks: int            - Number of indexed chunks (server mode)
  watched_files: int           - Number of files being tracked
  pending_files: int           - Files in queue for processing
  pending_uploads: int         - Uploads waiting to send (client mode)
  connected: bool              - Server connection status (client mode)
  server_status: dict          - Remote server status (client mode)
  status: str                  - Overall health status

get_server_status

Get comprehensive server status and health information.

Arguments:
  detail_level: str  - "basic" for summary, "full" for detailed metrics (default: "basic")

Returns:
  server: dict      - Version, uptime, PID, platform info
  health: dict      - Overall status and component health checks
  database: dict    - Chunk counts, database size (full detail only)
  indexing: dict    - File processing progress (full detail only)
  performance: dict - Memory, CPU, query metrics (full detail only)
  cache: dict       - Hit rates, cache size (full detail only)

Development

Running Tests

uv run pytest

Linting

uv run ruff check .
uv run ruff format .

Testing with MCP Inspector

npx @modelcontextprotocol/inspector ./scripts/history-rag-mcp-native.sh

Detailed Architecture

Single-Machine Mode

┌─────────────────────────────────────────────────────────────┐
│                     Daemon Process                          │
│  (ai-agent-history-rag-daemon)                                │
│                                                             │
│  ~/.claude/projects/*.jsonl                                 │
│           │                                                 │
│           ▼                                                 │
│     File Watcher ──► Chunker ──► Embedder ──► LanceDB       │
│                                               (shared)      │
│                                                   │         │
│     Status Server (dashboard, health, metrics)    │         │
└───────────────────────────────────────────────────│─────────┘
                                                    │
                                                    ▼
┌─────────────────────────────────────────────────────────────┐
│                   MCP Proxy Process                         │
│  (scripts/history-rag-mcp-native.sh)                        │
│                                                             │
│     Claude Code ◄──► STDIO Transport ◄──► MCP Tools         │
│                                               │             │
│                                               ▼             │
│                                  Loopback daemon API        │
└─────────────────────────────────────────────────────────────┘

Multi-Machine Mode

┌─────────────────────────────────────────────────────────────┐
│                    Client Machine                           │
│                                                             │
│  ~/.claude/projects/*.jsonl                                 │
│           │                                                 │
│           ▼                                                 │
│     File Watcher ──► Chunker ──► HTTP Client                │
│                                      │                      │
│                            ┌─────────┴─────────┐            │
│                            │  Pending Queue    │            │
│                            │  (offline mode)   │            │
│                            └───────────────────┘            │
│                                      │                      │
│     MCP Tools ◄── proxy to server ◄──┘                      │
└──────────────────────────────│──────────────────────────────┘
                               │ HTTP POST /api/chunks
                               │ HTTP POST /api/search
                               ▼
┌─────────────────────────────────────────────────────────────┐
│                    Central Server                           │
│                                                             │
│     API Endpoints ◄── Status Server (port 4680)             │
│           │                                                 │
│           ▼                                                 │
│     Embedder ──► Storage Backend ◄── Search API            │
│     (OpenAI-compatible / Vertex)   (LanceDB / Spanner)     │
│                                                             │
│     Position Tracking (per machine)                        │
└─────────────────────────────────────────────────────────────┘

Offline Resilience (Client Mode)

When the server is unavailable:

1. Chunking continues locally - Files are still processed into chunks

2. Uploads are queued durably - A versioned outbox index is stored in ~/.claude-history-rag/client_state.json; bounded payload records are stored alongside it using exclusive randomized atomic writes. Every pending upload binds the canonical request body—including machine, client, chunks, source, and cursor—to a SHA-256 digest, and cursor progress is committed only after complete server acceptance

3. Retry logic - 3 retries with 30s delay, then waits for next sync interval

4. Catch-up on reconnect - Compares durable local vs server positions and replays generation-bound gaps without using the retired direct position-sync route

5. Search degrades gracefully - Returns "server unavailable" error

Chunk Types

1. Turn chunks: User message paired with assistant response

2. File change chunks: Extracted from Edit/Write tool_use blocks with parent-child linking

3. Summary chunks: From compaction events

Each chunk includes machine_id in multi-machine mode for tracking origin.

Tech Stack

• Python 3.10+ with async/await patterns

• FastMCP (official MCP SDK) - STDIO transport

• Storage backends - LanceDB 0.25+ embedded search, or Cloud Spanner vector/full-text/hybrid search

• Embedding providers - OpenAI-compatible /v1/embeddings API or Vertex AI REST

• httpx - Async HTTP client for embeddings API and client/server communication

• watchfiles - Rust-based async file watching

• pydantic - Data validation and settings

• aiohttp - Status server and API endpoints

Performance

Troubleshooting

Native Diagnostics

Inspect the daemon and validate the MCP production boundary without invoking a Python wizard:

./scripts/status.sh
./scripts/history-rag-mcp-native.sh --validate-only

The first command reports daemon and log state. The second fails closed unless the complete production runtime and credential contract is valid; it performs no MCP handler or daemon network call during validation.

Client can't connect to server

1. Check server is running: curl http://server-ip:4680/health

2. Verify firewall allows port 4680

3. Check STATUS_SERVER_HOST is set to 0.0.0.0 on server (not 127.0.0.1)

Embeddings failing

1. Verify embedding server is running: curl http://localhost:11434/v1/models

2. Check model is pulled: ollama list

3. Verify EMBEDDING_BASE_URL and EMBEDDING_MODEL are correct

Pending uploads not syncing

1. Check server connectivity: curl http://server-ip:4680/health

2. View pending uploads: cat ~/.claude-history-rag/client_state.json

3. Stale uploads (>72h) are automatically cleared

Roadmap

• Split LanceDB and Spanner implementations into separate backend modules behind the existing ConversationStore interface.

• Add typed importers for ChatGPT and Claude app official export ZIP/JSON files.

• Add a source registration layer so new watchers do not require edits across config, status, docs, and the watcher registry.

• Extend the dashboard to manage backend settings, source roots, and remote client onboarding.

License

MIT