How I Built a Memory System for Claude Code and Open-Sourced It

#ai #programming #opensource #productivity

You open Claude Code. You work for an hour — refactoring, debugging, building something real. You close the terminal. Next morning you type claude and... it has no idea what happened yesterday.

I've been there about a thousand times. Literally.

After 1000+ sessions building content pipelines, multi-agent systems, and GEO optimization tools with Claude Code, I got fed up with the context amnesia. So I built a system that fixes it. And today I'm open-sourcing everything.

Repo: awrshift/claude-starter-kit

The Problem Nobody Talks About

Claude Code is powerful. It reads your codebase, runs tests, writes code that actually works. But it has one brutal limitation — no persistent memory between sessions.

Every time you start a new session, you're back to square one. The agent doesn't remember:

What you worked on yesterday
Which architectural decisions you made
What patterns keep causing bugs
Where you left off

So you burn 10-15 minutes every session just re-loading context. Multiply that by 5 sessions a day, 5 days a week — that's over 6 hours a month wasted on "hey Claude, remember when we..."

Most devs I've talked to handle this with a fat CLAUDE.md file. That works until it doesn't. Once your project grows past 3 weeks of work, a single instruction file can't hold everything you need.

What I Built Instead

The starter kit gives Claude Code three things it doesn't have out of the box:

1. Persistent memory — a .claude/memory/ directory with three files that survive between sessions. MEMORY.md stores long-term patterns ("this API always returns pagination headers"). CONTEXT.md is a quick-orientation card ("currently working on auth module, tests are failing"). snapshots/ keeps session backups so nothing gets lost when the conversation compresses.

2. Session continuity — a next-session-prompt.md file that acts as a cross-project hub. Each project gets its own tagged section, so multiple Claude Code windows can work on different projects in parallel without stepping on each other.

3. Hooks that protect you — a session-start.sh that shows memory summary + git status when you open a session. And a pre-compact.sh that fires before Claude compresses your conversation — it forces the agent to save context before anything gets lost.

The Four-Layer Context System

Not everything needs to load every time. The kit uses a pyramid:

L1 — Auto (every session): CLAUDE.md + domain rules + MEMORY.md. This is the agent's identity and accumulated knowledge. Loads automatically, always.

L2 — Start (session start): next-session-prompt.md + CONTEXT.md. Orientation layer — what project am I in? What's next? What happened last time?

L3 — Project (on demand): projects/X/JOURNAL.md. Each project has one file for tasks, decisions, and status. The agent reads it when you start working on that project.

L4 — Reference (when needed): Docs, snapshots, anything deep. Pulled only when relevant — keeps token usage low.

The pyramid means Claude always knows who it is (L1), quickly orients itself (L2), and dives deep only when needed (L3-L4). No wasted context window.

Three Skills Included

The kit ships with three global skills that install to ~/.claude/skills/ on first run:

Gemini — get second opinions from Google's Gemini models. Different model family = different blind spots. I use this for prompt stress-testing and hypothesis falsification.

Brainstorm — a 3-round adversarial dialogue between Claude and Gemini. Round 1: diverge. Round 2: challenge weak points. Round 3: converge on one action. For architecture decisions it's worth every token.

Design — full design system lifecycle from URL to production CSS. Extract colors, compute palettes, generate tokens, audit HTML, run visual QA loops.

How to Get Started

cp -r claude-starter-kit my-project
cd my-project
claude

That's it. On first launch, Claude reads CLAUDE.md, sees the setup instructions, and configures everything automatically — installs skills, sets up memory, initializes git, cleans scaffolding.

No manual configuration. You can start working immediately.

What Changes After a Week

The real value isn't day one. It's day seven.

By then, MEMORY.md has 15-20 verified patterns from your work. Things like "this ORM silently drops null values" or "user prefers 2-space indentation". The agent stops asking and starts knowing.

next-session-prompt.md has a clean thread of where each project stands. You switch between three projects? Each one picks up exactly where it left off.

The pre-compact.sh hook has saved your context at least twice — you didn't even notice because it just worked.

Lessons from 1000 Sessions

The agent won't use memory unless you tell it to. Claude Code has an auto-memory directory, but in my experience it stays empty. The system-level mechanism exists, but without explicit instructions in CLAUDE.md, the agent rarely writes to it. That's why the starter kit includes both the files and the instructions.

Multi-project safety matters more than you think. Two Claude Code windows editing the same file = silent data loss. The PROJECT tags solve this — each window only edits its own section.

Pre-compact hooks are essential, not optional. When Claude's conversation gets too long, it compresses the history. If your context wasn't saved before compression, it's gone.

Skills should live globally, not per-project. I tried per-project skills. Then I had 8 copies of the same Gemini skill, each slightly out of date. Global install works much better.