cc-memory

cc-memory

Claude Code persistent memory plugin (v2.2) — anti-patch reconcile-on-write, forced PROGRESS.md handoff, live PLAN.md anchor with plan-refiner / plan-guardian subagents, FTS5 search, AI-judged extraction with Haiku + local Ollama fallback.

What it solves

Claude Code compresses (compacts) conversations when the context window fills up, causing information loss: decisions, results, todos, and project knowledge disappear. Conversations that end normally (terminal closed) also lose context.

cc-memory captures structured memories at every conversation boundary AND forces the next session to read a handoff document before it starts work.

What's new in v2.1

• Anti-patch writes. Every save goes through llm.memory_writer.upsert_smart, which MERGES (overwrites a similar memory in place), SUPERSEDES (archives the old, links the new via supersedes_id), or INSERTS — chosen by trigram-Jaccard similarity. No more stacked duplicates. See docs/MEMORY_RULES.md.
• Forced handoff via PROGRESS.md. memory/PROGRESS.md is the single source of truth for session handoff, always full-rewritten from a SQL row, never appended. SessionStart emits a <system-reminder> block that requires the next Claude to Read it before responding. See docs/HANDOFF_PROTOCOL.md.
• Auto-fresh MEMORY.md. Regenerated after every write — no more 50-day-stale index files.
• Idle reorg. Stop hook runs lightweight cleanup every 5 turns (no LLM).
• Clean subpackage layout. cc_memory/{core,hooks,llm,cli,mcp,ui}/.
• One installer, one skills location, one version number. Removed .claude/skills/ duplicate, removed the third copy of save-memories, removed dual installers.

What's new in v2.2

• Live plan anchor (memory/PLAN.md). Captures ExitPlanMode output (or user-supplied raw plans) into a structured, step-tracked document that survives session boundaries. TodoWrite syncs step statuses mechanically; sensitive Bash calls (git push, deploys, ...) flag drift. See docs/PLAN_PROTOCOL.md.
• Plugin-shipped subagents. plan-refiner normalises raw plans into JSON; plan-guardian checks alignment when drift counters trip. Definitions live in agents/ and are auto-discovered after install.
• /cc-mem dashboard subcommand: launches the Tkinter GUI without needing to know the plugin install path.

Installation

Via marketplace (recommended once published)

claude /plugin marketplace add skymanbp/cc-memory
claude /plugin install cc-memory

Local marketplace from this repo

claude /plugin marketplace add /path/to/cc-memory
claude /plugin install cc-memory

Standalone exe (Windows)

1. Download cc-memory-installer.exe from Releases
2. Double-click → Install Plugin → Configure Hooks → done.

From source

git clone https://github.com/skymanbp/cc-memory.git
python cc-memory/cc_memory/ui/installer.py        # GUI
# or
python cc-memory/cc_memory/ui/installer.py --cli  # CLI

The installer:

1. Copies the subpackage tree to ~/.claude/hooks/cc-memory/.
2. Adds the 5 hook entries to ~/.claude/settings.json.
3. Auto-detects + upgrades any v2.0 flat-layout install.

Per-project initialization is automatic — the first user message creates <project>/memory/ and the SQLite DB.

Architecture at a glance

Hooks (registered in ~/.claude/settings.json):

  UserPromptSubmit ─► turn count + first-prompt seeding of PROGRESS.md
                      auto-init memory/ on first contact

  PostToolUse     ─► insert one observation row per tool call (no LLM)

  Stop            ─► Haiku observer extracts memories from this turn
                     patch_progress(files_touched=...)
                     idle reorg every 5 turns

  PreCompact      ─► Haiku extracts memories from the full transcript
                     ALL writes go through llm.memory_writer.upsert_smart
                     FULL-REWRITE memory/PROGRESS.md from SQL row
                     archive session, regen MEMORY.md, maybe LLM-consolidate

  SessionStart    ─► inject context (topics + critical + timeline + PROGRESS preview)
                     emit FORCED <system-reminder>: "Read PROGRESS.md FIRST"
                     retroactive save of unsaved prior JSONLs

Per-project state lives at <project>/memory/:

memory/
├── memory.db                SQLite WAL, see core/db.py for schema
├── MEMORY.md                auto-generated index, refreshed every write
├── PROGRESS.md              full-rewrite from `progress` row at every Stop+PreCompact
├── .last_save.json          status from last PreCompact
├── .gitignore               excludes DB + sessions
├── sessions/YYYY/MM/        per-session archives
└── topics/                  reserved for future per-topic exports

Memory model