Memory Lifecycle

Memory Lifecycle

Threadnote separates current durable knowledge from the historical handoff trail. Every memory carries a kind (durable vs handoff) and a status (active vs archived); reusing a project/topic pair gives the memory a stable file so updates replace in place instead of accreting timestamped notes.

Three states

State	Holds	Default for	Recall scope
kind: durable	Long-lived feature knowledge — design decisions, API contracts, intended behavior, gotchas	remember	Active
kind: handoff	Current work logs — repo, branch, files touched, tests, blockers, next step	handoff	Active
status: archived	Old handoffs kept for provenance, no longer current working context	archive	Out of active scope; recall --include-archived still finds them

kind: durable

The knowledge that should outlive a session and travel across agents — design decisions, API contracts, intended behavior, edge cases, why an implementation choice was made. This is the default for threadnote remember. Only durable/ memories are shareable with teammates (see Sharing Memories).

kind: handoff

The current work log your next agent recalls first: repo, branch, files touched, tests run, blockers, and next step. threadnote handoff captures git state automatically, so a bare handoff already knows the repo and branch.

status: archived

Old handoffs that helped at the time but should stop being treated as current context. archive moves them out of the active recall scope while keeping them readable for provenance. They reappear only with recall --include-archived.

Stable paths via project + topic

A project + topic pair maps to one stable lifecycle file, so later updates with the same pair replace the current version instead of creating another note.

• Tagged memories (--project + --topic) write to a stable lifecycle path and update in place.
• Untagged memories use timestamped files — a historical trail.
• Bare threadnote handoff defaults to the current repo and current git branch as its project/topic, so routine handoffs update one active branch record.
• threadnote handoff --timestamped opts into a historical note instead of updating the active branch record.

User memories live under viking://user/<you>/memories/ with lifecycle subtrees:

durable/projects/<project>/<topic>.md
handoffs/active/<project>/<topic>.md
handoffs/archived/<project>/<topic>.md

Storing

remember

Stores a durable memory by default (kind: durable, status: active). Use --kind, --project, and --topic to store lifecycle-aware current knowledge.

threadnote remember --kind durable --project my-repo --topic feature-x --text "Feature knowledge: ..."

--replace <uri> stores the updated memory and removes the superseded personal memory only after the new write succeeds. If <uri> is a shared durable/ URI, Threadnote updates that shared memory in place and pushes the shared repo — no separate share publish step.

threadnote remember --replace viking://user/example/memories/durable/projects/example/workflow.md --text "Updated durable note..."

handoff

Stores current git state plus next-step notes as a durable handoff (kind: handoff).

threadnote handoff --project my-repo --topic feature-x --task "Current status for feature X" --tests "checks run" --next-step "what to do next"

Supports --replace <uri> (same superseded-after-success semantics) and --timestamped for a historical note.

Branch feature work: two memories side by side

For a feature branch, keep a durable feature memory and an active handoff with the same project/topic. Update the durable memory when implementation knowledge changes; update the handoff when status, tests, blockers, or next steps change.

threadnote remember --kind durable --project my-repo --topic feature-x --text "Feature knowledge: ..."
threadnote handoff --project my-repo --topic feature-x --task "Current status for feature X"

Hygiene

compact

Scoped memory hygiene for active personal memories. It dry-runs by default; use --apply after reviewing the plan. Keep it scoped to one project/topic — do not run global cleanup.

threadnote compact --project my-repo --topic feature-x --dry-run
threadnote compact --project my-repo --topic feature-x --apply

Applying:

• archives stale handoffs;
• forgets only exact duplicates;
• preserves the source viking:// URIs in the kept memory;
• leaves ambiguous durable or incident memories for manual review.

archive

Copies a memory into the archived lifecycle tree, then removes the original after the archive write succeeds. Use it when an old handoff has provenance value but should no longer be current context. If OpenViking is still processing the original file, archive keeps the archived copy and tells you to retry threadnote forget <uri> later.

threadnote archive viking://user/example/memories/handoffs/active/my-repo/feature-x.md
threadnote recall --query "my-repo feature x"
threadnote recall --query "my-repo feature x" --include-archived

forget

Removes a viking:// URI. Reserve it for clearly redundant, stale memories with no unique useful detail.

threadnote forget viking://user/example/memories/handoffs/archived/my-repo/old-topic.md

Worked example

Capture an in-flight feature memory and its current handoff side by side, then update the durable memory in place as knowledge changes. Because both records share the same project/topic, each stays as one stable file — updates replace, never accrete.

# Capture an in-flight feature memory and its current handoff side by side:
threadnote remember \
  --kind durable --project web-app --topic auth-token-refresh \
  --text "Architecture: provider-only token client, JWT helpers in jwt.ts..."

threadnote handoff \
  --project web-app --topic auth-token-refresh \
  --task "Address reviewer comments on token refresh PR" \
  --tests "lint and unit suite passing" \
  --next-step "Push and request re-review"

# Later, update the durable memory in place (no timestamped duplicates):
threadnote remember \
  --kind durable --project web-app --topic auth-token-refresh \
  --replace viking://user/<you>/memories/durable/projects/web-app/auth-token-refresh.md \
  --text "..."

See also: Recall and Read, CLI Reference, Sharing Memories, Agent Instructions.