Ai Agent History Rag Mcp

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

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

Install Wizard (Recommended)

The install wizard configures everything for you - MCP servers, daemon service, and all settings:

uv run ai-agent-history-rag-install

The wizard will:

1. Ask whether to install MCP server, daemon, or both
2. Configure server mode (local) or client mode (multi-machine)

2.5. Update mode (new): reuses existing daemon config (from the service) to reinstall without prompts

1. Detect installed AI tools (Claude Desktop, Claude Code, Cursor, VS Code, Gemini CLI, OpenAI Codex)
2. Add MCP configuration to selected applications
3. Install daemon as a system service (launchd/systemd/Windows Task) — removing any existing service first to ensure updates apply
4. Prompt for PSK authentication settings (optional PSK overrides + auth paths)
5. Verify installation - waits for daemon startup and runs health checks

Note: ChatGPT connectors are configured in-app (Developer mode) and are not managed by this installer.

Docker (Server Only)

1. Start Ollama on your host machine:

``bash ollama serve ollama pull bge-m3 ``

1. Start the container:

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

``bash ollama serve ollama pull nomic-embed-text ``

1. Start the daemon:

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

1. Configure Claude Code (see Configuration section below)

Multi-Machine Setup

On the Central Server

1. Start the embeddings server (Ollama example):

``bash ollama serve ollama pull nomic-embed-text ``

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

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

1. 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:

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

1. Start the daemon in client mode:

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

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

Current Spanner Server Example

On the central machine, run server mode against the shared Spanner DB:

export CLAUDE_HISTORY_RAG_STORAGE_BACKEND=spanner
export CLAUDE_HISTORY_RAG_SPANNER_PROJECT=
export CLAUDE_HISTORY_RAG_SPANNER_INSTANCE=
export CLAUDE_HISTORY_RAG_SPANNER_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
export CLAUDE_HISTORY_RAG_STATUS_SERVER_HOST=0.0.0.0
uv run ai-agent-history-rag-daemon start

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

export CLAUDE_HISTORY_RAG_SERVER_URL=http://:4680
export CLAUDE_HISTORY_RAG_MACHINE_ID=
export CLAUDE_HISTORY_RAG_CLIENT_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 (Easiest)

Server Mode (default):

claude mcp add-json ai-agent-history-rag '{
  "command": "uv",
  "args": ["--directory", "/path/to/claude-history-rag-mcp", "run", "ai-agent-history-rag"],
  "env": {
    "CLAUDE_HISTORY_RAG_DEFER_STARTUP_INDEXING": "true"
  }
}'

Client Mode (multi-machine):

claude mcp add-json ai-agent-history-rag '{
  "command": "uv",
  "args": ["--directory", "/path/to/claude-history-rag-mcp", "run", "ai-agent-history-rag"],
  "env": {
    "CLAUDE_HISTORY_RAG_SERVER_URL": "http://192.168.1.100:4680",
    "CLAUDE_HISTORY_RAG_MACHINE_ID": "my-laptop",
    "CLAUDE_HISTORY_RAG_CLIENT_NAME": "Brandon MacBook"
  }
}'

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

Option 2: Manual Configuration

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

Server Mode:

{
  "mcpServers": {
    "ai-agent-history-rag": {
      "command": "uv",
      "args": ["--directory", "/path/to/claude-history-rag-mcp", "run", "ai-agent-history-rag"],
      "env": {
        "CLAUDE_HISTORY_RAG_EMBEDDING_BASE_URL": "http://localhost:11434/v1",
        "CLAUDE_HISTORY_RAG_EMBEDDING_MODEL": "nomic-embed-text"
      }
    }
  }
}

Client Mode:

{
  "mcpServers": {
    "ai-agent-history-rag": {
      "command": "uv",
      "args": ["--directory", "/path/to/claude-history-rag-mcp", "run", "ai-agent-history-rag"],
      "env": {
        "CLAUDE_HISTORY_RAG_SERVER_URL": "http://192.168.1.100:4680",
        "CLAUDE_HISTORY_RAG_CLIENT_NAME": "Brandon MacBook"
      }
    }
  }
}

Environment Variables

Core Settings

| Variable | Default | Description | |----------|---------|-------------| | CLAUDE_HISTORY_RAG_DB_PATH | ~/.claude-history-rag/lancedb | LanceDB database location | | CLAUDE_HISTORY_RAG_STATE_PATH | ~/.claude-history-rag/state.json | File position state | | CLAUDE_HISTORY_RAG_PROJECTS_PATH | ~/.claude/projects | Claude Code projects directory | | CLAUDE_HISTORY_RAG_CODEX_SESSIONS_PATH | ~/.codex/sessions | Codex session history directory | | CLAUDE_HISTORY_RAG_CODEX_STATE_PATH | ~/.claude-history-rag/codex_state.json | Codex file position state | | CLAUDE_HISTORY_RAG_GEMINI_SESSIONS_PATH | ~/.gemini/tmp | Gemini CLI session history directory | | CLAUDE_HISTORY_RAG_GEMINI_STATE_PATH | ~/.claude-history-rag/gemini_state.json | Gemini file position state | | CLAUDE_HISTORY_RAG_ANTIGRAVITY_SESSIONS_PATH | ~/.gemini/antigravity | Google Antigravity history root | | CLAUDE_HISTORY_RAG_ANTIGRAVITY_STATE_PATH | ~/.claude-history-rag/antigravity_state.json | Google Antigravity file position state | | CLAUDE_HISTORY_RAG_CHATGPT_EXPORTS_PATH | ~/.claude-history-rag/imports/chatgpt | ChatGPT official export drop folder | | CLAUDE_HISTORY_RAG_CHATGPT_STATE_PATH | ~/.claude-history-rag/chatgpt_state.json | ChatGPT export file position state | | CLAUDE_HISTORY_RAG_CLAUDE_APP_EXPORTS_PATH | ~/.claude-history-rag/imports/claude-app | Claude web/Desktop app export drop folder | | CLAUDE_HISTORY_RAG_CLAUDE_APP_STATE_PATH | ~/.claude-history-rag/claude_app_state.json | Claude app export file position state | | CLAUDE_HISTORY_RAG_LOG_LEVEL | INFO | Logging level |

Client/Server Mode

| Variable | Default | Description | |----------|---------|-------------| | CLAUDE_HISTORY_RAG_SERVER_URL | None | Central server URL. If set, runs in client mode | | CLAUDE_HISTORY_RAG_MACHINE_ID | hostname | Unique identifier for this machine | | CLAUDE_HISTORY_RAG_CLIENT_NAME | "" | Optional human-friendly label for this client | | CLAUDE_HISTORY_RAG_UPLOAD_INTERVAL_SECONDS | 300 | Batch upload interval (5 min) | | CLAUDE_HISTORY_RAG_UPLOAD_RETRY_COUNT | 3 | Retries before queuing for later | | CLAUDE_HISTORY_RAG_UPLOAD_RETRY_DELAY_SECONDS | 30 | Delay between retries | | CLAUDE_HISTORY_RAG_CLIENT_HEARTBEAT_INTERVAL_SECONDS | 60 | Client heartbeat interval |

Embedding Settings

| Variable | Default | Description | |----------|---------|-------------| | CLAUDE_HISTORY_RAG_EMBEDDING_PROVIDER | openai | openai for OpenAI-compatible APIs, vertex for Vertex AI | | CLAUDE_HISTORY_RAG_EMBEDDING_BASE_URL | http://localhost:11434/v1 | Embeddings API base URL | | CLAUDE_HISTORY_RAG_EMBEDDING_MODEL | nomic-embed-text | Model name | | CLAUDE_HISTORY_RAG_EMBEDDING_API_KEY | "" | API key (for OpenAI, etc.) | | CLAUDE_HISTORY_RAG_EMBEDDING_DIMENSION | model default | Optional output/storage dimension override | | CLAUDE_HISTORY_RAG_OPENAI_EMBEDDING_SEND_DIMENSIONS | false | Send dimensions to OpenAI-compatible APIs | | CLAUDE_HISTORY_RAG_VERTEX_PROJECT | ADC/gcloud project | Vertex AI project | | `CLAUDEHISTORYRAG_V

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: no13productions
• Source: no13productions/ai-agent-history-rag-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.