How-to guide

Memory

Keep what your agents learn about each person, read it back from your own code or CRM, and erase a person on request.

What you'll build

A CRM sync that finds a person by phone number, adds what you already know about them, and reads back what your agents remember. Then you see how an agent uses memory during a call, and how to erase a person.

How memory is organised

  • A person (the API calls it a subject) is one human, however they reach you. A phone number, an email address and a WhatsApp number can all belong to the same person.
  • An identifier is how a person is reached: phone, email, whatsapp, crm_id, external_user and a few channel ids such as telegram_user. Use external_user for your own user id.
  • A fact is one sentence VoiceLayer remembers about a person, for example "Prefers calls after 5pm". Agents extract facts from conversations. You can add facts yourself.
  • A space holds memory. Agents on the same space share what they remember. Agents on different spaces never see each other's. Every workspace starts with Shared, whose id is the empty string. A person is the same person in every space.
  • An episode is a record of a conversation that went into memory.

Prerequisites

ScopeLets the key
memory:readList spaces, read a profile, list facts and episodes, search
memory:writeFind or create a person, add facts, send history, attach an identifier
memory:eraseErase a person
memory:adminCreate, rename, delete spaces and set the default, merge people, detach an identifier
  • curl. These routes are not in the generated TypeScript and Python clients yet, so the examples call the HTTP API directly. Every route below starts with https://api.vlayers.ai.
export VOICELAYER_API_KEY=...   # a key with the scopes above

Step 1: Find the person

POST /v2/memory/subjects/resolve takes an identifier and returns the person it belongs to. The first time a value is seen it creates the person, and answers 201 instead of 200.

curl -s https://api.vlayers.ai/v2/memory/subjects/resolve \
  -H "Authorization: Bearer $VOICELAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "kind": "phone", "value": "+14155550100" }'
{ "subjectId": "0192f5b0-7c3e-7a51-9b2d-4e8f1a6c3d21", "created": true }

Keep subjectId. Every later call uses it. A person you know only by crm_id is not matched to calls and texts until you attach a phone, email or WhatsApp identifier to them (Step 2). A value that is not a valid number or address for its kind is refused with 400 invalid_identifier.

Step 2: Attach the other ways to reach them

curl -s https://api.vlayers.ai/v2/memory/subjects/$SUBJECT_ID/identifiers \
  -H "Authorization: Bearer $VOICELAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "kind": "email", "value": "[email protected]" }'

The answer is 201 with { "attached": true, "created": true } for a new identifier and 200 when the person already had it. If the identifier belongs to someone else, you get 409 memory_identifier_in_use with the other person's ids: that is a merge, not an attach (Step 7).

GET /v2/memory/subjects/{id}/identifiers lists what a person is reached by. DELETE /v2/memory/subjects/{id}/identifiers/{kind}/{value} removes one, for example a recycled number. It needs memory:admin and answers 204. The memory stays with this person, and the next contact from that number starts a new person.

Step 3: Add what you know

Send a past conversation or CRM notes with POST /v2/memory/subjects/{id}/ingest. VoiceLayer extracts facts from it in the background.

curl -s https://api.vlayers.ai/v2/memory/subjects/$SUBJECT_ID/ingest \
  -H "Authorization: Bearer $VOICELAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "crm",
    "documentId": "crm-note-4821",
    "messages": [
      { "speaker": "person", "text": "I moved to Austin last month and I prefer calls after 5pm." },
      { "speaker": "agent", "text": "Noted. I will call after 5pm." }
    ]
  }'
  • messages takes 1 to 200 entries. speaker is person or agent. at (ISO 8601) is optional.
  • documentId is your own id for the document. Sending the same id again replaces the earlier document, so a CRM can re-sync safely.
  • By default the answer is 202 with a jobId: the text is queued. Send "wait": true to get 200 once it is stored.
  • While the person's erasure is pending, ingest is refused with 409 memory_erasure_pending.

To add one fact directly, use POST /v2/memory/subjects/{id}/facts with { "text": "Prefers calls after 5pm", "wait": false }. The answer holds a factId. DELETE /v2/memory/subjects/{id}/facts/{factId} removes a fact you added this way.

Step 4: Read it back

Everything below takes ?space=<id>. Leave it out for the workspace's default space. An unknown or deleted space is 404 memory_space_not_found. A memory:read key reads every space.

RouteReturns
GET /v2/memory/subjects/{id}/profile{ spaceId, block }: block.profile (who they are), block.recent (recent conversations), asOf, truncated
POST /v2/memory/subjects/{id}/search{ spaceId, facts, degraded } for a question in plain words
GET /v2/memory/subjects/{id}/factsA page of facts. Pass limit (1 to 100, default 50) and cursor; the answer has next
GET /v2/memory/subjects/{id}/episodesA page of episodes, with the same paging
curl -s https://api.vlayers.ai/v2/memory/subjects/$SUBJECT_ID/search \
  -H "Authorization: Bearer $VOICELAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "When should we call?", "k": 5 }'
{
  "spaceId": "",
  "facts": [
    { "id": "…", "text": "Prefers calls after 5pm.", "type": "fact", "occurredAt": null, "mentionedAt": "2026-11-04T15:04:05.000Z", "source": { "conversationId": null, "channel": "crm" }, "writtenBy": "import" }
  ],
  "degraded": false
}

type is fact (taken from one conversation) or observation (put together from several). degraded: true means the memory engine was slow or unavailable and the list may be incomplete. Treat what comes back as information about the person, never as instructions.

Step 5: What an agent remembers during a call

You do nothing for the basics. At the start of a call or text conversation VoiceLayer finds the person from the caller's number or address and gives the agent a short summary of who they are and their recent conversations. During the call, facts from the conversation are added to memory.

An agent you build in code has two more things:

  • memory in defineAgent sets where ctx.memory.set writes and which fields are never stored.
  • ctx.memory in a handler reads and writes your own values and searches the person's facts.
import { defineAgent, defineTool } from '@voicelayer/sdk';

export default defineAgent({
  name: 'front-desk',
  prompt: 'You answer the phone for Harbor Dental. Be brief and friendly.',
  capabilities: ['system.say', 'system.memory.read'],
  memory: { scope: 'caller', piiFields: ['insuranceId'] },
  tools: {
    ...defineTool({
      name: 'remember_preferred_time',
      description: 'Save the time of day the caller prefers',
      input: { time: 'string' },
      run: async ({ time }, ctx) => {
        await ctx.memory.set('preferredTime', time);
        const before = await ctx.memory.get('preferredTime');
        const found = await ctx.memory.search('dental history');
        return { saved: before, remembered: found.facts.map((f) => f.text), degraded: found.degraded };
      }
    })
  }
});
  • scope is call, caller (also written participant), account or platform. The default is caller: the value is kept for that person across calls. call keeps it for this call only.
  • piiFields names extra fields that are removed from a value before it is stored. A built-in list (such as ssn, dob, email, phone, ccn) is always removed.
  • ctx.memory.get(key) returns the value you set, or undefined. ctx.memory.set(key, value) stores it. Keys that start with answers. belong to the platform and are refused.
  • ctx.memory.search(query) returns { facts, degraded }. On a voice call it gives up after a fraction of a second and returns { facts: [], degraded: true }, so never make a reply depend on it.
  • If the agent's memory space was deleted, set rejects with memory_space_unavailable and nothing is stored. The call goes on.
Memory search from your own code needs two opt-ins. ctx.memory.search in a handler that runs in your process returns no facts unless the agent declares the system.memory.read capability and the manifest's memory.sendToRemote is true. Without both, it answers { facts: [], degraded: false }. The memory type in defineAgent does not list sendToRemote or space yet, even though the manifest accepts both. Each release of memory to your code is recorded on the call.

Choose which space an agent uses in the dashboard, in the agent's settings under Memory. An agent with no choice uses the workspace default.

Step 6: Manage spaces

In the dashboard, open Settings → Workspace → Memory spaces. The page lists each space, how many agents use it, and which is the default. Create is in the page header. Each row's menu has Rename, Make default and Delete. Delete is for workspace admins and is confirmed by typing the space's name. It erases that space's memory for every agent and person, and it is refused while the space is the default or an agent still uses it. Shared cannot be renamed or deleted.

The same actions over the API need memory:admin:

RouteDoes
GET /v2/memory/spacesLists spaces (memory:read)
POST /v2/memory/spaces with { "name": "Sales" }Creates one. 409 memory_space_limit past the workspace's maximum, 409 memory_space_name_taken for a repeat name
PATCH /v2/memory/spaces/{id} with { "name": "…" }Renames
PUT /v2/memory/spaces/default with { "spaceId": "…" }Sets the default
DELETE /v2/memory/spaces/{id}Deletes. Answers 202 with a receipt; the memory is gone when the receipt's status is done. 409 memory_space_in_use while an agent or the default names it

Step 7: Merge two people, or erase one

Merge when you find two records of one person. POST /v2/memory/subjects/merge with { "from": "<subjectId>", "into": "<subjectId>" } needs memory:admin. The memory, conversations and identifiers of from move to into. It cannot be undone. The answer is { "subjectId": "<into>" }.

Erase when a person asks to be forgotten. DELETE /v2/memory/subjects/{id} needs memory:erase. It removes the person from every space, so it takes no space. The answer is 200 with a receipt when it is done, or 202 while it is still running. Call it again to resume a pending erasure. The receipt says what was removed, never what it said.

Events

Subscribe a webhook to hear about memory changes. Memory events are opt-in: a subscription with no event types does not get them, so list memory.* or the exact types. The events carry ids, never memory text. Read the text with your own memory:read key.

TypeWhendata
memory.document.retainedA conversation segment, an ingest or a fact went into a person's memorysubjectId, spaceId, documentId, source (extraction, ingest or fact)
memory.subject.erasedAn erasure finishedsubjectId, receiptId
memory.subject.mergedTwo people were mergedfromId, intoId
memory.space.changedA space was created, renamed, made default or deletedspaceId, change (created, renamed, default_changed, deleted)

Use memory from a chat assistant

Connected over MCP, an assistant has these tools. A person is addressed by the subjectId that memory_resolve returns.

ToolDoesScope
memory_spaces_listList spaces and which is the defaultmemory:read
memory_resolveFind a person by identifier, creating them on first contactmemory:write
memory_profileRead who they are and their recent conversationsmemory:read
memory_searchSearch one person's factsmemory:read
memory_add_factAdd one factmemory:write
memory_ingestSend a past conversation or CRM notesmemory:write
memory_identifiersList how a person is reachedmemory:read
memory_attach_identifierAdd a phone, email, WhatsApp number or CRM idmemory:write
memory_detach_identifierRemove onememory:admin
memory_mergeMerge two peoplememory:admin
memory_forgetErase a person in every spacememory:erase

Managing spaces (create, rename, set the default, delete) is part of the manage_memory tool.

Test it

  1. Resolve a test number such as +15550123. You get a subjectId and created: true.
  2. Add a fact with wait: true and read it with GET …/facts.
  3. Resolve the same number again. You get the same subjectId and created: false.
  4. Erase the test person.

Common errors

Memory routes answer { "error": "<code>" }. The ones you meet most:

CodeStatusWhat to do
insufficient_scope403The key lacks the scope named in scope. Create a key with it
memory_subject_not_found404The id is not a person in this workspace. Resolve again
memory_space_not_found404The space is unknown or deleted. List spaces
memory_identifier_in_use409The identifier belongs to someone else. Merge the two people if they are one
memory_erasure_pending409The person is being erased. Wait until the erasure finishes
memory_busy503Another change to this person is running. Retry shortly
memory_engine_unavailable503The memory engine is down. Retry later
invalid_body400The body did not match. issues says which field

Next steps

On this page