DeltaContext

Incremental, citation-first repository context for AI coding agents.

DeltaContext indexes a Python repository into syntax-aware chunks, retrieves relevant functions with SQLite FTS5/BM25, follows local import dependencies, and returns source-cited context within a hard character budget. Four read-only MCP tools expose the index to coding clients, including Gemini CLI. Everything runs locally; no model key, cloud database or target-code execution is required.

The engineering problem: agents need to find the right implementation, understand nearby dependencies and refresh context when files change. Sending a whole repository wastes context; returning an uncited snippet makes the result harder to verify. DeltaContext makes indexing, retrieval and context assembly explicit and inspectable.

What is implemented

• Incremental indexing: SHA-256 detects changed files; only changed Python files are parsed. Deleted or newly invalid files lose stale search entries. Import edges are relinked transactionally.

• Syntax-aware retrieval: functions, async functions, class headers and methods have exact line ranges; long symbols split at 80 lines. Identifier splitting makes authorizeRequest searchable as authorize request.

• Ranked lexical search: BM25 with identifier weighting over SQLite FTS5. This is lexical retrieval, not neural semantic search.

• Dependency context: selected source plus direct local imports; reverse-import BFS identifies potential affected files up to a declared depth. Cycles and traversal counts are bounded.

• Budgeted evidence: context never exceeds max_chars; every included source range is cited and tied to a content-derived repository revision. Character budgets are exact; they are not tokenizer-specific token budgets.

• Snapshot consistency: transactions and WAL allow readers to see a complete index revision during updates.

• Agent integration: four MCP tools with structured JSON output, verified through an actual stdio client/server round trip.

flowchart LR
  A[Python repository] --> B[Git-aware discovery + content hashes]
  B --> C[AST chunks + local imports]
  C --> D[(SQLite FTS5 + dependency edges)]
  E[Question or changed file] --> D
  D --> F[Ranked symbols + bounded dependency traversal]
  F --> G[Cited context bundle]
  G --> H[CLI or read-only MCP tools]

Related MCP server: RepoPilot MCP Server

Quick start

Python 3.11+ and SQLite with FTS5 support. Git is recommended so repository ignore rules are respected.

python -m venv .venv
# Activate the environment using your shell's standard activation command.
python -m pip install -e ".[mcp,dev]"

deltacontext --db .deltacontext/demo.sqlite3 index /absolute/path/to/python-repo
deltacontext --db .deltacontext/demo.sqlite3 search "authentication credentials"
deltacontext --db .deltacontext/demo.sqlite3 context "authentication credentials" --max-chars 8000
deltacontext --db .deltacontext/demo.sqlite3 impact package/auth.py --depth 3
deltacontext --db .deltacontext/demo.sqlite3 stats

Run index again after changes. An unchanged run reports parsed_files: 0. Each database is bound to one root to prevent accidentally mixing repositories. JSON includes counts, parse errors, timings and a content-derived revision. Core indexing and CLI have no third-party runtime dependencies; the MCP extra installs the official SDK.

Connect a coding agent

Start the server with an absolute database path:

python -m deltacontext --db /absolute/path/index.sqlite3 mcp

Example Gemini CLI MCP configuration; replace the executable/database paths for your machine:

{
  "mcpServers": {
    "deltacontext": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["-m", "deltacontext", "--db", "/absolute/path/index.sqlite3", "mcp"]
    }
  }
}

On Windows the executable is typically .venv/Scripts/python.exe. Install the package in that environment so the server can launch from any directory. The SDK's stdio protocol is tested locally; a Gemini CLI end-to-end session has not been run in the checked-in validation.

The server cannot index arbitrary paths on an agent's request, execute source, modify repository files or run shell commands. Index updates are an explicit operator CLI action.

Tests and measurements

python -m pytest -q
git clone https://github.com/encode/starlette.git .benchmark-cache/starlette
# Check out the commit recorded in benchmarks/results/starlette.json to reproduce its corpus.
python -m benchmarks.run .benchmark-cache/starlette

The test suite covers incremental updates/deletes, invalid-source cleanup, exact citations, context-size bounds, relative imports, Git ignores, symlink escape rejection, non-execution of source, concurrent readers/writer, CLI JSON, and the real MCP transport. A symlink test skips only when the operating system disallows creating symlinks.

The Starlette measurement includes repository tests and 16 hand-authored file-relevance queries. The benchmark reports BM25 and a simple term-overlap baseline, per-query rankings, latency, no-op reindexing, and a controlled single-file mutation in a disposable copy. Results are a local engineering smoke benchmark, not a held-out retrieval benchmark or a coding-agent success claim. Raw reproducible output is in benchmarks/results/starlette.json.

Measured September 24, 2026 on Windows/Python 3.12.14, Starlette commit fada3631d80274e0f1d552490a83ca877d58ed04:

The small relevance set was authored for this project, so the one-query advantage over the baseline is descriptive, not statistically established. Timing includes local SQLite access and is machine/cache dependent. Full versus incremental processing still hashes eligible files and relinks imports.

Boundaries and tradeoffs

Python only. Static imports approximate dependencies; dynamic imports, monkey-patching, namespace-package ambiguity and runtime dispatch are not resolved. Search can miss conceptual matches with no shared words. Graph expansion adds direct imports, not an LLM-generated explanation. Class-level nonmethod statements after methods may not be represented as separate chunks. Oversized files (>512 KB), hidden paths, symlinks and common build/dependency directories are excluded. Git ignore rules apply when the supplied root is the exact Git root; otherwise discovery uses a bounded file policy, not a full gitignore implementation.

Indexing scans/hashes eligible files and rebuilds import links even when parsing is incremental. A parse error removes that file's stale data and is reported explicitly. The index stores source text locally; select repositories accordingly. Indexed source is untrusted data and can contain misleading instructions. Clients must treat returned text as evidence, not executable instructions. Snapshot citations may differ from a working tree edited after indexing.

Current work focuses on retrieval infrastructure and correctness. A future neural-retrieval extension could compare local code embeddings, reranking and BM25 under a fixed, independently labeled evaluation set. No embedding-model or SOTA-performance claim is made for this version.

Design references

• Official MCP Python SDK — tool schemas, structured results and stdio transport.

• Gemini CLI MCP integration — client connection pattern.

• SQLite FTS5 — lexical indexing and BM25 ranking.

• Python AST — source locations and static syntax extraction.

MIT licensed. Built by Ashutosh Ambley Manoj with AI coding assistance. Repository timestamps reflect the actual implementation date.