# Guia de bases de conhecimento Crie bases de conhecimento, carregue documentação técnica, publique itens versionados e permita que agentes recuperem fatos citados com procedência. - Canonical: https://docs.xmemo.dev/pt-br/docs/guides/knowledge-bases - Locale: pt-BR - Content-Locale: pt-BR - Canonical-Content-Digest: 1867d8b68c37e8f52cb96a448217aeea61bf2b42608d8931313472d77f22d9c6 - Edition-Digest: 2fa02a0119779406734c89cec04311d7f1b129641fc69d549a0006f66590f671 - Source-Revision: sha256:c0d24fff7e465ea3dbb6daf903fbcba1cab87eecc6514e3b935a312cafc20ddd ## Objetivo do usuário Mantenha bases de conhecimento estruturadas em seu espaço de trabalho pessoal ou de equipe, ingira documentos em markdown e formatos estruturados, publique revisões imutáveis verificadas e configure agentes autônomos para recuperar fatos citados com atribuição de fonte. ## Disponibilidade e pré-requisitos A criação e inspeção de bases de conhecimento estão disponíveis no console web em https://xmemo.dev/me#knowledge (espaço pessoal) ou https://xmemo.dev/me?space=#knowledge (espaço de equipe) se Knowledge estiver habilitado em sua conta. Antes de começar, verifique os seguintes pré-requisitos: - Requisito de autenticação: é necessária uma sessão de usuário ativa. Visitas não autenticadas são redirecionadas para /login (a página de login). - Escopos de token: o acesso programático requer knowledge:read para pesquisas e leituras endereçadas, e knowledge:write para criar ou editar itens. - Formatos de arquivo suportados: o leitor de texto e código no navegador suporta .md, .markdown, .txt, .json, .csv, .py, .js, .ts, .tsx, .html, .yaml, .yml e .toml. A extração de documentos suporta .pdf, .docx, .pptx e .xlsx. - Interface de arrastar e soltar: o console apresenta "Drag & drop files here" com o texto de ajuda "Supports PDF, Word, PowerPoint, Excel, Markdown, and text files (.pdf, .docx, .pptx, .xlsx, .md, .txt, .csv, .json, etc.)". ## 1. Criar uma base de conhecimento no console web Navegue até https://xmemo.dev/me#knowledge em seu navegador. Clique em "Create Knowledge Base" para abrir a caixa de diálogo de criação. Insira "Engineering Runbooks" em Name e "Operational runbooks and deployment procedures." em Description. Confirme a criação para inicializar a base ativa. ```bash # Access personal knowledge workspace https://xmemo.dev/me#knowledge # Access team knowledge workspace with explicit space parameter https://xmemo.dev/me?space=#knowledge ``` ## 2. Adicionar e publicar um item de conhecimento sintético Abra a base "Engineering Runbooks" recém-criada e clique em "Create Knowledge item" para criar uma entrada a partir de markdown ou arquivo local. Insira o título "Deployment Guidelines" e cole as instruções sintéticas iniciais. O item é inicializado com o status "draft": ```markdown ## Deployment Guidelines Production deployments require two peer approvals, clean migration dry-runs, and verified canary health. ``` ## 3. Publicar o item em rascunho para recuperação por agentes Enquanto estiver no status "draft", o item permanece visível apenas para editores humanos. Para torná-lo localizável por agentes, clique em "Publish". O console exibe a dica "Published content becomes eligible for authorized Knowledge search.". Uma vez confirmado, o item avança para o status "published", estabelecendo a revisão 1 como a revisão atual pesquisável. - Privacidade de rascunhos: itens em rascunho são excluídos da descoberta de agentes e da pesquisa por consulta. - Ação de publicação: publicar atualiza o status do item para "published" e define current_revision_id como a revisão 1. - Revisão imutável: o conteúdo canônico, o hash e os metadados da revisão 1 são preservados de forma imutável. ## 4. Recuperar conhecimento com citação de agente Agentes autorizados em ambientes de cliente que expõem search_knowledge (como cursor-plugin ou ordinary-full) podem consultar o runbook publicado. A ferramenta retorna trechos classificados com ponteiros explícitos de referência de citação: ```bash # Query knowledge via standalone Skill CLI node scripts/xmemo-skill.mjs recall-context --query "production deployments" --include_knowledge true ``` ## 5. Atualizar conteúdo e publicar uma nova revisão imutável Quando os procedimentos técnicos mudarem, abra "Deployment Guidelines" e clique em "Edit Knowledge item". Atualize o conteúdo para refletir os novos requisitos operacionais. Clique em "Save new revision". O console exibe "Saving content creates an immutable new revision. Metadata changes do not create a revision.": ```markdown ## Deployment Guidelines Production deployments require two peer approvals, clean migration dry-runs, verified canary health, and automated smoke verification. ``` ## Resultado observável Verifique o item publicado e a procedência de sua revisão no console web e por meio da busca do agente: - Distintivo do console: o cartão do item exibe o distintivo de status "Published" e aponta para a revisão ativa atual. - Linhagem de revisões: abrir "Revision history" mostra a revisão 2 como atual e a revisão 1 como histórica, com registros de data e hora e atribuição de autor. - Resultado de busca do agente: pesquisas por consulta avaliam exclusivamente a revisão 2. A revisão histórica 1 permanece acessível por leituras endereçadas especificando o knowledge_revision_id exato. ## O que os agentes podem acessar As bases de conhecimento impõem limites rígidos de acesso e visibilidade para a integração de agentes: - Apenas itens publicados: agentes não podem acessar itens em rascunho. As pesquisas por consulta avaliam apenas itens publicados em bases ativas. - Limite da revisão atual: a pesquisa por consulta resolve automaticamente para current_revision_id. Revisões substituídas não podem aparecer nos resultados de busca. - Disponibilidade de perfil: a ferramenta MCP somente leitura search_knowledge está disponível estritamente nos perfis de cliente cursor-plugin e ordinary-full (config/mcp-documentation-contract.json). Outros perfis de cliente utilizam recall_context, que inclui automaticamente Knowledge quando habilitado e autorizado. - Comportamento de recall: o MCP recall_context inclui Knowledge automaticamente quando Knowledge está habilitado em sua conta e o token inclui knowledge:read. Nem todo recall pesquisa em Knowledge. ## Limites de compartilhamento e armazenamento As bases de conhecimento mantêm isolamento estrito de espaços e limites de papéis administrativos: - Espaço pessoal versus de equipe: bases pessoais (/me#knowledge) são privadas para a conta. Bases de equipe (?space=#knowledge) impõem o controle de acesso por papéis da equipe (routes/knowledge.py:129-134). - Capacidades de papel: Owner e Admin possuem direitos de base:admin e item:write (criar, arquivar, atualizar e excluir bases e itens). Member possui direitos de item:write (criar, editar e publicar itens). Viewer possui apenas direitos de leitura. - Arquivamento versus exclusão permanente: arquivar ("Are you sure you want to archive knowledge base ''? Archived bases will no longer be retrieved by agents.") suspende a recuperação sem perda. A exclusão permanente ("Are you sure you want to permanently delete knowledge base '' and all its items? This action cannot be undone.") remove fisicamente os dados. - Independência da memória de projetos: as bases de conhecimento operam de maneira independente das partições de memória de trabalho e conhecimento de projetos. Desvincular uma memória de um projeto não afeta documentos da base de conhecimento. ## Recuperação de falhas Resolva problemas comuns de acesso e extração de bases de conhecimento usando as seguintes etapas de diagnóstico: - Extração de documento em andamento: ao carregar documentos .pdf, .docx, .pptx ou .xlsx, aguarde enquanto "Extraction is still in progress. Try again when it succeeds.". - Falha na extração de documento: se o processamento falhar, o console exibe "Extraction failed. Retry the Document from its existing Document surface first.". Verifique a integridade do arquivo ou carregue texto simples em markdown. - Item não retornado na consulta do agente: verifique se o status do item é "Published" (não "draft"), se a base está ativa (não arquivada) e se o token do cliente contém o escopo knowledge:read. - Conflito de atualização simultânea: se outro usuário ou agente atualizou o item enquanto sua edição estava aberta, o console exibe "This Knowledge item changed elsewhere. Refresh it and try again.". Atualize a página e reaplique as alterações. - Seleção do modo de pesquisa: se símbolos exatos de runbook ou chaves de configuração não forem localizados pela pesquisa híbrida, mude para o modo lexical (mode="lexical") para correspondência exata de tokens. ## Referência relacionada Continue explorando conceitos de bases de conhecimento, ferramentas associadas e gerenciamento de espaços de trabalho: - Conceitos: bases de conhecimento (/docs/concepts/knowledge-bases) — Modelo arquitetural, DAG de revisões e modos de recuperação. - Ferramentas: search_knowledge (/docs/tools/search-knowledge) — Referência da ferramenta para leituras endereçadas e parâmetros de busca. - Ferramentas: recall_context (/docs/tools/recall-context) — Ferramenta de empacotamento de contexto com recuperação automática de Knowledge. - Guias: Memory Console (/docs/guides/memory-console) — Guia completo de navegação pelo console web. - Conceitos: procedência e atribuição (/docs/concepts/provenance-attribution) — Envelopes de citação e atribuição de autor. ## Usuário do ChatGPT Dê ao ChatGPT acesso duradouro às suas preferências do XMemo, fatos do projeto, decisões e TODOs sem colar tokens bearer no chat. Conecte o servidor MCP hospedado do XMemo pelo fluxo OAuth do app ChatGPT/OpenAI e aprove a concessão memory:read e memory:write para sua conta do XMemo. Salve uma preferência de teste ou anotação de projeto, inicie um novo chat e peça ao ChatGPT para recuperá-la via XMemo antes de prosseguir. Se o OAuth falhar ou as ferramentas não aparecerem, saia do servidor MCP no app host, reconecte a URL do servidor XMemo e tente novamente antes de criar tokens diretos. ## Desenvolvedor Copilot / Codex Transfira decisões do repositório, convenções de código, notas de correção de bugs e histórico de tarefas entre agentes de IDE e CLI. Use OAuth para VS Code / GitHub Copilot e Gemini CLI quando disponível. Para Copilot CLI, Codex, Cursor ou outros clientes MCP diretos, mantenha XMEMO_KEY no ambiente local ou cofre de segredos e defina um XMEMO_AGENT_INSTANCE_ID estável. Registre uma decisão da base de código ou correção de bug e peça ao próximo agente de IDE ou CLI para recuperar o contexto relevante do XMemo antes de editar. Se as recuperações estiverem vazias, verifique o caminho da configuração MCP selecionada, a variável de ambiente XMEMO_KEY para clientes diretos e eventuais credenciais OAuth desatualizadas no app host. ## Líder de piloto de equipe / corporativo Avalie a memória compartilhada com controles de conta, atribuição de origem, fluxos de exportação/exclusão e evidências de configuração seguras para revisores. Crie ou acesse o espaço de trabalho protegido do XMemo, convide usuários aprovados e conecte cada cliente via OAuth ou credencial direta com escopo de acordo com os selos de disponibilidade. Peça para um membro do piloto salvar uma memória de equipe de teste, confirme a atribuição de origem no XMemo e revise os caminhos de exclusão/exportação e suporte. Se um membro não conseguir se conectar, verifique as permissões de função, aprovação OAuth, status de prontidão do cliente e orientações de suporte antes de emitir um novo token. ## Operador de agentes autônomos Permita que agentes headless ou agendados registrem progresso, recuperem decisões anteriores e mantenham uma identidade estável e não secreta de instância. Obtenha /api/v1/mcp/config/autonomous-agent. Prefira auth_modes.oauth quando o executor suportar OAuth + cabeçalhos personalizados; use auth_modes.xmemo_key com XMEMO_KEY de um cofre de segredos apenas para executores totalmente headless. Execute uma tarefa de teste que grave progresso no XMemo, reinicie o executor e confirme se ele recupera esse progresso usando o mesmo XMEMO_AGENT_INSTANCE_ID. Se a atribuição mudar ou as recuperações se dividirem entre instâncias, persista XMEMO_AGENT_INSTANCE_ID fora do git e verifique se o executor não o está gerando a cada início.