English · 简体中文

Table of contents

• The problem
• How it works in 60 seconds
• Quick start
• Feature index
  • 1 · Memory capture
  • 2 · Memory quality — the anti-patch contract
  • 3 · Session handoff — PROGRESS.md
  • 4 · Plan and intent — PLAN.md and the directive ledger
  • 5 · Search and retrieval
  • 6 · Interfaces
  • 7 · Privacy and safety
  • 8 · Reliability engineering
• Reference
  • /cc-mem — 32 subcommands
  • cc-memory-plan — the plan queue
  • MCP tools
  • Configuration
  • Per-project files
  • Database schema
  • Hook table
• Architecture
• Development
• Troubleshooting
• What's new in v2.11.1
• Documentation map
• License

The problem

Claude Code compacts a conversation when the context window fills. Whatever
was in the discarded turns is gone: the decision you made three hours ago, the
benchmark number you measured, the bug you already fixed once, the constraint
you stated and had to state again. Sessions that simply end — terminal closed,
laptop shut — lose the same thing, silently.

The usual workarounds do not survive contact with a long project:

cc-memory attacks all four. It captures structured memories at every
conversation boundary, reconciles each new fact against what is already
stored instead of appending, and emits a <system-reminder> at session start
that requires the next Claude to read the handoff document before it
responds.

How it works in 60 seconds

┌──────────────────────── your Claude Code session ────────────────────────┐
│                                                                          │
│  UserPromptSubmit ──▶ create memory/ on first contact, count the turn,    │
│                       seed "what the user asked for" on turn 1           │
│                                                                          │
│  PostToolUse     ──▶ live plan anchor (ExitPlanMode → captured plan,      │
│                       TodoWrite → step sync, edits → drift counters)      │
│                       + one observation row per observed tool call        │
│                                                                          │
│  Stop            ──▶ Haiku reads this turn's observations and writes      │
│                       memories · patches PROGRESS.md · enforces the plan  │
│                                                                          │
│  PreCompact      ──▶ sync leg  : extract from a bounded transcript window │
│                       → reconcile → FULL-REWRITE PROGRESS.md → archive    │
│                       async leg: LLM consolidation, off the blocking path │
│                                                                          │
│  SessionStart    ──▶ inject topics + critical memories + timeline, then   │
│                       FORCE: "Read memory/PROGRESS.md before responding"  │
└──────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
                     <project>/memory/memory.db   (SQLite + FTS5)
                     <project>/memory/PROGRESS.md (handoff, full-rewrite)
                     <project>/memory/PLAN.md     (live plan anchor)
                     <project>/memory/MEMORY.md   (browsable index)

Everything is project-local. memory/ lives inside your repository, is
git-ignored by a .gitignore cc-memory writes itself, and never leaves your
machine except for the extraction call to Anthropic (which you can scope with
<private> tags, or switch off per-project entirely).

Quick start

Install — marketplace (recommended)

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

Install — from a local checkout

git clone https://github.com/skymanbp/cc-memory.git
claude /plugin marketplace add ./cc-memory
claude /plugin install cc-memory

Install — standalone, no marketplace

python cc-memory/cc_memory/ui/installer.py          # GUI
python cc-memory/cc_memory/ui/installer.py --cli    # headless

Or download cc-memory-installer.exe from
Releases on Windows.

Then

Nothing. Per-project initialization is automatic: the first message you send in
a project creates <project>/memory/ and its database. Verify with:

/cc-mem status

To opt a directory out completely, list it in excluded_projects — see
Configuration.

Feature index

1 · Memory capture

2 · Memory quality — the anti-patch contract

The differentiator. Most memory tools append; appending is what turns a memory
store into noise.

3 · Session handoff — PROGRESS.md

4 · Plan and intent — PLAN.md and the directive ledger

Two different things, deliberately kept apart: a plan step is a unit of
execution and dies when the plan is replaced; a directive is a unit of user
intent and outlives every plan.

5 · Search and retrieval

6 · Interfaces

7 · Privacy and safety

8 · Reliability engineering

Reference

/cc-mem — 32 subcommands

Inside Claude Code (path-agnostic — the wrapper resolves the plugin root):

# ── state and health ───────────────────────────────────────────────────────
/cc-mem status                      Full health check (hooks, DB, API key, PROGRESS)
/cc-mem stats                       Memory counts + supersede-chain count
/cc-mem schema                      Live SQLite schema (tables, indexes, migrations)
/cc-mem mode [code|research|writing] Show or set the project mode
/cc-mem summary                     Latest session summary
/cc-mem sessions                    Compaction history with archive paths
/cc-mem observations                Raw PostToolUse rows awaiting extraction

# ── reading memory ─────────────────────────────────────────────────────────
/cc-mem search "<query>"            FTS5 search
/cc-mem list [category]             Recent memories, optionally by category
/cc-mem topics                      Topic summaries
/cc-mem keywords                    Project vocabulary by frequency
/cc-mem supersedes <id>             Walk a memory's supersede chain
/cc-mem sql "<SELECT ...>"          Read-only query (writes refused)

# ── writing memory ─────────────────────────────────────────────────────────
/cc-mem add <category> "<text>" [--importance N]   Anti-patch upsert
/cc-mem archive <id>... [--supersedes ID]          Retire a WRONG fact (recoverable)
/cc-mem consolidate                 Full LLM-backed consolidation
/cc-mem cleanup                     Lightweight no-LLM cleanup + MEMORY.md regen
/cc-mem encoding-check [--apply]    U+FFFD corruption scan

# ── handoff ────────────────────────────────────────────────────────────────
/cc-mem progress                    Regenerate memory/PROGRESS.md and print it
/cc-mem inject-show                 What the last SessionStart injected
/cc-mem inject-usage                Did Claude actually read PROGRESS.md / MEMORY.md

# ── live plan anchor ───────────────────────────────────────────────────────
/cc-mem plan-status                 Counters + freshness summary
/cc-mem plan-show                   Regenerate + print memory/PLAN.md
/cc-mem plan-set --raw "<text>"     Capture a raw plan, mark needs_refine
/cc-mem plan-set --raw-file FILE    Same, from a file
/cc-mem plan-set --from-refiner     Store structured JSON from stdin
/cc-mem plan-check                  Reset drift counters + emit guardian hint
/cc-mem plan-replan                 Re-arm needs_refine on the stored raw
/cc-mem plan-clear --reason "<why>" Drop the active plan (reason required if unfinished)

# ── directive ledger ───────────────────────────────────────────────────────
/cc-mem directive-list [--status active|done|superseded|dropped|all]
/cc-mem directive-add <slug> --demand "..." [--quote "..."] [--kind ...] [--times N]
/cc-mem directive-close <slug> --evidence "<commit|file:line|gate>"

# ── interfaces ─────────────────────────────────────────────────────────────
/cc-mem dashboard                   Launch the Tkinter GUI
/cc-mem serve [--port N]            Launch the loopback web viewer

Full per-subcommand semantics: commands/cc-mem.md.

Outside Claude Code:

# NOTE: $HOME, not ~. Bash expands a tilde BEFORE parameter expansion and does
# not rescan the result, so a ~ stored inside a variable stays a literal.
M="python $HOME/.claude/hooks/cc-memory/cli/mem.py --project ."   # flat install
$M status
$M search "auth flow"

cc-memory-plan — the plan queue

A task queue in the same database, distinct from the live plan anchor.

P="cc-memory-plan --project ."       # or python .../cli/plan.py --project .

$P add "Task A" "Task B" "Task C"    # append drafts
$P list                              # show the queue
$P reorder <id> <position>           # move a task
$P evaluate                          # draft → evaluating
$P set-eval <id> "<verdict>"         # record a feasibility verdict
$P approve --all                     # evaluating → ready
$P exec --next                       # ready → executing, print the plan text
$P done <id> "<result>"              # → done
$P fail <id> "<why>"                 # → failed
$P skip <id> "<why>"                 # → skipped
$P status                            # queue summary
$P clear                             # drop done/failed/skipped

Flow: draft → evaluating → ready → executing → done | failed | skipped.
exec spawns nothing — it flips status and prints the plan text plus the
done command to run afterwards. Every subcommand that names an id resolves it
within --project first and exits 1 on an unknown or foreign id.

MCP tools

8 tools over JSON-RPC 2.0 stdio. The server forces UTF-8 with LF newlines on
both stdin and stdout itself — no PYTHONUTF8 / PYTHONIOENCODING env block
is required.

Marketplace / dev checkout — nothing to do. .claude-plugin/plugin.json
ships the registration inline.

Standalone install — register by hand. Note the absent cc_memory/ path
segment in the flat layout:

// <project>/.mcp.json, or the user-scoped equivalent
{
  "mcpServers": {
    "cc-memory": {
      "command": "python3",
      "args": ["<HOME>/.claude/hooks/cc-memory/mcp/server.py"]
    }
  }
}

Configuration

config.json in your install root — flat: ~/.claude/hooks/cc-memory/config.json;
marketplace / dev checkout: <plugin-root>/cc_memory/config.json.

Every key in this file is read by code. Inert tunables were deleted rather
than left in place, because editing one that does nothing looks like it does
something.

Everything else is a module constant, documented in notes.removed_keys:
writer thresholds in llm/memory_writer.py, injection budgets in
hooks/session_start.py, the idle-reorg interval in core/idle.py, the
per-mode observation skip-list in core/modes.py, the web viewer's default
port in ui/web_viewer.py. MCP registration is the mcpServers block in
.claude-plugin/plugin.json, not a config key.

Environment variables

Per-project files

<project>/memory/
├── memory.db                   SQLite (WAL) — the source of truth
├── MEMORY.md                   browsable index, refreshed after every write
├── PROGRESS.md                 handoff; full-rewritten from the `progress` row
├── PLAN.md                     live plan anchor; from the `plan_active` row
├── .gitignore                  written by cc-memory; migrates on existing installs
├── .last_save.json             status + trigger of the last PreCompact
├── .last_inject.json           what SessionStart injected (observability)
├── .last_consolidation.json    interval marker for the async leg
├── .consolidation.lock         prevents overlapping async workers
├── .pre_compact_attempt.json   start marker; survives ⇒ the last run was killed
├── .plan_raw.md                last raw ExitPlanMode capture
├── .plan_history/              append-only archive of replaced / cleared plans
├── sessions/YYYY/MM/           per-session archives
└── topics/                     reserved for per-topic exports

Database schema

12 tables in one project-local SQLite file:

Hook table

Six hook commands across five Claude Code events, declared in
hooks/hooks.json:

Hook contract, never violated: hooks never write to stderr (Claude Code renders
stderr as error UI), never raise, and always exit 0.

Architecture

Full detail in docs/ARCHITECTURE.md
(简体中文). The three hard contracts are specified in
docs/CONTRACTS.md (简体中文):

• Anti-patch contract — how a write reconciles
• Handoff contract — the PROGRESS.md spec
• Plan contract — PLAN.md, the carryover gate, the subagents

Two install layouts, both supported. A marketplace / dev checkout keeps the
nested <plugin-root>/cc_memory/… shape. The standalone installer lays the
package FLAT under ~/.claude/hooks/cc-memory/ — core/, hooks/, llm/,
cli/, mcp/, ui/ directly under it, with no cc_memory/ path segment.
Any code or documentation that probes for an install must accept both.

Development

Repository layout

cc-memory/
├── .claude-plugin/          plugin.json (+ inline mcpServers) · marketplace.json
├── .github/                 CI running every release gate · issue + PR templates
├── agents/                  plan-refiner.md · plan-guardian.md
├── commands/                cc-mem.md — the /cc-mem slash command
├── hooks/hooks.json         hook declarations (6 commands / 5 events)
├── skills/                  ccm-load/ · save-memories/
├── cc_memory/               the Python package
│   ├── core/                db · extractor · consolidate · plan · progress · privacy
│   │                        modes · roots · atomic · markers · textsim · auth · …
│   ├── hooks/               _entry (shared ladder) + the six hook entry points
│   ├── llm/                 ccl_backend · memory_writer · parse
│   ├── cli/                 mem.py · plan.py
│   ├── mcp/                 server.py
│   └── ui/                  installer · dashboard · web_viewer
├── docs/                    ARCHITECTURE.md · CONTRACTS.md (+ .zh.md siblings)
├── scripts/                 build_exe.py — PyInstaller build
├── tests/                   4 suites + run_gates.py (one command, every gate)
├── tools/                   citation_check · doc_claims · contracts · falsify_fixes · i18n_check
├── CLAUDE.md                project instructions for Claude Code
├── CHANGELOG.md · README.md · README.zh.md · LICENSE · pyproject.toml

Release gates

Ten gates, all pure stdlib — no pytest, no pip dependencies. Run them all with
one command:

python tests/run_gates.py           # runs all 10, prints a table, exits nonzero on any red
python tests/run_gates.py --list    # show what each gate is

Or individually:

python -m compileall -q cc_memory tests tools
python -c "import tomllib,pathlib;tomllib.loads(pathlib.Path('pyproject.toml').read_text(encoding='utf-8'))"
python tests/smoke_test.py                    # end-to-end + the three doc gates + version agreement
python tests/test_plan_carryover.py           # the carryover gate
python tests/test_surfaces.py                 # installer · MCP · web viewer · opt-out · anchoring
python tests/test_directive_enforcement.py    # the directive ledger + Stop enforcement
python tools/i18n_check.py                    # translation drift
python tools/citation_check.py                # every file.py:LINE citation in the tracked docs
python tools/doc_claims.py                    # prose counts vs the sets computed from the tree

Two more scripts are not gates, and are the ones to reach for when you
doubt a gate:

python tools/contracts.py       # print what the code currently says each set contains
python tools/falsify_fixes.py   # revert each registered fix on a COPY, assert its gate goes RED

Tests must use tempfile directories only and must remove them: all four
suites redirect HOME/USERPROFILE and TMPDIR/TEMP/TMP into a
sandbox before importing the package, assert Path.home() really moved, and
tear the sandbox down in a finally. An uncleanable leak is a test failure.

Build the executables

pip install pyinstaller
python scripts/build_exe.py
# → dist/cc-memory-installer.exe
#   dist/cc-memory-dashboard.exe

Contributing

See CONTRIBUTING.md. Security reports: SECURITY.md.

Troubleshooting

What's new in v2.11.1

v2.11.0 shipped the enforcement engine with zero coverage — and shipped with
a RED gate. The directive ledger added three CLI subcommands and
commands/cc-mem.md was never updated, so tests/smoke_test.py failed; and
because it is one sequential function, that first failing assert also hid the
one below it. Nothing caught either, because "run all ten gates" was a sentence
in a markdown file rather than an executable. It is one now:
python tests/run_gates.py, plus CI.

Six defects in the path that can refuse your turn, each reproduced first:

• The escape budget could never release. write_marker never raises — it
  returns False — so the except OSError guarding the "cannot count, so do
  not block" case was dead code. On any temp directory the marker layer
  refuses, the hook blocked forever: measured [1,1,1,1,1,1,1,1] over eight
  consecutive Stops. An unbreakable block is worse than no block.
• A stored directive reached Claude as a live authority marker. The block
  reason is fed back as a decision payload — higher authority than PROGRESS.md
  — and was the one renderer in its module that never escaped. Now escaped on
  the way in and the way out.
• A refusal's stdout was not a JSON document, because a status line printed
  first.
• A cleared plan enforced forever — the hook tested a row that
  plan-clear deliberately keeps as a tombstone.
• A just-stated directive was reported idle for N turns, because idleness
  came from the plan's counter rather than the directive's own history.
• Re-stating a directive erased its demand and quote — the single operation
  the ledger exists for.

Also: concurrent directive writes are serialised; the install health check now
derives its required-module list from the hooks' import graph instead of a
hand-kept list that had gone stale three times; and a .gitignore pattern that
silently took .github/ to zero tracked files is gated. Nine new falsification
cases, every one driven RED individually — two ran GREEN first, and the
checks were fixed rather than the cases.

Every earlier release is in CHANGELOG.md, which is the
single history of this project — this README documents what the software is,
not what it used to be.

Requirements

• Python 3.8+ — standard library only, zero runtime dependencies
• Claude Code with hooks support
• Tkinter only for the desktop dashboard (the CLI, MCP server and web
  viewer do not need it)
• PyInstaller only for building the executables
• Windows: python3 must resolve to a Python 3 interpreter (see
  Troubleshooting)

Developed Windows-first; cross-platform by construction and exercised on POSIX
paths throughout.

Documentation map

English is the canonical skeleton; each *.zh.md is a drift-tracked sibling
bound to a normalised hash of its English source, and tools/i18n_check.py
turns the suite red when one drifts. Memory content is language-agnostic —
only the project's own documentation follows this convention.

License

MIT © skymanbp

_{Keywords — Claude Code plugin · Claude Code memory · persistent memory
for LLM agents · agent long-term memory · context window management ·
conversation compaction recovery · session handoff · AI coding assistant memory
· Anthropic Claude · MCP server · Model Context Protocol · SQLite FTS5 memory
store · retrieval for coding agents · prompt-injection hardening · pure-stdlib
Python plugin.}