Product wiki
RAGRAF documentation — in depth, with evidence
Everything needed to understand and apply the product: the problem space, architecture, operations, index freshness, CPG and GPU, benchmarks and the roadmap. Every article is grounded in code (file:line) or measurement artifacts.
Core & principles
Problem space: why an agent cannot be trusted with memory of code
Three measured symptoms of a blind agent, VulnGym and LLMxCPG data, and the five anti-requirements that shaped RAGRAF's architecture.
Architecture: three SQLite files and zero infrastructure
Stores, the indexing pipeline, the answer envelope, provenance, deterministic identifiers and degradation — how RAGRAF works inside.
Freshness and drift: how the index keeps itself from lying
Immutable revisions, the append-only drift ledger, the checksum guard, stale marks, and "what changed in the knowledge" archives — RAGRAF's central guarantee.
Practice
Install and first run in 10 minutes
The Windows installer and the pip path, ensure, first indexing, first query and agent connection — with real numbers and typical pitfalls.
The agent working regimen: MCP, AGENTS.md and typical scenarios
23 MCP tools, agent modes, the "ask the index, not grep" regimen, and three working scenarios with real call counts.
Admin panel: catalog, quality, usage, settings
How the local panel at 127.0.0.1:8777 works: four blocks, the REST API, the mutation token gate, security, and the interactive emulator.
CLI: commands, flags, exit codes
The full ragraf command-line reference: install, ensure, query, reindex, selftest, global flag order and exit codes.
Diagnostics: the recipe book
Symptoms → causes → fixes: install, indexing, Joern, embeddings, MCP, panel, Windows specifics. All from real runs and the defect register.
Reference
The 22 operations: full facade reference
Every operation — purpose, key flags, what the result contains and which limits it declares. The answer envelope and reading rules.
Corpus configuration: every key explained
A full walkthrough of the YAML config: project, file selection, secrets, embeddings, index thresholds, Joern, reindex gates and validation.
The CPG layer: Joern, interprocedural calls and honest degradation
What Joern (php2cpg) adds, the 12 CPG facts, the torch.sparse backend, the degraded contract, and why a missing Joern is a mode — not an accident.
GPU compute: when graphs and embeddings run on the video card
RAGRAF's two GPU paths (embeddings and tensor graph traversal), measured switch thresholds, the backend cascade and the honest economics of acceleration.
Evolution
Benchmarks and limits: what is proven and what is not
Every published product number with its source: navigation tasks, fact verifiability, latencies, indexing — and an honest breakdown of what must not be believed.
Future directions: what comes next and what it will bring
The product roadmap by track: taint analysis, parallel indexing, query cache, multi-corpus, LSP bridge, live A/B evidence — with the benefit of each item.