/session-memory

name: session-memory
description: "Persist and recall findings across skill runs within and between sessions, building a cumulative knowledge base of what has been discovered about a design system. This is the cross-skill memory layer — it saves what was found, when, and by which skill, so future runs can compare, correlate, and avoid repeating work. Trigger when someone says: save these findings, remember this for later, compare with last run, what did we find before, load previous findings, recall the last audit, session history, show me what changed, cross-reference with previous runs, or anything about persisting, recalling, or comparing findings over time. Do NOT trigger for generating a single standalone report — use the specific skill for that. Do NOT trigger for running a full diagnostic — use full-system-diagnostic for that."
references:
  - ../../knowledge-notes/agent-orchestration-guide.md
  - ../../knowledge-notes/human-oversight-framework.md

Session Memory

A skill for persisting findings across skill runs so that future skills can compare, correlate, and build on what was previously discovered.

**Output type:** Memory file creation and recall. This skill writes structured session files and retrieves previous session data. It does not produce analysis — it provides the memory layer that other skills draw from.

---

Why this exists

Every skill in Design System Ops produces findings. But those findings are ephemeral — they exist in the conversation, get summarised, and then vanish. The next time someone runs token-audit, it starts from zero. It cannot tell you whether things got better or worse since last quarter. It cannot cross-reference what drift-detection found last month with what component-audit finds today.

Session Memory fixes this. It creates a structured memory layer that:

1. **Saves findings** from any skill run with timestamps, severity, and skill provenance 2. **Recalls findings** when a skill asks "what did we find before?" 3. **Compares findings** between runs to surface trends (improving, stable, worsening) 4. **Correlates findings** across skills to surface patterns that persist over time

This is not a database. It is a structured markdown file per session that accumulates over time. Simple, portable, and readable by both humans and AI.

Boundaries

This skill is a persistence layer — it saves, recalls, compares, and correlates findings. It does not run audits, produce reports, or generate recommendations on its own. If no previous session files exist and the mode is Recall, Compare, or Correlate, inform the user that there is no history to work with and suggest running an audit first. If the session memory directory does not exist, create it on Save. Do not correlate across skills unless at least two different skill sessions exist — a single-skill history is a Compare, not a Correlate.

---

Configuration

Check for `.ds-ops-config.yml` in the project root:

memory:
  directory: ".ds-ops/sessions"     # Where session files are stored
  retain_count: 12                   # How many session files to keep
  auto_save: true                    # Automatically save after every skill run
  comparison_window: 3               # How many previous sessions to compare against

If no configuration exists, use these defaults:

• Directory: `.ds-ops/sessions/`
• Retain count: 12
• Auto-save: true
• Comparison window: 3

---

Session file format

Each session file is a structured markdown document saved to the memory directory. One file per skill run.

Filename convention

`[YYYY-MM-DD]-[skill-name]-[short-hash].md`

Example: `2026-03-09-token-audit-a7f3.md`

The short hash is the first 4 characters of a hash of the input parameters, ensuring uniqueness when the same skill is run twice on the same day with different inputs.

File structure

---
skill: token-audit
date: 2026-03-09
scope: "AGDS token architecture"
system: "Australian Government Design System"
component_count: 42
---

# Session: token-audit — 2026-03-09

## Summary
[2–3 sentence summary of what was found]

## Key metrics
| Metric | Value |
|---|---|
| Total tokens | 140 |
| Violations | 12 |
| Critical | 2 |
| High | 4 |
| Orphaned tokens | 45 (32%) |

## Findings
### TA-01 [Critical] — Missing semantic tier for feedback tokens
[One paragraph description]

### TA-02 [High] — Orphaned primitive tokens in legacy palette
[One paragraph description]

[... all findings ...]

## Recommendations
1. [First recommendation]
2. [Second recommendation]

## Cross-references
- Correlates with: [any related findings from prior sessions, or "None — first run"]
- Trend: [Improving / Stable / Worsening / New baseline]

---

Step 0: Determine the operation

Session Memory has four modes. Determine which one based on the request:

Mode A — Save

Someone ran a skill and wants the findings persisted.

Mode B — Recall

Someone wants to see what was found in previous runs before running a new skill.

Mode C — Compare

Someone wants to compare current findings against previous runs to see trends.

Mode D — Correlate

Someone wants to cross-reference findings across different skills to surface persistent patterns.

---

Step 1: Save (Mode A)

Input

Accept findings from any skill output: copy-pasted report, file reference, or inline conversation output.

Process

1. **Parse the skill output** and extract:

• Skill name (from the output header or context)
• Date (today)
• Scope (what was assessed)
• System name (from config or context)
• Component count (if available)
• Key metrics (counts, scores, percentages)
• Individual findings with IDs, severities, and descriptions
• Recommendations

2. **Check for prior sessions** from the same skill:

• If prior sessions exist, add a `## Trend` section comparing key metrics
• Calculate deltas: "Violations: 12 → 8 (↓ 33%)"
• Note new findings not present in the previous run

-