docdex

Docdex

Turn your repository into fast, private context that humans and AI can trust.

Docdex 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.

⚡ Why Docdex?

Most 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.

Problem	Typical Approach	The Docdex Solution
Finding Context	grep/rg (Noisy, literal matches)	Ranked, structured results based on intent.
Code Privacy	Hosted RAG (Requires uploading code)	Local-only indexing. Your code stays on your machine.
Siloed Search	IDE-only search bars	Shared Daemon serving CLI, HTTP, and MCP clients simultaneously.
Code Awareness	String matching	AST & Impact Graph to understand dependencies and definitions.

🚀 Features

• 📚 Document Indexing: Rank and summarize repo documentation instantly.
• 🧠 AST & Impact Graph: Search by function intent and track downstream dependencies (supports Rust, Python, JS/TS, Go, Java, C++, and more).
• 💾 Repo Memory: Stores project facts, decisions, and notes locally.
• 👤 Agent Memory: Remembers user preferences (e.g., "Use concise bullet points") across different repositories.
• 🔌 MCP Native: Auto-configures for tools like Claude Desktop, Cursor, and Windsurf.
• 🌐 Web Enrichment: Optional web search with local LLM filtering through detected local LLM services.

📦 Set-and-Forget Install

Install once, point your agent at Docdex, and it keeps working in the background.

1. Install via npm (Recommended)

Requires Node.js >= 18. This will download the correct binary for your OS (macOS, Linux, Windows).

npm i -g docdex

[!WARNING] Windows requirement: Docdex uses the MSVC runtime. Install the Microsoft Visual C++ Redistributable 2015-2022 (x64) before running docdex/docdexd.

• Winget: winget install --id Microsoft.VCRedist.2015+.x64
• Manual: download vc_redist.x64.exe from Microsoft: https://aka.ms/vs/17/release/vc_redist.x64.exe
• If docdexd exits with 0xC0000135, the runtime is missing.

2. Auto-Configuration

If you have any of the following clients installed, Docdex automatically configures them to use the local MCP endpoint (daemon HTTP/SSE):

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

Note: Restart your AI client after installation.

🛠️ Usage Workflow

1. Index a Repository

Run this once to build the index and graph data.

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

2. Start the Daemon

Start the shared server. This handles HTTP requests and MCP connections.

docdexd daemon --host 127.0.0.1 --port 28491

3. Ask Questions (CLI)

You can chat directly from the terminal.

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

🔌 Model Context Protocol (MCP)

Docdex is designed to be the "brain" for your AI agents. It exposes an MCP endpoint that agents connect to.

Architecture

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

Use the daemon HTTP/SSE endpoint. For sandboxed clients, Docdex can also serve MCP over local IPC (Unix socket or Windows named pipe), while HTTP/SSE remains the default for most MCP clients.

Stdio MCP (Smithery/stdio-only clients)

If your client requires a stdio MCP server (e.g., Smithery), use the bundled stdio bridge:

npx docdex docdex-mcp-stdio

The bridge reads newline-delimited JSON-RPC from stdin and forwards to Docdex. You can force IPC or override endpoints with:

DOCDEX_MCP_TRANSPORT=ipc DOCDEX_MCP_SOCKET_PATH=/path/to/mcp.sock npx docdex docdex-mcp-stdio

Manual Configuration

If you need to configure your client manually:

JSON (Claude/Cursor/Continue):

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

Claude Code (CLI) JSON (~/.claude.json or project .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

🤖 capabilities & Examples

1. AST & Impact Analysis

Don't just find the string "addressGenerator"; find the definition and what it impacts.

# 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. Memory System

Docdex allows you to store "facts" that retrieval helps recall later.

Repo Memory (Project specific):

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

Agent Memory (User preference):

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

3. Local LLM Services

Docdex 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.

• Setup: Run docdex setup for an interactive wizard that lists detected services, models, embedding candidates, and local delegation agents.
• Inspect: Run docdexd llm detect --json or docdexd llm diagnostics --json to see why a service/model was selected, skipped, or marked unhealthy.
• Manual Ollama fallback: If no usable service is installed, pull the fallback embedding model with ollama pull nomic-embed-text.
• Custom Ollama URL:

DOCDEX_OLLAMA_BASE_URL=http://127.0.0.1:11434 docdexd daemon --host 127.0.0.1 --port 28491

⚙️ Configuration & HTTP API

Docdex runs as a local daemon serving:

• CLI Commands: docdexd chat
• HTTP API: /search, /v1/capabilities, /v1/search/rerank, /v1/search/batch, /v1/ast, /v1/graph/impact
• MCP Endpoints: /v1/mcp and /v1/mcp/sse
• Capability Negotiation Tools: docdex_capabilities, docdex_rerank, docdex_batch_search

Multi-Repo Setup

Run a single daemon and mount additional repos on demand.

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

Notes:

• When more than one repo is mounted (or the daemon starts without a default repo), include x-docdex-repo-id: <sha256> on HTTP requests.
• MCP sessions bind to the repo provided in initialize.rootUri and reuse that repo automatically.

Security

• Secure Mode: By default, Docdex enforces TLS on non-loopback binds.
• Loopback: 127.0.0.1 is accessible without TLS for local agents.
• To expose to a network (use with caution), use --expose and --auth-token.

📚 Learn More

• Detailed Usage: docs/usage.md
• API Reference: docs/http_api.md
• MCP Specs: docs/mcp/errors.md