MIMIRS

MIMIRS

What is MIMIRS about?

MIMIRS creates a local vector store of your entire codebase, enabling AI assistants to retrieve relevant snippets, symbols, and documentation instantly. It eliminates the need for repetitive file‑grepping, large context windows, and external RAG services.

How to use MIMIRS?

1. Install SQLite (required for extensions):

   brew install sqlite   # macOS example
   

2. Run the CLI (prefer npx for convenience):

   npx mimirs init --ide claude   # replace "claude" with cursor, windsurf, copilot, jetbrains or "all"
   

   This creates the MCP server configuration, editor rules, .mimirs/config.json, and adds a .gitignore entry.
3. Start the server (the CLI launches the MCP server automatically when needed).
4. Optional demo to see it in action:

   npx mimirs demo
   

5. Claude Code plugin (or any MCP client) can now call search, read_relevant, etc., and benefit from cross‑session memory, auto‑reindexing, and checkpoints.

Key Features

• Full‑local operation – no API keys, no cloud, only Bun and SQLite.
• Hybrid semantic search – combines vector similarity (384‑dim MiniLM embeddings) with BM25, boosted by a dependency‑graph.
• AST‑aware chunking for 24 programming languages (via tree‑sitter) and smart handling of markup, config, and data files.
• Cross‑session memory & checkpoints – agents retain conversation context across runs.
• Automatic watch & re‑index – file changes are detected and indexed within seconds.
• Annotations & inline notes – attach metadata to files or symbols.
• Analytics dashboard – logs zero‑result queries, relevance trends, etc.
• Works with many editors – Claude Code, Cursor, Windsurf, JetBrains (Junie), GitHub Copilot, and any MCP client.

Use Cases

• Accelerate AI‑assisted coding by reducing prompt tokens from ~380 K to ~90 K and cutting response time from ~12 s to ~3 s.
• Generate and maintain project wikis automatically from indexed content.
• Perform dependency‑graph analysis for impact assessment or refactoring.
• Provide context‑rich answers in code review bots, pair‑programming tools, or documentation generators.
• Save on API costs for any LLM‑backed workflow that needs source‑code context.

FAQ

• Do I need an internet connection? No—everything runs locally after the initial npm install.
• Which languages are supported? 24 languages including TypeScript, Python, Go, Rust, Java, C/C++, C#, Ruby, PHP, Kotlin, etc., plus markup and config formats.
• Where is the data stored? In a SQLite database under .mimirs/ which is automatically added to .gitignore.
• Can I change the embedding model? Yes, the model is configurable in config.json (default is all-MiniLM-L6-v2).
• What editors can I use? Claude Code, Cursor, Windsurf, JetBrains (Junie), GitHub Copilot, or any client that speaks the MCP protocol.
• How does re‑indexing work? A file watcher debounces changes (2 s) and updates only the modified files, keeping the index fresh with minimal overhead.

Your agent starts every session blind — guessing filenames, grepping for keywords, burning context on irrelevant files, and forgetting everything you discussed yesterday.

On a real project, that costs 380K tokens per prompt and 12-second response times.

After indexing with mimirs: 91K tokens, 3 seconds. A 76% reduction — depending on your model and usage, that's hundreds to thousands in monthly API savings.

Quick start

1. Install SQLite (macOS)

Apple's bundled SQLite doesn't support extensions:

brew install sqlite

2. Set up your editor

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

This creates the MCP server config, editor rules, .mimirs/config.json, and .gitignore entry. Run with --ide all to set up every supported editor at once.

3. Try the demo (optional)

bunx mimirs demo

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 adds SessionStart (context summary), PostToolUse (auto-reindex on edit), and SessionEnd (auto-checkpoint) hooks. No CLAUDE.md instructions needed — the plugin's built-in skill handles tool usage.

Search quality

93–98% recall. Benchmarked on four real codebases across three languages (120 queries total) — from 97 files to 8,553 — with known expected results per query. Full methodology in BENCHMARKS.md.

Codebase	Language	Files	Queries	Recall@10	MRR	Zero-miss
mimirs	TypeScript	97	30	98.3%	0.683	0.0%
Excalidraw	TypeScript	693	30	96.7%	0.442	3.3%
Django	Python	3,090	30	93.3%	0.688	6.7%
Kubernetes	Go	8,553	30	90.0%	0.589	10.0%

Kubernetes excludes test files and demotes generated files. With searchTopK: 15, recall reaches 100%. See Kubernetes benchmarks for details.

How it compares

	mimirs	No tool (grep + Read)	Context stuffing	Cloud RAG services
Setup	One command	Nothing	Nothing	API keys, accounts
Token cost	~91K/prompt	~380K/prompt	Entire codebase	Varies
Search quality	93–98% Recall@10	Depends on keywords	N/A (everything loaded)	Varies
Code understanding	AST-aware (24 langs)	Line-level	None	Usually line-level
Cross-session memory	Conversations + checkpoints	None	None	Some
Privacy	Fully local	Local	Local	Data leaves your machine
Price	Free	Free	High token bills	$10-50/mo + tokens

How it works

1. Parse & chunk — Splits content using type-matched strategies: function/class boundaries for code (via tree-sitter across 24 languages), headings for markdown, top-level keys for YAML/JSON. Chunks that exceed the embedding model's token limit are windowed and merged.

2. Embed — Each chunk becomes a 384-dimensional vector using all-MiniLM-L6-v2 (in-process via Transformers.js + ONNX, no API calls). Vectors are stored in sqlite-vec.

3. Build dependency graph — Import specifiers and exported symbols are captured during AST chunking, then resolved to build a file-level dependency graph.

4. Hybrid search — Queries run vector similarity and BM25 in parallel, blended by configurable weight. Results are boosted by dependency graph centrality and path heuristics. read_relevant returns individual chunks with entity names and exact line ranges (path:start-end).

5. Watch & re-index — File changes are detected with a 2-second debounce. Changed files are re-indexed; deleted files are pruned.

6. Conversation & checkpoints — Tails Claude Code's JSONL transcripts in real time. Agents can create checkpoints at important moments for future sessions to search.

7. Annotations — Notes attached to files or symbols surface as [NOTE] blocks inline in read_relevant results.

8. Analytics — Every query is logged. Analytics surface zero-result queries, low-relevance queries, and period-over-period trends.

Supported languages

AST-aware chunking via bun-chunk with tree-sitter grammars:

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

Also indexes: Markdown, JSON, XML, SQL, GraphQL, Protobuf, Terraform, Dockerfiles, Makefiles, and more. Files without a known extension fall back to paragraph splitting.

Documentation

• MCP tools, CLI & analytics
• Configuration & examples
• Benchmarks

Stack

Layer	Choice
Runtime	Bun (built-in SQLite, fast TS)
AST chunking	bun-chunk — tree-sitter grammars for 24 languages
Embeddings	Transformers.js + ONNX (in-process, no daemon)
Embedding model	all-MiniLM-L6-v2 (~23MB, 384 dimensions) — configurable
Vector store	sqlite-vec (single .db file)
MCP	@modelcontextprotocol/sdk (stdio transport)
Plugin	Claude Code plugin with skills + hooks

All data lives in .mimirs/ inside your project — add it to .gitignore.