Claude is stateless. Every new conversation starts from zero. No memory of the last sprint, no recollection of the client's weird edge cases, no awareness that you've already solved this problem twice before.
That's fine for one-off tasks. It's a serious problem when you're building something real over days or weeks.
I spent a lot of time fighting this. Pasting in context blocks at the start of every session. Re-explaining the same architectural decisions. Watching Claude suggest the exact thing we decided against two weeks ago because it had no idea.
Eventually I stopped fighting the statelessness and started building around it. What I landed on is a lightweight memory architecture that gives Claude reliable persistent context without a lot of overhead to maintain.
Here's how it works.
The Problem With Most Approaches
Most people solve this one of two ways. Either they dump a giant wall of context at the top of every prompt, or they rely on the CLAUDE.md file to carry everything.
The first approach breaks down fast. Context windows are finite, and a 3,000-word project history injected at the start of every prompt crowds out the actual work. You get shallow responses because the model is burning tokens processing background instead of thinking about your actual question.
The second approach, relying on CLAUDE.md alone, works for static project-level context. But it's not built for evolving state. It doesn't capture decisions made yesterday, blockers that emerged this week, or the subtle shift in direction that happened after a client call.
What I wanted was something in between. Stable enough to persist. Lightweight enough not to bloat every prompt. Structured enough that Claude could actually use it.
The Three-Layer Memory Model
I split persistent context into three distinct layers. Each one has a different update frequency and a different job.
Layer 1: Project Bedrock
This is the stuff that almost never changes. Tech stack, architecture decisions, naming conventions, the client's core constraints, what's in scope, what's explicitly out of scope.
This lives in a file called project.md at the root of the project. It's written once and updated rarely, maybe when there's a major pivot. It's dense but short, usually under 400 words. No fluff, just decisions and constraints.
Example section:
Stack: Next.js 14 app router, Supabase, Tailwind, Resend for email. No Redux. State stays local or in Zustand if shared across more than two components. All API routes are server actions unless there's a reason they can't be.
Claude reads this and immediately knows how to make decisions without asking. That's the point.
Layer 2: Sprint Memory
This is the layer most people skip and it's the most valuable one. It captures the current working state of the project, what's done, what's in progress, what decisions got made in the last few sessions, and what's blocked.
I keep this in a file called sprint.md and I update it at the end of every working session. Takes about five minutes. Sometimes I ask Claude to draft the update based on what we did, then I clean it up.
The format is simple:
- Completed this session: short bullet list of what shipped or got resolved
- In progress: what's partially done and what state it's in
- Decisions made: anything architectural or directional that future sessions need to know
- Blockers and open questions: what's unresolved and why
- Next up: what I'm planning to tackle next session
When I start a new session, I paste in the sprint.md content before I do anything else. Not the whole project history, just the last session's summary. Claude picks up right where we left off.
Layer 3: Decision Log
This one is the most underrated. It's a running log of every significant decision made on the project, why it was made, and what alternatives were rejected.
File is called decisions.md. Entries look like this:
2025-06-10, Auth approach: Chose Supabase Auth over Clerk. Reason: client already had Supabase set up, didn't want another vendor. Considered Clerk for its UI components but decided against adding the dependency. If auth UX becomes a problem, revisit Clerk at that point.
I don't paste this whole file into every session. I reference it when I need it, or when Claude starts suggesting something that feels like a direction we already rejected. Then I pull the relevant entry and say: here's why we're not doing that.
This layer also protects you when you hand a project off or come back to it after a break. The reasoning is preserved, not just the outcome.
How I Actually Load Context at the Start of a Session
I have a short prompt template I use to open every Claude session on an active project. It looks roughly like this:
Here's the context for this project before we start. [PROJECT BEDROCK] {paste project.md} [SPRINT STATE] {paste sprint.md from last session} We're picking up from there. Today I want to work on: {specific task}. Before you start, confirm you understand the current state and flag anything that seems unclear or contradictory.
That last line matters. Asking Claude to confirm understanding and flag contradictions catches problems before they snowball. Sometimes it'll surface something like: you said no external API calls but the task you described requires one, want to talk through that? That's exactly what you want.
The decision log doesn't go in the opening prompt. It sits in the project directory and I pull from it on demand.
Automating the Sprint Update
Manually writing the sprint summary after every session adds friction. I've automated part of it.
At the end of a session, I run this prompt:
Based on everything we did in this session, draft a sprint.md update in this format: Completed, In Progress, Decisions Made, Blockers and Open Questions, Next Up. Be specific. Reference file names and function names where relevant. Keep bullets tight, one to two lines each.
Claude generates the draft. I spend two minutes editing it for accuracy, then save it. The next session loads fast because the handoff is clean.
If you're on a project with multiple collaborators or agents, this becomes even more valuable. Everyone starts from the same current state instead of reconstructing it from git commits and Slack threads.
What to Put In Project Bedrock (And What to Leave Out)
This file has a tendency to bloat if you're not careful. Every time something comes up, there's a temptation to add it. Resist that.
Bedrock should only contain things that are true for the entire life of the project and that Claude needs to know before touching any task. Think of it as the briefing document for a new developer joining the project for the first time.
What goes in:
- Stack and why it was chosen
- Folder structure and conventions
- Core constraints (performance targets, accessibility requirements, client mandates)
- What's in scope and explicitly out of scope
- Integration points and external dependencies
What does not go in:
- Current task status (that's sprint.md)
- Reasoning behind decisions (that's decisions.md)
- Anything that might change in the next month
- Background on the client that doesn't affect code decisions
Keep it to what shapes every code decision. Nothing else.
Why This Works Better Than Alternatives
Vector databases and embedding-based retrieval are the other option people reach for. Tools like Mem0, LangChain memory modules, that kind of thing. They work, but they add infrastructure and they add points of failure. For a solo builder or small team, the operational overhead usually isn't worth it.
This three-file system is auditable. You can read it. You can edit it. You know exactly what Claude is working with. When something goes wrong, you can trace it back to what context was loaded, and fix it.
It also forces a useful habit. Summarizing what you did at the end of a session is good practice whether Claude exists or not. It clarifies your thinking and gives you a trail to follow when you come back.
The Setup Cost Is Low
You don't need to build this before starting a project. I usually create project.md at the start and add decisions.md after the first few significant choices. Sprint.md gets created at the end of the first real working session.
Total setup time is under an hour spread across the first week. Maintenance is five minutes per session. The payoff is Claude that behaves like it's been on the project the whole time, not like it just woke up with no memory.
For long-running projects, client work, or anything you're going to be in for more than a week, this system pays for itself fast. Build the habit early.
