Claude Code memory bank pattern: never lose context between sessions

If you've used Claude Code for more than a week, you've hit this wall: you start a new session, and Claude has no memory of what you were doing yesterday. You spend the first 10 minutes re-explaining your codebase, your decisions, your conventions.

There's a pattern that solves this completely. It's called the memory bank.

The problem with fresh sessions

Claude Code's context window is per-session. Every time you close and reopen it:

• No memory of previous decisions
• No memory of why you structured things a certain way
• No memory of what's broken and what you're actively fixing
• Re-reading documentation and files from scratch

For a small project, annoying. For a large codebase, genuinely painful.

The memory bank approach

The idea: maintain a set of markdown files that Claude reads at the start of every session. These files ARE the memory.

Create a memory-bank/ directory at your project root:

memory-bank/
  projectBrief.md       # What this project is
  activeContext.md      # What we're working on RIGHT NOW
  progress.md           # What's done, what's not
  decisions.md          # Why things are the way they are
  patterns.md           # Code conventions and patterns we use

The files in detail

projectBrief.md

High-level context that never changes:

# Project: AuthService

## What it does
JWT-based auth service for the platform. Handles signup, login, token refresh, and social OAuth.

## Stack
- Node.js + Express
- PostgreSQL (users, sessions)
- Redis (token blacklist)
- Docker Compose for local dev

## Key constraints
- Must support horizontal scaling (no local state)
- GDPR compliant (EU users, right to delete)
- Sub-100ms auth responses at p99

activeContext.md

This is the key file — update it every session:

# Active Context (updated 2026-04-05)

## Currently working on
Implementing refresh token rotation. Old tokens should be invalidated on use.

## Current problem
Refresh endpoint works but isn't invalidating old tokens in Redis.
File: src/routes/auth.js, function refreshToken(), line ~140

## Blocked on
Nothing currently blocked.

## Next steps
1. Fix Redis invalidation in refreshToken()
2. Add test coverage for rotation
3. Deploy to staging

decisions.md

Capture WHY decisions were made:

# Architecture Decisions

## Why Redis for token blacklist (not DB)
Decision: 2026-03-15
Reason: Token validation is in the hot path. Redis TTL auto-expires tokens, no cleanup job needed.
Tradeoff: One more service to run locally.

## Why we use UUIDs not auto-increment IDs
Decision: 2026-02-28
Reason: IDs leak user count to clients. Security > convenience.

The CLAUDE.md trigger

In your CLAUDE.md, add this at the top:

# Session Start Protocol

Before doing anything else:
1. Read memory-bank/projectBrief.md — understand the project
2. Read memory-bank/activeContext.md — understand what we're doing NOW
3. Read memory-bank/progress.md — understand what's done
4. Confirm with: "I've read the memory bank. Currently working on: [activeContext summary]"

At session end (or when asked to /memorize):
1. Update memory-bank/activeContext.md with current state
2. Add any new decisions to memory-bank/decisions.md
3. Update memory-bank/progress.md

The /memorize custom command

Create .claude/commands/memorize.md:

Update the memory bank to reflect the current state of the session.

1. Update memory-bank/activeContext.md:
   - What are we currently working on?
   - What problem are we actively solving?
   - What are the next steps?

2. If any significant decisions were made, add them to memory-bank/decisions.md

3. If any tasks were completed, update memory-bank/progress.md

After updating, confirm with a one-line summary of what changed.

Now you can run /memorize before ending any session and Claude will save its own context.

Real workflow

# Start of session
claude  # Claude reads memory bank automatically via CLAUDE.md

# Mid-session
/memorize  # Save state if taking a break

# End of session  
/memorize  # Always memorize before closing
exit

Next session, Claude opens with:

"I've read the memory bank. Currently working on: refresh token rotation. The Redis invalidation in refreshToken() at line ~140 is the active problem."

You're immediately productive instead of spending 10 minutes re-explaining.

What goes in progress.md

# Progress

## Done ✅
- Basic JWT auth (signup, login, logout)
- PostgreSQL user table and migrations
- Docker Compose local dev setup
- Social OAuth (Google, GitHub)
- Rate limiting on auth endpoints

## In Progress 🔄
- Refresh token rotation (Redis invalidation broken)

## Not Started ⬜
- Account deletion (GDPR right to delete)
- Admin API for user management
- Audit logging

This gives Claude (and you) a clear picture of where things stand.

Why this beats alternatives

vs just using CLAUDE.md: CLAUDE.md is static. The memory bank is dynamic — it evolves with the project.

vs pasting context at session start: Manual, error-prone, and you'll inevitably forget something.

vs relying on git history: Git tells you what changed, not why, and not what's actively broken.

The rate limit problem this solves sideways

One hidden benefit: when Claude re-reads your memory bank at session start, it loads context efficiently from files rather than through expensive back-and-forth conversation turns. This means you preserve more of your context window for actual work.

If you're hitting Claude Code rate limits mid-session, it's often because you've spent too many tokens on context reconstruction. The memory bank reduces that overhead significantly.

For teams hitting rate limits on the official Claude Code subscription, SimplyLouie provides an ANTHROPIC_BASE_URL-compatible endpoint at $2/month that works with this exact workflow — same commands, same memory bank pattern, no rate limit interruptions.

Getting started in 5 minutes

# Create the structure
mkdir -p memory-bank .claude/commands

# Create the command
cat > .claude/commands/memorize.md << 'EOF'
Update the memory bank with current session state.
Update memory-bank/activeContext.md with: what we're working on, current problems, next steps.
Add any significant decisions to memory-bank/decisions.md.
Confirm with a one-line summary of what changed.
EOF

# Add to CLAUDE.md
echo '' >> CLAUDE.md
echo '## Session Start Protocol' >> CLAUDE.md
echo 'Read memory-bank/activeContext.md before anything else. Confirm what we are working on.' >> CLAUDE.md

Then start Claude Code and say: "initialize the memory bank for this project" — Claude will read your codebase and populate the files.

That's it. Persistent memory for Claude Code, zero infrastructure required.