Home

RAGRAF Wiki

A graph-and-vector knowledge base of code for LLM agents. Facts with file:line instead of blind grep — and an index that knows when it is stale.

---

Start here

🚀 New to RAGRAF? Problem Statement — why an agent with rg is not enough, with measurements Getting Started — install in 5 minutes, first query in 10 Architecture — three SQLite stores, immutability, drift ledger	🔧 Using it daily? Operations Reference — all 22 operations + the answer envelope CLI Reference — every command and flag MCP Integration — attach RAGRAF to your agent Troubleshooting — recovery recipes
📚 Reference Configuration — corpus config, exclusions, secrets CPG & Joern Layer — optional interprocedural graph Admin Panel — local web dashboard Benchmarks & Limits — what was measured, what was not	🤝 Project FAQ — short answers to common questions Contributing — defect reports, conventions, doctrine checker ROADMAP — where the product is going Defect Register — findings of the 2026-10 revision

---

What RAGRAF is, in one paragraph

An LLM agent modifying an existing codebase burns most of its context on navigation: where is this defined, who calls it, what breaks if I change it. RAGRAF indexes the repository once (tree-sitter graph + FTS5 lexicon + local vectors, all in SQLite) and then answers those questions through 22 fixed operations — every fact carrying a path:line reference, a provenance mark (stated vs derived), and a freshness state. When the code moves ahead of the index, RAGRAF knows: the drift ledger marks affected facts stale, and the guard can reindex automatically. No graph query language is exposed — by design, backed by measurements (LLMxCPG, USENIX Sec '25: base models write valid CPGQL in 19–132 cases out of 1278).

The headline numbers

Measured on a real PHP portal (14 navigation tasks, artifacts in bench/results/):

Metric	Without index	With index
Tool calls per task	2.0–3.1	1.0
Files read in full	14	0
First-query target hit	—	92%
Facts with file:line	—	100%
Defects found/prevented during one real feature	—	16 (4 before code ran)

Honesty corner — what these numbers are NOT

• The 2–3× call savings applies to localization tasks; in the read→edit→verify loop the count is roughly equal (the win there is correctness, not speed).
• The baseline (28 calls) was computed in favor of rejecting the index; the realistic estimate is 43.
• Token figures are estimates (4 chars/token, measured coefficient), not inference measurements.
• The sample is small: 14 tasks + one real development effort. Enough to see the difference, not enough for a statistical claim.
• A live «agent with index vs agent without» comparison is the next evidence level — not done yet (roadmap R-EVID-1).

Full limits: Benchmarks & Limits.

System requirements (short)

Python	3.13+ (verified on 3.14)
OS	Windows + PowerShell 7.6 — verified; Linux/macOS — best-effort, unverified
Privileges	none (everything lives in the user profile)
Disk	~2.5 GB for the environment; ~1 MB of index per 1–2 source files; +5–6 GB for the optional Joern layer
Network	PyPI at install; ~240 MB model at first vector indexing

Details and the TLS-inspection caveat: Getting Started.

Repository map

RAGRAF/
├─ src/ragraf/          the core: facade (22 ops), MCP server (23 tools), CLI,
│                       indexer, guard, drift ledger, three SQLite stores
├─ tools/               entry points: ragraf.py, ragraf-mcp.py, ragraf-admin.py
├─ scripts/             install.ps1 · install-joern.ps1 · ragraf.ps1
├─ docs/                architecture, specification, acceptance protocols,
│                       integration, CPG study, the article, the agent skill
├─ tests/               portable checks on synthetic fixtures (6 suites, 164 checks)
├─ bench/results/       measurement artifacts (M2, rev-0012 / rev-0025)
└─ examples/            corpus config template

---

Wiki language: English (2026 production pass). The original Russian documentation is preserved in the repository history. Every number in this wiki is traceable to code (file:line) or to a shipped artifact.