Skip to content
Back to search

bgts-context-engine

Deterministic code-graph context engine for AI coding agents - PostgreSQL + Apache AGE + pgvector, MCP & REST, no LLM in the loop.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/bgts-ai-org/bgts-context-engine with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/bgts-ai-org/bgts-context-engine'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/bgts-ai-org--bgts-context-engine/badge.svg)](/listings/bgts-ai-org--bgts-context-engine)

HTML

<a href="/listings/bgts-ai-org--bgts-context-engine"><img src="/api/listings/bgts-ai-org--bgts-context-engine/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 533 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <!-- mcp-name: io.github.bgts-ai-org/bgts-context-engine -->
  2. <div align="center">
  3. <img src="https://raw.githubusercontent.com/bgts-ai-org/bgts-context-engine/main/docs/assets/readme-hero.gif" alt="BGTS Context Engine: a coding agent searching the repository turn after turn, next to the same agent starting from BCE's code graph" width="820">
  4. **Deterministic code-graph context for AI coding agents.**
  5. Ask *"why does the login timeout fire on the meeting webhook?"* and get the eight symbols
  6. that actually answer it — ranked, budgeted, and reproducible.
  7. [![Tokens −82%](https://img.shields.io/badge/tokens-%E2%88%9282%25-39ff88?style=for-the-badge&labelColor=0b0f14)](#results)
  8. [![Cost −63%](https://img.shields.io/badge/cost-%E2%88%9263%25-f2ac0b?style=for-the-badge&labelColor=0b0f14)](#results)
  9. [![Tool calls −89%](https://img.shields.io/badge/tool_calls-%E2%88%9289%25-4d8dff?style=for-the-badge&labelColor=0b0f14)](#results)
  10. [![Time −37%](https://img.shields.io/badge/time-%E2%88%9237%25-f1881e?style=for-the-badge&labelColor=0b0f14)](#results)
  11. [![Recall 92.7%](https://img.shields.io/badge/recall-92.7%25_kept-22c55e?style=for-the-badge&labelColor=0b0f14)](#results)
  12. <sub>Two coding agents, 600 real merged changes, 12 repositories, 6 languages — the agent alone against the same agent with BCE as its first step.</sub>
  13. [![PyPI](https://img.shields.io/pypi/v/bgts-context-engine.svg)](https://pypi.org/project/bgts-context-engine/)
  14. [![Python](https://img.shields.io/pypi/pyversions/bgts-context-engine.svg)](https://pypi.org/project/bgts-context-engine/)
  15. [![CI](https://github.com/bgts-ai-org/bgts-context-engine/actions/workflows/ci.yml/badge.svg)](https://github.com/bgts-ai-org/bgts-context-engine/actions/workflows/ci.yml)
  16. [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
  17. [![MCP](https://img.shields.io/badge/MCP-compatible-000000.svg)](docs/mcp.md)
  18. [![Stars](https://img.shields.io/github/stars/bgts-ai-org/bgts-context-engine?style=flat&logo=github)](https://github.com/bgts-ai-org/bgts-context-engine/stargazers)
  19. [Results](#results) · [Quick start](#quick-start) · [Use it from your agent](#use-it-from-your-agent) · [How it works](#how-it-works) · [Supported models](#supported-models) · [Selector models](docs/selector.md) · [Documentation](#documentation) · [Website](https://bgts-ai-org.github.io/bce-microsite/) · [Türkçe](README.tr.md)
  20. </div>
  21. ---
  22. ## Why this exists
  23. An agent working on an unfamiliar repository has to decide what to read before it can
  24. decide what to change. The usual answer is embedding search over chunked files. It is cheap
  25. to build and wrong in a specific way: it returns text that *reads* like the question rather
  26. than code that *participates* in the behaviour. Ask about a login timeout and you get the
  27. five files that mention timeouts, not the one function that sets it and the three callers
  28. that break when you change it.
  29. That information is structural, and it has an exact answer. `handleLogin` calls
  30. `refreshSession`, which reads `SESSION_TTL`, which is written in exactly one place. That is
  31. a graph walk.
  32. BGTS Context Engine indexes your repositories into that graph — symbols, calls,
  33. references, type hierarchies, HTTP routes, cross-language bridges — and answers questions
  34. by walking it. Embeddings are used in one place only: finding entry points when the task
  35. text names nothing recognisable. They never affect ranking.
  36. **The same task text, against the same commit, returns the same ranking.** No model in
  37. the retrieval path, no clock, no randomness. When an agent makes a bad change you can
  38. replay exactly what it was told, find the stage that surfaced the wrong symbol, and fix
  39. that stage.
  40. On top of that ranking sits one optional, clearly marked probabilistic step: a *context
  41. selector* that asks a decision model which of the ranked files the task actually edits and
  42. hands the agent those in full, the likely-related ones as one line each, and nothing else.
  43. On 600 real changes it cut the tokens handed to the agent from 8 310 to 1 121 (−87 %) for
  44. about one point of recall (94.4 → 93.3). It is off until
  45. `BCE_SELECTOR` names a model — hosted Jev, or decider-2b / decider-4b on your own GPU — and
  46. `--no-select` gives back the byte-exact pack.
  47. The engine is published so people can run it. Organisations that want the same thing
  48. inside their own perimeter — help with indexing, deployment, scoring tuned to their
  49. repositories, or the agent stack around it — can engage
  50. [BGTS](https://www.bgts.com) for consulting. Write to
  51. **opensource-ai@bgts.com**.
  52. ## Results
  53. Two coding agents ran the same 600 tasks. Each task is a change a project actually merged,
  54. 50 per repository across 12 open-source repositories in six languages: flask and requests
  55. (Python), express and axios (JavaScript), nest and vite (TypeScript), guava and netty
  56. (Java), efcore and PowerShell (C#), gin and prometheus (Go). The agent gets the developer's
  57. sentence in a copy with the history removed and has to name the source files the change
  58. touched. Every task ran twice: the agent **alone**, with its own grep, glob and read tools,
  59. and the agent **with BCE as its first step** (`BCE_AGENT_MODE=hint`): it asks the engine,
  60. starts from the answer and adds to it when it needs to.
  61. | Per task | Cursor CLI · grok-4.7-high-fast<br>alone → with BCE | OpenCode · GLM 5.3 Flash<br>alone → with BCE | Change<br>(mean of both) |
  62. | --- | --- | --- | --- |
  63. | Tokens | 264k → 59k | 196k → 24k | **−82 %** |
  64. | Cost | −60 % | −67 % | **−63 %** |
  65. | Tool calls | 17.4 → 2.0 | 11.3 → 1.1 | **−89 %** |
  66. | Model turns | 9.1 → 3.0 | 8.3 → 2.1 | **−71 %** |
  67. | Wall time | 65 s → 42 s | 132 s → 83 s † | **−37 %** |
  68. | File recall | 95.6 % → 92.9 % | 89.2 % → 92.5 % | **92.4 → 92.7 %** |
  69. The agent stops searching the tree: most of what it saves is the context it re-reads on
  70. every turn while it greps (cache-read tokens fall by about 90 %). The weaker model gains recall — BCE's
  71. graph supplies the files GLM 5.3 Flash missed on its own (hard tasks 74 → 81 %). With
  72. `BCE_AGENT_MODE=trust`, where the agent takes the answer as the set of locations and does
  73. not search at all, Cursor CLI went further: 45k tokens, 1.3 tool calls, 36 s, 92.3 % recall.
  74. > **Read the numbers with these in mind.**
  75. > Recall is the target, not precision: the engine tells the agent to pass its file list on,
  76. > about 15 files per task against 1.9 alone, so precision falls (Cursor CLI 91 → 11 %).
  77. > Cursor CLI had web access in its alone runs and sometimes found the change on GitHub,
  78. > which lifts that baseline. Cost is priced with one rate card for both agents (OpenRouter's
  79. > GLM 5.3 Flash rates for input, output and cache read), so the Cursor CLI column is not
  80. > Cursor's own bill. OpenCode's two runs are compared on the 597 tasks both
  81. > completed. † OpenCode's runs with BCE were on a machine with no free memory (16 GB, 99 %
  82. > used); MCP start-up and the engine call are normalised to an idle machine's medians, the
  83. > raw mean was 155 s. The harness is not in this repository yet — see the
  84. > [roadmap](#roadmap).
  85. ## Quick start
  86. ```bash
  87. # 1. PostgreSQL 16 with Apache AGE + pgvector, in one database
  88. docker compose -f deploy/docker-compose.yml up -d
  89. # 2. Install and migrate
  90. pip install bgts-context-engine
  91. cp .env.example .env
  92. bce migrate
  93. # 3. Index something
  94. bce index --repo /path/to/your/repo --name my-service
  95. # 4. Ask
  96. bce context --task "fix the login timeout in the meeting webhook"
  97. ```
  98. Then serve it:
  99. ```bash
  100. bce serve # REST at :8000/docs, web UI at :8000/ui/
  101. bce serve-mcp # MCP over stdio, for agents (install the [mcp] extra; see below)
  102. ```
  103. ## Use it from your agent
  104. The MCP surface is behind the `mcp` extra (Python MCP SDK 1.x: `mcp>=1.0,<2`). Install it
  105. so `bce` is on the **user PATH**, not only inside a project `.venv`. Cursor and VS Code
  106. spawn `bce serve-mcp` themselves and do not activate the venv:
  107. ```bash
  108. pip install "bgts-context-engine[mcp]"
  109. bce --version # must work in a new terminal, with no venv activated
  110. ```
  111. Every MCP client uses the same stdio command plus the database in the environment. Do not
  112. leave `bce serve-mcp` running in a terminal for the editor: stdout is the protocol, so the
  113. process stays silent, and the IDE starts its own copy.
  114. **One command per editor.** Run it in the project the agent works on (the repository you
  115. indexed), pointing at the engine's `.env`:
  116. ```bash
  117. bce --env-file /path/to/engine/.env cursor-init --repo-id my-service # Cursor
  118. bce --env-file /path/to/engine/.env claude-init --repo-id my-service # Claude Code
  119. bce --env-file /path/to/engine/.env opencode-init --repo-id my-service # OpenCode
  120. bce --env-file /path/to/engine/.env codex-init --repo-id my-service # Codex
  121. bce --env-file /path/to/engine/.env copilot-init --repo-id my-service # GitHub Copilot
  122. ```
  123. `opencode-init` merges the server into `opencode.json` (OpenCode's `mcp` format) and writes
  124. the same agent guidance as a marked section of `AGENTS.md`. `codex-init` adds the server
  125. table to `.codex/config.toml` (other tables and comments are kept) and writes the same
  126. `AGENTS.md` section; Codex loads it once you trust the project. `copilot-init` writes the
  127. portable `.mcp.json` that Copilot CLI and VS Code both read (the same entry Claude Code
  128. uses) and the guidance as a marked section of `.github/copilot-instructions.md`.
  129. `cursor-init` writes `.cursor/mcp.json` (merged into an existing one) and the rule
  130. `.cursor/rules/bgts-context-engine.mdc`, which tells the agent to call
  131. `get_context_for_task` *first*, treat its `file:line` entries as verified locations instead
  132. of grepping for them, and not to edit a file just because it was listed. `claude-init`
  133. writes `.mcp.json`, a marked section in `CLAUDE.md`, and a `UserPromptSubmit` hook
  134. (`bce precontext`) that runs the graph once per prompt and hands the agent the answer
  135. before its first turn. An earlier 14-task benchmark on a React/TypeScript codebase measured
  136. this hook at −20 % tokens and half the search output with the same or better checks; the
  137. 600-task numbers in [Results](#results) measure the MCP flow on Cursor CLI and OpenCode.
  138. Cursor's prompt hook cannot add context, so there the rule does that job. `--no-hook`,
  139. `--repo-id` (repeatable) and `--bce-command` adjust the files; every init command is safe to
  140. rerun.
  141. **Two agent modes.** `BCE_AGENT_MODE` sets how far the agent relies on the answer. Every init
  142. command writes it into the server entry's `env` block (`environment` in `opencode.json`);
  143. change it there and reload the MCP server to switch:
  144. - `hint` (**starting point**, the default): the agent designs the change from the code the
  145. answer shows, reads only the ranges it leaves out, opens the files of identifiers the answer
  146. does not cover, and searches as usual for anything else; the answer's "Gaps" section lists
  147. what the engine knows it lacks.
  148. - `trust` (**localize-only, for benchmarks**): the answer's files are the set of locations; the
  149. agent opens those files and does not search the tree. It measures the engine alone.
  150. On the 600 tasks with Cursor CLI, `hint` reached 92.9 % file recall at 59k tokens per task and
  151. `trust` 92.3 % at 45k, against 95.6 % and 264k for the CLI alone.
  152. The server states the active mode's steps in the tool description and in every answer's
  153. `payload.workflow`, and the rules tell the agent to follow them, so switching needs no rule
  154. edit. `--mode hint|trust` picks it at init; a rerun keeps the configured value. Details:
  155. [docs/mcp.md](docs/mcp.md#agent-mode).
  156. After you add or change the MCP config, **restart Cursor or VS Code** (or Command Palette
  157. → “Developer: Reload Window”). The server should then show as enabled with eight tools (ten with indexing enabled).
  158. Setup detail: [docs/mcp.md](docs/mcp.md). The manual equivalents:
  159. **Cursor** — user config `~/.cursor/mcp.json` (applies to every project), or a project
  160. `.cursor/mcp.json` that stays local (the directory is gitignored):
  161. ```json
  162. {
  163. "mcpServers": {
  164. "bgts-context-engine": {
  165. "command": "bce",
  166. "args": ["serve-mcp"],
  167. "env": { "BCE_DB_HOST": "localhost", "BCE_DB_NAME": "bce" }
  168. }
  169. }
  170. }
  171. ```
  172. **VS Code** — user MCP settings, or a project `.vscode/mcp.json` (also gitignored):
  173. ```json
  174. {
  175. "servers": {
  176. "bgts-context-engine": {
  177. "type": "stdio",
  178. "command": "bce",
  179. "args": ["serve-mcp"],
  180. "env": { "BCE_DB_HOST": "localhost", "BCE_DB_NAME": "bce" }
  181. }
  182. }
  183. }
  184. ```
  185. **Claude Code** — one command:
  186. ```bash
  187. claude mcp add bgts-context-engine --env BCE_DB_HOST=localhost -- bce serve-mcp
  188. ```
  189. **Claude Desktop** — same block as Cursor, in `claude_desktop_config.json`.
  190. If `command: "bce"` stays disconnected, the editor cannot see `bce` on PATH. Install as
  191. above, or skip a permanent install with `uvx`:
  192. ```json
  193. "command": "uvx",
  194. "args": ["--from", "bgts-context-engine[mcp]", "bce", "serve-mcp"]
  195. ```
  196. Then ask your agent something that needs the repository rather than the file you have open:
  197. *"what breaks if I change the session TTL?"* The agent calls `get_context_for_task`, and the
  198. other tools in [docs/mcp.md](docs/mcp.md) let it drill from there — exact callers, the blast
  199. radius of a change, the symbol behind a name — without guessing at file names.
  200. ## What comes back
  201. Not a list of file paths. A ranked pack, with the reasoning attached:
  202. ```json
  203. {
  204. "anchors": {
  205. "python::api::webhooks::handle_meeting_webhook#a3f1": ["explicit", "lexical"],
  206. "python::auth::session::refresh_session#88c2": ["lexical", "semantic"]
  207. },
  208. "context": {
  209. "items": [
  210. { "symbol_id": "...refresh_session#88c2", "name": "refresh_session", "kind": "function",
  211. "file_id": "my-service:src/auth/session.py", "line": 41, "detail_level": "full",
  212. "graph_distance": 0, "score": 11.42, "tokens": 214, "content": "def refresh_session(...)" },
  213. { "symbol_id": "...SESSION_TTL#4b0d", "name": "SESSION_TTL", "kind": "constant",
  214. "file_id": "my-service:src/auth/config.py", "line": 12, "detail_level": "signature",
  215. "graph_distance": 2, "score": 6.10, "tokens": 31, "content": "SESSION_TTL: int" }
  216. ],
  217. "used_tokens": 1388, "budget": 1500, "included": 20, "skipped": 0
  218. },
  219. "coverage": {
  220. "anchor_source_count": 3, "connected_component_ratio": 0.875,
  221. "top_candidate_margin": 1.84, "orphan_ratio": 0.0,
  222. "touches_god_node": false, "commit_mismatch": false,
  223. "confidence": "high"
  224. }
  225. }
  226. ```
  227. Three things here that a vector store cannot give you:
  228. **`anchors`** says *why* the engine looked where it did, and which independent sources
  229. agreed. Three sources agreeing is usually right; one is a guess.
  230. **`coverage`** is a trust report. `confidence: "low"` means the engine found something but
  231. could not corroborate it — the moment for an agent to ask a follow-up question instead of
  232. editing. `commit_mismatch` means the index is behind your working tree.
  233. **`detail_level`** falls off with graph distance: the symbol you are changing arrives in
  234. full, its neighbours as signatures, the outer ring as `name @ file:line`. That is how twenty
  235. genuinely relevant symbols fit in 1500 tokens — short enough for an agent to carry on every
  236. turn. Every item also names its `file_id` and `line`, so the agent opens the file instead of
  237. searching for the symbol.
  238. With the context selector on, items also carry a **`tier`**: `full` for the two or three
  239. files the task most likely edits, `stub` — a single `path - N candidate symbols: …` line —
  240. for files that are probably related, and `coverage.selector` says what was cut and why
  241. ([docs/retrieval.md](docs/retrieval.md#context-selection-optional); models and setup in
  242. [docs/selector.md](docs/selector.md)).
  243. ## How it works
  244. <div align="center">
  245. <img src="https://raw.githubusercontent.com/bgts-ai-org/bgts-context-engine/main/docs/assets/architecture-overview.png" alt="BGTS Context Engine architecture: the repository becomes a code graph, embeddings find entry points, and at query time the engine drops anchors, expands the graph, scores, narrows, optionally selects, and assembles the pack" width="820">
  246. </div>
  247. <details>
  248. <summary>The same pipeline as text</summary>
  249. ```
  250. task text
  251. │
  252. ├─ anchors seven independent sources nominate entry points:
  253. │ explicit names and routes, file paths, task history,
  254. │ full-text, code usage, vector, impact
  255. ├─ expansion fixed-shape graph walk: callers 2 hops, callees 1,
  256. │ references, type hierarchy, same-file siblings
  257. ├─ scoring weighted sum over anchor strength, reference kind, task
  258. │ signal, proximity, kind prior, semantic rank, churn,
  259. │ centrality, leaf and test penalties, edge provenance
  260. ├─ scope drop repositories this caller may not see
  261. ├─ narrowing keep the top N
  262. ├─ selection optional: a decision model tiers the N files into
  263. │ full / one-line stub / dropped
  264. ├─ assembly fit the token budget, cheaper detail further out
  265. └─ coverage report how much of this is trustworthy
  266. ```
  267. </details>
  268. Callers reach two hops and callees only one, on purpose: when you change a function, what
  269. breaks is upstream of it. Of the structural signals, reference kind weighs the most, because
  270. a place that *writes* a value is where the bug lives while a place that *reads* it is usually
  271. just downstream. Centrality saturates at degree 20, because a logger touches everything and
  272. explains nothing.
  273. The full formula, every weight, and the confidence thresholds are in
  274. [docs/retrieval.md](docs/retrieval.md).
  275. ## Web UI
  276. `bce serve` ships a UI at `/ui/` that replays a real retrieval call stage by stage: anchors
  277. lighting up, expansion spreading, candidates scored and cut.
  278. <div align="center">
  279. <video src="https://github.com/user-attachments/assets/ac8ddd8f-2148-4d16-8c3a-3ce69d32b9d8" width="820" controls playsinline>
  280. UI walkthrough of the BGTS Context Engine web interface.
  281. </video>
  282. </div>
  283. ## Features
  284. - **Code graph, not chunks.** Symbols, `CALLS`, `REFERENCES`, `INHERITS`, `IMPLEMENTS`,
  285. `IMPORTS`, HTTP `ROUTES_TO` handlers, and `WHY:` comments bound to what they explain.
  286. - **Deterministic by construction.** Sorted traversal, stable tiebreaks, versioned scoring
  287. weights. `bce bench` verifies it by running each case repeatedly and comparing output.
  288. - **Under a seventh of the tokens, optionally.** The context selector keeps the files a task
  289. edits and lists the rest in one line each: 8 310 → 1 121 tokens per answer on 600 real
  290. changes, file recall 94.4 → 93.3 with Jev, fail-open to the plain ranking.
  291. - **Eight languages.** Python, JavaScript and TypeScript built in; Java, C#, Go, Rust and
  292. C/C++ behind the `langs` extra. [Adding one](docs/languages.md#adding-a-language) touches
  293. two files. `bce doctor` reports how much of each repository's code the index parsed, and an
  294. answer says so when part of it is in a language no installed parser handles.
  295. - **Cross-language call edges.** React Native and Expo bridges connect
  296. `NativeModules.Foo.bar()` in TypeScript to `bar` in Objective-C, Swift or Kotlin — a hole
  297. no single parser can see.
  298. - **Edge provenance you can audit.** `scip` from a real compiler index, `treesitter` from
  299. syntax, `heuristic` from a pattern match. Scored differently, reported per response.
  300. - **Incremental re-indexing.** `git diff` decides what to re-parse. Symbol ids survive file
  301. moves and reformatting, so history and embeddings stay valid.
  302. - **One database.** Apache AGE and pgvector in the same PostgreSQL, so one query joins a
  303. graph traversal, a vector search and a SQL filter — and one `pg_dump` backs up the index.
  304. - **MCP and REST from one implementation.** A focused tool set over stdio, the same functions
  305. over HTTP. Nothing to drift.
  306. - **A UI that explains itself.** `/ui` ships in the wheel and replays a real retrieval call
  307. stage by stage: anchors lighting up, expansion spreading, candidates scored and cut.
  308. - **Runs offline.** The default embedding provider is deterministic arithmetic over token
  309. digests. No API key, no network, repeatable benchmarks. `openai` talks to any
  310. OpenAI-compatible `/v1/embeddings` server (vLLM, TEI, Ollama), so a model such as
  311. [jina-code-embeddings-1.5b](https://huggingface.co/jinaai/jina-code-embeddings-1.5b)
  312. can run inside the perimeter.
  313. ## Supported models
  314. Embeddings only find entry points when the task text names nothing the graph already
  315. knows. They never rank the answer. Out of the box that seed is `hashing`: deterministic
  316. arithmetic, no API key, no network. For a real code model, set `BCE_EMBEDDING_PROVIDER`
  317. and `BCE_EMBEDDING_MODEL` to one of these:
  318. | Model | Provider | Dimension |
  319. | --- | --- | --- |
  320. | [`voyage-code-3`](https://blog.voyageai.com/2024/12/04/voyage-code-3/) | Voyage AI (`voyage`) | 1024 |
  321. | [`voyage-code-4`](https://blog.voyageai.com/2026/08/13/voyage-code-4/) | Voyage AI (`voyage`) | 1024 |
  322. | [`jina-code-embeddings-1.5b`](https://huggingface.co/jinaai/jina-code-embeddings-1.5b) | OpenAI-compatible (`openai`) | 1536 |
  323. Voyage is a hosted API — `pip install "bgts-context-engine[embed]"` and
  324. `BCE_VOYAGE_API_KEY`. Jina is the on-prem path: any server that speaks `/v1/embeddings`
  325. (vLLM, TEI, Ollama). Switching the model or the dimension is a re-index
  326. (`bce migrate --reset-embeddings`). The knobs are in
  327. [docs/deployment.md](docs/deployment.md).
  328. **Coming next** — same `openai` socket, not yet a fitted retrieval profile:
  329. - [`jina-code-embeddings-0.5b`](https://huggingface.co/jinaai/jina-code-embeddings-0.5b)
  330. — the smaller sibling of 1.5b, for hosts that cannot hold 1.5B parameters.
  331. - [`Nomic Embed Code`](https://huggingface.co/nomic-ai/nomic-embed-code) — an open 7B
  332. code retriever.
  333. ### Selector models
  334. The optional [context selector](#what-comes-back) runs one of these decision models over the
  335. ranked answer. Set `BCE_SELECTOR` to its name; unset (`off`), the engine returns the plain
  336. ranking at K=20.
  337. | `BCE_SELECTOR` | Model | Runs on | File recall @50 · tokens* |
  338. | --- | --- | --- | --- |
  339. | `jev` | [Jev 1.13](https://openrouter.ai/typesafe/jev-1.13) (`typesafe/jev-1.13`, TypeSafe) | hosted: [OpenRouter](https://openrouter.ai/docs/guides/community/jev) or [TypeSafe's API](https://www.typesafeai.org/guides/jev-api-quickstart) | 93.3 · 1 121 |
  340. | `decider-2b` | [Mapika/decider-2b](https://huggingface.co/Mapika/decider-2b) (open weights, Apache-2.0) | your GPU (16 GB+), via `decider.serve` | 89.8 · 1 355 |
  341. | `decider-4b` | [Mapika/decider-4b](https://huggingface.co/Mapika/decider-4b) (open weights, Apache-2.0) | your GPU (32 GB), via `decider.serve` | 92.1 · 1 193 |
  342. \* 600 real changes over 12 repositories, K=50, against 94.4 recall and 8 310 tokens without
  343. a selector. Jev needs `OPENROUTER_API_KEY` and sends task text and code excerpts to a third
  344. party; the deciders keep everything inside your perimeter and need no key.
  345. **Setup, the decider server install and RunPod notes: [docs/selector.md](docs/selector.md).**
  346. ## Where it fits
  347. | | Embedding RAG | Language server | BGTS Context Engine |
  348. | --- | --- | --- | --- |
  349. | Retrieval basis | text similarity | compiler index | code graph + anchors |
  350. | Cross-file, cross-repo | weak | per project | yes |
  351. | Cross-language edges | no | no | yes, heuristic |
  352. | Same query, same answer | no | yes | yes |
  353. | Ranked for *a task* | by similarity | not ranked | yes, with coverage |
  354. | Token budget aware | chunk count | no | yes, detail by distance |
  355. | Explains its own answer | no | no | anchors + provenance + confidence |
  356. A language server is exact but scoped to what you have open. Embedding search is broad but
  357. unaccountable. This sits between them: repository-wide and cross-language like the former,
  358. exact and reproducible like the latter.
  359. ## Measuring it
  360. Retrieval quality claims are worthless without the task set they were measured on, so the
  361. harness ships instead of a leaderboard. You give it your own tasks and the symbols you
  362. believe answer them:
  363. ```bash
  364. bce bench --cases my-tasks.json --out report.json
  365. ```
  366. Each case is a task text plus its ground-truth `symbol_id`s. The report gives recall,
  367. precision, precision@1 and MRR per case, median and p95 latency, and two pass/fail checks
  368. that matter more than the scores: every case is run repeatedly and must return a
  369. byte-identical ordering, and any case with a scoped principal must not surface a repository
  370. that principal cannot read.
  371. Building the case file is the real work — it means deciding, by hand, what the right answer
  372. is. It is also the only honest way to know whether a change to the scoring weights helped.
  373. The format and a worked example are in
  374. [docs/deployment.md](docs/deployment.md#benchmarking).
  375. `bce bench` measures the ranking. The numbers in [Results](#results) measure what an agent
  376. does with it: a second harness drives real agent CLIs (Cursor CLI, OpenCode) over the
  377. 12-repository task set, once alone and once per agent mode, and records tokens, cost, tool
  378. calls, model turns, wall time and file recall per run. That harness and its task set are
  379. not published yet.
  380. ## Roadmap
  381. Ordered by how often it comes up, not by difficulty:
  382. - **Scope enforcement on every layer.** Layer 3 applies the per-user repository filter;
  383. Layers 1 and 2 do not. Until that closes, the API belongs behind a proxy — see
  384. [SECURITY.md](SECURITY.md).
  385. - **Streamable HTTP transport for MCP.** Today the MCP surface is stdio only, so the server
  386. runs next to the agent. Remote transport makes one index serve a team.
  387. - **More languages.** Kotlin and PHP are the most requested. The provider interface is
  388. the contribution path with the least friction — see
  389. [docs/languages.md](docs/languages.md#adding-a-language).
  390. - **Wider SCIP ingestion.** Compiler-grade edges beat syntax-derived ones and are scored as
  391. such; more toolchains means more of the graph carries `scip` provenance.
  392. - **A published benchmark corpus.** The 600 tasks over 12 public repositories and the agent
  393. harness behind [Results](#results) run outside this repository today. Publishing them makes
  394. the results reproducible and comparable between projects rather than only between your own
  395. runs.
  396. Requests and disagreements belong in
  397. [issues](https://github.com/bgts-ai-org/bgts-context-engine/issues) — what people
  398. actually ask for reorders this list.
  399. ## Documentation
  400. | | |
  401. | --- | --- |
  402. | [Architecture](docs/architecture.md) | the deterministic line, the three layers, indexing |
  403. | [Retrieval](docs/retrieval.md) | anchors, expansion, every scoring weight, confidence |
  404. | [Selector models](docs/selector.md) | Jev, decider-2b and decider-4b: choosing, installing, configuring the context selector |
  405. | [Data model](docs/data-model.md) | node labels, edge types, tables, symbol identity |
  406. | [MCP and API](docs/mcp.md) | every tool and endpoint, MCP configuration, the CLI |
  407. | [Languages](docs/languages.md) | what each parser extracts, and how to add one |
  408. | [Deployment](docs/deployment.md) | configuration reference, jobs, backup, benchmarking |
  409. | [Web interface](web/README.md) | developing the frontend |
  410. ## Contributing
  411. Contributions are welcome — especially new languages, which is the contribution the
  412. pipeline is most ready for.
  413. Read [CONTRIBUTING.md](CONTRIBUTING.md) first. The one rule worth knowing up front:
  414. **determinism is the product.** A change that makes the same task return different results
  415. will not be merged without an explicit opt-in flag, and anything touching scoring or
  416. ordering needs a test that pins the output.
  417. ```bash
  418. pip install -e ".[dev,mcp]"
  419. ruff check src tests scripts && pytest
  420. cd web && npm ci && npm test
  421. ```
  422. ## Security
  423. The engine has no authentication of its own and expects to sit behind something that does.
  424. Only the Layer-3 endpoints apply the per-user repository scope. Read
  425. [SECURITY.md](SECURITY.md) before exposing a port, and report vulnerabilities privately
  426. rather than in an issue.
  427. ## License
  428. [MIT](LICENSE) © BGTS.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.