# Como o XMemo funciona Arquitetura autoritativa e fronteira pública: composição do servidor, ciclo de vida, nós de subsistema e nuvem. - Canonical: https://docs.xmemo.dev/pt-br/docs/concepts/how-xmemo-works - Locale: pt-BR - Content-Locale: pt-BR - Canonical-Content-Digest: 321f29a0f9c36406e495bc50c7110f64ee7680a5bf2706f6b5eef7ecfa09163d - Edition-Digest: 8daeb33d9ce2f531f65f9592a050b1f18de1bb9e7fec1791d0af7e0e0723d033 - Source-Revision: sha256:8310426b563698994f72fce9d60572391625bf1c49e90527246490ed5f7a65b5 ## Arquitetura simplificada: O pipeline de memória em 7 etapas O XMemo processa as memórias dos agentes por meio de um pipeline de 7 etapas (Capture → Scope → Retrieve → Rerank → Assemble → Govern → Consolidate). Cada etapa cumpre uma responsabilidade dedicada para assegurar operações rápidas, precisas, isoladas e verificáveis: - Capture: Recebe solicitações de gravação e atualização de memória de clientes de IA via Model Context Protocol (MCP) padrão ou APIs REST, e higieniza dados confidenciais antes do armazenamento. O que isso significa para você: Seus agentes podem salvar notas, decisões e preferências automaticamente por meio de ferramentas padrão sem expor segredos ou dados pessoais. - Scope: Resolve o contexto de identidade do chamador e aplica limites rígidos multilocatário entre camadas de usuário, sessão, agente e espaço de trabalho. O que isso significa para você: Cada agente acessa apenas a memória dentro de seu limite autorizado, mantendo os dados pessoais e da equipe isolados com segurança. - Retrieve: Pesquisa memórias armazenadas usando um mecanismo híbrido que combina embeddings vetoriais semânticos com correspondência exata de palavras-chave. O que isso significa para você: Seu agente recupera os fatos corretos, seja pesquisando pelo significado do tópico ou buscando uma frase ou identificador exato. - Rerank: Avalia e pontua memórias candidatas equilibrando relevância semântica, recência e pesos de importância. O que isso significa para você: Seu agente recebe o contexto mais relevante e atualizado em vez de fragmentos obsoletos ou de baixa prioridade. - Assemble: Empacota as memórias recuperadas em um contexto pronto para o prompt, aplicando estritamente orçamentos de tokens e bytes. O que isso significa para você: A memória injetada nunca estoura a janela de contexto do seu modelo nem gera custos imprevistos de tokens. - Govern: Registra logs de auditoria operacional, rastreia o histórico de versões (memory_versions) e aplica envelopes de criptografia quando o modo keyguard/vault está ativo. O que isso significa para você: Cada atualização de memória é rastreável, verificável e recuperável com total responsabilidade de auditoria. - Consolidate: Pré-visualiza a consolidação de memória (Dream) para sintetizar interações episódicas recentes em insights candidatos estruturados, exigindo confirmação humana antes de salvar. O que isso significa para você: Insights úteis são preparados para sua revisão sem mutações automáticas inesperadas ou lentidão nos chats interativos dos agentes. ## Aspectos internos da arquitetura / Evidências Detalhes autorizados de implementação arquitetônica, rastreamentos de execução e contratos empíricos verificados diretamente na base de código do XMemo. As seções a seguir documentam a composição concreta de tempo de execução, limites isolados de subsistemas e matrizes de verificação formal. ## Invariantes arquiteturais e princípios fundamentais O XMemo aplica invariantes arquiteturais inegociáveis que separam as superfícies públicas de clientes da execução de subsistemas internos. Os recursos são vinculados ao código-fonte sob a política de zero exposição de segredos em texto simples. - Zero exposição de segredos em texto simples: Arquivos de configuração do cliente, logs e respostas nunca contêm tokens Bearer ou senhas sem criptografia. - Proveniência de origem verificada: Toda memória persistida, revisão e citação carrega metadados imutáveis e trilhas de auditoria vinculadas a contratos de código. - Orçamentos determinísticos de tokens e bytes: A injeção de contexto de recuperação respeita estritamente os limites, evitando estouro de janela do LLM. - Limites de planos e portas de recursos: BYODB multilocatário, sincronização distribuída e agendamento Dream em segundo plano são controlados por configurações explícitas do espaço de trabalho, flags de recursos e limites de plano. ## Composição do servidor e topologia do ciclo de vida A inicialização do servidor desacopla a composição no momento da implantação dos rastreamentos de execução. Os clientes não montam o servidor; o servidor Starlette monta o FastMCP e o adapta via MemoryOSMcpMountAdapter. - Step 1 [HOST_COMPOSITION]: O servidor host Starlette/FastAPI monta FastMCP em /mcp — Relação: SERVER_MOUNTS_APP — Subsistema: Montagem do servidor ASGI — Limite: Entrada HTTP pública. - Step 2 [MOUNT_ADAPTER]: mount_streamable_mcp encapsula streamable_http_app em MemoryOSMcpMountAdapter para gerenciar CORS e escopo — Relação: ADAPTS_ASGI_APP — Subsistema: Adaptador de protocolo — Limite: Ponte de protocolo. - Step 3 [AUTH_REGISTRATION]: install_mcp_tool_surface registra _call_tool_with_oauth_errors como manipulador de ferramentas — Relação: REGISTERS_TOOL_WRAPPER — Subsistema: Gate de identidade e despacho — Limite: Superfície de ferramentas autenticada. ```text +---------------------------------------------------------------------------------------------------+ | [DEPLOYMENT-TIME SERVER COMPOSITION & TOPOLOGY: 2 INDEPENDENT BRANCHES] | | | | [BRANCH 1: SERVER ASGI MOUNT BRANCH] | | +-------------------------------------------------------+ | | | Host ASGI Server (Starlette / FastAPI) | [PUBLIC_BOUNDARY] | | | Role: FastMCP Host Ingress Gateway | [PUBLIC_BOUNDARY] | | +-------------------------------------------------------+ | | | | | | Relation: SERVER_MOUNTS_APP | | | Status: [PUBLIC_BOUNDARY (VERIFIED)] | | v | | +-------------------------------------------------------+ | | | mount_streamable_mcp | [INTERNAL_SUBSYSTEM] | | | Role: Streamable HTTP Application Adapter | [INTERNAL_SUBSYSTEM] | | +-------------------------------------------------------+ | | | | | | Relation: ADAPTS_ASGI_APP | | | Status: [INTERNAL_SUBSYSTEM (VERIFIED)] | | v | | +-------------------------------------------------------+ | | | MemoryOSMcpMountAdapter | [PUBLIC_BOUNDARY] | | | Role: ASGI Protocol Bridge & Connection Handler | [PUBLIC_BOUNDARY] | | +-------------------------------------------------------+ | | | | [BRANCH 2: TOOL SURFACE REGISTRATION BRANCH] | | +-------------------------------------------------------+ | | | install_mcp_tool_surface | [INTERNAL_SUBSYSTEM] | | | Role: MCP Tool Surface Registration Pipeline | [INTERNAL_SUBSYSTEM] | | +-------------------------------------------------------+ | | | | | | Relation: REGISTERS_TOOL_WRAPPER | | | Status: [INTERNAL_SUBSYSTEM (VERIFIED)] | | v | | +-------------------------------------------------------+ | | | FastMCP Tool Ingress Wrapper (_call_tool_with_oauth) | [PUBLIC_BOUNDARY] | | | Role: Authenticated Tool Invocation & Error Handler | [PUBLIC_BOUNDARY] | | +-------------------------------------------------------+ | +---------------------------------------------------------------------------------------------------+ ``` ## Rastreamentos de execução em tempo de execução Em tempo de execução, as solicitações seguem quatro fluxos isolados e determinísticos governados por relações estritas e classificações explícitas de limites arquitetônicos: - OP_REMEMBER_WRITE [Lembrar / Fluxo de escrita: 13 etapas]: Cliente externo [PUBLIC_INGRESS] -> MemoryOSMcpMountAdapter [TRANSPORT_ADAPTER] -> Despacho FastMCP ASGI -> Gate de autenticação -> Ferramenta remember -> Gate de verificação -> Envelope de sanitização PII -> Envelope de segurança (criptografia quando o modo keyguard/vault está ativo) -> Motor de persistência. 13 etapas verificadas de ponta a ponta. - OP_RECALL_READ [Recuperar / Fluxo de leitura: 12 etapas]: Cliente externo [PUBLIC_INGRESS] -> MemoryOSMcpMountAdapter [TRANSPORT_ADAPTER] -> Despacho FastMCP ASGI -> Gate de autenticação -> Ferramenta recall -> Isolamento multi-inquilino BoundSpace -> Motor de busca híbrido -> Reclassificador semântico -> Montador de orçamento -> Formatador de citação pública. 12 etapas verificadas. - OP_UPDATE_VERSION [Atualizar / Fluxo de versão: 13 etapas]: Cliente externo [PUBLIC_INGRESS] -> MemoryOSMcpMountAdapter [TRANSPORT_ADAPTER] -> Despacho FastMCP ASGI -> Gate de autenticação -> Ferramenta update_memory -> Gate de verificação -> Envelope de sanitização PII -> Envelope de segurança (criptografia quando o modo keyguard/vault está ativo) -> Motor de persistência -> Controlador DAG de histórico de versão. 13 etapas verificadas. - OP_FORGET_LIFECYCLE [Esquecer / Fluxo de ciclo de vida: 11 etapas]: Cliente externo [PUBLIC_INGRESS] -> MemoryOSMcpMountAdapter [TRANSPORT_ADAPTER] -> Despacho FastMCP ASGI -> Gate de autenticação -> Ferramenta forget -> Gate de verificação -> Persistência de tombstone suave -> Daemon de retenção -> Filtro de exclusão de consulta. 11 etapas verificadas. ```text +------------------------------------------------------------------------------------------------------------------------+ | [RUNTIME EXECUTION TRACES: 4 CANONICAL OPERATION FLOW DIAGRAMS] | | | | 1. OP_REMEMBER_WRITE [WRITE INGRESS FLOW: 13 STEPS] | | Step 1: External Client --[CLIENT_REQUESTS_ENDPOINT]--> MemoryOSMcpMountAdapter | | Boundary: Public Ingress Gateway [PUBLIC_BOUNDARY] | | Step 2: MemoryOSMcpMountAdapter --[DELEGATES_ASGI_REQUEST]--> FastMCP.streamable_http_app | | Boundary: ASGI Streamable Mount Adapter [INTERNAL_SUBSYSTEM] | | Step 3: FastMCP --[DISPATCHES_TOOL_INVOCATION]--> _call_tool_with_oauth_errors | | Boundary: Tool Surface Ingress Gate [INTERNAL_SUBSYSTEM] | | Step 4: _call_tool_with_oauth_errors --[DISPATCHES_TOOL]--> remember tool | | Boundary: MCP Tool Dispatch Handler [PUBLIC_BOUNDARY] | | Step 5: remember tool --[CALLS]--> Identity Context Resolver | | Boundary: Identity & Authentication Context [INTERNAL_SUBSYSTEM] | | Step 6: remember tool --[CALLS]--> Workspace Setup Gate | | Boundary: Workspace Initialization Gate [INTERNAL_SUBSYSTEM] | | Step 7: Workspace Setup Gate --[CALLS]--> Initialization Validator | | Boundary: Setup Verification Gate [INTERNAL_SUBSYSTEM] | | Step 8: remember tool --[CALLS]--> Write Preparation Pipeline | | Boundary: Memory Write Preparation [INTERNAL_SUBSYSTEM] | | Step 9: Write Preparation Pipeline --[CALLS]--> PII Sanitization Envelope | | Boundary: Sensitive Data Redaction [INTERNAL_SUBSYSTEM] | | Step 10: Write Preparation Pipeline --[CALLS]--> Security Envelope (encryption when keyguard/vault mode is active)| | Boundary: Cryptographic Security Envelope [INTERNAL_SUBSYSTEM] | | Step 11: remember tool --[CALLS]--> Tenant Isolation Envelope | | Boundary: Multi-Tenant Workspace Binding [INTERNAL_SUBSYSTEM] | | Step 12: remember tool --[CALLS]--> Memory Manager Core Engine | | Boundary: Core Memory Management [INTERNAL_SUBSYSTEM] | | Step 13: Memory Manager Core Engine --[CALLS]--> Persistence Storage Engine | | Boundary: Persistent Storage Engine [INTERNAL_SUBSYSTEM] | | | | 2. OP_RECALL_READ [READ RETRIEVAL FLOW: 12 STEPS] | | Step 1: External Client --[CLIENT_REQUESTS_ENDPOINT]--> MemoryOSMcpMountAdapter | | Boundary: Public Ingress Gateway [PUBLIC_BOUNDARY] | | Step 2: MemoryOSMcpMountAdapter --[DELEGATES_ASGI_REQUEST]--> FastMCP.streamable_http_app | | Boundary: ASGI Streamable Mount Adapter [INTERNAL_SUBSYSTEM] | | Step 3: FastMCP --[DISPATCHES_TOOL_INVOCATION]--> _call_tool_with_oauth_errors | | Boundary: Tool Surface Ingress Gate [INTERNAL_SUBSYSTEM] | | Step 4: _call_tool_with_oauth_errors --[DISPATCHES_TOOL]--> recall tool | | Boundary: MCP Tool Dispatch Handler [PUBLIC_BOUNDARY] | | Step 5: recall tool --[CALLS]--> Search Memory Implementation | | Boundary: Search Query Coordinator [INTERNAL_SUBSYSTEM] | | Step 6: Search Memory Implementation --[CALLS]--> Identity Context Resolver | | Boundary: Identity & Authentication Context [INTERNAL_SUBSYSTEM] | | Step 7: Search Memory Implementation --[CALLS]--> BoundSpace Multi-Tenant Isolation | | Boundary: Scope Isolation Boundary [INTERNAL_SUBSYSTEM] | | Step 8: Search Memory Implementation --[CALLS]--> Memory Manager Search Service | | Boundary: Core Search Controller [INTERNAL_SUBSYSTEM] | | Step 9: Memory Manager Search Service --[CALLS]--> Hybrid Retrieval Engine | | Boundary: Hybrid Vector & Text Retrieval [INTERNAL_SUBSYSTEM] | | Step 10: Hybrid Retrieval Engine --[CALLS]--> Semantic Relevance Reranker | | Boundary: Candidate Scorer & Reranker [INTERNAL_SUBSYSTEM] | | Step 11: Hybrid Retrieval Engine --[CALLS]--> Response Budget Assembler | | Boundary: Token & Byte Budget Manager [INTERNAL_SUBSYSTEM] | | Step 12: Response Budget Assembler --[CALLS]--> Public Citation & Receipt Formatter | | Boundary: Provenance Citation Formatter [PUBLIC_BOUNDARY] | | | | 3. OP_UPDATE_VERSION [VERSIONING & CORRECTION FLOW: 13 STEPS] | | Step 1: External Client --[CLIENT_REQUESTS_ENDPOINT]--> MemoryOSMcpMountAdapter | | Boundary: Public Ingress Gateway [PUBLIC_BOUNDARY] | | Step 2: MemoryOSMcpMountAdapter --[DELEGATES_ASGI_REQUEST]--> FastMCP.streamable_http_app | | Boundary: ASGI Streamable Mount Adapter [INTERNAL_SUBSYSTEM] | | Step 3: FastMCP --[DISPATCHES_TOOL_INVOCATION]--> _call_tool_with_oauth_errors | | Boundary: Tool Surface Ingress Gate [INTERNAL_SUBSYSTEM] | | Step 4: _call_tool_with_oauth_errors --[DISPATCHES_TOOL]--> update_memory tool | | Boundary: MCP Tool Dispatch Handler [PUBLIC_BOUNDARY] | | Step 5: update_memory tool --[CALLS]--> Identity Context Resolver | | Boundary: Identity & Authentication Context [INTERNAL_SUBSYSTEM] | | Step 6: update_memory tool --[CALLS]--> Workspace Setup Gate | | Boundary: Workspace Initialization Gate [INTERNAL_SUBSYSTEM] | | Step 7: update_memory tool --[CALLS]--> Scope Validation Gate | | Boundary: Workspace Scope Boundary [INTERNAL_SUBSYSTEM] | | Step 8: update_memory tool --[CALLS]--> Write Preparation Pipeline | | Boundary: Memory Write Preparation [INTERNAL_SUBSYSTEM] | | Step 9: Write Preparation Pipeline --[CALLS]--> PII Sanitization Envelope | | Boundary: Sensitive Data Redaction [INTERNAL_SUBSYSTEM] | | Step 10: update_memory tool --[CALLS]--> Tenant Isolation Envelope | | Boundary: Multi-Tenant Workspace Binding [INTERNAL_SUBSYSTEM] | | Step 11: update_memory tool --[CALLS]--> Memory Manager Core Engine | | Boundary: Core Memory Management [INTERNAL_SUBSYSTEM] | | Step 12: Memory Manager Core Engine --[CALLS]--> Persistence Storage Engine | | Boundary: Persistent Storage Engine [INTERNAL_SUBSYSTEM] | | Step 13: Persistence Storage Engine --[CALLS]--> Immutable Version DAG Controller | | Boundary: Version DAG Supersession Engine [INTERNAL_SUBSYSTEM] | | | | 4. OP_FORGET_LIFECYCLE [RETENTION & LIFECYCLE FLOW: 11 STEPS] | | Step 1: External Client --[CLIENT_REQUESTS_ENDPOINT]--> MemoryOSMcpMountAdapter | | Boundary: Public Ingress Gateway [PUBLIC_BOUNDARY] | | Step 2: MemoryOSMcpMountAdapter --[DELEGATES_ASGI_REQUEST]--> FastMCP.streamable_http_app | | Boundary: ASGI Streamable Mount Adapter [INTERNAL_SUBSYSTEM] | | Step 3: FastMCP --[DISPATCHES_TOOL_INVOCATION]--> _call_tool_with_oauth_errors | | Boundary: Tool Surface Ingress Gate [INTERNAL_SUBSYSTEM] | | Step 4: _call_tool_with_oauth_errors --[DISPATCHES_TOOL]--> forget tool | | Boundary: MCP Tool Dispatch Handler [PUBLIC_BOUNDARY] | | Step 5: forget tool --[CALLS]--> Identity Context Resolver | | Boundary: Identity & Authentication Context [INTERNAL_SUBSYSTEM] | | Step 6: forget tool --[CALLS]--> Workspace Setup Gate | | Boundary: Workspace Initialization Gate [INTERNAL_SUBSYSTEM] | | Step 7: forget tool --[CALLS]--> Memory Manager Core Engine | | Boundary: Core Memory Management [INTERNAL_SUBSYSTEM] | | Step 8: Memory Manager Core Engine --[CALLS]--> Persistence Storage Engine | | Boundary: Persistence Tombstone Engine [INTERNAL_SUBSYSTEM] | | Step 9: Background Lifecycle Daemon --[BATCH_POLICY_EVALUATION]--> Retention Policy Evaluator | | Boundary: Archive Policy Evaluation [INTERNAL_SUBSYSTEM] | | Step 10: Background Lifecycle Daemon --[BATCH_POLICY_EVALUATION]--> Importance Decay Evaluator | | Boundary: Importance Decay Engine [INTERNAL_SUBSYSTEM] | | Step 11: Hybrid Retrieval Engine --[EXCLUDES_AT_QUERY]--> Database Storage Engine | | Boundary: Query-Time Tombstone Filter [INTERNAL_SUBSYSTEM] | +------------------------------------------------------------------------------------------------------------------------+ ``` ## Decomposição de subsistemas e classificação de limites O sistema se decompõe em dez nós de subsistema verificados. Cada nó possui uma classificação estrita de limite (PUBLIC_BOUNDARY ou INTERNAL_SUBSYSTEM) e status empírico de evidência (SOURCE_BACKED_PUBLIC_CONTRACT / VERIFIED, CONCEPTUAL_DELEGATED ou NOT_VERIFIED): - NODE_1_CLIENT_AGENT_LAYER: Ecossistema de cliente e agente (@xmemo/client, Claude Desktop, Cursor, Codex) — Classificação: [PUBLIC_BOUNDARY] — Status da evidência: [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)]. - NODE_2_TRANSPORT_ADAPTER: Adaptador de protocolo e transporte MCP (MemoryOSMcpMountAdapter, mount_streamable_mcp) — Classificação: [PUBLIC_BOUNDARY] — Status da evidência: [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)]. - NODE_3_IDENTITY_AUTH_GATE: Gateway de autorização e identidade (_call_tool_with_oauth_errors, install_mcp_tool_surface) — Classificação: [PUBLIC_BOUNDARY] — Status da evidência: [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)]. - NODE_4_SANITIZATION_ENVELOPE: Sanitização de PII e envelope do cofre (sanitize_server_write, enforce_memory_write_envelope) — Classificação: [INTERNAL_SUBSYSTEM] — Status da evidência: [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)]. - NODE_5_SCOPE_ISOLATION_GUARD: Guarda de isolamento de escopo e multi-inquilino (BoundSpace, assert_requested_team_matches_bound_space) — Classificação: [INTERNAL_SUBSYSTEM] — Status da evidência: [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)]. - NODE_6_SEARCH_TEMPORAL_PARSER: Analisador de consultas temporais e pesquisa (TemporalQuerySpec, extract_temporal_context) — Classificação: [INTERNAL_SUBSYSTEM] — Status da evidência: [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)]. - NODE_7_CANDIDATE_SCORER: Pontuador e reclassificador de candidatos (SearchEngine.rerank_recall_results) — Classificação: [INTERNAL_SUBSYSTEM] — Status da evidência: [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)]. - NODE_8_VERSION_LIFECYCLE_ENGINE: Controlador de ciclo de vida e versão (VersionController.superseded_snapshot) — Classificação: [INTERNAL_SUBSYSTEM] — Status da evidência: [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)]. - NODE_9_CONTEXT_BUDGET_ASSEMBLER: Montador de orçamento de contexto (_apply_recall_response_budget) — Classificação: [INTERNAL_SUBSYSTEM] — Status da evidência: [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)]. - NODE_10_PUBLIC_RECEIPT_CITATION: Formatador de citação e recibo público (_public_recall_meta) — Classificação: [PUBLIC_BOUNDARY] — Status da evidência: [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)]. ## Fronteira entre código aberto e serviço em nuvem gerenciado Declarações públicas são avaliadas contra o contrato de código e classificadas estritamente como VERIFIED ou NOT_VERIFIED: - STMT_01_PROVENANCE_ATTRIBUTION [VERIFIED]: O XMemo registra logs de auditoria operacional, preserva o histórico de versões (memory_versions) e aplica envelopes de criptografia quando o modo keyguard/vault está ativado. Arquitetura: Envelope de segurança criptográfica. - STMT_02_CROSS_CLIENT_CONTINUITY [VERIFIED]: Memórias capturadas ficam instantaneamente disponíveis em qualquer cliente compatível com MCP via JSON-RPC. Arquitetura: Adaptador FastMCP ASGI com suporte a streaming. - STMT_03_REALTIME_CORRECTION [VERIFIED]: Atualizações de fatos mantêm histórico imutável substituindo memórias conflitantes anteriores. Arquitetura: Controlador DAG de versão imutável. - STMT_04_TOKEN_BUDGET_GUARANTEE [VERIFIED]: A injeção de contexto de recuperação respeita rigorosamente os orçamentos especificados. Arquitetura: Montador determinístico de orçamento de tokens. - STMT_05_ZERO_TOKEN_EXPOSURE [VERIFIED]: Solicitações não autenticadas são negadas no gateway sem expor tokens ou executar consultas. Arquitetura: Gate de autenticação de entrada e isolamento de escopo. - STMT_06_BACKEND_OPEN_SOURCE_CLAIM [NOT_VERIFIED]: A alegação de backend 100% de código aberto é REFUTADA. Apenas pacotes de cliente (@xmemo/client) e adaptadores locais MCP são abertos. A infraestrutura em nuvem multi-inquilino é proprietária. - STMT_07_AUTONOMOUS_CONSENSUS_CLAIM [NOT_VERIFIED]: Consenso autônomo entre organizações é REFUTADO. O isolamento de inquilinos é estrito via BoundSpace; não há mesclagem automática entre inquilinos. - STMT_08_ZERO_LATENCY_REPLICATION_CLAIM [NOT_VERIFIED]: Replicação global com latência zero é REFUTADA. A busca usa índices vetoriais locais; latência zero global não é garantida. ## Roteiro reproduzível do ciclo de vida da arquitetura (Exemplo sintético A/B) Um passo a passo verificável do ciclo de vida que demonstra o compartilhamento de memória entre agentes, isolamento multilocatário, correção do usuário em tempo real e rastreamento imutável de proveniência com dados de demonstração estritamente sintéticos: - Step 1 [AGENT_A_WRITE]: Agente A (ide-assistant-alpha) grava preferência sintética via remember tool no escopo project:synthetic-demo — Payload: {'formatting': 'tabs', 'indent': 4} — Claim: [STMT_01_PROVENANCE_ATTRIBUTION] & [STMT_02_CROSS_CLIENT_CONTINUITY] — Receipt: mem-synth-pref-001@v1, digest sha256:7f83b165 — Status: [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] — Boundary: [DEMO_DATA: SYNTHETIC]. - Step 2 [AGENT_B_RECALL]: Agente B (terminal-assistant-beta) recupera preferência dentro do escopo autorizado project:synthetic-demo via recall tool — Query: 'code formatting indent' — Claim: [STMT_02_CROSS_CLIENT_CONTINUITY] & [STMT_04_TOKEN_BUDGET_GUARANTEE] — Receipt: mem-synth-pref-001@v1 cited, score 0.94, bounded budget — Status: [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] — Boundary: [DEMO_DATA: SYNTHETIC]. - Step 3 [UNAUTHORIZED_DENIAL]: Agente não autorizado (rogue-guest-gamma) tenta acesso entre locatários ao project:synthetic-demo sem credenciais válidas — Gate: Scope Isolation & Auth Gateway — Claim: [STMT_05_ZERO_TOKEN_EXPOSURE] — Outcome: AUTH_SCOPE_DENIED (HTTP 403), zero data leakage, zero storage mutation verified by database snapshot byte equality — Status: [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] — Boundary: [DEMO_DATA: SYNTHETIC]. - Step 4 [USER_CORRECTION]: Usuário corrige padrão de formatação via update_memory tool — Payload: {'formatting': 'spaces', 'indent': 2}, reason: 'team style guide update' — Controller: Version DAG Controller — Claim: [STMT_03_REALTIME_CORRECTION] — Receipt: mem-synth-pref-001@v2, supersedes v1, parent_digest sha256:7f83b165 — Status: [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] — Boundary: [DEMO_DATA: SYNTHETIC]. - Step 5 [LATER_RECALL_V2]: Consulta de recuperação posterior seleciona a versão 2 atualizada enquanto o SearchEngine exclui estritamente a versão 1 substituída — Query: 'indentation preference' — Claim: [STMT_03_REALTIME_CORRECTION] & [STMT_04_TOKEN_BUDGET_GUARANTEE] — Outcome: Active recall context injects only v2 (spaces, 2) — Status: [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] — Boundary: [DEMO_DATA: SYNTHETIC]. - Step 6 [PROVENANCE_DAG]: Inspeção de auditoria do histórico de versões via Version Controller — Chain: v1 (initial write by ide-assistant-alpha) -> v2 (superseded_by user correction) — Claim: [STMT_01_PROVENANCE_ATTRIBUTION] — Verification: Histórico de versões e ponteiros pai totalmente inspecionáveis — Status: [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] — Boundary: [DEMO_DATA: SYNTHETIC]. - Step 7 [STATE_RESET]: Controles de sandbox redefiníveis restauram o escopo project:synthetic-demo para a linha de base limpa — Action: Desmontagem determinística e limpeza de estado — Claim: [STMT_05_ZERO_TOKEN_EXPOSURE] — Receipt: reset_status CLEARED, 0 residual rows, zero persistent side effects — Status: [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] — Boundary: [DEMO_DATA: SYNTHETIC]. - Boundary Notice [NOT_VERIFIED]: Pipelines de faturamento multilocatário em nuvem [STMT_06_BACKEND_OPEN_SOURCE_CLAIM], consenso autônomo entre organizações [STMT_07_AUTONOMOUS_CONSENSUS_CLAIM] e replicação global com latência zero [STMT_08_ZERO_LATENCY_REPLICATION_CLAIM] são [NOT_VERIFIED] e foram excluídos deste tempo de execução de código aberto local. ```text +------------------------------------------------------------------------------------------------------------------------+ | [REPRODUCIBLE ARCHITECTURE LIFECYCLE WALKTHROUGH: SYNTHETIC A/B PREFERENCE SHARING & CORRECTION] | | | | Agent A (IDE) XMemo Gateway & Engines Agent B (CLI) Unauthorized Agent (Guest) | | [ide-assistant-alpha] [FastMCP / Storage / Scope] [terminal-assistant-beta] [rogue-guest-gamma] | | | | | | | | (1) remember(pref: tabs, 4) | | | | | -------------------------------------> | | | | | | [Write v1, Hash: 7f83b1] | | | | <------------------------------------- | | | | | Receipt: mem-001@v1 | | | | | | | (2) recall(pref) | | | | | | <--------------------------- | | | | | | [Scope Match: synth-demo] | | | | | | ---------------------------> | | | | | | Citation: mem-001@v1 | | | | | | | (3) recall(foreign tenant) | | | | | <---------------------------------------------------------- | | | | | [BoundSpace Check: MISMATCH] | | | | | ----------------------------------------------------------> | | | | | DENIED: AUTH_SCOPE_DENIED (Zero Mutation) | | | | | | | | (4) update_memory(pref: spaces, 2) | | | | | -------------------------------------> | | | | | | [Write v2, parent: v1] | | | | <------------------------------------- | | | | | Receipt: mem-001@v2 (supersedes v1) | | | | | | | (5) recall(pref) | | | | | | <--------------------------- | | | | | | [Exclude v1, Select v2] | | | | | | ---------------------------> | | | | | | Citation: mem-001@v2 | | | | | | | | | | (6) inspect_provenance(mem-001) | | | | | -------------------------------------> | | | | | <------------------------------------- | | | | | DAG: v1 (Hash: 7f83) -> v2 (Hash: 4d82) | | | | | | | | | | (7) reset_synthetic_state() | | | | | -------------------------------------> | [Purge demo scope] | | | | <------------------------------------- | 0 residual rows | | | +------------------------------------------------------------------------------------------------------------------------+ ``` ## Navegação detalhada de conceitos e segurança Explore domínios arquiteturais específicos por meio de nossa documentação detalhada de conceitos e segurança: - Modelo de dados de memória (/docs/concepts/memory-model): Estruturas de entidade, categorias semânticas e camadas de representação. - Proveniência e atribuição (/docs/concepts/provenance-attribution): Trilhas de auditoria e atribuição de chamador. - Espaços de memória de projeto (/docs/concepts/projects): Associação verificada de projeto por meio de roteamento de caminhos de workspace e isolamento de limites de projeto pessoal. - Consolidação de memória e Dream (/docs/concepts/dream-reflection): Consolidação de pré-visualização de candidatos, revisão explícita de destinos e políticas de manutenção. - Bases de conhecimento externas (/docs/concepts/knowledge-bases): Indexação de documentos, estratégias de divisão e citações. - Limite de dados e segurança (/docs/security/data-boundary): Delimitação abrangente entre recursos auto-hospedados e serviços SaaS em nuvem. ## 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.