Alcove

Alcove es un servidor MCP que proporciona a los agentes de codificación de IA acceso bajo demanda a los documentos de tus proyectos privados, sin volcar todo en la ventana de contexto, sin filtrar documentos en repositorios públicos y sin necesidad de una configuración por proyecto para cada agente que utilices.

Demo

Claude, Gemini, Codex — buscar · cambiar de proyecto · búsqueda global · validar y generar. Una sola configuración.

alcove search · cambio de proyecto · --scope global · alcove validate

El problema

Tienes dos malas opciones.

Opción A: Poner los documentos en CLAUDE.md / AGENTS.md Cada archivo se inyecta en la ventana de contexto en cada ejecución. Funciona para convenciones cortas. Falla con documentos de proyectos reales. 10 archivos de arquitectura = exceso de contexto = respuestas más lentas, costosas y menos precisas.

Opción B: No incluir los documentos Tu agente inventa requisitos que ya habías documentado. Ignora las restricciones de decisiones que ya habías tomado. Te pide que expliques las mismas cosas en cada sesión.

Ninguna de las opciones escala. Ahora multiplícalo por 5 proyectos y 3 agentes, cada uno configurado de forma diferente. Cada vez que cambias, pierdes el contexto.

Cómo lo soluciona Alcove

Alcove no inyecta tus documentos. Los agentes buscan lo que necesitan, cuando lo necesitan.

~/projects/my-app $ claude "how is auth implemented?"

  → Alcove detects project: my-app
  → BM25 search: "auth" → ARCHITECTURE.md (score: 0.94), DECISIONS.md (score: 0.71)
  → Agent gets the 2 most relevant docs, not all 12

~/projects/my-api $ codex "review the API design"

  → Alcove detects project: my-api
  → Same doc structure, same access pattern
  → Different project, zero reconfiguration

Cambia de agente cuando quieras. Cambia de proyecto cuando quieras. La capa de documentos permanece estandarizada.

La división correcta

CLAUDE.md / AGENTS.md es para el comportamiento del agente: errores repetidos que evitar, convenciones de codificación e instrucciones específicas de la sesión. Mantenlo por debajo de las 200 líneas.

Alcove es para el conocimiento del proyecto: arquitectura, decisiones, manuales operativos, documentación de API y cualquier otra cosa que tu agente necesite entender, pero no necesariamente en cada ejecución.

El patrón:

CLAUDE.md | AGENTS.md                             ← agent rules, coding conventions, recurring corrections
~/.config/alcove/docs/my-app/
  ARCHITECTURE.md                      ← tech stack, data model, system design
  DECISIONS.md                         ← why X was chosen over Y
  DEBT.md                              ← known issues, workarounds
  ...                                  ← agent searches here when it needs context

Los agentes llaman a search_project_docs("auth flow") y obtienen los 2 documentos más relevantes, no los 12. Nada llega a la ventana de contexto a menos que sea realmente necesario.

Por qué Alcove

¿Por qué no usar simplemente CLAUDE.md? Las convenciones cortas y los comportamientos del agente pertenecen allí. La documentación del proyecto (arquitectura, decisiones, manuales operativos, PRD) no escala en un archivo de contexto. Alcove no es un reemplazo; es la capa que CLAUDE.md nunca debió ser.

Inicio rápido

# macOS
brew install epicsagas/alcove/alcove

# Linux / Windows — pre-built binary (fast, no compilation)
cargo install cargo-binstall
cargo binstall alcove

# Any platform — build from source
cargo install alcove

# Clone and build
git clone https://github.com/epicsagas/alcove.git
cd alcove
make install

alcove setup

Nota: Hay binarios precompilados disponibles para Linux (x86_64), macOS (Apple Silicon e Intel) y Windows.

setup te guía a través de todo de forma interactiva:

1. Dónde viven tus documentos

2. Qué categorías de documentos rastrear

3. Formato de diagrama preferido

4. Qué agentes de IA configurar (MCP + archivos de habilidades)

Vuelve a ejecutar alcove setup en cualquier momento para cambiar la configuración. Recuerda tus elecciones anteriores.

Cómo funciona

flowchart LR
    subgraph Projects["Your projects"]
        A1["my-app/\n  src/ ..."]
        A2["my-api/\n  src/ ..."]
    end

    subgraph Docs["Your private docs (one repo)"]
        D1["my-app/\n  PRD.md\n  ARCH.md"]
        D2["my-api/\n  PRD.md\n  ..."]
        P1["policy.toml"]
    end

    subgraph Agents["Any MCP agent"]
        AG["Claude Code · Cursor\nGemini CLI · Codex · Copilot\n+4 more"]
    end

    subgraph MCP["Alcove MCP server"]
        T["search · get_file\noverview · audit\ninit · validate"]
    end

    A1 -- "CWD detected" --> D1
    A2 -- "CWD detected" --> D2
    Agents -- "stdio MCP" --> MCP
    MCP -- "scoped access" --> Docs

Tus documentos están organizados en un directorio separado (DOCS_ROOT), una carpeta por proyecto. Alcove gestiona los documentos allí y los sirve a cualquier agente de IA compatible con MCP a través de stdio. Tu agente llama a herramientas como search_project_docs("auth flow") y obtiene resultados clasificados y específicos del proyecto, independientemente del agente que estés usando.

Qué hace

• Recuperación de documentos bajo demanda — los agentes buscan y recuperan; nada se precarga en el contexto

• Búsqueda clasificada BM25 — búsqueda de texto completo rápida impulsada por tantivy; los documentos más relevantes primero, indexación automática, recurre a grep

• Un repositorio de documentos, múltiples proyectos — documentos privados organizados por proyecto, gestionados en un solo lugar

• Una configuración, cualquier agente — configura una vez, cada agente compatible con MCP obtiene el mismo acceso

• Detecta automáticamente tu proyecto desde CWD — no se necesita configuración por proyecto

• Acceso con alcance — cada proyecto solo ve sus propios documentos

• Búsqueda entre proyectos — busca en todos los proyectos a la vez con scope: "global"

• Los documentos privados permanecen privados — los documentos nunca tocan tu repositorio público, se ejecutan completamente en tu máquina a través de stdio

• Estructura de documentos estandarizada — policy.toml aplica documentos consistentes en todos los proyectos y equipos

• Auditoría entre repositorios — encuentra documentos internos extraviados en el repositorio de tu proyecto, sugiere correcciones

• Validación de documentos — comprueba archivos faltantes, plantillas sin rellenar, secciones requeridas

• Funciona con más de 9 agentes — Claude Code, Cursor, Claude Desktop, Cline, OpenCode, Codex, Copilot, Antigravity, Gemini CLI

Herramientas MCP

CLI

alcove              Start MCP server (agents call this)
alcove setup        Interactive setup — re-run anytime to reconfigure
alcove doctor       Check the health of your alcove installation
alcove validate     Validate docs against policy (--format json, --exit-code)
alcove index        Build or rebuild the full-text search index for ranked search
alcove search       Search docs from the terminal
alcove uninstall    Remove skills, config, and legacy files

Búsqueda

Alcove elige automáticamente la mejor estrategia de búsqueda. Cuando existe el índice de búsqueda, utiliza búsqueda clasificada BM25 (impulsada por tantivy) para obtener resultados con puntuación de relevancia. Cuando no existe, recurre a grep. Nunca tienes que pensar en ello.

# Search the current project (auto-detected from CWD)
alcove search "authentication flow"

# Force grep mode if you want exact substring matching
alcove search "FR-023" --mode grep

El índice se construye automáticamente en segundo plano cuando se inicia el servidor MCP y se reconstruye cuando detecta cambios en los archivos. Sin trabajos cron, sin pasos manuales.

Cómo funciona para los agentes: los agentes simplemente llaman a search_project_docs con una consulta. Alcove se encarga del resto: clasificación, deduplicación (un resultado por archivo), búsqueda entre proyectos y alternativa. El agente nunca necesita elegir un modo de búsqueda.

Búsqueda global

Cada decisión de arquitectura, cada manual operativo, cada nota de proyecto: buscable en todos tus proyectos a la vez.

# Search across ALL projects
alcove search "rate limiting patterns" --scope global
alcove search "OAuth token refresh" --scope global

Los agentes pueden hacer lo mismo con scope: "global" en search_project_docs. Una consulta, cada proyecto.

Detección de proyectos

Por defecto, Alcove detecta el proyecto actual desde el directorio de trabajo de tu terminal (CWD). Puedes anular esto con la variable de entorno MCP_PROJECT_NAME:

MCP_PROJECT_NAME=my-api alcove

Esto es útil cuando tu CWD no coincide con un nombre de proyecto en tu repositorio de documentos.

Política de documentos

Define estándares de documentación para todo el equipo con policy.toml en tu repositorio de documentos:

[policy]
enforce = "strict"    # strict | warn

[[policy.required]]
name = "PRD.md"
aliases = ["prd.md", "product-requirements.md"]

[[policy.required]]
name = "ARCHITECTURE.md"

  [[policy.required.sections]]
  heading = "## Overview"
  required = true

  [[policy.required.sections]]
  heading = "## Components"
  required = true
  min_items = 2

Los archivos de política se resuelven con prioridad: proyecto (<project>/.alcove/policy.toml) > equipo (DOCS_ROOT/.alcove/policy.toml) > predeterminado integrado (desde tus archivos principales config.toml). Esto garantiza una calidad de documento consistente en todos tus proyectos, al tiempo que permite anulaciones por proyecto.

Clasificación de documentos

Alcove clasifica los documentos en niveles:

La herramienta audit escanea tanto tu repositorio de documentos como el directorio del proyecto local, luego sugiere acciones, como generar un README público a partir de tu PRD privado, o devolver informes extraviados a Alcove.

Configuración

La configuración vive en ~/.config/alcove/config.toml:

docs_root = "/Users/you/documents"

[core]
files = ["PRD.md", "ARCHITECTURE.md", "PROGRESS.md", "DECISIONS.md", "CONVENTIONS.md", "SECRETS_MAP.md", "DEBT.md"]

[team]
files = ["ENV_SETUP.md", "ONBOARDING.md", "DEPLOYMENT.md", "TESTING.md", ...]

[public]
files = ["README.md", "CHANGELOG.md", "CONTRIBUTING.md", "SECURITY.md", ...]

[diagram]
format = "mermaid"

Todo esto se establece de forma interactiva mediante alcove setup. También puedes editar el archivo directamente.

Las listas de archivos son totalmente personalizables: añade cualquier nombre de archivo a cualquier categoría, o mueve archivos entre categorías para que coincidan con el flujo de trabajo de tu equipo:

[core]
files = ["PRD.md", "ARCHITECTURE.md", "DECISIONS.md", "MY_SPEC.md"]  # added custom doc

[public]
files = ["README.md", "CHANGELOG.md", "PRD.md"]  # PRD exposed as public for this project

Agentes compatibles

Los agentes con soporte de habilidades activan Alcove automáticamente cuando preguntas sobre la arquitectura del proyecto, convenciones, decisiones o estado. También se pueden invocar explícitamente:

/alcove                          Summarize current project docs and status
/alcove search auth flow         Search docs for a specific topic
/alcove what conventions apply?  Ask a doc question directly

Idiomas compatibles

La CLI detecta automáticamente la configuración regional de tu sistema. También puedes anularla con la variable de entorno ALCOVE_LANG.

# Override language
ALCOVE_LANG=ko alcove setup

Actualización

# Homebrew
brew upgrade epicsagas/alcove/alcove

# cargo-binstall
cargo binstall alcove

# From source
cargo install alcove

Desinstalación

alcove uninstall          # remove skills & config
cargo uninstall alcove    # remove binary

Ecosistema

obsidian-forge

Alcove se combina naturalmente con obsidian-forge, un generador de bóvedas de Obsidian y demonio de automatización. Usa obsidian-forge para construir y fortalecer tu grafo de conocimiento en Obsidian, luego apunta el DOCS_ROOT de alcove a la bóveda: tus agentes de IA obtienen una búsqueda clasificada y con alcance sobre toda tu base de conocimiento personal sin ningún exceso de contexto.

Contribución

Las notificaciones de errores, solicitudes de funciones y solicitudes de extracción son bienvenidas. Por favor, abre un issue en GitHub para iniciar una discusión.

Licencia

Apache-2.0