Docdex

Verwandeln Sie Ihr Repository in schnellen, privaten Kontext, dem Menschen und KI vertrauen können.

Docdex ist ein Local-First-Indexer und Such-Daemon für Dokumentationen und Quellcode. Er fungiert als Schnittstelle zwischen Ihren Rohdateien und Ihrem KI-Assistenten und bietet deterministische Suche, Code-Intelligenz und persistenten Speicher, ohne jemals Ihren Code in einen Cloud-Vektor-Speicher hochzuladen.

⚡ Warum Docdex?

Die meisten KI-Tools verlassen sich auf "grep" (schnell, aber dumm) oder gehostetes RAG (langsam und erfordert Uploads). Docdex läuft lokal, versteht die Codestruktur und gibt Ihren KI-Agenten ein persistentes Gedächtnis.

Related MCP server: mcp-server-tree-sitter

🚀 Funktionen

• 📚 Dokumenten-Indexierung: Dokumentation des Repos sofort ranken und zusammenfassen.

• 🧠 AST & Impact Graph: Suche nach Funktionsabsicht und Verfolgung nachgelagerter Abhängigkeiten (unterstützt Rust, Python, JS/TS, Go, Java, C++ und mehr).

• 💾 Repo-Gedächtnis: Speichert Projektfakten, Entscheidungen und Notizen lokal.

• 👤 Agenten-Gedächtnis: Merkt sich Benutzerpräferenzen (z. B. "Verwende prägnante Aufzählungspunkte") über verschiedene Repositories hinweg.

• 🗂️ Konversations-Gedächtnis: Importiert Transkripte, hält Wake-up-Bundles kompakt und leitet repo-spezifische Zusammenfassungen, Tagebucheinträge und Arbeitsspeicher ab.

• 🕸️ Temporaler Wissensgraph: Extrahiert Entitäten, Kanten, Episoden und code-bezogene Links aus archivierten Konversationen für Zeitlinien- und Umgebungsabfragen.

• 🧭 Wake-Up + Projektkarten-Kontext: Injiziert kompakte Wake-up-Bundles, Profilwahrheiten und zwischengespeicherten Project map:-Kontext in OpenAI-kompatible Chat-Vervollständigungen.

• 🔌 MCP Native: Automatische Konfiguration für Tools wie Claude Desktop, Cursor und Windsurf.

• 🌐 Web-Anreicherung: Optionale Websuche mit lokaler LLM-Filterung (via Ollama).

📦 Installieren und vergessen

Einmal installieren, Ihren Agenten auf Docdex verweisen, und es arbeitet im Hintergrund weiter.

1. Installation via npm (Empfohlen)

Erfordert Node.js >= 18. Dies lädt die korrekte Binärdatei für Ihr Betriebssystem (macOS, Linux, Windows) herunter.

npm i -g docdex

2. Automatische Konfiguration

Wenn Sie einen der folgenden Clients installiert haben, konfiguriert Docdex diese automatisch für die Verwendung des lokalen MCP-Endpunkts (Daemon HTTP/SSE):

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

Hinweis: Starten Sie Ihren KI-Client nach der Installation neu.

🛠️ Arbeitsablauf

1. Ein Repository indexieren

Führen Sie dies einmal aus, um den Index und die Graphdaten zu erstellen.

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

2. Den Daemon starten

Starten Sie den gemeinsamen Server. Dieser verarbeitet HTTP-Anfragen und MCP-Verbindungen.

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

3. Fragen stellen (CLI)

Sie können direkt vom Terminal aus chatten.

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

🔌 Model Context Protocol (MCP)

Docdex wurde als "Gehirn" für Ihre KI-Agenten entwickelt. Es stellt einen MCP-Endpunkt bereit, mit dem sich Agenten verbinden.

Architektur

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

Verwenden Sie den Daemon HTTP/SSE-Endpunkt. Für isolierte Clients kann Docdex MCP auch über lokales IPC (Unix-Socket oder Windows Named Pipe) bereitstellen, während HTTP/SSE der Standard für die meisten MCP-Clients bleibt.

Manuelle Konfiguration

Falls Sie Ihren Client manuell konfigurieren müssen:

JSON (Claude/Cursor/Continue):

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

Claude Code (CLI) JSON (~/.claude.json oder Projekt .mcp.json):

{
  "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

🤖 Fähigkeiten & Beispiele

1. AST & Impact-Analyse

Suchen Sie nicht nur nach dem String "addressGenerator"; finden Sie die Definition und was sie beeinflusst.

# 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. Gedächtnissystem

Docdex ermöglicht es Ihnen, "Fakten" zu speichern, die durch Abruf später leichter erinnert werden können.

Repo-Gedächtnis (Projektspezifisch):

# 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"

Agenten-Gedächtnis (Benutzerpräferenz):

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

3. Konversations-Gedächtnis

Das Konversations-Gedächtnis ist standardmäßig repo-spezifisch und optional. Sitzungen ohne Repo müssen einen expliziten Konversations-Namespace verwenden, damit sie niemals versehentlich ein Repo-Archiv wiederverwenden. Das Subsystem importiert Transkripte, speichert episodische Zusammenfassungen und Arbeitsspeicher, leitet Tagebucheinträge und temporale KG-Fakten in knowledge.db ab und hält den Abruf innerhalb eines strengen Wake-up-Budgets.

Die CLI-Befehle für Archiv, Tagebuch und Hooks sind HTTP-basierte Wrapper, starten Sie also zuerst docdex start oder docdexd daemon.

# 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. Lokales LLM (Ollama)

Docdex verwendet Ollama für Embeddings und optionalen lokalen Chat.

• Einrichtung: Führen Sie docdex setup für einen interaktiven Assistenten aus.

• Manuell: Stellen Sie sicher, dass nomic-embed-text in Ollama geladen ist (ollama pull nomic-embed-text).

• Benutzerdefinierte URL:

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

⚙️ Konfiguration & HTTP-API

Docdex läuft als lokaler Daemon und bietet:

• CLI-Befehle: docdexd chat

• HTTP-API: /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/*

• MCP-Endpunkte: /v1/mcp und /v1/mcp/sse

• Tools zur Fähigkeitsaushandlung: docdex_capabilities, docdex_rerank, docdex_batch_search, docdex_conversation_*, docdex_diary_*, docdex_conversation_hook, docdex_wakeup, docdex_kg_*

Multi-Repo-Einrichtung

Starten Sie einen einzelnen Daemon und mounten Sie bei Bedarf zusätzliche Repos.

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"}'

Hinweise:

• Wenn mehr als ein Repo gemountet ist (oder der Daemon ohne Standard-Repo startet), fügen Sie x-docdex-repo-id: <sha256> zu den HTTP-Anfragen hinzu.

• MCP-Sitzungen binden sich an das in initialize.rootUri angegebene Repo und verwenden dieses automatisch wieder.

Sicherheit

• Sicherer Modus: Standardmäßig erzwingt Docdex TLS bei Nicht-Loopback-Bindungen.

• Loopback: 127.0.0.1 ist ohne TLS für lokale Agenten zugänglich.

• Um das System für ein Netzwerk freizugeben (mit Vorsicht verwenden), nutzen Sie --expose und --auth-token.

📚 Mehr erfahren

• Detaillierte Nutzung: docs/usage.md

• API-Referenz: docs/http_api.md

• MCP-Spezifikationen: docs/mcp/errors.md