Coleções e vaults

Dois eixos diferentes, constantemente confundidos:

• Uma coleção é um namespace de conteúdo dentro de um tenant: team-notes, _valorbrain, baseline-2026-05-26. Os documentos o carregam; buscas podem ser escopadas a ele.
• Um vault é uma fonte de sync: um diretório nomeado de markdown que o engine pode ingerir e manter indexado (vault_sync, list_vaults). Várias ferramentas MCP aceitam um parâmetro vault para escopar leituras.

Coleções

Todo documento tem collection + path, e path é único dentro da coleção — esse par, não o título, é a identidade contra a qual você escreve. Re-POSTar o mesmo path re-entrega o mesmo documento em vez de duplicá-lo.

Quatro comportamentos que vale a pena conhecer antes de desenhar namespaces:

1. Dedup é por hash de conteúdo, entre coleções também. Os mesmos bytes não serão indexados duas vezes, nem em duas coleções — uma postura curatorial deliberada, não um bug. Se duas coleções precisam de "o mesmo" texto, elas precisam de conteúdos diferentes (headers, datas, contexto diferentes).
2. Cobertura ≠ curadoria. Puxar um corpus externo para dentro pode prejudicar a recuperação: milhares de documentos quase-clones poluem o pool de candidatos de toda query. Faça ingest apenas daquilo sobre o que o seu tenant realmente pergunta.
3. collection_settings é onde a política mora — incluindo excludePatterns, a forma deliberada de dizer "arquivos nesta coleção são recusados por política" (dados pessoais curados, sobras de experimento) para que relatórios de cobertura mostrem recusas esperadas em vez de divergência.
4. _valorbrain é a coleção padrão para escritas de memory_store que não nomeiam uma — decisões, lições e observações caem lá a menos que você diga o contrário.

Endpoints: GET /collections (lista com contagens), GET /collections/health (estado de embedding/lifecycle por coleção), POST /api/v1/collection-settings/{collection} (política), POST /api/v1/collection-settings/reindex (reconstrução), POST /collections/{id}/lifecycle (executa o lifecycle de uma coleção).

Vaults

Um vault mapeia um diretório para um estado indexado e buscável:

• vault_sync — ingere/atualiza um vault (operação longa; run_async: true devolve um handle, operation_status o consulta).
• list_vaults — vaults configurados e seus caminhos.
• O parâmetro vault nas ferramentas de leitura escopa a recuperação aos documentos de um vault.

O vault não isola identidade. A identidade de uma entidade é (tenant_id, entity_id) — o tenant é a fronteira de isolamento, não o vault; dois vaults num mesmo tenant compartilham o grafo de entidades. Se você precisa de isolamento total entre dois mundos, isso são dois tenants.

Escolhendo

Dicas de nomeação que envelhecem bem: datas para baselines (baseline-2026-05-26), dono + propósito para coleções vivas (team-notes), e nunca um nome que implique que uma pessoa é a única leitora — memória de tenant é compartilhada por design, e visibility: private é o eixo por usuário.