RAG Rat

1# rag-rat
2 
3[![CI](https://github.com/cq27-dev/rag-rat/actions/workflows/ci.yml/badge.svg)](https://github.com/cq27-dev/rag-rat/actions/workflows/ci.yml)
4[![codecov](https://codecov.io/gh/cq27-dev/rag-rat/branch/main/graph/badge.svg)](https://codecov.io/gh/cq27-dev/rag-rat)
5[![crates.io](https://img.shields.io/crates/v/rag-rat.svg)](https://crates.io/crates/rag-rat)
6[![benchmarks](https://img.shields.io/badge/benchmarks-bencher-orange)](https://bencher.dev/perf/rag-rat/plots)
7[![site](https://img.shields.io/badge/site-rag--rat.cq27.dev-2563eb)](https://rag-rat.cq27.dev)
8 
9**What a repository knows about itself.** `rag-rat` is a local repo-intelligence index and MCP server
10for coding agents. It keeps source files read-only, writes only its own SQLite database, and answers
11with provenance on every result — current source, the code graph, git/GitHub history, and durable,
12source-anchored repo memories that persist across sessions and agents.
13 
14Every coding harness already has `grep` and file reads. rag-rat adds the layer they do not provide:
15source-anchored *rationale*. It connects the code an agent is about to touch to its callers, callees,
16tests, git/GitHub history, prior decisions, invariants, risks, and duplicate-code signals — and
17labels every result with confidence and coverage, so an agent can judge it instead of trusting it.
18 
19```mermaid
20sequenceDiagram
21    participant Repo as Repository
22    participant Engine as rag-rat engine
23    participant Agent as Coding agent
24 
25    Repo->>Engine: Source · git/GitHub · repo memories
26    Engine->>Engine: Index → graph → (opt) SCIP oracle → reconcile
27    Agent->>Engine: where / why / who-calls / impact?
28    Engine-->>Agent: source + call paths + papertrail + memories (with provenance)
29    Agent->>Engine: record a finding
30    Engine->>Repo: persist a source-anchored repo memory
31```
32 
33## Why
34 
35- **Provenance, not guesses.** Every result carries a confidence label, coverage warnings, and the
36  raw evidence — so a partial index or an ambiguous edge reads as exactly that.
37- **Repo memories.** Typed, source-anchored notes (`Invariant`, `Decision`, `Risk`, …) that survive
38  refactors and surface automatically during future queries — the signal grep can't give you. They
39  are *not* assistant memory: they are versioned, local, source-anchored facts about **this**
40  repository that any future agent retrieves with evidence.
41- **A real code graph.** tree-sitter callers/callees/imports across Rust, TypeScript/TSX, Kotlin,
42  C/C++, Python, and Swift — with an optional [compiler-grade SCIP oracle](docs/oracle.md) for
43  configured toolchains that upgrades edges to `Compiler` confidence and ranks the load-bearing
44  symbols.
45- **History as evidence.** Git history, lazy chunk blame, and cached GitHub issue/PR/review
46  rationale, all queryable.
47- **Rides your existing grep.** A [grep-augmentation hook](docs/grep-augmentation.md) injects the
48  memories and symbols behind whatever you just searched for.
49- **Flags clones as you write them.** A PreToolUse hook on Write/Edit/MultiEdit fingerprints the
50  functions you're writing and warns when they're exact or near-duplicates of code already in the
51  repo — so an agent reuses instead of re-implementing. Read-only, and a silent no-op when the index
52  isn't ready, so it never blocks a write.
53 
54## Quickstart
55 
56For Claude Code, Codex, and opencode, install the plugin. It registers the MCP server, adds the
57hooks, and installs a version-matched `rag-rat` binary on first run (the Claude Code and Codex
58bundles also add the skills; on opencode add them with `npx @rag-rat/skills`):
59 
60```bash
61# Claude Code
62claude plugin marketplace add cq27-dev/rag-rat
63claude plugin install rag-rat@rag-rat
64 
65# Codex
66codex plugin marketplace add cq27-dev/rag-rat
67codex plugin add rag-rat@rag-rat
68 
69# opencode (add -g for a global install)
70opencode plugin @rag-rat/plugin-opencode
71```
72 
73After installing, approve the plugin so its tools and hooks run (opencode loads plugins without an
74approval step — nothing to do there):
75 
76- **Claude Code** asks before each rag-rat MCP tool the first time it runs — choose "Yes, don't ask
77  again," or pre-allow them in `~/.claude/settings.json` with
78  `"permissions": { "allow": ["mcp__rag-rat__*"] }`.
79- **Codex** shows a **"Hooks need review"** prompt on the first `codex` session started *inside the
80  repo* (the plugin ships grep-augmentation, clone-check, and session-digest hooks that run outside
81  the sandbox). Choose **"Trust all and continue"** to enable them. For unattended commands such as
82  `codex review`, also allow the plugin's MCP tools in `~/.codex/config.toml` so the run cannot stall
83  on a per-tool approval prompt:
84 
85  ```toml
86  [plugins."rag-rat@rag-rat".mcp_servers.rag-rat]
87  default_tools_approval_mode = "approve"
88  ```
89 
90  This trusts every current and future MCP tool exposed by the installed rag-rat plugin. Only enable
91  it when you trust the plugin's source and installation origin, then restart Codex.
92 
93Then open the repository and ask:
94 
95> Set up rag-rat in this repo.
96 
97The `init-rag-rat` skill scans the repo, explains the material choices, previews `rag-rat.toml`,
98writes and indexes only after confirmation, and offers to set up the git hooks that keep the index
99fresh. The MCP server starts dormant in an unconfigured repo; when setup finishes, reconnect it so it
100restarts fully active against the new index.
101 
102Then put it to work — the loop rag-rat is built for is in [Try it](#try-it).
103 
104<details>
105<summary><strong>Manual installation and other agents</strong></summary>
106 
107Use this path for the standalone CLI, agents without plugin support, or building from source.
108 
109### Install the CLI
110 
111The prebuilt package needs no Rust toolchain and supports Apple Silicon macOS, glibc ≥2.38 Linux
112(x86-64 and arm64), Windows x64, and Android/Termux arm64:
113 
114```bash
115npm install -g @rag-rat/bin
116# or run it without installing:
117npx @rag-rat/bin --help
118```
119 
120`@rag-rat/bin` fetches the full binary from the matching GitHub release. FastEmbed's ONNX Runtime is
121statically linked.
122 
123To build from source instead:
124 
125```bash
126cargo install rag-rat
127# or from a checkout:
128cargo install --path crates/rag-rat-cli --bin rag-rat
129```
130 
131The default source build needs glibc ≥2.38 and is unavailable for Intel macOS and musl/Alpine. On
132those platforms, including Ubuntu 22.04, use the pure-Rust embedder:
133 
134```bash
135cargo install rag-rat --no-default-features --features model2vec
136```
137 
138`--no-default-features` alone produces a smaller hash-only build without real embeddings. SQLite is
139bundled; see [Platform support](#platform-support) for toolchain details.
140 
141### Initialize the repository
142 
143```bash
144cd /path/to/your/repo
145rag-rat init
146```
147 
148`init` scans the repo, guides language and embedding choices, writes `rag-rat.toml`, and builds the
149initial index. Use `rag-rat init --dry-run` to preview without writing, or `--yes` for
150non-interactive defaults. Configuration reference: [`docs/config.md`](docs/config.md).
151 
152### Add skills and connect MCP
153 
154Install the skills for Claude Code, Codex, Cursor, and 70+ other detected agents:
155 
156```bash
157npx @rag-rat/skills
158```
159 
160That installs `using-rag-rat`, `dream-review`, `init-rag-rat`, and
161`configure-rag-rat-dream`. See [`skills/README.md`](skills/README.md) for per-agent flags and
162`update`, `list`, and `remove`.
163 
164The MCP server uses STDIO: the client launches `rag-rat mcp` from the repository so it discovers the
165correct `rag-rat.toml` and repository scope in the consolidated machine-global store.
166 
167```bash
168claude mcp add --scope project rag-rat -- rag-rat mcp
169codex  mcp add rag-rat -- rag-rat mcp
170```
171 
172Or add the equivalent project configuration:
173 
174```json
175{
176  "mcpServers": {
177    "rag-rat": { "command": "rag-rat", "args": ["mcp"] }
178  }
179}
180```
181 
182`rag-rat init` prints the registration command but does not register the server itself. Pass
183`rag-rat mcp --json` if the client must parse JSON; tool text defaults to [TOON](#output). Full tool
184schemas: [`docs/mcp-tools.md`](docs/mcp-tools.md).
185 
186<details>
187<summary>Claude Code tool permissions</summary>
188 
189Claude Code asks once before each rag-rat MCP tool first runs. Choose "Yes, don't ask again," or
190allow the tool namespace in `~/.claude/settings.json`:
191 
192```json
193{ "permissions": { "allow": ["mcp__rag-rat__*"] } }
194```
195</details>
196 
197> **Do not pin a global server to one repository's config.** A user-scoped server with
198> `--config /some/repo/rag-rat.toml` serves that repository everywhere. Register MCP per project and
199> let the process discover the config from its working directory.
200 
201</details>
202 
203## Try it
204 
205Once the repo is indexed, the code graph, symbols, git history, semantic search, and clone
206detection are ready — these answer on the first query. Repo memories start **empty**: they accrue as
207agents record findings with `memory_create` and then surface automatically in later answers.
208(Tracker issue/PR rationale needs a `rag-rat papertrail sync`.)
209 
210Ask your MCP client:
211 
212- "Run `impact_surface` on the function I'm about to edit — its callers, callees, tests, and recent
213  commits."
214- "Where is config reload handled?" — hybrid `semantic_search` over source and docs.
215- "What are the most load-bearing symbols in this repo?" — `important_symbols`.
216- "Does this helper duplicate anything already in the codebase?" — `find_clones` (and the write-time
217  hook warns as you write it).
218- "Record an invariant on `parse_config`: reload must not allocate after the scheduler starts." —
219  `memory_create` writes your first repo memory; it then rides along in future `impact_surface` /
220  `symbol_lookup` results.
221 
222Or from the CLI:
223 
224```bash
225rag-rat query "where is config reload handled?"
226rag-rat important-symbols --limit 20
227rag-rat brief --mode spine
228rag-rat clusters --limit 10
229```
230 
231## The agent loop
232 
233The point isn't the tool catalog — it's the loop an agent runs *around* an edit, so it changes code
234with the callers, tests, rationale, and prior art in front of it instead of guessing:
235 
2361. **Before editing a symbol, ask `impact_surface`.** One call returns the current source anchor,
237   callers and callees, related tests, git/GitHub rationale, the repo memories bound to that
238   symbol / path / call-path, and confidence + coverage warnings.
2392. **Read the blast radius, then edit.** The invariant a previous agent recorded, the caller three
240   hops away, the test that pins the behavior — all surfaced before the change, not discovered after.
2413. **The clone hook catches duplication at write time.** If the new function reimplements code that
242   already exists, the Write/Edit hook says so, with the existing symbol to reuse.
2434. **Record what you learned.** When the edit reveals a durable invariant, decision, or footgun,
244   `memory_create` stores it as a source-anchored repo memory — so the next agent (or the next
245   session) gets it in one call instead of re-deriving it.
246 
247A trimmed `impact_surface` answer (TOON — the default output; abbreviated here) — every field is
248evidence, not prose:
249 
250```text
251query:
252  ref: "crates/config/src/config.rs::parse_config"
253  resolution: syntactic
254direct_semantic_callers[12]:
255  - from_symbol: "crates/runtime/src/boot.rs::start"
256    edge_kind: calls_name
257    confidence: syntactic
258    callsite:
259      path: "crates/runtime/src/boot.rs"
260      line: 88
261    importance:
262      label: local structural load
263      score: 6.8
264      bucket: high
265tests_touching_symbol_path[4]:
266  - path: "crates/config/src/config_tests.rs"
267    reason: test_mentions_symbol_or_path
268recent_commits_touching_symbol_path[1]:
269  - evidence[1]: "a1b2c3d touched crates/config/src/config.rs: fix reload race during startup (#141)"
270repo_memories:
271  direct[2]:
272    - kind: Invariant
273      title: "Config reload must not allocate after the scheduler starts"
274      confidence: high
275      anchor_status: current
276      binding_kind: symbol
277    - kind: Decision
278      title: "TOML over JSON5 for the config surface (#88)"
279      anchor_status: current
280      binding_kind: path
281completeness_and_caveats:
282  exact_graph_callers: 12
283  memory_status:
284    active: 2
285    stale: 0
286  caveats[1]: "Graph evidence is tree-sitter/syntactic, not compiler-grade name resolution."
287```
288 
289And the write-time clone warning an agent sees before it duplicates logic — verbatim hook output:
290 
291```text
292▶ rag-rat clone check — code you're writing duplicates existing functions:
293  • `normalize_path_for_lookup` (line 42) is ~91% similar to crates/index/src/paths.rs::canonicalize_lookup_path
294Prefer reusing the existing function(s) over duplicating — impact_surface / symbol_lookup to inspect them.
295```
296 
297## The tools
298 
299rag-rat's **MCP tools** — the full catalog with JSON schemas lives in
300[`docs/mcp-tools.md`](docs/mcp-tools.md). The ones you'll reach for most:
301 
302- **`impact_surface`** — the coding preflight from the loop above: callers, callees, tests, git
303  history, GitHub papertrail, and the repo memories crossing a symbol, in one call. Memories default
304  to compact, scannable headers; pass `full_memories: true` for full bodies + bindings.
305- **`semantic_search`** — hybrid BM25 + vector recall over source and docs, validated against current
306  source. Every hit reports `retrieval_mode`; `explain=true` breaks down the score.
307- **`symbol_lookup`** — exact/fuzzy symbol resolution; cfg/overload variants grouped as one logical
308  symbol.
309- **`find_callers` / `trace_callees`** — reverse/forward call-graph traversal (low-signal std/macro
310  noise filtered by default).
311- **`important_symbols`** — the load-bearing symbols by (SCIP-aware) PageRank, seeded from your
312  current diff by default; see [`docs/oracle.md`](docs/oracle.md).
313- **`find_clones`** — exact + near-miss duplicate functions ranked by refactor ROI (the candidate
314  graph is precomputed in the background, so it scales to large repos).
315- **`memory_create`** — record a source-anchored repo memory; **`dream`** surfaces the maintenance
316  worklist that keeps them honest ([below](#self-maintaining-memories)).
317 
318Beyond these: repo orientation (`repo_brief`, `repo_clusters`), git/GitHub rationale
319(`commit_search`, `git_history_for_*`, `papertrail_for_*`, `rationale_search`), the full memory
320graph (`memory_search`, `memory_edges`, `memory_rebind`, `memory_doctor`, …), graph-vs-compiler
321audit (`compare_graph_to_scip`), and index diagnostics (`index_status`, `llm_status`, `heal_index`)
322— all documented in [`docs/mcp-tools.md`](docs/mcp-tools.md).
323 
324## Repo memories
325 
326Repo memories are first-class local evidence — **not chat memory, not cloud personalization.** They
327are versioned, local, source-anchored facts about this repository. Each is typed
328(`Invariant`, `Decision`, `RejectedAlternative`, `Risk`, `BugPattern`, `PerformanceNote`, …) and
329**source-anchored**: bound to a logical symbol, concrete symbol, chunk, path+span, graph edge,
330call-path, commit, or GitHub ref. rag-rat tracks each anchor as `current`, `relocated`, `stale`,
331`gone`, or `unverified`, and surfaces matching memories through the `memory_*` tools and inline in
332`read_chunk`, `symbol_lookup`, `find_callers`, `trace_callees`, and `impact_surface`. They're how
333hard-won context reaches the *next* agent in one call instead of evaporating.
334 
335Memories are also a **typed graph**, not just a flat list: `memory_edge_add` / `memory_edges` connect
336them with relations (`depends_on`, `relates_to`, `supersedes`, `derived_from`, `tracks`) — a task DAG,
337a mind-map link between decisions, or a task that `tracks` a GitHub issue. Full tool list:
338[`docs/mcp-tools.md`](docs/mcp-tools.md#repo-memories).
339 
340## Self-maintaining memories
341 
342Memories rot: the code moves under them, an invariant gets superseded, a load-bearing function ships
343with no memory at all. **`dream`** is the maintenance loop that keeps the layer honest. It recomputes
344a ranked worklist of findings *about* the memories themselves — each with a stable id to review:
345 
346- **coverage gaps** — load-bearing symbols (by the same PageRank as `important_symbols`) that carry no
347  memory, so the next agent editing them gets nothing.
348- **stale references** — a memory citing a path or anchor that no longer resolves.
349 
350`dream` runs the deterministic findings on every call. Two opt-in **model passes** go deeper, running
351a small model on an ephemeral remote GPU (`[llm.dream.remote]`) only when work is pending:
352`rag-rat dream --verify` recomputes each memory's verdict against current source *reality* (has the
353code drifted from what the memory claims?), and `--compact` rewrites a verbose memory to a tighter
354summary. Findings those passes persist surface back through `dream`.
355 
356Nothing is deleted automatically. A human — or a strong agent over MCP — burns the worklist down with
357**`dream_review`** (`accept` a real gap, `dismiss` noise, `reset` a prior verdict), and verdicts
358survive future runs so settled findings don't come back. It's the same surface as the CLI
359`rag-rat dream` / `rag-rat dream <id> --accept|--dismiss|--reset`.
360 
361## Compiler-grade resolution & ranking
362 
363The graph is heuristic by default. The opt-in **SCIP oracle** (`rag-rat oracle run`) upgrades edges
364to a `Compiler` tier from a real language tool, recovers calls tree-sitter missed, flags external
365edges, and makes `important_symbols` surface the genuine god-modules. For C/C++ the `scip-clang`
366oracle distinguishes declarations from definitions and sharpens call/type edges in macro-heavy or
367multi-target code — the difference between usable and noisy graphs on firmware, kernels, drivers, and
368SDKs. Turn on `[oracle] auto_run` and the MCP server keeps it fresh on its own (throttled,
369watcher-safe). Full details: [`docs/oracle.md`](docs/oracle.md).
370 
371## Freshness
372 
373`rag-rat mcp` runs a background file watcher (on by default; `[watch] enabled = false` or
374`RAG_RAT_NO_WATCH=1` to disable), so graph/symbol queries reflect uncommitted edits without a commit.
375Indexed rows are git-context-aware: clean files are stored by `commit_sha`, dirty/untracked files in
376a worktree overlay, so one database reuses rows across branch switches while reflecting local edits.
377Optional git hooks (`rag-rat hooks install`) keep the index current on checkout/merge/rewrite/commit.
378`read_chunk` and search validate hits against current source and heal stale entries before returning.
379 
380One watcher per worktree and one writer at a time are enforced with file locks (unreliable on
381NFS / WSL2 `/mnt` mounts).
382 
383By default every repo's index and memories live in **one consolidated database per machine**
384(`$XDG_DATA_HOME/rag-rat/rag-rat.sqlite`; override with `RAG_RAT_DATA_DIR`), so a deleted checkout or
385`git clean -fdx` no longer loses your authored memories. Set an explicit `[index] database` to keep a
386repo on its own file (deprecated), and run `rag-rat consolidate` to import a pre-existing
387`.rag-rat/index.sqlite` into the global store — see [docs/config/database.md](docs/config/database.md).
388 
389## <a id="output"></a>Output format
390 
391The CLI and MCP results default to **TOON** (Token-Oriented Object Notation) — a token-efficient
392encoding that renders uniform rows as a dense `[N]{cols}:` table (~30% smaller than compact JSON on
393those payloads, never larger in practice). Pass `--json` (CLI, either position) or launch
394`rag-rat mcp --json` (MCP) when a JSON parser must read the output.
395 
396## Embedding backends
397 
398The default local embedder (FastEmbed) needs no setup, but a large repo or a stronger model is worth
399offloading. rag-rat speaks the **OpenAI-compatible `/v1/embeddings` API**, so a `[llm.embedding.remote]`
400block can serve embeddings from **Ollama, vLLM, or michaelfeil/infinity** — one client, one place to
401audit and secure. Two modes:
402 
403- **Connect** to a server you already run (set `endpoint`).
404- **Ephemeral** — let the bundled cookbook provision a GPU worker (**Modal / RunPod**) just for the
405  backfill and tear it down afterward (set `cookbook`); pick the backend and GPU class in config.
406 
407The init flow warns when a **short-context model would truncate long code chunks** and steers you to a
408long-context code embedder, and rag-rat **auto-tunes the client concurrency** against the chosen
409backend so the sweep finds its throughput knee. Setup and every knob: [`docs/config.md`](docs/config.md).
410 
411## Retrieval quality
412 
413Search quality is measurable, not guesswork. rag-rat ships a **commit-replay evaluation harness**
414(`rag-rat eval --replay`): each recent commit becomes a case — its message is the query, the files it
415touched are the gold set — and search is scored on how well it recovers them. It reports **recall@3**
416(did the right chunk land in the first three reads?), recall@10, and MRR@10, and CI tracks the trend
417on [Bencher](https://bencher.dev/perf/rag-rat/plots) on `main` so a regression is caught before it
418ships.
419 
420Reach for it when comparing embedding models, changing chunking, enabling int8 vector storage
421(smaller on disk), or tuning a remote backend — you can prove the change didn't cost recall instead
422of hoping. (`rag-rat eval` requires a `--features eval` build; it is absent from the released binary.)
423 
424## Benchmarks
425 
426The headline workload is indexing the whole Linux kernel (v7.0, ~63k C/H files, 9.14M graph edges).
427Full numbers — wall-clock, throughput, peak RSS, on-disk size, unresolved-edge taxonomy — are in
428[`docs/benchmarks.md`](docs/benchmarks.md). Performance is tracked per-push and gated per-PR; the live
429history is at [bencher.dev/perf/rag-rat/plots](https://bencher.dev/perf/rag-rat/plots) (wiring:
430[`docs/bencher.md`](docs/bencher.md)).
431 
432## Security
433 
434The MCP server exposes read-only source tools. It never executes shell commands or writes your source
435files. It writes only the configured SQLite index — during indexing, migration, maintenance,
436reconciliation, repo-memory operations, and automatic stale-index healing. GitHub sync is explicit
437and uses `gh api`; normal query tools read only the local cache.
438 
439### Local vs remote embedding
440 
441With the **default local embedder, nothing leaves the machine** — indexing and querying are entirely
442local. Configuring a `[llm.embedding.remote]` backend is what sends text off the box, in two places:
443the **chunk text** selected at index time, and the **query text** of each semantic search (a search
444embeds your query to compare it against the indexed vectors). A CONNECT backend embeds both against
445the configured `endpoint`; an ephemeral backend embeds queries against the local `query_endpoint`.
446 
447What the endpoint *is* decides how much that matters:
448 
449- **Your own server** (self-hosted Ollama / vLLM / infinity) — the text stays in infrastructure you
450  control.
451- **Ephemeral Modal / RunPod workers** (the cookbook path) are ephemeral *compute* providers running
452  *your* open-source embedder, not data services that train on inputs. Both are SOC 2 Type II, encrypt
453  in transit and at rest, isolate tenants, and tear the box and its storage down after the backfill —
454  a data-processor relationship, reasonable for proprietary code the same way a cloud VM is.
455- **A third-party embedding API** you don't control is the one to actually read the terms on
456  (retention, training on inputs).
457 
458Sensible hygiene regardless of backend: exclude secrets, generated files, and vendor trees from the
459indexed targets so they're never chunked or embedded, and keep secrets out of query text. Details:
460[`docs/config.md`](docs/config.md).
461 
462## Platform support
463 
464rag-rat builds and tests on Linux, macOS, and Windows. Linux is covered on every PR and on every
465push to main; macOS and Windows are exercised on release, so `cargo install rag-rat` builds and
466links on all three. Android (aarch64, bionic) is also a release target — a prebuilt binary is
467attached to each release and published to `@rag-rat/bin`, so `npx @rag-rat/bin` works on Termux; see
468[Quickstart](#quickstart).
469SQLite is bundled (compiled from source via `rusqlite`), so there's no system-library prerequisite,
470but each platform needs a C toolchain: Linux ships one; on macOS install the Xcode Command Line
471Tools (`xcode-select --install`); on Windows install the Visual Studio Build Tools with the C++
472workload (MSVC). Requires **Rust 1.95+** (the bundled SQLite build uses the `cfg_select!` macro,
473stabilized in 1.95).
474 
475A few maintenance conveniences are Unix- or Linux-only by design and degrade quietly elsewhere — no
476feature of the index, query, or MCP surface is affected:
477 
478- **Hot-upgrade of a running MCP server** (the `SIGUSR1` in-place re-exec) is Unix-only. On Windows,
479  restart `rag-rat mcp` to pick up a new binary.
480- **Fleet auto-upgrade** (signalling other running servers when a new binary lands) is Linux-only —
481  it walks `/proc` — and is a no-op elsewhere.
482- **The grep-augmentation hook** uses a warm Unix-socket listener (with per-session dedupe) on
483  Linux and macOS; on Windows it falls back to a per-call read-only query straight against the
484  index, which works the same but without cross-call dedupe.
485 
486## Commands
487 
488```bash
489rag-rat init                       # guided first-run setup
490rag-rat index [--changed|--discover|--full]
491rag-rat doctor
492rag-rat query "semantic recall"    # add --json for JSON
493rag-rat important-symbols --limit 20
494rag-rat brief --mode spine|churn|god_modules|refactor_candidates
495rag-rat clusters --limit 10
496rag-rat oracle run | status        # compiler-grade resolution (docs/oracle.md)
497rag-rat models list | install <model>
498rag-rat reconcile --changed-first --max-seconds 60 --batch-size 64
499rag-rat papertrail sync            # add --full to force a historical healing pass
500rag-rat memory list | show <id> | doctor | rebind <id>    # inspect / re-anchor repo memories
501rag-rat dream [--verify|--compact] [<id> --accept|--dismiss|--reset]   # memory-maintenance worklist
502rag-rat consolidate                # import a legacy per-repo index into the global store
503rag-rat hooks install              # git maintenance hooks
504rag-rat gc                         # prune rows for dead git contexts
505rag-rat eval [--json|--update-baseline]   # CI search-quality gate; requires a `--features eval` build (absent from the released binary)
506rag-rat mcp                        # start the STDIO server
507```
508 
509## Releasing & license
510 
511Releases are automated by [release-plz](https://release-plz.dev) (the three crates ship in lockstep;
512see [`docs/releasing.md`](docs/releasing.md)). `rag-rat` is MIT-licensed — see [LICENSE](LICENSE).
513 
514## Prior art
515 
516rag-rat's clone-detection design is inspired by SourcererCC's scalable token-bag candidate
517generation, NiCad's normalized near-miss clone-detection framing, GumTree's move-aware AST
518differencing, and anti-unification / least-general generalization for template extraction. Planned
519fragment-level mining and copy-paste bug heuristics are inspired by CP-Miner.
520