Active Memory¶
Active Memory carries useful lessons from one run to the next. It saves guidance about costly mistakes and recurring work, then supplies relevant lessons when an agent encounters related code or runs the same graph again. It is enabled by default.
After the main graph finishes, a postmortem reviews the evidence, updates existing lessons and proposes new ones. Workers do not write directly to memory. Routine summaries and generic advice do not qualify as lessons.
Configuration¶
Add these optional fields to your runtime JSON alongside harness, provider, size and nodes:
{
"activeMemory": {
"repository": true,
"graph": true,
"nodeInjectionTokens": 16000,
"hookInjectionTokens": 8000
},
"globalAgents": {
"postmortem": {
"enabled": true,
"sourceNode": "worker",
"timeoutMs": 600000
}
}
}
- Set
repositoryorgraphtofalseto stop reading and collecting lessons for that scope. Set both tofalseto disable Active Memory. - Set
postmortem.enabledtofalseto keep reading saved lessons without updating them. nodeInjectionTokenslimits graph guidance per node invocation;hookInjectionTokenslimits repository recall per tool callback. They default to 16000 and 8000 approximate tokens and each accepts 1–64000. One approximate token permits four UTF-8 bytes, including formatting. There is no cumulative conversation or run budget.sourceNodeselects the agent whose model, provider and connections the postmortem uses. Omit it to use the first worker, or the first agent verifier if there is no worker.timeoutMsdefaults to ten minutes and accepts 1–600000 milliseconds. Startup, investigation and all batches and retries share that deadline. Completed specialist work can publish after another specialist times out; an incomplete maintenance specialist publishes none of its decisions.
budgetBytes is replaced by the two injection limits; remove it from saved runtime JSON when upgrading.
These settings apply per run, so saved profiles can use different policies. Postmortem model usage counts toward the run total. An ordinary postmortem failure appears in the logs and does not change the main graph's result.
Initialization failures name the lessons file when applicable and retain the safe underlying
cause in error logs, including when postmortem is disabled but recall is enabled. Failed
specialists log their role and cause, followed by one error summary. Confirmed hook configuration
or carrier failures are reported once per execution; a conversation without tool callbacks is
not treated as a failure. These auxiliary errors do not become primary graph failure evidence.
Foreground run and watch print the latest five memory error records on stderr when observation
ends. resume also checks that stream after its receipt, within the existing five-second log-read
deadline; longer-running successors can be followed with watch. Complete diagnostics remain in
zeroshot logs RUN_ID. Disabling both memory scopes skips store initialization without a warning.
While the postmortem runs, the run stays running. status and list carry the recorded graph
outcome in status.graphResult; watch and foreground run print it immediately. A log line
records that outcome and says the postmortem is running. The run finishes after postmortem,
usage accounting and cleanup, and then only terminalResult remains. The foreground command
waits until then and exits according to that final result.
A force stop during the postmortem cancels and drains it while preserving the recorded graph
result. Ordinary postmortem errors and controller restart after confirmed cleanup also preserve
that result. A runtime or cleanup failure during finalization can prevent completion or produce
a final runtime_failed or runtime_lost result, so graphResult is not a guarantee of the final
run outcome. See observing run results.
Indexing and retrieval¶
Repository lessons match file paths, folders, identifiers and keyword groups. Graph lessons belong to a particular compiled graph and node; changing the graph creates a new scope. Lessons do not transfer automatically across graph versions.
Each run reads a snapshot of memory. New lessons become available to future runs. Matching makes no model calls. An ID/revision is supplied once per provider conversation; compaction does not reset this deduplication. Copilot does not keep tool-call context in its session, so there a repository lesson is supplied once per execution. Each matching injection gets its own context limit.
Repository lessons arrive at matching tool calls through harness hooks, never inside a tool result. Disabled hooks can prevent delivery; scripts that hide their file paths can miss matches. Advice cannot change a tool call already issued, and receipt of a lesson does not prove the model followed it. See the matching and delivery rules for details.
Storage and backups¶
Local runs share a database outside your checkouts, with separate repository scopes:
| Platform | Default database |
|---|---|
| Linux / macOS | ~/.local/state/zeroshot/active-memory/lessons.sqlite3 |
| Windows | %LOCALAPPDATA%\zeroshot\state\active-memory\lessons.sqlite3 |
On Unix, XDG_STATE_HOME changes the base directory. ZEROSHOT_STATE_DIR takes precedence on all
platforms and selects STATE_DIR/active-memory/lessons.sqlite3. Changing either variable selects a
store; it does not move existing lessons.
A direct Docker target uses <target-storage>/active-memory/lessons.sqlite3, shared by its
submitters with repository scopes. Preserve its storage volume when recreating the container.
Local and target stores do not synchronize automatically. ACP integration is not supported.
Executable updates and normal run cleanup preserve memory. There are no automatic backups or
built-in undo for changed or retired lessons. To back up or move it, stop all zeroshot processes
using the store and copy the whole active-memory/ directory, including SQLite journal files.
Restore it while those processes are stopped.
Initialize from local history¶
Ask your agent to use the zeroshot-memory-init skill to learn from completed local runs.
zeroshot update installs the skill; if it is missing after upgrading through an older updater,
run the update again.
The skill inventories local history across repositories, discovers lessons, checks them against current source and publishes them together. Keep the selected checkouts stable during its final review and publication. It does not clone repositories, pull changes or change branches. Docker and Platform history are outside this workflow.
The skill uses this resumable command:
zeroshot memory init --directory /path/to/session
zeroshot memory init --directory /path/to/session --ignore-repos owner/repo,other-repo --ignore-graphs autoresearch,GRAPH_HASH
Choose a session directory outside checkouts. Ignore values must match inventory aliases exactly;
saved exclusions apply when resuming. Unavailable checkouts and unusable runs are reported as
exclusions. phase: complete returns the publication receipt; repeating a completed session does
not publish twice.
See history initialization for alias matching, repository identity checks and interruption recovery.
Concurrent maintenance and hosting¶
Concurrent runs check lesson revisions before publishing, so stale updates cannot overwrite newer advice. Hosting integrations must explicitly provide a memory namespace and enforce its access. See memory lifecycle and storage for maintenance, evidence and host contracts.
The native tool-call carrier is installed for every agent conversation, including when Active
Memory is off, so it can deliver standing steers.
Memory off still leaves its database unopened. Steers come from the run vector record. At a tool
call they travel as a user message where the harness has a channel for one, and ahead of the
memory cards in hook context on Codex. They are delivered whole and do not count against
nodeInjectionTokens or hookInjectionTokens; memory card selection keeps its own limits.