User Memory

How per-user memory works — the two memory stores, how each user gets their own memory, how the agent reads and writes it, and every control for managing it.

This page explains how memory behaves. To configure the memory schema and the extraction settings on the dashboard, see the Memory page.

Every agent keeps memory per user, per agent: what it learns about one person is never shared with another, and each way a user reaches your agent (web login, WhatsApp sender, email address, API key, anonymous visitor) has its own private memory. This page covers what’s stored, how the agent reads and writes it, and how owners and subscribers manage it.

The two memory stores

Store	What it holds	Written by
Freeform memory	Short notes — preferences, ongoing projects, feedback, facts worth keeping.	The agent (record_agent_user_memory) and automatic extraction after a turn.
Structured memory	The fields you define on the Memory page (public + private), with values and a record of how they changed.	The agent (update_user_memory), the user (public fields), and extraction.

The schema is owner-defined once per agent and shared by all users; only the values are per-user. A user’s workflow progress — their Stages position and goal progress — travels with their memory.

Everything the platform keeps for a user — memories, workflow position, goal progress — is private to that user and isolated per subscriber: what one person’s conversations produce is never readable from another’s, and a subscriber’s own visitors’ memories are not browsable from the owner’s memory panel. All of it survives restarts and updates, and is manageable from the Memory page.

Identity per channel

Each user is recognized by how they reach your agent, and their memory follows that identity:

Caller	Memory persists across
Logged-in subscriber (web)	Sessions and devices
WhatsApp / Telegram / other IM	Sessions and devices
Inbound email	Sessions and devices
API key	Sessions; the integrator supplies the user identity (optionally per end user)
Anonymous visitor on a public agent page	Sessions from the same visitor; a new visitor starts fresh
Widget visitor on a subscriber route	Sessions on the same browser
Plain anonymous widget	That browser only
Owner preview	A single shared preview scope

The widget exception: browser-side memory

The plain embeddable widget (no subscriber in the URL) deliberately keeps no server-side memory. The browser holds the memory and sends it with each chat request; the agent works from that and returns the updated version to the browser. If the browser sends nothing, the agent starts empty — anonymous widget traffic never falls into any shared server-side memory. Clearing the browser or switching devices loses the plain widget’s memory. (The contact registry entry and conversation transcripts are stored separately and do persist.)

How the agent accesses memory

Reading — automatic. Relevant memory is loaded into the agent’s context at the start of every turn, so it begins with background knowledge without a tool call. This is strictly per-user — one user’s memory can never appear in another’s conversation.

Reading — on demand. Tools the agent can call:

Tool	Store	What it does
find_memories_by_entity	freeform	Search notes by entity / topic.
get_user_memory	structured	Read the current snapshot (public + private fields).
query_user_memory_field	structured	Read a single field.
get_user_adaptations	structured	Summarize how values changed over time.

Writing.

Tool / path	Store	Notes
record_agent_user_memory	freeform	Creates or updates a note.
update_user_memory / forget_user_memory	structured	Field-level updates, recorded with their history.
Auto-extraction	both	After a turn, durable facts are extracted automatically (configurable per agent; see Memory Engine). It never delays the reply.

Structured-memory tools are available only when the agent has a memory schema and the caller has an identity to store under. Custom code can reach the same stores through the ctx bridge.

Managing memory

As the owner:

• Memory page — define the schema (public/private fields), tune the Memory Engine (auto-extract, semantic search, dedup & merge, compression, focus instructions), and generate schemas with AI.
• Your agent’s memory (same page) — browse each owner-side memory (preview, API keys, IM senders, email senders) and inspect what the agent remembered.
• View Insights — per-user analytics plus the trust & contradiction tools for resolving conflicting memories.
• Management MCP — the memory_schema section is readable/writable programmatically (reference).

As a subscriber:

• View and edit their public fields directly.
• Ask the agent what it remembers (private fields are inspectable on request).
• Pause memory — the “agent may remember things about you” toggle. When off, the agent can still read what it already knows and be asked to forget things.

Deleting: forgetting a structured field is audited; freeform notes can be deleted from the memory views. Deleting a subscriber removes all of their stored memory, and every memory nested beneath them.

Worth noting

• Everything the agent remembers is kept as readable notes and structured values — fully inspectable from the dashboard; nothing it knows about a user is opaque.
• Memory writes happen after the reply, so they never add latency to a turn.
• A subscriber instance’s visitors’ memories are intentionally not surfaced to the owner’s memory browser; the subscriber can always see their own public fields.