Skip to main content
Glama
deenesjakoruzh
bekirdag

docdex

by bekirdag
OverviewSchemaRelated ServersScoreDiscussions
Rust

Website GitHub Actions Workflow Status GitHub License GitHub Release Made with Rust

Docdex

将您的代码库转化为人类和 AI 都可以信赖的快速、私密的上下文。

Docdex 是一个面向文档和源代码的本地优先索引器和搜索守护进程。它位于您的原始文件和 AI 助手之间，提供确定性搜索、代码智能和持久化记忆，且无需将代码上传到云端向量数据库。

⚡ 为什么选择 Docdex？

大多数 AI 工具依赖于“grep”（快速但笨拙）或托管的 RAG（缓慢且需要上传）。Docdex 在本地运行，理解代码结构，并为您的 AI 代理提供持久化记忆。

问题

典型方法

Docdex 解决方案

查找上下文

grep/rg (嘈杂，字面匹配)

基于意图的排名、结构化结果。

代码隐私

托管 RAG (需要上传代码)

仅限本地索引。您的代码保留在您的机器上。

孤立搜索

仅限 IDE 的搜索栏

共享守护进程，同时为 CLI、HTTP 和 MCP 客户端提供服务。

代码感知

字符串匹配

AST 和影响图，用于理解依赖关系和定义。

Related MCP server: mcp-server-tree-sitter

🚀 功能

  • 📚 文档索引： 即时对仓库文档进行排名和总结。

  • 🧠 AST 和影响图： 按函数意图搜索并跟踪下游依赖关系（支持 Rust、Python、JS/TS、Go、Java、C++ 等）。

  • 💾 仓库记忆： 在本地存储项目事实、决策和笔记。

  • 👤 代理记忆： 在不同仓库间记住用户偏好（例如：“使用简洁的要点”）。

  • 🗂️ 对话记忆： 导入转录内容，保持唤醒包紧凑，并导出仓库范围的摘要、日记条目和工作记忆。

  • 🕸️ 时间知识图谱： 从存档对话中提取实体、边、片段和面向代码的链接，用于时间线和邻域查询。

  • 🧭 唤醒 + 项目地图上下文： 将紧凑的唤醒包、配置文件事实和缓存的 Project map: 上下文注入到兼容 OpenAI 的聊天补全中。

  • 🔌 MCP 原生： 为 Claude Desktop、Cursor 和 Windsurf 等工具自动配置。

  • 🌐 网络增强： 可选的本地 LLM 过滤网络搜索（通过 Ollama）。

📦 安装即用

安装一次，将您的代理指向 Docdex，它就会在后台持续工作。

1. 通过 npm 安装（推荐）

需要 Node.js >= 18。这将下载适用于您操作系统（macOS、Linux、Windows）的正确二进制文件。

npm i -g docdex
WARNING

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

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. 提问 (CLI)

您可以直接从终端进行聊天。

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

🔌 模型上下文协议 (MCP)

Docdex 旨在成为您 AI 代理的“大脑”。它公开了一个代理连接的 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"

代理记忆 (用户偏好):

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

3. 对话记忆

对话记忆默认是仓库范围的，且是可选的。无仓库会话必须使用显式的对话命名空间，以确保它们永远不会静默重用仓库存档。子系统导入转录内容，存储片段摘要和工作记忆，将日记条目和时间 KG 事实导出到 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. 本地 LLM (Ollama)

Docdex 使用 Ollama 进行嵌入和可选的本地聊天。

  • 设置： 运行 docdex setup 进行交互式向导。

  • 手动： 确保在 Ollama 中拉取了 nomic-embed-text (ollama pull nomic-embed-text)。

  • 自定义 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。

  • 回环： 127.0.0.1 无需 TLS 即可供本地代理访问。

  • 要暴露给网络（请谨慎使用），请使用 --expose 和 --auth-token。

📚 了解更多

  • 详细用法： docs/usage.md

  • API 参考： docs/http_api.md

  • MCP 规范： docs/mcp/errors.md

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

How are these scores calculated?

Resources

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/bekirdag/docdex'

If you have feedback or need assistance with the MCP directory API, please join our Discord server