local-rag

Ваш агент начинает каждую сессию вслепую — угадывая имена файлов, ища по ключевым словам, сжигая контекст на нерелевантных файлах и забывая всё, что вы обсуждали вчера.

На одном реальном проекте типичный промпт сжигал 380K токенов и ~12 секунд от начала до конца.

После индексации с помощью mimirs: 91K токенов, ~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. Настройка редактора (ручной справочник)

MCP-сервер mimirs работает через 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-профиль, поэтому ~/.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"
      }
    }
  }
}

Copilot в VS Code использует карту 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" }

Или, что эквивалентно, с развёрнутой таблицей env:

[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 (автоматическая контрольная точка) — и набор workflow-навыков, которые оркестрируют инструменты для типовых задач: explore, plan, review, debug, research, recall, catch-up, handoff, doc-gaps, scout и wiki.

Нужны навыки без плагина? Это обычные файлы SKILL.md в skills/. Скопируйте любые понравившиеся в .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; полнота достигает 97–100% к топ-20, так что на больших репозиториях задавайте searchTopK: 15–20.

Сравнение с агентами, пишущими код (ContextBench)

Мы также запускали mimirs на ContextBench (извлечение эталонного контекста из реальных репозиториев), другие участники которого — полноценные агенты, пишущие код, — многошаговые исследователи, а не инструменты с одним вызовом. При сфокусированном запросе (то, что LLM отправляет после чтения issue) один вызов поиска mimirs ранжируется так в сравнении с целыми траекториями агентов:

mimirs лидирует по обеим метрикам покрытия одним вызовом. Точность по файлам намеренно на последнем месте: пропущенный эталонный файл фатален (LLM никогда не увидит код, который нужно исправить), а лишняя ссылка на файл дёшево отфильтровывается — поэтому mimirs максимизирует полноту и позволяет модели выполнить проход по точности. И эта низкая точность по файлам — в основном артефакт метрики: ~86% не-эталонных файлов, которые возвращает mimirs, — это релевантный контекст, связанный с исправлением (вызывающие функции, типы, соседние реализации), а не шум: при измерении против эталона точность равна 0.19, а против релевантности — 0.87.

Та же полнота за долю стоимости. В прямом сравнении с агентом на основе только grep, который локализует те же 15 issues (сырой issue, без индекса, без подглядывания в исправление): mimirs выдаёт релевантный кластер за один вызов ~15 мс с нулевыми LLM-токенами; агенту потребовалось ~11.5 вызовов инструментов на issue (каждый — шаг LLM), чтобы сойтись, — и он остановился на основном файле. При многофайловых исправлениях агент достиг 22% эталонных файлов, mimirs — 56% за тот единственный вызов: граф зависимостей показывает вторичные файлы, которые в issue вообще не названы.

Выборка n=15 против набора агентов из 500 — результаты ориентировочные; вызовы инструментов агентов заявлены самими агентами и ограничены. Полные рейтинги, оговорки, таблицы релевантности и стоимости в BENCHMARKS.md.

Сравнение с альтернативами

Почему не существующий инструмент?

• Continue.dev’s @codebase — ближайший по функциональности аналог (локальный RAG, open source), но поиск живёт внутри расширения редактора. Mimirs — это автономный MCP-сервер с явными инструментами (search, read_relevant, project_map, search_conversation, annotate), вокруг которых агент может строить план, плюс встроенное чтение журналов бесед и генератор вики.

• Aider’s repo-map — статическая tree-sitter-сводка по репозиторию, без эмбеддингов. Умное и лёгкое решение, но сводка — это не поиск: mimirs ранжирует чанки под каждый запрос с помощью векторов + BM25 и повышает их вес по центральности в графе.

• Sourcegraph Cody / OpenCtx — отлично подходят для поиска по коду, но индексация там опирается на облачную инфраструктуру и учётную запись. Mimirs — одной командой bunx, и он никогда не покидает вашу машину.

• llama-index / LangChain / своя реализация — это библиотеки. Mimirs — решение «всё включено»: AST-чанкинг, гибридный поиск, файловый сторож, чтение журналов бесед и аннотации — уже соединено в единую систему.

Как это работает

1. Разбор и разбиение на чанки — содержимое делится по стратегиям, соответствующим типу данных: границы функций и классов для кода (через tree-sitter для 24 языков), заголовки для markdown, ключи верхнего уровня для YAML/JSON. Чанки, превышающие лимит токенов модели эмбеддингов, разбиваются на окна и объединяются.

2. Эмбеддинги — каждый чанк превращается в 384-мерный вектор с помощью all-MiniLM-L6-v2 (внутри процесса, на базе Transformers.js + ONNX, без вызовов API). Векторы хранятся в sqlite-vec.

3. Построение графа зависимостей — спецификаторы импортов и экспортируемые символы собираются во время AST-чанкинга, а затем разрешаются в граф на уровне файлов и граф вызовов на уровне символов. impact обходит транзитивные вызывающие функции (радиус поражения и какие тесты вирунчить); trace узнаёт, как один символ связан с другим; CLI mimirs affected превращает git diff в точный набор тестов для запуска.

4. Гибридный поиск — запросы выполняют векторную поиск и BM25 параллельно и объединяются механизмом слияния обратных рангов (weighted, по умолчанию 0.5) — так они устойчивы к совершенно разным шкалам оценок двух скораров. Идентификаторы разбиваются (camelCase/snake_case), поэтому поиск depends находит getDependsOn. Затем результаты получают повышение по центральности в графе зависимостей и эвристикам по путям. read_relevant возвращает отдельные чанки с именами сущностей и точными диапазонами строк (path:start-end).

5. Слежение и переиндексация — изменения файлов отслеживаются с debounce-задержкой 2 секунды. Изменённые файлы переиндексируются; удалённые — удаляются из индекса.

6. Беседы и контрольные точки — в реальном времени читает JSON-логи транскриптов Claude Code. Агенты могут создавать контрольные точки в важный момент, чтобы их можно было найти в будущих сессиях.

7. Аннотации — заметки, прикреплённые к файлам или символам, отображаются в виде блоков [NOTE] прямо в результатах read_relevant.

8. Аналитика — каждый запрос логируется. Аналитика выявляет запросы без результатов, запросы с низкой релевантностью и тренды период-к-периоду.

Работа с данными

mimirs работает полностью на локальной машине. Он индексирует файлы, отслеживаемые вашим репозиторием, а также неотслеживаемые, но не исключённые через .gitignore (так что .env, который вы забыли добавить в .gitignore, может быть прочитан — типичные секретные паттерны, такие как .env, *.pem, *.key и SSH-ключи, по умолчанию исключены; свои паттерны можно добавить в exclude в .mimirs/config.json). Файлы и эмбеддинги хранятся в <project>/.mimirs/index.db — одном локальном файле SQLite. Индексация бесед читает только транскрипты текущего проекта в ~/.claude/projects/<this-project>/.

Единственный сетевой запрос — однократная загрузка модели эмбеддингов (Xenova/all-MiniLM-L6-v2) с huggingface.co, которая кэшируется в ~/.cache/mimirs/models. Ваш код никогда не покидает вашу машину — никакие данные не отправляются на серверы.

Поддерживаемые языки

AST-чанкинг через bun-chunk с грамматиками tree-sitter:

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 и другие. Файлы без известного расширения разбиваются на абзацы.

Документация

• Примеры выходных данных MCP — что именно агент получает по каналам MCP

• MCP-инструменты, CLI и аналитика

• Конфигурация и примеры

• Бенчмарки