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

```mermaid
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]
```

## Quick start

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

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

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

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

```json
{
  "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.

| Tool | Purpose |
| --- | --- |
| `search_code` | Ranked symbols with source text, scores and citations |
| `build_context` | Size-bounded source plus direct import dependencies |
| `change_impact` | Potential reverse-import dependents and traversal paths |
| `index_status` | Snapshot revision and file/chunk/edge counts |

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

```sh
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`](benchmarks/results/starlette.json).

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

| Measurement | Result |
| --- | --- |
| Indexed corpus | 84 Python files, 1,609 chunks, 406 local import edges |
| BM25 file hit@5 / mean reciprocal rank@5 | 13/16 (81.25%) / 0.6302 |
| Term-overlap baseline hit@5 / MRR@5 | 12/16 (75%) / 0.6094 |
| Search latency, 80 calls, p50 / p95 | 13.7 ms / 20.831 ms |
| No-change reindex | 0 parsed files, 84 reused |
| One-file mutation | 1 parsed file, 83 reused |

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](https://github.com/modelcontextprotocol/python-sdk) — tool schemas, structured results and stdio transport.
- [Gemini CLI MCP integration](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md) — client connection pattern.
- [SQLite FTS5](https://www.sqlite.org/fts5.html) — lexical indexing and BM25 ranking.
- [Python AST](https://docs.python.org/3/library/ast.html) — source locations and static syntax extraction.

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