§03 · Building agents

Memory

Durable, versioned context that agents read at the start of a session and write back at the end. It lives in the control plane, so it survives pod restarts, cluster migrations, and the agent itself.

Most agents forget everything between runs. A memory is a named markdown document an agent reads on the way in and can write on the way out — conventions it learned, decisions it made, the shape of a codebase it keeps rediscovering. Because it is held centrally rather than on a pod volume, performance compounds instead of resetting. Open Capabilities → Memory.

What memory is

A markdown document the platform owns and versions, attached to Agents rather than baked into any one of them.
Read into the agent's context at boot, or listed for it to open on demand.
Written to by agents you allow, editable by people from the dashboard.

Memory vs skill vs context

Skill: instructions. How to behave. Curated ahead of time, effectively versionless.
Context: everything assembled fresh for one run. Rebuilt every boot, dies with the pod.
Memory: what has been learned so far. Versioned, portable across agents and runtimes, outlives the pod that wrote it.

Write a memory

The Memory page listing the tenant's memories with defaults, attachments, and history actions — The Memory page: every memory in the tenant, with its defaults, attachments, and history.

A memory has a kebab-case name, a description, and a markdown body. The name is the on-disk identity inside the pod and is immutable after creation; the body is edited on its own full page rather than in a dialog, because editing durable knowledge should feel like editing a document. Agents write to memory the same way, through their own credential.

Attach it to agents

Pick memories on an agent's create or edit form. Each attachment carries a mode and a routing flag:

Setting	Meaning
`readWrite`	The agent reads the memory and may write new versions back.
`readOnly`	The agent reads it and cannot change it — the right mode for shared house knowledge.
`read first`	Preload the body into the session instead of leaving it to be fetched on demand. Defaults on for readWrite, off for readOnly.

Attachments follow the omitted-preserves rule: send the list to replace it, send an empty list to detach everything, omit it and saving another part of the form cannot silently detach memory. Apps and web agents take the same attachment list for their embedded agents.

Tenant defaults

A memory marked tenant default reaches agents without being attached one by one — the way to give a whole fleet the same operating context. Its reach is either every agent in the tenant, or narrowed to a single deployment's agents.

Versions & rollback

Every write is an immutable version carrying its author — a person's email, or the canonical identity of the agent that wrote it — a content hash, and a flag when it overwrote a concurrent edit. The history view walks them, and rollback restores an earlier version as a new one, so history is never rewritten. List rows show the latest author, which is usually enough to answer “who changed this” without opening anything.

Writes are compare-and-swap against the current version, and an agent holds a short lease while writing, so two agents on one memory cannot silently clobber each other. Per-run visibility shows which pod wrote which versions; reads are not attributed per run.

●memory API· http

1GET  /api/v1/memories
2GET  /api/v1/memories/{id}
3GET  /api/v1/memories/{id}/versions
4POST /api/v1/memories/{id}/rollback    { "version": 7 }

Promote

Knowledge that started local is often worth sharing. Promote copies a chosen version of a memory into a brand-new tenant default, recording where it came from; the source is left untouched. Promote to a tool appends a version into a tool's notes as a provenance-tagged section — an append, never a clobber, so earlier promotes and hand-written notes survive.

The memory map

The map view draws the graph: memories, the agents and apps attached to them, a single node standing in for “all agents” where a tenant-wide default reaches, and dashed edges for promote provenance. It is the quickest way to see which memories are actually in use and which are orphaned.

Access & credentials

Visibility. Memories are open to anyone with memory read access by default; the Access panel restricts one to named users, teams, or roles. A memory's detail lists the agents referencing it, by name.
Agent write credentials. Each agent gets its own memory write credential. Rotating it invalidates the old one immediately — running pods lose write access until they restart. That is the compromise response, and it is deliberately abrupt.
Deleting a memory removes it and its bindings cleanly; attached agents are updated rather than left pointing at nothing.

Previous · Building agentsMCP servers Next · Building agents File systems