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.
Related
Do you like what you are reading? Subscribe to receive updates.
Unsubscribe anytime