1. Prerequisites

Bun (curl -fsSL https://bun.sh/install | bash) and, on macOS, a modern SQLite — Apple's bundled one doesn't support extensions:

brew install sqlite

Linux and Windows ship with a compatible SQLite already.

Quick start

5. Try the demo (optional)

bunx mimirs demo

3. Set up your editor (manual reference)

The mimirs MCP server runs over stdio. Every client needs the same three things: a command (bunx), args (["mimirs@^1", "serve"]), and a RAG_PROJECT_DIR env var pointing at your project root.

Why @^1 and not @latest? The range keeps you on 1.x, so bug fixes and new features still arrive automatically, but a future 2.0 with breaking changes never lands without you asking for it. To move up a major, edit the arg or re-run bunx mimirs init. If you already have mimirs@latest in a config, re-running bunx mimirs init rewrites it to mimirs@^1.

"command not found: bunx" / server fails to start (but bunx works in your terminal)? Editors launched from the Dock or a desktop launcher don't load your shell profile, so ~/.bun/bin isn't on their PATH. Use the absolute path from which bunx as the command instead of the bare bunx in the snippets below. bunx mimirs init writes the absolute path automatically (re-run it to fix an existing config), and bunx mimirs doctor detects the problem.

<details> <summary><b>Claude Code</b> — <code>.mcp.json</code> in project root</summary>

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

<details> <summary><b>Cursor</b> — <code>.cursor/mcp.json</code> in project root</summary>

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

<details> <summary><b>Windsurf</b> — <code>~/.codeium/windsurf/mcp_config.json</code> (global)</summary>

Windsurf reads MCP servers from your home directory, not the project. JetBrains plugin variant uses ~/.codeium/mcp_config.json.

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

<details> <summary><b>JetBrains (Junie)</b> — <code>.junie/mcp.json</code> in project root</summary>

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

<details> <summary><b>GitHub Copilot</b> — <code>.vscode/mcp.json</code> in project root</summary>

VS Code's Copilot uses a servers map (not mcpServers) and a type field.

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

<details> <summary><b>Codex</b> — <code>~/.codex/config.toml</code> (global)</summary>

Codex uses TOML, not JSON, and reads from ~/.codex/config.toml. One block per project — pick a unique table name if you wire up multiple repos (mimirs-frontend, mimirs-api, etc).

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

Or, equivalently, with an expanded env table:

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

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

<details> <summary><b>Read-only project directory?</b> Redirect the index</summary>

If the project lives in a read-only mount, set RAG_DB_DIR to a writable location. The index lives there instead of <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"
      }
    }
  }
}

Manual workflow (without `init`)

init is a convenience: it wires up your editor (MCP config, agent rules, .gitignore, .mimirs/config.json). It does not build the index, and nothing below needs it — the index and a default config are created automatically the first time you index or query.

1. Add the MCP server by hand. Drop the snippet for your client from the manual reference above: command: "bunx", args: ["mimirs@^1", "serve"], and RAG_PROJECT_DIR pointing at your project root. That is the entire MCP setup.

Without init there's no agent-rules file, so your assistant won't know the tools exist. Either mention mimirs in your prompt, or copy the tool list from CLAUDE.md into your editor's rules.

2. Build the index. The MCP server indexes lazily on the first tool call, so through an agent you can skip this step. To index up front (recommended for large repos, and required before the CLI search/read below):

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

No init and no config file required — defaults are applied and the index is written to <project>/.mimirs/.

3. Query from the CLI. Two read commands, both running against the index in the current directory (use --dir to point elsewhere):

```bash

Claude Code plugin

For deeper integration, mimirs is also available as a Claude Code plugin. In a Claude Code session:

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

The plugin wires the MCP server, three hooks — SessionStart (context summary), PostToolUse (auto-reindex on edit), SessionEnd (auto-checkpoint) — and a set of workflow skills that orchestrate the tools for common jobs: explore, plan, review, debug, research, recall, catch-up, handoff, doc-gaps, scout, and wiki.

Want the skills without the plugin? They're plain SKILL.md files under skills/. Copy any you like into your project's .claude/skills/<name>/ (shared with the repo) or ~/.claude/skills/<name>/ (all your projects) and Claude Code picks them up next session. Skills are a Claude Code feature, so they don't apply to other editors — but the MCP tools themselves work everywhere.

vs coding agents (ContextBench)

We also ran mimirs on ContextBench (gold-context retrieval on real repos), whose other entries are full coding agents — multi-step explorers — not single-call tools. Given a focused query (what an LLM sends after reading the issue), one mimirs retrieval call ranks like this against whole agent trajectories:

mimirs leads both coverage metrics as a single call. File precision is last on purpose: a missed gold file is fatal (the LLM never sees the code to fix), an extra file reference is cheap to filter — so mimirs maximizes recall and lets the model do the precision pass. And that low file precision is mostly an artifact of the metric: ~86% of the non-gold files mimirs returns are relevant context coupled to the fix (callers, types, sibling implementations), not noise — measured against gold the precision is 0.19, against relevance it is 0.87.

Same recall, a fraction of the cost. Head-to-head against a grep-only agent (raw issue, no index, no peeking at the fix) localizing the same 15 issues: mimirs delivers the relevant cluster in one ~15 ms call with zero LLM tokens; the agent took ~11.5 tool calls per issue (each an LLM step) to converge — and stopped at the primary file. On multi-file fixes the agent reached 22% of the gold files, mimirs 56% in that single call — the dependency graph surfaces the secondary files the issue never names.

_n=15 sample vs the agents' 500-set — directional; agent tool-calls self-reported and capped. Full leaderboards, caveats, relevance + cost tables in BENCHMARKS.md.

How it compares