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.
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.
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); // episodicGuia 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].
+------------------------------------------------------------------------------------------------------------------------+
| [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 | |
+------------------------------------------------------------------------------------------------------------------------+Fluxos de personas
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.
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.
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.
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.
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.
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.
Origem: Introdução