memory-toolkit

memory-toolkit

CLAUDE.md is for your codebase. Not for your sessions.

People stuff session state into CLAUDE.md because there's nowhere else to put it. But CLAUDE.md is static — it doesn't know what you did today, what you decided, or where you stopped. And every conversation context you build up gets destroyed at compaction.

memory-toolkit is the session layer that should have existed alongside CLAUDE.md from the start.

Built for tech leads who run multiple workstreams in parallel.

claude plugin marketplace add IlyaGorsky/memory-toolkit
claude plugin install memory-toolkit

See INSTALL.md for other methods (local clone for contributors, per-session, manual copy, existing auto-memory migration).

The problem

Three documented pain points this plugin solves:

1. Compaction silently destroys context — you're 4 hours into an auth refactor, compaction fires, and your entire conversation history is compressed into a few paragraphs by a single inference call. Claude Code restores up to 5 recently-read files (50K token budget) — if you read 30 files in those 4 hours, 25 are gone from context. Starting over takes 45 minutes and never fully recovers. (real report)

2. --resume doesn't actually restore context — claude --continue and claude --resume start fresh. All accumulated context — files read, decisions made, in-progress work state — is irrecoverable. (issue #43696)

3. Switching between tasks means re-explaining everything — each context rebuild takes 10–15 minutes. Switching between workstreams multiple times a day compounds into hours of lost time. (real report)

memory-toolkit fixes all three with hooks that fire at the right moment — not at session start.

Why not just CLAUDE.md?

CLAUDE.md is designed for your codebase — conventions, architecture, commands. It's reloaded from disk on every turn and survives compaction just fine. But it's the wrong tool for session state:

• no structure for "where did I stop", "what did I decide yesterday", "which idea did I park"
• shared and committed — personal session state and team conventions don't belong together
• static by design — it doesn't capture decisions, corrections, or context as you work
• 40KB total limit across all CLAUDE.md levels (managed + user + project + .claude/rules/*)

What compaction actually destroys is your conversation context — every file Claude read, every decision you discussed, every in-progress plan. CLAUDE.md rules survive; the session doesn't.

memory-toolkit saves the session.

What this plugin does

• Session lifecycle — start, continue, end. Handoff between sessions so you pick up where you left off, not from scratch.
• Workstreams — group related memory by project area. Switch context without losing it.
• Background watcher — runs on Haiku every 3 minutes, extracts corrections, decisions, and plans from your live transcript into notes/ as WATCH: entries. Raw observations you can see.
• Docs pipeline — two separate streams. Watcher observes automatically. When you notice something rule-worthy, mark it explicitly with DOC: notation. At /session-end, docs-reflect collects your DOC: notes and routes them to .claude/rules/<domain>.md with your confirmation. You decide what becomes a rule.
• Model recommendations — /session-start suggests Opus/Sonnet/Haiku per task type. Right model, right cost.
• Session length nudge — when the topic shifts mid-session, Claude gently suggests /session-end. Semantic signal, not a timer. Save context when a logical unit of work is done — not when compaction forces it.
• Memory API — search, filter, query memory from any skill or hook. No vector DB, no external dependencies.

How it works

Session lifecycle