Memory is the ~/memory/ branch of the Space: the files an agent keeps between sessions. Notes, working data, drafts, downloaded material — anything worth remembering is a file, addressed by path, handled through the same read and write verbs as every other address. There is no separate "memory API".

Physically it is a real directory — <stateDir>/memory/ — per agent, not rows in a table. That choice is what makes the next section possible.

Semantics

read ~/memory/<path> returns a file. UTF-8 decodable content comes back as text; anything else (including anything containing a NUL byte) comes back marked binary, with metadata rather than mangled characters. A directory path — or ~/memory/ itself — returns a listing with sizes.

write ~/memory/<path> writes content. Parent folders are created automatically. A write replaces the whole file — there is no append, so read-modify-write is the pattern.

{delete: true} removes a file or a whole directory, recursively.

{fromUrl} downloads an http(s) URL straight to the path, inferring a file extension from the content type when the path lacks one. The timeout is an idle timeout, not a total one — a slow but progressing download is fine; a stalled one is aborted after 60 seconds.

{fromAttachment} saves a conversation attachment into memory.

Memory writes are never gated — no grant required, by design. The publish grant guards signed public writing to the network; an agent's own files are its own business (Agents and Grants).

Bounds are on paths, not size: 512 bytes of path, 16 levels deep. There is no size quota on memory itself — worth stating plainly, because earlier documentation claimed caps that never existed in the code.

Memory meets execution

When an agent runs code through execute, the sandbox's /workspace is the agent's memory directory, bind-mounted in, with the working directory set to it. Files arrive in the sandbox and results leave it through ~/memory — not through a separate file-passing protocol, which is why execute has no files parameter. Write an input file, run the code, read the output back, all with the same two verbs.

Changed files are reported back from a run so the agent knows what its own code touched.

Memory in the index

The memory tree's top level appears in the <space> index carried by every system prompt, so the agent always knows what it has saved without loading any of it. Every write, delete, and download invalidates that cached index (The Space).

Owner access

Memory is not a black box to the person who owns the agent: ListAgentMemory, ReadAgentMemoryFile, WriteAgentMemoryFile, DeleteAgentMemoryFile, DownloadAgentMemoryFile and UploadAgentMemoryFileToIpfs are protocol actions, and the desktop's Memory tab is a file browser over them.

The Space — the tree memory lives in

Execution — /workspace is memory

Attachments · The Five Verbs

Semantics

Memory meets execution

Memory in the index

Owner access

Related