Claude Memory Kit

The memory plugin for Claude Code. Your agent remembers every client, every brief, every decision — across sessions. Three lines to install, nothing to maintain.

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

Install it into a repository you already have:

/plugin marketplace add awrshift/claude-memory-kit
/plugin install memory-kit@memory-kit
/memory-kit:setup

Then work as usual, and type /memory-kit:close-session when you're done. That's the whole loop. Free — it runs on your existing Claude Pro or Max subscription and calls nothing else.

Upgrading later takes two steps, and the second one needs the FULL plugin@marketplace identifier — the bare name resolves to nothing and the CLI answers Plugin "memory-kit" not found:

claude plugin marketplace update memory-kit     # refresh the catalog
claude plugin update memory-kit@memory-kit      # then the plugin itself

Restart the session to apply. Your repository is untouched by an upgrade — memory, handoffs and knowledge live in your repo, never in the plugin — so /memory-kit:setup does not need re-running.

The problem

Every session starts from zero. Yesterday you locked the brand voice; today you explain it again. Last week you found the right angle; this week you can't reconstruct how. The first ten minutes of every session go to re-explaining what Claude already knew.

Built for people running many projects or clients — one install per repository, each with its own accumulated memory, all with the same working discipline. (The story: 1000+ sessions, 12 months in production, one operator.)

What the three lines do

/memory-kit:setup reads what your repository already has, then proposes — never writes first:

• the memory layers it is missing (.claude/memory/MEMORY.md, context/handoffs/, knowledge/);
• who owns memory: the kit, or Claude Code's built-in auto memory. Running both means two writers and two truths, so the kit makes you pick (why it matters);
• permission rails (deny on forced pushes and secret reads, ask on the destructive classes);
• the .gitignore lines — private memory by default, shared if your team wants it.

Nothing else changes in your repo. Your CLAUDE.md is yours; the kit never writes to it.

Starting from zero instead of an existing project? Make an empty folder, run claude in it, and use the same three lines.

[!TIP] Say /memory-kit:tour after setup — Claude walks you through the system using your own files.

On v5 (the clone-the-repo layout)? Your memory files stay where they are: migration in 4 steps.

Who it's for

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

A hook injects, before you type anything: your hot cache, the handoff the previous session left, memory-health stats, and the knowledge index. You do nothing — you just see "here's where we left off" and continue. (After a /compact, it re-injects what compaction dropped.)

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". Hooks run silently: compaction is blocked until state is written, and an edit to an existing test file has to be confirmed.

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

Say /memory-kit: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

flowchart LR
    T([you talk]) --> H[".claude/memory/MEMORY.md<br/>hot cache · dated one-liners<br/>180 lines / 32 KB / 3000 chars"]
    H -->|"/close-session"| N["context/handoffs/*.md<br/>one note per session"]
    H -->|"same pattern on 3+ dates<br/>and you say yes"| K["knowledge/concepts/*.md<br/>facts + rationale"]
    K -->|"stable, mechanical"| R[".claude/rules/*.md<br/>always / never"]
    N -->|"newest one injected"| S([next session])
    H -->|"injected in full"| S

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

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. It 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.
• The memory is actually in context. v6 injects the hot cache itself at session start, and re-injects it after compaction. (v5 only measured it while claiming it was always loaded — a year-long silent failure, found by asking "prove it's in context", not by reading the code.)

Multiple clients

Two shapes, both supported. One repo per client — install the plugin in each, and every client gets its own memory with the same discipline. Or one workspace, many client folders: /memory-kit:setup offers projects/<name>/ and experiments/<name>-YYYYMMDD/, shared layers (memory, wiki, rules) load for all of them, and per-client materials load when you name one.

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

Hooks and skills

Four hooks run silently, all inside the plugin — nothing to maintain in your repo. One injects your memory and the working agreement at every session start (and after each compaction), one blocks compaction until state is saved, one asks before an existing test gets edited, one logs the close.

Everything else is a skill, and skills cost nothing until you invoke them:

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).

v5.2 makes the loop self-improving. Every nontrivial diff passes an automated code review before merge; every confirmed finding is logged by class, and a class that recurs three times is promoted into the cheapest layer that prevents it forever — a lint rule, a line in an agent definition, a review-brief line. Rules that stop firing get dropped. Your review process compounds instead of repeating itself.

And when what you're building is a user-facing product, the QA layer puts agents on the other side of the screen: /qa-sweep fans out qa subagents over the running app — five adversarial lenses (user-flow · edge-state · honesty · contract · ux-critique), parallel isolated browsers, findings that must carry machine-checkable evidence — and nothing becomes a ticket until the integrator reproduces it. A calibration ladder (seeded-defect recall runs, brief edits kept only on a measured delta) keeps the lenses sharp.

All of it ships in the same plugin — the agents and skills are simply there when you invoke them. The one always-on piece is optional and deliberately tiny: /memory-kit:setup offers to drop a ~20-line orchestration.md into .claude/rules/, which is what makes the invariants binding rather than advisory. Depth stays in the plugin's reference/, read on demand. Distilled from hundreds of real multi-agent sessions in the maintainers' production repos.

FAQ

What's inside

This repository is the marketplace; the plugin is what you install.

.claude-plugin/marketplace.json   ← the catalog (one plugin)
plugins/memory-kit/
  .claude-plugin/plugin.json      ← the manifest
  context/identity.md             ← the working agreement, injected every session
  hooks/                          ← session-start · pre-compact · protect-tests · session-end
  skills/                         ← close-session, memory-audit, system-audit, setup, tour,
                                    session-review, second-opinion, qa-sweep
  agents/                         ← executor · recon · idea-validator · qa
  templates/                      ← what /memory-kit:setup scaffolds into YOUR repo
  reference/                      ← depth, read on demand (fact-check, parallel dev,
                                    doc governance, decisions log, review loop, QA protocol)
docs/                             ← architecture · changelog · contributing

In your repository the kit owns only state: .claude/memory/MEMORY.md, context/handoffs/, knowledge/, and — if you want them — projects/<name>/ for real client work and experiments/<name>-YYYYMMDD/ for hypotheses (rough OK, distil on close, then delete).

Full architecture: docs/ARCHITECTURE.md Version history: docs/CHANGELOG.md Contributing: docs/CONTRIBUTING.md Open decisions: docs/DECISIONS.md · Diagram state: docs/ASSETS.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. Installed per project — each repository accumulating its own memory, rules, and knowledge base while the working discipline stays identical. That's exactly who it fits best: automators and consultants running many clients — three lines 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. The operator's own write-up lives at awrshift.com.

Help

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

License

MIT — see LICENSE.