local-rag

Dein Agent startet jede Sitzung blind — rät Dateinamen, grepst nach Schlüsselwörtern, verbrennt Kontext an irrelevanten Dateien und vergisst alles, was ihr gestern besprochen habt.

Bei einem echten Projekt verbrannte ein typischer Prompt 380K Tokens und ~12 Sekunden Ende-zu-Ende.

Nach der Indexierung mit mimirs: 91K Tokens, ~3 Sekunden — ein Rückgang um 76% auf dieser Codebasis. Deine Werte variieren mit Repogröße, Abfrage und Modell.

Schnellstart

1. Voraussetzungen

Bun (curl -fsSL https://bun.sh/install | bash) und unter macOS ein modernes SQLite — das von Apple gebündelte unterstützt keine Erweiterungen:

brew install sqlite

Linux und Windows werden bereits mit einem kompatiblen SQLite ausgeliefert.

2. Editor einrichten (automatisch)

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

Dadurch werden die MCP-Server-Konfiguration, Editor-Regeln, .mimirs/config.json und ein .gitignore-Eintrag erstellt. Führe den Befehl mit --ide all aus, um alle unterstützten Editoren auf einmal einzurichten.

init deckt Claude Code, Cursor, Windsurf, Copilot und JetBrains (Junie) ab. Für alles andere — Codex, Zed, benutzerdefinierte Clients — kopiere eines der folgenden Snippets.

3. Editor einrichten (manuelle Referenz)

Der mimirs-MCP-Server läuft über stdio. Jeder Client benötigt dieselben drei Dinge: einen command (bunx), args (["mimirs@^1", "serve"]) und eine RAG_PROJECT_DIR-Umgebungsvariable, die auf dein Projektverzeichnis zeigt.

Warum @^1 und nicht @latest? Die Versionsspanne hält dich bei 1.x, sodass Bugfixes und neue Funktionen weiterhin automatisch eintreffen, aber ein zukünftiges 2.0 mit Breaking Changes landet nie ohne dein Zutun. Um auf eine neue Hauptversion zu wechseln, bearbeite das Argument oder führe bunx mimirs init erneut aus. Wenn du bereits mimirs@latest in einer Konfiguration hast, überschreibt ein erneutes bunx mimirs init es mit mimirs@^1.

„command not found: bunx“ / Server startet nicht (aber bunx funktioniert in deinem Terminal)? Editoren, die über das Dock oder einen Desktop-Launcher gestartet werden, laden dein Shell-Profil nicht, daher ist ~/.bun/bin nicht in deren PATH. Verwende den absoluten Pfad aus which bunx als command anstelle des bloßen bunx in den untenstehenden Snippets. bunx mimirs init schreibt den absoluten Pfad automatisch (erneut ausführen, um eine bestehende Konfiguration zu reparieren), und bunx mimirs doctor erkennt das Problem.

{
  "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 liest MCP-Server aus deinem Home-Verzeichnis, nicht aus dem Projekt. Die JetBrains-Plugin-Variante verwendet ~/.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"
      }
    }
  }
}

Der Copilot von VS Code verwendet eine servers-Map (nicht mcpServers) und ein type-Feld.

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

Codex verwendet TOML, nicht JSON, und liest aus ~/.codex/config.toml. Ein Block pro Projekt — wähle einen eindeutigen Tabellennamen, wenn du mehrere Repos anbindest (mimirs-frontend, mimirs-api usw.).

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

Oder, gleichwertig, mit einer erweiterten env-Tabelle:

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

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

Wenn das Projekt in einem schreibgeschützten Mount liegt, setze RAG_DB_DIR auf einen beschreibbaren Speicherort. Der Index liegt dann dort anstelle von <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. Erste Indexierung

Der MCP-Server indexiert lazy bei der ersten Abfrage. Sobald er eingerichtet ist, kannst du deinen Agenten einfach etwas fragen. Um einen vollständigen Index im Voraus zu erzwingen (nützlich für große Repos):

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

5. Demo ausprobieren (optional)

bunx mimirs demo

Related MCP server: codeix

Manueller Workflow (ohne init)

init ist ein Komfortfeature: Es richtet deinen Editor ein (MCP-Konfiguration, Agent-Regeln, .gitignore, .mimirs/config.json). Es erstellt den Index nicht, und nichts davon wird im Folgenden benötigt — der Index und eine Standardkonfiguration werden automatisch beim ersten Indexieren oder Abfragen erstellt.

1. MCP-Server von Hand hinzufügen. Füge das Snippet für deinen Client aus der manuellen Referenz oben ein: command: "bunx", args: ["mimirs@^1", "serve"] und RAG_PROJECT_DIR, das auf dein Projektverzeichnis zeigt. Das ist die gesamte MCP-Einrichtung.

Ohne init gibt es keine Agent-Regeln-Datei, daher weiß dein Assistent nicht, dass die Tools existieren. Erwähne mimirs entweder in deinem Prompt oder kopiere die Werkzeugliste aus CLAUDE.md in die Regeln deines Editors.

2. Index erstellen. Der MCP-Server indexiert lazy beim ersten Tool-Aufruf, daher kannst du diesen Schritt über einen Agenten überspringen. Um vorab zu indexieren (empfohlen für große Repos und erforderlich vor dem CLI search/read weiter unten):

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

Kein init und keine Konfigurationsdatei erforderlich — Standardwerte werden angewendet und der Index wird nach <project>/.mimirs/ geschrieben.

3. Abfrage über die CLI. Zwei Lese-Befehle, die beide gegen den Index im aktuellen Verzeichnis laufen (mit --dir auf ein anderes Verzeichnis zeigen):

# 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

Begrenze den Umfang entweder mit --ext .ts,.tsx, --in src,packages/core oder --exclude tests. Hinweis: Die CLI-Befehle search/read indexieren nicht automatisch — führe zuerst mimirs index aus (nur der MCP-Server indexiert bei Bedarf).

Claude-Code-Plugin

Für eine tiefere Integration ist mimirs auch als Claude-Code-Plugin verfügbar. In einer Claude-Code-Sitzung:

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

Das Plugin verdrahtet den MCP-Server, drei Hooks — SessionStart (Kontextzusammenfassung), PostToolUse (automatisches Reindexieren bei Bearbeitung), SessionEnd (automatischer Checkpoint) — sowie eine Reihe von Workflow-Skills, die die Tools für häufige Aufgaben orchestrieren: explore, plan, review, debug, research, recall, catch-up, handoff, doc-gaps, scout und wiki.

Möchtest du die Skills ohne das Plugin? Es handelt sich um einfache SKILL.md-Dateien unter skills/. Kopiere beliebige davon in das .claude/skills/<name>/-Verzeichnis deines Projekts (mit dem Repo geteilt) oder nach ~/.claude/skills/<name>/ (für alle deine Projekte), und Claude Code übernimmt sie in der nächsten Sitzung. Skills sind eine Claude-Code-Funktion, gelten also nicht für andere Editoren — die MCP-Tools selbst funktionieren jedoch überall.

Suchqualität

89–97% Recall@10, 97–100% Recall@20, MRR 0.69–0.77. Gemessen an vier realen Codebasen in drei Sprachen mit stratifizierten, schwierigkeitsgemischten Abfragesätzen (je 72–120 Abfragen, ~⅓ schwer), erneut gemessen am 2026-06-04 an der aktuellen Pipeline. Die vollständige Methodik findest du in BENCHMARKS.md.

Die größeren Repos (Kubernetes, Excalidraw) sind groß genug, dass einige korrekte Dateien knapp hinter den Top 10 liegen; der Recall erreicht bis Top-20 97–100%, also setze searchTopK: 15–20 bei großen Repos.

Im Vergleich zu Coding-Agenten (ContextBench)

Wir haben mimirs auch auf ContextBench laufen lassen (Goldkontext-Abruf auf echten Repos), deren andere Einträge vollwertige Coding-Agenten sind — mehrstufige Explorer — und keine Einzelaufruf-Tools. Bei einer fokussierten Abfrage (was ein LLM nach dem Lesen des Issues sendet), schneidet ein einziger mimirs-Abruf im Vergleich zu kompletten Agent-Trajektorien wie folgt ab:

mimirs führt bei beiden Abdeckungsmetriken als Einzelaufruf. Die Dateipräzision ist mit Absicht die letzte: Eine verpasste Gold-Datei ist fatal (das LLM sieht den zu reparierenden Code nie), ein zusätzlicher Dateiverweis ist billig zu filtern — also maximiert mimirs den Recall und überlässt dem Modell den Präzisionsdurchgang. Und diese niedrige Dateipräzision ist größtenteils ein Artefakt der Metrik: ~86% der Nicht-Gold-Dateien, die mimirs zurückgibt, sind relevanter Kontext, der mit dem Fix zusammenhängt (Aufrufer, Typen, Schwesterimplementierungen), kein Rauschen — gemessen gegen Gold liegt die Präzision bei 0.19, gegen Relevanz bei 0.87.

Gleicher Recall, ein Bruchteil der Kosten. Im direkten Vergleich mit einem Nur-Grep-Agenten (rohes Issue, kein Index, kein Blick auf den Fix), der dieselben 15 Issues lokalisiert: mimirs liefert den relevanten Cluster in einem ~15-ms-Aufruf mit null LLM-Tokens; der Agent brauchte ~11.5 Tool-Aufrufe pro Issue (jeder ein LLM-Schritt), um zu konvergieren — und blieb bei der primären Datei stehen. Bei Multi-Datei-Fixes erreichte der Agent 22% der Gold-Dateien, mimirs 56% in diesem einen Aufruf — der Abhängigkeitsgraph bringt die sekundären Dateien zum Vorschein, die das Issue nie nennt.

n = 15 Stichprobe gegenüber den 500er-Sets der Agenten — richtungsweisend; die Tool-Aufrufe der Agenten wurden selbst gemeldet und gedeckelt. Vollständige Bestenlisten, Einschränkungen sowie Relevanz- und Kostentabellen in BENCHMARKS.md.

Wie es sich vergleicht

Warum kein bestehendes Tool?

• Continue.dev's @codebase — größte Überlappung (lokales RAG, Open Source), aber das Retrieval liegt innerhalb der Editor- Erweiterung. Mimirs is a eigenständiger MCP-Server with explizite Tools (search, read_relevant, project_map, search_conversation, annotate), die project Agent in seine Referenzplanung ganz klar einbeziehen kann, plus live Konversationsverfolgung und a integriertem Wiki-Generator.

• Aiders repo-map — statische tree-sitter-Zusammenfassung des Repos, keine Embeddings. Clever und Leichtgewichtig, oder a summary summary ist kein Retrieval: Mimirs bewertet Chunks pro Abfruf mit Vektor + BM25 und gibt zusätzlich deine Graph-Zentralität ein.

• Sourcegraph Cody / OpenCtx — exzellent bei der Codesuche, aber die Indexierung basiert auf Cloud-Infrastruktur und einem Konto. Mimirs ist nur one bunx-Angriff entfernt und verlässt nie nezubrechen.

• llama-index / LangChain / selbst gebaut — das sind Bibliotheken. Mimirs ist vollständig ausgestattet: AST-bewertetes Chunking, hybrides Retrieval, Datei-Watcher, Konversationsverfolgung und Annotationen sind bereits involviert.

So funktioniert es

1. Parsen & Chunkning — Der Inhalt wird mit typpassenden Strategien aufgeteilt: Funktions-/Klassengrenzen für Code (mit tree-sitter ingiebig 24 Sprachen), Überschriften für Markdown, Top-Level-Schlüssel für YAML/JSON. Chunks, die die Token-Limit des Embedding-Modells überschreiten, werden in Window-Verfahren aufgeteilt und wieder zusammengefügt.

2. Embedding — Jeder Chunk wird mithilfe von all-MiniLM-L6-v2 (in-process per Transformers.js + ONNX, keine API-Aufrufe) zu einem 384-dimensionalen Vektor. Die Vektoren werden in sqlite-vec gespeichert.

3. Abhängigkeitsgraph? — Import-Modul und exportierte Symbole werden beim AST-Chunking erfasst und dann aufgelöst, um einen Abhängigkeitsgraphen auf Datei-Ebene und einen Call-Graphen auf Symbol-Ebene zu erstellen. impact geht die transitiven Aufrufer einer Funktion durch (Blast-Radius + auszuführende Tests); trace erfährt, wie ein Symbol ein anderes erreicht; das CLI mimirs affected transformiert einen Git-Diff in die exakte auszuführende Test-Menge.

4. Hybrid-Suche — Freie/query führen Vektorähnlichkeit und BM25 parallel aus und werden durch Reciprocal-Rank–Fusion (gewichtet, Standard 0.5) kombiniert — robust gegen die sehr unterschiedlichen Score-Skalen der beiden Verfahren. Bezeichner werden aufgeteilt (camelCase/snake)._case), sodass depends getDependsOn findet. Die Ergebnisse werden dann zusätzlich mit der Zentralität im Abhängigkeitsgraph und Pfadheutiken verstärkt. read_relevant liefert einzelne Chunks Messies.

5. Überwachen & Reindizieren — Dateiänderungen werden mit einer 2-Sekunden-Entprellung erkannt. Geänderte Dateien werden neu indiziert; gelöschte Dateien werden entfernt.

6. Konversation & Prüfpunkte — Die JSONL-Transkripte von Claude Code werden in Echtzeit verfolgt. Agenten können an wichtigen Stellen Prüfpunkte nutzen, um später in Sitzungen zu suchen.

7. Notizen — Notizen an Dateien oder Symbolen erscheinen als [NOTIZ]-Blöcke direkt in den read_relevant-Ergebnissen.

8. Analysen — Jede Abfrage wird protokolliert. Die Analysen zeigen Abfragen ohne Ergebnisse, Abfragen mit geringer Relevanz und Trends im Vergleich zwischen den Zeiträumen.

Datenverwaltung

Mimirs läuft vollständig auf deinem Rechner. Es indexiert Dateien, die dein Repo verfolgt, sowie untracked, aber nicht per .gitignore ausgeschlossene Dateien (dadurch kann eine möglicherweise vergessen, in .gitignore aufgenommene .env-Datei gelesen werden — typische Secret-Muster wie .env, *.pem, *.key und SSH-Schlüssel sind standardmäßig ausgeschlossen; deine eigenen kannst du unter exclude in .mimirs/config.json hinzufügen). Inhalte und Embeddings speichert es in <project>/.mimirs/index.db, einer lokalen SQLite-Datei. Die Konversationsindizierung liest ausschließlich die Transkripte des aktuellen Projekts unter ~/.claude/projects/<this-project>/.

Der einzige Netzwerkaufruf ist der einmalige Download des Embedding-Modells (HitScale/all-MiniLM-L6-v2) von huggingface.co, gespeichert unter ~/.cache/mimirs/models. Dein Code verlässt nie deinSystem — es wird nichts an einen Server gesendet.

Unterstützte Programmiersprachen

AST-bewusstes Chunking über bun-„chunk mit tree-sitter-Grammatiken:

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

Zusätzlich indexiert: Markdown, JSON, XML, SQL, GraphQL, Protobuf, Terraform, Dockerfiles, Makefiles und weitere. Dateien ohne bekannte Endung fallen auf eine absatzweise Unterteilung zurück.

Dokumentation

• Beispiel-Tool-Ausgaben — was dein Agent tatsächlich über SMP erhält

• MCP-Tools, CLI & Analytics

• Konfiguration & Beispiele

• Benchmarks

Architektur

Alle Daten liegen in .mimirs/ in deinem Projekt — bitte füge es zu deiner .gitignore hinzu.