Ваш ИИ-агент не знает ваш проект. Alcove это исправляет.
English ·
한국어 ·
日本語 ·
简体中文 ·
Español ·
हिन्दी ·
Português ·
Deutsch ·
Français ·
Русский
Alcove — это HTTP API сервер, предоставляющий ИИ-агентам для кодирования доступ к документации вашего частного проекта по требованию — **гибридный поиск BM25 + векторный** для точного извлечения, **индексация кода tree-sitter** для понимания структуры кодовой базы, и **контроль политик** для согласованности документов. Без раздувания контекста, без утечки документов в публичные репозитории, без настройки для каждого агента.
## Демо
> *Claude, Codex — поиск · переключение проектов · глобальный поиск · валидация и генерация. Одна настройка.*
Демо CLI
> *`alcove search` · переключение проектов · `--scope global` · `alcove validate`*
## Проблема
Ваш ИИ-агент начинает каждую сессию с нуля.
Он не знает вашу архитектуру. Игнорирует ограничения из уже принятых вами решений. Просит объяснять одно и то же каждую сессию.
Контекстное окно — это узкое место. Каждый токен стоит денег и внимания. Загрузка 10 архитектурных документов в контекст тратит 50K+ токенов при каждом запуске — и собственная документация Anthropic предупреждает, что раздутые файлы конфигурации заставляют агентов *игнорировать ваши фактические инструкции*.
У вас есть три плохих варианта:
**Засунуть всё в конфиг агента** — каждый файл загружается в контекст при каждом запуске. 10 документов = раздутый контекст = медленные, дорогие, менее точные ответы.
**Копировать-вставлять в каждый чат** — работает один раз, не масштабируется за пределы одной сессии.
**Забить** — агент выдумывает требования, которые вы уже задокументировали, игнорирует ограничения из уже принятых решений, и вы повторно объясняете одну и ту же архитектуру каждый понедельник утром.
Умножьте на 5 проектов и 3 агента. При каждом переключении вы теряете контекст.
## Как Alcove решает эту проблему
Alcove хранит все ваши частные документы в **одном общем репозитории**, организованном по проектам. Все агенты обращаются к ним одинаково через HTTP API — будь то Claude Code, Cursor или Codex.
```
~/projects/my-app $ claude "/alcove как реализована аутентификация?"
→ Alcove определяет проект: my-app
→ Читает ~/documents/my-app/ARCHITECTURE.md
→ Агент отвечает с реальным контекстом проекта
```
```
~/projects/my-api $ codex "/alcove проверь дизайн API"
→ Alcove определяет проект: my-api
→ Та же структура документов, тот же паттерн доступа
→ Другой проект, тот же рабочий процесс
```
**Меняйте агентов в любой момент. Меняйте проекты в любой момент. Документальный слой остаётся стандартизированным.**
## Основные возможности
- **Один репозиторий документов, несколько проектов** — частные документы организованы по проектам, управляются в одном месте
- **Одна настройка, любой агент** — настройте один раз, каждый ИИ-агент получает одинаковый доступ
- **Автоопределение проекта** по CWD — без настройки для каждого проекта
- **Ограниченный доступ** — каждый проект видит только свои документы
- **Умный поиск** — BM25-ранжированный поиск с автоматической индексацией; находит наиболее релевантные документы первыми, при необходимости откатывается на grep
- **Кросс-проектный поиск** — ищите во всех проектах одновременно с `scope: "global"` — используйте как персональную базу знаний
- **Частные документы остаются частными** — конфиденциальные документы (карта секретов, внутренние решения, технический долг) никогда не попадают в публичный репозиторий
- **Стандартизированная структура документов** — `policy.toml` обеспечивает единообразие документов во всех проектах и командах
- **Кросс-репозиторный аудит** — находит неправильно размещённые внутренние документы в репозитории проекта, предлагает исправления
- **Валидация документов** — проверяет отсутствующие файлы, незаполненные шаблоны, обязательные разделы
- **Семантический линтинг** — автоматически обнаруживает сломанные вики-ссылки, файлы-сироты, устаревшие маркеры WIP/DRAFT и упоминания дат старше 2 лет
- **Импорт из внешнего хранилища** — перенесите заметку из Obsidian (или любого другого хранилища) в doc-repo одной командой; автоматическая маршрутизация в нужный проект
- **Работает с 9+ агентами** — Claude Code, Cursor, Claude Desktop, Cline, OpenCode, Codex, Copilot
## Почему Alcove
| Без Alcove | С Alcove |
|------------|----------|
| Внутренние документы разбросаны по Notion, Google Docs, локальным файлам | Один репозиторий документов, структурированный по проектам |
| Каждый ИИ-агент настраивается отдельно для доступа к документам | Одна настройка, все агенты разделяют одинаковый доступ |
| Смена проекта означает потерю документального контекста | Автоопределение по CWD, мгновенное переключение проекта |
| Поиск агента возвращает случайные совпадающие строки | Гибридный поиск (BM25 + RAG) — агенты получают только нужное, ранжированное по релевантности |
| Агент видит только текстовые документы, а не структуру кода | Индексация кода tree-sitter — агенты понимают модули, функции и типы на 12 языках |
| "Найти все мои заметки об аутентификации" — невозможно | Глобальный поиск по всем проектам в одном запросе |
| Конфиденциальные документы рискуют утечь в публичные репозитории | Частные документы физически отделены от репозиториев проектов |
| Структура документов различается у каждого проекта и члена команды | `policy.toml` обеспечивает стандарты во всех проектах |
| Нет способа проверить, полны ли документы | `validate` обнаруживает отсутствующие файлы, пустые шаблоны, недостающие разделы |
| Устаревшие ссылки или маркеры WIP остаются незамеченными | `lint` автоматически обнаруживает сломанные ссылки, файлы-сироты и устаревшие маркеры |
| Заметки из Obsidian и других инструментов остаются изолированными | `promote` интегрирует внешние заметки в doc-repo одной командой |
## Быстрый старт
> **Обязательно**: Выполните `alcove setup` один раз после установки, чтобы настроить корневой каталог документов и включить все функции. Плагины автоматически регистрируют MCP-подключение, но Alcove не может искать и индексировать документы до выполнения `setup`.
>
> **Используете Obsidian?** См. раздел [Экосистема](#ecosystem) для рекомендуемой структуры документов и настройки хранилищ.
### Claude Code
```
/plugin marketplace add epicsagas/plugins
/plugin install alcove@epicsagas
```
Автоматически устанавливает бинарный файл и регистрирует MCP-сервер при следующем запуске сессии.
> **Обязательно**: Запустите `alcove setup` один раз после установки, чтобы настроить корень документов и включить полный функционал. Плагин автоматически инициализирует MCP-подключение, но Alcove не может искать или индексировать документы, пока не будет выполнен `setup`.
```bash
alcove setup # запустить один раз после установки плагина
```
Обновления через `claude plugin update epicsagas/alcove`.
### Codex CLI
```bash
codex plugin marketplace add epicsagas/plugins
```
Автоматически устанавливает навык и регистрирует MCP-сервер.
Доступно сразу — дополнительные шаги не требуются.
Обновления через `codex plugin update alcove@epicsagas`.
### macOS (только Apple Silicon)
```bash
brew install epicsagas/tap/alcove
```
Нет Homebrew? Используйте скрипт установки:
```bash
curl --proto '=https' --tlsv1.2 -LsSf \
https://github.com/epicsagas/alcove/releases/latest/download/alcove-installer.sh | sh
```
### Linux (x86_64 / ARM64)
```bash
curl --proto '=https' --tlsv1.2 -LsSf \
https://github.com/epicsagas/alcove/releases/latest/download/install.sh | sh
```
### Windows (x86_64 / ARM64)
```powershell
irm https://github.com/epicsagas/alcove/releases/latest/download/install.ps1 | iex
```
### Antigravity (Gemini CLI)
```bash
agy plugins install https://github.com/epicsagas/alcove
```
Автоматически устанавливает плагин (MCP-сервер, навык, хуки) и регистрирует его при следующем запуске сессии.
```bash
alcove setup # run once after plugin install
```
### Через цепочку инструментов Rust
```bash
cargo binstall alcove # готовый бинарный файл, гибридный поиск включён
cargo install alcove --features full-macos # сборка из исходников (macOS)
cargo install alcove --features full-cross # сборка из исходников (Linux/Windows)
```
> **Примечание**: `cargo binstall` загружает готовый бинарный файл с гибридным поиском (векторный + BM25). При сборке из исходников для гибридного поиска требуется `--features full-macos` или `--features full-cross`. Без features доступен только поиск BM25 (по ключевым словам).
### Первичная настройка (обязательно)
После установки любым из способов выше, запустите:
```bash
alcove setup
alcove --version
alcove doctor
```
`setup` проведёт вас через всё интерактивно:
1. Где находятся ваши документы
2. Какие категории документов отслеживать
3. Предпочтительный формат диаграмм
4. Модель эмбеддингов для гибридного поиска
5. **Фоновый сервер** — устранить холодный старт при каждой сессии (элемент входа macOS)
6. Какие ИИ-агенты настроить (MCP + файлы навыков — Claude Code и Codex управляются через их плагин-системы)
Перезапустите `alcove setup` в любое время для изменения настроек. Он запоминает ваши предыдущие выборы.
**Необязательные зависимости**
| Инструмент | Назначение | Установка |
|---|---|---|
| `pdftotext` (poppler) | Полное извлечение текста PDF — требуется для поиска по PDF | macOS: `brew install poppler` · Debian/Ubuntu: `apt install poppler-utils` · Fedora: `dnf install poppler-utils` · Windows: [poppler for Windows](https://github.com/oschwartz10612/poppler-windows/releases) |
Без `pdftotext` Alcove откатывается на встроенный PDF-парсер, который может не справиться с некоторыми файлами. Запустите `alcove doctor`, чтобы проверить установку.
### Устранение неполадок
**Агент не находит инструменты Alcove**
Запустите `alcove setup` повторно — он перерегистрирует MCP-сервер для всех настроенных агентов. Затем начните новую сессию агента (регистрация вступит в силу при следующем запуске).
**Поиск не выдаёт результатов**
Индекс, возможно, ещё не построен. Запустите `alcove index` для построения и повторите попытку.
**403 Unauthorized от фонового сервера**
В вашей оболочке не задана переменная `ALCOVE_TOKEN`. Запустите `alcove token` для вывода токена, добавьте `export ALCOVE_TOKEN="..."` в профиль оболочки и перезагрузите.
**`alcove doctor` сообщает о проблемах**
Следуйте предложениям, выводимым `doctor` — он проверяет расположение бинарного файла, регистрацию MCP, состояние индекса и необязательные зависимости, такие как `pdftotext`.
## Использование
### Поиск через CLI
Ищите по своим документам прямо из терминала. По умолчанию поиск ведется по **всем проектам** (глобальный охват).
```bash
# Базовый поиск (глобальный охват)
alcove search "authentication"
# Ограничить поиск текущим проектом (автоопределение через CWD)
alcove search "auth flow" --scope project
# Принудительный режим grep (точное совпадение подстроки)
alcove search "TODO" --mode grep
# Принудительный ранжированный режим (BM25/Гибридный)
alcove search "data model" --mode ranked
# Настроить лимит результатов
alcove search "deployment" --limit 5
```
### ИИ-агенты (HTTP API)
ИИ-агенты для кодирования используют Alcove через **локальный HTTP API** на порту 58301. Навыки вызывают `curl http://localhost:58301/...` под капотом. Обычно вам не нужно вызывать их самостоятельно; агент сам воспользуется ими, когда вы зададите вопросы о своем проекте.
| Endpoint | Метод | Описание |
|----------|-------|----------|
| `/health` | GET | Проверка работоспособности |
| `/search?q=...` | GET | Поиск документации |
| `/v1/search` | POST | Поиск с JSON-телом |
| `/projects` | GET | Список всех проектов |
| `/projects` | POST | Инициализация нового проекта |
| `/projects/{name}/docs` | GET | Список документов проекта |
| `/projects/{name}/audit` | GET | Аудит состояния документов |
| `/projects/{name}/validate` | GET | Валидация документов по политике |
| `/projects/{name}/config` | PUT | Обновление настроек проекта |
| `/docs/{path}` | GET | Чтение файла документа |
| `/rebuild` | POST | Перестроить поисковый индекс |
| `/changes` | GET | Проверить изменённые файлы |
| `/lint` | GET | Линтинг документов |
| `/vaults` | GET | Список хранилищ |
| `/vaults/search?q=...` | GET | Поиск по хранилищам |
| `/vaults/backup` | POST | Резервная копия хранилища |
| `/promote` | POST | Импорт файла в doc-repo |
| `/index-code` | POST | Индексация структуры кода |
| `/mcp` | POST | JSON-RPC прокси (устаревший MCP) |
> **Примечание**: MCP по-прежнему доступен для ручной настройки — см. `registry/mcp.json` для доступа через stdio.
**Пример взаимодействия с агентом:**
> **Пользователь:** "/alcove Как мне добавить новую конечную точку API?"
> **Агент:** (вызывает `POST /v1/search` с `query="add api endpoint"`)
> **Агент:** (читает наиболее релевантный документ через `GET /docs/{path}?project=...`)
> **Агент:** "Согласно `ARCHITECTURE.md`, вам необходимо..."
---
## Как это работает
```mermaid
flowchart LR
subgraph Projects["Ваши проекты"]
A1["my-app/\n src/ ..."]
A2["my-api/\n src/ ..."]
end
subgraph Docs["Ваши частные документы (один репозиторий)"]
D1["my-app/\n PRD.md\n ARCH.md"]
D2["my-api/\n PRD.md\n ..."]
P1["policy.toml"]
end
subgraph Agents["Любой ИИ-агент"]
AG["Claude Code · Cursor\nCodex · Copilot\n+4 more"]
end
subgraph API["HTTP API сервер Alcove"]
T["search · get_file\noverview · audit\ninit · validate"]
end
A1 -- "CWD определён" --> D1
A2 -- "CWD определён" --> D2
Agents -- "HTTP :58301" --> API
API -- "ограниченный доступ" --> Docs
```
Документы организованы в отдельном каталоге (`DOCS_ROOT`), по одной папке на проект. Alcove управляет документами и передаёт их любому ИИ-агенту через HTTP на порту 58301.
## Классификация документов
Alcove классифицирует документы на следующие уровни:
| Классификация | Расположение | Примеры |
|--------------|-------------|---------|
| **doc-repo-required** | Alcove (частный) | PRD, Architecture, Decisions, Conventions |
| **doc-repo-supplementary** | Alcove (частный) | Deployment, Onboarding, Testing, Runbook |
| **reference** | Alcove папка `reports/` | Отчёты аудита, бенчмарки, анализы |
| **project-repo** | GitHub-репозиторий (публичный) | README, CHANGELOG, CONTRIBUTING |
Инструмент `audit` сканирует репозиторий документов и локальный каталог проекта, затем предлагает действия — например, создание публичного README из вашего частного PRD или перенос неправильно размещённых отчётов обратно в alcove.
## Точки API
| Endpoint | Метод | Что делает |
|----------|-------|------------|
| `/health` | GET | Проверка работоспособности |
| `/search?q=...` | GET | Поиск документации |
| `/v1/search` | POST | Поиск с JSON-телом |
| `/projects` | GET | Список всех проектов |
| `/projects` | POST | Инициализация нового проекта |
| `/projects/{name}/docs` | GET | Список документов проекта |
| `/projects/{name}/audit` | GET | Аудит состояния документов |
| `/projects/{name}/validate` | GET | Валидация документов по политике |
| `/projects/{name}/config` | PUT | Обновление настроек проекта |
| `/docs/{path}` | GET | Чтение файла документа |
| `/rebuild` | POST | Перестроить поисковый индекс |
| `/changes` | GET | Проверить изменённые файлы |
| `/lint` | GET | Линтинг документов |
| `/vaults` | GET | Список хранилищ |
| `/vaults/search?q=...` | GET | Поиск по хранилищам |
| `/vaults/backup` | POST | Резервная копия хранилища |
| `/promote` | POST | Импорт файла в doc-repo |
| `/index-code` | POST | Индексация структуры кода |
| `/mcp` | POST | JSON-RPC прокси (устаревший MCP) |
> **Примечание**: MCP по-прежнему доступен для ручной настройки — см. `registry/mcp.json` для доступа через stdio.
## CLI
```
alcove Запустить MCP-сервер (агенты вызывают это)
alcove setup Интерактивная настройка — перезапустите для переконфигурации
alcove doctor Проверить состояние установки Alcove
alcove validate Валидация документов по политике (--format json, --exit-code)
alcove lint Семантический линтинг — сломанные ссылки, сироты, устаревшие маркеры (--format json)
alcove promote Импорт заметок из внешнего хранилища в doc-repo
alcove index Обновить поисковый индекс (инкрементально — только изменённые файлы)
alcove rebuild Перестроить поисковый индекс с нуля (использовать после изменений схемы)
alcove search Искать документы из терминала
alcove bench Бенчмарк качества поиска [--corpus] (точность, задержка, обнаружение регрессий)
alcove index-code Генерирует индекс структуры кода из исходников [--language LANG] [--source PATH]
alcove token Вывести bearer-токен (для аутентификации фонового сервера)
alcove uninstall Удалить навыки, конфигурацию и устаревшие файлы
alcove mcp Управление жизненным циклом фонового MCP-сервера (start, stop, status, enable, disable)
alcove vault link Связать внешний каталог как vault (например, Obsidian)
alcove vault list Список всех vault с количеством документов
alcove vault index Создать поисковый индекс для vault
```
### Индексация кода
Анализирует исходные файлы с помощью tree-sitter и генерирует `CODE_INDEX.md`—сводку кодовой базы на уровне модулей в формате Markdown, интегрированную с поисковым конвейером Tantivy.
```bash
# Индексировать текущий проект (автоматическое определение всех языков)
alcove index-code --source ./src
# Монорепо: индексировать директорию с несколькими языками
alcove index-code --source ./
# Ограничить одним языком
alcove index-code --source ./src --language typescript
alcove index-code --source ./src --language rust
```
**Поддерживаемые языки:**
| Язык | Feature-флаг | Расширения файлов |
|------|-------------|------------------|
| Rust | `lang-rust` | `.rs` |
| Python | `lang-python` | `.py`, `.pyi` |
| TypeScript | `lang-typescript` | `.ts`, `.tsx` |
| JavaScript | `lang-javascript` | `.js`, `.jsx`, `.mjs` |
| Go | `lang-go` | `.go` |
| Java | `lang-java` | `.java` |
| Kotlin | `lang-kotlin` | `.kt`, `.kts` |
| C | `lang-c` | `.c`, `.h` |
| C++ | `lang-cpp` | `.cpp`, `.cc`, `.cxx`, `.hpp`, `.hxx`, `.h` |
| Swift | `lang-swift` | `.swift` |
| Ruby | `lang-ruby` | `.rb` |
| C# | `lang-csharp` | `.cs` |
Официальные бинарные файлы активируют все 12 парсеров (`lang-all`). Без `--language` **автоматически индексируются все распознанные расширения**—безопасно для монорепо.
`--language` принимает сокращения: `ts` → TypeScript, `cpp` → C++, `csharp` → C#, `py` → Python, `js` → JavaScript, `kt` → Kotlin, `rb` → Ruby.
### Lint (Линтинг)
```bash
# Линтинг текущего проекта (автоматическое определение из CWD)
alcove lint
# Указать конкретный проект
alcove lint --project my-app
# Машиночитаемый вывод для CI
alcove lint --format json
```
Линтинг проверяет четыре вещи:
| Проверка | Что обнаруживается |
|---------|-------------------|
| `broken-link` | `[[вики-ссылки]]` или `[текст](путь)`, указывающие на несуществующие файлы |
| `orphan` | Файлы, на которые не ссылается ни один документ |
| `stale-marker` | Маркеры WIP / TODO / FIXME / DRAFT / DEPRECATED |
| `stale-date` | Упоминания дат старше 2 лет (например, «по состоянию на 2022») |
### Promote (Продвижение)
```bash
# Скопировать заметку из Obsidian в doc-repo (автоматическая маршрутизация)
alcove promote ~/my-brain/Projects/auth-notes.md
# Указать конкретный проект
alcove promote ~/my-brain/Projects/auth-notes.md --project my-app
# Переместить вместо копирования
alcove promote ~/my-brain/Projects/auth-notes.md --mv
```
Файлы без подходящего проекта сохраняются в `inbox/` для ручной проверки.
### Бенчмарк
**Режим изолированного корпуса** (`--corpus`) использует автономный тестовый набор данных (19 синтетических документов, 25 запросов) для быстрых и воспроизводимых CI-бенчмарков — реальные документы не нужны, завершается менее чем за 60 секунд.
```bash
# Запустить на встроенном оценочном корпусе (рекомендуется для CI)
alcove bench --corpus --baseline benches/corpus/baseline.json
# Обновить базовый показатель корпуса после намеренных изменений
alcove bench --corpus --save-baseline benches/corpus/baseline.json
# Запустить на реальных документах (50 запросов, 10 категорий)
alcove bench --metrics precision
# Сохранить как базовый показатель для будущего сравнения
alcove bench --output json --save-baseline benches/baseline.json
# Сравнить с базовым показателем — обнаружение регрессий в CI
alcove bench --baseline benches/baseline.json
# Отчёт в Markdown
alcove bench --output markdown --output-file bench-report.md
```
| Метрика | Что измеряет |
|---------|-------------|
| Precision@K | Доля релевантных документов в топ-K результатах |
| Recall@K | Доля найденных релевантных документов в топ-K |
| NDCG@K | Качество ранжирования со скидкой за позицию |
| MAP@K | Средняя точность по всем запросам |
| MRR | Обратный ранг первого релевантного результата |
| Точность чанков | Попадают ли извлечённые чанки в правильные разделы |
**Пороги регрессии**: точность >5%, задержка >20%, пропускная способность >15%. Предупреждение на половине порога.
## Фоновый сервер
Запуск постоянного фонового сервера устраняет задержку при холодном старте при каждой новой сессии агента. **`alcove setup` включает это по умолчанию** (объект входа в систему macOS).
```bash
alcove mcp enable --now # Включить и запустить (сохраняется после перезагрузки)
alcove mcp stop / start / restart / status
alcove mcp disable # Отключить и удалить объект входа в систему
```
Когда фоновый сервер запущен, процесс stdio работает как лёгкий прокси — вместо загрузки поискового движка при каждой сессии, он перенаправляет запросы на активный сервер. При запуске процесс stdio проверяет `GET /health` и автоматически переходит в режим прокси.
## Поиск
Alcove автоматически выбирает лучшую стратегию поиска. Когда поисковый индекс существует, используется **BM25-ранжированный поиск** (на базе [tantivy](https://github.com/quickwit-oss/tantivy)) для результатов, отсортированных по релевантности. Без индекса откатывается на grep. Вам никогда не нужно об этом думать.
```bash
# Поиск в текущем проекте (автоопределение из CWD)
alcove search "authentication flow"
# Поиск во ВСЕХ проектах — ваша персональная база знаний
alcove search "OAuth token refresh" --scope global
# Принудительный режим grep для точного поиска подстрок
alcove search "FR-023" --mode grep
```
Индекс строится автоматически в фоновом режиме при запуске MCP-сервера и перестраивается при обнаружении изменений в файлах. Никаких cron-задач, никаких ручных действий.
**Как это работает для агентов:** агенты просто вызывают `search_project_docs` с запросом. Alcove обрабатывает всё остальное — ранжирование, дедупликацию (один результат на файл), кросс-проектный поиск и откат. Агенту никогда не нужно выбирать режим поиска.
### Выбор модели эмбеддингов
| Модель | Диск | Размерность | Контекст | Языки | Лучше всего для | Пиковая RAM |
|--------|------|-------------|----------|-------|-----------------|-------------|
| **`ArcticEmbedXS`** (по умолч.) | **90 MB** | **384** | **512** | **Многоязычный** | **По умолчанию — лучшее соотношение** | **~400 MB** |
| `ArcticEmbedXSQ` | 90 MB | 384 | 512 | Многоязычный | Квантованный, меньший загрузка | ~400 MB |
| `MultilingualE5Small` | 470 MB | 384 | 512 | 100+ языков | Лучшая поддержка корейского/CJK | ~1.2 GB |
| `BGEM3` | 600 MB | 1024 | 8192 | 100+ языков | Премиум — Dense+Sparse+ColBERT | ~2 GB |
| `ArcticEmbedMLong` | 430 MB | 768 | 8192 | Многоязычный | Длинные документы | ~1.5 GB |
| `JinaEmbeddingsV2BaseCode` | 550 MB | 768 | 8192 | Код+английский | Оптимизирован для кода | ~1.5 GB |
Модель по умолчанию — **ArcticEmbedXS** (90 МБ, многоязычная). Обеспечивает лучший баланс размера и качества для большинства проектов.
Модели эмбеддинга основаны на [fastembed-rs](https://github.com/Anush008/fastembed-rs) (ONNX Runtime) и работают полностью локально. Чтобы использовать другую модель, укажите её в `config.toml`:
```toml
[embedding]
model = "BGEM3" # имя Variable из документации моделей
```
Полный список 40+ поддерживаемых моделей (размерности, длина контекста, языки) см. в **[EMBEDDING_MODELS.md](../docs/EMBEDDING_MODELS.md)**.
**Память при перестройке:**
Пиковая RAM зависит от модели — см. столбец "Пиковая RAM" в таблице выше. Крупные модели (BGEM3, ArcticEmbedMLong) могут использовать 1.5-2 ГБ во время перестройки. После завершения стационарное состояние снижается до ~50-200 МБ в зависимости от вашей конфигурации `[memory]`. Вы можете дополнительно уменьшить, снизив `max_hnsw_cache` и укоротив `model_unload_secs`.
## Определение проекта
По умолчанию Alcove определяет текущий проект по рабочему каталогу вашего терминала (CWD). Вы можете переопределить это переменной окружения `MCP_PROJECT_NAME`:
```bash
MCP_PROJECT_NAME=my-api alcove
```
Полезно, когда ваш CWD не совпадает с именем проекта в хранилище документов.
## Политика документов
Определите командные стандарты документации с помощью `policy.toml` в вашем хранилище документов:
```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
```
Файлы политики разрешаются с приоритетом: **проект** (`/.alcove/policy.toml`) > **команда** (`DOCS_ROOT/.alcove/policy.toml`) > **встроенный по умолчанию** (список core-файлов из config.toml). Это обеспечивает единообразное качество документов во всех проектах, позволяя при этом переопределения на уровне проекта.
## Конфигурация
Конфигурация находится в `~/.config/alcove/config.toml`:
```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`. Вы также можете редактировать файл напрямую.
## Поддерживаемые агенты
| Агент | MCP | Навык |
|-------|-----|-------|
| Claude Code | `~/.claude.json` | `~/.claude/skills/alcove/` |
| Cursor | `~/.cursor/mcp.json` | `~/.cursor/skills/alcove/` |
| Claude Desktop | конфигурация платформы | — |
| Cline (VS Code) | VS Code globalStorage | `~/.cline/skills/alcove/` |
| OpenCode | `~/.config/opencode/opencode.json` | `~/.opencode/skills/alcove/` |
| Codex CLI | `~/.codex/config.toml` | `~/.codex/skills/alcove/` |
| Copilot CLI | `~/.copilot/mcp-config.json` | `~/.copilot/skills/alcove/` |
| Antigravity | `agy plugins install` | — |
## Поддерживаемые языки
CLI автоматически определяет локаль вашей системы. Вы также можете переопределить её с помощью переменной окружения `ALCOVE_LANG`.
| Язык | Код |
|------|-----|
| English | `en` |
| 한국어 | `ko` |
| 简体中文 | `zh-CN` |
| 日本語 | `ja` |
| Español | `es` |
| हिन्दी | `hi` |
| Português (Brasil) | `pt-BR` |
| Deutsch | `de` |
| Français | `fr` |
| Русский | `ru` |
```bash
# Переопределить язык
ALCOVE_LANG=ru alcove setup
```
## Обновление
| Способ | Команда |
|--------|--------|
| Homebrew | `brew upgrade alcove` |
| curl installer | Повторно запустить скрипт установки выше |
| cargo binstall | `cargo binstall alcove@latest` |
| cargo install | `cargo install alcove@latest --features full-macos` |
| Claude Code Plugin | `claude plugin update epicsagas/alcove` |
```bash
alcove --version
```
## Удаление
```bash
alcove uninstall # удалить навыки и конфигурацию
cargo uninstall alcove # удалить бинарный файл
```
## Хранилища знаний (Vaults)
Помимо документации проекта, Alcove поддерживает **независимые хранилища знаний (vaults)** для исследовательских заметок, справочных материалов и курируемых знаний, по которым LLM могут осуществлять поиск.
```bash
# Создать vault для заметок об исследованиях ИИ
alcove vault create ai-research
# Связать существующий vault Obsidian (без копирования — индексация на месте)
alcove vault link my-obsidian ~/Obsidian/research
# Добавить документ
alcove vault add ai-research ~/Downloads/transformer-survey.md
# Создать поисковый индекс для vault
alcove vault index
# Список всех vault
alcove vault list
# areas (8 docs) → (linked)
# resources (71 docs) → (linked)
# zettelkasten (17 docs) → (linked)
# Поиск через CLI
alcove search "attention mechanism" --vault ai-research
# Агенты ищут через MCP
search_vault(query="attention mechanism", vault="ai-research")
# Поиск по ВСЕМ vault одновременно
search_vault(query="transformer", vault="*")
```
Vaults **полностью изолированы** от документации проекта — отдельные индексы, отдельные кэши, отдельный поиск. Поиск документов проекта вашим агентом для кодирования никогда не затрагивается активностью в vault.
| Функция | Документация проекта | Хранилища (Vaults) |
|---------|-------------|--------|
| Цель | Документация по проектам | Общая база знаний |
| Хранение | `~/.alcove/docs/` | `~/.alcove/vaults/` |
| Индекс | Общий индекс проекта | Независимый индекс для каждого vault |
| Cache | `PROJECT_READER_CACHE` | `VAULT_READER_CACHE` |
| Поиск | `search_project_docs` | `search_vault` |
| Симлинк | Нет | Да (привязка внешних каталогов) |
### Конфигурация Vault
По умолчанию vault хранятся в `~/.alcove/vaults/`. Вы можете изменить это в своем `config.toml`:
```toml
[vaults]
root = "/path/to/your/vaults"
```
Дополнительные сведения о `config.toml` см. в разделе [Конфигурация](#конфигурация).
## Экосистема
### [obsidian-forge](https://github.com/epicsagas/obsidian-forge)
Alcove идеально сочетается с **obsidian-forge**, генератором хранилищ Obsidian и демоном автоматизации. Для наилучшей интеграции ваш Alcove **`docs_root`** должен указывать на архивы проектов obsidian-forge.
**1. Установка корня документов**
Укажите основной каталог документов на директорию проектов obsidian-forge (напрямую или через символьную ссылку):
```bash
# Во время настройки alcove установите docs_root в:
~/Obsidian/SecondBrain/99-Archives/projects
```
**2. Привязка областей знаний как хранилищ (vaults)**
Привяжите остальные три категории obsidian-forge как независимые хранилища Alcove. Это создаст символьные ссылки в `~/.alcove/vaults/`:
```bash
# Привязка категорий obsidian-forge
alcove vault link areas ~/Obsidian/SecondBrain/02-Areas
alcove vault link resources ~/Obsidian/SecondBrain/03-Resources
alcove vault link zettelkasten ~/Obsidian/SecondBrain/10-Zettelkasten
```
Теперь у ваших агентов есть структурированный доступ:
- **`search_project_docs`**: поиск по архивированным знаниям проекта (PRD и т. д.)
- **`search_vault`**: поиск по вашим более широким областям знаний и исследовательским заметкам.
Вы можете проверить сопоставление физического хранилища, просмотрев символьные ссылки в `~/.alcove/vaults/`.
## FAQ
### Почему бы просто не использовать ripgrep как MCP-инструмент?
Ripgrep возвращает файлы целиком. Если ваш агент ищет «auth» и находит 5 файлов по ~200 строк каждый, в контекст попадает ~10K токенов, бо́льшая часть которых не имеет отношения к делу. Alcove разбивает документы на фрагменты, ранжирует их и возвращает только самые релевантные отрывки. Кроме того, Alcove предоставляет семантический поиск на основе векторных эмбеддингов, который ripgrep не способен обеспечить — запрос вроде «как устроен конвейер развёртывания» не совпадёт ни с одним ключевым словом в вашем DEPLOYMENT.md, но векторный поиск Alcove его найдёт.
### Это заменяет CLAUDE.md / AGENTS.md?
Нет — у них разные цели. Конфигурационные файлы агентов (CLAUDE.md, AGENTS.md) определяют **поведенческие правила**: стиль коммитов, языковые предпочтения, ограничения безопасности. Alcove управляет **институциональными знаниями**: архитектурными решениями, отслеживанием прогресса, конвенциями кодирования, структурой кода. Конфиг агента — это *как агент должен действовать*. Alcove — это *что агент должен знать*.
### Почему Rust?
Единый бинарный файл, без зависимостей от среды выполнения. Tantivy — лучший в своём классе движок BM25. fastembed (ONNX Runtime) обеспечивает локальные векторные эмбеддинги без Python. Одна команда `cargo install` или curl — без Docker, без Node.js, без virtualenv.
### Что насчёт увеличения контекстных окон?
Бо́льшие окна не решают проблему релевантности. Даже 200K-токенное окно, заполненное нерелевантными документами, снижает качество вывода агента — собственная документация Anthropic предупреждает, что раздутые файлы конфигурации приводят к тому, что агенты игнорируют реальные инструкции. Цель не в большем контексте, а в правильном контексте в нужный момент.
## Дорожная карта
- **Многопользовательский удалённый доступ** — REST API для совместного доступа к документам команды через LAN/VPN (аутентификация по bearer-токену, ограничение скорости уже реализовано). Требуется: API записи, координация параллельных индексов, управление жизненным циклом проектов.
## Вклад в проект
Приветствуются сообщения об ошибках, запросы функций и pull request'ы. Откройте issue на [GitHub](https://github.com/epicsagas/alcove/issues), чтобы начать обсуждение.
## Лицензия
Apache-2.0