What Is The Memory Layer

What is the memory layer?

CLAUDE.md files tell Claude WHO you are. The memory layer tells Claude WHAT you've done - across every session, every project, forever. It's the second half of making every session feel like a continuation of the last, not a restart.

The problem memory solves

Every new Claude Code session starts fresh. The context window is empty, the conversation is new. Without a memory layer:

• You have to re-explain what you're working on every session
• You lose decisions and learnings every time a session ends
• Claude can't reference work from last week when you come back this week
• There's no single place to search across all your past sessions

With a memory layer in place

• At the end of every session, a summary gets saved - what you worked on, decisions, next steps
• At the start of every new session, the relevant memory loads automatically
• You can search across every session you've ever run: "what did we decide about X three weeks ago?"
• Claude picks up where you left off with full context - not just the last message

Two ways to store memory

Claude Code can save memory in two places. Both work. Choose based on how much you want to set up upfront.

Option 1: Markdown files (simplest)

Memory lives in plain markdown files inside your project folder - typically memory.md, decisions.md, and a sessions/ folder with one file per session.

• Pros: zero setup, no account to create, no database to run, works offline, version-controlled via git automatically
• Pros: human-readable - open any .md file in any editor and see what's there
• Cons: no cross-project search (you'd search one project folder at a time)
• Cons: no semantic / fuzzy search - just full-text
• Cons: gets slow if you accumulate thousands of sessions across many projects

Best for: beginners, solo operators, anyone with 1-5 projects, anyone who wants the simplest possible setup.

Option 2: Supabase database (more powerful)

Memory lives in a Supabase database (a hosted Postgres database, free tier covers most use cases).

• Pros: one place to search across every project you've ever worked on
• Pros: semantic search - find "sessions about email delivery issues" by meaning, not exact keywords
• Pros: handles thousands of sessions without slowing down
• Pros: scales when you have many clients or projects
• Cons: requires signup + 5-minute setup
• Cons: requires an internet connection to read/write memory

Best for: agencies, consultants with many clients, anyone planning 20+ projects or 100+ sessions, anyone who wants cross-project search.

You can start with markdown files + graduate later Most members start with markdown files - zero friction to try. If you grow past 5-10 projects or find yourself wanting cross-project search, migrate to Supabase (covered in Lesson 2-4). Your existing markdown memory can be imported - nothing is lost.

What gets saved either way

• Projects - one record per client or initiative (context, pending items, rules)
• Sessions - one record per Claude Code session (summary, decisions, actions, learnings, pending items)
• Rules - preferences and patterns that apply across sessions

Think of it as a persistent brain that survives every session. Every session adds to it. Every session can read from it. Whether that brain lives in .md files or a database is a storage choice, not a functional one.

What this module covers

1. This lesson - the why, and the choice between markdown and Supabase
2. Lesson 2 - set up markdown memory (the simple path)
3. Lesson 3 - set up Supabase memory (the scaled path)
4. Lesson 4 - connect /startup and /wrapup skills to whichever you chose
5. Lesson 5 - maintain and audit your memory over time

You can do Lesson 2 OR Lesson 3 - you don't need both. Pick one based on your situation.

Action items

☐ Understand: memory = persistent store that survives across sessions

☐ Understand: CLAUDE.md (who you are) + memory (what you've done) = full context

☐ Decide which option you'll start with - markdown (simpler) or Supabase (scaled) ☐ Rule of thumb: start with markdown. Upgrade to Supabase when you need cross-project search.

Next lesson: Set up markdown memory (skip to Lesson 3 if you're going straight to Supabase).

Exercises

1. Review the concepts covered in this lesson: What Is The Memory Layer.
2. Write down your key takeaway from this lesson.
3. Practice running any commands or prompts mentioned above inside your terminal.