bgts-context-engine

Deterministic code-graph context for AI coding agents.

Ask "why does the login timeout fire on the meeting webhook?" and get the eight symbols that actually answer it — ranked, budgeted, and reproducible.

Two coding agents, 600 real merged changes, 12 repositories, 6 languages — the agent alone against the same agent with BCE as its first step.

Results · Quick start · Use it from your agent · How it works · Supported models · Selector models · Documentation · Website · Türkçe

Why this exists

An agent working on an unfamiliar repository has to decide what to read before it can decide what to change. The usual answer is embedding search over chunked files. It is cheap to build and wrong in a specific way: it returns text that reads like the question rather than code that participates in the behaviour. Ask about a login timeout and you get the five files that mention timeouts, not the one function that sets it and the three callers that break when you change it.

That information is structural, and it has an exact answer. handleLogin calls refreshSession, which reads SESSION_TTL, which is written in exactly one place. That is a graph walk.

BGTS Context Engine indexes your repositories into that graph — symbols, calls, references, type hierarchies, HTTP routes, cross-language bridges — and answers questions by walking it. Embeddings are used in one place only: finding entry points when the task text names nothing recognisable. They never affect ranking.

The same task text, against the same commit, returns the same ranking. No model in the retrieval path, no clock, no randomness. When an agent makes a bad change you can replay exactly what it was told, find the stage that surfaced the wrong symbol, and fix that stage.

On top of that ranking sits one optional, clearly marked probabilistic step: a context selector that asks a decision model which of the ranked files the task actually edits and hands the agent those in full, the likely-related ones as one line each, and nothing else. On 600 real changes it cut the tokens handed to the agent from 8 310 to 1 121 (−87 %) for about one point of recall (94.4 → 93.3). It is off until BCE_SELECTOR names a model — hosted Jev, or decider-2b / decider-4b on your own GPU — and --no-select gives back the byte-exact pack.

The engine is published so people can run it. Organisations that want the same thing inside their own perimeter — help with indexing, deployment, scoring tuned to their repositories, or the agent stack around it — can engage BGTS for consulting. Write to opensource-ai@bgts.com.

Results

Two coding agents ran the same 600 tasks. Each task is a change a project actually merged, 50 per repository across 12 open-source repositories in six languages: flask and requests (Python), express and axios (JavaScript), nest and vite (TypeScript), guava and netty (Java), efcore and PowerShell (C#), gin and prometheus (Go). The agent gets the developer's sentence in a copy with the history removed and has to name the source files the change touched. Every task ran twice: the agent alone, with its own grep, glob and read tools, and the agent with BCE as its first step (BCE_AGENT_MODE=hint): it asks the engine, starts from the answer and adds to it when it needs to.

The agent stops searching the tree: most of what it saves is the context it re-reads on every turn while it greps (cache-read tokens fall by about 90 %). The weaker model gains recall — BCE's graph supplies the files GLM 5.3 Flash missed on its own (hard tasks 74 → 81 %). With BCE_AGENT_MODE=trust, where the agent takes the answer as the set of locations and does not search at all, Cursor CLI went further: 45k tokens, 1.3 tool calls, 36 s, 92.3 % recall.

Read the numbers with these in mind. Recall is the target, not precision: the engine tells the agent to pass its file list on, about 15 files per task against 1.9 alone, so precision falls (Cursor CLI 91 → 11 %). Cursor CLI had web access in its alone runs and sometimes found the change on GitHub, which lifts that baseline. Cost is priced with one rate card for both agents (OpenRouter's GLM 5.3 Flash rates for input, output and cache read), so the Cursor CLI column is not Cursor's own bill. OpenCode's two runs are compared on the 597 tasks both completed. † OpenCode's runs with BCE were on a machine with no free memory (16 GB, 99 % used); MCP start-up and the engine call are normalised to an idle machine's medians, the raw mean was 155 s. The harness is not in this repository yet — see the roadmap.

Quick start

# 1. PostgreSQL 16 with Apache AGE + pgvector, in one database
docker compose -f deploy/docker-compose.yml up -d

# 2. Install and migrate
pip install bgts-context-engine
cp .env.example .env
bce migrate

# 3. Index something
bce index --repo /path/to/your/repo --name my-service

# 4. Ask
bce context --task "fix the login timeout in the meeting webhook"

Then serve it:

bce serve        # REST at :8000/docs, web UI at :8000/ui/
bce serve-mcp    # MCP over stdio, for agents (install the [mcp] extra; see below)

Use it from your agent

The MCP surface is behind the mcp extra (Python MCP SDK 1.x: mcp>=1.0,<2). Install it so bce is on the user PATH, not only inside a project .venv. Cursor and VS Code spawn bce serve-mcp themselves and do not activate the venv:

pip install "bgts-context-engine[mcp]"
bce --version   # must work in a new terminal, with no venv activated

Every MCP client uses the same stdio command plus the database in the environment. Do not leave bce serve-mcp running in a terminal for the editor: stdout is the protocol, so the process stays silent, and the IDE starts its own copy.

One command per editor. Run it in the project the agent works on (the repository you indexed), pointing at the engine's .env:

bce --env-file /path/to/engine/.env cursor-init --repo-id my-service   # Cursor
bce --env-file /path/to/engine/.env claude-init --repo-id my-service   # Claude Code
bce --env-file /path/to/engine/.env opencode-init --repo-id my-service # OpenCode
bce --env-file /path/to/engine/.env codex-init --repo-id my-service    # Codex
bce --env-file /path/to/engine/.env copilot-init --repo-id my-service  # GitHub Copilot

opencode-init merges the server into opencode.json (OpenCode's mcp format) and writes the same agent guidance as a marked section of AGENTS.md. codex-init adds the server table to .codex/config.toml (other tables and comments are kept) and writes the same AGENTS.md section; Codex loads it once you trust the project. copilot-init writes the portable .mcp.json that Copilot CLI and VS Code both read (the same entry Claude Code uses) and the guidance as a marked section of .github/copilot-instructions.md.

cursor-init writes .cursor/mcp.json (merged into an existing one) and the rule .cursor/rules/bgts-context-engine.mdc, which tells the agent to call get_context_for_task first, treat its file:line entries as verified locations instead of grepping for them, and not to edit a file just because it was listed. claude-init writes .mcp.json, a marked section in CLAUDE.md, and a UserPromptSubmit hook (bce precontext) that runs the graph once per prompt and hands the agent the answer before its first turn. An earlier 14-task benchmark on a React/TypeScript codebase measured this hook at −20 % tokens and half the search output with the same or better checks;