Bases de conhecimento

Arquitetura de base, item e revisão

Uma Knowledge Base é uma coleção de documentos de referência, especificações e runbooks no escopo do proprietário ou da equipe. Ela organiza o conhecimento técnico em três entidades hierárquicas distintas:

• Knowledge Base: O contêiner de nível superior (como "Engineering Runbooks"). Uma base tem nome, descrição, status (active ou archived) e propriedade de espaço (Personal ou Team).
• Knowledge Item: Um documento ou diretriz distinta dentro de uma base (como "Deployment Guidelines"). Um item tem título, localizador, status (draft, published ou archived), tipo de origem (user_created ou file) e um ponteiro current_revision_id.
• Knowledge Revision: Um snapshot imutável contendo conteúdo canônico, número de revisão, formato de conteúdo (como markdown), hash de conteúdo, metadados de origem e proveniência (provenance).
• Ciclo de vida de publicação: Um item começa com o status draft. Quando publicado, sua revisão atual torna-se detectável para agentes. Edições subsequentes criam novas revisões imutáveis e avançam o ponteiro atual sem alterar as revisões históricas.

Limites de publicação e visibilidade de agentes

As Knowledge Bases impõem limites estritos de publicação entre a autoria humana e a recuperação por agentes autônomos. Os chamadores escolhem entre busca por consulta (query search) e leitura endereçada (addressed read). As buscas por consulta protegem o frescor avaliando apenas itens publicados em suas revisões ativas atuais:

• Apenas bases ativas: Bases arquivadas são excluídas da descoberta de agentes. O arquivamento suspende a recuperação em todos os itens contidos sem destruir o conteúdo.
• Apenas itens publicados: Itens em rascunho (draft) permanecem privados para o autor e os editores da equipe até serem explicitamente publicados. Agentes não podem descobrir nem citar itens em rascunho em buscas por consulta.
• Revisão atual por padrão: A busca por consulta avalia apenas a revisão referenciada por current_revision_id. Revisões históricas substituídas não podem aparecer como resultados de busca por consulta.
• Leitura endereçada: Uma leitura endereçada pode inspecionar uma revisão histórica exata fornecendo knowledge_revision_id junto com knowledge_item_id, preservando citações reproduzíveis.

query search       -> active base + published item + current_revision_id
addressed (no pin) -> published item's current revision
addressed (pinned) -> exact immutable revision (e.g. knowledge:<item-id>@<revision-id>)

Modos de recuperação: Hybrid, RRF, Semantic e Lexical

O runtime de busca suporta quatro modos de recuperação para equilibrar precisão lexical e compreensão semântica:

• hybrid (padrão): Combinação linear de pontuações lexicais e semânticas normalizadas usando o parâmetro alpha (padrão 0.5). Alpha mais próximo de 1 favorece sobreposição lexical exata, enquanto alpha mais próximo de 0 favorece similaridade semântica conceitual. Recorre a lexical quando as pontuações vetoriais não estão disponíveis.
• rrf (Reciprocal Rank Fusion): Funde listas classificadas lexicais e semânticas independentes usando a constante de classificação k (padrão 60), garantindo uma ordenação equilibrada sem exigir calibração de pontuação.
• semantic: Classificação por similaridade vetorial baseada em representações de embeddings, recorrendo à correspondência lexical quando os embeddings não estão configurados.
• lexical: Correspondência normalizada de tokens e frases otimizada para símbolos exatos, nomes de funções, códigos de erro e chaves de configuração.

Tipos de arquivo suportados e pipelines de upload

Os itens de conhecimento podem ser criados diretamente em markdown ou importados de arquivos locais por meio de dois mecanismos distintos de ingestão:

• Arquivos de texto e código lidos no navegador: Arquivos de texto simples e código (.md, .markdown, .txt, .json, .csv, .py, .js, .ts, .tsx, .html, .yaml, .yml, .toml) são lidos diretamente no navegador e salvos como conteúdo canônico em markdown.
• Pipeline de extração de documentos: Documentos formatados (.pdf, .docx, .pptx, .xlsx) são enviados via Documents API, processados por workers de extração de texto e convertidos em snapshots como itens de Knowledge assim que a extração for bem-sucedida.
• Limites de arquivos: Os limites de ingestão se aplicam em ambientes de cliente e servidor. Para um processamento confiável, organize o conhecimento em documentos focados e modulares em vez de despejos de arquivos monolíticos.

Superfícies de acesso de agentes e perfis de cliente

Agentes autorizados acessam Knowledge por meio de ferramentas MCP dedicadas e comandos de Skill autônomos:

• MCP search_knowledge: Ferramenta de busca dedicada somente leitura que exige o escopo de token knowledge:read. Exposta especificamente nos perfis de cliente cursor-plugin e ordinary-full (config/mcp-documentation-contract.json); não exposta nos perfis chatgpt-public ou generic-public.
• MCP recall_context: Inclui automaticamente itens de Knowledge relevantes junto com a memória episódica quando Knowledge estiver habilitado para sua conta e o token incluir knowledge:read.
• Skill XMemo autônoma: Executa recall-context com inclusão explícita de conhecimento: node scripts/xmemo-skill.mjs recall-context --query "api authentication" --include_knowledge true.
• Aplicação de escopo: Nem todo recall consulta Knowledge automaticamente; a recuperação ocorre apenas quando configurada, permitida pelo escopo do token e suportada pelo perfil de cliente ativo.
• Complemento REST: O endpoint complementar autenticado POST /api/v1/knowledge/search fornece acesso programático direto à busca de conhecimento para serviços de backend e ferramentas personalizadas.

{
  "type": "knowledge_search",
  "results": [
    {
      "knowledge_item_id": "item_runbook_deploy",
      "knowledge_revision_id": "rev_v2_deploy_runbook",
      "title": "Production Deployment Runbook",
      "content": "Production deployments require two peer approvals, clean migration dry-runs, and verified canary health.",
      "reference": "knowledge:item_runbook_deploy@rev_v2_deploy_runbook",
      "score": 3.84
    }
  ]
}

Papéis de equipe, espaços e operações de ciclo de vida

As Knowledge Bases suportam espaços de trabalho pessoais e colaborativos com controle de acesso baseado em funções:

• Recursos das funções: Owner e Admin detêm direitos de base:admin e item:write (criar, arquivar, atualizar e excluir bases e itens). Member detém direitos de item:write (criar, editar e publicar itens, mas não pode excluir nem arquivar bases). Viewer detém apenas direitos de leitura.
• Limites de espaço: O espaço pessoal (/me#knowledge) é privado para o proprietário. O espaço de equipe (?space=<team_id>#knowledge) compartilha documentação publicada entre membros autenticados da equipe.
• Arquivamento vs Exclusão Permanente: Arquivar uma base define o status como archived, excluindo instantaneamente todos os itens das consultas de agentes e permitindo restauração completa. A exclusão permanente destrói fisicamente a base e todas as revisões associadas de forma irreversível.

Diferença da memória de projeto

As Knowledge Bases fornecem documentação de referência com curadoria, que opera sob garantias diferentes da memória conversacional de projeto:

• Itens de Knowledge Base: Documentos de referência versionados e com curadoria (como runbooks, documentos de design e padrões de codificação) com histórico de múltiplas revisões e referências de citação exatas (knowledge:<item-id>@<revision-id>).
• Memória de projeto Knowledge/Working: Registros de memória conversacional categorizados em um espaço de trabalho de projeto como contexto duradouro (knowledge) versus estado de tarefa transitório (working memory).
• Independência: Remover um registro de memória ou desvincular um documento de um projeto não modifica, arquiva nem exclui os itens subjacentes da Knowledge Base.

Disponibilidade e ativação em tempo de execução

A Knowledge Base é documentada como um recurso principal, não como Preview. A disponibilidade fica ativa se Knowledge estiver habilitado para sua conta. Quando o runtime de conhecimento do backend não estiver configurado ou estiver desabilitado, as requisições retornarão HTTP 503 com o código knowledge_runtime_disabled. As designações de plano de catálogo (como alocações do nível Plus) representam cotas de plano e não mecanismos de imposição em runtime; nenhuma rota de API impõe níveis de plano.