> ## Documentation Index
> Fetch the complete documentation index at: https://docs.matrices.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Memory

> What an agent keeps between threads.

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.

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
curl -X PUT "https://api.matrices.com/v1/memory/entry?key=runbooks%2Fq3-close" \
  -H "Authorization: Bearer $MATRICES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "value": "Cite invoice IDs. Mark estimates clearly.", "expectedVersion": "0" }'
```

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.

<Info>
  **Namespaced** to one agent or the workspace · **Versioned** on every write ·
  **Values** up to 40 KiB · **Granted by** `tool:builtin:memory.*`
</Info>

## Rules

* Agent memory follows the agent, so sibling threads share it. See
  [Rules](/model/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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.