Docdex

Превратите свой репозиторий в быстрый и приватный контекст, которому могут доверять люди и ИИ.

Docdex — это локальный индексатор и поисковый демон для документации и исходного кода. Он располагается между вашими исходными файлами и ИИ-помощником, обеспечивая детерминированный поиск, анализ кода и постоянную память без необходимости загрузки вашего кода в облачное векторное хранилище.

⚡ Почему Docdex?

Большинство ИИ-инструментов полагаются на «grep» (быстро, но примитивно) или облачный RAG (медленно и требует загрузки данных). Docdex работает локально, понимает структуру кода и предоставляет вашим ИИ-агентам постоянную память.

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

2. Автоматическая настройка

Если у вас установлены следующие клиенты, Docdex автоматически настроит их на использование локальной конечной точки MCP (демон HTTP/SSE):

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

Примечание: Перезапустите ваш ИИ-клиент после установки.

🛠️ Рабочий процесс

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

🔌 Model Context Protocol (MCP)

Docdex разработан как «мозг» для ваших ИИ-агентов. Он предоставляет конечную точку 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 также может предоставлять MCP через локальный IPC (Unix-сокет или именованный канал Windows), в то время как 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. Память диалогов

Память диалогов по умолчанию привязана к репозиторию и является опциональной. Сессии без репозитория должны использовать явное пространство имен диалога, чтобы они никогда случайно не использовали архив репозитория. Подсистема импортирует транскрипты, хранит эпизодические суммаризации и рабочую память, извлекает дневниковые записи и факты временного графа знаний в 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 для интерактивного мастера настройки.

• Вручную: Убедитесь, что nomic-embed-text загружен в Ollama (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"}'

Примечания:

• Когда подключено более одного репозитория (или демон запущен без репозитория по умолчанию), добавляйте x-docdex-repo-id: <sha256> в HTTP-запросы.

• MCP-сессии привязываются к репозиторию, указанному в initialize.rootUri, и автоматически повторно используют этот репозиторий.

Безопасность

• Безопасный режим: По умолчанию Docdex принудительно использует TLS для соединений вне loopback.

• Loopback: 127.0.0.1 доступен без TLS для локальных агентов.

• Чтобы открыть доступ к сети (используйте с осторожностью), используйте --expose и --auth-token.

📚 Узнать больше

• Подробное использование: docs/usage.md

• Справочник API: docs/http_api.md

• Спецификации MCP: docs/mcp/errors.md