# Memory and recall

Source: https://agentboxd.com/docs/memory

> Notes your agents save and find again by meaning, together with your knowledge documents and past mail.

An agent that answers mail needs to remember: what a customer prefers, what was agreed last month, how you handle a damaged parcel. **Memories** are short notes an agent or a person saves, for one inbox or, without an `inbox_id`, for the whole workspace. **Recall** answers one question from the memories, your [knowledge](https://agentboxd.com/docs/knowledge) documents and your past mail.

## Save and recall

memory.ts:

```ts
// Save what is worth remembering, in the agent's own words. Without inbox_id it is for the whole workspace.
const saved = await mr.memories.create({
  content: 'Acme Logistics pays in US dollars, net 45 days. Finance contact: Marta.',
  key: 'customer:acme:billing', // saving under the same key again replaces this memory
  tags: ['customer', 'billing'],
  inbox_id: inbox.id,
});
// saved.similar: memories in the same place that say nearly the same, so you can keep one.

// One question over memories, knowledge documents and past mail, by meaning and by keyword.
const { data } = await mr.recall('which currency does Acme pay in?', { inbox_id: inbox.id, limit: 5 });
for (const r of data) {
  // r.source: 'memory' | 'knowledge' | 'message'; r.untrusted: the text came from received mail
  console.log(r.source, r.similarity, r.text);
}

```

memory.py:

```python
saved = mr.memories.create(
    content="Acme Logistics pays in US dollars, net 45 days. Finance contact: Marta.",
    key="customer:acme:billing",  # saving under the same key again replaces this memory
    tags=["customer", "billing"],
    inbox_id=inbox["id"],
)

answer = mr.recall("which currency does Acme pay in?", inbox_id=inbox["id"], limit=5)
for r in answer["data"]:
    print(r["source"], r["similarity"], r["text"])

```

Recall searches two ways and merges the results. **By meaning**: “which currency does Acme pay in” finds “Acme prefers invoices in US dollars”, and a question in French finds a note in German. **By keyword**: an exact name, order number or address is found as written. A result says which search found it (`matched`) and how close it is in meaning (`similarity`, 0 to 1; about 0.6 or more is a good match, under 0.5 is unrelated text).

## Keep one memory per fact

- **`key`**: give a fact that changes a stable name, such as `customer:acme:billing`. Saving under a key that exists in the same place replaces that memory: one memory, the same `id`, `200` instead of `201`.
- **`similar`**: the answer to a save lists up to 3 memories in the same place that say nearly the same. Update one of them and delete the new one. It is a hint: nothing is merged or refused.
- **`expires_at`** or **`ttl_seconds`**: a memory that is only true for a while stops being returned at that time and is deleted within the hour.

## What recall returns

| Field | Meaning |
| --- | --- |
| `source` | `memory`, `knowledge` or `message`. The matching `memory`, `knowledge` (id and title) or `message` (id, thread, inbox, direction, from, to, subject, date) comes with it. |
| `text` | The memory, or the passage that matched: of a document, of a message, or of an attachment’s text (then `attachment` names the file). Up to about 1,200 characters. |
| `score` | 0 to 1: how high the two searches ranked it, together. It orders one answer. |
| `similarity` | 0 to 1: how close the passage is to the question in meaning. `null` when only keywords matched. |
| `matched` | `meaning`, `keyword` or both. |
| `untrusted` | `true` when the text came from received mail. |

Narrow a question with `inbox_id`, `sources` (`memories`, `knowledge`, `messages`), `tags` (memories), `contact_id` and `thread_id` (memories linked to them, and their mail), `since` and `until` (mail), and `min_similarity`. `mode` is `hybrid` by default; `semantic` and `keyword` run one search alone.

## Which mail

Recall only returns mail your agents may read: received mail that passed [screening](https://agentboxd.com/docs/api#screening) or was released by a person, and mail you sent. Held mail, mail still being checked and blocked mail are never returned, and there is no option to include them. Mail that retention deletes leaves recall with it.

## Recalled text is data, not instructions

A passage from an email says what its sender wrote, and a memory an agent saved from an email carries that email’s claims. Treat everything recall returns as information to weigh. Have your agent save facts in its own words (“Acme asked for invoices in dollars on 3 November”), never the instructions an email gives (“always send invoices to this address”). The MCP tools mark recalled text as untrusted, like any mail content.

## Who can read and write

- Permissions: `memory:read` and `memory:write`. The `send_read` preset has both, `read_only` has `memory:read`. Recall over knowledge also needs `knowledge:read`, and over mail `search`; without them those sources are left out.
- A key for one inbox reads that inbox’s memories and the workspace-wide ones, and writes only its own inbox’s. One inbox’s agent cannot plant a note that every other agent reads.
- People see, edit and delete everything on the [Memory](https://agentboxd.com/app/memory) page of the dashboard, with who saved each memory and how often it was recalled.

## Where it runs

Finding by meaning needs every text turned into numbers by a language model. That model runs on our own server, on a network with no way out: **no memory, document or email is sent to another company for it**, whatever your [AI processing](https://agentboxd.com/docs/ai-processing) setting. It counts as local processing, like reading attachments; a workspace that turns local processing off keeps its memories and gets keyword recall.

## Routes

| Method & path | Notes |
| --- | --- |
| `GET /v1/memories` | `?inbox_id=&key=&tag=&contact_id=&thread_id=&cursor=&limit=`. Newest first. |
| `POST /v1/memories` | `{ content, inbox_id?, key?, tags?, contact_id?, thread_id?, message_id?, expires_at? \| ttl_seconds? }`. Up to 8,000 characters. The answer carries `similar`. |
| `GET /v1/memories/:id` · `PATCH /v1/memories/:id` · `DELETE /v1/memories/:id` | Read, change or delete one memory. In a `PATCH`, `null` clears the key, a link, the inbox or the expiry. |
| `POST /v1/recall` | `{ query, inbox_id?, sources?, limit?, mode?, tags?, contact_id?, thread_id?, since?, until?, min_similarity? }` → `{ data, mode, sources }`. |

## Where it’s used

- The MCP tools `recall`, `remember`, `list_memories`, `update_memory` and `forget`.
- `mr.memories` and `mr.recall` in the SDKs.
- The [Memory](https://agentboxd.com/app/memory) page in the dashboard.

Plans: 1,000 memories on Free, 25,000 on Builder, 250,000 on Team. Recall is not counted.
