RAGRAF#

A graph-and-vector knowledge base of code for LLM agents.

Website · Wiki · Docs site · Releases · Discussions · Issues

An assistant that answers an agent's questions about a codebase — where is it, who calls it, what breaks if I change it, how is it done elsewhere — with verifiable facts (file:line) instead of blind rg and full-file reads. Python 3.13+, SQLite (graph + FTS5 + vectors in one place), tree-sitter, local embeddings without torch. It runs entirely on the machine that owns the code: no service to run, no cloud index, nothing sent anywhere — a local RAG index over your own repository. An optional property-graph layer (Java + Joern) unlocks slicing; without it the product still works and says so honestly.

Documentation status. Every count in this tree, in README.ru.md, in the Russian originals under docs/ru/ and in the wiki was re-measured from the sources on 2026-10-16; the summary is in By the numbers, and Test-DocumentedNumbers in the project checker compares those numbers with the code. Documents that describe the release-1 scope keep their own numbers on purpose — docs/architecture/SPECIFICATION.md still says 17 operations and states why — while the current surface is 38 operations / 40 MCP tools / 39 CLI query operations.

Contents#

• What this is and why

• Use cases

• Capabilities

• By the numbers

• How it works

• Installation

• First steps

• Requirements and limitations

• Documentation

• Development

• Contributing

• License

What this is and why#

An agent working on a code change spends most of its context on finding the place: where a function is defined, who calls it, how something similar is done nearby. The usual path is rg plus reading whole files.

RAGRAF replaces that path with an index. The agent asks a question through a fixed operation and gets a fact with a file:line reference — not ten candidates to review.

Measured on a real project (PHP portal, 14 navigation tasks; the run was made on the author's machine — see what the shipped artifacts measure below):

The call, hit-rate and verifiability numbers are measurements of that run; its raw artifacts are not part of the public tree (tracked as R-REL-1 in ROADMAP.md). What does ship is the artifact of the graph metric — bench/results/M2_rev-0012.json and M2_rev-0025.json measure impact-analysis completeness on the same portal: does the graph reach the files that were actually co-changed? Mean recall 0.771 → 0.917 over 20 and 8 commits at depth 3, median recall 1.0, precision 0.072 → 0.020 — deliberately low, because the metric counts connectivity, not prediction — against a naive baseline of 0.0.

«Realistically 43» is a modeled correction (the agent reviews up to 5 candidates instead of one), and it is recorded in the artifact itself.

Re-measured 2026-10-21, with the artifact shipped in the tree. The numbers above describe a run whose raw log is not public, so a new probe answers the same question in a way anyone can repeat: bench/nav_probe.py takes a real corpus (an open-source PHP library, 186 files, rev-0001, capability=full), builds a deterministic sample of 14 names from the source text (function / class declarations — the index takes no part in deciding the right answer), then compares two ways of locating a definition: rg -l over the same tree, and one symbol call.

Two honest notes. The single miss is group: four definitions carry that name (three WpCache::$group properties and one function), so the target sits at position 4 — the answer still carries the kind, which rg cannot, so the ambiguity is resolved inside the same call. And this corpus ships mirrored copies (php83/html.php, php85/html.php, src-8.5/), which is why file narrowing is only ×3.8 while byte narrowing is ×253: the same source file is legitimately declared in three places, and the index says so instead of hiding it.

One caveat usually omitted: the 2–3× win applies to localization tasks («where is it defined», «who calls it»). In the edit loop «read → change → verify» there is almost no savings in call count — the win there is different: edits do not corrupt the index, and disputed SQL is checked before it runs.

Use cases#

The numbers above are the contract, not marketing: a localization win is measured at 2–3× fewer tool calls, and the edit loop is measured honestly — see What this is and why.

Capabilities#

Thirty-eight operations over a repository — a fixed set, with no graph query language:

The same operations are available as 40 MCP tools (ragraf_*) — to attach to an agent as a server — and through the CLI.

Sixteen languages are parsed as trees (graph nodes and edges): PHP, Python, JavaScript, TypeScript, Java, C#, C, C++, Ruby, Lua, Go, Perl, bash, PowerShell, CSS, HTML — thirteen generic profiles plus dedicated PHP, CSS and HTML extractors. Eleven more are attached as text — files are findable by search but yield no nodes: Markdown, SQL, YAML, JSON, TOML, INI, XML, RST, Rust, batch, plain text. 55 file extensions are mapped in total.

By the numbers#

Every count below was measured on the published tree on 2026-10-16 — not copied from earlier prose. The two that matter most are gated by Test-DocumentedNumbers in tools/Invoke-ProjectDoctrine.ps1, which compares the documents with the code.

Dogfooding, for scale: RAGRAF indexes its own working tree (648 files, 140 741 lines — larger than this published subset) into 3 620 symbols, 46 296 edges and 3 417 chunks in 74 s, 63 s of which is the optional Joern/CPG stage (rev-0156, measured 2026-10-16; capability=full, 0 failed files). Full breakdown: wiki → Benchmarks and Limits.

Measured polygon, anonymised. The registry knows 28 corpora, 25 of them indexed — 10 with the CPG layer, 15 degraded. The 16 whose revision record was read on 2026-10-16 hold 7 527 files, 94 528 symbols, 791 871 edges and 86 790 chunks. Project names, paths and domains are withheld on purpose; the labels are ordered by size, and only the author's private map resolves them.

The full 16-row table, the anonymisation rules and a counting caveat are in the wiki → Benchmarks and Limits. That caveat matters when quoting numbers: the corpus registry and the revision record report different totals for the same revision (measured on one corpus: 8 721 vs 4 498 symbols, 41 201 vs 56 106 edges), so every count above is taken from the revision record — the one the answer envelope reports.

How it works#

Three SQLite stores per corpus, in a .ragraf/ directory inside the indexed project:

Indexing flow: scan (walk + checksums) → ast (tree-sitter: symbols, calls, SQL) → load → resolve (names) → schema (tables from migrations) → cpg (interprocedural calls via Joern) → lexvec (FTS5 + vectors).

Three decisions that define the behavior — each derived from a measured defect:

1. An immutable index and a ledger of differences instead of «updating on the fly». Within a revision the index does not change; code edits accumulate in the ledger, and affected facts are marked stale. Otherwise facts from different moments in time would mix in a single answer with no way to tell them apart — which is exactly how wrong conclusions are born.

2. The agent gets no graph query language. Fixed operations only. Rationale: in LLMxCPG (USENIX Security '25) base models produce 132/1278 and 19/1278 valid CPGQL queries versus 1278/1278 for a fine-tuned one — a free-form language turns into an error generator.

3. Every fact carries proof. path:line, provenance (stated — proven, derived — heuristic), index_rev, confidence. An edge without evidence looks credible only because it came «from the database».

Degradation instead of failure. A missing code property graph yields capability=degraded and an honest refusal from the slice operation stating the actual mode; all other operations work. No embedding model — lexical search works. No free port — the server reports the reason. Silent degradation never happens.

Installation#

Requires Python 3.13 or newer. No administrator rights needed.

Quick start (one command)#

The bootstrap installer fetches the package from GitHub and deploys it in a dialogue:

iwr -OutFile install.ps1 https://raw.githubusercontent.com/paulmann/RAGRAF/main/install.ps1
pwsh -NoLogo -NoProfile -File .\install.ps1

It asks for the installation directory (default C:\RAGRAF), creates the virtual environment and installs dependencies through scripts/install.ps1, offers to locate AutoClaw and DeepSeek Harness and to set up the connection, and finally prints how to start the admin panel plus a warning about access to it.

It states plainly what it does not do: AutoClaw values are shown, not written — AutoClaw accepts MCP servers only through its own interface, and its store belongs to the product. For Harness the installer can write the profile block, with a backup and a parse check afterwards. An existing installation is never overwritten silently, and a rehearsal run that skips dependencies is available: -SkipDeps.

Windows (PowerShell 7.6+)#

git clone https://github.com/paulmann/RAGRAF.git
cd RAGRAF
pwsh -NoLogo -NoProfile -File scripts/install.ps1

The script creates a virtual environment in ~/.ragraf/venv, installs dependencies, and verifies that the result is a working environment — step by step, ending with a summary table. It does not «pretend to install»: every step ends with a check. A full transcript is written to ~/.ragraf/logs/install-<timestamp>.log, and every external command runs under a timeout.

Useful variants:

# install and immediately prepare a corpus for your project
pwsh -File scripts/install.ps1 -Project C:\work\myproject

# same, plus full indexing (downloads the ~240 MB embedding model)
pwsh -File scripts/install.ps1 -Project C:\work\myproject -Index

# indexing without vectors: no model download, lexical search works
pwsh -File scripts/install.ps1 -Project C:\work\myproject -Index -NoVectors

# in a TLS-inspecting network (corporate proxy)
pwsh -File scripts/install.ps1 -WithTruststore

Other platforms#

One common path, works anywhere with Python 3.13+:

git clone https://github.com/paulmann/RAGRAF.git
cd RAGRAF
python -m venv .venv
. .venv/bin/activate            # Windows: .venv\Scripts\Activate.ps1
pip install -e .                # or: pip install -r requirements.txt
ragraf --version

The product also works without installing the package — via a wrapper that adds src/ to the path itself:

python tools/ragraf.py --version

scripts/install.ps1 is verified on Windows (PowerShell 7.6, Python 3.14). The common pip path on Linux and macOS is not verified — the product was developed and measured on Windows.

External layer: Java and Joern (optional)#

The interprocedural graph (the slice operation) needs JDK 21 and Joern. Without them the product works: the index builds, search and structure are available, and slice refuses with a reason.

# fetch (official GitHub release + Adoptium API), verify SHA-256, unpack, self-check
pwsh -File scripts/install-joern.ps1 -Download

# or verify/prepare from locally placed artifacts (no network)
pwsh -File scripts/install-joern.ps1

Archives go to .tools/downloads/ — the script is idempotent. The unpacked set takes about 5–6 GB.

First steps#

# 1. Prepare the corpus: find it, create it if missing, rebuild a stale index.
#    A corpus for an unknown directory is created by this same command.
ragraf ensure C:\work\myproject

# 2. Check the environment (report on 11 components).
#    NOTE: the command ALWAYS returns exit code 0 — it is not a gate; read the report.
ragraf -p <config> selftest

# 3. Ask
ragraf -p <config> query search "reindex delay"
ragraf -p <config> query symbol --name corpus_hash
ragraf -p <config> query code --name corpus_hash
ragraf -p <config> query callers --name dedupe
ragraf -p <config> query impact --target Facade --depth 2

# 4. Freshness: did the code change after indexing
ragraf -p <config> check

Full command list: ragraf --help. Important: the global flags --project/-p and --json go BEFORE the subcommand (ragraf -p cfg query search ...), while the subcommand's own flags go after it.

Exit codes: 0 — success (including an empty result with found=false), 1 — error, 2 — usage, 3 — the operation cannot run right now (e.g. slice while capability != full).

Corpus management#

ragraf init C:\work\myproject         # create the corpus config and print its path
ragraf -p <config> register           # register the project in the registry
ragraf -p <config> index              # full indexing
ragraf -p <config> reindex            # reindex + archive the drift ledger
ragraf -p <config> drift --scan       # register differences WITHOUT touching the index
ragraf -p <config> status             # state: revision, coverage, ledger size
ragraf -p <config> usage              # telemetry: calls, facts, effect estimate

Attaching to an agent as an MCP server#

{
  "mcpServers": {
    "ragraf": {
      "command": "python",
      "args": [
        "/path/to/RAGRAF/tools/ragraf-mcp.py",
        "--project", "/path/to/RAGRAF/config/mycorpus.yaml",
        "--agent", "my-agent",
        "--agent-kind", "external"
      ]
    }
  }
}

--project is required. --agent and --agent-kind exist only for per-agent call statistics: without them, calls are logged as unknown.

Admin panel#

python tools/ragraf-admin.py --no-browser

Opens on 127.0.0.1:8777 and listens on that address only. Shows corpora and their index states, store sizes, index quality, call statistics. Mutating requests require the access token printed at startup.

Requirements and limitations#

About the internet and certificates. In a TLS-inspecting network (corporate proxy) the model download fails certificate validation. The cure is truststore:

pip install truststore      # or: install.ps1 -WithTruststore

On a home network the package is unnecessary. Measured: without it — certificate verify failed; with it — 240 MB download in 9.2 s.

About the model cache. The cache directory is overridden by RAGRAF_MODEL_CACHE. Read operations never download the model — only indexing with vectors does.

Documentation#

Historical note: the original Russian documentation set is preserved under docs/ru/ in the source repository history. Some internal documents referenced by the deep-dive docs (research notes, effect reports on the author's private corpora) are intentionally not part of the public tree; references to them are marked (not shipped).

Development#

# tests run as standalone scripts — there is no unified runner yet
python tests/test_lang_routing.py
python tests/test_watch.py

# project convention checker (14 checks)
pwsh -NoLogo -NoProfile -File tools/Invoke-ProjectDoctrine.ps1

# refresh the index of RAGRAF itself
python tools/ragraf.py ensure .

The shipped checks are only those that run on synthetic fixtures and are portable. The rest measured behavior on the author's real corpora (a PHP portal, a C# service, their project configs) and would be meaningless on other code.

What passes right after installation:

Three checks require things the base installation does not include, and that is not a packaging defect but the nature of the check:

• test_joern_server.py — needs the external Java + Joern layer (scripts/install-joern.ps1);

• test_graph_algo.py — needs torch (~2.5 GB), which is in neither pyproject.toml nor requirements.txt: GPU graph algorithms are an optional branch, and without torch it honestly degrades to CPU;

• test_cpg_call_names.py — needs a corpus config (the config/ directory is not published); you can run the test by copying examples/ragraf.example.yaml into config/ and pointing it at your own root; without one it refuses to run rather than passing silently.

A tenth file, test_capability_consistency.py, reports «not applicable» until a corpus config exists — it validates the declared capability against what the graph actually contains. test_graph_algo.py without torch still runs 7 checks and names the 17 properties it could not check, rather than printing a green line over untested code.

The project checker is equally explicit about this published subset: of its 14 checks, 11 pass here and 3 report files that are deliberately absent from the public tree (the corpus config, tests/test_dedupe.py, tests/test_text_from_index.py) — tracked as R-REL-1 in ROADMAP.md.

selftest is not a gate: it prints a report on 11 components and always returns exit code 0. A non-zero code is not provided for, so a «green selftest» proves nothing by itself.

Contributing#

Useful reports: a reproducible defect with the command and its output; a document diverging from the code; a case of degradation the product did not name. One thing is welcome above all: a fact with a file-and-line reference. See CONTRIBUTING.md; questions, ideas and measurements on your own corpus go to Discussions. Participation is covered by the Code of Conduct.

The project is developed for concrete tasks, so architecture proposals are discussed more readily than large patches without a prior conversation. Security problems are reported privately, never as a public issue — see SECURITY.md.

If this saved you a context window, a star helps the next agent find it.

License#

PolyForm Noncommercial License 1.0.0 — free for any noncommercial purpose: personal projects, study, research, experiment and testing, and use by charitable, educational, public-research, public-safety, health and environmental organizations. Commercial use needs a separate license from the copyright holder, who keeps every right not expressly granted. CHANGELOG.md records the transition from MIT on 2026-10-15.

GitHub's licence badge for this repository reads «Other»: PolyForm is not in the catalogue GitHub detects, so the badge cannot be trusted here. LICENSE and pyproject.toml (license = "PolyForm-Noncommercial-1.0.0") are the authoritative sources.

External dependencies keep their own licenses: tree-sitter (MIT), sqlite-vec (MIT/Apache-2.0), fastembed (Apache-2.0), PyYAML (MIT), tiktoken (MIT), ijson (BSD). Java and Joern, installed separately, are distributed under Apache-2.0 and are not part of the distribution.