docdex

Docdex

将你的代码仓库转变为快速、私密且值得人类与 AI 信赖的上下文。

Docdex 是一款本地优先的索引器和搜索守护进程，用于文档和源代码。它位于原始文件与 AI 助手之间，提供确定性搜索、代码智能和持久记忆，同时绝不将代码上传到云端向量存储。

⚡ 为什么选择 Docdex？

大多数 AI 工具依赖「grep」（速度快但不够智能）或托管式 RAG（速度慢且需要上传文件）。Docdex 在本地运行，能够理解代码结构，并为 AI Agent 提供持久记忆。

问题	常见做法	Docdex 的解决方案
查找上下文	grep/rg（结果嘈杂，只匹配字面内容）	基于意图提供排序后的结构化结果。
代码隐私	托管式 RAG（需要上传代码）	仅在本地建立索引。 代码始终保留在你的设备上。
搜索孤岛	仅限 IDE 的搜索栏	共享守护进程，可同时为命令行、HTTP 和 MCP 客户端提供服务。
代码理解能力	字符串匹配	AST 和影响关系图，用于理解依赖关系和定义。

---

🚀 功能

• **📚 文档索引：**即时为代码仓库文档排序并生成摘要。
• **🧠 AST 和影响关系图：**按函数意图搜索并追踪下游依赖（支持 Rust、Python、JS/TS、Go、Java、C++ 等）。
• **💾 代码仓库记忆：**在本地存储项目事实、决策和笔记。
• **👤 Agent 记忆：**在不同代码仓库间记住用户偏好（例如「使用简洁的项目符号」）。
• **🗂️ 对话记忆：**导入对话记录，精简唤醒信息包，并生成限定于代码仓库的摘要、日志条目和工作记忆。
• **🕸️ 时序知识图谱：**从归档对话中提取实体、边、事件和面向代码的链接，以便查询时间线和邻近关系。
• **🧭 唤醒信息和项目地图上下文：**向兼容 OpenAI 的聊天补全接口注入精简的唤醒信息包、准确的用户画像，以及缓存的 Project map: 上下文。
• **🔌 原生支持 MCP：**自动为 Claude Desktop、Cursor 和 Windsurf 等工具配置。
• **🌐 Web 增强：**可选的网络搜索，并通过检测到的本地大模型服务进行本地 LLM 筛选。

---

📦 一次安装，持续运行

安装一次，将 Agent 指向 Docdex，它就会在后台持续运行。

1. 通过 npm 安装（推荐）

需要 Node.js >= 18。安装程序会为你的操作系统（macOS、Linux、Windows）下载正确的二进制文件。

npm i -g docdex

警告

**Windows 要求：**Docdex 使用 MSVC 运行库。运行 docdex/docdexd 前，请安装 Microsoft Visual C++ Redistributable 2015-2022 (x64)。

• Winget：winget install --id Microsoft.VCRedist.2015+.x64
• 手动安装：从 Microsoft 下载 vc_redist.x64.exe：https://aka.ms/vs/17/release/vc_redist.x64.exe
• 如果 docdexd 以 0xC0000135 退出，则表示缺少运行库。

2. 自动配置

如果你安装了以下任一客户端，Docdex 会自动将其配置为使用本地 MCP 端点（守护进程 HTTP/SSE）：

Claude Desktop、Cursor、Windsurf、Cline、Roo Code、Continue、VS Code、PearAI、Void、Zed、Codex。

注意：安装后请重启 AI 客户端。

---

🛠️ 使用工作流

1. 为代码仓库建立索引

运行一次即可构建索引和图数据。

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

2. 启动守护进程

启动共享服务。它负责处理 HTTP 请求和 MCP 连接。

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

3. 提问（命令行）

你可以直接在终端中聊天。

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

---

🔌 模型上下文协议（MCP）

Docdex 专为充当 AI Agent 的“大脑”而设计。它提供一个供 Agent 连接的 MCP 端点。

架构

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

使用守护进程的 HTTP/SSE 端点。对于沙盒客户端，Docdex 也可通过本地 IPC（Unix 套接字或 Windows 命名管道）提供 MCP 服务，而 HTTP/SSE 仍是大多数 MCP 客户端的默认方式。

手动配置

如果需要手动配置客户端：

JSON（Claude/Cursor/Continue）：

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

Claude Code（CLI）JSON（~/.claude.json 或项目 .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

---

🤖 功能与示例

1. AST 与影响分析

不要只查找字符串“addressGenerator”，还要找到它的定义以及它会影响什么。

# 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. 记忆系统

Docdex 允许你存储“事实”，以便之后通过检索帮助回忆。

仓库记忆（针对特定项目）：

# 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 记忆（用户偏好）：

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

3. 对话记忆

对话记忆默认按仓库范围划分，且为可选功能。无仓库会话必须使用明确的对话命名空间，以免意外复用仓库归档。该子系统会导入对话记录，存储情景摘要和工作记忆，将日记条目和时间知识图谱事实派生到 knowledge.db，并严格控制唤醒预算内的回忆操作。

CLI 归档、日记和钩子命令都是由 HTTP 支持的封装，因此请先启动 docdex start 或 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. 本地大模型服务

Docdex 会先检测受支持的本地大模型服务，再建议安装任何内容。若 Ollama、vLLM、兼容 llama.cpp 的 OpenAI 端点、LM Studio、LocalAI、SGLang、兼容 TGI 的部署以及运行正常的本地 mcoda Agent 已存在，Docdex 可以复用它们。Ollama 仍是推荐的备用方案，因为它是最简单的引导式设置方式。

• **设置：**运行 docdex setup，启动交互式向导，查看检测到的服务、模型、嵌入候选项和本地委派 Agent。
• **检查：**运行 docdexd llm detect --json 或 docdexd llm diagnostics --json，查看服务/模型被选中、跳过或标记为不健康的原因。
• **手动使用 Ollama 备用方案：**如果未安装可用的服务，请使用 ollama pull nomic-embed-text 拉取备用嵌入模型。
• 自定义 Ollama URL：

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

---

⚙️ 配置与 HTTP API

Docdex 以本地守护进程的形式运行，提供：

• CLI 命令：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 端点：/v1/mcp 和 /v1/mcp/sse
• 能力协商工具：docdex_capabilities、docdex_rerank、docdex_batch_search、docdex_conversation_*、docdex_diary_*、docdex_conversation_hook、docdex_wakeup、docdex_kg_*

多仓库设置

运行单个守护进程，并按需挂载其他仓库。

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

注意：

• 挂载了多个仓库（或守护进程启动时未指定默认仓库）时，请在 HTTP 请求中包含 x-docdex-repo-id: <sha256>。
• MCP 会话会绑定到 initialize.rootUri 中提供的仓库，并自动复用该仓库。

安全

• **安全模式：**默认情况下，Docdex 会对非环回绑定强制启用 TLS。
• **环回：**本地 Agent 可在不使用 TLS 的情况下访问 127.0.0.1。
• 如需对网络开放（请谨慎使用），请使用 --expose 和 --auth-token。

---

📚 了解更多

• 详细用法：docs/usage.md
• API 参考：docs/http_api.md
• MCP 规范：docs/mcp/errors.md