turbocontext

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

# 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

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

---

Verified MCP Integration Specs & Schemas

Verified configuration schemas across supported AI agent clients:

1. Claude Code (CLI)

Global registration via CLI:

claude mcp add turbocontext -- uv run /path/to/turbocontext/src/server.py

Or repository-level .mcp.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

{
  "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:

{
  "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:

{
  "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:

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

---

6. Aider CLI

Launch via CLI flag:

aider --mcp-server "uv run /path/to/turbocontext/src/server.py"

Or save in .aider.conf.yml:

mcp-servers:
  - "uv run /path/to/turbocontext/src/server.py"

---

7. Hermes / Open-WebUI Agents

Add to agent tool configuration (mcp_servers.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:

 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 (ICLR 2026) — vector quantization algorithm implemented by turbovec
• FastEmbed — lightweight local ONNX text embedding library
• Model Context Protocol — open standard protocol for connecting AI models to context tools
• Tree-sitter — parser generator tool and incremental parsing library