Agents memory console

Agents → Memory is the operator console for the long-term memory your AI agents accumulate. It covers the whole lifecycle of a memory entry: browsing what exists, adding a fact by hand, checking what a single agent has learned, and removing or erasing entries. Everything the console does is also available on the public API. Customer memory, the per-contact store agents read and write during a conversation, is covered in Customer memory. This page is about the console and per-agent surfaces built on top of it.

Agent memory vs customer memory

Two scopes exist, and the console lets you move between them:

Customer memory is namespaced by contact — the shared per-contact store every agent reads from, so a fact one agent captured is available to your other agents on the next turn.
Agent memory is namespaced by agent — the slice of the same store one agent wrote or was taught. The per-agent view at /agents/:id/memory shows exactly one agent’s corpus, so you answer “what does THIS agent know about this contact” without the rest of the tenant’s entries mixed in.

Both scopes hold the same four entry types — fact, preference, goal, summary — and both respect the contact’s memory consent flag.

The Agents → Memory console

Open AI Agents → Memory. The page lists memory entries for your tenant as cards showing content, type, and importance, including a filter field for Agent ID (agt_…) alongside Contact ID (cnt_…), type, and a creation-date range. Enter an agent ID to narrow the grid to that agent’s entries; combine it with a contact ID to see what one agent knows about one contact. Entries load 50 at a time; a Load more button extends the list when a cursor says more exist. Click a card for the full entry — the complete content, contact and agent IDs, importance, creation time, and the entry ID. Filter inputs are debounced, so pasting an ID issues one fetch, and an inverted From/To range is flagged inline rather than silently returning an empty list. Access to this page is restricted to owner and admin roles, because it can surface notes across every contact and agent in the tenant.

Teach your agent a fact

The Create memory button in the header opens the teach dialog. Its fields map 1:1 to the create-memory API payload:

Contact ID — the contact (cnt_…) this fact is about. Paste it from a conversation or contact page.
Agent — pick from a dropdown of your agents, so no one has to copy an agt_… id out of a URL.
Type — fact, preference, goal, or summary.
Content — a short, single-sentence statement, up to 10,240 characters.

Manual entries land at an importance of 0.9 by default, so an operator-authored fact outlives auto-extracted summaries under budget eviction. The agent retrieves a taught fact on its next conversation with that contact, exactly like a fact the runtime extracted — manual add does not skip retrieval ranking, and every entry still passes through the same grounding and guardrail pipeline described in Agent grounding and citations.

Per-agent view

On an agent’s detail page, open Memory. The page at /agents/:id/memory shows what that one agent has remembered about a given contact, grouped by contact, so you can audit a single agent’s corpus. Paste a contact ID and press Load; the page fetches facts only by default, with controls to Reveal PII (owner, admin, or developer roles; the reveal is audit-logged) and to Teach a fact scoped to that agent and contact. Search filters the loaded facts inline without re-querying. If the contact has opted out of memory, the page says so explicitly instead of listing entries — and once you type a different contact ID, the stale opt-out warning is suppressed until you load it. Each fact carries a Forget action (removes that entry, audit-logged), and each contact group carries Forget all — the same GDPR erasure as the console’s erase panel: it deletes the contact’s memory entries across all agents and flips the contact’s memory consent flag off. Erasure is the only way memory leaves an agent’s corpus automatically. If you want an entry gone from one agent but retained for others, remember that the store is per-contact and shared — forgetting it removes it for every agent.

API surface

Writes require owner or admin; requests authenticate with your session token or API key. The paths below are the same ones the console calls.

Operation	Endpoint
List entries (filter by contact, agent, type, date)	`GET /api/v1/agents/memory`
Fetch a single entry	`GET /api/v1/agents/memory/:id`
Create a manual entry	`POST /api/v1/agents/memory`
Promote (raise importance)	`PATCH /api/v1/agents/memory/:id`
Delete a single entry	`DELETE /api/v1/agents/memory/:id`
Erase a contact’s memory	`DELETE /api/v1/agents/memory?contactId=cnt_…`

Every response wraps its payload in a { data, meta } envelope — meta.request_id and meta.timestamp — and every error is { error: { code, message, status }, meta } with a stable machine error.code you can switch on. The samples below cover the three operations the console performs most often.

List entries — `GET /agents/memory`

cURL:

curl -sG 'https://api.orbit.devotel.io/api/v1/agents/memory' \
  -H 'Authorization: Bearer '$(get_jwt) \
  --data-urlencode 'agentId=agt_01J8Z9K3P4Q5R6S7T8U9V0W1X2' \
  --data-urlencode 'memoryType=fact' \
  --data-urlencode 'limit=50'

The payload carries items, an opaque next_cursor to pass back as ?cursor=… for the next page, a total_scanned count of entries matching the active filter, and an echo of the applied filter:

{
  "data": {
    "items": [
      {
        "id": "mem_9f2c1a8b4d6e4f0a9c2b5d7e3f1a6c84",
        "tenantId": "tn_01J8Z9K3P4Q5R6S7T8U9V0W1X2",
        "contactId": "cnt_01J8Z9K3P4Q5R6S7T8U9V0W1X2",
        "agentId": "agt_01J8Z9K3P4Q5R6S7T8U9V0W1X2",
        "memoryType": "fact",
        "content": "Customer prefers SMS over email",
        "importance": 0.9,
        "createdAt": "2026-09-10T14:22:31.120Z"
      }
    ],
    "next_cursor": null,
    "total_scanned": 1,
    "filter": {
      "contact_id": null,
      "agent_id": "agt_01J8Z9K3P4Q5R6S7T8U9V0W1X2",
      "memory_type": "fact",
      "from": null,
      "to": null
    }
  },
  "meta": { "request_id": "req_01J8", "timestamp": "2026-09-10T14:22:31.201Z" }
}

TypeScript (Node SDK — the typed resources do not expose a dedicated memory accessor yet, so use the generic request() escape hatch, which still handles auth, retries, and idempotency keys):

import { Orbit } from '@devotel-orbit/node';

const orbit = new Orbit({ apiKey: 'dv_live_sk_xxxx' });

const res = await orbit.request('GET',
  '/agents/memory?agentId=agt_01J8Z9K3P4Q5R6S7T8U9V0W1X2&memoryType=fact&limit=50');
for (const item of res.data.items) {
  console.log(item.memoryType, item.content);
  // carry res.data.next_cursor into the next call's ?cursor=… to page
}

Fetch one entry — `GET /agents/memory/:id`

Returns the same entry shape under data.item. An unknown or cross-tenant id is a deliberate 404, never a leak.

curl -s 'https://api.orbit.devotel.io/api/v1/agents/memory/mem_9f2c1a8b4d6e4f0a9c2b5d7e3f1a6c84' \
  -H 'Authorization: Bearer '$(get_jwt)

{
  "data": {
    "item": {
      "id": "mem_9f2c1a8b4d6e4f0a9c2b5d7e3f1a6c84",
      "tenantId": "tn_01J8Z9K3P4Q5R6S7T8U9V0W1X2",
      "contactId": "cnt_01J8Z9K3P4Q5R6S7T8U9V0W1X2",
      "agentId": "agt_01J8Z9K3P4Q5R6S7T8U9V0W1X2",
      "memoryType": "fact",
      "content": "Customer prefers SMS over email",
      "importance": 0.9,
      "createdAt": "2026-09-10T14:22:31.120Z"
    }
  },
  "meta": { "request_id": "req_01J8", "timestamp": "2026-09-10T14:22:31.201Z" }
}

TypeScript:

const res = await orbit.request('GET',
  '/agents/memory/mem_9f2c1a8b4d6e4f0a9c2b5d7e3f1a6c84');
console.log(res.data.item.content);

Create a manual entry — `POST /agents/memory`

The same payload the teach dialog sends. memoryType defaults to fact, and importance is optional — manual entries default to 0.9.

curl -X POST 'https://api.orbit.devotel.io/api/v1/agents/memory' \
  -H 'Authorization: Bearer '$(get_jwt) \
  -H 'Content-Type: application/json' \
  -d '{
    "contactId": "cnt_01J8Z9K3P4Q5R6S7T8U9V0W1X2",
    "agentId": "agt_01J8Z9K3P4Q5R6S7T8U9V0W1X2",
    "memoryType": "fact",
    "content": "Customer prefers SMS over email"
  }'

The create returns 201 Created with the stored entry:

{
  "data": {
    "item": {
      "id": "mem_9f2c1a8b4d6e4f0a9c2b5d7e3f1a6c84",
      "tenantId": "tn_01J8Z9K3P4Q5R6S7T8U9V0W1X2",
      "contactId": "cnt_01J8Z9K3P4Q5R6S7T8U9V0W1X2",
      "agentId": "agt_01J8Z9K3P4Q5R6S7T8U9V0W1X2",
      "memoryType": "fact",
      "content": "Customer prefers SMS over email",
      "importance": 0.9,
      "createdAt": "2026-09-10T14:22:31.120Z"
    }
  },
  "meta": { "request_id": "req_01J8", "timestamp": "2026-09-10T14:22:31.201Z" }
}

TypeScript:

const res = await orbit.request('POST', '/agents/memory', {
  contactId: 'cnt_01J8Z9K3P4Q5R6S7T8U9V0W1X2',
  agentId: 'agt_01J8Z9K3P4Q5R6S7T8U9V0W1X2',
  memoryType: 'fact',
  content: 'Customer prefers SMS over email',
});
console.log('Stored memory', res.data.item.id);

Error envelope

Errors share one shape: error.code is a stable machine string, error.details carries per-field violations on validation failures. A 422 means the request body or query failed validation — fix the named field; a 409 with MEMORY_FACTS_CAP_EXCEEDED means the contact is at its facts cap — forget an existing fact before teaching another; an invalid filter shape on the list endpoint is also a 422. A failing create:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid body",
    "status": 422,
    "details": {
      "memoryType": ["Invalid enum value. Expected 'summary' | 'fact' | 'preference' | 'goal'"]
    }
  },
  "meta": { "request_id": "req_01J8", "timestamp": "2026-09-10T14:22:31.201Z" }
}

And the fact-cap rejection:

{
  "error": {
    "code": "MEMORY_FACTS_CAP_EXCEEDED",
    "message": "This contact already has 50 facts (cap: 50). Forget one before teaching another.",
    "status": 409,
    "details": { "current": 50, "cap": 50 }
  },
  "meta": { "request_id": "req_01J8", "timestamp": "2026-09-10T14:22:31.201Z" }
}

For a fuller treatment of auth schemes and the envelope every endpoint returns, see API integration and Error handling examples.

Limits and responsibilities

Manual add is an explicit, audit-logged admin action — it never happens implicitly from a conversation.
A contact can opt out of memory entirely; the per-contact erasure deletes existing entries and stops new writes until the flag is re-enabled on the contact’s profile.
Memory feeds agent grounding and recall — it does not bypass the guardrail stack. Retrieval still ranks entries, and grounded responses still cite their sources where citations are enabled (see Agent grounding and citations).
There is a hard cap on fact entries per contact; when it is reached the API rejects new facts with a 409 MEMORY_FACTS_CAP_EXCEEDED until an existing fact is forgotten.

Next steps

Customer memory — the per-contact store and its runtime behaviour.
Agent grounding and citations — how retrieved memory and knowledge ground responses.
Agent guardrails — the controls memory retrieval still passes through.

WhatsApp

Guides

Messaging Controls

Audience & Support Tools

Agents memory console: browse, teach, and audit per-agent memory

Agents memory console

Agent memory vs customer memory

The Agents → Memory console

Teach your agent a fact

Per-agent view

API surface

List entries — `GET /agents/memory`

Fetch one entry — `GET /agents/memory/:id`

Create a manual entry — `POST /agents/memory`

Error envelope

Limits and responsibilities

Next steps

​Agents memory console

​Agent memory vs customer memory

​The Agents → Memory console

​Teach your agent a fact

​Per-agent view

​API surface

​List entries — GET /agents/memory

​Fetch one entry — GET /agents/memory/:id

​Create a manual entry — POST /agents/memory

​Error envelope

​Limits and responsibilities

​Next steps

Agents memory console

Agent memory vs customer memory

The Agents → Memory console

Teach your agent a fact

Per-agent view

API surface

List entries — `GET /agents/memory`

Fetch one entry — `GET /agents/memory/:id`

Create a manual entry — `POST /agents/memory`

Error envelope

Limits and responsibilities

Next steps