memory-bank

What this skill does

# Memory Bank

An adaptive memory system that gives Claude Code persistent, intelligent
context across sessions — while cutting token waste so your sessions last
3-5x longer. Not a flat file — a layered architecture that compresses,
branches, diffs, self-heals, and loads only what matters.

---

## Core Architecture

Memory Bank operates on three layers:

```
┌─────────────────────────────────────────────┐
│  Layer 2: GLOBAL MEMORY                     │
│  ~/.claude/GLOBAL-MEMORY.md                 │
│  Cross-project patterns, user preferences,  │
│  reusable decisions. Permanent.             │
├─────────────────────────────────────────────┤
│  Layer 1: PROJECT MEMORY                    │
│  ./MEMORY.md (+ branch overlays)            │
│  Architecture, decisions, active work.      │
│  Lives as long as the project.              │
├─────────────────────────────────────────────┤
│  Layer 0: SESSION CONTEXT                   │
│  In-conversation only.                      │
│  Current task focus, scratch notes.         │
│  Dies when session ends (persisted to L1).  │
└─────────────────────────────────────────────┘
```

**Layer 0 (Session)** — Ephemeral. Tracks what you're doing right now.
Automatically flushed to Layer 1 at session end.

**Layer 1 (Project)** — The primary memory file. Tracks project state,
decisions, active work, blockers. Branch-aware: each git branch can have
its own overlay that merges with the base memory.

**Layer 2 (Global)** — Cross-project knowledge. Your coding preferences,
tool choices, patterns you always use. Lives in `~/.claude/GLOBAL-MEMORY.md`.
Loaded alongside Layer 1 at session start.

> See `references/memory-layers.md` for full architecture details.

---

## When to Activate

| Trigger | Action |
|---------|--------|
| Session starts, `MEMORY.md` exists | Full load sequence |
| `"remember this"`, `"don't forget"` | Mid-session update |
| `"wrap up"`, `"save progress"`, `"done for now"` | Full session write |
| `"pick up where we left off"`, `"what were we doing"` | Load + summarize |
| `"switch to [branch]"`, `"context for [feature]"` | Branch-aware load |
| `"memory health"`, `"is memory stale"` | Health check |
| `"hand off"`, `"onboard someone"` | Generate handoff doc |
| `"compress memory"`, `"clean up memory"` | Run compression |
| `"rebuild memory"` | Recovery mode |
| `"save state"`, `"continue this later"` | Session continuation protocol |
| `"context budget"`, `"how much context left"` | Context budget check |
| `"running out of context"`, `"session is long"` | Emergency save + continuation file |

---

## Workflow

### 1. Session Start — The Load Sequence

Execute this sequence before doing anything else:

```
Step 1: Detect memory files
  └─ Check for MEMORY.md in project root
  └─ Check for ~/.claude/GLOBAL-MEMORY.md
  └─ Check for MEMORY-ARCHIVE.md (has history been archived?)

Step 2: Detect git context
  └─ Current branch name
  └─ Check for .memory/branches/<branch>.md overlay
  └─ Days since last session (from "Last updated" field)

Step 3: Session diff (if git available)
  └─ Commits since last memory update
  └─ Files changed since last session
  └─ Any conflicts between memory and current code state

Step 4: Health check
  └─ Score memory freshness (see Health Scoring below)
  └─ Flag stale entries
  └─ Flag referenced files that no longer exist

Step 5: Context-aware greeting
  └─ Summarize where we left off (2-3 sentences, specific)
  └─ Report any drift detected (code changed, memory stale)
  └─ State the next immediate action
  └─ Ask: "Ready to continue, or has the plan changed?"
```

**Example greeting (fresh memory, same branch):**
> "Welcome back! Last session you finished the Stripe webhook handler in
> `src/api/webhooks/stripe.ts` and were about to write integration tests.
> The `handlePaymentSuccess()` function is complete but `handleRefund()` is
> stubbed out. 3 commits have landed since — all yours, no surprises.
> Ready to pick up with the integration tests?"

**Example greeting (stale memory, branch switched):**
> "Welcome back! Your memory is from 5 days ago on `main`, but you're now
> on `feature/user-profiles`. I found a branch overlay from 3 days ago with
> context about the profile avatar upload. However, `src/components/Avatar.tsx`
> referenced in memory was renamed to `ProfileImage.tsx`. Want me to update
> memory with the current state before we continue?"

**If no MEMORY.md exists:**
- Proceed normally
- After first meaningful work, offer: "Want me to start tracking our
  progress? I'll create a memory file so next session picks up instantly."

---

### 2. Mid-Session Updates

When the user says "remember this" or you complete a significant milestone:

1. Read current `MEMORY.md`
2. Determine what changed:
   - New decision made? → Update `Key Decisions`
   - Task completed? → Move from `Active Work` to `Completed`, update `Where We Left Off`
   - New blocker? → Add to `Blockers`
   - Important context? → Add to `Notes`
3. Write the updated file
4. Confirm with specifics: "Saved — added the Zod migration decision and
   marked the user model as complete."

**Do NOT rewrite the entire file on mid-session updates.** Only modify
the sections that changed. This preserves context from session start.

---

### 3. Session End — The Write Sequence

When wrapping up, execute a full memory write:

```
Step 1: Audit the session
  └─ What was accomplished? (be specific: files, functions, lines)
  └─ What decisions were made and why?
  └─ What's blocked or unresolved?
  └─ What should happen next? (crystal clear next step)

Step 2: Compress completed work
  └─ Move finished items to Completed with one-line summaries
  └─ Remove resolved blockers
  └─ Archive stale notes

Step 3: Update memory health metadata
  └─ Update "Last updated" timestamp
  └─ Increment session counter
  └─ Update file reference table (verify paths still exist)

Step 4: Write MEMORY.md
  └─ Full overwrite with current state
  └─ Verify the file was written successfully

Step 5: Check compression threshold
  └─ If > 150 lines, suggest compression
  └─ If > 200 lines, auto-compress (see Smart Compression)

Step 6: Prompt for global memory
  └─ Any cross-project learnings worth saving to Layer 2?
  └─ New user preferences discovered?
```

---

## MEMORY.md Template

```markdown
# Project Memory
Last updated: [DATE] | Session [N] | Branch: [BRANCH]
Memory health: [SCORE]/10

## Project Overview
[1-2 sentences. What this is, what stack, what stage.]

## Where We Left Off
- **Current task:** [specific task with file/function reference]
- **Status:** [done | in progress | blocked]
- **Next immediate step:** [so clear Claude can start without asking anything]
- **Open question:** [decision pending, if any]

## Completed
- [DATE] [one-line summary with key files touched]
- [DATE] [one-line summary]

## Active Work
- [ ] [task — specific file, function, or component]
- [ ] [task]
- [x] [recently completed, will archive on next compression]

## Blockers
- [blocker with context on what's needed to unblock]

## Key Decisions
| Date | Decision | Reasoning | Affects |
|------|----------|-----------|---------|
| [DATE] | [what was decided] | [why] | [files/areas impacted] |

## Key Files
| File | Purpose | Last Modified |
|------|---------|---------------|
| [path] | [what it does] | [session N] |

## Architecture Notes
[Non-obvious design choices, data flow, system boundaries]

## Known Issues
- [issue, severity, and workaround if any]

## Session Log
| Session | Date | Summary |
|---------|------|---------|
| [N] | [DATE] | [one-line summary of what happened] |

## User Preferences
[How the user likes to work — discovered across sessions]

## External Context
[APIs, services, env setup — NO secrets, NO credentials, NEVER]
```

---

## Branch-Aware Memory

When working across multiple git branches, memory adapts:

```
MEMORY.md                          <- Base project memory (main/trunk)
.memory/
  branches/
    feature-auth