Avaliação e comparativo

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).

{
  "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.

# 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.

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.