Never Lose Context Again The Four-Layer Memory Stack

The solution is a four-layer memory system made up of simple text files and a shell script. Once set up, it takes care of itself automatically. Let's build each layer from scratch, explaining every single concept along the way.

The Four Layers at a Glance

Before diving into each layer, here's what we're building and how the pieces fit together:

CLAUDE.md — Your Permanent Rulebook

The foundation of the entire memory stack. Claude Code reads this automatically before every session.

What is CLAUDE.md?

When you run Claude Code inside a project directory, it automatically looks for a file called CLAUDE.md at the root of your project. If it finds one, it reads it before doing anything else. Think of it as a "briefing document" you hand to Claude at the start of every session — describing who you are, how you like to work, and what your project is about.

This file is static, meaning Claude Code reads it but does not modify it. You write it once, and it silently applies to every session forever. It's the foundation of the entire memory stack.

What should CLAUDE.md contain?

1. Project Identity

Describe your project in plain language. What does it do? Who uses it? What tech stack does it use? Claude should never need to ask "so what is this project?" if you answer this here.

2. Coding Conventions

Do you use tabs or spaces? Single quotes or double quotes? Do you write TypeScript or JavaScript? Do you prefer functional components or classes in React? Define these once here, and Claude will respect them forever.

3. Architectural Decisions

Every project has key decisions that shaped its structure. "We chose Postgres over MongoDB because...", "We use Zod for all validation because...", "All API calls go through the /lib/api.ts wrapper because...". Document those decisions so Claude never suggests something that contradicts them.

4. Things Claude Must Never Do

This is often the most valuable section. Examples: "Never use any type in TypeScript", "Never write inline styles", "Never commit secrets or keys", "Never modify the database schema without asking first".

5. The Primer Rewrite Instruction

This is the single most important addition to your CLAUDE.md — the instruction that powers the entire memory stack. More on this in the next section, but you must add it here.

# Project: My SaaS App

## What This Project Is
A subscription-based task manager for small teams.
Backend: Node.js + Express. Database: PostgreSQL.
Frontend: React + TypeScript. Auth: JWT tokens.
Deployed on: Railway (backend), Vercel (frontend).

## Code Conventions
- Always use TypeScript (never plain JS in .ts/.tsx files)
- Use single quotes for strings
- 2-space indentation
- All async functions must have try/catch error handling
- Use named exports, not default exports (except pages)
- API response format: { data, error, status }

## Architecture Rules
- All DB queries go through /src/db/queries/ — never raw SQL elsewhere
- All API calls from the frontend go through /src/lib/api.ts
- Environment variables accessed only through /src/config.ts

## Never Do
- Never use `any` type in TypeScript
- Never store secrets in code — use .env variables
- Never write inline CSS styles
- Never modify the DB schema without discussing it first

## SESSION MANAGEMENT (CRITICAL)
At the end of EVERY session, you must rewrite primer.md completely.
Include:
1. Current state of the project
2. What was accomplished this session
3. Immediate next steps (specific, actionable)
4. Any open blockers or unresolved issues
5. Any important decisions made this session

primer.md — The Living State Document

Claude rewrites this at the end of every session, so the next session always starts with full context.

The problem CLAUDE.md doesn't solve

Your CLAUDE.md is great for permanent rules — things that don't change. But it doesn't know what happened yesterday. It doesn't know you're halfway through implementing a new feature. It doesn't know you hit a bug that's blocking the next step. That's what primer.md is for.

primer.md is a second markdown file in your project root. Unlike CLAUDE.md (which you write and never touch again), Claude Code rewrites primer.md at the end of every session. That means when you start your next session, the very first thing Claude reads is an accurate, up-to-date description of exactly where your project stands.

How it works

What a good primer.md looks like

Here's an example of what Claude might write into your primer.md at the end of a session:

# Project State — Updated: 2025-06-14

## Current Status
Working on the team invitation flow. The invite email
sending is complete and tested. The invite acceptance
page (/accept-invite) is 70% done — form renders
but the token validation endpoint is not yet wired up.

## What Was Done This Session
- Built POST /api/invites endpoint (creates invite + sends email)
- Created InviteEmail template in /src/emails/InviteEmail.tsx
- Added invite record to the DB (new table: team_invites)
- Wrote unit tests for the invite creation logic (all passing)

## Immediate Next Steps
1. Build POST /api/invites/accept endpoint (validate token, add user to team)
2. Wire up the AcceptInvitePage form to call the accept endpoint
3. Handle expired token case (tokens expire after 48 hours)
4. Add invite list to team settings page (show pending invites)

## Open Blockers
- Resend (email provider) has a sending limit of 100/day on free tier.
  When we get close to launch, we need to upgrade or switch providers.
- The AcceptInvitePage currently redirects to /dashboard after acceptance,
  but if the user is new (not yet registered), they need to go to /onboarding.
  This logic isn't implemented yet.

## Key Decisions Made
- Invite tokens are UUIDs stored hashed in the DB (not plaintext)
- Invites expire after 48 hours (configurable via INVITE_EXPIRY_HOURS env var)
- A user can be re-invited after their previous invite expires

Your initial primer.md

Create this file manually when you first set up the system. It can be very simple to start:

# Project State

Project is in early development.
No sessions completed yet.
Starting fresh — see CLAUDE.md for project overview.

memory.sh — Live Git Context at Launch

A shell script that pulls fresh data from git and injects it as context at the start of every session.

What problem does this solve?

primer.md tells Claude what was planned. But between sessions, you might have manually changed files, made commits, or run into errors. Git contains all of that information — but Claude doesn't automatically look at it. memory.sh bridges that gap.

It's a shell script (a small text file of commands that your terminal can run) that you execute once at the beginning of a session. It queries your git history, finds recently modified files, checks for error logs, and assembles all of that into a single block of text that gets passed to Claude Code as initial context.

What is a shell script?

If you've never written one: a shell script is just a plain text file containing terminal commands, one per line. When you run it, your terminal executes them in order. The .sh extension signals that it's a shell script. That's all there is to it.

Creating memory.sh

Create a file called memory.sh in your project root with the following contents:

#!/bin/bash
# memory.sh — Inject live git context into Claude Code at session start
# Run this before starting a Claude Code session: bash memory.sh

echo "=== CLAUDE CODE SESSION CONTEXT ==="
echo ""

# 1. Show current git branch
echo "Current branch:"
git branch --show-current
echo ""

# 2. Show last 5 commits with short messages
echo "Recent commits (last 5):"
git log --oneline -5
echo ""

# 3. Show files changed since last commit
echo "Files modified (not yet committed):"
git status --short
echo ""

# 4. Show files changed in the last 24 hours
echo "Files changed in last 24 hours:"
git diff --name-only HEAD@{1.day.ago} HEAD 2>/dev/null || echo "No changes"
echo ""

# 5. Check for recent error logs (if your project generates them)
echo "Recent errors (last 10 lines of error.log, if it exists):"
if [ -f "error.log" ]; then
  tail -10 error.log
else
  echo "No error.log found"
fi
echo ""

echo "=== END OF SESSION CONTEXT ==="
echo "Paste the above output into Claude Code when starting your session."

How to use memory.sh

chmod +x memory.sh

bash memory.sh

Git Hook — Automatic Commit Logging

Zero-effort audit trail. Every commit automatically logged to a memory file.

What is a git hook?

Git hooks are scripts that git runs automatically at specific moments — for example, every time you make a commit. They live in the hidden .git/hooks/ folder inside your project. You can use them to automatically trigger any action when a git event occurs.

For our memory system, we use a post-commit hook: a script that runs automatically every time you run git commit. Its job is simple — log the commit message and timestamp to a file called project-memory.md. Over time, this builds a complete, automatically maintained history of everything that's been committed.

Why is this useful?

primer.md tells Claude about recent sessions. memory.sh gives Claude the last few commits. But what about older history? What decisions were made two weeks ago? What did you change last month? The git hook's project-memory.md file answers these questions with zero effort on your part.

Setting up the git hook

cd .git/hooks

#!/bin/bash
# Auto-log every commit to project-memory.md

# Get the latest commit hash (short) and message
COMMIT_HASH=$(git log -1 --format="%h")
COMMIT_MSG=$(git log -1 --format="%s")
COMMIT_DATE=$(git log -1 --format="%ci")
MEMORY_FILE="project-memory.md"

# Create the file with a header if it doesn't exist yet
if [ ! -f "$MEMORY_FILE" ]; then
  echo "# Project Memory Log" > "$MEMORY_FILE"
  echo "Auto-generated by git post-commit hook." >> "$MEMORY_FILE"
  echo "" >> "$MEMORY_FILE"
fi

# Append the new commit
echo "- [$COMMIT_DATE] $COMMIT_HASH: $COMMIT_MSG" >> "$MEMORY_FILE"

chmod +x post-commit

cd ../..           # back to project root
git add project-memory.md primer.md
git commit -m "Add Claude Code memory stack"

Putting It All Together

Your project structure after setup and the complete session workflow.

curl -sL tunerlabs.com/tools/claude-code-memory/install.sh | bash

Your project structure after setup

your-project/
├── CLAUDE.md            ← Layer 1: permanent rules (you write once)
├── primer.md            ← Layer 2: current state (Claude rewrites every session)
├── memory.sh            ← Layer 3: live git context injector (you run at session start)
├── project-memory.md    ← Layer 4: auto-growing commit log (written by git hook)
├── .git/
│   └── hooks/
│       └── post-commit  ← Layer 4: the hook that writes project-memory.md
└── src/                 ← your actual code

Your session workflow

Summary of All Four Layers