# Memory

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

Source: https://docs.vlayers.ai/developers/memory

Kind: How-to guide

## 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

- A secret API key. Create one under **Access → New → Create API key** (see [Authentication and API keys](https://docs.vlayers.ai/get-started/authentication)) 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`.

```bash
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`.

```bash
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" }'
```

```json
{ "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

```bash
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": "ada@example.org" }'
```

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.

```bash
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.

| 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 |

```bash
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 }'
```

```json
{
  "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.

```ts
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.

> **Warning:** **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`:

| 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](https://docs.vlayers.ai/developers/receive/webhooks) 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](https://docs.vlayers.ai/developers/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

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:

| 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](https://docs.vlayers.ai/developers/sdks/voice-agents): the rest of `ctx`.
- [Receive with webhooks](https://docs.vlayers.ai/developers/receive/webhooks).
- [Connect VoiceLayer to ChatGPT, Claude, Cursor](https://docs.vlayers.ai/get-started/connect-chatgpt-claude-cursor).
