Navigation: Chat & Agents → Agent Memory
For notes an agent saves across conversations, see Memory. This page covers only the per-run store.
context.memory is a key-value store on every ProcessingContext. Executors write step and task results into it, and agents read it through three tools. This is what list_shared returns mid-run:
{
"total": 2, "returned": 2, "truncated": false,
"entries": [
{ "key": "task:research", "kind": "task_result", "title": "Research findings",
"source": "research", "valueBytes": 142, "createdAt": "2026-05-07T14:00:01.234Z" },
{ "key": "shared:top_source", "kind": "shared", "title": "Top source URL",
"source": "share_result", "valueBytes": 19, "createdAt": "2026-05-07T14:00:03.020Z" }
]
}
The store lives for one run. It is cleared when the run ends and is not shown on the Memory page.
Architecture
┌──────────────────────────────────┐
│ ProcessingContext.memory │
│ │
│ Map<string, MemoryEntry> │
│ │
│ step:<id> step_result │
│ task:<id> task_result │
│ input:<key> input │
│ shared:<k> shared │
└────────────┬─────────────────────┘
│
┌─────────────────────────┴─────────────────────────┐
│ │
▼ ▼
CodeActExecutor ParallelTaskExecutor
(writes step:, task: on finish-task (passes task.dependsOn IDs as
steps; auto-attaches list_shared / upstream key hints to
read_shared / share_result tools) TaskExecutor)
Every step has list_shared, read_shared, and share_result attached automatically. The step prompt does not include memory contents. The agent lists metadata, then reads only the keys it needs. The step’s user message names the keys the planner declared through task.dependsOn or step.dependsOn, without their values.
Key Namespaces
| Namespace | Helper | Written By | Used For |
|---|---|---|---|
step:<id> |
memoryKeys.step(id) |
CodeActExecutor, TaskExecutor (terminal step failure) |
Per-step results |
task:<id> |
memoryKeys.task(id) |
CodeActExecutor (finish-task steps), ParallelTaskExecutor |
Per-task results |
input:<key> |
memoryKeys.input(key) |
TaskExecutor, ParallelTaskExecutor |
Caller-supplied inputs |
shared:<key> |
memoryKeys.shared(key) |
share_result tool |
Cross-agent communication, scratch space |
Build keys with the memoryKeys helpers.
import { memoryKeys } from "@nodetool-ai/runtime";
context.memory.has(memoryKeys.task("research_phase"));
context.memory.getValue(memoryKeys.step("step_1"));
Memory Entry Shape
export interface MemoryEntry {
/** Globally unique key (use memoryKeys.*). */
key: string;
/** Categorization for filtering and rendering. */
kind: "task_result" | "step_result" | "input" | "shared";
/** Stored value (any JSON-serializable structure). */
value: unknown;
/** Optional ID of the producer (task / step / agent / tool). */
source?: string;
/** Optional human-readable title shown in `list_shared`. */
title?: string;
/** Optional brief description. */
description?: string;
/** Wall-clock ms when the entry was first written. */
createdAt: number;
}
title and description appear in list_shared output.
Memory Tools (the LLM-facing API)
Inside a CodeAct step the model calls nodetool.shared.list(opts), nodetool.shared.read(keys), and nodetool.shared.publish(key, value, opts) (opts carries title and description). The wire names below are what tool calls and the supervisor’s StepExecutor use.
list_shared
Returns metadata only.
// args
{
"kind": ["task_result", "shared"], // optional filter
"key_prefix": "task:", // optional filter
"sources": ["research", "summary"] // optional filter
}
// result
{
"total": 4,
"returned": 4,
"truncated": false,
"entries": [
{
"key": "task:research",
"kind": "task_result",
"title": "Research findings",
"description": "Top three sources from the web search step.",
"source": "research",
"valueBytes": 142,
"createdAt": "2026-05-07T14:00:01.234Z"
}
// ...
]
}
valueBytes is the character length of the value (the string itself, or its JSON serialization). The model can use it to budget reads. Each description is cut at 240 characters with a trailing …. The result is capped at 200 entries, the first 200 in insertion order, and truncated: true reports that more exist. createdAt is an ISO timestamp here.
read_shared
Returns full values for the keys given.
// args
{ "keys": ["task:research", "step:summary"] }
// result
{
"entries": {
"task:research": {
"key": "task:research",
"kind": "task_result",
"value": { "findings": ["alpha", "beta"] },
"source": "research",
"title": "Research findings",
"createdAt": 1700000000000
}
},
"missing": ["step:summary"]
}
Missing keys come back in missing. A key with no : is retried under shared:, so the suffix given to share_result reads back as written. Each entry is the full MemoryEntry, so createdAt is a millisecond number here.
share_result
Publishes a value under shared:.
// args
{
"key": "top_source", // suffix; stored as "shared:top_source"
"value": "https://example.com",
"title": "Top source URL",
"description": "Picked by the researcher agent."
}
// result
{ "ok": true, "key": "shared:top_source", "kind": "shared", "createdAt": "..." }
A key that already starts with shared: has the prefix stripped, so writing back a key from list_shared does not produce shared:shared:<key>. title defaults to the key suffix, and source is always share_result. Writes are limited to shared:, so an agent cannot overwrite step, task, or input results.
Direct API Reference
AgentMemory lives in packages/runtime/src/agent-memory.ts and is exported from @nodetool-ai/runtime. Executors use it directly. Agents reach it through the three tools.
Other methods: delete(key) returns whether the key existed, size() returns the entry count, and formatForPrompt(filter?) renders matching entries as a Markdown block ordered by createdAt (empty string when none match).
Writing
context.memory.set({
key: memoryKeys.task("research"),
kind: "task_result",
value: { findings: ["alpha", "beta"] },
source: "research",
title: "Research findings",
description: "Top three sources from the web search step."
});
set returns the persisted MemoryEntry. Repeated writes for the same key overwrite the value but preserve the original createdAt.
Reading
context.memory.get(memoryKeys.task("research")); // MemoryEntry | undefined
context.memory.getValue<T>(memoryKeys.task("research")); // T | undefined
context.memory.has(memoryKeys.task("research")); // boolean
context.memory.snapshot(); // MemoryEntry[]
Listing & Filtering
context.memory.list(); // all
context.memory.list({ kind: "task_result" });
context.memory.list({ kind: ["task_result", "input"] });
context.memory.list({ keys: ["task:research", "task:report"] });
context.memory.list({ keyPrefix: "step:" });
context.memory.list({ sources: ["research"] });
Subscriptions
const unsubscribe = context.memory.subscribe((entry) => {
console.log(`memory write: ${entry.key} (${entry.kind})`);
});
// later...
unsubscribe();
Snapshot and restore
const saved = context.memory.snapshot(); // MemoryEntry[] in insertion order
context.memory.restore(saved); // rewrites each entry, keeps createdAt, notifies subscribers
restore on a fresh AgentMemory rebuilds it. Existing keys are overwritten.
Clearing
context.memory.clear(); // wipe everything
context.memory.clear({ kind: "step_result" }); // selective
context.memory.clear({ keyPrefix: "input:" }); // by prefix
How Each Agent Type Uses Memory
CodeActExecutor (packages/agents/src/codeact/codeact-executor.ts)
The execution engine for a single step.
Writes:
| Trigger | Key | Kind |
|---|---|---|
| Always | step:<step.id> |
step_result |
| Last step of a task (finish-task) | task:<task.id> |
task_result |
Step failed (error, budget stop, iterations exhausted, or no finish()) |
step:<step.id> (with { error }, title Failed: <instructions>) |
step_result |
LLM access:
- The memory tools ride in the toolbelt like any other, but the object model is their one documented form: the prompt teaches
nodetool.shared.list()/nodetool.shared.read(keys)/nodetool.shared.publish(key, value), and the three wire names drop out of the raw tool catalog like every other wrapped tool. - The user message includes only specific declared upstream keys as a hint, under the heading “Required upstream context — read these before acting (via
await nodetool.shared.read([...]))”:step:<id>for every entry of the step’sdependsOn(intra-task deps).- any key supplied via
CodeActExecutorOptions.upstreamMemoryKeys(typicallytask:<id>from the parent task’sdependsOn).
- Values are not included, and the keys are listed whether or not they exist yet. The agent calls
nodetool.shared.readto fetch them.
Tool attachment: getSharedTools() (packages/agents/src/tools/shared-tools.ts) — a belt built from the shared capability module’s specs — is auto-pushed into the step’s tool list at construction time, alongside any caller-supplied tools. Mount policy stays with the executor: the host never mounts these. Completion is finish(result) in the sandbox, validated host-side against the step’s schema.
Custom prompts are preambles, not replacements: A caller-supplied systemPrompt is layered before the default execution prompt, so the contract — including the tool catalog and the finish() discipline — is non-bypassable.
TaskExecutor (packages/agents/src/task-executor.ts)
Walks the step DAG of a single task. On startup it seeds caller inputs:
for (const [key, value] of Object.entries(this.inputs)) {
this.context.memory.set({
key: memoryKeys.input(key),
kind: "input",
value,
title: key
});
}
Keys already seeded by ParallelTaskExecutor are skipped. Each step runs on a copy of the context that shares the task’s memory (context.copy({ shareMemory: true })). The only step: key it writes itself is a terminal failure: failStepEvents records { error } under memoryKeys.step(step.id) so the parent can read the reason. Every successful step result is written by the CodeActExecutor running it.
TaskExecutor accepts an optional upstreamMemoryKeys array (e.g. task:<id> keys from the parent plan). It forwards this verbatim to every step executor it creates.
ParallelTaskExecutor (packages/agents/src/parallel-task-executor.ts)
Runs a TaskPlan of multiple tasks as a DAG. It owns no private result map — everything lives in context.memory.
| Operation | Memory Action |
|---|---|
| Startup: seed inputs | set each as input:<key> |
| For each task: derive upstream keys | task.dependsOn.map(memoryKeys.task) → forwarded as upstreamMemoryKeys to TaskExecutor |
| After task executor completes | If no is_task_result was emitted, fall back to step:<lastStepId> |
| Idempotent task write | set task:<task.id> only if not already present |
| Read final result | getFinalResult() returns getValue(task:<lastTaskId>) |
| Read all results | getAllResults() lists all task_result entries |
| Read specific task | getTaskResult(id) |
Downstream tasks see their declared upstream task keys as hints in the step user message and pull values via read_shared when needed.
StepExecutor (packages/agents/src/step-executor.ts)
The step executor of the supervisor agent and the app-build harness, not of execute_plan. It attaches the same three tools. Its system prompt has a “Memory Tools (progressive disclosure)” section that names list_shared, read_shared, and share_result directly. Its user message lists declared upstream keys that exist in memory, with titles:
# Required upstream memory (call `read_shared` with these keys):
- task:research_phase — Research findings
Steps finish through finish_step.
The calling loop (execute_plan’s caller)
There is no synthesis stage that reads memory on the run’s behalf. When
execute_plan returns, each task’s value is in context.memory under
task:<id> and in the call’s own results object; the CodeAct session that
made the call writes the answer on its next turn, calling read_shared for
anything the return did not carry. That is what execute_plan’s description
tells the model to do, and it is why the planner is told not to plan an
assembly task.
Propagation Flow
This is the canonical end-to-end flow for a multi-task plan:
1. Caller: execute_plan(plan)
2. ParallelTaskExecutor.execute()
├─ Seed inputs: context.memory.set({ kind: "input", ... })
└─ For each executable task:
└─ TaskExecutor.executeTasks()
└─ For each step:
└─ CodeActExecutor.execute()
├─ system prompt teaches nodetool.shared.*
├─ buildUserMessage() → instructions
│ + "Required upstream context" hint listing
│ declared dependency keys (no values)
├─ model writes actions that may call:
│ - nodetool.shared.list → returns metadata
│ - nodetool.shared.read → returns values for chosen keys
│ - nodetool.shared.publish → publishes shared facts
├─ finish(result) accepted → storeCompletionResult()
│ ├─ context.memory.set({ key: "step:<id>", ... })
│ └─ if useFinishTask:
│ context.memory.set({ key: "task:<id>", ... })
└─ yield step_result
3. ParallelTaskExecutor: ensure task: entry exists (idempotent)
4. Mark task.completed = true → unblocks downstream tasks
5. Next iteration: downstream tasks now executable. Their step user
messages name the upstream task keys; agents call nodetool.shared.read when
they actually need the values.
6. execute_plan returns the task results; the calling session's next turn
reads task:<id> via read_shared for anything it still needs and writes
the answer.
Examples
What the LLM sees (StepExecutor system prompt extract)
The StepExecutor default execution system prompt includes the block below. A CodeAct step is taught the same three operations as nodetool.shared.list, read, and publish.
## Memory Tools (progressive disclosure)
- Shared agent memory holds results from prior steps and tasks, original
inputs, and facts published by other agents.
- Memory contents are NOT auto-included in your prompt. If you need upstream
context, discover it on demand:
1. Call `list_shared` to see what's available (returns metadata only —
keys, titles, kinds, byte sizes).
2. Call `read_shared` with the specific keys you actually need; it returns
full values.
3. Call `share_result` to publish a value under `shared:<key>` so other
agents can find it via `list_shared`.
- Pull only what you need — don't fetch every entry by reflex.
And the StepExecutor user message for a step that depends on task:research_phase looks like:
Write a report from the upstream findings.
# Required upstream memory (call `read_shared` with these keys):
- task:research_phase — Research findings
The model then chooses whether to read the key or proceed.
Pre-populate memory before running
Useful in tests, and for handing a run what an earlier one already found:
context.memory.set({
key: memoryKeys.task("prior_research"),
kind: "task_result",
value: cachedFindings,
source: "prior_research",
title: "Cached prior research",
description: "Findings from a previous run; reuse instead of re-researching."
});
The first list_shared call in any step under this context surfaces the entry,
and read_shared fetches it.
Tool that publishes to shared memory directly (without an LLM round-trip)
For deterministic publish-from-code use cases, write to the API directly:
context.memory.set({
key: memoryKeys.shared("top_source"),
kind: "shared",
value: "https://example.com/article",
source: "data_pipeline",
title: "Top source URL"
});
Subsequent agents will see this via list_shared and can fetch it via read_shared.
Design notes
- Progressive disclosure: a step needs one or two upstream values, so listing metadata first keeps prompts small.
- Declared dependencies are named in the step’s user message, so the agent can go straight to
read_shared. share_resultwrites onlyshared:so step, task, and input results stay executor-owned.context.copy()does not share memory unless called withshareMemory: true, asTaskExecutordoes. A sub-run that should inherit memory gets entriessetfrom the parent first.- A caller-supplied
systemPromptis layered before the default execution prompt, so the memory tools and completion protocol stay in force.
Troubleshooting
Symptom: A downstream task’s prompt shows the upstream key hint but the agent never reads it.
- The model may have decided it doesn’t need the value. If you know it should, make the user instructions more explicit (“read the upstream findings via read_shared before writing”).
Symptom: Task result key is missing after the step yielded step_result with is_task_result: true.
- A step executor only writes
task:<id>for steps whereuseFinishTask === true. That flag is set byTaskExecutor.isFinishStep()for the last step in the task. Steps in the middle of a task only writestep:<id>. - For belt-and-suspenders,
ParallelTaskExecutorperforms an idempotent task-result write after each task, falling back to the last step’s value.
Symptom: Tests pass but memory entries seem stale across test runs.
- A new
AgentMemoryinstance is constructed for everyProcessingContext. If you reuse a context across tests, callcontext.memory.clear()between them.
Symptom: Agent calls list_shared and gets truncated: true.
- The list response is capped at the first 200 entries in insertion order. Narrow the filter (
kind,key_prefix, orsources) to reach later ones.
Related
- Memory: durable notes across conversations
- Chat & Agents
packages/runtime/src/agent-memory.ts—AgentMemoryimplementationpackages/agents/src/capabilities/shared.ts—list_shared/read_shared/share_result(thesharedcapability module;packages/agents/src/tools/memory-tools.tsis the belt executors mount them from)packages/agents/tests/memory-propagation.test.ts— end-to-end propagation tests including the tool round-trippackages/agents/tests/memory-tools.test.ts— unit tests for the memory toolspackages/runtime/tests/agent-memory.test.ts—AgentMemoryunit tests