# Kanban card memory

Card memory separates a compact continuation checkpoint from retained attempts
and automatic observations. It complements the scheduler's dispatch ownership;
it does not change artifact permissions, planning gates, or review acceptance.

## Storage and durability

Each card has an optional `Memory` object, version 1, inside `board.json`:

- `Generation` identifies the active continuation history.
- `Checkpoint` contains completed work, decisions, remaining work, blocker,
  next action, and reported verification, with its author attempt and save time.
- `Attempts` retains attempt identity, agent, phase, timestamps, outcome,
  completion/error summaries, workflow/review state, handoff, artifact hashes,
  and ordered observer events.

Memory and workflow state use the same existing revision/fingerprint checked,
locked atomic board write. There is no second file that can commit independently.
An explicit checkpoint returns success only after its board revision is saved.
Automatic observations are queued from the runner and coalesced on the editor
thread, independently of the Auto Save preference. A failed scheduled memory
save stops owned work. Events still in memory at an abrupt process/power failure
may be lost; this is not synchronous disk commit for every individual tool event.

Old boards need no manual migration. Their existing bounded execution journal is
imported once when the first new attempt is claimed. Previously discarded history
cannot be reconstructed. The original short journal remains for existing
recovery classifiers, but new worker prompts use the compact memory projection.

## Worker tools

`save_kanban_checkpoint` accepts a full replacement checkpoint. Each text field
is at most 2,000 characters and `nextAction` is required. Workers are instructed
to save after meaningful milestones, before risky reloads, and before a final
handoff. Still-relevant decisions must be included in a replacement. The tool
does not complete a card or make a verification claim authoritative.

`read_kanban_memory` is scoped to the running card and active generation:

1. Omit `attemptId` to list recent attempts. Use `offset` and `limit` to paginate.
2. Supply an exact returned `attemptId` to list its events, optionally filtered
   by `query`.
3. Supply an `eventIndex` from that listing and `detailOffset` to read a longer
   event in 8,000-character pages.
4. Alternatively select `section`: `handoff`, `summary`, `error`, or `review`.
   These also use `detailOffset` paging. The default section is `events`.

`nextOffset`/`nextDetailOffset` is -1 at the end. Lists contain at most ten records;
their summaries are individually bounded. Neither tool accepts another card ID.
Both recheck the active dispatch attempt and board ownership before acting.
Planning and implementation/review workers receive the tools; normal chat does
not acquire access to a card's memory services.

The initial prompt includes the checkpoint, four recent observations, three
recent attempts, and up to six completed dependency handoffs. Older details stay
retrievable without replaying the entire ledger. Handoffs retain the original
checkpoint's author/time: a later retry cannot relabel old verification as fresh.

## Evidence and artifacts

The host captures SHA-256 fingerprints for declared produced/consumed files under
`Assets/`. A later context read identifies changed saved bytes. Captures cover
up to 64 paths, with a 16 MiB per-file and 32 MiB aggregate hashing budget. Missing,
unreadable, linked, or over-budget files are explicitly unverified. Links are not
followed. Completion captures and checkpoint captures are separate records.

A fingerprint says nothing about dirty unsaved scenes, compilation, gameplay,
or correctness. Model checkpoint text remains historical, untrusted context.
Existing authoritative capability evidence and review gates remain required.

## Reset and lifecycle

Reset advances the generation and clears the active checkpoint and short journal.
Earlier attempts remain available to a human through the export action but are
excluded from worker context and retrieval. Late callbacks from an old dispatch
cannot restore them. Recovery paths that deliberately discard a stale journal
also advance the memory generation.

The card details panel shows readable checkpoint fields and can export retained
history, including archived reset generations. Deleting a card/board deletes its
embedded history along with it; reset is not deletion.

## Bounds and tradeoffs

Automatic event messages retain up to 16,000 characters each, with explicit
truncation markers. Completion summaries retain 8,000 characters and errors
4,000. This is an execution ledger, not an unlimited conversation transcript.
Context-retrieval tool payloads are omitted from the ledger to prevent recursive
history amplification. Checkpoint changes are retained as events.

There is no automatic deletion of old attempts. Board size therefore grows with
history, and saves rewrite the board. This intentionally keeps the first version
transactionally simple; a later transactional database migration or explicit
archive policy can address large long-running boards without sacrificing history.

Checkpoint calls are encouraged, not assumed: automatic observation retention
continues even when the model forgets to save a structured checkpoint. There is
no separate model call to summarize each event or claim that a crash can always
produce a final summary.

## Verification

`KanbanCardMemoryTests` covers atomic checkpoint receipts, reload recovery,
retention beyond the prompt journal limit, actual observer wiring, pagination,
long-event retrieval, reset/stale-write isolation, board conflicts, artifact
freshness, immutable provenance, dependency scoping, capability availability,
and a deterministic worker completion saved through the Unity editor loop.
The live test uses no external model provider.
