Mimirs

MIMIRS

以北欧智慧与知识之神 Mímir 命名。

为 AI 编码 Agent 提供持久的项目记忆。只需一条命令即可完成设置，无需维护。

你的 Agent 每次开始会话时都一无所知——只能猜文件名、搜索关键字、把上下文浪费在无关文件上，还会忘记昨天讨论过的所有内容。

在一个真实项目中，一条典型提示词会消耗 380K 个 token，端到端约需 12 秒。

使用 mimirs 建立索引后：91K 个 token，约需 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，因此仍会自动获取错误修复和新功能，但不会在未经你允许的情况下升级到带有破坏性变更的未来 2.0 版本。要升级到下一个主版本，请编辑参数或重新运行 bunx mimirs init。如果配置中已有 mimirs@latest，重新运行 bunx mimirs init 会将其改写为 mimirs@^1。

“command not found: bunx”／服务无法启动（但 bunx 在终端中可以运行）？ 从 Dock 或桌面启动器启动的编辑器不会加载 shell 配置文件，因此其 PATH 中没有 ~/.bun/bin。请在下方代码片段中将 command 设置为 which bunx 返回的绝对路径，而不是单独的 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"
      }
    }
  }
}

{
  "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"
      }
    }
  }
}

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

[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"

{
  "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 服务会在首次查询时延迟建立索引，因此配置完成后，只需向 Agent 提问即可。要预先强制建立完整索引（适用于大型仓库）：

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

5. 试用演示（可选）

bunx mimirs demo

手动工作流（不使用 init）

init 是一项便捷功能：它会配置你的编辑器（MCP 配置、Agent 规则、.gitignore、.mimirs/config.json）。它不会构建索引，下面的步骤也都不需要它——首次建立索引或查询时，索引和默认配置会自动创建。

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

不使用 init 就不会有 Agent 规则文件，因此你的助手不会知道这些工具的存在。你可以在提示词中提及 mimirs，也可以将 CLAUDE.md 中的工具列表复制到编辑器的规则中。

2. 构建索引。 MCP 服务会在首次调用工具时延迟建立索引，因此通过 Agent 使用时可以跳过此步骤。若要提前建立索引（大型代码库建议这样做；使用下面的 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 工具本身可在任何地方使用。

搜索质量

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

较大的代码库（Kubernetes、Excalidraw）规模足够大，因此一些相关文件的排名会刚好落在前 10 之外；前 20 的召回率可达 97–100%，因此在大型代码库中请设置 searchTopK: 15–20。

与编码 Agent 的对比（ContextBench）

我们还在 ContextBench（针对真实代码仓库进行金标准上下文检索）上测试了 mimirs。该基准中的其他项目都是完整的编码 Agent——多步骤探索者——而非单次调用的工具。对于一个聚焦查询（大模型阅读 issue 后发送的查询），一次 mimirs 检索调用与完整的 Agent 执行轨迹相比，排名如下：

mimirs 通过单次调用在两项覆盖率指标上均领先。文件精确率有意排在最后：漏掉一个金标准文件是致命的（大模型永远看不到要修复的代码），多找到一个文件则很容易过滤——因此 mimirs 尽可能提高召回率，再由模型完成精确筛选。而文件精确率偏低，主要是指标造成的假象：mimirs 返回的非金标准文件中，约 86% 是与修复相关联的上下文（调用方、类型、同级实现），而非噪声——以金标准衡量时精确率为 0.19，以相关性衡量时则为 0.87。

相同的召回率，成本仅为一小部分。 在与仅使用 grep 的 Agent 正面对比时（原始 issue、无索引、不查看修复内容），针对相同的 15 个 issue 进行定位：mimirs 通过一次约 15 ms 的调用且不消耗任何大模型 Token，就能提供相关文件簇；Agent 则平均每个 issue 需要 约 11.5 次工具调用（每次都是一个大模型步骤）才能收敛——而且最终只找到主要文件。对于多文件修复，Agent 找到了金标准文件的 22%，而 mimirs 通过一次调用就找到了 56%——依赖关系图揭示了 issue 从未提及的次要文件。

n=15 的样本，对比 Agent 的 500 个样本集——仅供参考；Agent 的工具调用次数由其自行报告且设有上限。完整排行榜、注意事项、相关性和成本表请见 BENCHMARKS.md。

对比情况

为什么不选用现有工具？

• Continue.dev 的 @codebase——功能最接近（本地 RAG、开源），但检索功能集成在编辑器扩展中。Mimirs 是独立的 MCP 服务，提供明确的工具（search、read_relevant、project_map、search_conversation、annotate），供 Agent 规划调用，并内置对话追踪和 Wiki 生成器。
• Aider 的 repo-map——使用 tree-sitter 生成代码仓库的静态摘要，不使用嵌入。它巧妙而轻量，但摘要并不等于检索——mimirs 会针对每个查询，使用向量 + BM25 为代码块排序，并根据图中心性提升排名。
• Sourcegraph Cody / OpenCtx——代码搜索能力出色，但索引依赖云基础设施和账号。只需运行一条 bunx 命令即可使用 Mimirs，且数据不会离开你的设备。
• llama-index / LangChain / 自行搭建——这些都是库。Mimirs 开箱即用：已集成感知 AST 的分块、混合检索、文件监视器、对话追踪和注释功能。

工作原理

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

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 对话记录。Agent 可以在重要时刻创建检查点，供后续会话搜索。

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

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、Dockerfile、Makefile 等。扩展名不在已知列表中的文件会回退到按段落拆分。

文档

• 工具输出示例 — Agent 通过 MCP 实际收到的内容
• MCP 工具、CLI 与分析
• 配置与示例
• 基准测试

技术栈

所有数据都存储在项目内的 .mimirs/ 中——请将其加入 .gitignore。