# Rag Rat > Local repo-intelligence MCP for coding agents: indexes source, symbols, call graphs, git/GitHub history, and source-bound repo memories into local database. - **Type:** MCP server - **Install:** `agentstack add mcp-cq27-dev-rag-rat` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [cq27-dev](https://agentstack.voostack.com/s/cq27-dev) - **Installs:** 0 - **Category:** [Databases](https://agentstack.voostack.com/c/databases) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [cq27-dev](https://github.com/cq27-dev) - **Source:** https://github.com/cq27-dev/rag-rat ## Install ```sh agentstack add mcp-cq27-dev-rag-rat ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # rag-rat [](https://github.com/cq27-dev/rag-rat/actions/workflows/ci.yml) [](https://codecov.io/gh/cq27-dev/rag-rat) [](https://crates.io/crates/rag-rat) [](https://bencher.dev/perf/rag-rat/plots) **What a repository knows about itself.** `rag-rat` is a local repo-intelligence index and MCP server for coding agents. It keeps source files read-only, writes only its own SQLite database, and answers with provenance on every result — current source, the code graph, git/GitHub history, and durable, source-anchored repo memories that persist across sessions and agents. Every coding harness already has `grep` and file reads. rag-rat adds the layer they do not provide: source-anchored *rationale*. It connects the code an agent is about to touch to its callers, callees, tests, git/GitHub history, prior decisions, invariants, risks, and duplicate-code signals — and labels every result with confidence and coverage, so an agent can judge it instead of trusting it. ```mermaid sequenceDiagram participant Repo as Repository participant Engine as rag-rat engine participant Agent as Coding agent Repo->>Engine: Source · git/GitHub · repo memories Engine->>Engine: Index → graph → (opt) SCIP oracle → reconcile Agent->>Engine: where / why / who-calls / impact? Engine-->>Agent: source + call paths + papertrail + memories (with provenance) Agent->>Engine: record a finding Engine->>Repo: persist a source-anchored repo memory ``` ## Why - **Provenance, not guesses.** Every result carries a confidence label, coverage warnings, and the raw evidence — so a partial index or an ambiguous edge reads as exactly that. - **Repo memories.** Typed, source-anchored notes (`Invariant`, `Decision`, `Risk`, …) that survive refactors and surface automatically during future queries — the signal grep can't give you. They are *not* assistant memory: they are versioned, local, source-anchored facts about **this** repository that any future agent retrieves with evidence. - **A real code graph.** tree-sitter callers/callees/imports across Rust, TypeScript/TSX, Kotlin, C/C++, Python, and Swift — with an optional [compiler-grade SCIP oracle](docs/oracle.md) for configured toolchains that upgrades edges to `Compiler` confidence and ranks the load-bearing symbols. - **History as evidence.** Git history, lazy chunk blame, and cached GitHub issue/PR/review rationale, all queryable. - **Rides your existing grep.** A [PreToolUse hook](docs/grep-augmentation.md) injects the memories and symbols behind whatever you just searched for. - **Flags clones as you write them.** A PreToolUse hook on Write/Edit/MultiEdit fingerprints the functions you're writing and warns when they're exact or near-duplicates of code already in the repo — so an agent reuses instead of re-implementing. Read-only, and a silent no-op when the index isn't ready, so it never blocks a write. ## Quickstart For Claude Code and Codex, install the plugin. It registers the MCP server, adds the skills and hooks, and installs a version-matched `rag-rat` binary on first run: ```bash # Claude Code claude plugin marketplace add cq27-dev/rag-rat claude plugin install rag-rat@rag-rat # Codex codex plugin marketplace add cq27-dev/rag-rat codex plugin add rag-rat@rag-rat ``` After installing, approve the plugin so its tools and hooks run: - **Claude Code** asks before each rag-rat MCP tool the first time it runs — choose "Yes, don't ask again," or pre-allow them in `~/.claude/settings.json` with `"permissions": { "allow": ["mcp__rag-rat__*"] }`. - **Codex** shows a **"Hooks need review"** prompt on the first `codex` session started *inside the repo* (the plugin ships grep-augmentation, clone-check, and session-digest hooks that run outside the sandbox). Choose **"Trust all and continue"** to enable them. For unattended commands such as `codex review`, also allow the plugin's MCP tools in `~/.codex/config.toml` so the run cannot stall on a per-tool approval prompt: ```toml [plugins."rag-rat@rag-rat".mcp_servers.rag-rat] default_tools_approval_mode = "approve" ``` This trusts every current and future MCP tool exposed by the installed rag-rat plugin. Only enable it when you trust the plugin's source and installation origin, then restart Codex. Then open the repository and ask: > Set up rag-rat in this repo. The `init-rag-rat` skill scans the repo, explains the material choices, previews `rag-rat.toml`, writes and indexes only after confirmation, and offers to set up the git hooks that keep the index fresh. The MCP server starts dormant in an unconfigured repo; when setup finishes, reconnect it so it restarts fully active against the new index. Then put it to work — the loop rag-rat is built for is in [Try it](#try-it). Manual installation and other agents Use this path for the standalone CLI, agents without plugin support, or building from source. ### Install the CLI The prebuilt package needs no Rust toolchain and supports Apple Silicon macOS, glibc ≥2.38 Linux (x86-64 and arm64), Windows x64, and Android/Termux arm64: ```bash npm install -g @rag-rat/bin # or run it without installing: npx @rag-rat/bin --help ``` `@rag-rat/bin` fetches the full binary from the matching GitHub release. FastEmbed's ONNX Runtime is statically linked. To build from source instead: ```bash cargo install rag-rat # or from a checkout: cargo install --path crates/rag-rat-cli --bin rag-rat ``` The default source build needs glibc ≥2.38 and is unavailable for Intel macOS and musl/Alpine. On those platforms, including Ubuntu 22.04, use the pure-Rust embedder: ```bash cargo install rag-rat --no-default-features --features model2vec ``` `--no-default-features` alone produces a smaller hash-only build without real embeddings. SQLite is bundled; see [Platform support](#platform-support) for toolchain details. ### Initialize the repository ```bash cd /path/to/your/repo rag-rat init ``` `init` scans the repo, guides language and embedding choices, writes `rag-rat.toml`, and builds the initial index. Use `rag-rat init --dry-run` to preview without writing, or `--yes` for non-interactive defaults. Configuration reference: [`docs/config.md`](docs/config.md). ### Add skills and connect MCP Install the skills for Claude Code, Codex, Cursor, and 70+ other detected agents: ```bash npx @rag-rat/skills ``` That installs `using-rag-rat`, `dream-review`, `init-rag-rat`, and `configure-rag-rat-dream`. See [`skills/README.md`](skills/README.md) for per-agent flags and `update`, `list`, and `remove`. The MCP server uses STDIO: the client launches `rag-rat mcp` from the repository so it discovers the correct `rag-rat.toml` and repository scope in the consolidated machine-global store. ```bash claude mcp add --scope project rag-rat -- rag-rat mcp codex mcp add rag-rat -- rag-rat mcp ``` Or add the equivalent project configuration: ```json { "mcpServers": { "rag-rat": { "command": "rag-rat", "args": ["mcp"] } } } ``` `rag-rat init` prints the registration command but does not register the server itself. Pass `rag-rat mcp --json` if the client must parse JSON; tool text defaults to [TOON](#output). Full tool schemas: [`docs/mcp-tools.md`](docs/mcp-tools.md). Claude Code tool permissions Claude Code asks once before each rag-rat MCP tool first runs. Choose "Yes, don't ask again," or allow the tool namespace in `~/.claude/settings.json`: ```json { "permissions": { "allow": ["mcp__rag-rat__*"] } } ``` > **Do not pin a global server to one repository's config.** A user-scoped server with > `--config /some/repo/rag-rat.toml` serves that repository everywhere. Register MCP per project and > let the process discover the config from its working directory. ## Try it Once the repo is indexed, the code graph, symbols, git history, semantic search, and clone detection are ready — these answer on the first query. Repo memories start **empty**: they accrue as agents record findings with `memory_create` and then surface automatically in later answers. (Tracker issue/PR rationale needs a `rag-rat papertrail sync`.) Ask your MCP client: - "Run `impact_surface` on the function I'm about to edit — its callers, callees, tests, and recent commits." - "Where is config reload handled?" — hybrid `semantic_search` over source and docs. - "What are the most load-bearing symbols in this repo?" — `important_symbols`. - "Does this helper duplicate anything already in the codebase?" — `find_clones` (and the write-time hook warns as you write it). - "Record an invariant on `parse_config`: reload must not allocate after the scheduler starts." — `memory_create` writes your first repo memory; it then rides along in future `impact_surface` / `symbol_lookup` results. Or from the CLI: ```bash rag-rat query "where is config reload handled?" rag-rat important-symbols --limit 20 rag-rat brief --mode spine rag-rat clusters --limit 10 ``` ## The agent loop The point isn't the tool catalog — it's the loop an agent runs *around* an edit, so it changes code with the callers, tests, rationale, and prior art in front of it instead of guessing: 1. **Before editing a symbol, ask `impact_surface`.** One call returns the current source anchor, callers and callees, related tests, git/GitHub rationale, the repo memories bound to that symbol / path / call-path, and confidence + coverage warnings. 2. **Read the blast radius, then edit.** The invariant a previous agent recorded, the caller three hops away, the test that pins the behavior — all surfaced before the change, not discovered after. 3. **The clone hook catches duplication at write time.** If the new function reimplements code that already exists, the Write/Edit hook says so, with the existing symbol to reuse. 4. **Record what you learned.** When the edit reveals a durable invariant, decision, or footgun, `memory_create` stores it as a source-anchored repo memory — so the next agent (or the next session) gets it in one call instead of re-deriving it. A trimmed `impact_surface` answer (TOON — the default output; abbreviated here) — every field is evidence, not prose: ```text query: ref: "crates/config/src/config.rs::parse_config" resolution: syntactic direct_semantic_callers[12]: - from_symbol: "crates/runtime/src/boot.rs::start" edge_kind: calls_name confidence: syntactic callsite: path: "crates/runtime/src/boot.rs" line: 88 importance: label: local structural load score: 6.8 bucket: high tests_touching_symbol_path[4]: - path: "crates/config/src/config_tests.rs" reason: test_mentions_symbol_or_path recent_commits_touching_symbol_path[1]: - evidence[1]: "a1b2c3d touched crates/config/src/config.rs: fix reload race during startup (#141)" repo_memories: direct[2]: - kind: Invariant title: "Config reload must not allocate after the scheduler starts" confidence: high anchor_status: current binding_kind: symbol - kind: Decision title: "TOML over JSON5 for the config surface (#88)" anchor_status: current binding_kind: path completeness_and_caveats: exact_graph_callers: 12 memory_status: active: 2 stale: 0 caveats[1]: "Graph evidence is tree-sitter/syntactic, not compiler-grade name resolution." ``` And the write-time clone warning an agent sees before it duplicates logic — verbatim hook output: ```text ▶ rag-rat clone check — code you're writing duplicates existing functions: • `normalize_path_for_lookup` (line 42) is ~91% similar to crates/index/src/paths.rs::canonicalize_lookup_path Prefer reusing the existing function(s) over duplicating — impact_surface / symbol_lookup to inspect them. ``` ## The tools rag-rat's **MCP tools** — the full catalog with JSON schemas lives in [`docs/mcp-tools.md`](docs/mcp-tools.md). The ones you'll reach for most: - **`impact_surface`** — the coding preflight from the loop above: callers, callees, tests, git history, GitHub papertrail, and the repo memories crossing a symbol, in one call. Memories default to compact, scannable headers; pass `full_memories: true` for full bodies + bindings. - **`semantic_search`** — hybrid BM25 + vector recall over source and docs, validated against current source. Every hit reports `retrieval_mode`; `explain=true` breaks down the score. - **`symbol_lookup`** — exact/fuzzy symbol resolution; cfg/overload variants grouped as one logical symbol. - **`find_callers` / `trace_callees`** — reverse/forward call-graph traversal (low-signal std/macro noise filtered by default). - **`important_symbols`** — the load-bearing symbols by (SCIP-aware) PageRank, seeded from your current diff by default; see [`docs/oracle.md`](docs/oracle.md). - **`find_clones`** — exact + near-miss duplicate functions ranked by refactor ROI (the candidate graph is precomputed in the background, so it scales to large repos). - **`memory_create`** — record a source-anchored repo memory; **`dream`** surfaces the maintenance worklist that keeps them honest ([below](#self-maintaining-memories)). Beyond these: repo orientation (`repo_brief`, `repo_clusters`), git/GitHub rationale (`commit_search`, `git_history_for_*`, `papertrail_for_*`, `rationale_search`), the full memory graph (`memory_search`, `memory_edges`, `memory_rebind`, `memory_doctor`, …), graph-vs-compiler audit (`compare_graph_to_scip`), and index diagnostics (`index_status`, `llm_status`, `heal_index`) — all documented in [`docs/mcp-tools.md`](docs/mcp-tools.md). ## Repo memories Repo memories are first-class local evidence — **not chat memory, not cloud personalization.** They are versioned, local, source-anchored facts about this repository. Each is typed (`Invariant`, `Decision`, `RejectedAlternative`, `Risk`, `BugPattern`, `PerformanceNote`, …) and **source-anchored**: bound to a logical symbol, concrete symbol, chunk, path+span, graph edge, call-path, commit, or GitHub ref. rag-rat tracks each anchor as `current`, `relocated`, `stale`, `gone`, or `unverified`, and surfaces matching memories through the `memory_*` tools and inline in `read_chunk`, `symbol_lookup`, `find_callers`, `trace_callees`, and `impact_surface`. They're how hard-won context reaches the *next* agent in one call instead of evaporating. Memories are also a **typed graph**, not just a flat list: `memory_edge_add` / `memory_edges` connect them with relations (`depends_on`, `relates_to`, `supersedes`, `derived_from`, `tracks`) — a task DAG, a mind-map link between decisions, or a task that `tracks` a GitHub issue. Full tool list: [`docs/mcp-tools.md`](docs/mcp-tools.md#repo-memories). ## Self-maintaining memories Memories rot: the code moves under them, an invariant gets superseded, a load-bearing function ships with no memory at all. **`dream`** is the maintenance loop that keeps the layer honest. It recomputes a ranked worklist of findings *about* the memories themselves — each with a stable id to review: - **coverage gaps** — load-bearing symbols (by the same PageRank as `important_symbols`) that carry no memory, so the next agent editing them gets nothing. - **stale references** — a memory citing a path or anchor that no longer resolves. `dream` runs the deterministic findings on every call. Two opt-in **model passes** go deeper, running a small model on an ephemeral remote GPU (`[llm.dream.remote]`) only when work is pending: `rag-rat dream --verify` recomputes each memory's verdict against current source *reality* (has the code drifted from what the memory claims?), and `--compact` rewrites a verbose memory to a tighter summary. Findings those passes persist surface back through `dream`. Nothing is deleted automatically. A human — or a strong agent over MCP — burns the worklist down with **`dream_review`** (`accept` a real gap, `dismiss` noise, `reset` a prior verdict), and verdicts survive future runs so settled findings don't come back. It's the sa … ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [cq27-dev](https://github.com/cq27-dev) - **Source:** [cq27-dev/rag-rat](https://github.com/cq27-dev/rag-rat) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-cq27-dev-rag-rat - Seller: https://agentstack.voostack.com/s/cq27-dev - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.