Memory lifecycle and storage

Active Memory covers configuration, storage and backups.

Lesson discovery and maintenance

Workers do not write lessons. After the main graph settles, the built-in postmortem runs inside the same run, using an existing node's model, provider and connections. It has four specialists:

• Graph maintenance reconciles every supplied graph lesson against its authored node instructions, output contract and procedural operation, including graph lessons qualified by a repository.
• Repository maintenance reconciles every supplied repository lesson against current authoritative files. Neither maintenance specialist receives or can modify lessons from the other scope.
• Graph discovery proposes procedural guidance for agent nodes that executed.
• Repository discovery proposes lessons about recurring work in the repository.

Each maintenance specialist keeps, adapts, retires or defers every lesson in its scope. Large manifests are processed in complete batches bounded by serialized context size; every batch requires exactly one decision per supplied ID. The host binds that ID to its frozen supplied revision and owns revision increments; agents do not manage version counters. Missing delivery evidence makes the specialists abstain. Missing or duplicate decisions fail that specialist's reconciliation instead of reporting success.

Maintenance receives the complete original authored graph and nonsecret runtime, including node instructions, contracts and runtime bindings. Large definitions remain available in complete private files rather than being replaced by truncated prefixes.

For repository-bound lessons, the host records the actual clean checkout commit, when available, in a source: evidence reference. New findings without a verified source basis remain unknown. Adaptation or retirement requires the previous source commit to be an ancestor of the current inspected commit, using local Git objects only, and the checkout must remain unchanged during review. No fetch, authority ref or additional checkout is required. Unknown legacy provenance, dirty or non-Git workspaces, filtered or submodule checkouts, missing commits and divergent or squash histories defer destructive changes; existing lessons remain readable. Such cards need trustworthy revalidation before automatic adaptation or retirement becomes possible.

Maintenance also consolidates overlapping advice within the same repository or exact graph/node/ repository-qualified scope. It keeps or adapts one canonical card and retires redundant paraphrases, while still deciding every supplied ID/revision. Distinct causes and operations remain separate.

There is no findings count quota. Discovery returns every distinct lesson that qualifies; zero new lessons is valid. A lesson needs observed non-obvious learning, a concrete recommendation and a reason to expect reuse. Task summaries, generic advice and facts obvious from nearby code do not qualify. Titles have at most 96 UTF-8 bytes; recommendations have at most 640. The store keeps evidence pointers and provenance separately from the injected card. Use stable paths and identifiers in advice. Admission detects common literal root-relative file:line pointers; semantic maintenance also checks other positional forms. Legacy cards remain readable; maintenance must adapt them to stable guidance or defer, rather than keep or merely renumber their source positions.

Discovery includes observed agent completions and tool receipts without requiring a particular graph shape, failure count, tool count or elapsed duration. Maps, nested loops, retries and partial history do not exclude locally observed evidence. Execution occurrences and attempts keep their identities visible; shared node names alone do not establish causal attribution. The specialist assesses significance, novelty, attribution and expected reuse. A quick discovery or single meaningful failure may justify a lesson; generic advice, waiting time and routine response-format corrections alone do not. Every proposal must cite an observed main-run completion or tool receipt for its actual agent node. Related reviewer evidence may support a worker lesson. Repository discoveries also need a current file citation and a matching file, folder or verified identifier association. Imported history and auxiliary agents never supply fabricated current-run evidence. Maintenance can update supplied lessons independently of discovery. Rejected discovery proposals log the failed validation stage (including card field errors) without logging the proposed lesson text. Postmortem history is read in bounded pages; its fixed transcript budget reclaims old records from the execution consuming the most space, so a verbose late reviewer cannot displace all worker evidence. Reads stop between bounded pages on cancellation. Final context trimming shrinks the largest evidence array first and retains an excerpt per execution where the byte budget allows. Truncation remains explicit.

Configuration limits

sourceNode must identify an agent binding in the authored graph. Omit it to inherit the first worker in graph order, then the first agent verifier. All four specialists inherit that node's exact model, effective harness/provider lane, effort and declared connections. They use separate sessions. Each scope's opt-out disables both its maintenance and discovery. A maintenance specialist cannot change the other scope even if its model returns a foreign ID. Only built-in global agents are accepted initially.

nodeInjectionTokens limits graph guidance per node invocation (default 16000), and hookInjectionTokens limits repository recall per native tool callback (default 8000). Each accepts 1 through 64000. These are approximate tokens: one token allows four UTF-8 bytes, including card framing. There is no model-specific tokenizer and no cumulative conversation or run budget. Complete cards that do not fit remain undelivered and eligible for a later matching injection.

budgetBytes is replaced by these two fields; remove it from saved runtime JSON when upgrading.

The postmortem's shared work deadline is timeoutMs, from 1 through 600000, defaulting to ten minutes. Evidence collection, provider startup, investigation, all maintenance batches and conflict retries share that deadline. When it expires, unfinished specialists stop; complete, host-validated specialist results may publish during bounded settlement. A maintenance specialist's decisions publish together only after all its batches finish, preserving related replacements and retirements. Explicit cancellation fences new publication and drains writes already started.

Indexing and retrieval

A run freezes an immutable, scoped snapshot. Matching uses resident inverted indexes and performs no model calls, network lookups or filesystem scans. Repository lessons can independently associate with multiple literal files, folders, identifiers or groups of keywords.

Match	Score
Exact root-relative file	1000
Containing folder	800
Exact whole identifier	700
All terms in an indexed keyword group	500

Each card gets its strongest independent match. Repeated words do not increase its score. Retrieval sorts by descending score, then lesson ID, and returns complete cards within the injection limit. Impact determines admission, so retrieval ranks by relevance alone. An ID/revision is supplied once per provider conversation. Compaction does not reset this deduplication; a new conversation can receive it again.

An identifier is a literal name such as configure_bedrock or CLAUDE_CODE_USE_BEDROCK. Matching preserves the whole name and also splits snake/camel names into topic words for keyword groups. Groups require two through four specific terms; individual broad words cannot retrieve a card. Matching is deterministic and uses exact terms in this version.

Native path fields take priority. Paths resolve against the tool's working directory and the workspace root, with component-aware folder matching. Shell arguments provide additional signals; simple cd folder && ... commands are recognized. An opaque script that never exposes its file paths can miss relevant cards. The matcher does not trace arbitrary program filesystem access.

Repository cards arrive through native harness hooks:

• Codex and Claude use PreToolUse additional context through a small native callback helper.
• Copilot uses its private RPC preToolUse callback.
• Pi uses a product-owned extension that appends cards to the tool result, including in contained mode where automatic project extensions remain disabled.

Context guides subsequent model decisions. It cannot revise a tool call already issued, so reads and searches provide the most useful early triggers. Managed policy or disabled native hooks can prevent injection. Transport failures leave the task running; missing delivery evidence makes maintenance abstain. Hook receipts record returned context, not proof that the model followed it.

Graph lessons supplement the private provider prompt after admission validation, outside authored instructions. Their scope is the authored compiled graph hash plus node ID, optionally repository. Memory injection never changes that hash, the authored graph, permissions or output contracts. Authored graph changes create a new scope; this version does not transfer guidance across graph versions.

Store consistency and run completion

The host owns the database outside the checkout and publishes all shared-store mutations. Workers receive a run-scoped retrieval capability. Reconciliation uses expected revisions, atomic transactions and deletion tombstones, so concurrent runs cannot silently overwrite a newer lesson or recreate a retired record from a stale snapshot. Newly published lessons become available to future runs.

Maintenance can replace lessons or retire obsolete ones. Previous contents are not archived, and there is no built-in undo; deletion tombstones retain IDs and revisions rather than card contents.

The main graph outcome is durably latched before postmortem. Ordinary postmortem failures appear in run logs and preserve that outcome. After a controller restart, confirmed runtime cleanup preserves the latched outcome and marks interrupted auxiliary token usage incomplete. Cancellation stops and drains the optional work; uncertain provider cleanup retains the runtime's existing failure handling. Global-agent work stays outside reducer execution history and checkpoint seeds, while its model usage contributes to run totals.

The native hook records bounded tool receipts in memory for postmortem evidence, including when a tool matches no card. Receipts contain the node, tool name, time and a few associated workspace paths; they exclude arguments and results and do not claim that a tool succeeded. The first and latest receipts survive a fixed 512-record cap. Hidden reasoning is not required or inspected.

Local and target stores do not synchronize automatically. ACP integration is outside this version. Embedders must explicitly select a host-owned memory namespace; the generic hosting configuration does not create an organization-wide store implicitly.

History initialization

--ignore-repos and --ignore-graphs accept comma-separated, space-separated or repeated values. Matching is exact and case-sensitive. Repository values match aliases reported in the inventory: checkout folder name, absolute checkout path, admitted repository name, forge owner/repo, or the opaque repo:... namespace. A short folder name excludes every matching repository. Graph values match the exact authored root name or graph hash reported in the inventory; original profile names are not retained in historical admission. There is no --cwd flag.

The first call creates a private session outside repository checkouts and inventories finished local native runs across all repositories. Each run carries its own repository namespace, aliases, workspace, graph name and hash. Checkouts are resolved from recorded workspace metadata, with current remote identity checked against admitted sources. Admissions without a remote are matched against repository IDs independently resolved from the current checkout or its registered remote; folder names and historical display aliases cannot prove identity. A historical remote, when present, still requires its exact remote-derived identity. During inventory, unavailable or changed checkouts are explicit exclusions and do not prevent other repositories from proceeding. Nothing is cloned or fetched. Current checkout probes are shared across runs.

Subsequent calls return the next work through phase and next_action. The skill classifies every candidate, fills the exported specialist response files, and calls the same command to advance. Saved ignore lists apply on resume without repeating flags; conflicting lists require a new session. Discovery findings remain staged until every supplied card has a maintenance decision. The CLI validates the same impact rules and lesson contracts as after-run postmortems; it makes no model calls and uses no provider credentials. Host subagents use the host's model connections.

The newest selected run for each repository supplies its recorded current checkout for maintenance. Graph maintenance covers each exact graph and repository scope; unqualified graph cards shared by several repositories are reconciled once. Repository cards stay within their own repository. Specialist contexts never include another repository's cards. Every selected checkout is fingerprinted, and all mutations across repositories publish in one transaction after complete maintenance coverage. Remote and runtime namespace identities are rechecked before review and publication, including changes to Git configuration that leave tracked files unchanged. If a selected checkout disappears or changes identity after staging, publication stops; restore it or start a new session with appropriate exclusions. Supplied cards are never silently dropped. Citations through symlinks require their canonical targets to be tracked or nonignored too, so the cited bytes participate in the fingerprint.

phase: complete returns the publication receipt. Retrying a completed session returns that result without repeating mutations. Session locks prevent concurrent advancement, including interrupted history export. Atomic SQLite receipts recover a process interruption between publication and its local completion checkpoint; checkpoints use durable atomic file replacement before receipts are removed. Source or lesson changes preserve staged findings for fresh maintenance work; digest-bound task responses prevent stale reuse. Deferred discoveries remain inactive. There is no findings count quota.

Each response retains the source basis exported with its task. A known revision must still match the verified checkout when importing the answer; restore it or start a new session if it changed. Answers exported without a verified basis remain unknown even if the checkout later becomes clean.

Current source includes tracked and nonignored untracked files and executable permissions. Ignored artifacts cannot be maintenance authority. Keep code stable during final review and publication; the filesystem and database cannot share a transaction. The CLI does not pull or change branches. Historical exploration receipts were not persisted, so backfill cannot reconstruct them from elapsed time. Unreadable, unfinished, opted-out and unprovable-repository runs remain explicit exclusions. Old ledgers are read-only; initialization usage belongs to the host session. Platform and Docker target history are outside this workflow.

Inventory can prove an attached run's repository from a unique eligible remote even when its recorded checkout now has detached HEAD. Publication uses that checkout's current runtime namespace, reported per run. Existing local path namespaces do not migrate automatically when a checkout later acquires an admitted remote source.

Concurrent maintenance and hosting

Worker recall remains frozen at run startup. Immediately before postmortem, the host reads current scoped lessons and supplies before/current changes separately from the original delivery manifest. Maintenance decisions target current revisions; newly received advice is not evidence of worker use. Publication checks reviewed revisions atomically. A revision conflict refreshes the context and reinvokes maintenance while retaining validated discoveries, within the original cancellation and time budget. A conflict followed by an unchanged visible lesson set stops rather than repeatedly retrying a hidden deletion tombstone. New findings deferred by maintenance remain unpublished. Ordinary transport failures are not revision conflicts.

Storage reads and queued writes stop on cancellation. Backends check the original hard-stop signal and absolute publication deadline immediately before dispatch. MemoryPublicationControl carries both without a forwarded signal. Started writes drain within a bounded storage timeout before cleanup completes.

Embedding hosts may install an authenticated ActiveMemoryBackend through ProductionHostingConfig. Its snapshot and publication operations carry run identity; the backend must derive and enforce the accepted run's tenant, repository and graph scope independently of request fields. SQLite implements the same interface for local and direct-target runs. Hosts must return complete bounded snapshots; failed or partial reads must never masquerade as an empty lesson set.