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

1. 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. See Build a knowledge base.

2. 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.

3. 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.

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.

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.

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:

CLAUDE.md

## 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.

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.

README.md

# 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.
• 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.

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.

Next

Agents overview

Combine knowledge bases, skills, memory and tools in an agent.

Build an app

Use knowledge bases as reference material in the App Builder.