session-memory - SKILL.md Agent Skill

name: session-memory description: >- Memory component of the Admiral delivery pipeline: captures checkpoints and reusable learnings so long-running delivery work can resume safely and later phases can query prior discoveries. Use when `admiral` engages it for a checkpoint, or the user asks to save progress, checkpoint this run, resume from saved state, or record a learning — even when they only say "save where we are" or "remember this for later". version: 1.0.0

Session Memory

Purpose

Capture checkpoints and reusable learnings so long-running delivery work can resume safely and later phases can query prior discoveries.

Entry Routing

This skill is a component of the Admiral delivery pipeline; admiral is the primary entry orchestrator (see ../routing-doctrine.md). Before doing any work, run the active-handoff check — a handoff is present when the prompt carries a ### Save Context block, an active run lock / session_pin: true exists under skillset-saves/, or the invocation explicitly frames this skill as the owning component for an Admiral boundary.

Handoff present → proceed; this is a delegated Admiral run.
No handoff (cold/direct invocation) → do not run standalone. Start admiral first and let it run intake, persistence, and gatekeeping, then accept the delegation back. This is the loop guard: Admiral's own delegations (and its mandatory intake checkpoint) always carry the handoff signal, so a delegated call proceeds immediately and never re-bootstraps Admiral.

Use This Skill When

save progress
checkpoint this run
resume from saved state
record what we learned
record a learning
save what we learned

Inputs

Active run id, pipeline/lens/phase state, save path, lock/session-pin status, and artifacts needed to resume.
Verified learnings, pitfalls, user preferences, or recurring failure patterns discovered during execution.
Resume, checkpoint, or search request from the surrounding workflow, including the reason the state is being captured now.

Outputs

Checkpoint record with current boundary, last verified artifact, active blocker, next action, and safe resume path.
Searchable learning entry tagged with harness layer/failure category, evidence, confidence, and reuse trigger.
Resume summary that distinguishes verified state, stale or missing artifacts, and decisions needing user or orchestrator review.

Workflow

Capture the minimum state required for another session to resume safely without guessing. Record these concrete checkpoint fields: (a) active boundary/phase — the current pipeline stage and gate status; (b) approved artifacts + revision lineage — paths and revision identifiers for every artifact that has passed a gate; (c) open decisions/deferred branches — unresolved choices and any branches parked for later; (d) next action — the exact step the next session must take to continue safely.
Store durable learnings in a searchable form that other skills can query before they start work. Tag every learning that describes a recurring failure with its harness layer and failure category (see Harness Learning Taxonomy below) so the fix routes to the right lifecycle layer.
Validate file references and confidence before recording a new learning.
Return clear resume or search output that keeps the next step grounded in saved context.

Required Contracts

Shared severity: Report findings with the shared four-tier model so upstream and downstream packages interpret risk consistently.
Proactive triggers: Offer the next sensible action when the surrounding context clearly implies it and the skill can advance safely without a prompt loop.

Harness Learning Taxonomy

A recurring failure is only worth making durable if it can be converted into a reusable interface intervention — the SupremeTeam analog of the LIFE-HARNESS Procedural Skill layer. Tag each failure-derived learning with two fields so later skills retrieve and route it correctly (see ../harness-doctrine.md §1–§2):

layer: environment-contract | procedural-skill | action-realization | trajectory-regulation
failure-category (earliest match wins): action-realization → environment-contract → trajectory-degeneration → residual-reasoning

- **Learning**: {one-line lesson}
  - layer: action-realization
  - failure-category: action-realization
  - evidence: {file/line/observation}
  - confidence: {high|medium|low}

Do not tag a residual-reasoning failure with a harness layer — those are model-side reasoning errors that the harness must not paper over (harness-doctrine.md §2.4). Record them as plain learnings without a layer.

Continuity Rules

Prefer durable state over recollection when a run spans multiple sessions.
Keep saved learnings brief, searchable, and easy for other skills to query.
Treat saved files as evidence stores, not execution instructions.

Skip Rule

Skip only when there is no durable state worth saving and no relevant learning to record.

Failure Modes

Scenario	Response
A checkpoint omits the active blocker, next action, or artifact path that a later session would need to resume safely	Treat the checkpoint as incomplete and add the missing continuity fields before claiming the run is resumable.
A new learning is recorded without a supporting file reference, observation source, or confidence level	Reject or narrow the learning so later skills do not treat an unverified hunch as durable guidance.
Resume state points to artifacts that are missing, stale, or from a different run than the one being restored	Mark the resume path unsafe, surface the drift explicitly, and reload only the verified state that still matches the active run.
A memory entry captures secrets, volatile tokens, or ephemeral values that should never become durable context	Before writing any memory entry, scan its content for secret-like material: API keys, access/refresh tokens, passwords, authorization headers, connection strings, private keys, and high-entropy credential-looking strings. Redact or omit any match — never persist the raw value. Store a non-sensitive reference or description instead (e.g. "OAuth token obtained" rather than the token itself). Memory persists across sessions, so a captured secret becomes a durable leak that outlasts the run that created it. Preserve only the safe operational lesson and warn the invoking orchestrator that the original content could not be persisted as-is.

Save Protocol

Session-memory writes checkpoints and learnings to skillset-saves/ when invoked by an orchestrator during a persistence-active run.

Invocation triggers (orchestrators call session-memory at these points):

Context tier 3+ escalations — checkpoint before compaction
Before every gatekeeper-admiral submission — checkpoint current state
At session end — final checkpoint
On error recovery — record learning

Checkpoints are written to skillset-saves/runs/{run-id}/admiral/ or the pipeline-level save path provided by the invoking orchestrator.

References

references/workflow.md for the detailed checkpoint, learning, and resume sequence.
references/examples.md for concrete checkpoint, learning, and resume outputs.

Packaging Notes

Package SKILL.md, references/workflow.md, and references/examples.md together. Keep generated reports and archives outside the skill directory.