┌─────────────────────────────────────────────┐
│  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).  │
└─────────────────────────────────────────────┘

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?"

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?

undefined

---

MEMORY.md                          <- Base project memory (main/trunk)
.memory/
  branches/
    feature-auth.md                <- Overlay for feature/auth branch
    feature-payments.md            <- Overlay for feature/payments branch
    bugfix-race-condition.md       <- Overlay for bugfix branch

undefined

> See `references/smart-compression.md` for the full compression algorithm.

---

undefined

**Report format:**
> "Since your last session (3 days ago), there have been 7 commits:
> 4 by you, 3 by @teammate. Key changes: `src/api/users.ts` was refactored,
> `package.json` has 2 new dependencies (zod, @tanstack/query).
> Your memory references `src/api/users.ts` — I'll verify it's still accurate."

**Conflict detection:**
When session diff reveals changes that contradict memory:
- Memory says "using Express" but `package.json` now has Fastify → flag
- Memory references `src/auth/login.ts` but file was deleted → flag
- Memory says "blocked on API key" but `.env` now has it → update

> See `references/session-diffing.md` for conflict resolution strategies.

---

Memory health: 8/10
  Freshness:    9/10 (updated yesterday)
  Relevance:    7/10 (2 file paths changed)
  Completeness: 8/10 (all sections present)
  Actionability: 9/10 (next step is crystal clear)

Step 1: Scan the project
  └─ Read package.json / pyproject.toml / go.mod (detect stack)
  └─ Read README.md and CLAUDE.md (project context)
  └─ List key directories and recent files

Step 2: Read git history
  └─ Last 20 commits (who, what, when)
  └─ Current branch and recent branches
  └─ Any open/recent PRs

Step 3: Reconstruct memory
  └─ Build Project Overview from package.json + README
  └─ Build Key Files from most-modified files in git log
  └─ Build Key Decisions from commit messages and code patterns
  └─ Set "Where We Left Off" from most recent commits
  └─ Flag confidence level: "Reconstructed from code — verify with user"

Step 4: Present and confirm
  └─ Show reconstructed memory to user
  └─ Ask for corrections
  └─ Write verified MEMORY.md

undefined

Trigger with: "generate a handoff", "onboard someone to this project",
"write a handoff doc"

---

Session start WITHOUT memory-bank:

User: "Let's continue working on the app"
Claude: "What app? What stack? What were we doing?"
User: "It's a Next.js e-commerce app with Prisma and Stripe..."
       [400+ tokens explaining the project]
User: "We were building the checkout flow..."
       [300+ tokens explaining current state]
User: "The key files are..."
       [200+ tokens listing files]
User: "We decided to use X because..."
       [300+ tokens re-explaining decisions]

Total wasted: ~1,200+ tokens EVERY SESSION just to get back to baseline.
Over 10 sessions: ~12,000 tokens wasted on re-explanation alone.

Session start WITH memory-bank:

Claude reads MEMORY.md: ~800 tokens (compact, structured, complete)
Claude greets with full context: ~150 tokens
User: "Let's go"

Total: ~950 tokens. Savings: 60-80% per session start.
Over 10 sessions: ~9,000+ tokens saved on context alone.

Tier 1: ALWAYS load (costs ~200 tokens)
  └─ Project Overview (1-2 sentences)
  └─ Where We Left Off (current task, status, next step)
  └─ Active Blockers

Tier 2: Load on DEMAND (costs ~300 tokens when needed)
  └─ Key Decisions (only when a decision comes up)
  └─ Key Files (only when working with files not in Tier 1)
  └─ Architecture Notes (only when touching architecture)

Tier 3: Load ONLY when asked (costs ~200 tokens when needed)
  └─ Session Log (only for velocity/history questions)
  └─ User Preferences (only on first session or when relevant)
  └─ External Context (only when working with APIs/services)

BAD (38 tokens):
  "We made the decision to use Prisma as our ORM instead of Drizzle
   because it provides better TypeScript type inference and the team
   is already familiar with it from previous projects."

GOOD (14 tokens):
  | 2025-04-01 | Prisma over Drizzle | Type inference, team familiarity | All DB |

BAD (scattered prose — 120 tokens for 5 files):
  The main checkout route is in src/app/api/checkout/route.ts. The Stripe
  client is configured in src/lib/stripe.ts. Cart state management is in...

GOOD (table — 60 tokens for 5 files):
  | File | Purpose |
  | src/app/api/checkout/route.ts | Stripe session creation |
  | src/lib/stripe.ts | Stripe client singleton |
  | src/stores/cart.ts | Zustand cart + persistence |

BAD (prose):
  We are currently working on the webhook handler, which is partially
  complete. We also need to write tests and haven't started yet.

GOOD (checklist):
  - [x] Stripe webhook handler — handlePaymentSuccess()
  - [ ] handleRefund() — stubbed, needs implementation
  - [ ] Integration tests for webhook endpoints

BAD: "The project is essentially a web application that was built for..."
GOOD: "Bakery e-commerce. Next.js 14, Prisma, Stripe. Launching April."

At session start, estimate the context budget:

Available context:   ~200,000 tokens (Claude's window)
Memory load:         ~800 tokens (Tier 1 + loaded Tiers)
System prompt:       ~2,000 tokens
Remaining for work:  ~197,200 tokens

At 40% usage (~80,000 tokens consumed):
  → Suggest: "We're at 40% context. Consider compacting soon."

At 60% usage (~120,000 tokens consumed):
  → Save a session checkpoint automatically
  → Suggest: "Context at 60%. Good time to /compact or start fresh."

At 80% usage (~160,000 tokens consumed):
  → Auto-save full state to MEMORY.md
  → Alert: "Context is at 80%. Saving state now — you can continue
     in a new session with zero loss. Say 'wrap up' or keep going."

Step 1: EMERGENCY SAVE (before context dies)
  └─ Write MEMORY.md with EVERYTHING from current session
  └─ Include exact cursor position: file, function, line number
  └─ Include any uncommitted mental model (what Claude was thinking)
  └─ Include partial work state: what's done, what's half-done, what's next

Step 2: Write CONTINUATION.md (a one-shot warm-up file)
  └─ Ultra-compact: under 50 lines, under 500 tokens
  └─ Contains ONLY what the next session needs to start immediately
  └─ Format:

  ```markdown
  # Continue: [task name]
  Resume from: `src/auth/refresh.ts:47` — writing rotateToken()
  
  ## State
  - handlePaymentSuccess(): DONE ✓
  - handleRefund(): stubbed at line 89, needs Stripe refund.created event
  - Tests: NOT STARTED
  
  ## Context
  - Stripe webhook sig verified in middleware (line 12)
  - Using stripe.webhooks.constructEvent() not manual HMAC
  - Refund handler follows same pattern as payment handler
  
  ## Immediate Next Action
  Implement handleRefund() in src/api/webhooks/stripe/route.ts:89
  using the stripe.refund.created event payload. Pattern:
  extract refund.payment_intent → find order → update status to "refunded"

**Trigger phrases:** "save state", "I'm running out of context",
"continue this later", "session is getting long"

✗ Verbose prose where a table works
✗ Repeating the same information in multiple sections
✗ Storing code snippets in memory (reference file:line instead)
✗ Long descriptions of completed work (one-line summaries only)
✗ Keeping resolved blockers (delete them)
✗ Storing information that's in README.md or CLAUDE.md already
✗ Using memory for things Git tracks (commit history, diffs, blame)

✓ Tables for structured data (decisions, files, tasks)
✓ Checklists for active work
✓ One sentence for Project Overview (not a paragraph)
✓ File:line references instead of describing code
✓ Delete resolved items (they're in git history)
✓ Reference other files instead of duplicating content

undefined

> See `references/claude-md-integration.md` for the full integration guide.

---