turbocontext

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

Related MCP server: ContextAtlas

MCP Tools Reference

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

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:

Compression Footprint Comparison

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