# Modelo de memória Entenda fatos duradouros, decisões, passagens de contexto e atribuição de origem antes de escolher uma integração. - Canonical: https://docs.xmemo.dev/pt-br/docs/concepts/memory-model - Locale: pt-BR - Content-Locale: pt-BR - Canonical-Content-Digest: 9ffe2da573b664ce4e37254715ed959c138dfd6b89262c6d0a1bda8dd473291a - Edition-Digest: fa7b23a7d560a5cdbfe4a4f620884d99c72d51df748db64283f683d480db1802 - Source-Revision: sha256:310bf66a9ffcf2384ebc6400fad1b1da9d01fa0cdadc9d129c9084e880334e73 ## O que o XMemo armazena O XMemo mantém contexto duradouro que continua útil depois que a conversa ou tarefa atual termina: fatos do projeto, decisões, preferências, correções e notas de passagem de contexto. Ruído transitório de conversa, respostas pontuais e saída bruta de ferramentas não pertencem à memória. - semântico — fatos duradouros e decisões que permanecem verdadeiros entre sessões. - episódico — algo que aconteceu, associado a um momento de uma tarefa ou sessão. - procedural — como uma tarefa é executada neste projeto. - de trabalho — estado ativo da tarefa atualmente em andamento. - identidade — informações estáveis sobre o proprietário ou o próprio agente. ## Escreva uma memória duradoura Uma escrita duradoura precisa do conteúdo, de um caminho lógico associado a um projeto ou namespace e do tipo de memória. É o caminho que as recuperações posteriores usam para filtrar. ```ts remember({ content: "Use OAuth for hosted ChatGPT connections.", path: "projects/memory-os/decisions" }) ``` ## Tipos de memória no SDK MemoryCandidate.memory_type aceita o mesmo conjunto por meio do SDK do TypeScript, então um evento de agente normalizado leva consigo o tipo sob o qual deve ser armazenado. ```ts import { normalizeAgentEvent, toMemoryCandidate } from '@xmemo/client'; const event = normalizeAgentEvent( { type: 'command_completed', command: 'pytest', exit_code: 0, output: '12 passed' }, { source: 'shell', defaultAgentId: 'codex' }, ); console.log(toMemoryCandidate(event).memory_type); // episodic ``` ## Guia interativo de procedência e ciclo de vida (Demonstração sintética) Uma demonstração passo a passo e verificável do ciclo de vida mostrando criação de memória, recuperação entre clientes, correção do usuário em tempo real com substituição de versão (v1 -> v2), proteção do orçamento de tokens, marcação de exclusão reversível e desmontagem sintética isolada. Cada etapa é respaldada por evidências de tempo de execução descartáveis sem nenhuma exposição de memórias de usuário reais: - Etapa 1 [STATE_1_CREATED_ACTIVE_V1]: O Agente A (Claude Desktop) grava a preferência inicial com autor imutável, hash de instância e metadados de dispositivo via tools.py::remember — Recibo: Status 200 OK, demo_mem_lifecycle_001@v1, ativo — Status: [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] — Limite: [DEMO_DATA: SYNTHETIC]. - Etapa 2 [STATE_2_ACCESSED_ATTRIBUTED]: O Agente B (Codex CLI) no mesmo escopo autorizado recupera imediatamente a memória com recibo de citação e zero desvio entre clientes via tools.py::recall — Recibo: Status 200 OK, citado demo_mem_lifecycle_001@v1 — Status: [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] — Limite: [DEMO_DATA: SYNTHETIC]. - Etapa 3 [STATE_3_CORRECTED_SUPERSEDED_V2]: O usuário corrige a sala e o horário da reunião via tools.py::update_memory. O VersionController cria um snapshot imutável de v1 com status='superseded' e promove o registro ativo para v2 — Recibo: Status 200 OK, v2, pai v1, diff: Room Orion -> Room Polaris — Status: [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] — Limite: [DEMO_DATA: SYNTHETIC]. - Etapa 4 [STATE_4_RETRIEVAL_FILTERED]: A consulta posterior recall seleciona apenas v2 ativa enquanto v1 obsoleta é estritamente filtrada da janela de contexto do LLM para evitar alucinações e economizar o orçamento de tokens — Recibo: Status 200 OK, selecionada v2, excluída v1 substituída — Status: [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] — Limite: [DEMO_DATA: SYNTHETIC]. - Etapa 5 [STATE_5_TOMBSTONE_DELETED]: O proprietário marca o fato como excluído via tools.py::forget. Ele é imediatamente excluído das consultas candidatas e movido para a lixeira com ação de restauração — Recibo: Status 200 OK, status: deleted, contagem de candidatos: 0 — Status: [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] — Limite: [DEMO_DATA: SYNTHETIC]. - Etapa 6 [STATE_6_RESET_PURGED]: A desmontagem descartável isolada (reset_synthetic_state) limpa os registros do escopo de demonstração para exatamente 0 linhas residuais no disco. A redefinição total da conta pessoal (POST /api/v1/me/memories/reset) é estritamente excluída — Recibo: teardown_status: SUCCESS_PURGED, residual_rows: 0, account_hard_reset_called: FALSE — Status: [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] — Limite: [DEMO_DATA: SYNTHETIC]. ```text +------------------------------------------------------------------------------------------------------------------------+ | [PROVENANCE & LIFECYCLE 6-STATE STATE MACHINE: DISPOSABLE HARNESS WALKTHROUGH] | | | | Agent A (Claude Desktop) XMemo FastMCP & Engine Agent B (Codex CLI) Demo Owner (Supervising) | | [04f9b8c2 / MacBook] [VersionController / Scope] [e81d7a31 / Workstation] [user:demo_owner] | | | | | | | | (1) remember(sync in Orion) | | | | | -------------------------------------> | | | | | | [STATE 1: Created Active v1] | | | | <------------------------------------- | | | | | Receipt: mem-001@v1 | | | | | | | (2) recall(sync) | | | | | | <--------------------------- | | | | | | [STATE 2: Cited @v1] | | | | | | ---------------------------> | | | | | | Citation: mem-001@v1 | | | | | | | (3) update_memory(Polaris) | | | | | <---------------------------------------------------------- | | | | | [STATE 3: Bump v2, Supersede v1] | | | | | ----------------------------------------------------------> | | | | | Receipt: mem-001@v2 (parent: v1) | | | | | | | | | | | (4) recall(Polaris) | | | | | | <--------------------------- | | | | | | [STATE 4: Select v2, | | | | | | Filter superseded v1] | | | | | | ---------------------------> | | | | | | Citation: mem-001@v2 only | | | | | | | (5) forget(mem-001) | | | | | <---------------------------------------------------------- | | | | | [STATE 5: Tombstone / Trash View] | | | | | ----------------------------------------------------------> | | | | | Receipt: status=deleted | | | | | | | | | | | (6) reset_synthetic_state() | | | | | <---------------------------------------------------------- | | | | | [STATE 6: Teardown Purge] | | | | | Scope purged: 0 residual rows (account reset excluded) | | | | | ----------------------------------------------------------> | | | | | Teardown Status: SUCCESS_PURGED | | +------------------------------------------------------------------------------------------------------------------------+ ``` ## 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.