save-session

One fast, non-blocking turn. The user usually continues within minutes of asking, so this skill extracts, dedupes, routes, writes and prints a receipt. It does not summarise the session, does not ask questions, does not review or test, does not commit.

Why it exists: the unit of continuity is usually one long-lived session that gets compacted again and again, not a chain of fresh sessions. Handoff-style tools write a narrative for the next session to a place nothing reads. The loss happens inside the current session, right after compaction, and the fix is memory that survives it plus a pointer the next turn actually reads. Lessons behind the design:

• Save rules, decisions and gotchas, not "what was done". Activity is already in git log and STATUS.md.
• Every lesson saved only as a reaction to a complaint ("you forgot my pattern") was a lesson that should have been saved at the first compaction.
• Mid-task steers ("keep in mind", "as of now", "for now", "from now on") are extraction triggers with a scope attached, even when the user never says "memory".
• Counts quoted after compaction go stale; counts belong in a live-state file with a timestamp and the query that produced them, never in memory.
• The only cross-surface handoff that reliably works is plain chat text the user can paste; other agent surfaces may not read the same memory dir.

Procedure

1. Scope

• Everything in context since session start, or since the last marker line save-session: saved N items at <ISO time> if one exists.
• Include any compaction summary already in context; its "Primary Request", constraints and pending-tasks sections are candidate sources.
• Record: cwd, repo, branch, and the brain dir $AGENT_BRAIN_DIR (default ~/.agent-brain). If that dir has no INDEX.md, create it with the four headings ## User, ## Feedback, ## Project, ## Reference.

2. Extract candidates

Walk the scope and collect items into these buckets. Each item is one line: claim | evidence (turn or tool result) | date.

Mark each item verified (a tool result in this session shows it) or (unverified). Unverified items are still saved, tagged as such.

3. Drop noise

Discard anything that is:

• already in your user-level rules files, a CLAUDE.md (user, workspace or repo), or any INDEX.md line (brain recall <key noun> first)
• a transient error with no reusable cause
• activity narration that git log or STATUS.md already records
• a one-off UI nit
• agent-authored text: subagent prompts, worker chatter, your own plans
• a pasted third-party document, log, or web page

4. Secrets gate

Before routing, scan every item for ghp_, github_pat_, sk-, AKIA, eyJ, Bearer, session cookie names (sessionid, csrftoken, cf_clearance, __stripe_mid), .env values, and booking-reference / order-number / phone-number / address / salary shaped strings.

• Strip the value. Keep the NAME. Never write a value anywhere, including the receipt.
• Add a rotate: line to the receipt naming each credential seen.
• Identifiers (booking reference, order number, phone) are dropped; keep only the derived fact ("share rises 2,000/month"), never the identifier.

5. Dedupe

For each surviving item, search before writing:

• brain recall <key noun> against $AGENT_BRAIN_DIR
• INDEX.md description lines
• headings and bullets in your user-level rules files
• file names in the brain, in kebab-case AND snake_case (older files may be snake_case)

A match means update in place: add a dated line under **Why:** or **How to apply:**, bump modified in the frontmatter, report "updated". Never create a second file for the same fact.

6. Route

Send each item through the memory-router skill. It returns a destination and the exact format. Follow it; do not improvise a location.

7. Write

• brain remember for brain entries (or write the file directly and add its INDEX.md line; brain index rebuilds the index). Run brain lint after.
• Preserve each file's existing line endings; never sed -i a CRLF file.
• Absolute dates (2026-09-22), never relative.
• -- or -, never an em or en dash character.
• One memory file per lesson, named by the lesson (cpp-solutions-use-vector-never-arrays.md), never by the session or date.
• Add the INDEX.md line under the right heading.
• STATUS.md (optional, workspace root): update the > Last updated: line.
• Repo doc edits stay uncommitted unless the same message asked to push. "also update the readme and changelog" is an edit ask, not a commit ask.
• Nothing is ever written inside a fork of someone else's repo.

8. Receipt

Print under ~25 lines, no prose:

| item | destination | file | new/updated |
| ... | ... | ... | ... |

not saved: <item> (duplicate) / <item> (transient) / <item> (agent-text)
unfinished: <open item> -> <exact next command>
rotate: <CREDENTIAL_NAME>, <CREDENTIAL_NAME>
next session reads: <$AGENT_BRAIN_DIR/INDEX.md>, <STATUS.md or status file path>

save-session: saved N items at <ISO time>
safe to /compact

The next session reads: line is plain text on purpose: other agent surfaces may not read the brain dir, so this line is what the user pastes across surfaces. The marker line scopes the next run and rides into the compaction summary.

If nothing qualifies, print exactly: nothing new to save; live state already in STATUS.md and the marker line.

Non-goals

No narrative summary (users ask the agent to act, not to recap). No review pass, tests, or commits. No .claude/handoffs/. No blocking questions. No rewriting of legacy snake_case memory files. No touching generated content or anything between <!-- ...:START --> markers.

Standalone triggers

A single "remember this" or "add in user rule" mid-session runs steps 4 to 8 on that one item only and prints a one-line receipt with the absolute path. An explicit ask always writes at least one file, even when the router would otherwise discard.