Session Recap & Memory Extraction

Overview

At session end, generate a recap that documents what changed, what you learned, and what should be remembered. Then extract 2-3 high-confidence memory items for approval.

This captures knowledge that would otherwise be lost, and surfaces patterns you might not explicitly notice.

Trigger

# Manual (end of session)
.agents/skills/session-recap

# Automatic (via hook, after session completes)
# Defined in ~/.claude/settings.json onSessionEnd hook

Step 1: Collect Session Data

# What changed in code
git diff HEAD~N...HEAD --stat
git log --oneline HEAD~N...HEAD
git diff HEAD~N...HEAD -- apps/docs/ .agents/

# What was modified
git status --porcelain

# Session context (if available)
# - User requests from conversation
# - Decisions made
# - Bugs encountered and fixed
# - Patterns discovered

Step 2: Generate Recap Markdown

Create .recap-{timestamp}.md:

# Session Recap — YYYY-MM-DD HH:MM

## Session Goal
[What the user asked you to do]

## What Changed

### Code Changes
- **docs**: Fixed X broken links in whats-new.md (Starlight absolute path issue)
- **ci**: Updated Node.js from v20 to v22 in Deploy Docs workflow
- **chore**: Removed pending 0.9.1 changesets (not releasing yet)

### Files Modified
- .agents/skills/update-docs/SKILL.md (+28 lines)
- apps/docs/src/content/docs/guides/whats-new.md (9 link fixes)
- .github/workflows/docs.yml (added Node.js setup)
- .agents/MEMORY.md (+1 entry)

### Tests/Verification
- Docs build: ✓ 66 pages, no build errors
- Link validation: local build passes
- CI status: awaiting latest run completion

## Patterns Discovered

### 1. Starlight/Astro Link Conversion Issue
**What**: Relative paths in markdown get converted to file-system paths that break the lychee link checker.
- `](./tools)` → rendered as `/guides/whats-new/tools/` ❌
- `](../features/observability)` → rendered as `/guides/features/observability/` ❌
- `](/guides/tools)` → rendered as `/guides/tools/` ✓

**Why it matters**: CI link checks fail silently without clear error messages. Took 3 iterations to find root cause.

**Solution**: Use absolute paths for all internal doc links. Update update-docs skill.

### 2. CI/Astro Node.js Version Pinning
**What**: Deploy Docs workflow was using Node.js v20, but Astro requires v22.12.0+.
**Why it matters**: CI environment differs from local dev (which had v22).
**Solution**: Pin all workflows to Node.js v22 in setup-node actions.

### 3. Changesets Auto-PR Behavior
**What**: Pending changeset files trigger automatic "Version Packages" PR creation on every push.
**Why it matters**: Noisy CI, misleading impression that release is pending.
**Solution**: Delete changeset files when not actively preparing a release.

## Memory Candidates

### HIGH CONFIDENCE → Create

**Type: feedback**
- **Name**: Starlight link patterns
- **Description**: Use absolute paths for internal doc links; relative paths cause CI link-checker failures
- **Action**: Create `.agents/MEMORY.md` entry + update update-docs skill Step 9
- **Confidence**: 🟢 HIGH (just fixed this, clear pattern)

### MEDIUM CONFIDENCE → Review

**Type: project**
- **Name**: Node.js version pinning for Astro
- **Description**: All CI workflows must use Node.js v22.12.0+ (Astro requirement)
- **Action**: Add to AGENTS.md CI section
- **Confidence**: 🟡 MEDIUM (specific to current Astro version, might change)

**Type: feedback**
- **Name**: Changeset management
- **Description**: Delete pending changeset files from `.changeset/` when not preparing a release; they trigger auto-PR creation
- **Action**: Add note to prepare-release skill
- **Confidence**: 🟡 MEDIUM (workflow-specific, not code pattern)

### LOW CONFIDENCE → Skip

- Per-session insights that are self-contained (don't apply elsewhere)
- Workarounds that should be fixed in code, not remembered
- One-off debugging that won't recur

## Step 3: Extract Memory Candidates

For each candidate, evaluate:

| Criterion | Question | Examples |
|-----------|----------|----------|
| **Reusable** | Will future sessions need this? | ✓ Link patterns ✓ Version requirements ✗ "Fixed typo in line 42" |
| **Non-obvious** | Would someone rediscover this easily? | ✓ Astro conversion behavior ✓ CI workflow drift ✗ "Use git status to see changes" |
| **Actionable** | Can the rule be applied mechanically? | ✓ "Use absolute paths" ✓ "Pin to v22" ✗ "Be careful with links" |
| **Durable** | Will this still matter in 6 months? | ✓ Link patterns ✓ Type requirements ✗ "Changesets bugged in Apr" |

Score 3+/4: **HIGH confidence** → auto-create memory file
Score 2/4: **MEDIUM confidence** → present for approval
Score <2/4: **LOW confidence** → skip

## Step 4: Memory File Creation

For each HIGH-confidence candidate, create file at:

~/.claude/projects/-home-tylerbuell-Documents-AIProjects-reactive-agents-ts/memory/ feedback_.md project_.md reference_.md

**Format for feedback**:
```markdown
---
name: [topic]
description: [one-line, use for future relevance filtering]
type: feedback
---

[Rule statement]

**Why:** [Reason + past incident/discovered issue]

**How to apply:** [When/where this kicks in]

Step 5: Update .agents/MEMORY.md Index

Add one-line pointer in appropriate section:

## Feedback
- [Starlight link patterns](feedback_starlight_link_patterns.md) — use absolute paths for internal doc links; relative paths cause CI link-checker failures

Keep under 150 characters so index stays readable (max ~200 lines total).

Step 6: Approval & Commit

Present candidates for review:

3 Memory Candidates Extracted

[HIGH] ✅ feedback_starlight_link_patterns.md
  Use absolute paths for internal doc links; relative paths cause CI link-checker failures
  [Create] [Skip]

[MEDIUM] 🟡 project_astro_node_version.md
  All CI workflows must use Node.js v22.12.0+ (Astro requirement)
  [Create] [Review first] [Skip]

[MEDIUM] 🟡 feedback_changeset_workflow.md
  Delete pending changeset files when not preparing a release
  [Create] [Review first] [Skip]

User decides:

• [Create]: Auto-commit memory files and update index
• [Review first]: Show full markdown, let user edit before committing
• [Skip]: Don't create (but show in git diff for manual review later)

Step 7: Commit with Recap

git add .agents/MEMORY.md feedback_*.md project_*.md .recap-*.md
git commit -m "chore: session recap + extracted learnings [auto-memory]"

Include recap in commit (or as GitHub Actions annotation) for future reference.

Quick Reference: Memory Types

Type	Purpose	Examples
feedback	How to approach work (what to do/avoid)	"Use absolute paths", "Never skip hooks", "Commit before branching"
project	Current state, milestones, constraints	"v0.9.0 shipped Apr 3", "Node.js v22 required", "180 tests across 42 files"
reference	Where to find info in external systems	"Bugs tracked in Linear project INGEST", "Grafana board is grafana.internal/d/api-latency"
user	About the user's role/preferences	"User is data scientist", "Prefers terse responses", "10 years Go experience"

Implementation: Hook Integration

In .claude/settings.json:

{
  "hooks": {
    "onSessionEnd": {
      "name": "auto-recap",
      "command": ".agents/skills/session-recap/generate.sh",
      "env": {
        "PROJECT_ROOT": "${PROJECT_PATH}",
        "SESSION_START": "${SESSION_START_TIME}"
      }
    }
  }
}

Script (generate.sh) would:

1. Collect git changes since session start
2. Parse conversation context
3. Generate recap markdown
4. Extract candidates
5. Present for approval (interactive prompt or GitHub annotation)
6. Commit approved items

Notes

• Recap is not a commit message — it's documentation for future reference
• Memory extraction is opt-in — user always decides what gets remembered
• Recap files stay in git history for audit trail
• If extraction takes >30s, skip approval step and commit all HIGH-confidence items only