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.
Quick start · Use it from your agent · How it works · Supported models · Documentation · 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 context pack. 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.
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.
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
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 — the flow the agent benchmark measured (−20 % tokens, half the search
output, same or better checks; 14 tasks on a React/TypeScript codebase, same model and machine).
Cursor's prompt hook cannot add context, so there the rule does that job. --no-hook,
--repo-id (repeatable) and --bce-command adjust the files; both commands are safe to rerun.
After you add or change the MCP config, restart Cursor or VS Code (or Command Palette → “Developer: Reload Window”). The server should then show as enabled with eight tools (ten with indexing enabled). Setup detail: docs/mcp.md. The manual equivalents:
Cursor — user config ~/.cursor/mcp.json (applies to every project), or a project
.cursor/mcp.json that stays local (the directory is gitignored):
{
"mcpServers": {
"bgts-context-engine": {
"command": "bce",
"args": ["serve-mcp"],
"env": { "BCE_DB_HOST": "localhost", "BCE_DB_NAME": "bce" }
}
}
}
VS Code — user MCP settings, or a project .vscode/mcp.json (also gitignored):
{
"servers": {
"bgts-context-engine": {
"type": "stdio",
"command": "bce",
"args": ["serve-mcp"],
"env": { "BCE_DB_HOST": "localhost", "BCE_DB_NAME": "bce" }
}
}
}
Claude Code — one command:
claude mcp add bgts-context-engine --env BCE_DB_HOST=localhost -- bce serve-mcp
Claude Desktop — same block as Cursor, in claude_desktop_config.json.
If command: "bce" stays disconnected, the editor cannot see bce on PATH. Install as
above, or skip a permanent install with uvx:
"command": "uvx",
"args": ["--from", "bgts-context-engine[mcp]", "bce", "serve-mcp"]
Then ask your agent something that needs the repository rather than the file you have open:
"what breaks if I change the session TTL?" The agent calls get_context_for_task, and the
other tools in docs/mcp.md let it drill from there — exact callers, the blast
radius of a change, the symbol behind a name — without guessing at file names.
What comes back
Not a list of file paths. A ranked pack, with the reasoning attached:
{
"anchors": {
"python::api::webhooks::handle_meeting_webhook#a3f1": ["explicit", "lexical"],
"python::auth::session::refresh_session#88c2": ["lexical", "semantic"]
},
"context": {
"items": [
{ "symbol_id": "...refresh_session#88c2", "name": "refresh_session", "kind": "function",
"file_id": "my-service:src/auth/session.py", "line": 41, "detail_level": "full",
"graph_distance": 0, "score": 11.42, "tokens": 214, "content": "def refresh_session(...)" },
{ "symbol_id": "...SESSION_TTL#4b0d", "name": "SESSION_TTL", "kind": "constant",
"file_id": "my-service:src/auth/config.py", "line": 12, "detail_level": "signature",
"graph_distance": 2, "score": 6.10, "tokens": 31, "content": "SESSION_TTL: int" }
],
"used_tokens": 1388, "budget": 1500, "included": 20, "skipped": 0
},
"coverage": {
"anchor_source_count": 3, "connected_component_ratio": 0.875,
"top_candidate_margin": 1.84, "orphan_ratio": 0.0,
"touches_god_node": false, "commit_mismatch": false,
"confidence": "high"
}
}
Three things here that a vector store cannot give you:
anchors says why the engine looked where it did, and which independent sources
agreed. Three sources agreeing is usually right; one is a guess.
coverage is a trust report. confidence: "low" means the engine found something but
could not corroborate it — the moment for an agent to ask a follow-up question instead of
editing. commit_mismatch means the index is behind your working tree.
detail_level falls off with graph distance: the symbol you are changing arrives in
full, its neighbours as signatures, the outer ring as name @ file:line. That is how twenty
genuinely relevant symbols fit in 1500 tokens — short enough for an agent to carry on every
turn. Every item also names its file_id and line, so the agent opens the file instead of
searching for the symbol.
How it works
task text
│
├─ anchors four independent sources nominate entry points:
│ explicit names, task history, full-text, vector
├─ expansion fixed-shape graph walk: callers 2 hops, callees 1,
│ references, type hierarchy, same-file siblings
├─ scoring weighted sum over reference kind, task signal, centrality,
│ distance, leaf penalty, edge provenance
├─ scope drop repositories this caller may not see
├─ narrowing keep the top N
├─ assembly fit the token budget, cheaper detail further out
└─ coverage report how much