Claude Memory Kit

The starter kit for Claude Code — persistent memory edition. Your Claude remembers everything. Every client, every brief, every decision. Across sessions. Zero setup.

"I wake up already knowing where we left off." — the agent this kit builds. Read its day.

The problem

Every time you open Claude, it forgets everything. Yesterday you locked the brand voice. Today you have to explain it again. Last week it helped you find the right campaign angle — this week you can't remember exactly how.

The first 10 minutes of every session go to re-explaining what Claude already knew.

Memory Kit fixes this. Free. Runs on top of your Claude Pro or Max subscription.

Built for automators and consultants running many clients: one clone of the kit per client or vertical — each with its own accumulated memory, all with the same working discipline. (The story: 1000+ sessions, 12 months in production, one operator.)

Quick start

git clone --depth 1 https://github.com/awrshift/claude-memory-kit.git my-projects
cd my-projects
claude

--depth 1 skips the kit's own development history (~170 MB of old graphic revisions) — your clone starts its own history from here anyway.

That's it. Claude sets itself up and asks a couple of questions (your name, what you're working on).

[!TIP] Say /tour after install — Claude walks you through the system using your own files.

Before / after

How a session works

Three steps. That's the entire workflow:

1. Open a session — Claude wakes up already knowing where you left off

Claude auto-loads context: the handoff (the note the previous session left), memory health stats, your projects, the knowledge index. You do nothing — you just see "here's where we left off" and continue.

2. Work as usual — the habits run without you asking

Talk to Claude. Write copy. Do research. Lock the tone. When something worth keeping comes up, Claude saves it as a dated one-liner and tells you "saved". Safety hooks run silently — they prompt a save every ~50 messages and physically block context compaction until state is written.

3. Close the session — the note to tomorrow's you

Say /close-session. Claude doesn't just dump logs — it audits: "noticed you rejected em-dashes on three different dates — make it a tone-of-voice rule?" You say "yes", it writes. Then it leaves a note for tomorrow-you. Tomorrow's session opens with that note already loaded.

Where memory lives

Four places, each answering a different question. Claude writes all of them — you only talk.

A pattern's journey: noticed in conversation → saved as a dated line in MEMORY → repeats on 3+ dates → Claude proposes promotion → your "yes" → becomes a knowledge article or a rule, and the raw lines are pruned. Observation → candidate → law. You approve every step.

Why it doesn't rot (v5)

Memory systems don't usually die loudly — they rot quietly: a "current state" file that froze three weeks ago but still looks authoritative; a memory file that grew so dense it's unreadable. v5 is built around the failure modes we hit in real long-running use:

• Three size caps on MEMORY.md (180 lines / 32 KB / 3000 chars per line), checked by a hook at every session start. Three, because line count alone lies — content can densify into ever-longer lines while the line count stays flat. When a cap trips, the session opens with an audit prompt instead of silently growing.
• Handoffs instead of a rolling status file. One immutable note per closed session; the newest one is injected automatically. A note that says its date can't pretend to be current.
• Stale-reference detector. Every session start, file paths mentioned in memory are checked against disk; anything that moved or vanished is flagged. A memory that references dead files is the #1 way agents confidently act on outdated beliefs.
• The header rule. The top of MEMORY.md is "current state in 2-3 sentences", replaced at every close — never a stack of "previous session" paragraphs.

Multiple clients

Each client = their own folder. Shared layers (rules, memory, wiki) load for every project. Per-project materials load when you name the project.

Say "we're working on Nestlé" — Claude unloads other clients and loads that scope only.

Hooks and operators

Five hooks run silently — they make state survive compaction and crashes, and they watch the memory caps. Two slash operators give you direct control: /close-session (the end-of-session ritual) and /tour. Power-user extras sit in .kit/advanced/ for when you want them: hygiene and usage-stats commands, an optional day-by-day journal layer (/close-day), and an orchestration layer for building with subagents (executor/recon/idea-validator agents, /session-review, /second-opinion).

Everything in plain text files. No databases. No external services. git checkout restores anything.

Agent-orchestrated work (opt-in)

When you use the kit to BUILD things — software, agent systems, research pipelines — there's a next level: your agent stops doing everything in one thread and starts orchestrating agents. The main session designs and decides; executor subagents build to a decided spec in isolated git worktrees; recon gathers facts read-only; idea-validator attacks the design from a fresh context. The integrator merges, re-runs the gates on the merged tree, and treats every subagent report as INPUT — never as a fact.

Two skills close the loop: /session-review (an adversarial review of the session's work by independent reviewers before it sets) and /second-opinion (cross-check a high-stakes answer before committing to it).

All of it is one cp set away: .kit/advanced/orchestration-layer/. Distilled from hundreds of real multi-agent sessions in the maintainers' production repos.

FAQ

Yes. You talk to Claude in plain language. "Read the client brief and propose three newsletter topics" — works. Install is one command. You never edit the memory files yourself — that's the kit's first rule: you only talk, Claude writes.

The kit itself is free, open source. You need a Claude Pro or Max subscription (which you probably already have). No additional cost.

Yes. Everything is stored on your computer in plain text files. Nothing leaves. Your personal layers — MEMORY.md and the session handoffs — are gitignored by default, so they stay private even if you push the repo (the kit creates your MEMORY.md from a template on first run). knowledge/ articles and .claude/rules/ ARE tracked — they're your curated wiki, meant to live in the repo; keep the repo private (or prune them) before publishing it anywhere.

Yes. On install, tell Claude you already have a project — it analyses it and integrates.

Nothing breaks. Safety hooks save progress automatically every ~50 messages and before any context compaction. /close-session is the cherry on top — the deliberate audit where patterns get promoted to permanent knowledge and the handoff note gets written.

The kit's tracked files revert with one git checkout. Your private layers (MEMORY.md, handoffs) are gitignored, so git can't restore those — but the hooks checkpoint them continuously, and if MEMORY.md ever disappears the session-start hook recreates it from the template. If you want your private memory versioned too, remove those two lines from .gitignore in your own (private) clone.

It's an opt-in layer now: .kit/advanced/close-day-layer/ — one cp command enables it, and it composes with the v5 core (journal + handoffs together). It left the default because in long-running use the chronicle was the layer that silently rotted when you skipped days. Full story: that folder's README.

Clone v5 into a new folder and tell Claude: "I have a v4 kit at <path>, help me migrate". Your memory entries, knowledge articles, rules and projects carry over as-is; the mechanical steps are in .kit/CHANGELOG.md § Migration.

What's inside

README.md               ← You are here
LICENSE                 ← MIT
CLAUDE.md               ← Agent's brain — who it is, how it works
SKILL.md                ← Metadata for skill aggregators
projects/               ← Real client / product folders (tasks + materials)
experiments/            ← Sandbox for hypotheses + prototypes (date-named)
knowledge/              ← Knowledge base (grows over time)
context/handoffs/       ← One note per closed session (private by default)
.claude/                ← Kit core: memory, hooks, skills, rules
.kit/                   ← Docs about the kit ITSELF (architecture, changelog,
                          contributor guide) + advanced/ (opt-in layers: power
                          commands, the daily-journal layer, the orchestration
                          layer for multi-agent development)

projects/ vs experiments/ — projects/<name>/ for real client work (polished, indefinite lifetime, patterns promote to rules); experiments/<name>-YYYYMMDD/ for hypotheses and prototypes (rough OK, days-to-weeks lifetime, distill on close, then delete). Full spec: experiments/README.md.

Full architecture: .kit/ARCHITECTURE.md Version history: .kit/CHANGELOG.md Contributing: .kit/CONTRIBUTING.md

Origin

This is not a template written in an afternoon — it's an architecture distilled from 1000+ real sessions over 12 months of continuous daily Claude Code work, by one operator, across very different verticals: marketing, sales, lead generation, business analysis, research & development, and shipping production code side-by-side with backend and frontend engineers.

One person. One agent architecture. Cloned per vertical — each clone accumulating its own memory, rules, and knowledge base while the working discipline stays the same. That's exactly who it fits best: automators and consultants running many clients — spin up a clone per client, and memory keeps every engagement scoped, accumulated, and instantly resumable.

Everything here survived that year of production use — including the scars: the parts that quietly rotted (the daily chronicle, the rolling status file) were retired, and what remains is what kept earning its place.

Help

Issues and PRs welcome. See .kit/CONTRIBUTING.md.

License

MIT — see LICENSE.