# session-memory

> Give your Claude Code sessions memory across /clear and /compact boundaries. Save/resume workstream state to named session files without clobbering shared MEMORY.md. Triggers on "save session", "continue session", "clear session".

- Author: Alon Lavi
- Repository: guardzcom/skills
- Version: 20260207215458
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-07
- Source: https://github.com/guardzcom/skills
- Web: https://mule.run/skillshub/@@guardzcom/skills~session-memory:20260207215458

---

---
name: session-memory
description: Give your Claude Code sessions memory across /clear and /compact boundaries. Save/resume workstream state to named session files without clobbering shared MEMORY.md. Triggers on "save session", "continue session", "clear session".
---

# Session Memory

Save workstream state to its own file. MEMORY.md stays a thin index. Multiple sessions can save concurrently without conflict.

## Triggers

- **Save:** "save session {name}", "save session" (defaults to branch name)
- **Resume:** "continue {name}", "continue session" (auto-select if one, list if many)
- **Cleanup:** "clear session {name}"

---

## Save Procedure

### 1. Determine Name

If user gave a name, use it (lowercase, sanitize: replace `/` with `-`).
If no name, derive from branch:

```bash
git branch --show-current
```

Sanitize: lowercase, replace `/` with `-`, strip leading `-`.

### 2. Locate Memory Directory

Find the auto memory directory path from the system prompt line:
`You have a persistent auto memory directory at <path>`

### 3. Gather State

Run in parallel:

```bash
git branch --show-current
git status --short | head -10
```

From conversation context, determine:
- What was accomplished this session
- What failed or was abandoned (and why)
- What the next action should be
- Which files were modified

### 4. Find Active Plan

Check if a plan file was referenced in conversation context. If found, read it to get step N of M. If none referenced, skip — don't guess.

### 5. Write Session File

Write `<memory_dir>/session-{name}.md`:

```markdown
# Session: {name}

- **Branch:** `{branch}`
- **Saved:** {YYYY-MM-DD HH:MM}
- **Plan:** `~/.claude/plans/{file}` (step N of M)

## Next Action: {Title}
{1-3 lines with file paths}

## Done This Session
- {accomplishments}

## Failed Approaches
- {what + why — or "None"}

## Modified Files
- {list}
```

Omit the **Plan:** line if no plan file exists.

### 6. Update MEMORY.md Index

Read MEMORY.md. Find the `## Active Sessions` section.

- If session name already in index: update its line.
- If not: add a new bullet.
- If no `## Active Sessions` section exists: insert it after the first `#` heading. If MEMORY.md doesn't exist, create it with `# Project Memory` as the heading.

Bullet format:
```
- **{name}** ({branch}, {Mon DD HH:MM}) — {one-line summary}
```

Keep the `Resume any: \`continue {name}\`` line after the bullets.

Do NOT touch any other sections in MEMORY.md.

### 7. Smart Output

Always save the session file (it's insurance if they `/clear` later). Then recommend the right next step.

**Heuristic:** Is there an active plan referenced in conversation context?

**Yes → plan-driven.** Context is disposable (plan tracks progress). Recommend `/clear`:

```
Session "{name}" saved -> session-{name}.md

/clear then: continue {name}
Next: {one-line next action}
```

**No → exploratory.** Context has unique value (debugging, discoveries, decisions). Recommend `/compact` to preserve it:

```
Session "{name}" saved -> session-{name}.md

/compact {focus guidance derived from session's key findings}
```

No "continue" line for the `/compact` case — they're staying in the session. The session file is there if they `/clear` later.

---

## Resume Procedure

### 1. Determine Name

If user gave a name, use it.
If no name given:
- List `session-*.md` files in memory directory
- If exactly one: use it automatically
- If multiple: list them and ask user to pick
- If none: report "No saved sessions found." and stop

### 2. Read Session File

Read `<memory_dir>/session-{name}.md`.
If file missing: list available sessions (from filenames), ask user to pick.

### 3. Check Branch

```bash
git branch --show-current
```

If current branch differs from session's branch, warn:
```
Warning: You're on `{current}` but session was saved on `{saved}`. Switch with: git checkout {saved}
```

Continue regardless — user decides.

### 4. Load Plan

If session references a plan file, read it.

### 5. Present and Begin

Output the session summary and next action.

If **Failed Approaches** is non-empty, explicitly note them before starting work:
```
⚠ Previously failed: {approach} — {why}
```

Do not repeat failed approaches. Choose alternative strategies. Then begin working on the next action.

---

## Cleanup Procedure

### 1. Delete File

Delete `<memory_dir>/session-{name}.md`.

### 2. Update MEMORY.md

Remove the bullet for `{name}` from `## Active Sessions`.
If no bullets remain, remove the entire section (header + resume line).

### 3. Output

```
Cleared session "{name}"
```

---

## First-Time Migration

If MEMORY.md contains legacy volatile sections (`## Current State`, `## Next Action`, `## Session Checkpoint`, `## Session * Summary`, `## Active Checkpoints`), migrate on first save:

1. Extract volatile content into the session file being saved
2. Remove volatile sections from MEMORY.md
3. Add `## Active Sessions` section to MEMORY.md
4. Preserve all stable sections verbatim