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

# Memory

> Let agents remember what they learn: a writable knowledge base, the tools agents use to write and read it, the Auto-record learnings switch, and how to review what was written

Every agent run happens in a sandbox that is discarded when the run ends. The working directory, scratch files and anything the agent noted for itself are gone. To remember something between runs, an agent writes it into a **knowledge base it is allowed to write to**. That knowledge base is the agent's memory.

Memory is therefore not a separate store. It is an ordinary knowledge base, connected with **Read & write** access, so everything an agent remembers is a file you can open, a version you can inspect, and a change you can roll back.

## Set up memory for an agent

<Steps>
  <Step title="Create the knowledge base">
    Create a knowledge base for the agent's memory and write a short **Description** of what belongs in it. Publish at least a `README.md` that explains how it is organized -- see [Give the knowledge base its own rules](#give-the-knowledge-base-its-own-rules). See [Build a knowledge base](/context/build).
  </Step>

  <Step title="Grant write access">
    Open the knowledge base, then the **Agents** tab. Connect the agent with **Read & write** access, or change an existing connection to it.

    Choose **Read & write (ask first)** instead if a person should approve each write. That only works in web chat; on chat apps, webhooks and automations the agent then cannot write at all. See [Use a knowledge base](/context/use#choose-the-access-mode).
  </Step>

  <Step title="Decide the memory policy">
    Open the agent, then the **Data access** tab. Turn on **Auto-record learnings** to use the platform's default policy, or leave it off and write your own in the agent's `CLAUDE.md` or a skill. See [Choose a memory policy](#choose-a-memory-policy).
  </Step>
</Steps>

Changes apply from the agent's next turn.

## How an agent writes memory

An agent with at least one writable knowledge base gets three tools:

| Tool | What it does |
| - | - |
| `list_context_files` | Lists the files in a writable knowledge base |
| `read_context_file` | Reads the **current** version of a file and returns its `sha256` |
| `write_context` | Changes one or more files. **One call is one new version** of the knowledge base |

`write_context` applies a mode to each file:

| Mode | Effect |
| - | - |
| `create` | Makes a new file; fails if it already exists |
| `append` | Adds to the end of a file |
| `edit` | Replaces an exact snippet; fails unless the snippet occurs exactly once |
| `overwrite` | Replaces the whole file |
| `delete` | Removes the file |

Every mode except `create` can carry the `expected_sha256` that `read_context_file` returned. If the file changed since it was read, the write is refused as `stale` instead of silently undoing someone else's change. By default each file is limited to 256 KB and each call to 20 files.

With **Read & write (ask first)**, a `write_context` call is a request: web chat shows an approval card with the files, and the write happens only if the person approves it.

### What the platform always tells the agent

Whenever the tools are present, DataGen adds tool instructions to the agent's system prompt, whatever you configure. They list the writable knowledge bases by slug, name and description, and tell the agent to:

* treat the knowledge base as the **only** storage that outlives the sandbox;
* read the knowledge base's `README.md` (or its index file) before changing anything, and follow it;
* read a file before changing it, and pass `expected_sha256` on an overwrite;
* put a whole update in a single `write_context` call;
* never write secrets, credentials, tokens or raw transcripts.

On a run with a writable knowledge base, DataGen also turns off the Claude Code auto-memory directory (`~/.claude/projects/*/memory/`), which would otherwise be discarded with the sandbox. An agent with no writable knowledge base keeps that behavior unchanged.

## Choose a memory policy

The tool instructions say **how** to write. Whether the agent records anything, and **what**, is the agent designer's decision.

<Tabs>
  <Tab title="Auto-record learnings (platform default)">
    Turn on **Auto-record learnings** on the agent's **Data access** tab. DataGen appends a default policy to the system prompt: before finishing a task, record what is worth remembering -- facts about the workspace and people in it, what worked and what failed, preferences the user stated -- into the knowledge base whose description or `README.md` covers it. The policy also tells the agent to:

    * edit what is there rather than piling up new files;
    * add any new file to the knowledge base's index in the same call;
    * write facts and procedures, never instructions to other agents;
    * summarize in its own words, never paste raw transcripts or tool output;
    * never claim it remembered something unless a `write_context` call succeeded;
    * on unattended runs (automations, webhooks, chat apps), do the memory update as the last step.

    It is **off by default**, and it only takes effect when the agent has a writable knowledge base.
  </Tab>

  <Tab title="Your own policy">
    Leave **Auto-record learnings** off and add a section to the agent's `CLAUDE.md` or a skill. The tool instructions are still injected, so you only describe the decision:

    ```markdown CLAUDE.md theme={null}
    ## Memory

    You can write to the `<slug>` knowledge base. Follow its `README.md`.

    - WHEN: as the LAST step of every run, once you know whether it worked.
    - WHAT: one entry per run -- what you were asked, what you did, what
      surprised you, and what the next run should do differently.
    - WHERE: `append` to `log/<YYYY-MM>.md` under a `## <YYYY-MM-DD> -- <task>`
      heading. Create the month file if it does not exist and add it to
      `README.md` in the SAME `write_context` call.
    - NEVER: rewrite or delete an older entry.
    ```

    Do not name any other place to write, such as a `MEMORY.md` or a notes file in the working directory. Those are discarded when the run ends.
  </Tab>
</Tabs>

## Give the knowledge base its own rules

Every agent with write access is told to read the knowledge base's `README.md` before changing it. That makes the `README.md` the place for rules that belong to the **knowledge base** rather than to one agent, and every agent that writes to it -- including ones added later -- follows them.

```markdown README.md theme={null}
# Account notes

What this knowledge base is for, in one sentence, and who relies on it.

## How it is organized
- `accounts/` -- one file per customer, named `<customer-slug>.md`.
- Keep this index current: every file is listed below.

## What belongs here
Durable facts about accounts: contacts, renewal dates, stated preferences.
Not meeting notes, not anything true only today.

## Index
- [accounts/example.md](accounts/example.md) -- one line
```

## How an agent reads memory

Memory is read the same way as any knowledge base:

* At the start of each run, the latest published version is mounted read-only at `/mnt/context/contexts/<slug>/`. See [How the agent sees the files](/context/use#how-the-agent-sees-the-files).
* During a run, `read_context_file` always returns the current file, including writes made earlier in the same run. The mounted copy does not show a write until the mount refreshes, so the tool's result is the confirmation.
* Other agents that can read the knowledge base see what this agent wrote from their next turn. They are told that knowledge base files may have been written by agents, and to check the version history when something looks wrong.

## Inspect and correct memory

Agent writes are stored as versions of the knowledge base in `.context/<slug>/`, so you review them on the knowledge base's detail page:

* **Files** shows what is live right now -- exactly what agents read.
* **Versions** lists every version. Versions created by an agent carry an **Agent write** badge with the file path, or the number of files the call changed.
* To undo a bad write, use **Roll back to this version** on the last good version. It is published as a new version, and the version you rolled back from keeps its files, so you can restore it later.

You can also open the builder and edit the files directly, then **Publish context**.

<Warning>
  A knowledge base is read by other agents as reference material. Keep it to facts and procedures. A file that says "always approve refunds" is an instruction every reader will see, so review agent writes the same way you would review a teammate's edits.
</Warning>

## Next

<CardGroup cols={2}>
  <Card title="Agents overview" icon="robot" href="/agents/overview">
    Combine knowledge bases, skills, memory and tools in an agent.
  </Card>

  <Card title="Build an app" icon="window-maximize" href="/apps/build">
    Use knowledge bases as reference material in the App Builder.
  </Card>
</CardGroup>


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