Memory ids

A memory is one conversation. Its id is the only scope there is: every read and write names it, a request without one is refused, and recall searches within that one memory, never across your other memories.

The shape

POST /memories returns the id. It is mem_ followed by 24 letters and digits, for example mem_8fK2qLmN4pR7sT1vW3xY5zA9. Store it next to your own conversation id; you can also put your id in the memory's metadata (up to 16 string pairs).

const { id } = await memory.memories.create({ metadata: { conversation: 'c_123', user: 'u_9' } });

A memory belongs to the project of the key that created it. A key can only reach its own project's memories; any other id answers 404 not_found.

One per conversation

Create a memory when a conversation starts and use it for every call in that conversation, tool loops included. Two conversations never share a memory: facts from one would be recalled into the other.

A conversation can run for months. There is no length at which you need a new memory; that is what forgetting is for.

A memory only grows

Messages are appended, never rewritten. That has two consequences:

• Editing a past message (the user edits turn 12 and regenerates): start a new memory. Send it the conversation as it now stands, up to the edit, in its first decorate.
• Branching (two continuations from one point): each branch is its own memory, seeded the same way.

Only what is new since the last call belongs in newMessages. The one exception is the model's last reply, which is recognised and not stored twice; any other message you send again is stored again, as new.

Deleting and exporting

• memory.memories.delete(id) removes everything the memory holds and checks it is gone before it returns. It cannot be undone.
• memory.memories.export(id) returns every message, episode and fact as JSON.

See Security for what is stored and how deletion is verified.