Skip to main content
A profile says how an agent behaves; memory is what it picks up while working: preferences, task state, a note from a thread three weeks ago. Entries are key/value records in one of two namespaces. The agent namespace is private to one agent (user preferences, its own notes). The workspace namespace is readable and writable by every agent (shared playbooks, reference material). Keys are whatever you like, GOALS or runbooks/q3-close. Agents use the memory.read, memory.write, memory.list, and memory.delete tools; your application reaches the same entries over HTTP at /v1/memory and /v1/agents/{agentId}/memory. Every write is compare-and-set, so you have to say which version you expect to be overwriting. Read the entry, send its version back as expectedVersion, and use "0" only when the read confirmed the key is absent. If the version moved in between, someone else wrote first and your write is rejected. Re-read and retry.
One thing to resist is putting instructions in workspace memory. Stable behavior belongs in the profile’s systemPrompt; memory is for facts an agent should be able to change itself. For files and generated documents, use artifacts.* instead.
Namespaced to one agent or the workspace · Versioned on every write · Values up to 40 KiB · Granted by tool:builtin:memory.*

​
Rules

  • Agent memory follows the agent, so sibling threads share it. See Rules.
  • An agent still needs a role granting the memory tools.

​
API

  • GET/PUT/DELETE /v1/memory/entry, and the /v1/agents/{agentId}/memory equivalents. GET /v1/memory lists metadata, not bodies.