<p align="center">
  <img src="assets/turbocontext_architecture.png" alt="Turbocontext System Architecture" width="100%">
</p>

<p align="center">
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License"></a>
  <a href="https://modelcontextprotocol.io/"><img src="https://img.shields.io/badge/MCP-stdio%202.0-green.svg" alt="MCP Protocol"></a>
  <a href="https://github.com/RyanCodrai/turbovec"><img src="https://img.shields.io/badge/Quantization-4--bit%20Turbovec-purple.svg" alt="Quantization"></a>
  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.12+-blue.svg" alt="Python Version"></a>
  <a href="#search-speed--benchmarks"><img src="https://img.shields.io/badge/Retrieval-sub--20ms-emerald.svg" alt="Retrieval Speed"></a>
</p>

---

**A 100,000 code chunk index takes 307 MB of RAM as float32. Turbocontext fits it in 38 MB - and searches it in sub-20ms with cross-encoder accuracy.**

**Turbocontext** is a high-performance, real-time codebase indexing engine and vector context retriever for AI coding agents (Claude Code, Cursor, Aider, Hermes, Windsurf, Continue). Built on Tree-sitter AST parsing, FastEmbed local ONNX embeddings, Google Research's [**TurboQuant**](https://arxiv.org/abs/2504.19874) 4-bit quantization algorithm via `turbovec`, and Cross-Encoder reranking, it serves workspace-isolated context queries over Model Context Protocol (MCP) stdio transport.

- **Incremental online ingest.** SHA-256 file hashing skips unchanged files automatically (~90% indexing work saved). Added or modified files are AST-chunked and indexed immediately — no parameter tuning, no separate training step.
- **8.0x Memory compression.** Quantizes dense 768-dim float32 vectors down to 4-bit representations ($384\text{ bytes/vec}$ instead of $3,072\text{ bytes/vec}$), enabling massive codebase indexing in RAM.
- **Tree-sitter AST breadcrumbs.** Decomposes multi-language source code (`.py`, `.js`, `.ts`, `.rs`, `.go`, `.cpp`, `.c`, `.java`, `.html`, `.css`, `.json`) into semantic function and class blocks with prepended breadcrumbs (`File: [path]\nType: [Class|Function]\n\n[code]`).
- **Filtered allowlist search.** Pass a workspace `uint64` ID allowlist to `search()` and the Turbovec kernel honours it directly. You get zero cross-workspace data leakage and no over-fetching penalty.
- **Two-stage cross-encoder precision.** Oversamples candidate vectors from Turbovec search, then reranks top candidates using `BAAI/bge-reranker-v2-m3` cross-encoder to eliminate context noise.
- **Pure local & air-gapped.** Runs locally via stdio MCP. No cloud API calls, no third-party vector database service, no code leaving your machine or VPC.

Building AI agent workflows where context quality, RAM footprint, or sub-20ms latency matters? **You're in the right place.**

---

## Quickstart (Python & MCP)

### Environment Setup

```bash
# Clone the repository
git clone https://github.com/e-x-h-i-b-i-t/turbocontext.git
cd turbocontext

# Synchronize dependencies with uv
uv sync

# Run FastMCP stdio server
uv run python src/server.py
```

### Python API Usage

```python
import numpy as np
from storage import VectorStore
from indexer import index_file

# Initialize VectorStore with local SQLite + Turbovec 4-bit index
store = VectorStore(db_path="storage.db", dim=768, bit_width=4)

# Index a source file (AST chunking + FastEmbed vectorization + SHA-256 hash skip)
chunks_indexed = index_file("src/server.py", workspace_id="my_project", vector_store=store)

# Search with two-stage vector search + cross-encoder reranking
query_text = "FastMCP stdio server tools"
query_vec = np.random.randn(768).astype(np.float32)  # Generated via FastEmbed

results = store.search(
    query_vector=query_vec,
    workspace_id="my_project",
    top_k=20,          # Oversample 20 candidates from Turbovec
    query_text=query_text,
    final_k=3          # Rerank to top 3 best chunks
)

for res in results:
    print(f"[{res['file_path']}] score={res['rerank_score']:.4f}\n{res['text']}\n")

store.close()
```

---

## MCP Tools Reference

Connecting AI agents to `src/server.py` over stdio MCP grants access to 7 tools:

| MCP Tool Name | Parameters | Description |
| :--- | :--- | :--- |
| `index_workspace` | `workspace_id` (str), `directory_path` (str), `force` (bool) | Recursively scans code files, parses AST chunks, computes SHA-256 hashes, and indexes chunks. |
| `search_code` | `workspace_id` (str), `query` (str), `top_k` (int=3) | Embeds text query, retrieves candidates via Turbovec allowlist, and cross-encoder reranks top matching chunks. |
| `add_memory` | `workspace_id` (str), `text` (str) | Injects plain-text notes or architectural decisions into the index without needing a file path. |
| `get_status` | `workspace_id` (optional str) | Returns diagnostic metrics: chunk counts, file counts, memory counts, DB disk size, and model metadata. |
| `clear_workspace` | `workspace_id` (str) | Purges all indexed code chunks, memories, and file hashes for a workspace ID and rebuilds vector index. |
| `start_file_watcher` | `workspace_id` (str), `directory_path` (str) | Starts an asynchronous real-time background file watcher that updates the index on file edits/deletions. |
| `stop_file_watcher` | `workspace_id` (str) | Stops the asynchronous background file watcher for a workspace ID. |

---

## Verified MCP Integration Specs & Schemas

Verified configuration schemas across supported AI agent clients:

### 1. Claude Code (CLI)
Global registration via CLI:
```bash
claude mcp add turbocontext -- uv run /path/to/turbocontext/src/server.py
```
Or repository-level `.mcp.json`:
```json
{
  "mcpServers": {
    "turbocontext": {
      "command": "uv",
      "args": ["run", "/path/to/turbocontext/src/server.py"]
    }
  }
}
```

---

### 2. Claude Desktop App
Configuration file path by OS:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "turbocontext": {
      "command": "uv",
      "args": [
        "run",
        "/path/to/turbocontext/src/server.py"
      ],
      "cwd": "/path/to/turbocontext"
    }
  }
}
```

---

### 3. Cursor IDE
Add to `.cursor/mcp.json` in your workspace root, or configure under **Cursor Settings → Features → MCP**:

```json
{
  "mcpServers": {
    "turbocontext": {
      "command": "uv",
      "args": [
        "run",
        "/path/to/turbocontext/src/server.py"
      ]
    }
  }
}
```

---

### 4. Cline / Roo Code / CoolCline (VS Code Extensions)
File path: `~/.vscode/extensions/.../cline_mcp_settings.json` or `roo_code_mcp_settings.json`:

```json
{
  "mcpServers": {
    "turbocontext": {
      "command": "uv",
      "args": [
        "run",
        "/path/to/turbocontext/src/server.py"
      ],
      "disabled": false,
      "autoApprove": []
    }
  }
}
```

---

### 5. Continue (VS Code & JetBrains IDEs)
File path: `~/.continue/config.json`:

```json
{
  "mcpServers": [
    {
      "name": "turbocontext",
      "command": "uv",
      "args": [
        "run",
        "/path/to/turbocontext/src/server.py"
      ]
    }
  ]
}
```

---

### 6. Aider CLI
Launch via CLI flag:
```bash
aider --mcp-server "uv run /path/to/turbocontext/src/server.py"
```
Or save in `.aider.conf.yml`:
```yaml
mcp-servers:
  - "uv run /path/to/turbocontext/src/server.py"
```

---

### 7. Hermes / Open-WebUI Agents
Add to agent tool configuration (`mcp_servers.yaml`):
```yaml
mcp_servers:
  turbocontext:
    transport: stdio
    command: uv
    args:
      - run
      - /path/to/turbocontext/src/server.py
```

---

## Search Speed & Benchmarks

All empirical benchmarks evaluated on Linux with Python 3.12 and CPU-only ONNX execution:

| Benchmark Domain | Metric Measured | Result | Evaluation |
| :--- | :--- | :--- | :--- |
| **AST Parsing Speed** | Throughput | **137,404 files/sec** | 0.0073 ms/file parsing latency |
| **FastEmbed Embedding** | Throughput | **130.9 chunks/sec** (9.8 KB/s) | Local ONNX CPU execution |
| **Turbovec Quantized Search** | Latency (1,000 vectors) | **0.318 ms P50** / **0.321 ms P95** | Sub-millisecond vector retrieval |
| **Memory Compression** | Footprint Ratio | **8.0x Reduction** (3072 → 384 B/vec) | 87.5% memory footprint savings |
| **End-to-End Search Response** | `search_code` Response Time | **15.7 ms Mean** (16.5 ms P95) | Sub-20ms total context retrieval |

### Compression Footprint Comparison

| Corpus Scale | Unquantized Float32 | 4-Bit Turbovec | Memory Saved |
| :--- | :--- | :--- | :--- |
| **10,000 Chunks** | 29.3 MB | 3.7 MB | **-25.6 MB** |
| **100,000 Chunks** | 293.0 MB | 36.6 MB | **-256.4 MB** |
| **1,000,000 Chunks** | 2.93 GB | 366.0 MB | **-2.56 GB** |

---

## How It Works

Turbocontext compresses context retrieval latency and RAM footprint using a 6-stage architectural pipeline:

```text
 1. AST Chunking    -->  2. Dense Embedding  -->  3. 4-Bit Quantization
 (Tree-sitter node)     (FastEmbed 768-dim)     (384 bytes/vector)
                                                        │
 6. MCP Response    <--  5. Cross-Encoder    <--  4. Allowlist SIMD Search
 (Sub-20ms stdio)       (bge-reranker-v2-m3)    (Workspace uint64 IDs)
```

1. **AST Decomposition**: Tree-sitter parses multi-language source code files into semantic definitions (`function_definition`, `class_definition`, `struct_item`) with contextual breadcrumbs (`File: [path]\nType: [Class|Function]\n\n[code]`).
2. **Local Vector Embedding**: FastEmbed ONNX model (`jinaai/jina-embeddings-v2-base-code`) maps each code block to a 768-dimensional dense vector space.
3. **Random Orthogonal Quantization**: `turbovec.IdMapIndex` applies a random orthogonal rotation matrix to map coordinates to a canonical distribution, quantizing 768 float32 dimensions into 4-bit representations ($384\text{ bytes/vec}$).
4. **Allowlist SIMD Search**: `turbovec.search()` takes a 1D `uint64` numpy array allowlist corresponding to `workspace_id` row IDs in SQLite, executing short-circuited SIMD search with zero cross-workspace data leakage.
5. **Cross-Encoder Precision Reranking**: Candidate chunks from vector search are reranked by `BAAI/bge-reranker-v2-m3` cross-encoder, scoring raw query text against retrieved code blocks to eliminate false positives.
6. **FastMCP Stdio Transport**: Returns structured results over stdio MCP transport to AI agents within **~16.22 ms**.

---

## References

- [TurboQuant: Online Vector Quantization with Near-optimal Distortion Rate](https://arxiv.org/abs/2504.19874) (ICLR 2026) — vector quantization algorithm implemented by `turbovec`
- [FastEmbed](https://qdrant.github.io/fastembed/) — lightweight local ONNX text embedding library
- [Model Context Protocol](https://modelcontextprotocol.io/) — open standard protocol for connecting AI models to context tools
- [Tree-sitter](https://tree-sitter.github.io/tree-sitter/) — parser generator tool and incremental parsing library