Claude Code memory: the 5 techniques that actually work across sessions

One of the most common frustrations with Claude Code: you spend 20 minutes explaining your codebase, get great results, then come back the next day and start from scratch.

Claude Code has no persistent memory between sessions. But there are 5 techniques that come close — and using all 5 together means your sessions start informed, not blank.

Why Claude Code forgets everything

Claude Code runs in a stateless context window. When you close a session, nothing persists. The next session has no knowledge of:

• What files you edited
• What decisions you made
• What your conventions are
• What's already been tried

The context window is large (200k tokens) but not infinite, and it resets completely.

Technique 1: CLAUDE.md as persistent brain

This is the most powerful technique. CLAUDE.md is loaded automatically at session start.

# Project: MyApp

## What this is
Node.js REST API for a SaaS product. PostgreSQL database. JWT auth.

## Current status
- Auth: complete and working
- Payments: Stripe integration done, webhook handler has a bug (see TODO.md)
- Tests: 67% coverage, auth routes fully tested

## Conventions
- Use async/await, never callbacks
- Errors always return {error: string, code: string}
- Database queries go in /src/db/, not in routes

## Don't touch
- /src/legacy/ — untested, leave it alone
- config/production.js — ask before editing

## Recent decisions
- Switched from mongoose to pg (2026-03-15)
- Decided NOT to use Redis for sessions (cookie-based instead)

Every time you make a significant decision, update CLAUDE.md. It's the one file that persists.

Technique 2: Session handoff notes

At the end of each session, ask Claude to write a handoff:

Before we end: write a SESSION_NOTES.md that captures:
- What we accomplished today
- What's in progress (incomplete work)
- What I should tackle next session
- Any gotchas or decisions made

Start the next session with:

Read SESSION_NOTES.md and CLAUDE.md, then tell me what you understand about where we are.

This gives Claude a complete picture in the first 2 minutes.

Technique 3: Decision log

Create a DECISIONS.md file:

# Decision Log

## 2026-03-20: Database choice
**Decision**: PostgreSQL over MongoDB
**Reason**: Better for relational data, team knows SQL better
**Alternative rejected**: MongoDB (too flexible, no schema enforcement)

## 2026-03-25: Auth approach
**Decision**: JWT with 24h expiry, refresh tokens in DB
**Reason**: Stateless API, mobile clients need long sessions
**Alternative rejected**: Sessions (would need Redis)

This prevents Claude from suggesting approaches you've already rejected.

Technique 4: TODO.md as live work queue

Instead of keeping tasks in your head:

# TODO

## In progress
- [ ] Fix Stripe webhook handler (stripe-webhook.js:47 — signature verification failing)

## Next
- [ ] Add rate limiting to /api/chat
- [ ] Write tests for payment routes
- [ ] Migrate legacy user table (see /src/legacy/users.js)

## Blocked
- [ ] Email notifications (waiting for SendGrid API key from Brian)

## Done (keep for context)
- [x] JWT auth
- [x] Stripe integration
- [x] User CRUD

Start sessions with: Read TODO.md and tell me what's in progress.

Technique 5: ANTHROPIC_BASE_URL for session continuity

One underrated cause of memory issues: hitting Anthropic's rate limits mid-session, which forces a session restart.

If you're frequently hitting:

Claude is currently unavailable. Please try again later.

...you're losing session context unnecessarily.

Some developers use a Claude API proxy that removes the rate limits:

export ANTHROPIC_BASE_URL=https://simplylouie.com/api/claude

This routes Claude Code through a proxy so you're not subject to per-session rate limits. $2/month flat rate at simplylouie.com. The session itself still resets, but you don't lose context to rate limit interruptions.

Putting it all together

Here's the full init script that sets up all 5 techniques for a new project:

#!/bin/bash
# init-claude-project.sh

mkdir -p .claude

cat > CLAUDE.md << 'EOF'
# Project: [PROJECT_NAME]

## What this is
[Brief description]

## Tech stack
[List languages, frameworks, databases]

## Current status
[What's done, what's in progress]

## Conventions
[Your code style, patterns, preferences]

## Don't touch
[Protected files/folders]

## Recent decisions
[Key architectural decisions]
EOF

cat > TODO.md << 'EOF'
# TODO

## In progress

## Next

## Blocked

## Done
EOF

cat > DECISIONS.md << 'EOF'
# Decision Log
EOF

touch SESSION_NOTES.md

echo "Claude memory system initialized."
echo "Files created: CLAUDE.md, TODO.md, DECISIONS.md, SESSION_NOTES.md"

The startup prompt

Save this as .claude/startup.md:

Start of session checklist:
1. Read CLAUDE.md (project context)
2. Read TODO.md (current work queue)
3. Read SESSION_NOTES.md (last session handoff)
4. Confirm: what are we working on today?

Then start every session:

Read .claude/startup.md and follow the checklist.

Summary

Technique	What it stores	When to update
CLAUDE.md	Project context + conventions	Every major decision
SESSION_NOTES.md	Handoff + current progress	End of each session
DECISIONS.md	Why you chose X over Y	Every architectural choice
TODO.md	Work queue + blocked items	Continuously
Rate limit proxy	Session continuity	Set once in env

Claude Code's memory limitation is real, but with these 5 techniques you can get 90% of the way to persistent context.

What's your current memory strategy? I'm curious whether people are using CLAUDE.md for this or something else.

---

For rate-limit-free Claude Code sessions: simplylouie.com — flat $2/month, no usage caps.