{
  "markdown": "[![Website](https://img.shields.io/badge/website-docdex.org-blue)](https://docdex.org)\n![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/bekirdag/docdex/release.yml?branch=main)\n![GitHub License](https://img.shields.io/github/license/bekirdag/docdex)\n![GitHub Release](https://img.shields.io/github/v/release/bekirdag/docdex)\n![Made with Rust](https://img.shields.io/badge/Made%20with-Rust-orange?logo=rust)\n\n# Docdex\n\n> **Turn your repository into fast, private context that humans and AI can trust.**\n\nDocdex is a **local-first indexer and search daemon** for documentation and source code. It sits between your raw files and your AI assistant, providing deterministic search, code intelligence, and persistent memory without ever uploading your code to a cloud vector store.\n\n## ⚡ Why Docdex?\n\nMost AI tools rely on \"grep\" (fast but dumb) or hosted RAG (slow and requires uploads). Docdex runs locally, understands code structure, and gives your AI agents a persistent memory.\n\n| Problem | Typical Approach | The Docdex Solution |\n| --- | --- | --- |\n| **Finding Context** | `grep`/`rg` (Noisy, literal matches) | **Ranked, structured results** based on intent. |\n| **Code Privacy** | Hosted RAG (Requires uploading code) | **Local-only indexing.** Your code stays on your machine. |\n| **Siloed Search** | IDE-only search bars | **Shared Daemon** serving CLI, HTTP, and MCP clients simultaneously. |\n| **Code Awareness** | String matching | **AST & Impact Graph** to understand dependencies and definitions. |\n\n---\n\n## 🚀 Features\n\n* **📚 Document Indexing:** Rank and summarize repo documentation instantly.\n* **🧠 AST & Impact Graph:** Search by function intent and track downstream dependencies (supports Rust, Python, JS/TS, Go, Java, C++, and more).\n* **💾 Repo Memory:** Stores project facts, decisions, and notes locally.\n* **👤 Agent Memory:** Remembers user preferences (e.g., \"Use concise bullet points\") across different repositories.\n* **🗂️ Conversation Memory:** Imports transcripts, keeps wake-up bundles compact, and derives repo-scoped summaries, diary entries, and working memory.\n* **🕸️ Temporal Knowledge Graph:** Extracts entities, edges, episodes, and code-facing links from archived conversations for timeline and neighborhood queries.\n* **🧭 Wake-Up + Project Map Context:** Injects compact wake-up bundles, profile truth, and cached `Project map:` context into OpenAI-compatible chat completions.\n* **🔌 MCP Native:** Auto-configures for tools like Claude Desktop, Cursor, and Windsurf.\n* **🌐 Web Enrichment:** Optional web search with local LLM filtering through detected local LLM services.\n\n---\n\n## 📦 Set-and-Forget Install\n\nInstall once, point your agent at Docdex, and it keeps working in the background.\n\n### 1. Install via npm (Recommended)\n\nRequires Node.js >= 18. This will download the correct binary for your OS (macOS, Linux, Windows).\n\n```bash\nnpm i -g docdex\n\n```\n\n> [!WARNING]\n> **Windows requirement:** Docdex uses the MSVC runtime. Install the **Microsoft Visual C++ Redistributable 2015-2022 (x64)** before running `docdex`/`docdexd`.\n> - Winget: `winget install --id Microsoft.VCRedist.2015+.x64`\n> - Manual: download `vc_redist.x64.exe` from Microsoft: https://aka.ms/vs/17/release/vc_redist.x64.exe\n> - If `docdexd` exits with `0xC0000135`, the runtime is missing.\n\n### 2. Auto-Configuration\n\nIf you have any of the following clients installed, Docdex automatically configures them to use the local MCP endpoint (daemon HTTP/SSE):\n\n> **Claude Desktop, Cursor, Windsurf, Cline, Roo Code, Continue, VS Code, PearAI, Void, Zed, Codex.**\n\n*Note: Restart your AI client after installation.*\n\n---\n\n## 🛠️ Usage Workflow\n\n### 1. Index a Repository\n\nRun this once to build the index and graph data.\n\n```bash\ndocdexd index --repo /path/to/my-project\n\n```\n\n### 2. Start the Daemon\n\nStart the shared server. This handles HTTP requests and MCP connections.\n\n```bash\ndocdex start\n# or: docdexd daemon --host 127.0.0.1 --port 28491\n\n```\n\n### 3. Ask Questions (CLI)\n\nYou can chat directly from the terminal.\n\n```bash\ndocdexd chat --repo /path/to/my-project --query \"how does auth work?\"\n\n```\n\n---\n\n## 🔌 Model Context Protocol (MCP)\n\nDocdex is designed to be the \"brain\" for your AI agents. It exposes an MCP endpoint that agents connect to.\n\n### Architecture\n\n```mermaid\nflowchart LR\n  Repo[Repo on disk] --> Indexer[Docdex Indexer]\n  Indexer --> Daemon[Docdex Daemon]\n  Daemon -->|HTTP + SSE| MCPClient[MCP Client]\n  MCPClient --> Host[AI Agent / Editor]\n\n```\n\nUse the daemon HTTP/SSE endpoint. For sandboxed clients, Docdex can also serve MCP over local IPC\n(Unix socket or Windows named pipe), while HTTP/SSE remains the default for most MCP clients.\n\n### Manual Configuration\n\nIf you need to configure your client manually:\n\n**JSON (Claude/Cursor/Continue):**\n\n```json\n{\n  \"mcpServers\": {\n    \"docdex\": {\n      \"url\": \"http://127.0.0.1:28491/v1/mcp/sse\"\n    }\n  }\n}\n\n```\n\n**Claude Code (CLI) JSON (`~/.claude.json` or project `.mcp.json`):**\n\n```json\n{\n  \"mcpServers\": {\n    \"docdex\": {\n      \"type\": \"http\",\n      \"url\": \"http://127.0.0.1:28491/v1/mcp\"\n    }\n  }\n}\n\n```\n\n**TOML (Codex):**\n\n```toml\n[mcp_servers.docdex]\nurl = \"http://127.0.0.1:28491/v1/mcp\"\ntool_timeout_sec = 300\nstartup_timeout_sec = 300\n\n```\n\n---\n\n## 🤖 capabilities & Examples\n\n### 1. AST & Impact Analysis\n\nDon't just find the string \"addressGenerator\"; find the **definition** and what it impacts.\n\n```bash\n# Find definition\ncurl \"http://127.0.0.1:28491/v1/ast?name=addressGenerator&pathPrefix=src\"\n\n# Track downstream impact (what breaks if I change this?)\ncurl \"http://127.0.0.1:28491/v1/graph/impact?file=src/app.ts&maxDepth=3\"\n\n```\n\n### 2. Memory System\n\nDocdex allows you to store \"facts\" that retrieval helps recall later.\n\n**Repo Memory (Project specific):**\n\n```bash\n# Teach the repo a fact\ndocdexd memory-store --repo . --text \"Payments retry up to 3 times with backoff.\"\n\n# Recall it later\ndocdexd memory-recall --repo . --query \"payments retry policy\"\n\n```\n\n**Agent Memory (User preference):**\n\n```bash\n# Set a style preference\ndocdexd profile add --agent-id \"default\" --category style --content \"Use concise bullet points.\"\n\n```\n\n### 3. Conversation Memory\n\nConversation memory is repo-scoped by default and optional. Repo-less sessions must use an explicit conversation namespace so they never silently reuse a repo archive. The subsystem imports transcripts, stores episodic summaries and working memory, derives diary entries and temporal KG facts into `knowledge.db`, and keeps recall under a strict wake-up budget.\n\nThe CLI archive, diary, and hook commands are HTTP-backed wrappers, so start `docdex start` or `docdexd daemon` first.\n\n```bash\n# Archive and inspect transcripts\ndocdexd conversations import --repo . ./session.txt --format plain_text --agent-id codex\ndocdexd conversations list --repo . --agent-id codex\ndocdexd conversations search --repo . \"timeline_index\"\ndocdexd conversations read --repo . <session_id>\n\n# Import into an explicit global conversation namespace instead of a repo archive\ndocdexd conversations import --conversation-namespace shared-team ./session.txt --format plain_text --agent-id codex\ndocdexd conversations search --conversation-namespace shared-team \"timeline_index\"\n\n# Keep agent diary notes alongside imported sessions\ndocdexd diary write --repo . --agent-id codex \"Wake-up rollout validated against knowledge.db timeline output.\"\ndocdexd diary read --repo . --agent-id codex\n\n# Trigger durable summarization from an external transcript\ndocdexd hook conversation --repo . \\\n  --action session_close_summarization \\\n  --source codex \\\n  --agent-id codex \\\n  --transcript ./session.txt \\\n  --format plain_text \\\n  --wait-for-processing\n\n# Build a compact wake-up bundle over recent context\ncurl -X POST http://127.0.0.1:28491/v1/wakeup \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"agent_id\":\"codex\",\"query\":\"timeline_index\",\"max_tokens\":96}'\n\n# Address the same archive over HTTP without repo_id\ncurl -X POST http://127.0.0.1:28491/v1/wakeup \\\n  -H \"Content-Type: application/json\" \\\n  -H \"x-docdex-conversation-namespace: shared-team\" \\\n  -d '{\"agent_id\":\"codex\",\"query\":\"timeline_index\",\"max_tokens\":96}'\n\n# Explore derived repo-scoped knowledge facts and provenance\ncurl \"http://127.0.0.1:28491/v1/kg/query?q=knowledge.db&limit=10\"\ncurl \"http://127.0.0.1:28491/v1/kg/search/nodes?q=knowledge&limit=10\"\ncurl \"http://127.0.0.1:28491/v1/kg/neighborhood?entity=knowledge.db&limit=10\"\ncurl \"http://127.0.0.1:28491/v1/kg/timeline?entity=knowledge.db&limit=10\"\n\n# Chat with wake-up + project-map context and inspect reasoning trace metadata\ncurl -X POST http://127.0.0.1:28491/v1/chat/completions \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"fake-model\",\n    \"messages\": [{\"role\": \"user\", \"content\": \"What changed around knowledge.db?\"}],\n    \"docdex\": {\n      \"agent_id\": \"codex\",\n      \"limit\": 6,\n      \"include_libs\": true,\n      \"dag_session_id\": \"session-123\"\n    }\n  }'\n```\n\n### 4. Local LLM Services\n\nDocdex detects supported local LLM services before it suggests installing anything. It can reuse Ollama, vLLM, llama.cpp-compatible OpenAI endpoints, LM Studio, LocalAI, SGLang, TGI-compatible deployments, and healthy local mcoda agents when they are already present. Ollama remains the recommended fallback because it is the easiest guided setup path.\n\n* **Setup:** Run `docdex setup` for an interactive wizard that lists detected services, models, embedding candidates, and local delegation agents.\n* **Inspect:** Run `docdexd llm detect --json` or `docdexd llm diagnostics --json` to see why a service/model was selected, skipped, or marked unhealthy.\n* **Manual Ollama fallback:** If no usable service is installed, pull the fallback embedding model with `ollama pull nomic-embed-text`.\n* **Custom Ollama URL:**\n```bash\nDOCDEX_OLLAMA_BASE_URL=http://127.0.0.1:11434 docdex start --host 127.0.0.1 --port 28491\n\n```\n\n\n\n---\n\n## ⚙️ Configuration & HTTP API\n\nDocdex runs as a local daemon serving:\n\n* **CLI Commands:** `docdexd chat`\n* **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/*`\n* **MCP Endpoints:** `/v1/mcp` and `/v1/mcp/sse`\n* **Capability Negotiation Tools:** `docdex_capabilities`, `docdex_rerank`, `docdex_batch_search`, `docdex_conversation_*`, `docdex_diary_*`, `docdex_conversation_hook`, `docdex_wakeup`, `docdex_kg_*`\n\n### Multi-Repo Setup\n\nRun a single daemon and mount additional repos on demand.\n\n```bash\ndocdex start --port 28491\n\n# Mount repos and capture repo_id values\ncurl -X POST \"http://127.0.0.1:28491/v1/initialize\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"rootUri\":\"file:///path/to/repo-a\"}'\n\ncurl -X POST \"http://127.0.0.1:28491/v1/initialize\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"rootUri\":\"file:///path/to/repo-b\"}'\n```\n\nNotes:\n- When more than one repo is mounted (or the daemon starts without a default repo), include `x-docdex-repo-id: <sha256>` on HTTP requests.\n- MCP sessions bind to the repo provided in `initialize.rootUri` and reuse that repo automatically.\n\n### Security\n\n* **Secure Mode:** By default, Docdex enforces TLS on non-loopback binds.\n* **Loopback:** `127.0.0.1` is accessible without TLS for local agents.\n* To expose to a network (use with caution), use `--expose` and `--auth-token`.\n\n---\n\n## 📚 Learn More\n\n* **Detailed Usage:** `docs/usage.md`\n* **API Reference:** `docs/http_api.md`\n* **MCP Specs:** `docs/mcp/errors.md`\n\n\n<a href=\"https://glama.ai/mcp/servers/@bekirdag/docdex\">\n  <img width=\"380\" height=\"200\" src=\"https://glama.ai/mcp/servers/@bekirdag/docdex/badge\" />\n</a>\n",
  "bytes": 11778,
  "sha": "d9df5e7aaae0cc40eda4bab4da7be3e5efb39351fa4c86e22edb3674ee91d8b1",
  "repo_slug": "bekirdag/docdex",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_bekirdag_docdex_4484153d/readme"
}