Scratchpad
The scratchpad is a session-scoped working memory that the agent can use to store, retrieve, edit, and manage content without consuming conversation context. Entries are identified by string names and persist across turns within a session.
When the scratchpad is used
- Proactively: The agent stores intermediate results (extracted text, API responses, research notes) for later use.
- Via
scratchpadparameter: any tool call carrying one has its output saved there instead of returned inline. See Scratchpad parameter for which tools advertise it. - Automatically: when a tool’s output exceeds 30,000 bytes, it is saved under a generated name (e.g.
execute_command_a1b2c3_1) and replaced with a preview. Reading the entry back is never treated that way: ascratchpad_readreply stays inline however large, sized to what fits in the context window (seelimitbelow).
Tools
The whole family ships default-active; no load_tool round-trip is required to use any of them.
scratchpad_write
Store content in the scratchpad. If the name already exists, the content is overwritten.
Permission: Read
| Name | Type | Required | Description |
|---|---|---|---|
name | string | yes | Name for the entry |
content | string | yes | The content to store |
scratchpad_read
Read or search a scratchpad entry by name.
Permission: Read
| Name | Type | Required | Description |
|---|---|---|---|
name | string | yes | The entry name |
offset | integer | no | Byte offset to start reading from (default: 0) |
limit | integer | no | Maximum bytes to return. Pass the entry’s size to load all content in one call; a read that would carry the context past the context_ceiling_percent line is cut there, whether or not auto_compact is on, and the reply names the offset to continue from. The cut is sized by a token bound that errs toward cutting: letters count about five to a token, every digit, symbol and non-ASCII character counts as one, so dense text such as numbers, hashes or JSON is cut sooner than prose. A read never returns less than the 30,000 bytes any tool may return inline. (Default and exact value are advertised in the tool’s parameter schema.) |
regex | string | no | Search the entry and return matching lines (capped, exact value advertised in the tool’s parameter schema). |
scratchpad_edit
Edit a scratchpad entry in place. Provide content for a full overwrite, or old_string/new_string for targeted replacement.
Permission: Read
| Name | Type | Required | Description |
|---|---|---|---|
name | string | yes | The entry name |
content | string | no | Full replacement (mutually exclusive with old/new) |
old_string | string | no | String to find |
new_string | string | no | Replacement string |
replace_all | boolean | no | Replace all occurrences (default: false) |
scratchpad_list
List all scratchpad entries as a table with Name, Size, Created and Origin columns, the last own for an entry this session wrote and inherited for one a parent lent a sub-agent read-only. No parameters.
Permission: Read
scratchpad_delete
Delete a scratchpad entry by name.
Permission: Read
| Name | Type | Required | Description |
|---|---|---|---|
name | string | yes | The entry name to delete |
scratchpad_merge
Combine several entries into one without routing the bytes through the conversation. Useful for
collecting parallel sub-agent reports. The entries go in the order given: sources first, as
listed, then every own entry whose name starts with prefix, in name order. The sources are kept
as they are; nothing is deleted, and target is overwritten if it exists. A sub-agent cannot merge
into a name it inherited read-only from its parent, though it may name such an entry in sources;
prefix selects only its own entries.
Permission: Read
| Name | Type | Required | Description |
|---|---|---|---|
sources | array of string | no | Entry names to combine, in this order; optional when prefix is given |
prefix | string | no | Also combine every own entry whose name starts with this, in name order, after sources; target itself is never selected |
target | string | yes | Name to store the result under; overwrites if it exists |
format | string | no | concat_with_headers (default) puts a --- name --- line before each entry’s content, concat joins the contents with a newline, json_array parses each content as JSON (quoting one that is not) into one compact array |
scratchpad_rename
Rename an entry without round-tripping its content through the conversation. Errors if old does
not exist, if new already exists, or, for a sub-agent, if either name is inherited read-only.
Permission: Read
| Name | Type | Required | Description |
|---|---|---|---|
old | string | yes | Current entry name |
new | string | yes | Replacement entry name |
scratchpad_load_file
Read a file’s contents into a scratchpad entry without the bytes passing through the conversation.
The model never sees the payload, which is what makes this the way to stage a large log or document
for inherit_scratchpad. UTF-8 text only; a binary file is refused with its detected MIME type.
Overwrites an existing entry of the same name, and a sub-agent cannot load into a name it inherited
read-only from its parent.
Permission: Read
| Name | Type | Required | Description |
|---|---|---|---|
path | string | yes | The file path to read |
name | string | yes | Name to store the contents under |
scratchpad_save_file
Write a scratchpad entry out to a file, again without routing the bytes through the conversation. A sub-agent can save an entry it inherited, so a sub-agent’s report reaches disk without being copied through the model.
Permission: Workspace
This is the one scratchpad tool that leaves meka’s own storage, so it is the one that requires a
level that can write. It reads as the scratchpad’s write_file and is fenced identically: at
workspace the path must resolve inside a workspace root, and the refusal is the same one
write_file gives. Every other scratchpad tool stays at read because the scratchpad lives in
the store, not your tree.
| Name | Type | Required | Description |
|---|---|---|---|
name | string | yes | The scratchpad entry to read from |
path | string | yes | The file path to write to |
force | boolean | no | Proceed despite the file already existing, or existing but being unreadable (default: false) |
Handing entries to a sub-agent
agent_spawn’s inherit_scratchpad takes a list of the parent’s entry names and grants the
sub-agent read-only access to exactly those:
agent_spawn(prompt: "summarize the failures", inherit_scratchpad: ["build_log"])
The sub-agent’s scratchpad_read falls back to the parent for an inherited name, and its
scratchpad_list shows the entry with origin inherited. scratchpad_write, scratchpad_edit and
scratchpad_delete targeting one return an error, so a sub-agent cannot rewrite what it was lent.
This is how a large captured output reaches a sub-agent without being re-inlined into the prompt.
When you expect to delegate a result later, name it at the source with the scratchpad parameter
(execute_command({command: "...", scratchpad: "build_log"})) so there is a semantic name to pass
through.
Lifecycle
- Entries are scoped to the session and persist across turns.
- Entries survive session compaction (
/compact). - Entries are deleted when the session is deleted.
- Two sessions can have entries with the same name without conflict.
- Writing to an existing name overwrites it silently.