rag-rat 是一个本地代码库智能索引与 MCP 服务器，服务于编程智能体。它在源码文件只读的前提下工作，仅写入自身的 SQLite 数据库，并为每条返回结果附带出处（provenance）。其目标是把智能体即将修改的代码与它的调用者、被调用者、测试、git/GitHub 历史、既往决策、不变量、风险和重复代码信号连接起来，并为每条结果标注置信度与覆盖范围，供智能体自行判断。
用途
rag-rat 旨在补充编程智能体已有的 grep 和文件读取能力，提供它们所没有的一层：源码锚定的理由（source-anchored rationale）。它面向在编辑器或命令行中工作的编码智能体，帮助其在修改代码前了解影响范围与历史决策。
主要能力
- 出处而非猜测：每条结果带有置信度标签、覆盖警告与原始证据，部分索引或模糊的边会如实呈现。
- 仓库记忆（Repo memories）：类型化、源码锚定的笔记（如 Invariant、Decision、Risk 等），能在重构后存活，并在后续查询中自动浮现。它们是关于该仓库的、带版本、本地、源码锚定的事实，而非助手记忆。
- 真实代码图谱：通过 tree-sitter 支持 Rust、TypeScript/TSX、Kotlin、C/C++、Python、Swift 和 Go 的调用者/被调用者/导入关系；对已配置的工具链可选使用编译器级 SCIP oracle，将边升级为 Compiler 置信度，并对关键符号排序。
- 历史作为证据：git 历史、惰性 chunk blame，以及缓存的 GitHub issue/PR/review 理由，均可查询。
- 议题提炼（Issue distillation）：每个已关闭 issue 与已合并 PR 及其修复 diff 被提炼为类型化决策记录，包含根因、最终采用的方案（及被否决的替代方案）和结果，并锚定到相关符号上作为上下文浮现。
- 增强现有 grep：grep 增强钩子会把你刚搜索内容背后的记忆与符号注入结果中。
- 边写边检测克隆：针对 Write/Edit/MultiEdit 的 PreToolUse 钩子会对你正在编写的函数做指纹识别，当它们与仓库已有代码完全相同或近似重复时发出警告。该钩子只读，索引未就绪时静默无操作，不会阻塞写入。
使用方式
针对 Claude Code、Codex 和 opencode，可安装插件：它注册 MCP 服务器、添加钩子，并在首次运行时获取版本匹配的 rag-rat 二进制文件，启动时由 MCP 服务器暴露为 ~/.local/bin/rag-rat（Claude Code 和 Codex 的包还会添加 skills；opencode 可用 npx @rag-rat/skills 添加）。
安装后需批准插件以使其工具与钩子运行。Claude Code 会在每次 rag-rat MCP 工具首次运行时询问，可选择“Yes, don't ask again”，或在 ~/.claude/settings.json 中预允许。Codex 会在仓库内首次启动的会话中显示“Hooks need review”提示，选择“Trust all and continue”启用；对于无人值守命令（如 codex review），可在 ~/.codex/config.toml 中允许插件的 MCP 工具，然后重启 Codex。
也可使用独立 CLI 路径，适用于没有插件支持的智能体或从源码构建。预构建包无需 Rust 工具链，支持 Apple Silicon macOS、glibc ≥2.38 的 Linux（x86-64 与 arm64）、Windows x64 和 Android/Termux arm64。@rag-rat/bin 会从对应的 GitHub release 获取完整二进制文件，FastEmbed 的 ONNX Runtime 为静态链接。从源码构建时，默认构建需要 glibc ≥2.38，且不支持 Intel macOS 和 musl/Alpine；在这些平台（包括 Ubuntu 22.04）上应使用纯 Rust embedder。
初始化仓库使用 init（交互式终端向导，扫描仓库、引导语言与嵌入选择、写入 rag-rat.toml 并构建初始索引）。非交互式用 rag-rat init --yes 采用默认值并安装 git 维护钩子（--no-hooks 跳过；--dry-run 预览配置）。--yes 不会覆盖已存在的 rag-rat.toml，除非加 --force。配置参考见 docs/config.md。
MCP 服务器使用 STDIO：客户端从仓库启动 rag-rat mcp，以发现正确的 rag-rat.toml 与仓库范围。rag-rat init 会打印注册命令，但不自行注册。可传 rag-rat mcp --json 让客户端解析 JSON；工具文本默认是 TOON。完整工具 schema 见 docs/mcp-tools.md。注意不要将全局服务器固定到单一仓库配置，应按项目注册 MCP，让进程从工作目录发现配置。
仓库索引后，代码图谱、符号、git 历史、语义搜索和克隆检测即可用；仓库记忆初始为空，随智能体用 memory_create 记录发现而积累，并在后续结果中自动浮现（issue/PR 理由需要 rag-rat papertrail sync）。
常见工具包括：impact_surface（编码预检：调用者、被调用者、测试、git 历史、GitHub papertrail 及跨符号的仓库记忆）、semantic_search（对源码与文档的混合 BM25 + 向量召回）、symbol_lookup、find_callers / trace_callees、important_symbols、find_clones、memory_create 等。维护与诊断工具如 dream、heal_index、memory_doctor 等位于可选的 admin 与 graph 工具集（[mcp] toolsets）。所有工具详见 docs/mcp-tools.md。
仓库记忆是类型化图谱而非扁平列表：memory_edge_add / memory_edges 用 depends_on、relates_to、supersedes、derived_from、tracks 等关系连接它们。dream 是保持记忆层可靠的维护循环，会重算关于记忆本身的排序工作清单（如覆盖缺口、过期引用），每个条目有稳定 id 供审查。
适用场景
适合使用编码智能体进行开发、并希望在修改代码前掌握影响范围、测试、历史决策与重复代码信号的团队或个人开发者。适用于支持 MCP 的客户端（如 Claude Code、Codex、opencode）以及通过 CLI 或源码构建的集成方式。
限制
仓库提供的资料未明确说明定价、收费模式、性能基准或具体限制条件，这些信息暂未提供。平台支持方面，源码默认构建不支持 Intel macOS 与 musl/Alpine，这些平台需使用纯 Rust embedder。
