Repository navigation
12 FAQ
Short answers. Links go deep.
What IS RAGRAF, in one sentence?
A local, file-based (SQLite) knowledge index of a codebase that answers an agent's navigation/structure/schema questions through 22 fixed operations — every fact with file:line, provenance and freshness marks. → Home
Is it a RAG framework? A vector DB? An agent? No, no, no. Vectors are one supplementary layer (FTS5 lexicon + graph are primary, P5). It answers; the agent edits. → Problem Statement §6
Why the name? RAG + GRAph + Facts: retrieval-augmented graph of verifiable facts. (The product judges itself by whether a fact can be checked, not by how it is named.)
What does it cost to run? Zero services. Python 3.13+, ~2.5 GB environment, ~1 MB index per 1–2 source files, optional ~5–6 GB Joern layer, one 240 MB model download. No admin rights, no Docker, no DB server. → Getting Started
Which languages? 16 tree-parsed (PHP, Python, JS, TS, Java, C#, C, C++, Ruby, Lua, Go, Perl, bash, PowerShell, CSS, HTML) + 10 text-attached (Markdown, SQL, YAML, JSON, TOML, INI, XML, RST, batch, text). PHP is the most battle-tested (the pilot); the CPG layer currently targets PHP via php2cpg. → Configuration
Why no Cypher/CPGQL? Query languages are more flexible.
Because base models write valid CPGQL in 19–132 cases out of 1278 (LLMxCPG, USENIX Sec '25). A flexible interface the caller cannot use correctly is an error generator. Fixed operations + limits in every answer beat expressiveness. → Problem Statement §2
The agent edited files. Does the index break?
No. The index is immutable within a revision (P1). Edits accumulate in the append-only drift ledger; affected facts are marked stale in every answer; the guard can reindex automatically on thresholds (5/20 edits, 15 min). → Architecture
slice refuses with exit code 3. Broken?
No — that's the contract. Exit 3 = «operation cannot run now» (CPG layer absent: capability=degraded). Empty result would be exit 0 + found=false. Install the Joern layer to unlock. → CLI Reference · CPG Layer
selftest is green. Are we good?
selftest always exits 0 — it's a report, not a gate. Read the 11 component checks (9 required + joern/java optional). → Getting Started
Answers say provenance: derived. Trust them?
Separately: stated = analyzer-proven (confidence 1.0), derived = heuristic (0.30–0.60, calibratable). impact --mode hard gives proven-only. A conclusion on derived requires verification — that's rule №4 of the agent regimen. → Operations Reference
Why is search ~1 s when symbol is 0.7 ms?
Hybrid search computes the query embedding per call (no cache yet — roadmap R-PERF-3). Everything structural is index-backed SQLite. → Benchmarks
Where do secrets go?
Nowhere. secrets_exclude files are never opened — not indexed, not chunked, not embedded, not logged. Config-value references index the fact of the reference, never values. Verified by pattern test M3-T2. → Configuration
Is my code uploaded anywhere?
No. Everything is local: SQLite files in <project>/.ragraf/, model in ~/.ragraf/models. The only network traffic is PyPI at install and the one-time model download (both avoidable: -NoVectors, offline wheels on the roadmap).
How do I make my agent actually use it?
Three moves: register the MCP server (config snippet in the docs), paste the ready AGENTS.md block (index-first regimen, forbidden list), and start sessions with ragraf_index_status + ragraf_drift_report. → MCP Integration
What benefit should I expect? Localization tasks: ~2–3× fewer tool calls, 0 full-file reads, 92% first-query hit (measured, small sample). Edit loops: roughly call-neutral — the win is correctness (schema/permission defects caught before runtime: 4 prevented in one feature). Don't expect magic on «read → edit → verify». → Benchmarks
We have a huge monorepo. Will it scale? Indexed corpora: 123–392 files measured end-to-end; the design targets ≤15 min full index at 162 K lines (NFR-2) and holds (71 s at 323 files incl. CPG). Known ceilings: KNN scan without ANN above ~500 K chunks (migration threshold documented), sequential parsing (R-PERF-1), full CPG rebuild per reindex (Joern has no incremental mode). → Architecture §Performance
Can I use it in CI?
Yes: install.ps1 -SummaryJson, exit codes 0/1/2/3 with documented semantics, --json on every operation, selftest --json. A ready GitHub Actions workflow is in the release checklist deliverables. → Contributing
Why is half the documentation about PHP? Release 1 was PHP-only by owner decision; the pilot corpora are PHP portals. The shipped product already parses 16 languages; PHP remains the deepest-verified path (it's where all 12 Joern surprises were found). → CPG Layer
The docs reference files I can't find (AGENTS.md, tests/test_mcp.py, …).
Known release defect (A-01…A-03 in the defect register): the public tree shipped with references to the author's private tooling. EN docs mark every such reference (not shipped); publishing or excising them is roadmap R-REL-1. → Defect Register
Docs said 17 operations, README says 22, MCP has 23. Which is right?
All — at different times/surfaces: the spec (release-1 scope) froze 17; the shipped facade has 22 op_*; MCP exposes 23 tools (adds ensure, omits calibrate); CLI query accepts 23 (adds usage). The EN docs carry sync notes. Defect B-01; single-source generation is roadmap R-DOC-2.
How do I report a bug so it gets taken seriously? The project's currency is a fact with a reference: reproducible command + output + revision + checksum. There's an issue template for exactly that. → Contributing
License? MIT. Joern/JDK (optional, separately installed) are Apache-2.0. Dependencies keep their own licenses (all MIT/Apache/BSD-family).
Next: Contributing →