local-rag

你的代理每次会话都是盲开——猜测文件名、用 grep 搜索关键词、把上下文烧在无关文件上，并且忘记你们昨天讨论的一切。

在一个真实项目中，一个典型提示词曾消耗 380K tokens 和约 12 秒的端到端时间。

使用 mimirs 索引后：91K tokens，约 3 秒——在该代码库上下降了 76%。具体数字会因仓库大小、查询和模型而异。

快速开始

1. 前置条件

Bun（curl -fsSL https://bun.sh/install | bash）以及 macOS 上较新的 SQLite——Apple 自带的版本不支持扩展：

brew install sqlite

Linux 和 Windows 已经自带了兼容的 SQLite。

2. 设置你的编辑器（自动）

bunx mimirs init --ide claude   # or: cursor, windsurf, copilot, jetbrains, all

这会创建 MCP 服务器配置、编辑器规则、.mimirs/config.json 和 .gitignore 条目。使用 --ide all 运行可一次性设置所有受支持的编辑器。

init 覆盖 Claude Code、Cursor、Windsurf、Copilot 和 JetBrains (Junie)。对于其他所有情况——Codex、Zed、自定义客户端——从下方复制一个代码片段即可。

3. 设置你的编辑器（手动参考）

mimirs MCP 服务器通过 stdio 运行。每个客户端都需要相同的三样东西：一个 command（bunx）、args（["mimirs@^1", "serve"]），以及一个指向项目根目录的 RAG_PROJECT_DIR 环境变量。

为什么用 @^1 而不是 @latest？ 这个版本范围让你保持在 1.x，因此 bug 修复和新功能仍会自动到来，但带有破坏性变更的未来 2.0 版本绝不会在你未主动要求时落地。要升到下一个主版本，请编辑该参数或重新运行 bunx mimirs init。如果你的某个配置中已有 mimirs@latest，重新运行 bunx mimirs init 会将其改写为 mimirs@^1。

「command not found: bunx」/ 服务器无法启动（但 bunx 在终端里可以正常工作）？ 从 Dock 或桌面启动器启动的编辑器不会加载你的 shell 配置，因此 ~/.bun/bin 不在它们的 PATH 中。请用 which bunx 输出的绝对路径作为 command，而不是下面代码片段中的裸 bunx。bunx mimirs init 会自动写入绝对路径（重新运行即可修复现有配置），bunx mimirs doctor 可以检测出该问题。

{
  "mcpServers": {
    "mimirs": {
      "command": "bunx",
      "args": ["mimirs@^1", "serve"],
      "env": {
        "RAG_PROJECT_DIR": "/absolute/path/to/your/project"
      }
    }
  }
}

{
  "mcpServers": {
    "mimirs": {
      "command": "bunx",
      "args": ["mimirs@^1", "serve"],
      "env": {
        "RAG_PROJECT_DIR": "/absolute/path/to/your/project"
      }
    }
  }
}

Windsurf 从你的主目录读取 MCP 服务器，而不是项目目录。JetBrains 插件变体使用 ~/.codeium/mcp_config.json。

{
  "mcpServers": {
    "mimirs": {
      "command": "bunx",
      "args": ["mimirs@^1", "serve"],
      "env": {
        "RAG_PROJECT_DIR": "/absolute/path/to/your/project"
      }
    }
  }
}

{
  "mcpServers": {
    "mimirs": {
      "command": "bunx",
      "args": ["mimirs@^1", "serve"],
      "env": {
        "RAG_PROJECT_DIR": "/absolute/path/to/your/project"
      }
    }
  }
}

VS Code 的 Copilot 使用 servers 映射（而不是 mcpServers）和一个 type 字段。

{
  "servers": {
    "mimirs": {
      "type": "stdio",
      "command": "bunx",
      "args": ["mimirs@^1", "serve"],
      "env": {
        "RAG_PROJECT_DIR": "/absolute/path/to/your/project"
      }
    }
  }
}

Codex 使用 TOML 而不是 JSON，并从 ~/.codex/config.toml 读取。每个项目一个块——如果你接入多个仓库，请为每个仓库选择唯一的表名（mimirs-frontend、mimirs-api 等）。

[mcp_servers.mimirs]
command = "bunx"
args = ["mimirs@^1", "serve"]
env = { RAG_PROJECT_DIR = "/absolute/path/to/your/project" }

或者等效地，使用展开的环境变量表：

[mcp_servers.mimirs]
command = "bunx"
args = ["mimirs@^1", "serve"]

[mcp_servers.mimirs.env]
RAG_PROJECT_DIR = "/absolute/path/to/your/project"

如果项目位于只读挂载中，请将 RAG_DB_DIR 设置为可写位置。索引将存放在那里，而不是 <project>/.mimirs/。

{
  "mcpServers": {
    "mimirs": {
      "command": "bunx",
      "args": ["mimirs@^1", "serve"],
      "env": {
        "RAG_PROJECT_DIR": "/read/only/project",
        "RAG_DB_DIR": "/home/me/.cache/mimirs/myproject"
      }
    }
  }
}

4. 首次索引

MCP 服务器在首次查询时惰性索引，因此配置好之后，你直接向代理提问即可。要预先强制完整索引（对大型仓库很有用）：

bunx mimirs index            # current directory
bunx mimirs status           # how many files, chunks, embeddings

5. 尝试演示（可选）

bunx mimirs demo

Related MCP server: codeix

手动工作流（不使用 init）

init 是一个便捷工具：它会配置好你的编辑器（MCP 配置、代理规则、.gitignore、.mimirs/config.json）。它不会构建索引，下面的一切也不需要它——索引和默认配置会在你首次索引或查询时自动创建。

1. 手动添加 MCP 服务器。 从上面的手动参考中取用适用于你的客户端的代码片段：command: "bunx"、args: ["mimirs@^1", "serve"]，以及指向项目根目录的 RAG_PROJECT_DIR。这就是完整的 MCP 设置。

没有 init 就没有代理规则文件，因此你的助手不会知道这些工具的存在。要么在提示词中提及 mimirs，要么将 CLAUDE.md 中的工具列表复制到你的编辑器规则中。

2. 构建索引。 MCP 服务器在首次工具调用时惰性索引，因此通过代理使用时你可以跳过这一步。要预先索引（建议大型仓库使用，并且是下面 CLI search/read 之前所必需的）：

bunx mimirs index                                # current directory
bunx mimirs index /path/to/repo                  # a specific directory
bunx mimirs index --patterns "src/**/*.ts,*.md"  # restrict to globs
bunx mimirs status                               # files, chunks, embeddings

不需要 init，也不需要配置文件——会自动应用默认设置，索引写入 <project>/.mimirs/。

3. 从 CLI 查询。 两个读取命令，都针对当前目录中的索引运行（使用 --dir 指向其他位置）：

# Where is it? — ranked file paths + snippet previews
bunx mimirs search "where is auth handled" --top 10

# What is it? — the actual matching code chunks (functions, classes, sections)
bunx mimirs read "jwt validation" --top 8 --threshold 0.3

可以使用 --ext .ts,.tsx、--in src,packages/core 或 --exclude tests 限定范围。注意：CLI 的 search/read 不会自动索引——请先运行 mimirs index（只有 MCP 服务器按需索引）。

Claude Code 插件

为了更深入的集成，mimirs 还可以作为 Claude Code 插件使用。在 Claude Code 会话中：

/plugin marketplace add https://github.com/TheWinci/mimirs.git
/plugin install mimirs

该插件接入 MCP 服务器、三个钩子——SessionStart（上下文摘要）、PostToolUse（编辑时自动重新索引）、SessionEnd（自动检查点）——以及一组工作流技能，为常见任务编排这些工具：explore、plan、review、debug、research、recall、catch-up、handoff、doc-gaps、scout 和 wiki。

想要技能但不想用插件？ 它们是 skills/ 下的纯 SKILL.md 文件。把你喜欢的任意技能复制到项目的 .claude/skills/<name>/（与仓库共享）或 ~/.claude/skills/<name>/（你的所有项目），Claude Code 会在下次会话时拾取它们。技能是 Claude Code 的功能，因此不适用于其他编辑器——但 MCP 工具本身在任何地方都能用。

搜索质量

89–97% 的 Recall@10、97–100% 的 Recall@20、MRR 0.69–0.77。在四个真实代码库、覆盖三种语言上，使用分层、难度混合的查询集（每个 72–120 个查询，约 ⅓ 为困难）进行基准测试，并于 2026-06-04 在当前流水线上重新测量。完整方法论见 BENCHMARKS.md。

较大的仓库（Kubernetes、Excalidraw）规模足够大，一些正确文件的排名刚好落在前 10 之外；到前 20 时召回率达到 97–100%，因此在大型仓库上设置 searchTopK: 15–20。

与编码代理对比（ContextBench）

我们也在 ContextBench（在真实仓库上进行黄金上下文检索）上运行了 mimirs，该基准中的其他参赛者是完整的编码代理——多步骤探索型——而不是单次调用的工具。给定一个聚焦的查询（LLM 在阅读 issue 后发送的内容），一次 mimirs 检索调用与完整的代理轨迹相比，排名如下：

mimirs 作为单次调用在两项覆盖率指标上均领先。文件精确率垫底是故意的：漏掉黄金文件是致命的（LLM 永远看不到需要修复的代码），而多一个文件引用过滤起来代价很低——因此 mimirs 最大化召回率，让模型去做精确率的筛选。而且那个较低的文件精确率主要是指标的产物：mimirs 返回的非黄金文件中约 86% 是与修复耦合的相关上下文（调用方、类型、同层实现），而不是噪音——对照黄金文件测量精确率为 0.19，对照相关性则为 0.87。

相同的召回率，成本却只有一小部分。 与一个仅用 grep 的代理（原始 issue、无索引、不偷看修复）直接对比，定位相同的 15 个 issue：mimirs 用一次约 15 ms 的调用、零 LLM tokens 就返回了相关文件簇；而该代理平均每个 issue 花了 约 11.5 次工具调用（每次都是一步 LLM）才收敛——并且止步于主文件。在多文件修复中，该代理只触及了 22% 的黄金文件，而 mimirs 在这一次调用中达到 56%——依赖关系图让 issue 中从未提及的次要文件浮出水面。

n=15 的样本对比代理的 500 条——仅具方向性意义；代理的工具调用次数为自报且设有上限。完整排行榜、注意事项、相关性与成本表见 BENCHMARKS.md。

对比

为什么不用现有工具？

• Continue.dev 的 @codebase — 与 Mimirs 最接近（本地 RAG，开源），但检索功能位于编辑器扩展内部。Mimirs 是一个独立的 MCP 服务器，提供显式工具（search、read_relevant、project_map、search_conversation、annotate），代理可以围绕这些工具进行规划，并且内置了会话跟踪和 wiki 生成器。

• Aider 的 repo-map — 仓库的静态 tree-sitter 摘要，没有嵌入。巧妙且轻量，但摘要不是检索——mimirs 使用向量 + BM25 对每个查询的块进行排序，并通过图中心性提升。

• Sourcegraph Cody / OpenCtx — 在代码搜索方面表现出色，但索引依赖云端基础设施和账户。Mimirs 只需一条 bunx 命令即可运行，且永远不会离开你的机器。

• llama-index / LangChain / 自建方案 — 那些是库。Mimirs 开箱即用：AST 感知分块、混合检索、文件监视器、会话跟踪和注释都已集成。

工作原理

1. 解析与分块 — 使用类型匹配策略拆分内容：代码按函数/类边界（通过 tree-sitter 支持 24 种语言）、markdown 按标题、YAML/JSON 按顶层键。超过嵌入模型 token 限制的块会被窗口化并合并。

2. 嵌入 — 每个块通过 all-MiniLM-L6-v2 变成一个 384 维向量（通过 Transformers.js + ONNX 在进程内完成，无 API 调用）。向量存储在 sqlite-vec 中。

3. 构建依赖图 — 在 AST 分块过程中捕获导入说明符和导出的符号，然后进行解析以构建文件级依赖图和符号级调用图。impact 遍历函数的传递调用者（影响范围 + 需要运行的测试）；trace 查找一个符号如何到达另一个符号；mimirs affected CLI 将 git diff 转换为需要运行的精确测试集。

4. 混合搜索 — 查询并行运行向量相似度和 BM25，通过倒数排名融合（加权，默认 0.5）合并——对两个评分器截然不同的评分范围具有鲁棒性。标识符会被拆分（camelCase/snake_case），因此搜索 depends 可以匹配 getDependsOn。然后通过依赖图中心性和路径启发式对结果进行提升。read_relevant 返回带有实体名称和精确行范围（path:start-end）的各个块。

5. 监视与重新索引 — 文件更改以 2 秒防抖检测。更改的文件会重新索引；删除的文件会被清除。

6. 会话与检查点 — 实时跟踪 Claude Code 的 JSONL 记录。代理可以在重要时刻创建检查点，供未来会话搜索。

7. 注释 — 附加到文件或符号的注释会以内联的 [NOTE] 块形式出现在 read_relevant 结果中。

8. 分析 — 每次查询都会被记录。分析会呈现零结果查询、低相关性查询以及环比趋势。

数据处理

mimirs 完全在你的机器上运行。它会索引仓库跟踪的文件以及未跟踪但未被 gitignore 忽略的文件（因此你忘记加入 gitignore 的 .env 可能被读取——默认排除常见的机密模式，如 .env、*.pem、*.key 和 SSH 密钥；你可以在 .mimirs/config.json 的 exclude 中添加自己的模式）。文件内容和嵌入存储在 <project>/.mimirs/index.db 中，这是一个本地 SQLite 文件。会话索引只读取 ~/.claude/projects/<this-project>/ 下当前项目的记录。

唯一的网络调用是一次性从 huggingface.co 下载嵌入模型（Xenova/all-MiniLM-L6-v2），缓存在 ~/.cache/mimirs/models。你的代码永远不会离开你的机器——不会向任何服务器发送任何内容。

支持的语言

通过 bun-chunk 结合 tree-sitter 语法进行 AST 感知分块：

TypeScript, JavaScript, Python, Go, Rust, Java, C, C++, C#, Ruby, PHP, Scala, Kotlin, Lua, Zig, Elixir, Haskell, OCaml, Dart, Bash/Zsh, TOML, YAML, HTML, CSS/SCSS/LESS

还索引：Markdown、JSON、XML、SQL、GraphQL、Protobuf、Terraform、Dockerfiles、Makefiles 等。没有已知扩展名的文件回退到段落拆分。

文档

• 工具输出示例 — 你的代理通过 MCP 实际接收到的内容

• MCP 工具、CLI 与分析

• 配置与示例

• 基准测试

技术栈

所有数据都位于项目内的 .mimirs/ 中——请将其添加到 .gitignore。