# Ai Agent History Rag Mcp

> Full featured aggregation of all your AI agents in single vector database for full MCP search.

- **Type:** MCP server
- **Install:** `agentstack add mcp-no13productions-ai-agent-history-rag-mcp`
- **Verified:** Pending review
- **Seller:** [no13productions](https://agentstack.voostack.com/s/no13productions)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [no13productions](https://github.com/no13productions)
- **Source:** https://github.com/no13productions/ai-agent-history-rag-mcp

## Install

```sh
agentstack add mcp-no13productions-ai-agent-history-rag-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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)

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

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

```bash
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
3. Detect installed AI tools (Claude Desktop, Claude Code, Cursor, VS Code, Gemini CLI, OpenAI Codex)
4. Add MCP configuration to selected applications
5. Install daemon as a system service (launchd/systemd/Windows Task) — removing any existing service first to ensure updates apply
6. Prompt for **PSK authentication** settings (optional PSK overrides + auth paths)
7. **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
   ```

2. **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:
```bash
# 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):
```bash
# 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:
```bash
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
   ```

2. **Start the daemon**:
   ```bash
   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):
   ```bash
   ollama serve
   ollama pull nomic-embed-text
   ```

2. **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
   ```

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**:
   ```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
   ```

2. **Start the daemon in client mode**:
   ```bash
   uv run ai-agent-history-rag-daemon start
   ```

3. **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:

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

```bash
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)**:
```bash
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)**:
```bash
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**:
```json
{
  "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**:
```json
{
  "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 |
| `CLAUDE_HISTORY_RAG_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](https://github.com/no13productions)
- **Source:** [no13productions/ai-agent-history-rag-mcp](https://github.com/no13productions/ai-agent-history-rag-mcp)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-no13productions-ai-agent-history-rag-mcp
- Seller: https://agentstack.voostack.com/s/no13productions
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.