Alcove

Alcove — это MCP-сервер, который предоставляет AI-агентам для программирования доступ по запросу к вашей частной проектной документации — без загрузки всего содержимого в контекстное окно, без утечки документации в публичные репозитории и без необходимости настраивать каждый проект для каждого используемого агента.

Демонстрация

Claude, Gemini, Codex — поиск · переключение проектов · глобальный поиск · проверка и генерация. Единая настройка.

alcove search · переключение проекта · --scope global · alcove validate

Проблема

У вас есть два плохих варианта.

Вариант А: Поместить документацию в CLAUDE.md / AGENTS.md Каждый файл внедряется в контекстное окно при каждом запуске. Работает для коротких соглашений. Не справляется с реальной проектной документацией. 10 файлов архитектуры = раздувание контекста = более медленные, дорогие и менее точные ответы.

Вариант Б: Не добавлять документацию Ваш агент выдумывает требования, которые вы уже задокументировали. Он игнорирует ограничения, принятые вами ранее. Он просит вас объяснять одно и то же каждую сессию.

Ни один из вариантов не масштабируется. Теперь умножьте это на 5 проектов и 3 агента, каждый из которых настроен по-своему. Каждый раз, когда вы переключаетесь, вы теряете контекст.

Как Alcove решает эту проблему

Alcove не внедряет вашу документацию. Агенты ищут то, что им нужно, тогда, когда им это нужно.

~/projects/my-app $ claude "how is auth implemented?"

  → Alcove detects project: my-app
  → BM25 search: "auth" → ARCHITECTURE.md (score: 0.94), DECISIONS.md (score: 0.71)
  → Agent gets the 2 most relevant docs, not all 12

~/projects/my-api $ codex "review the API design"

  → Alcove detects project: my-api
  → Same doc structure, same access pattern
  → Different project, zero reconfiguration

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

Правильное разделение

CLAUDE.md / AGENTS.md предназначены для поведения агента: повторяющиеся ошибки, которых следует избегать, соглашения о кодировании и инструкции для конкретной сессии. Держите их объем до 200 строк.

Alcove предназначен для знаний о проекте: архитектура, решения, руководства (runbooks), API-документация и все остальное, что нужно знать вашему агенту, но не обязательно при каждом запуске.

Паттерн:

CLAUDE.md | AGENTS.md                             ← agent rules, coding conventions, recurring corrections
~/.config/alcove/docs/my-app/
  ARCHITECTURE.md                      ← tech stack, data model, system design
  DECISIONS.md                         ← why X was chosen over Y
  DEBT.md                              ← known issues, workarounds
  ...                                  ← agent searches here when it needs context

Агенты вызывают search_project_docs("auth flow") и получают 2 наиболее релевантных документа — а не все 12. Ничего не попадает в контекстное окно, если это действительно не нужно.

Почему Alcove

Почему бы просто не использовать CLAUDE.md? Короткие соглашения и поведение агентов должны быть там. Проектная документация — архитектура, решения, руководства, PRD — не масштабируется в контекстном файле. Alcove — это не замена; это уровень, которым CLAUDE.md никогда не должен был быть.

Быстрый старт

# macOS
brew install epicsagas/alcove/alcove

# Linux / Windows — pre-built binary (fast, no compilation)
cargo install cargo-binstall
cargo binstall alcove

# Any platform — build from source
cargo install alcove

# Clone and build
git clone https://github.com/epicsagas/alcove.git
cd alcove
make install

alcove setup

Примечание: Предварительно скомпилированные бинарные файлы доступны для Linux (x86_64), macOS (Apple Silicon и Intel) и Windows.

setup интерактивно проведет вас через все этапы:

1. Где хранятся ваши документы

2. Какие категории документов отслеживать

3. Предпочитаемый формат диаграмм

4. Какие AI-агенты настроить (MCP + файлы навыков)

Запускайте alcove setup в любое время, чтобы изменить настройки. Он запоминает ваш предыдущий выбор.

Как это работает

flowchart LR
    subgraph Projects["Your projects"]
        A1["my-app/\n  src/ ..."]
        A2["my-api/\n  src/ ..."]
    end

    subgraph Docs["Your private docs (one repo)"]
        D1["my-app/\n  PRD.md\n  ARCH.md"]
        D2["my-api/\n  PRD.md\n  ..."]
        P1["policy.toml"]
    end

    subgraph Agents["Any MCP agent"]
        AG["Claude Code · Cursor\nGemini CLI · Codex · Copilot\n+4 more"]
    end

    subgraph MCP["Alcove MCP server"]
        T["search · get_file\noverview · audit\ninit · validate"]
    end

    A1 -- "CWD detected" --> D1
    A2 -- "CWD detected" --> D2
    Agents -- "stdio MCP" --> MCP
    MCP -- "scoped access" --> Docs

Ваши документы организованы в отдельной директории (DOCS_ROOT), по одной папке на проект. Alcove управляет документами там и предоставляет их любому MCP-совместимому AI-агенту через stdio. Ваш агент вызывает такие инструменты, как search_project_docs("auth flow"), и получает ранжированные результаты, специфичные для проекта — независимо от того, какого агента вы используете.

Что он делает

• Извлечение документации по запросу — агенты ищут и извлекают; ничего не загружается в контекст заранее

• Поиск с ранжированием BM25 — быстрый полнотекстовый поиск на базе tantivy; наиболее релевантные документы первыми, автоматическая индексация, резервный вариант — grep

• Один репозиторий документации, несколько проектов — частные документы организованы по проектам, управляются в одном месте

• Одна настройка, любой агент — настройте один раз, каждый MCP-совместимый агент получает одинаковый доступ

• Автоматическое определение вашего проекта из CWD — не требуется настройка для каждого проекта

• Ограниченный доступ — каждый проект видит только свои документы

• Межпроектный поиск — поиск по всем проектам сразу с помощью scope: "global"

• Частные документы остаются частными — документы никогда не касаются вашего публичного репозитория, все работает полностью на вашем компьютере через stdio

• Стандартизированная структура документации — policy.toml обеспечивает единообразие документации во всех проектах и командах

• Аудит между репозиториями — находит внутренние документы, ошибочно размещенные в репозитории проекта, предлагает исправления

• Проверка документации — проверяет наличие отсутствующих файлов, незаполненных шаблонов, обязательных разделов

• Работает с 9+ агентами — Claude Code, Cursor, Claude Desktop, Cline, OpenCode, Codex, Copilot, Antigravity, Gemini CLI

Инструменты MCP

CLI

alcove              Start MCP server (agents call this)
alcove setup        Interactive setup — re-run anytime to reconfigure
alcove doctor       Check the health of your alcove installation
alcove validate     Validate docs against policy (--format json, --exit-code)
alcove index        Build or rebuild the full-text search index for ranked search
alcove search       Search docs from the terminal
alcove uninstall    Remove skills, config, and legacy files

Поиск

Alcove автоматически выбирает лучшую стратегию поиска. Когда индекс поиска существует, он использует поиск с ранжированием BM25 (на базе tantivy) для получения результатов с оценкой релевантности. Когда его нет, он переключается на grep. Вам никогда не нужно об этом думать.

# Search the current project (auto-detected from CWD)
alcove search "authentication flow"

# Force grep mode if you want exact substring matching
alcove search "FR-023" --mode grep

Индекс строится автоматически в фоновом режиме при запуске MCP-сервера и перестраивается при обнаружении изменений в файлах. Никаких cron-задач, никаких ручных шагов.

Как это работает для агентов: агенты просто вызывают search_project_docs с запросом. Alcove берет на себя остальное — ранжирование, дедупликацию (один результат на файл), межпроектный поиск и резервный вариант. Агенту никогда не нужно выбирать режим поиска.

Глобальный поиск

Каждое архитектурное решение, каждое руководство, каждая заметка по проекту — доступны для поиска по всем вашим проектам сразу.

# Search across ALL projects
alcove search "rate limiting patterns" --scope global
alcove search "OAuth token refresh" --scope global

Агенты могут делать то же самое с scope: "global" в search_project_docs. Один запрос, каждый проект.

Определение проекта

По умолчанию Alcove определяет текущий проект из рабочей директории вашего терминала (CWD). Вы можете переопределить это с помощью переменной окружения MCP_PROJECT_NAME:

MCP_PROJECT_NAME=my-api alcove

Это полезно, когда ваш CWD не совпадает с именем проекта в вашем репозитории документации.

Политика документации

Определите общекомандные стандарты документации с помощью policy.toml в вашем репозитории документации:

[policy]
enforce = "strict"    # strict | warn

[[policy.required]]
name = "PRD.md"
aliases = ["prd.md", "product-requirements.md"]

[[policy.required]]
name = "ARCHITECTURE.md"

  [[policy.required.sections]]
  heading = "## Overview"
  required = true

  [[policy.required.sections]]
  heading = "## Components"
  required = true
  min_items = 2

Файлы политики разрешаются с приоритетом: проект (<project>/.alcove/policy.toml) > команда (DOCS_ROOT/.alcove/policy.toml) > встроенный по умолчанию (из ваших основных файлов config.toml). Это обеспечивает постоянное качество документации во всех ваших проектах, позволяя при этом переопределения для конкретных проектов.

Классификация документации

Alcove классифицирует документы по уровням:

Инструмент audit сканирует как ваш репозиторий документации, так и локальную директорию проекта, а затем предлагает действия — например, создание публичного README из вашего частного PRD или перенос ошибочно размещенных отчетов обратно в Alcove.

Конфигурация

Конфигурация находится в ~/.config/alcove/config.toml:

docs_root = "/Users/you/documents"

[core]
files = ["PRD.md", "ARCHITECTURE.md", "PROGRESS.md", "DECISIONS.md", "CONVENTIONS.md", "SECRETS_MAP.md", "DEBT.md"]

[team]
files = ["ENV_SETUP.md", "ONBOARDING.md", "DEPLOYMENT.md", "TESTING.md", ...]

[public]
files = ["README.md", "CHANGELOG.md", "CONTRIBUTING.md", "SECURITY.md", ...]

[diagram]
format = "mermaid"

Все это настраивается интерактивно через alcove setup. Вы также можете редактировать файл напрямую.

Списки файлов полностью настраиваемы — добавьте любое имя файла в любую категорию или перемещайте файлы между категориями, чтобы они соответствовали рабочему процессу вашей команды:

[core]
files = ["PRD.md", "ARCHITECTURE.md", "DECISIONS.md", "MY_SPEC.md"]  # added custom doc

[public]
files = ["README.md", "CHANGELOG.md", "PRD.md"]  # PRD exposed as public for this project

Поддерживаемые агенты

Агенты с поддержкой навыков активируют Alcove автоматически, когда вы спрашиваете об архитектуре проекта, соглашениях, решениях или статусе. Их также можно вызвать явно:

/alcove                          Summarize current project docs and status
/alcove search auth flow         Search docs for a specific topic
/alcove what conventions apply?  Ask a doc question directly

Поддерживаемые языки

CLI автоматически определяет локаль вашей системы. Вы также можете переопределить ее с помощью переменной окружения ALCOVE_LANG.