Memory
An agent's memory is its own tree of files, read and written with the verbs, mounted into the code sandbox as /workspace, and open to the people the agent is shared with except for its private folder.

An agent's memory is its own file tree, ~/memory/ in its Space. It belongs to one agent, and all of that agent's sessions share it. An agent keeps notes, drafts and code there, for example ~/memory/notes/topic.md. Anyone the agent is shared with can browse it on the Memory tab of the app, except ~/memory/private/, which only the owner can reach.

Memory is a directory on the app environment, the server that runs the agent. Files are UTF-8 text or binary. The agent reaches memory with read and write. Code run by execute sees it as /workspace.

This page says how memory is read and written, what the private/ part is, and what is unsafe to keep there.

Reading and writing

    read ~/memory/<path> returns a file, or a listing for a directory. The address table is on read.

    write ~/memory/<path> replaces a file whole. There is no append. Options delete a path, download a URL to it, or save a session attachment to it. See write.

    Memory writes never need a grant, and memory has no quota. A path can be at most 512 bytes and 16 levels deep.

    Each turn's Space index carries a one-line summary of the top level of memory.

    A memory markdown file can be published as a document with options.fromPath on an hm:// write. Any memory file can be published to IPFS. Both need the publish grant.

Private memory

The path ~/memory/private/ is for the owner alone. It is stored outside the directory that is mounted into code sandboxes, so code run by execute cannot see it. Only two things can read or write it: a signed action from the agent's owner, and an interactive run the owner started. Every other run gets a 403.

What not to keep in /workspace

/workspace is shared. Only one sandbox holds an agent's memory directory at a time. But the calls of every open session, every delegated child and every trigger firing take turns on it. And the read and write verbs on the host touch the same files while a sandbox runs. The host and the sandbox do not share file caches or file locks. So two writers on one file at the same time can damage it. The rules:

    Do not keep a SQLite database under /workspace.

    Do not keep lock files, or any file that needs atomic or locked writes.

    Do not append to one shared log from several firings.

    Do not read a shared JSON file, change it, and write it back from code.

    Keep lasting state in memory files written whole with the write verb. Use one file per event or record, not one shared file that grows. Merge them later in a single run when you need a summary.

    Treat disk I/O error, database is locked, or a corrupt index under /workspace as two writers meeting on one file. The disk is fine. Move the state out of the shared file.

Do you like what you are reading? Subscribe to receive updates.

Unsubscribe anytime

Connections0
Linked document · Outgoing linkLinked documentLinked document · Outgoing linkLinked documentLinked document · Outgoing linkLinked documentLinked document · Outgoing linkLinked documentLinked document · Outgoing linkLinked documentLinked document · Outgoing linkLinked documentLinked document · Outgoing linkLinked documentLinked document · Outgoing linkLinked documentLinked document · Outgoing linkLinked documentLinked document · Outgoing linkLinked documentLinked document · Outgoing linkLinked documentLinked document · Outgoing linkLinked documentLinked document · Outgoing linkLinked documentLinked document · Outgoing linkLinked documentLinked document · Outgoing linkLinked documentLinked document · Outgoing linkLinked documentLinked document · Outgoing linkLinked documentMemoryMemory
Citations 0Children & links 17

Loading child documents…

Connections show where other documents or comments link to this document.

Related documents

Loading connections…