The Memory System That Makes Claude Code Coherent Across Sessions

Every Claude Code session starts from zero. It doesn't know who you are, what you're building, which bugs you fixed yesterday, or what your priorities are. Every new conversation is like the first day of an intern's job, except this intern forgets everything every evening and shows up blank the next morning.

For a quick coding question, this is fine. For running a company across weeks and months, it's a dealbreaker. I needed Claude Code to remember.

The Architecture

The solution is a file-based memory system. Every project has a memory directory at ~/.claude/projects/[project-hash]/memory/. Inside are individual .md files, each with YAML frontmatter.

The schema for each memory file:

---
name: "client project status"
description: "Arabia app paused, Saudi Hotels prioritized"
type: project
---

Client put Resorts Magazine on hold to prioritize Saudi Hotels app.

**Why:** Email from client, March 31st
**How to apply:** Don't propose work on Resorts until client resumes

An index file called MEMORY.md gets loaded automatically into every Claude Code conversation. It contains one-line links to each memory file, acting as a table of contents rather than holding the content itself. Max 200 lines. When Claude needs details, it reads the specific memory file.

Four Types of Memory

Each type has a distinct purpose. Getting the taxonomy right matters more than the implementation.

User captures who I am. My profile: developer, 18, builds iOS apps, runs SubraLabs, prefers direct communication, uses an iPhone 16 for testing. This calibrates how Claude talks to me. You explain things differently to a senior engineer than to someone writing their first app.

Feedback records corrections AND confirmations. This is the most important type. When I say "don't do that" or "yes, exactly like that", the system records the rule with the reason.

Example: "Always use light backgrounds, never black. Why: User prefers a magazine-style aesthetic with lots of light. How to apply: Use #FFFFFF or cream colors for all app backgrounds."

Confirmations matter as much as corrections. If you only record mistakes, you become overly cautious and start second-guessing approaches that actually worked. When I accept an unusual choice without pushback, that's signal too.

Project tracks state that isn't derivable from code. Things like: "The client paused Resorts Magazine to prioritize the new Saudi Hotels app. Why: Email from March 31st. How to apply: Don't propose Resorts work until the client resumes the conversation."

This type decays fast. A fact recorded two weeks ago might not be true anymore. The "why" field helps future sessions judge whether the memory is still relevant.

Reference stores pointers to external resources, specifically where to find information outside the project. "Pipeline bugs are tracked in the Linear project 'INGEST'." Or: "The Grafana dashboard at grafana.internal/d/api-latency is what oncall watches."

What NOT to Save

This is as important as knowing what to save:

• Code patterns, conventions, architecture can be read directly from the codebase
• Git history is authoritative through git log and git blame
• Debugging solutions live in the code itself, with context in the commit message
• Anything already in CLAUDE.md belongs in the project's static instructions file
• Current session state is ephemeral and not useful tomorrow

The rule: memory is for what can't be re-derived. If you can read it from the repo, don't put it in memory.

How It Works in Practice

The flow on a typical day:

1. I open a Claude Code session. MEMORY.md loads automatically into context.
2. Claude sees the memory titles and descriptions and decides which are relevant to the current task.
3. When it needs details, it reads the specific file, say feedback_app_style.md.
4. If I correct something during the session ("no, the client changed their mind, they want the dark theme now"), Claude creates or updates a memory file.
5. Tomorrow's session finds that file and accounts for it.

The system isn't perfect. Memories go stale. A fact recorded two weeks ago might not be true today. So there's a discipline: before acting on a memory, verify it. If a memory says "the function processPayment is in billing.swift", grep for it first. "The memory says X exists" is not the same as "X exists now."

The Bigger Picture: Five Layers of Persistence

Memory is just one layer. The full persistence stack at SubraLabs:

CLAUDE.md contains static project instructions: conventions, rules, repo structure. Like an employee handbook, it changes rarely.

PROJECT.md is the source of truth for project state, updated daily. What's active, what's blocked, who's waiting on what. Like the project board.

status/ holds daily logs. What got done, what's next, blockers encountered. Like a written standup.

Hooks run at SessionStart, syncing email and presenting context. Automation without memory, just runs every time.

Memory is the subjective layer. Preferences, lessons learned, context that isn't in the code or the logs.

Together, these five layers create continuity. Not perfect continuity, because there are gaps, stale data, and missed context. But functional continuity. Tomorrow's session knows who I am, what I prefer, where the projects stand, and what happened yesterday.

Right now the system has 21 memory files for the main project: 1 user profile, 9 feedback entries, 6 project states, and 5 references. It's small, manageable, and it does the job. The point isn't building a sophisticated database. It's giving Claude Code enough context to stop being the intern who forgot everything overnight.