# Avaliação e comparativo Critérios de avaliação de arquitetura, checklist neutro de camada de memória, seleção baseada em cenários, benchmarks reproduzíveis e guia de migração. - Canonical: https://docs.xmemo.dev/pt-br/docs/guides/evaluate - Locale: pt-BR - Content-Locale: pt-BR - Canonical-Content-Digest: 0069e449eaa8f028d7308cb779002505a54942410f60a2fededb0cfff578c724 - Edition-Digest: 221a9485e13eb840b2df845710ccfeed4b7aa16bba5557a5710900a579804c54 - Source-Revision: sha256:a21dd7bbdb6629dd16a471cb65bb89a3850e15a29b88ca1f457ab66fcf565701 ## Dimensões de avaliação de arquitetura Avaliar sistemas de memória para agentes exige ir além da simples busca vetorial superficial para analisar a arquitetura de produção central: modelo de armazenamento, isolamento multilocatário, garantias de consistência, conformidade com protocolos, latência e legibilidade computacional. - Modelo de armazenamento: Metadados relacionais híbridos com embeddings vetoriais versus armazenamento puramente vetorial linear. A base relacional garante pushdown de filtro exato, registros de auditoria imutáveis e particionamento determinístico de escopos. - Isolamento multilocatário: Partições físicas forçadas por hardware ou servidor versus filtragem por metadados na camada de aplicação. Espaços compartilhados de agentes exigem vinculações de espaço assinadas criptograficamente. - Garantias de consistência: Consistência de leitura pós-escrita (read-your-writes) entre chamadas de ferramentas distribuídas versus janelas de consistência eventual que induzem alucinações em loops contínuos de agentes. - Conformidade de protocolo: Endpoints HTTP nativos do Model Context Protocol (MCP) Streamable versus wrappers proprietários que demandam adaptadores de SDK específicos por framework. - Legibilidade computacional: Respostas JSON estruturadas e determinísticas que aderem rigorosamente aos esquemas de ferramentas, sem mensagens de preenchimento ou envoltórios conversacionais. ## O que avaliar em qualquer camada de memória Avalie qualquer sistema de memória para agentes em sete dimensões fundamentais de produção: isolamento de escopo, atribuição do autor, exclusão no ciclo de vida, integração de protocolos, limites de taxa de concorrência, benchmarks reproduzíveis e recursos dependentes de plano. - Isolamento de escopo: Pergunte a qualquer fornecedor como as memórias de usuário, sessão, agente e espaço de trabalho são particionadas. O XMemo impõe uma hierarquia ortogonal de escopos de 4 níveis (user, session, agent, team/space) com isolamento de projeto nativo no limite de armazenamento (veja /docs/concepts/scopes e /docs/concepts/projects). - Atribuição e proveniência: Pergunte a qualquer fornecedor se toda gravação e mutação de memória pode ser rastreada até uma identidade verificada do autor e um evento de origem. O XMemo registra a atribuição do autor, impressões digitais de instâncias de agentes e metadados de proveniência em logs de auditoria e preserva o histórico de versões (versões superseded) com DAGs de atualização (veja /docs/concepts/agent-instance-identity e /docs/concepts/memory-model). - Exclusão e exportação: Pergunte a qualquer fornecedor como a plataforma suporta exclusão reversível por tombstone, redação permanente de conteúdo e exportação em massa de dados. O XMemo oferece estados de ciclo de vida governados (active, archived, deleted), exclusão reversível com restauração, redação permanente de conteúdo e exportação estruturada em JSON (veja /docs/concepts/memory-deletion e /docs/api/memory). - Integração MCP e REST: Pergunte a qualquer fornecedor se a camada de memória oferece suporte nativo ao Model Context Protocol (MCP) junto com endpoints REST padrão. O XMemo fornece um servidor MCP nativo via Streamable HTTP expondo um catálogo de ferramentas padrão congelado junto com endpoints REST autenticados em /v1/ (veja /docs/mcp/overview e /docs/api/authentication). - Limites de taxa: Pergunte a qualquer fornecedor como os limites de throughput de requisições e concorrência são impostos e comunicados aos clientes. O XMemo impõe limitação de taxa em tempo de execução regida pela camada api-authentication em vez de cotas estáticas publicadas, e os clientes não devem fixar suposições de cotas no código (veja /docs/api/authentication). - Benchmarks reproduzíveis: Pergunte a qualquer fornecedor se as declarações de precisão de recuperação e latência são verificáveis de forma independente com conjuntos de testes abertos e dados determinísticos. O XMemo publica contratos de benchmarks pertencentes ao repositório com conjuntos de dados determinísticos Golden Set (recall_golden_set.jsonl) e registros de execução imutáveis, separando a avaliação em memória de I/O de rede (veja /docs/guides/evaluate#reproducible-benchmark-methodology). - Recursos dependentes de plano: Pergunte a qualquer fornecedor quais processos em segundo plano e recursos avançados estão incluídos no runtime base versus restritos por planos comerciais. O XMemo inclui armazenamento de memória principal, busca, recuperação e a ferramenta reflect com 5 ações no runtime base, enquanto a reflexão Dream programada em segundo plano depende de flags de recursos e do plano/autorizações (predefinições: manual, daily ou weekly; veja /docs/concepts/how-xmemo-works e /docs/concepts/dream-reflection). ```json { "evaluation_checklist": { "dimensions": [ { "dimension": "Scope isolation", "question": "How are user, session, agent, and workspace memories segregated?", "xmemo_answer": "4-tier orthogonal scope hierarchy (user, session, agent, team/space) enforced at storage boundary (/docs/concepts/scopes)" }, { "dimension": "Attribution and provenance", "question": "Can every memory mutation be traced to a specific caller and event?", "xmemo_answer": "Caller attribution and agent instance fingerprints recorded in audit logs with version history (/docs/concepts/agent-instance-identity)" }, { "dimension": "Deletion and export", "question": "Does the system support soft deletion, hard redaction, and data export?", "xmemo_answer": "Tombstone soft-deletion with restoration, hard redaction, and structured export (/docs/concepts/memory-deletion)" }, { "dimension": "MCP and REST integration", "question": "Is the memory layer accessible via native MCP as well as HTTP REST?", "xmemo_answer": "Native Streamable HTTP MCP server with frozen tool catalog and authenticated REST endpoints (/docs/mcp/overview)" }, { "dimension": "Rate limits", "question": "How are request quotas communicated and enforced?", "xmemo_answer": "Runtime rate limiting governed by api-authentication without hard-coded client quotas (/docs/api/authentication)" }, { "dimension": "Reproducible benchmarks", "question": "Are retrieval accuracy and performance metrics independently verifiable?", "xmemo_answer": "Open repository-owned benchmark harness with deterministic golden set datasets and run traces (/docs/guides/evaluate#reproducible-benchmark-methodology)" }, { "dimension": "Plan-dependent features", "question": "Which features are core runtime versus gated by tier entitlements?", "xmemo_answer": "Core operations and 5-action reflect tool in base runtime; background Dream reflection is plan/entitlement-dependent (/docs/concepts/dream-reflection)" } ] } } ``` ## Guia de seleção baseado em cenários Avalie a topologia de suas cargas de trabalho, a organização da equipe e as exigências de governança para escolher o padrão adequado de arquitetura de memória. - Fluxos multiagente em múltiplos ambientes: Escolha uma camada de memória com suporte nativo a MCP, escopos compartilhados de projeto e sincronização multicliente ao orquestrar agentes no Claude Code, Cursor, ChatGPT, Codex e Gemini CLI. - Espaços corporativos e regulamentados: Priorize arquiteturas que ofereçam hierarquias ortogonais de escopo (user, session, agent, team/space), logs de auditoria com atribuição do autor e limites de locatários forçados por hardware ou servidor. - Loops autônomos de alta concorrência: Selecione arquiteturas dotadas de árvores de atualização versionadas, bloqueio otimista e consistência de leitura pós-escrita (read-your-writes) para evitar atualizações conflitantes e alucinações de memória obsoleta. ## Metodologia de benchmark reproduzível O XMemo fornece um conjunto de testes aberto e integrado ao repositório para avaliar a precisão de recuperação e as restrições de governança sob condições controladas. A arquitetura distingue rigorosamente entre avaliação sintética interna, latência de produção real e declarações públicas verificadas. - Contrato metodológico: Os benchmarks seguem um contrato de método congelado e reproduzível com conjuntos de dados golden determinísticos e rastreamentos de verificação registrados. - Benchmarks sintéticos internos: Executados hermeticamente via scripts/benchmark_runner.py usando tests/data/recall_golden_set.jsonl (SHA-256 7533FBDC...) para medir a qualidade do algoritmo de recuperação em memória e a lógica de classificação sem I/O de rede ou banco de dados. - Latência de produção real: A latência ponta a ponta inclui negociação TLS, trânsito de rede, transações de banco de dados e sobrecarga de isolamento multilocatário. Varia de acordo com a topologia de implantação (SaaS em nuvem vs. Docker auto-hospedado) e distância geográfica, não sendo representada por números sintéticos em memória. - Declarações públicas de desempenho: Todas as métricas relatadas devem citar um benchmark_run_id imutável e o relatório bruto do verificador proveniente de execuções de verificação. Alegações não verificadas de fornecedores e atalhos sintéticos são excluídos das asserções de linha de base. - Análise de caso limite: Registro de ocorrência documentada na qual entidades homônimas ('config.py' em dois projetos distintos) disputaram relevância sem qualificação explícita de escopo; resolvido com a inclusão de restrições explícitas de escopo de projeto. ```bash # Execute reproducible retrieval benchmark against golden set python scripts/benchmark_runner.py \ --track standard \ --dataset tests/data/recall_golden_set.jsonl \ --cache-state COLD_CACHE \ --output reports/custom_run_raw.json ``` ## Guia de migração para o XMemo A transição de armazenamentos chave-valor legados, bancos puramente vetoriais ou serviços externos para o XMemo segue quatro fases estruturadas. - Fase 1: Exporte os itens de memória existentes como fluxos JSON Lines contendo text, user_id, session_id e registros de data e hora created_at. - Fase 2: Mapeie os identificadores para a hierarquia de escopos do XMemo (user_id para owner, session_id para agent_instance_id ou project_id) e classifique os fatos pela durabilidade. - Fase 3: Faça a ingestão por meio da ferramenta de lote remember ou da API REST (/v1/memories) com os atributos devidos de escopo e proveniência. - Fase 4: Valide a precisão de recuperação e as fronteiras de isolamento multilocatário com recall_context antes de conceder permissões de escrita aos agentes. ```python import requests def migrate_legacy_record(legacy_item, api_key): payload = { "content": legacy_item["content"], "path": f"migration/{legacy_item.get('id', 'item')}", "scope": "project" if legacy_item.get("project_id") else "user", "metadata": {"source": "legacy_migration", "original_id": legacy_item.get("id")} } response = requests.post( "https://xmemo.dev/v1/memories", headers={"Authorization": f"Bearer {api_key}"}, json=payload ) response.raise_for_status() return response.json() ``` ## Limitações conhecidas e fronteiras operacionais Para prevenir utilizações inadequadas, conheça as fronteiras operacionais e decisões de arquitetura explícitas do XMemo. - Não é um banco de dados relacional genérico: O XMemo é otimizado para fatos, estados e habilidades de agentes; não substitui bancos primários corporativos para transações SQL complexas arbitrárias. - Não é repositório para despejo de arquivos não estruturados: Documentos com mais de 32 KB devem ser indexados em Bases de Conhecimento (Knowledge Bases) e não guardados como nós de memória inline. - Periodicidade de reflexão Dream: A superfície de API e ferramenta MCP reflect não expõe um agendador; o agendamento em segundo plano do Dream depende de flags de recursos e do plano/autorizações (predefinições: manual [padrão], daily no horário local 03:00 do proprietário, ou weekly), e a consolidação não é síncrona com as gravações. - Limites de requisições: Endpoints hospedados aplicam limites de taxa em tempo de execução regidos por api-authentication em vez de cotas estáticas publicadas; clientes não devem fixar suposições de cotas no código. ## 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.