Skip to content

Memory

Nodexa assistants can remember information about users across sessions. When a user mentions something relevant in a conversation — their preferences, past decisions, or important context — the assistant may store that as a memory and recall it in future conversations.

How Memory Works

Memory is fully automatic and internal. There is no public API endpoint to list, write, or delete memory items. The assistant itself decides what is worth remembering based on the flow of conversation.

Key characteristics:

  • Per-user and per-assistant — each (userId, assistantId) pair has its own isolated memory space
  • Automatic — the assistant decides what to save; you cannot instruct it to remember or forget specific items via the API
  • Persistent — memories survive across sessions and are loaded at the start of every new conversation for that user
  • Scoped to the generic assistant path — memory is only available when the conversation is handled directly by the assistant. If the routing layer hands the query to a specialist agent, the save_to_memory capability is not available for that turn

To enable memory, always pass x-user-id in your request headers. Without a user ID, the assistant has no user context to attach memories to.

-H "x-user-id: user_abc123"

Memory vs. User Claims

Memory and user claims are both mechanisms for giving the assistant context about a user, but they work differently:

Memory User Claims
Who writes it The assistant, automatically Your application, via the API
When it is written During conversation Any time (before or after a conversation)
Public API None POST /v1/user-claims/bulk
Reliable for routing Generic assistant path only Always injected, regardless of routing
Use case Conversational context the assistant infers Structured user profile data your app manages

Recommendation: Use User Claims as the primary and reliable mechanism for persistent user context. Claims are always injected into every conversation regardless of which specialist agent handles the request. Memory is a complementary layer for context the assistant discovers during conversation.

Privacy and Data Erasure

Memory stores personal data that users have shared in conversations. Your platform must comply with applicable privacy regulations (GDPR, LGPD, etc.).

Recommended practices:

  1. Inform users that conversations may be used to form memories
  2. Support data erasure requests — for formal erasure requests, contact Nodexa support or use the Nodexa admin panel to erase all stored data for a user
  3. Consider user claims as an alternative — since your application controls writes and deletes, claims give you full auditability and the ability to erase data on demand via DELETE /v1/user-claims/:userId/:claimKey

Data erasure requests

There is no public /v1/memory endpoint. To fulfill a user data erasure request covering assistant memory, submit the request through the Nodexa admin panel or contact Nodexa support. For user claims data, use the DELETE /v1/user-claims/:userId/:claimKey endpoint which your application controls directly.