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_userand a few channel ids such astelegram_user. Useexternal_userfor 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
- A secret API key. Create one under Access → New → Create API key (see Authentication and API keys) with the scopes you need:
| Scope | Lets the key |
|---|---|
memory:read | List spaces, read a profile, list facts and episodes, search |
memory:write | Find or create a person, add facts, send history, attach an identifier |
memory:erase | Erase a person |
memory:admin | Create, 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 aboveStep 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." }
]
}'messagestakes 1 to 200 entries.speakerispersonoragent.at(ISO 8601) is optional.documentIdis 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
202with ajobId: the text is queued. Send"wait": trueto get200once 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.
| Route | Returns |
|---|---|
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}/facts | A page of facts. Pass limit (1 to 100, default 50) and cursor; the answer has next |
GET /v2/memory/subjects/{id}/episodes | A 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:
memoryindefineAgentsets wherectx.memory.setwrites and which fields are never stored.ctx.memoryin 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 };
}
})
}
});scopeiscall,caller(also writtenparticipant),accountorplatform. The default iscaller: the value is kept for that person across calls.callkeeps it for this call only.piiFieldsnames extra fields that are removed from a value before it is stored. A built-in list (such asssn,dob,email,phone,ccn) is always removed.ctx.memory.get(key)returns the value you set, orundefined.ctx.memory.set(key, value)stores it. Keys that start withanswers.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,
setrejects withmemory_space_unavailableand nothing is stored. The call goes on.
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:
| Route | Does |
|---|---|
GET /v2/memory/spaces | Lists 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.
| Type | When | data |
|---|---|---|
memory.document.retained | A conversation segment, an ingest or a fact went into a person's memory | subjectId, spaceId, documentId, source (extraction, ingest or fact) |
memory.subject.erased | An erasure finished | subjectId, receiptId |
memory.subject.merged | Two people were merged | fromId, intoId |
memory.space.changed | A space was created, renamed, made default or deleted | spaceId, 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.
| Tool | Does | Scope |
|---|---|---|
memory_spaces_list | List spaces and which is the default | memory:read |
memory_resolve | Find a person by identifier, creating them on first contact | memory:write |
memory_profile | Read who they are and their recent conversations | memory:read |
memory_search | Search one person's facts | memory:read |
memory_add_fact | Add one fact | memory:write |
memory_ingest | Send a past conversation or CRM notes | memory:write |
memory_identifiers | List how a person is reached | memory:read |
memory_attach_identifier | Add a phone, email, WhatsApp number or CRM id | memory:write |
memory_detach_identifier | Remove one | memory:admin |
memory_merge | Merge two people | memory:admin |
memory_forget | Erase a person in every space | memory:erase |
Managing spaces (create, rename, set the default, delete) is part of the manage_memory tool.
Test it
- Resolve a test number such as
+15550123. You get asubjectIdandcreated: true. - Add a fact with
wait: trueand read it withGET …/facts. - Resolve the same number again. You get the same
subjectIdandcreated: false. - Erase the test person.
Common errors
Memory routes answer { "error": "<code>" }. The ones you meet most:
| Code | Status | What to do |
|---|---|---|
insufficient_scope | 403 | The key lacks the scope named in scope. Create a key with it |
memory_subject_not_found | 404 | The id is not a person in this workspace. Resolve again |
memory_space_not_found | 404 | The space is unknown or deleted. List spaces |
memory_identifier_in_use | 409 | The identifier belongs to someone else. Merge the two people if they are one |
memory_erasure_pending | 409 | The person is being erased. Wait until the erasure finishes |
memory_busy | 503 | Another change to this person is running. Retry shortly |
memory_engine_unavailable | 503 | The memory engine is down. Retry later |
invalid_body | 400 | The body did not match. issues says which field |
Next steps
- Voice agents in code: the rest of
ctx. - Receive with webhooks.
- Connect VoiceLayer to ChatGPT, Claude, Cursor.