Docs · Guides
Memory and recall
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 documents and your past mail.
#Save and recall
// 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);
}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 sameid,200instead of201. - `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 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:readandmemory:write. Thesend_readpreset has both,read_onlyhasmemory:read. Recall over knowledge also needsknowledge:read, and over mailsearch; 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 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 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_memoryandforget. mr.memoriesandmr.recallin the SDKs.- The Memory page in the dashboard.
Plans: 1,000 memories on Free, 25,000 on Builder, 250,000 on Team. Recall is not counted.