Skip to main content

​
Customer Memory

Customer Memory is the tenant-wide record of what your AI agents have learned about each contact: facts they stated, preferences they expressed, goals they mentioned, and conversation summaries the runtime wrote. Every agent you run reads from and writes to this shared, per-contact store — so a fact an SMS agent captured last week is what a voice agent picks up on today. The memory plane page covers how retrieval works inside a live turn. This page covers the operator side: the AI Agents → Customer Memory browser at /agents/memory, how entries get their importance, how to curate them, and the API that backs the whole surface.

​
How memory accumulates

Entries land in four types, written by the agent runtime as conversations happen: Two safeguards keep the store sane over time:
  • Importance scores (0–1). Every entry carries an importance value. When the store comes under its per-contact budget, low-importance entries are evicted first. Manual entries land at 0.9 by default, so an operator-authored fact outlives an auto-extracted summary.
  • Per-contact caps. There is a hard cap on fact entries per contact; when a tenant reaches it the API rejects new facts with a 422 rather than silently growing the contact’s plane. Summaries, preferences, and goals stay under the wider sweep eviction instead.

​
The /agents/memory browser

Open AI Agents → Customer Memory. The page lists memory entries across your whole tenant — every agent, every contact — as cards showing the content, type, and importance of each entry. The filter bar narrows the grid:
  • Contact ID — show only one contact’s entries (cnt_…).
  • Agent ID — show only entries one agent wrote (agt_…).
  • Type — fact, preference, goal, or summary.
  • From / To — a creation-date range. If the From date is later than the To date, the page flags the range inline and ignores it until you fix it — other filters still apply.
Entries load 50 at a time. When more exist, a Load more button extends the list, and the counter above the grid reports how many entries you’ve loaded against the scanned total. Dates and contact IDs are debounced as you type, so a pasted contact ID issues one fetch, not one per character. Click a card to open the full entry: the complete content, type, importance, contact and agent IDs, creation time, and the entry ID. A View conversation link on each card deep-links into the conversation the entry was extracted from.
  • Empty tenant — before any agent has written memory, the page shows a zero state explaining what will appear.
  • Filtered, no matches — when filters exclude everything, the page offers to clear them instead of implying the tenant has no memory at all.

​
Curating entries

Each card carries three actions:
  • Promote — raises the entry’s importance by 0.1 (capped at 1.0) in place, so it survives budget eviction longer. The same entry updates; no duplicate is created.
  • Delete — removes the entry after a confirmation. Owner/admin roles only.
  • Add memory — the header button teaches a fact manually. Pick the contact, the agent it belongs to, the type, and the content. The entry is embedded the same way an LLM-extracted one is, so retrieval treats it identically.
Delete and Promote are written through as DELETE / PATCH on the entry, so an entry past the 1,000-item scroll cap is still reachable — bulk browsing caps do not gate single-entry actions.

​
Erasure and opt-out

Enter a Contact ID in the filter bar and, once the entries load, an Erase contact memory panel appears below the grid. Confirming it:
  1. Deletes every memory entry the tenant holds on that contact.
  2. Flips the contact’s memory consent flag off, so the agent runtime stops writing new entries for them — this is the GDPR right-to-erasure path and it closes the race where a live conversation could write a fresh entry right after the wipe.
Use this for a data-subject request. When a contact has opted out, the Profile API and the per-agent memory tab both show the opted-out state explicitly rather than listing entries.

​
Access roles

The page is gated to owner and admin, because it surfaces notes across the whole tenant — the same RoleGuard that gates the other AI-hub operator surfaces. Writes (create, promote, delete, erase) require owner/admin on the API as well. Reads through the Profile-API surface accept owner, admin, and developer with the contacts:read scope.

​
How an agent uses memory at runtime

On each new turn the memory plane resolves the contact, retrieves their top entries, and renders them as a system-level block with a fixed marker:
The executor strips the previous turn’s block before attaching the fresh one, so memory never accumulates inside a conversation. Curating an entry in the dashboard changes what every agent sees on its very next turn — Promote makes it rank higher in retrieval; Delete removes it from context; an added fact is available immediately.

​
API surface

Everything the dashboard does, the public API does. Writes require owner or admin; requests are authenticated with your session token or API key. List entries, newest first, paged with an opaque cursor:
The response returns items, the next_cursor for the following page, a total_scanned count, and the echo of the applied filter. An invalid filter shape is a 422. Teach a fact manually:
Raise an entry’s importance (promote):
Erase a contact — the right-to-erasure request path:
A cross-tenant or unknown entry id is a deliberate 404 on every single-entry route. For read-only, cross-channel surfacing of one contact’s memory to your own systems, use the Profile API memory endpoints — those accept the developer role and return masked content by default.

​
Next steps

  • Memory plane — resolution, retrieval, and rendering inside a live turn.
  • Agent guardrails — combine curated memory with the guardrail stack.
  • Audit log — every reveal, delete, and erase writes an auditable entry there.