<p align="center">
  <img src="../alcove.png" alt="Alcove" width="100%" />
</p>

<p align="center"><strong>Seu agente de IA não conhece seu projeto. O Alcove resolve.</strong></p>

<p align="center">
  <a href="../README.md">English</a> ·
  <a href="README.ko.md">한국어</a> ·
  <a href="README.ja.md">日本語</a> ·
  <a href="README.zh-CN.md">简体中文</a> ·
  <a href="README.es.md">Español</a> ·
  <a href="README.hi.md">हिन्दी</a> ·
  <a href="README.pt-BR.md">Português</a> ·
  <a href="README.de.md">Deutsch</a> ·
  <a href="README.fr.md">Français</a> ·
  <a href="README.ru.md">Русский</a>
</p>

<p align="center">
  <a href="https://glama.ai/mcp/servers/epicsagas/alcove"><img src="https://glama.ai/mcp/servers/epicsagas/alcove/badges/score.svg" height="20" alt="Glama MCP Score" /></a>
  <a href="https://crates.io/crates/alcove"><img src="https://img.shields.io/crates/v/alcove.svg" alt="crates.io" /></a>
  <a href="https://crates.io/crates/alcove"><img src="https://img.shields.io/crates/d/alcove.svg" alt="Downloads" /></a>
  <a href="../LICENSE"><img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="License" /></a>
  <a href="https://buymeacoffee.com/epicsaga"><img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-FFDD00?style=flat&logo=buy-me-a-coffee&logoColor=black" alt="Buy Me a Coffee" /></a>
</p>

O Alcove é um servidor MCP que dá a agentes de codificação com IA acesso sob demanda à documentação privada do seu projeto — **busca híbrida BM25 + vetorial** para recuperação precisa, **indexação de código com tree-sitter** para que os agentes entendam a estrutura da sua base de código, e **aplicação de políticas** para consistência da documentação. Sem inchar o contexto, sem vazar documentos em repositórios públicos, sem configuração por projeto para cada agente.

Mantenha PRDs, decisões de arquitetura, mapas de segredos e runbooks internos em um só lugar. Todo agente compatível com MCP recebe as mesmas ferramentas, em todos os projetos, sem configuração por projeto.

## Demonstração

![Demo do agente Alcove](../demo-agent.gif)
> *Claude, Codex — busca · troca de projeto · busca global · validar e gerar. Uma única configuração.*

<details>
<summary>Demo CLI</summary>

![Demo CLI do Alcove](../demo.gif)
> *`alcove search` · troca de projeto · `--scope global` · `alcove validate`*

</details>

## O problema

Seu agente de IA começa cada sessão do zero.

Ele não conhece sua arquitetura. Ignora restrições de decisões que você já tomou. Pede para você explicar as mesmas coisas em cada sessão.

A janela de contexto é o gargalo. Cada token custa dinheiro e atenção. Carregar 10 documentos de arquitetura no contexto desperdiça mais de 50K tokens em cada execução — e a própria documentação da Anthropic alerta que arquivos de configuração inchados fazem os agentes *ignorarem suas instruções reais*.

Então você tem três opções ruins:

**Enfiar tudo na configuração do agente** — cada arquivo é carregado no contexto em cada execução. 10 documentos = inchaço de contexto = respostas mais lentas, caras e imprecisas.

**Copiar e colar em cada chat** — funciona uma vez, não escala além de uma sessão.

**Não se preocupe** — seu agente inventa requisitos que você já documentou, ignora restrições de decisões que você já tomou, e você reexplica a mesma arquitetura toda segunda de manhã.

Multiplique por 5 projetos e 3 agentes. Toda vez que você troca, perde o contexto.

## Como o Alcove resolve isso

O Alcove mantém todos os seus documentos privados em **um único repositório compartilhado**, organizado por projeto. Qualquer agente compatível com MCP os acessa da mesma forma — seja no Claude Code, Cursor, Antigravity ou Codex.

```
~/projects/my-app $ claude "/alcove como a autenticação é implementada?"

  → Alcove detecta o projeto: my-app
  → Lê ~/documents/my-app/ARCHITECTURE.md
  → Agente responde com o contexto real do projeto
```

```
~/projects/my-api $ codex "/alcove revise o design da API"

  → Alcove detecta o projeto: my-api
  → Mesma estrutura de documentos, mesmo padrão de acesso
  → Projeto diferente, mesmo fluxo de trabalho
```

**Troque de agente a qualquer momento. Troque de projeto a qualquer momento. A camada de documentos permanece padronizada.**

## O que ele faz

- **Um repositório de documentos, vários projetos** — documentos privados organizados por projeto, gerenciados em um único lugar
- **Uma configuração, qualquer agente** — configure uma vez, todo agente compatível com MCP recebe o mesmo acesso
- **Detecta automaticamente seu projeto** a partir do CWD — sem necessidade de configuração por projeto
- **Acesso com escopo** — cada projeto vê apenas seus próprios documentos
- **Busca inteligente** — busca BM25 com ranking e indexação automática; encontra os documentos mais relevantes primeiro, recorre ao grep quando necessário
- **Busca entre projetos** — busque em todos os projetos de uma vez com `scope: "global"` — use como base de conhecimento pessoal
- **Documentos privados permanecem privados** — documentos sensíveis (mapa de segredos, decisões internas, dívida técnica) nunca tocam seu repositório público
- **Estrutura de documentos padronizada** — `policy.toml` garante documentos consistentes em todos os projetos e equipes
- **Auditoria entre repositórios** — encontra documentos internos mal posicionados no repositório do projeto, sugere correções
- **Validação de documentos** — verifica arquivos ausentes, templates não preenchidos, seções obrigatórias
- **Lint semântico** — detecta wikilinks quebrados, arquivos órfãos, marcadores WIP/DRAFT obsoletos e referências de datas com mais de 2 anos
- **Importação de vault externo** — traz uma nota do Obsidian (ou qualquer vault) para o doc-repo com um único comando; roteamento automático para o projeto correto
- **Funciona com mais de 9 agentes** — Claude Code, Cursor, Claude Desktop, Cline, OpenCode, Codex, Copilot, Antigravity

## Por que Alcove

| Sem Alcove | Com Alcove |
|------------|------------|
| Documentos internos espalhados entre Notion, Google Docs, arquivos locais | Um repositório de documentos, estruturado por projeto |
| Cada agente de IA configurado separadamente para acesso a documentos | Uma configuração, todos os agentes compartilham o mesmo acesso |
| Trocar de projeto significa perder o contexto dos documentos | Detecção automática por CWD, troca instantânea de projeto |
| Buscas do agente retornam linhas aleatórias | Busca híbrida (BM25 + RAG) — os agentes extraem apenas o que precisam, ordenado por relevância |
| O agente só vê documentos de texto, não a estrutura do código | Indexação de código com tree-sitter — os agentes entendem módulos, funções e tipos em 12 linguagens |
| "Buscar todas as minhas notas sobre autenticação" — impossível | Busca global em todos os projetos em uma única consulta |
| Documentos sensíveis com risco de vazar em repositórios públicos | Documentos privados fisicamente separados dos repositórios de projeto |
| Estrutura de documentos varia por projeto e membro da equipe | `policy.toml` garante padrões em todos os projetos |
| Sem como verificar se os documentos estão completos | `validate` detecta arquivos ausentes, templates vazios, seções faltando |
| Links quebrados ou marcadores WIP passam despercebidos | `lint` detecta automaticamente links quebrados, órfãos e marcadores obsoletos |
| Notas do Obsidian ou outras ferramentas ficam isoladas | `promote` integra notas externas ao doc-repo com um único comando |

## Início rápido

> **Obrigatório**: Execute `alcove setup` uma vez após a instalação para configurar o diretório de documentos e ativar todas as funcionalidades. Os plugins registram a conexão MCP automaticamente, mas o Alcove não pode pesquisar ou indexar documentos até que `setup` seja executado.
>
> **Usa Obsidian?** Veja a seção [Ecossistema](#ecosystem) para a estrutura de documentos recomendada e configuração de cofres.

### Claude Code

```
/plugin marketplace add epicsagas/plugins
/plugin install alcove@epicsagas
```

Instala automaticamente o binário e registra o servidor MCP na próxima inicialização de sessão.

> **Obrigatório**: Execute `alcove setup` uma vez após a instalação para configurar sua raiz de documentos e habilitar a funcionalidade completa. O plugin semeia a conexão MCP automaticamente, mas o Alcove não pode pesquisar ou indexar documentos até que o `setup` tenha sido executado.

```bash
alcove setup   # execute uma vez após a instalação do plugin
```

Atualizações com `claude plugin update epicsagas/alcove`.

### Codex CLI

```bash
codex plugin marketplace add epicsagas/plugins
```

Instala automaticamente a skill e registra o servidor MCP. As skills estão disponíveis imediatamente — nenhum passo adicional necessário.

Atualizações com `codex plugin update alcove@epicsagas`.

### macOS (somente Apple Silicon)

```bash
brew install epicsagas/tap/alcove
```

Não tem Homebrew? Use o script de instalação:

```bash
curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/epicsagas/alcove/releases/latest/download/alcove-installer.sh | sh
```

> **Nota**: Binários pré-compilados estão disponíveis somente para macOS Apple Silicon. Usuários de Linux e Windows podem usar os instaladores de uma linha acima.

### 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
```

Instala automaticamente o plugin (servidor MCP, skill, hooks) e o registra no próximo início de sessão.

```bash
alcove setup   # run once after plugin install
```

### Via cadeia de ferramentas Rust

```bash
cargo binstall alcove   # binário pré-compilado (rápido)
cargo install alcove    # compilar a partir do código-fonte
```

> **Nota**: Binários pré-compilados estão disponíveis para Linux (x86\_64), macOS (Apple Silicon e Intel) e Windows.

### Configuração inicial (obrigatória)

Após instalar por qualquer método acima, execute:

```bash
alcove setup
alcove --version
alcove doctor
```

`setup` guia você por tudo interativamente:

1. Onde seus documentos ficam
2. Quais categorias de documentos rastrear
3. Formato de diagrama preferido
4. Modelo de embeddings para busca híbrida
5. **Servidor em segundo plano** — eliminar o cold-start em cada sessão (item de login do macOS)
6. Quais agentes de IA configurar (MCP + arquivos de habilidades — Claude Code e Codex são gerenciados por seus sistemas de plugins)

Execute `alcove setup` novamente a qualquer momento para alterar as configurações. Ele lembra das suas escolhas anteriores.

**Dependências opcionais**

| Ferramenta | Finalidade | Instalação |
|---|---|---|
| `pdftotext` (poppler) | Extração completa de texto PDF — necessária para busca em 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) |

Sem `pdftotext`, o Alcove recorre a um parser PDF integrado que pode falhar em alguns arquivos. Execute `alcove doctor` para verificar sua instalação.

### Solução de problemas

**O agente não encontra as ferramentas do Alcove**
Execute `alcove setup` novamente — ele recadastra o servidor MCP para todos os agentes configurados. Depois inicie uma nova sessão do agente (o registro entra em vigor no próximo início de sessão).

**A busca não retorna resultados**
O índice pode ainda não ter sido construído. Execute `alcove index` para construí-lo e tente novamente.

**403 Unauthorized do servidor em segundo plano**
`ALCOVE_TOKEN` não está definido no seu shell. Execute `alcove token` para exibi-lo, adicione `export ALCOVE_TOKEN="..."` ao seu perfil de shell e recarregue.

**`alcove doctor` relata problemas**
Siga as sugestões exibidas por `doctor` — ele verifica a localização do binário, registro MCP, estado do índice e dependências opcionais como `pdftotext`.

## Uso

### Busca via CLI

Busque em seus documentos diretamente pelo terminal. Por padrão, ele busca em **todos os projetos** (escopo global).

```bash
# Busca básica (escopo global)
alcove search "authentication"

# Limitar a busca ao projeto atual (detectado automaticamente via CWD)
alcove search "auth flow" --scope project

# Forçar modo grep (correspondência exata de substring)
alcove search "TODO" --mode grep

# Forçar modo ranqueado (BM25/Híbrido)
alcove search "data model" --mode ranked

# Ajustar limite de resultados
alcove search "deployment" --limit 5
```

### Agentes de Codificação (MCP)

Os agentes de codificação de IA usam o Alcove por meio de **ferramentas MCP**. Geralmente, você não precisa chamá-las manualmente; o agente as invocará quando você fizer perguntas sobre seu projeto.

| Objetivo | Ferramenta do Agente | Descrição |
|----------|-----------------------|-----------|
| **Explorar** | `get_project_docs_overview` | Lista todos os arquivos no projeto atual para entender a estrutura. |
| **Buscar** | `search_project_docs` | Busca por palavras-chave ou conceitos específicos. Suporta `scope: "global"`. |
| **Ler** | `get_doc_file` | Lê o conteúdo de um arquivo específico encontrado durante a busca. |
| **Auditar** | `audit_project` | Verifica se há documentos faltando ou inconsistências entre o código e os documentos. |

**Exemplo de interação com o agente:**
> **Usuário:** "/alcove Como adiciono um novo endpoint de API?"
> **Agente:** (chama `search_project_docs(query="add api endpoint")`)
> **Agente:** (lê o documento mais relevante via `get_doc_file`)
> **Agente:** "De acordo com o `ARCHITECTURE.md`, você precisa..."

---

## Como funciona

```mermaid
flowchart LR
    subgraph Projects["Seus projetos"]
        A1["my-app/\n  src/ ..."]
        A2["my-api/\n  src/ ..."]
    end

    subgraph Docs["Seus documentos privados (um repositório)"]
        D1["my-app/\n  PRD.md\n  ARCH.md"]
        D2["my-api/\n  PRD.md\n  ..."]
        P1["policy.toml"]
    end

    subgraph Agents["Qualquer agente MCP"]
        AG["Claude Code · Cursor\nCodex · Copilot\n+4 more"]
    end

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

    A1 -- "CWD detectado" --> D1
    A2 -- "CWD detectado" --> D2
    Agents -- "stdio MCP" --> MCP
    MCP -- "acesso com escopo" --> Docs
```

Seus documentos são organizados em um diretório separado (`DOCS_ROOT`), uma pasta por projeto. O Alcove gerencia os documentos e os serve para qualquer agente de IA compatível com MCP via stdio.

## Classificação de documentos

O Alcove classifica documentos nos seguintes níveis:

| Classificação | Onde fica | Exemplos |
|---------------|-----------|----------|
| **doc-repo-required** | Alcove (privado) | PRD, Arquitetura, Decisões, Convenções |
| **doc-repo-supplementary** | Alcove (privado) | Implantação, Integração, Testes, Runbook |
| **reference** | Alcove pasta `reports/` | Relatórios de auditoria, benchmarks, análises |
| **project-repo** | Seu repositório GitHub (público) | README, CHANGELOG, CONTRIBUTING |

A ferramenta `audit` escaneia o repositório de documentos e o diretório local do projeto, e sugere ações — como gerar um README público a partir do seu PRD privado, ou mover relatórios mal posicionados de volta para o alcove.

## Ferramentas MCP

| Ferramenta | O que faz |
|------------|-----------|
| `get_project_docs_overview` | Lista todos os documentos com classificação e tamanhos |
| `search_project_docs` | Busca inteligente — seleciona automaticamente BM25 com ranking ou grep, suporta `scope: "global"` para busca entre projetos |
| `get_doc_file` | Lê um documento específico pelo caminho (suporta `offset`/`limit` para arquivos grandes) |
| `list_projects` | Mostra todos os projetos no seu repositório de documentos |
| `audit_project` | Auditoria entre repositórios — escaneia o repo de documentos e o projeto local, sugere ações |
| `init_project` | Cria estrutura de documentos para um novo projeto (documentos internos+externos, criação seletiva) |
| `validate_docs` | Valida documentos contra a política da equipe (`policy.toml`) |
| `rebuild_index` | Reconstrói o índice de busca de texto completo (normalmente automático) |
| `check_doc_changes` | Detecta documentos adicionados, modificados ou excluídos desde a última indexação |
| `lint_project` | Lint semântico — links quebrados, órfãos, marcadores obsoletos e datas antigas |
| `promote_document` | Copiar ou mover um arquivo de um vault externo para o alcove doc-repo |
| `index_code_structure` | Analisa o código-fonte com tree-sitter e gera `CODE_INDEX.md` por projeto |

## CLI

```
alcove              Inicia o servidor MCP (agentes chamam isso)
alcove setup        Configuração interativa — execute novamente a qualquer momento para reconfigurar
alcove doctor       Verificar a integridade da instalação do Alcove
alcove validate     Valida documentos contra a política (--format json, --exit-code)
alcove lint         Lint semântico — links quebrados, órfãos, marcadores obsoletos (--format json)
alcove promote      Importar notas de um vault externo para o doc-repo
alcove index        Atualizar o índice de busca (incremental — apenas arquivos alterados)
alcove rebuild      Reconstruir o índice de busca do zero (usar após mudanças de esquema)
alcove search       Busca documentos pelo terminal
alcove index-code   Gera índice de estrutura de código do fonte [--language LANG] [--source PATH]
alcove token        Exibir o bearer token (para autenticação do servidor em segundo plano)
alcove uninstall    Remove habilidades, configuração e arquivos legados

alcove mcp <CMD>      Gerencie o ciclo de vida do servidor MCP em segundo plano (start, stop, status, enable, disable)

alcove vault link     Vincular um diretório externo como um vault (ex: Obsidian)
alcove vault list     Listar todos os vaults com contagem de documentos
alcove vault index    Construir o índice de busca para os vaults
```

### Indexação de código

Analisa arquivos fonte com tree-sitter e gera `CODE_INDEX.md`—um resumo Markdown em nível de módulo da sua base de código, integrado ao pipeline de busca Tantivy.

```bash
# Indexar o projeto atual (detecta todos os idiomas automaticamente)
alcove index-code --source ./src

# Monorepo: indexar um diretório com múltiplas linguagens de uma vez
alcove index-code --source ./

# Restringir a uma única linguagem
alcove index-code --source ./src --language typescript
alcove index-code --source ./src --language rust
```

**Linguagens suportadas:**

| Linguagem | Feature flag | Extensões de arquivo |
|-----------|-------------|---------------------|
| 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` |

Os binários oficiais habilitam todos os 12 parsers (`lang-all`). Sem `--language`, **todas as extensões reconhecidas são indexadas automaticamente**—seguro para monorepos.

`--language` aceita abreviações: `ts` → TypeScript, `cpp` → C++, `csharp` → C#, `py` → Python, `js` → JavaScript, `kt` → Kotlin, `rb` → Ruby.

### Lint

```bash
# Lint do projeto atual (detectado automaticamente pelo CWD)
alcove lint

# Especificar projeto
alcove lint --project my-app

# Saída legível por máquina para CI
alcove lint --format json
```

O lint verifica quatro coisas:

| Verificação | O que detecta |
|-------------|--------------|
| `broken-link` | `[[wikilinks]]` ou `[texto](caminho)` apontando para arquivos inexistentes |
| `orphan` | Arquivos para os quais nenhum outro documento aponta |
| `stale-marker` | Marcadores WIP / TODO / FIXME / DRAFT / DEPRECATED |
| `stale-date` | Referências de data com mais de 2 anos (ex.: "as of 2022") |

### Promote

```bash
# Copiar uma nota do Obsidian para o doc-repo (roteamento automático)
alcove promote ~/my-brain/Projects/auth-notes.md

# Rotear para um projeto específico
alcove promote ~/my-brain/Projects/auth-notes.md --project my-app

# Mover em vez de copiar
alcove promote ~/my-brain/Projects/auth-notes.md --mv
```

Arquivos sem projeto correspondente são salvos em `inbox/` para revisão manual.

## Servidor em Segundo Plano

Executar um servidor persistente em segundo plano elimina a latência de inicialização a frio em cada nova sessão do agente. **`alcove setup` ativa isso por padrão** (item de login no macOS).

```bash
alcove mcp enable --now     # Ativar e iniciar (persiste após reinicializações)
alcove mcp stop / start / restart / status
alcove mcp disable          # Desativar e remover item de login
```

Quando o servidor em segundo plano está em execução, o processo stdio atua como um proxy leve — em vez de carregar o motor de busca a cada sessão, ele encaminha as requisições para o servidor ativo. Na inicialização, o processo stdio verifica `GET /health` e entra automaticamente no modo proxy.

## Busca

O Alcove seleciona automaticamente a melhor estratégia de busca. Quando o índice de busca existe, usa **busca BM25 com ranking** (baseada em [tantivy](https://github.com/quickwit-oss/tantivy)) para resultados ordenados por relevância. Quando não existe, recorre ao grep. Você nunca precisa pensar nisso.

### Busca Híbrida (RAG)

O Alcove suporta **Busca Híbrida** que combina BM25 com **Busca de Similaridade Vetorial** (baseada em [fastembed](https://github.com/ankane/fastembed-rs)).

Durante `alcove setup`, você pode escolher um modelo de embeddings e baixá-lo imediatamente. Você também pode gerenciar modelos manualmente:

```bash
# Definir e baixar um modelo de embeddings
alcove model set MultilingualE5Small
alcove model download

# Verificar status do modelo
alcove model status
```

#### Escolha do modelo

| Modelo | Disco | Dim | Idiomas | Melhor para | RAM de pico |
|--------|-------|-----|---------|-------------|-------------|
| `AllMiniLML6V2` | 90 MB | 384 | Inglês | Menor footprint, indexação rápida apenas em inglês | ~400 MB |
| **`MultilingualE5Small`** | **235 MB** | **384** | **100+ idiomas** | **Padrão — projetos multilíngues / mistos** | **~700 MB** |
| `MultilingualE5Base` | 555 MB | 768 | 100+ idiomas | Melhor qualidade multilíngue | ~2 GB |
| `MultilingualE5Large` | 2.2 GB | 1024 | 100+ idiomas | Máxima qualidade multilíngue | ~7 GB |
| `BGEM3` | 2.3 GB | 1024 | 100+ idiomas | Multilíngue de última geração | ~8 GB |
| `ArcticEmbedXS` | 90 MB | 384 | Inglês | Snowflake — melhor qualidade em 384 dim | ~400 MB |
| `ArcticEmbedS` | 130 MB | 384 | Inglês | Snowflake — recuperação aprimorada em tamanho pequeno | ~500 MB |
| `ArcticEmbedM` | 430 MB | 768 | Inglês | Snowflake — qualidade de recuperação de trabalho | ~1.5 GB |
| `ArcticEmbedL` | 1.3 GB | 1024 | Inglês | Snowflake — competitivo com APIs de código fechado | ~5 GB |

Uma vez que um modelo está baixado e pronto, o Alcove usará automaticamente Busca Híbrida tanto para busca via CLI quanto para ferramentas MCP baseadas em agentes. Isso é particularmente eficaz para projetos multilíngues e consultas semânticas complexas.

```bash
# Buscar no projeto atual (auto-detectado pelo CWD)
alcove search "authentication flow"

# Buscar em TODOS os projetos — sua base de conhecimento pessoal
alcove search "OAuth token refresh" --scope global

# Forçar modo grep se precisar de correspondência exata de substrings
alcove search "FR-023" --mode grep
```

O índice é construído automaticamente em segundo plano quando o servidor MCP inicia, e reconstruído quando detecta mudanças nos arquivos. Sem cron jobs, sem etapas manuais.

**Como funciona para agentes:** agentes simplesmente chamam `search_project_docs` com uma consulta. O Alcove cuida do resto — ranking, deduplicação (um resultado por arquivo), busca entre projetos e fallback. O agente nunca precisa escolher um modo de busca.

**Memória durante rebuild:**
A RAM de pico varia por modelo — consulte a coluna "RAM de pico" na tabela acima. Modelos grandes (BGEM3, MultilingualE5Large, ArcticEmbedL) podem usar 5-10 GB durante rebuild. Após o rebuild, o estado estacionário cai para ~50-200 MB dependendo da sua configuração `[memory]`. Você pode reduzir ainda mais com `max_hnsw_cache` mais baixo e `model_unload_secs` mais curto.

## Detecção de projeto

Por padrão, o Alcove detecta o projeto atual a partir do diretório de trabalho do seu terminal (CWD). Você pode sobrescrever com a variável de ambiente `MCP_PROJECT_NAME`:

```bash
MCP_PROJECT_NAME=my-api alcove
```

Útil quando seu CWD não corresponde a um nome de projeto no seu repositório de documentos.

## Política de documentos

Defina padrões de documentação para toda a equipe com `policy.toml` no seu repositório de documentos:

```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
```

Arquivos de política são resolvidos com prioridade: **projeto** (`<project>/.alcove/policy.toml`) > **equipe** (`DOCS_ROOT/.alcove/policy.toml`) > **padrão integrado** (lista de arquivos core do config.toml). Isso garante qualidade consistente dos documentos em todos os seus projetos, permitindo substituições por projeto.

## Configuração

A configuração fica em `~/.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"
```

Tudo isso é configurado interativamente via `alcove setup`. Você também pode editar o arquivo diretamente.

## Agentes suportados

| Agente | MCP | Habilidade |
|--------|-----|------------|
| Claude Code | `~/.claude.json` | `~/.claude/skills/alcove/` |
| Cursor | `~/.cursor/mcp.json` | `~/.cursor/skills/alcove/` |
| Claude Desktop | configuração da plataforma | — |
| 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` | — |

## Idiomas suportados

O CLI detecta automaticamente o locale do seu sistema. Você também pode substituí-lo com a variável de ambiente `ALCOVE_LANG`.

| Idioma | Código |
|--------|--------|
| English | `en` |
| 한국어 | `ko` |
| 简体中文 | `zh-CN` |
| 日本語 | `ja` |
| Español | `es` |
| हिन्दी | `hi` |
| Português (Brasil) | `pt-BR` |
| Deutsch | `de` |
| Français | `fr` |
| Русский | `ru` |

```bash
# Substituir idioma
ALCOVE_LANG=pt-BR alcove setup
```

## Atualizar

| Método | Comando |
|--------|---------|
| Homebrew | `brew upgrade alcove` |
| curl installer | Execute novamente o script de instalação acima |
| cargo binstall | `cargo binstall alcove@latest` |
| cargo install | `cargo install alcove@latest` |
| Claude Code Plugin | `claude plugin update epicsagas/alcove` |

```bash
alcove --version
```

## Desinstalar

```bash
alcove uninstall          # remove habilidades e configuração
cargo uninstall alcove    # remove o binário
```

## Vaults de Base de Conhecimento

Além da documentação do projeto, o Alcove suporta **vaults de base de conhecimento independentes** para notas de pesquisa, materiais de referência e conhecimento curado que LLMs podem buscar.

```bash
# Criar um vault para notas de pesquisa de IA
alcove vault create ai-research

# Vincular um vault Obsidian existente (sem cópia — indexa no local)
alcove vault link meu-obsidian ~/Obsidian/research

# Adicionar um documento
alcove vault add ai-research ~/Downloads/transformer-survey.md

# Construir o índice de busca do vault
alcove vault index

# Listar todos os vaults
alcove vault list
#   areas (8 docs) → (linked)
#   resources (71 docs) → (linked)
#   zettelkasten (17 docs) → (linked)

# Buscar pelo CLI
alcove search "attention mechanism" --vault ai-research

# Agentes buscam via MCP
search_vault(query="attention mechanism", vault="ai-research")

# Buscar em TODOS os vaults de uma vez
search_vault(query="transformer", vault="*")
```

Os vaults são **completamente isolados** dos docs do projeto — índices separados, caches separados, busca separada. A busca de documentos de projeto do seu agente de codificação nunca é afetada pela atividade do vault.

| Funcionalidade | Documentos do projeto | Vaults |
|---------|-------------|--------|
| Propósito | Documentação por projeto | Base de conhecimento geral |
| Armazenamento | `~/.alcove/docs/` | `~/.alcove/vaults/` |
| Índice | Índice de projeto compartilhado | Índice independente por vault |
| Cache | `PROJECT_READER_CACHE` | `VAULT_READER_CACHE` |
| Busca | `search_project_docs` | `search_vault` |
| Symlink | Não | Sim (vincular diretórios externos) |

### Configuração de Vault

Por padrão, os vaults são armazenados em `~/.alcove/vaults/`. Você pode alterar isso no seu `config.toml`:

```toml
[vaults]
root = "/caminho/para/seus/vaults"
```

Consulte a seção de [Configuração](#configuração) para mais detalhes sobre o `config.toml`.

## Ecossistema

### [obsidian-forge](https://github.com/epicsagas/obsidian-forge)

O Alcove combina perfeitamente com o **obsidian-forge**, um gerador de cofres Obsidian e daemon de automação. Para a melhor integração, o seu **`docs_root`** do Alcove deve apontar para os arquivos de projeto do obsidian-forge.

**1. Definir a Raiz de Documentos**
Aponte seus documentos principais para o diretório de projetos do obsidian-forge (diretamente ou via link simbólico):
```bash
# Durante a configuração do alcove, defina docs_root como:
~/Obsidian/SecondBrain/99-Archives/projects
```

**2. Vincular Áreas de Conhecimento como Vaults**
Vincule as outras três categorias do obsidian-forge como vaults independentes do Alcove. Isso cria links simbólicos em `~/.alcove/vaults/`:
```bash
# Vincular categorias do 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
```

Agora seus agentes têm acesso estruturado:
- **`search_project_docs`**: Busca conhecimento de projetos arquivados (PRDs, etc.)
- **`search_vault`**: Busca em suas áreas de conhecimento mais amplas e notas de pesquisa.

Você pode verificar o mapeamento do armazenamento físico verificando os links simbólicos em `~/.alcove/vaults/`.

## FAQ

### Por que não usar apenas o ripgrep como ferramenta MCP?

O ripgrep retorna arquivos inteiros. Se o seu agente busca por "auth" e encontra 5 arquivos com uma média de 200 linhas cada, isso injeta cerca de 10K tokens no contexto — a maior parte irrelevante. O Alcove fragmenta os documentos, classifica os trechos e retorna apenas as passagens mais relevantes. Ele também oferece busca semântica (embeddings vetoriais) que o ripgrep não consegue — uma consulta como "como o pipeline de deploy é estruturado" não vai corresponder a nenhuma palavra-chave no seu DEPLOYMENT.md, mas a busca vetorial do Alcove vai encontrar.

### Isso substitui o CLAUDE.md / AGENTS.md?

Não — eles servem a propósitos diferentes. Arquivos de configuração do agente (CLAUDE.md, AGENTS.md) definem **regras comportamentais**: estilo de commit, preferências de idioma, restrições de segurança. O Alcove gerencia o **conhecimento institucional**: decisões de arquitetura, acompanhamento de progresso, convenções de codificação, estrutura do código. A configuração do agente serve para *como o agente deve agir*. O Alcove serve para *o que o agente deve saber*.

### Por que Rust?

Binário único, sem dependência de runtime. O Tantivy é o melhor BM25 da categoria. O candle-transformers nos oferece embeddings vetoriais locais sem ONNX ou Python. Um `cargo install` ou curl — sem Docker, sem Node.js, sem virtualenv.

### E as janelas de contexto cada vez maiores?

Janelas maiores não resolvem o problema de relevância. Mesmo uma janela de 200K tokens preenchida com documentos irrelevantes degrada a qualidade da saída do agente — a própria documentação da Anthropic alerta que arquivos de configuração inchados fazem os agentes ignorarem as instruções reais. O objetivo não é mais contexto, é o contexto certo no momento certo.

## Roteiro

- **Acesso remoto multi-usuário** — API REST para compartilhamento de documentos da equipe via LAN/VPN (autenticação por bearer token, limitação de taxa já implementada). Necessário: API de escrita, coordenação de índice concorrente, gerenciamento do ciclo de vida do projeto.

## Contribuindo

Relatórios de bugs, solicitações de funcionalidades e pull requests são bem-vindos. Abra um issue no [GitHub](https://github.com/epicsagas/alcove/issues) para iniciar uma discussão.

## Licença

Apache-2.0
