Docdex

Convierte tu repositorio en un contexto rápido y privado en el que los humanos y la IA pueden confiar.

Docdex es un demonio de búsqueda e indexador local para documentación y código fuente. Se sitúa entre tus archivos sin procesar y tu asistente de IA, proporcionando búsqueda determinista, inteligencia de código y memoria persistente sin necesidad de subir nunca tu código a un almacén vectorial en la nube.

⚡ ¿Por qué Docdex?

La mayoría de las herramientas de IA dependen de "grep" (rápido pero limitado) o RAG alojado (lento y requiere subidas). Docdex se ejecuta localmente, entiende la estructura del código y proporciona a tus agentes de IA una memoria persistente.

Related MCP server: mcp-server-tree-sitter

🚀 Características

• 📚 Indexación de documentos: Clasifica y resume la documentación del repositorio al instante.

• 🧠 AST y Grafo de impacto: Busca por intención de función y rastrea dependencias descendentes (compatible con Rust, Python, JS/TS, Go, Java, C++, y más).

• 💾 Memoria del repositorio: Almacena hechos, decisiones y notas del proyecto localmente.

• 👤 Memoria del agente: Recuerda las preferencias del usuario (p. ej., "Usa viñetas concisas") en diferentes repositorios.

• 🗂️ Memoria de conversación: Importa transcripciones, mantiene compactos los paquetes de reactivación y deriva resúmenes, entradas de diario y memoria de trabajo con alcance de repositorio.

• 🕸️ Grafo de conocimiento temporal: Extrae entidades, bordes, episodios y enlaces orientados al código de conversaciones archivadas para consultas de línea de tiempo y vecindario.

• 🧭 Contexto de reactivación + Mapa del proyecto: Inyecta paquetes de reactivación compactos, verdad de perfil y contexto de Project map: en caché en completados de chat compatibles con OpenAI.

• 🔌 Nativo de MCP: Se autoconfigura para herramientas como Claude Desktop, Cursor y Windsurf.

• 🌐 Enriquecimiento web: Búsqueda web opcional con filtrado de LLM local (vía Ollama).

📦 Instalación "configurar y olvidar"

Instálalo una vez, apunta tu agente a Docdex y seguirá funcionando en segundo plano.

1. Instalación vía npm (Recomendado)

Requiere Node.js >= 18. Esto descargará el binario correcto para tu sistema operativo (macOS, Linux, Windows).

npm i -g docdex

2. Autoconfiguración

Si tienes instalado alguno de los siguientes clientes, Docdex los configura automáticamente para usar el punto final MCP local (demonio HTTP/SSE):

Claude Desktop, Cursor, Windsurf, Cline, Roo Code, Continue, VS Code, PearAI, Void, Zed, Codex.

Nota: Reinicia tu cliente de IA después de la instalación.

🛠️ Flujo de trabajo de uso

1. Indexar un repositorio

Ejecuta esto una vez para construir el índice y los datos del grafo.

docdexd index --repo /path/to/my-project

2. Iniciar el demonio

Inicia el servidor compartido. Esto maneja las solicitudes HTTP y las conexiones MCP.

docdex start
# or: docdexd daemon --host 127.0.0.1 --port 28491

3. Hacer preguntas (CLI)

Puedes chatear directamente desde la terminal.

docdexd chat --repo /path/to/my-project --query "how does auth work?"

🔌 Protocolo de contexto de modelo (MCP)

Docdex está diseñado para ser el "cerebro" de tus agentes de IA. Expone un punto final MCP al que se conectan los agentes.

Arquitectura

flowchart LR
  Repo[Repo on disk] --> Indexer[Docdex Indexer]
  Indexer --> Daemon[Docdex Daemon]
  Daemon -->|HTTP + SSE| MCPClient[MCP Client]
  MCPClient --> Host[AI Agent / Editor]

Utiliza el punto final HTTP/SSE del demonio. Para clientes en entorno aislado (sandboxed), Docdex también puede servir MCP a través de IPC local (socket Unix o tubería con nombre de Windows), mientras que HTTP/SSE sigue siendo el predeterminado para la mayoría de los clientes MCP.

Configuración manual

Si necesitas configurar tu cliente manualmente:

JSON (Claude/Cursor/Continue):

{
  "mcpServers": {
    "docdex": {
      "url": "http://127.0.0.1:28491/v1/mcp/sse"
    }
  }
}

JSON de Claude Code (CLI) (~/.claude.json o .mcp.json del proyecto):

{
  "mcpServers": {
    "docdex": {
      "type": "http",
      "url": "http://127.0.0.1:28491/v1/mcp"
    }
  }
}

TOML (Codex):

[mcp_servers.docdex]
url = "http://127.0.0.1:28491/v1/mcp"
tool_timeout_sec = 300
startup_timeout_sec = 300

🤖 Capacidades y ejemplos

1. AST y análisis de impacto

No solo encuentres la cadena "addressGenerator"; encuentra la definición y lo que impacta.

# Find definition
curl "http://127.0.0.1:28491/v1/ast?name=addressGenerator&pathPrefix=src"

# Track downstream impact (what breaks if I change this?)
curl "http://127.0.0.1:28491/v1/graph/impact?file=src/app.ts&maxDepth=3"

2. Sistema de memoria

Docdex te permite almacenar "hechos" que la recuperación ayuda a recordar más tarde.

Memoria del repositorio (específica del proyecto):

# Teach the repo a fact
docdexd memory-store --repo . --text "Payments retry up to 3 times with backoff."

# Recall it later
docdexd memory-recall --repo . --query "payments retry policy"

Memoria del agente (preferencia del usuario):

# Set a style preference
docdexd profile add --agent-id "default" --category style --content "Use concise bullet points."

3. Memoria de conversación

La memoria de conversación tiene alcance de repositorio por defecto y es opcional. Las sesiones sin repositorio deben usar un espacio de nombres de conversación explícito para que nunca reutilicen silenciosamente un archivo de repositorio. El subsistema importa transcripciones, almacena resúmenes episódicos y memoria de trabajo, deriva entradas de diario y hechos de KG temporales en knowledge.db, y mantiene la recuperación bajo un estricto presupuesto de reactivación.

Los comandos de archivo, diario y hook de la CLI son envoltorios respaldados por HTTP, así que inicia docdex start o docdexd daemon primero.

# Archive and inspect transcripts
docdexd conversations import --repo . ./session.txt --format plain_text --agent-id codex
docdexd conversations list --repo . --agent-id codex
docdexd conversations search --repo . "timeline_index"
docdexd conversations read --repo . <session_id>

# Import into an explicit global conversation namespace instead of a repo archive
docdexd conversations import --conversation-namespace shared-team ./session.txt --format plain_text --agent-id codex
docdexd conversations search --conversation-namespace shared-team "timeline_index"

# Keep agent diary notes alongside imported sessions
docdexd diary write --repo . --agent-id codex "Wake-up rollout validated against knowledge.db timeline output."
docdexd diary read --repo . --agent-id codex

# Trigger durable summarization from an external transcript
docdexd hook conversation --repo . \
  --action session_close_summarization \
  --source codex \
  --agent-id codex \
  --transcript ./session.txt \
  --format plain_text \
  --wait-for-processing

# Build a compact wake-up bundle over recent context
curl -X POST http://127.0.0.1:28491/v1/wakeup \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"codex","query":"timeline_index","max_tokens":96}'

# Address the same archive over HTTP without repo_id
curl -X POST http://127.0.0.1:28491/v1/wakeup \
  -H "Content-Type: application/json" \
  -H "x-docdex-conversation-namespace: shared-team" \
  -d '{"agent_id":"codex","query":"timeline_index","max_tokens":96}'

# Explore derived repo-scoped knowledge facts and provenance
curl "http://127.0.0.1:28491/v1/kg/query?q=knowledge.db&limit=10"
curl "http://127.0.0.1:28491/v1/kg/search/nodes?q=knowledge&limit=10"
curl "http://127.0.0.1:28491/v1/kg/neighborhood?entity=knowledge.db&limit=10"
curl "http://127.0.0.1:28491/v1/kg/timeline?entity=knowledge.db&limit=10"

# Chat with wake-up + project-map context and inspect reasoning trace metadata
curl -X POST http://127.0.0.1:28491/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "fake-model",
    "messages": [{"role": "user", "content": "What changed around knowledge.db?"}],
    "docdex": {
      "agent_id": "codex",
      "limit": 6,
      "include_libs": true,
      "dag_session_id": "session-123"
    }
  }'

4. LLM local (Ollama)

Docdex utiliza Ollama para incrustaciones (embeddings) y chat local opcional.

• Configuración: Ejecuta docdex setup para un asistente interactivo.

• Manual: Asegúrate de que nomic-embed-text esté descargado en Ollama (ollama pull nomic-embed-text).

• URL personalizada:

DOCDEX_OLLAMA_BASE_URL=http://127.0.0.1:11434 docdex start --host 127.0.0.1 --port 28491

⚙️ Configuración y API HTTP

Docdex se ejecuta como un demonio local que sirve:

• Comandos CLI: docdexd chat

• API HTTP: /search, /v1/capabilities, /v1/search/rerank, /v1/search/batch, /v1/chat/completions, /v1/ast, /v1/graph/impact, /v1/conversations/*, /v1/diary/*, /v1/hooks/conversation, /v1/wakeup, /v1/kg/*

• Puntos finales MCP: /v1/mcp y /v1/mcp/sse

• Herramientas de negociación de capacidades: docdex_capabilities, docdex_rerank, docdex_batch_search, docdex_conversation_*, docdex_diary_*, docdex_conversation_hook, docdex_wakeup, docdex_kg_*

Configuración multi-repositorio

Ejecuta un solo demonio y monta repositorios adicionales bajo demanda.

docdex start --port 28491

# Mount repos and capture repo_id values
curl -X POST "http://127.0.0.1:28491/v1/initialize" \
  -H "Content-Type: application/json" \
  -d '{"rootUri":"file:///path/to/repo-a"}'

curl -X POST "http://127.0.0.1:28491/v1/initialize" \
  -H "Content-Type: application/json" \
  -d '{"rootUri":"file:///path/to/repo-b"}'

Notas:

• Cuando se monta más de un repositorio (o el demonio inicia sin un repositorio predeterminado), incluye x-docdex-repo-id: <sha256> en las solicitudes HTTP.

• Las sesiones MCP se vinculan al repositorio proporcionado en initialize.rootUri y reutilizan ese repositorio automáticamente.

Seguridad

• Modo seguro: Por defecto, Docdex aplica TLS en enlaces que no son de loopback.

• Loopback: 127.0.0.1 es accesible sin TLS para agentes locales.

• Para exponer a una red (usar con precaución), utiliza --expose y --auth-token.

📚 Aprende más

• Uso detallado: docs/usage.md

• Referencia de API: docs/http_api.md

• Especificaciones MCP: docs/mcp/errors.md