Give Claude Code memory between sessions with three Markdown files

igal — Sat, 06 Jun 2026 12:49:37 +0000

Claude Code is brilliant inside a session and completely amnesiac between them. Close the terminal, come back tomorrow, and it has forgotten your architecture, your preferences, the bug you already solved, and the decision you made last week. So you spend the first ten minutes of every session re-explaining your project — and it still cheerfully suggests something you ruled out yesterday.

That cold-start tax adds up. Here's the small system I use to kill it. No plugin, no extension, no subscription — just three plain Markdown files and two habits.

The key insight

Claude Code automatically reads a file called CLAUDE.md at the start of every session. That's the whole hook. Instead of treating it as a static config file, treat it as a doorway: have it carry a short protocol that tells Claude to rebuild its own context before doing anything.

Split the context across three files by how often each changes:

CLAUDE.md — your standing rules + the session protocol. Read every session, so keep it short.
docs/JOURNAL.md — a chronological log of what's happened. Changes every session.
docs/KNOWLEDGE.md — durable facts, decisions, and gotchas. Rarely changes.

The protocol

The heart of it lives in CLAUDE.md:

## Session-start protocol (REQUIRED — do this before anything else)
1. Read docs/JOURNAL.md — the most recent entry is where we are.
2. Read docs/KNOWLEDGE.md — fundamentals, decisions, gotchas.
3. Greet me with current phase, last action, and the exact next step. Then wait.

## Session-end protocol (REQUIRED before we stop)
Append a journal entry: what we did / pitfalls hit / phase status / next steps.
Then commit.

With that in place, a session looks like this:

You open Claude Code. It reads the protocol, then the journal and knowledge base, and greets you with "current phase is X, last action was Y, next step is Z." No re-explaining.

You work. It already knows your stack, your style, and the decisions you've locked in — so it doesn't re-pitch the database you rejected last week.

You wrap up. It appends a journal entry — what you did, what tripped you up, and the exact next action — then commits. Tomorrow's session starts cold and is productive in under a minute.

Why a journal and a knowledge base?

Because they answer different questions. The journal is "what happened" (chronological, append-only). The knowledge base is "what's true" (reference, edited in place). The most valuable line in the journal is the next-steps block at the bottom of the latest entry — it's the handoff note to your future self, and it's what makes cold starts instant. The most valuable section in the knowledge base is the decision log, which stops settled questions from being re-litigated three weeks later.

Setup (about five minutes)

Drop CLAUDE.md into your project root, next to where you run claude.
Create docs/JOURNAL.md and docs/KNOWLEDGE.md (empty is fine to start).
Fill in the project-specific blanks in CLAUDE.md: owner, goal, stack, repo map.
Start your next session. It reads the protocol and asks what to work on.

The only habit you need is at the end of each session: "wrap up — append the journal entry and commit." That single habit is what makes every future session start fast.

It only gets more valuable the longer you run it: the journal deepens, your hard-won pitfalls stop repeating, and the knowledge base becomes the institutional memory of the project.

Grab the files

I put the core protocol and a ready-to-use CLAUDE.md up as a free, MIT-licensed repo:

👉 github.com/igal-in/claude-code-memory

That free file is the engine and works on its own. If you'd rather not build the journal and knowledge-base templates from scratch, I also packaged the complete system — both templates with the proven formats, a fully filled-in example project, and a short guide on adapting it — as the Claude Code Memory Kit ($12 on Gumroad).