Guia da Memory Console

Objetivo do usuário e visão geral do console

A Memory Console oferece uma interface web visual em /me (com o alias /memory-console) para inspecionar, pesquisar e gerenciar registros de memória, conexões de agentes, projetos e configurações de segurança. Em vez de interagir exclusivamente por comandos da CLI ou ferramentas MCP, desenvolvedores e membros de equipe utilizam o console para auditar o que os agentes registraram, corrigir memórias imprecisas, inspecionar a atribuição de agentes, gerenciar tokens de API e controlar a exportação e exclusão de dados.

Disponibilidade e pré-requisitos

A Memory Console está disponível em qualquer navegador moderno para usuários autenticados. O layout do console organiza as funcionalidades em seções distintas de espaço de trabalho e acesso, disponíveis pela barra lateral e por âncoras hash diretas de URL:

• Requisito de autenticação: é necessária uma sessão de usuário ativa. Visitas não autenticadas são redirecionadas para /login (a página de login).
• Visão geral (#overview): resumo rápido do espaço de memória pessoal, atividades recentes, agentes conectados e sinais de armazenamento.
• Memórias (#memory): pesquise, filtre, inspecione e edite registros de memória com pesquisa de texto completo, filtros de tipo e filtros de fonte.
• Knowledge (#knowledge): visualize e mantenha documentos de conhecimento para consulta por agentes autorizados.
• Projetos (#projects): navegue por espaços de trabalho de projetos, notas contextuais e memórias associadas a projetos.
• Cloud Skill (#skills): crie, importe e gerencie habilidades procedimentais na nuvem. Marcado com um distintivo Preview e disponível se habilitado para sua conta.
• Dream (#dream): revise padrões recorrentes e sugestões de síntese antes que se tornem memórias duradouras. Marcado com um distintivo Preview e disponível se habilitado para sua conta.
• Agentes (#agents): visualize agentes conectados a este espaço de trabalho, inspecione os últimos registros de data e hora ativos e revise permissões.
• Equipes (#teams): crie e gerencie equipes, convide membros e configure papéis no espaço de trabalho da equipe. Marcado com um distintivo Preview e disponível se habilitado para sua conta.
• Perfil (#profile): identidade da conta, status de verificação de e-mail e preferências pessoais.
• Sessões (#sessions): revise sessões ativas de login e dispositivos conectados.
• Chaves de API (#api-keys): emita, alterne e revogue tokens de acesso com escopo para CLI, agentes e automação.
• Configurações (#memory-settings): postura de privacidade, modos de segurança, solicitações de exportação de dados e controles de exclusão de memória.

Uma tarefa completa: inspecionar e corrigir memória sintética

Neste passo a passo, você localiza a memória de convenção sintética salva durante o guia de início rápido, inspeciona sua atribuição de agente, corrige seu texto no console, verifica a atualização e confirma os limites do espaço de trabalho pessoal.

1. Localizar memória sintética no painel Memórias

Navegue até /me e abra o painel Memórias clicando em Memories na barra lateral ou navegando até #memory. Digite "demo project timestamp format" na barra de pesquisa ou filtre pela categoria Facts. A lista renderiza cartões de memória correspondentes exibindo resumo de conteúdo, hora de criação e distintivos de visibilidade.

# Access personal workspace
https://xmemo.dev/me#memory

# Access team workspace with explicit team context
https://xmemo.dev/me?space=<team_id>#memory

2. Inspecionar atribuição e metadados do agente

Clique no cartão da memória para expandir o painel Explain. O console exibe detalhes de procedência e atribuição capturados no momento da gravação:

• Tipo de autor e identidade do agente: exibe se a memória foi gravada por um agente, usuário humano ou script importado, junto com o nome e ID do agente.
• Exibição de instância de agente: exibe o identificador distinto da instância do agente (agent_instance_display) para diferenciar execuções separadas do mesmo agente.
• Dispositivo e transporte: mostra o rótulo do dispositivo (device_label) e o canal de transporte pelo qual a gravação foi enviada.
• Visibilidade e escopo: indica se o registro é pessoal ou compartilhado em equipe (team_id), juntamente com atribuições de projeto e bucket.
• Histórico de versões: exibe o número da revisão atual e inclui link para a gaveta de linhagem de versões.

3. Corrigir conteúdo de memória em linha

Clique no botão Edit no cartão da memória para abrir o editor integrado. Atualize o conteúdo para refletir a convenção de projeto refinada e clique em Save:

• Conteúdo atualizado: altere "demo project timestamp format" para "Demo project timestamps use UTC with ISO 8601 formatting.".
• Ação de salvamento: o console emite uma solicitação de atualização autenticada com proteção CSRF, incrementando o contador de revisões.
• Proteção contra conflitos: se um agente atualizou a memória simultaneamente, o console detecta a divergência de revisão (HTTP 409) e solicita com "CAS version conflict: Data has been updated elsewhere. Please refresh and try again." para revisar o conteúdo mais recente antes de sobrescrever.

4. Verificar atualização no console e no recall do agente

Após salvar, o console exibe uma notificação de sucesso e atualiza o cartão da memória. A gaveta de linhagem de versões mostra a revisão anterior substituída pela nova revisão. Para verificar se os agentes conectados observam imediatamente a correção, execute recall no seu terminal:

node scripts/xmemo-skill.mjs recall --query "demo project timestamp format" --limit 1

Resultado observável

Uma correção bem-sucedida no console produz alterações observáveis na interface web e nas interfaces de agentes:

• Notificação toast no console web: uma notificação toast de confirmação ("Memory updated") aparece na parte inferior da tela.
• Apresentação do cartão: o cartão exibe imediatamente o texto atualizado, registro de data e hora atualizado e índice de revisão incrementado.
• Gaveta de linhagem: a gaveta de linhagem de versões exibe diferenças em nível de palavras comparando a revisão anterior com o texto atualizado.
• Saída de recall do agente: uma consulta por "demo project timestamp format" retorna o texto atualizado com sua referência de revisão mais recente.

O que os agentes podem acessar

Agentes e usuários do console operam sob limites distintos de autenticação e permissão:

• Permissões do console: usuários do console acessam dados por meio de cookies do navegador com validação CSRF. Ações no console refletem o perfil do usuário conectado.
• Permissões do agente: agentes se autenticam usando chaves de API com escopo emitidas no painel Chaves de API (#api-keys) ou tokens OAuth. Escopos de token permitidos incluem memory:read, memory:write, knowledge:read, ledger:read, ledger:write e read:audit.
• Limite de visibilidade do agente: agentes não podem visualizar senhas de contas, sessões ativas do navegador ou detalhes de faturamento. Um agente com token pessoal só pode consultar memórias pessoais e conhecimento público; ele não pode inspecionar espaços de trabalho de equipe a menos que esteja expressamente vinculado a essa equipe.

Limites de compartilhamento e armazenamento

A Memory Console impõe uma separação rigorosa entre dados pessoais e espaços de trabalho de equipe:

• Seleção de espaço: o seletor de espaço alterna entre memória pessoal e espaços de trabalho de equipe por meio do parâmetro de consulta ?space=<team_id> (gerenciado por useSpaceContext). Omitir o parâmetro ou definir ?space=personal restringe a exibição à memória pessoal.
• Isolamento de configurações: o painel Configurações (#memory-settings) é ocultado automaticamente ao navegar em um espaço de equipe para evitar divergências de configuração entre locatários. Tentar abrir Configurações em um espaço de equipe redefine o espaço ativo para Personal.
• Limites de exportação de dados: a partir de Configurações (#memory-settings), os usuários podem solicitar um arquivo de exportação seguro para segredos (/api/v1/me/export-requests). A exportação pessoal inclui registros de memória pessoais, linhagem de versões, transações de livro-razão pessoais e documentos pessoais. A memória da equipe é estritamente excluída das exportações pessoais.
• Autorização de download de exportação: arquivos de exportação gerados exigem um desafio sudo para obter um token temporário de autorização de download antes de obter xmemo-personal-export.zip. Artefatos de exportação podem ser revogados e excluídos a qualquer momento.
• Controles de exclusão de memória: usuários podem excluir memórias individuais com confirmação, limpar todas as memórias ou redefinir memórias confirmando o e-mail da conta e digitando a frase de confirmação "RESET MY XMEMO MEMORY". O encerramento de conta por autoatendimento exige a transferência de quaisquer equipes sob sua posse antes da exclusão (HTTP 409).
• Pontos de entrada de TODO: o console expõe TODOs como contadores agregados dentro dos cartões de projetos em Projetos (#projects), exibindo o número de itens de ação em aberto associados a cada espaço de trabalho.
• Pontos de entrada do livro-razão: registros do livro-razão aparecem como uma categoria de tipo filtrável em Memórias (#memory), podem ter escopo em tokens de API (ledger:read, ledger:write) em Chaves de API (#api-keys) e estão incluídos em arquivos de exportação de dados pessoais.

Recuperação de falhas

Resolva erros comuns do console e problemas de acesso usando as seguintes etapas:

• Memória não encontrada na pesquisa: verifique se o seletor de espaço está configurado para o espaço correto (Personal versus Team ?space=<team_id>). Limpe menus suspensos de filtro ativos na barra de ferramentas (como Tipo ou Visibilidade) para ampliar os resultados da pesquisa.
• Erro de edição simultânea (HTTP 409): se um agente ou outra aba atualizou a memória enquanto sua edição estava aberta, o console exibe "CAS version conflict: Data has been updated elsewhere. Please refresh and try again.". Atualize a lista, inspecione a nova revisão e reaplique as alterações.
• Opção de configurações não visível na barra lateral: Configurações fica oculta ao visualizar um espaço de equipe. Abra o menu suspenso de espaços na barra lateral e volte para o espaço de trabalho Personal para restaurar o acesso a Configurações (#memory-settings).
• Autorização de download de exportação expirada: tokens de autorização de download sudo têm vida curta. Insira novamente as credenciais da sua conta na solicitação de download para gerar uma nova autorização de download.

Referência relacionada

Consulte a documentação de conceitos e ferramentas relacionada para mecanismos subjacentes e contratos de API:

• Início rápido: /docs/quickstart para configuração inicial e criação de memória sintética.
• Correção de memória: /docs/concepts/memory-correction para histórico de revisões e semântica de substituição.
• Exclusão de memória: /docs/concepts/memory-deletion para exclusão lógica e ciclo de vida de registros de exclusão.
• Procedência e atribuição: /docs/concepts/provenance-attribution para especificações de instância de agente e tipo de autor.
• Projetos: /docs/concepts/projects para limites de espaços de trabalho de projetos e escopos de contexto.
• Equipes: /docs/capabilities/teams para criação de espaços de trabalho de equipes, papéis e colaboração.
• Bases de conhecimento: /docs/concepts/knowledge-bases para bases de documentos e regras de publicação.
• Cloud Skills: /docs/concepts/cloud-skills para autoria de habilidades procedimentais na nuvem.
• Reflexão Dream: /docs/concepts/dream-reflection para conceitos de análise de padrões.
• Governança e retenção: /docs/concepts/governance-retention para políticas de retenção e controles DSAR.
• Limite de dados: /docs/security/data-boundary para criptografia, multilocação e isolamento.
• Ferramenta TODO: /docs/tools/todos para parâmetros da ferramenta de acompanhamento de tarefas de agentes.
• Ferramenta Ledger: /docs/tools/ledger para parâmetros da ferramenta de transações financeiras.