Memory

A task starts fresh. Memory is how a worker carries what it learned from one task to the next. It is a store of short notes at paths, like a small folder of text files. A worker reads the notes when a task starts, writes new ones as it works, and the next task finds them.

Memory uses Claude Managed Agents' words and shapes: a memory store holds notes, and every change to a note is saved as a version. This page explains stores, notes, which stores a task reads, how history is kept, and dreams, which tidy a store up.

Stores and notes

A memory store is a named set of notes. Its id starts with memstore_. It has a name of 1 to 255 characters, a description of up to 1,024 characters, labels in metadata (up to 16 keys), and an archived_at that is null while the store is in use.

A note is text at a path. Its id starts with mem_. A folder in a listing, a memory_prefix, is only a path that ends with /, and it has no id.

A store holds up to 10,000 notes. These rules apply to every write:

• No two notes may collide on a path. /notes and /notes/todo.md cannot both be notes: a note at the same path, at a folder above it or inside it is 409 with error.type memory_path_conflict_error.
• No saved passwords. A note whose text holds a saved password is refused with 400.
• No writes to an archived store. That is 400.

To change a note only if nobody else has, send a precondition of { "type": "content_sha256", "content_sha256" } with the change. If the note no longer has that text, the answer is 409 with error.type memory_precondition_failed_error. A retry of an update that already landed answers 200 even though its hash is stale. Delete takes the same check as expected_content_sha256 in the query.

A listing of notes takes path_prefix, depth (0 or 1) and view. In the basic view, content is null. The full view returns the text. A listing holds up to 1,000 notes a page, or 20 with view=full.

Which stores a task reads

Every task has a worker's own store. Each worker has one, always read and written, and it does not count toward the workspace's limit of shared stores. A task may also read other stores:

• Name them in resources when you give the task, as { "type": "memory_store", "memory_store_id", "access", "instructions" }. With any named, the task reads only those, and at most 8.
• Name none, and the task reads the stores attached to its worker.

access is read_write (the default) or read_only. instructions, up to 4,096 characters, tell the worker how to use that store.

A task freezes its stores when it is made. A later rename of a store does not reach a task that is already at work, and a task's stores never change after it is made.

The worker sees its stores as folders on the computer, one for each store, under the task's own root: <workspace>/.little-worker/tasks/<task_id>/memory/<short name>/. On the Linux computer, <workspace> is /data/workspace. A Mac does not make these folders yet. Every task also gets memory tools and a short memory section in its context, so the worker can reach its notes without the folders.

Who changed a note

Every change to a note saves a memory version. Its id starts with memver_. A version has an operation, which is created, modified or deleted, and the note's path and text as they were. A deleted version has no text.

created_by says who made the change:

List versions with GET /memory_stores/{memory_store_id}/memory_versions, newest first. Filter by memory_id, operation, task_id, api_key_id, or created_at[gte] and created_at[lte]. A page is 20 by default and at most 100.

A version can be redacted. Redacting empties its path and text but keeps who made the change and when. The newest version of a note that still exists cannot be redacted: that is 409.

How long versions are kept

Versions are kept for 30 days after they are written. The two newest versions of a note that still exists are always kept, whatever their age, so a note that rarely changes can keep history longer. Versions of a deleted note, and redacted versions, follow the same rule. It is the same on every plan. A core on your own computer keeps every version.

To keep memory history longer, export the versions through the API before they go.

Archive and delete

• Archive a store with POST /memory_stores/{memory_store_id}/archive. It is one way: an archived store can only be read. It frees its place under the workspace limit.
• Delete a store with DELETE /memory_stores/{memory_store_id}. The store, its notes and its versions are removed. A worker's own store cannot be deleted: that is 409.

A workspace keeps up to 1,000 live shared stores. A worker's own store does not count, and archiving a store frees its place. One more is 400.

Dreams

A dream cleans up a memory store. It reads one store, and up to 100 tasks to learn from, and writes a tidier store. A dream runs as a task: task_id names it, and you read its events with the task routes.

Make one with POST /dreams:

• inputs holds exactly one { "type": "memory_store", "memory_store_id" } and at most one { "type": "tasks", "task_ids" } with 1 to 100 tasks.
• model is a model id, or { "id" }. Speed fast is 400.
• instructions, up to 4,096 characters, guide the dream.
• output_behavior is { "type": "create_new" }, the default, or { "type": "update_existing", "memory_store_id" } with the input store.

A dream starts pending and then moves through its status: pending, running, and then completed, failed or canceled. outputs names the store with the result once the dream starts. usage counts its tokens, and error and ended_at are set when it ends.

POST /dreams/{dream_id}/cancel stops a dream. One that ended completed or failed is 400. POST /dreams/{dream_id}/archive archives one that has ended, and it then leaves the list. A pending or running dream is 400.

A dream that fails has an error.type:

Limits

Next steps

• Tasks: how a task is given its stores in resources.
• Routines: hand a store to every task a routine makes.
• Files: the other thing a task may be given to work with.