Claude Memory Kit

Built-in memory decides what to remember. This one asks.

Claude Memory Kit is a Claude Code plugin that gives your coding agent a memory made of plain text files in your own folder. Session two opens with "you were on Nestlé, the client hates em-dashes, next step: the Q3 brief" — without you explaining anything again. The agent notes small facts as dated lines and tells you; nothing becomes a rule or a knowledge article until you say yes. No database, no service, no API key. An independent project, not made or endorsed by Anthropic.

Optional second half, for people who delegate to subagents: a method that ships with it — specs written as files before work starts, a subagent's report treated as a claim until checked, review findings that turn into checks.

On this page: How it works · Install · What is inside the plugin · What it creates in your folder · The method · Why not built-in memory · Privacy and cost

1. You talk. "We're working on Nestlé." "The client hates em-dashes." You never open a memory file.
2. The agent writes. Something worth keeping becomes one dated line in MEMORY.md, and the agent tells you ("saved", with the line). The work itself (backlog, specs, research, decisions) goes into that client's own folder, projects/<client>/.
3. You close the day. Say "we're done for today". The agent looks for patterns across dates ("you rejected em-dashes on four different days, make it a rule?"), writes what you approve, and leaves a handoff note.
4. Tomorrow starts already knowing. At the next session start a hook loads the memory, the newest handoff and the knowledge index. Nothing becomes a rule without your yes, and every line carries its date, so a stale fact looks stale.

Inside the folder you work in, in Claude Code:

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

setup reads what the folder already has and proposes before writing anything; your CLAUDE.md stays yours. Git is optional. To upgrade later: claude plugin marketplace update memory-kit, then claude plugin update memory-kit@memory-kit (the full id is needed), and restart the session. Upgrades never touch your files.

A plugin install hides its file tree, so here is all of it.

The guards for git and secrets block the action if they crash or time out, instead of letting it through (Claude Code 2.1.295 or later; older versions accept the setting but let the action through). Each guard names its opt-out variable. In a folder that never ran setup, the hooks write nothing. Shared code in hooks/lib/: cmdparse.py (one shell-command parser for every guard), rails.py (permission settings facts), stale-refs.py (finds paths in memory that no longer exist), legacy_hooks.py (spots a project's own copy of a kit hook), statefs.py and state.sh (write the kit's state files safely: never through a symlink, never outside the project).

All are named /memory-kit:<name>, and each one also triggers from plain words. Until a skill runs, only its one-line description sits in the context.

A plugin cannot install rules, so setup offers these and copies them only on your yes.

• Memory files: templates/MEMORY-TEMPLATE.md, templates/HANDOFF-TEMPLATE.md, templates/workspace/knowledge-index.md.
• Per project: templates/workspace/project/README-TEMPLATE.md (the project's map and workflow tier), BACKLOG-TEMPLATE.md, SPEC-TEMPLATE.md (the contract an executor builds to), ASSUMED-SPEC-TEMPLATE.md (an executor's recorded override, owed your ratification).
• Other: EXPERIMENT-TEMPLATE.md and experiments-README.md (a sandbox for throwaway work), ONBOARDING-BACKLOG.md (a first day in five tasks), and the four document templates (pr.md, changelog.md, release-note.md, postmortem.md).
• Scripts: scripts/quiet.sh (runs a noisy command, keeps the full log in a file, prints a summary), scripts/permission-probes.sh (checks that your permission rules stop what they should); system-audit carries collect.sh, gates.py and usage.py.
• The working agreement: context/identity.md, injected at every session start. It is the kit's only always-on instruction text, about 1.6k tokens.

plugins/memory-kit/
├── hooks/        hooks.json · session-start.py · pre-compact.sh · protect-tests.py · guard-git.py
│                 guard-secrets.py · guard-zsh-split.py · session-end.sh · lib/ · tests/
├── skills/       close-session · memory-audit · system-audit · setup · tour · session-review
│                 second-opinion · qa-sweep · document · code-sync
├── agents/       executor · recon · idea-validator · qa
├── reference/    the depth docs above
├── templates/    memory · rules · workspace · project
├── scripts/      quiet.sh · permission-probes.sh
└── context/      identity.md

Only state, and only after setup:

your-folder/
├── .claude/memory/MEMORY.md     hot cache: dated one-liners, capped at 180 lines / 32 KB / 3000 chars a line
├── context/handoffs/            one note per session; the newest is loaded at the next start
├── knowledge/                   the wiki: one article per settled topic, written after your yes
├── .claude/rules/               always / never, only what you promoted
└── projects/<client>/           each client's own documents: README (the map), BACKLOG, plans/, research/

flowchart LR
    T([you talk]) --> H["MEMORY.md<br/>dated one-liners"]
    H -->|"/close-session"| N["handoffs/<br/>one note per session"]
    H -->|"same pattern on 3+ dates<br/>and you say yes"| K["knowledge/<br/>facts + rationale"]
    K -->|"stable, mechanical"| R["rules/<br/>always / never"]
    N -->|"newest one loaded"| S([next session])
    H -->|"loaded in full"| S

A pattern's path: a dated line, then (seen on 3+ dates, with your yes) a knowledge article, then (stable and mechanical) a rule. Memory vs paperwork: what the agent learned is shared across your work; what the work produced belongs to one client's folder. Say "now IKEA" and the agent reads that folder only.

The main session designs and decides; subagents build or gather facts from a spec written as a file before anyone starts. The nine invariants in templates/rules/orchestration.md, in plain words:

1. A report from a subagent or reviewer is input, not a fact. Re-run the check, read the line, look at one real output yourself.
2. Subagents build to a decided spec file and never redesign; a deviation is reported, not absorbed.
3. A value with no named source stops the build as an owed decision; nothing is invented.
4. The main session alone writes memory and project documents, merges, and re-runs every check on the merged result.
5. A failing test means the code is wrong, not the test.
6. Reviewers are judged on merits, never by counting votes.
7. A subagent is resumed only for a short follow-up; new work gets a fresh one with a brief that points at files.
8. Every number in a report comes from a script or command shown next to it.
9. Scope, anything others will see, irreversible data changes and spending are yours to decide; technical choices are the agent's, explained as "decision, why it is correct, what would prove it wrong".

A spec also carries three lines before it is handed over (reference/spec-depth.md): a depth pass (what a top expert in the field would do that nobody asked for), a practice line (outside facts checked against official sources today, with the date), and a review line (who reviews it, by stake). Failure branches are written before the run, and success is judged by what reaches the user, not by a counter.

Claude Code ships its own auto memory, on by default. It is effortless, and it lives outside your folder.

Running both means two writers and two truths, so setup asks you to pick one.

• The kit itself sends nothing. No hook or script opens a network connection; all are readable Python or shell. Claude Code sends what it reads, memory included, to the model, as with any file in the conversation.
• Private by default. The hot cache and handoffs are gitignored, so they stay local even if you push. The knowledge base and rules are tracked: keep the repository private or prune before publishing. Working from two machines or with a teammate? Say so at setup and the hot cache gets committed instead.
• Forgot to close the session? Nothing breaks: the next session still opens with your memory. You lose that session's handoff note and the pattern audit.

Built and used daily by one operator since March 2026, across marketing, research and product work, and the method behind several production agent setups. Layers that quietly rotted were retired (a daily journal, a rolling status file, a staging layer), and CI now checks on every push that the memory actually reaches the model and that this page lists every part of the plugin.

A 68-second recording of a real session: demo video. Tell me how your first week went: open a note.

Architecture · Claude Code facts · Changelog · Contributing · Open decisions · MIT, see LICENSE.