local-rag

Tu agente empieza cada sesión a ciegas: adivinando nombres de archivo, haciendo grep de palabras clave, quemando contexto en archivos irrelevantes y olvidando todo lo que hablaste ayer.

En un proyecto real, un prompt típico quemaba 380K tokens y ~12 segundos de principio a fin.

Tras indexar con mimirs: 91K tokens, ~3 segundos — una reducción del 76% en esa base de código. Tus cifras variarán según el tamaño del repositorio, la consulta y el modelo.

Inicio rápido

1. Requisitos previos

Bun (curl -fsSL https://bun.sh/install | bash) y, en macOS, un SQLite moderno: el integrado de Apple no admite extensiones:

brew install sqlite

Linux y Windows ya traen un SQLite compatible.

2. Configura tu editor (automático)

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

Esto crea la configuración del servidor MCP, las reglas del editor, .mimirs/config.json y la entrada de .gitignore. Ejecútalo con --ide all para configurar todos los editores compatibles a la vez.

init cubre Claude Code, Cursor, Windsurf, Copilot y JetBrains (Junie). Para todo lo demás — Codex, Zed, clientes personalizados — copia uno de los fragmentos siguientes.

3. Configura tu editor (referencia manual)

El servidor MCP de mimirs se ejecuta sobre stdio. Cada cliente necesita las mismas tres cosas: un command (bunx), args (["mimirs@^1", "serve"]) y una variable de entorno RAG_PROJECT_DIR que apunte a la raíz de tu proyecto.

¿Por qué @^1 y no @latest? El rango te mantiene en 1.x, así que los arreglos de errores y las nuevas funciones siguen llegando automáticamente, pero una futura 2.0 con cambios incompatibles nunca se instalará sin que lo pidas. Para subir a una versión mayor, edita el argumento o vuelve a ejecutar bunx mimirs init. Si ya tienes mimirs@latest en una configuración, volver a ejecutar bunx mimirs init lo reescribe a mimirs@^1.

¿«command not found: bunx» o el servidor no arranca (aunque bunx funciona en tu terminal)? Los editores lanzados desde el Dock o un lanzador de escritorio no cargan el perfil de tu shell, así que ~/.bun/bin no está en su PATH. Usa la ruta absoluta de which bunx como command en lugar del simple bunx en los fragmentos siguientes. bunx mimirs init escribe la ruta absoluta automáticamente (vuelve a ejecutarlo para corregir una configuración existente), y bunx mimirs doctor detecta el problema.

{
  "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 lee los servidores MCP desde tu directorio personal, no desde el proyecto. La variante del plugin de JetBrains usa ~/.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"
      }
    }
  }
}

El Copilot de VS Code usa un mapa servers (no mcpServers) y un campo type.

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

Codex usa TOML, no JSON, y lee de ~/.codex/config.toml. Un bloque por proyecto: elige un nombre de tabla único si conectas varios repositorios (mimirs-frontend, mimirs-api, etc).

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

O, de forma equivalente, con una tabla de entorno expandida:

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

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

Si el proyecto está en un montaje de solo lectura, configura RAG_DB_DIR en una ubicación con permiso de escritura. El índice se guardará allí en lugar de en <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. Primer índice

El servidor MCP indexa de forma diferida en la primera consulta, así que una vez conectado puedes pedirle algo a tu agente directamente. Para forzar un índice completo desde el principio (útil en repositorios grandes):

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

5. Prueba la demo (opcional)

bunx mimirs demo

Related MCP server: codeix

Flujo de trabajo manual (sin init)

init es una conveniencia: conecta tu editor (config MCP, reglas de agente, .gitignore, .mimirs/config.json). No construye el índice, y nada de lo siguiente lo necesita: el índice y una configuración por defecto se crean automáticamente la primera vez que indexas o consultas.

1. Añade el servidor MCP a mano. Copia el fragmento de tu cliente de la referencia manual de arriba: command: "bunx", args: ["mimirs@^1", "serve"] y RAG_PROJECT_DIR apuntando a la raíz de tu proyecto. Esa es toda la configuración MCP.

Sin init no hay archivo de reglas de agente, así que tu asistente no sabrá que las herramientas existen. Menciona mimirs en tu prompt o copia la lista de herramientas de CLAUDE.md en las reglas de tu editor.

2. Construye el índice. El servidor MCP indexa de forma diferida en la primera llamada a una herramienta, así que a través de un agente puedes omitir este paso. Para indexar de antemano (recomendado en repositorios grandes y necesario antes del search/read de la CLI de abajo):

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 se requiere init ni archivo de configuración: se aplican los valores por defecto y el índice se escribe en <project>/.mimirs/.

3. Consulta desde la CLI. Dos comandos de lectura, ambos ejecutándose contra el índice del directorio actual (usa --dir para apuntar a otro lugar):

# 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

Acota el alcance con --ext .ts,.tsx, --in src,packages/core o --exclude tests. Nota: el search/read de la CLI no se autoindexan: ejecuta mimirs index primero (solo el servidor MCP indexa bajo demanda).

Plugin de Claude Code

Para una integración más profunda, mimirs también está disponible como plugin de Claude Code. En una sesión de Claude Code:

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

El plugin conecta el servidor MCP, tres hooks — SessionStart (resumen de contexto), PostToolUse (reindexado automático al editar), SessionEnd (checkpoint automático) — y un conjunto de skills de flujo de trabajo que orquestan las herramientas para tareas habituales: explore, plan, review, debug, research, recall, catch-up, handoff, doc-gaps, scout y wiki.

¿Quieres las skills sin el plugin? Son simples archivos SKILL.md en skills/. Copia las que quieras en .claude/skills/<name>/ de tu proyecto (compartidas con el repositorio) o en ~/.claude/skills/<name>/ (todos tus proyectos) y Claude Code las detectará en la próxima sesión. Las skills son una función de Claude Code, así que no se aplican a otros editores — pero las herramientas MCP en sí funcionan en todas partes.

Calidad de búsqueda

89–97% Recall@10, 97–100% Recall@20, MRR 0.69–0.77. Evaluado en cuatro bases de código reales en tres lenguajes con conjuntos de consultas estratificados y de dificultad mixta (72–120 consultas cada uno, ~⅓ difíciles), re-medido el 2026-06-04 con el pipeline actual. Metodología completa en BENCHMARKS.md.

Los repositorios más grandes (Kubernetes, Excalidraw) son lo bastante grandes como para que algunos archivos correctos queden justo después del top-10; el recall alcanza el 97–100% en el top-20, así que configura searchTopK: 15–20 en repositorios grandes.

vs. agentes de codificación (ContextBench)

También ejecutamos mimirs en ContextBench (recuperación de contexto de referencia en repositorios reales), cuyos otros participantes son agentes de codificación completos — exploradores de varios pasos —, no herramientas de una sola llamada. Dada una consulta centrada (lo que un LLM envía tras leer el issue), una sola llamada de recuperación de mimirs se posiciona así frente a trayectorias completas de agentes:

mimirs lidera ambas métricas de cobertura con una sola llamada. La precisión de archivos es la última a propósito: perder un archivo gold es fatal (el LLM nunca ve el código que debe corregir), mientras que una referencia extra a un archivo es barata de filtrar — por eso mimirs maximiza el recall y deja que el modelo haga el pase de precisión. Y esa baja precisión de archivos es en su mayor parte un artefacto de la métrica: ~86% de los archivos no gold que devuelve mimirs son contexto relevante acoplado a la corrección (callers, tipos, implementaciones hermanas), no ruido — medido contra el gold la precisión es 0.19, contra la relevancia es 0.87.

El mismo recall, a una fracción del coste. Cara a cara contra un agente que solo usa grep (issue en bruto, sin índice, sin espiar la corrección) localizando los mismos 15 issues: mimirs entrega el clúster relevante en una llamada de ~15 ms con cero tokens de LLM; el agente necesitó ~11.5 llamadas a herramientas por issue (cada una un paso de LLM) para converger — y se detuvo en el archivo principal. En correcciones de varios archivos, el agente alcanzó el 22% de los archivos gold; mimirs, el 56% en esa única llamada — el grafo de dependencias saca a la luz los archivos secundarios que el issue nunca nombra.

Muestra de n=15 frente al conjunto de 500 de los agentes — orientativo; las llamadas a herramientas de los agentes son autodeclaradas y con tope. Clasificaciones completas, advertencias y tablas de relevancia + coste en BENCHMARKS.md.

Comparativa

¿Por qué no una herramienta existente?

• El @codebase de Continue.dev — la superposición más cercana (RAG local, código abierto), pero la recuperación vive dentro de la extensión del editor. Mimirs es un servidor MCP independiente con herramientas explícitas (search, read_relevant, project_map, search_conversation, annotate) alrededor de las cuales el agente puede planificar, además de seguimiento de conversación y un generador de wiki integrado.

• El repo-map de Aider — resumen estático de tree-sitter del repositorio, sin embeddings. Ingenioso y ligero, pero un resumen no es recuperación: mimirs clasifica fragmentos por consulta con vector + BM25 y los potencia por centralidad de grafo.

• Sourcegraph Cody / OpenCtx — excelentes en búsqueda de código, pero la indexación depende de infraestructura en la nube y una cuenta. Mimirs está a un bunx de distancia y nunca sale de tu máquina.

• llama-index / LangChain / hazlo tú mismo — esas son bibliotecas. Mimirs viene con todo incluido: fragmentación consciente de AST, recuperación híbrida, vigilancia de archivos, seguimiento de conversación y anotaciones ya conectadas.

Cómo funciona

1. Analizar y fragmentar — Divide el contenido usando estrategias según el tipo: límites de funciones/clases para código (mediante tree-sitter en 24 idiomas), encabezados para markdown, claves de nivel superior para YAML/JSON. Los fragmentos que superan el límite de tokens del modelo de embeddings se dividen en ventanas y se fusionan.

2. Incrustar — Cada fragmento se convierte en un vector de 384 dimensiones usando all-MiniLM-L6-v2 (en proceso mediante Transformers.js + ONNX, sin llamadas a API). Los vectores se almacenan en sqlite-vec.

3. Construir grafo de dependencias — Los especificadores de importación y los símbolos exportados se capturan durante la fragmentación AST y luego se resuelven para construir un grafo de dependencias a nivel de archivo y un grafo de llamadas a nivel de símbolo. impact recorre los llamadores transitivos de una función (radio de explosión + pruebas a ejecutar); trace encuentra cómo un símbolo llega a otro; la CLI mimirs affected convierte un git diff en el conjunto exacto de pruebas a ejecutar.

4. Búsqueda híbrida — Las consultas ejecutan similitud vectorial y BM25 en paralelo, combinadas por fusión de rango recíproco (ponderada, por defecto 0.5), robusta a las escalas de puntuación muy diferentes de los dos evaluadores. Los identificadores se dividen (camelCase/snake_case) para que una búsqueda de depends coincida con getDependsOn. Luego, los resultados se potencian por centralidad del grafo de dependencias y heurísticas de ruta. read_relevant devuelve fragmentos individuales con nombres de entidad y rangos de línea exactos (path:start-end).

5. Vigilar y reindexar — Los cambios de archivo se detectan con un debounce de 2 segundos. Los archivos modificados se reindexan; los archivos eliminados se podan.

6. Conversación y puntos de control — Sigue las transcripciones JSONL de Claude Code en tiempo real. Los agentes pueden crear puntos de control en momentos importantes para que futuras sesiones los busquen.

7. Anotaciones — Las notas adjuntas a archivos o símbolos aparecen como bloques [NOTE] en línea en los resultados de read_relevant.

8. Analíticas — Cada consulta se registra. Las analíticas muestran consultas sin resultados, consultas de baja relevancia y tendencias periódicas.

Manejo de datos

mimirs se ejecuta enteramente en tu máquina. Indexa los archivos que tu repositorio rastrea, además de los archivos no rastreados pero no ignorados por git (por lo que un .env que olvidaste añadir a .gitignore podría leerse; los patrones de secretos comunes como .env, *.pem, *.key y las claves SSH están excluidos por defecto; añade los tuyos a exclude en .mimirs/config.json). El contenido de los archivos y los embeddings se almacenan en <project>/.mimirs/index.db, un archivo SQLite local. La indexación de conversaciones solo lee las transcripciones del proyecto actual en ~/.claude/projects/<this-project>/.

La única llamada de red es la descarga única del modelo de embeddings (Xenova/all-MiniLM-L6-v2) desde huggingface.co, almacenado en caché en ~/.cache/mimirs/models. Tu código nunca sale de tu máquina: no se envía nada a ningún servidor.

Idiomas admitidos

Fragmentación consciente de AST mediante bun-chunk con gramáticas de 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

También indexa: Markdown, JSON, XML, SQL, GraphQL, Protobuf, Terraform, Dockerfiles, Makefiles y más. Los archivos sin una extensión conocida recurren a la división en párrafos.

Documentación

• Ejemplos de salidas de herramientas — lo que tu agente realmente recibe a través de MCP

• Herramientas MCP, CLI y analíticas

• Configuración y ejemplos

• Puntos de referencia

Stack

Todos los datos viven en .mimirs/ dentro de tu proyecto: añádelo a .gitignore.