Memória¶

Os assistants do Nodexa podem lembrar informações sobre os usuários entre sessões. Quando um usuário menciona algo relevante em uma conversa — preferências, decisões passadas ou contexto importante — o assistant pode armazenar isso como memória e recuperar em conversas futuras.

Como a Memória Funciona¶

A memória é totalmente automática e interna. Não há endpoint público para listar, escrever ou excluir itens de memória. O próprio assistant decide o que vale a pena lembrar com base no fluxo da conversa.

Características principais:

Por usuário e por assistant — cada par (userId, assistantId) tem seu próprio espaço de memória isolado
Automática — o assistant decide o que salvar; você não pode instruí-lo a lembrar ou esquecer itens específicos via API
Persistente — as memórias sobrevivem entre sessões e são carregadas no início de cada nova conversa daquele usuário
Escopo limitado ao caminho genérico do assistant — a memória só fica disponível quando a conversa é tratada diretamente pelo assistant. Se a camada de roteamento encaminhar para um Agente Especialista, a capacidade save_to_memory não fica disponível naquele turno

Para habilitar a memória, sempre passe x-user-id nos headers da sua request. Sem um user ID, o assistant não tem contexto de usuário para vincular memórias.

-H "x-user-id: user_abc123"

Memória vs. User Claims¶

Memória e user claims são mecanismos para fornecer contexto sobre um usuário ao assistant, mas funcionam de forma diferente:

	Memória	User Claims
Quem escreve	O assistant, automaticamente	Sua aplicação, via API
Quando é escrita	Durante a conversa	A qualquer momento (antes ou depois de uma conversa)
API pública	Nenhuma	`POST /v1/user-claims/bulk`
Confiável para roteamento	Apenas no caminho genérico do assistant	Sempre injetado, independente do roteamento
Caso de uso	Contexto conversacional que o assistant infere	Dados estruturados de perfil que sua aplicação gerencia

Recomendação: Use User Claims como mecanismo primário para contexto persistente de usuário. Os claims são sempre injetados em cada conversa, independente de qual Agente Especialista trate a request. A memória é uma camada complementar para o contexto que o assistant descobre durante a conversa.

Privacidade e Exclusão de Dados¶

A memória armazena dados pessoais que os usuários compartilharam em conversas. Sua plataforma deve estar em conformidade com as regulamentações de privacidade aplicáveis (GDPR, LGPD, etc.).

Boas práticas:

Informe os usuários que as conversas podem ser usadas para formar memórias
Atenda solicitações de exclusão de dados — para solicitações formais de exclusão, fale com o suporte do Nodexa ou use o painel administrativo para apagar todos os dados armazenados de um usuário
Considere user claims como alternativa — como sua aplicação controla escritas e exclusões, os claims oferecem auditabilidade total e a capacidade de apagar dados sob demanda via DELETE /v1/user-claims/:userId/:claimKey

Solicitações de exclusão de dados

Não há endpoint público /v1/memory. Para atender uma solicitação de exclusão de dados que abrange a memória do assistant, use o painel administrativo do Nodexa ou fale com o suporte. Para dados de user claims, use o endpoint DELETE /v1/user-claims/:userId/:claimKey que sua aplicação controla diretamente.