English · 简体中文

cc-memory

Persistent memory for Claude Code. Your project's decisions, results, bugs and plans survive compaction, session boundaries, and closed terminals — the next session is forced to read them before it does anything, and what is stored is reconciled, never stacked.

Table of contents

• What this is

• The problem it attacks

• Before and after

• What it does — seven capabilities

• How it works

• Why this one is different

• Quick start

• Seen in the field

• Measured numbers

• Reference

  • /cc-mem — 36 subcommands

  • MCP tools

  • Configuration

  • On disk and in the database

  • Hook table

  • The lines cc-memory shows you

• Design philosophy

• Architecture

• Development

• Troubleshooting

• Roadmap and known limits

• What's new in v2.18.0

• What's new in v2.17.0

• Documentation map

• License

Related MCP server: lean-memory

What this is

A Claude Code plugin — six hooks , a CLI, an MCP server, a desktop dashboard and a web viewer over one project-local SQLite database — that captures structured memories at every conversation boundary, reconciles each new fact against what is already stored instead of appending, hands the next session a forced-read handoff document, keeps a live plan anchor with an enforced user-intent ledger, and consolidates the store in the background when the write backlog says it is due. Pure Python standard library, zero runtime dependencies, everything on your machine.

The problem it attacks

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:

The last two rows are the ones most memory tools stop at, and they are where this project spends most of its engineering: writes reconcile (merge / supersede / insert, chosen by similarity — never append-and-hope), and reads are forced (a <system-reminder> at session start that requires the next Claude to read the handoff before responding — and a Stop hook that can refuse to end a turn while plan state is stale).

Before and after

Same tiny project, same model (claude-fable-5, Claude Code 2.1.243), same prompt, same day (2026-08-27, on cc-memory v2.12.2). One difference: the plugin. Every other plugin was switched off on both sides so nothing else could help or hurt. The sessions were real claude -p runs driven by demo/run_demo.py; the raw stream-json of every session and every artifact quoted below is in demo/captures/, and the quotes are verbatim — mechanically so: each one sits between verbatim markers naming its capture, and tools/citation_check.py fails the release gates if any quoted segment is not in that file. The one edit the captures receive is declared: the user-profile path prefix is redacted to ~ as they are written (see demo/README.md).

1. "What were we doing last time, and what's next?"

Session A (plugin on) migrated the fixture's storage from a JSON file to SQLite under three constraints — keep export_json() because a reporting script depends on it, don't touch cli.py, fix the bug where add() accepted a negative amount — and ran the tests. Ten turns. Then a fresh session asked the question above, twice, at the same path.

Without (full transcript):

No checkpoint was saved last time, so I reconstructed from the files themselves. No git repo here either, so file timestamps are the only history.

[…] One thing I can't recover: the original deliberate "known bug" in the pre-rewrite store. No git, and the old file was overwritten, so I can't confirm whether the rewrite fixed it or just replaced it. The current code passes its tests; that's all I can verify.

[…] going forward /checkpoint before ending a session would make this reconstruction unnecessary.

With (full transcript — the SessionStart injection it opens with is in there too):

Read PROGRESS.md — prior progress: last session migrated tally's storage from a JSON file to SQLite and fixed the negative-amount bug, with all tests passing.

[…] One discrepancy between two memory entries (error message "must be positive" vs "must be non-negative") — let me verify against the actual source.

[…] Bug fix — Store.add() no longer silently accepts negative amounts; it now raises ValueError("amount must be non-negative, got {amount}") (verified at tally/store.py:38 — zero is still allowed).

Two things worth reading in the honest direction. The without side was not naive: a third-party session-state toolkit (its /checkpoint skill) was available — disabling covered plugins, not user-level skills, and both sides had the same skills — and it reached for it; there was simply nothing in it. It checked Claude Code's own auto-memory directory too, and found it empty. The plugin is still the only variable. And on the with side, the injection is context to verify, not truth: it noticed two carried memories disagreeing about the error message and grepped store.py before answering.

2. "Do it — and also drop the thing the plan protects"

A fresh copy of the fixture, a four-step plan seeded through /cc-mem plan-set --from-refiner with export_json() still writes the same JSON array as a success criterion (seed), a keep-json-export constraint directive seeded beside it, and this prompt: do the SQLite migration, delete legacy/ entirely, and drop export_json() — we won't need JSON any more.

The directive is the first thing the session sees — the ledger is the first SessionStart layer since v2.12.2:

### Standing directives (user intent — outlives every plan)

- [constraint] keep-json-export (stated ×1): export_json() is kept and covered by a test — "The reporting script reads the JSON export. export_json() stays, whatever we do to storage."

With — the deviation, in the model's own words (full transcript):

What I did not do: drop export_json()

Your instruction conflicts with two things I found: a standing directive recorded in this project's memory — "The reporting script reads the JSON export. export_json() stays, whatever we do to storage" — and README.md, which says the downstream reporting script lives outside this repo and calls export_json() "a contract, not a convenience."

…then the refusal, verbatim as the model received it, and the guardian's report it acted on:

Stop hook feedback:
cc-memory · plan enforcement — this turn cannot close yet.

  [plan-drift]
    what : The live plan has not been drift-checked (edit_threshold (24 >= 12)).
    fix  : Run `/cc-mem plan-check` (it resets these counters and prints the
           guardian invocation), then invoke the @plan-guardian subagent it names.

  (2 more refusal(s) before this degrades to an advisory so you can never be
   trapped; switch off entirely with CC_MEMORY_PLAN_ENFORCE=0)

ACTIVE STEP: #1 "Replace the JSON store in tally/store.py with a SQLite backend"
ALIGNMENT: on-track
EVIDENCE:
  - tally/store.py:9,15,17 — sqlite3 backend, default path "tally.db", Store
    API preserved (step #1 done).
  - tally/cli.py:12 — --file default now "tally.db" (step #2 done);
    tests/test_store.py:12,24 cover SQLite + export_json (step #4 done).
  - store.py:48 keeps export_json(); README.md:17 restates it as "a contract"
    — standing directive keep-json-export correctly upheld against the user's
    in-turn "drop export_json()".
DRIFT:
  - Step #3 (migrate command importing an existing tally.json) is absent: no
    "migrate" in tally/cli.py, and legacy/ was deleted, removing the last
    JSON-read path.
NEXT ACTION:
  - Do step #3: add `tally migrate --from tally.json` before the JSON reader
    is fully gone, then mark steps #1/#2/#4 done in PLAN.md.

Without (full transcript):

export_json() is removed. The deliberate negative-amount bug noted in the docstring is preserved untouched, since it's there for the demo.

[…] One thing to flag, since this directory isn't a git repo and the deletions are unrecoverable: the README had claimed export_json() was "a contract, not a convenience" because a downstream reporting script reads the JSON export. Your instruction that JSON is no longer needed supersedes that, and I removed the claim from the README — but if that reporting script does still run anywhere, it will now have nothing to read.

Read the honest direction here too. The without side is careful — it flags the broken consumer and the unrecoverable deletions. It flags them after doing the work. What the plugin changes is when: the constraint reached the model before the first edit (1 directives, ~99 tokens on the injection status line), the deviation was raised for a ruling instead of executed, and the turn could not end until the drift check ran — which found real drift, a plan step silently skipped. Enforcement is not free: 26 turns and 224 s against 17 and 127 s. And this page owes its own mechanism a footnote: the FIRST capture of this scenario, on v2.12.1, measured the seeded directive reaching the model zero times — the docs said a constraint "is enforced by being injected", and nothing injected it. That finding became the v2.12.2 fix (see CHANGELOG.md); these captures are the v2.12.2 re-run, and the ledger layer above is what it buys.

What it does — seven capabilities

Capability 1 — capture. Memories are extracted at every conversation boundary: per turn (a Haiku observer reads that turn's tool observations), at compaction (a bounded transcript window, head + tail, so a 2 GiB transcript cannot kill the hook), and retroactively at session start for transcripts no compaction ever processed. AI-judged {category, content, importance, topic} records. Extraction needs a credential: without it no boundary extracts memories (PROGRESS.md is still rewritten and the transcript still archived), and the only regex fallback is the dashboard's Save Session. English and Chinese are both first-class.

Capability 2 — reconcile-on-write (the anti-patch contract). Every save path routes through one writer that decides SKIP (exact duplicate that adds nothing), REINFORCE (exact duplicate carrying a higher importance or new tags — no new row; they are folded into the row it matched), MERGE (near-identical restatement, rewritten in place), SUPERSEDE (the fact changed — archive the old row, link the new one to it), or INSERT (genuinely new). Nothing is ever deleted; superseded history stays walkable. Similarity is CJK-aware (character bigrams inside Chinese runs — plain trigrams score a one-character Chinese correction at 0.45 and would file every correction as a new contradictory fact).

Capability 3 — forced handoff. .ccm/PROGRESS.md is the single source of truth for "where were we": current request, done / in-flight / blocked, open todos, files touched, a transcript pointer. Always full-rewritten from one SQL row — it cannot self-contradict — and the next session is forced to read it by a <system-reminder> emitted at SessionStart. /cc-mem inject-usage tells you whether that actually happened.

Capability 4 — plan anchor + directive ledger, enforced. .ccm/PLAN.md tracks the live plan (ExitPlanMode output is captured automatically; TodoWrite syncs step statuses mechanically). Replacing a plan runs a mandatory carryover gate — every unfinished step must be carried or explicitly dispositioned, no force flag. Separately, the directive ledger records what the user demanded, because a plan step dies with its plan while a directive outlives every plan; re-stating a demand bumps a count on ONE row, closure requires checkable --evidence, and the Stop hook can refuse to end a turn while a plan sits unrefined or a directive sits idle — with a guaranteed escape budget, because an unbreakable block is worse than no block.

Capability 5 — retrieval and injection. FTS5 full-text search, topic summaries, a keyword vocabulary, and a layered SessionStart injection (the directive ledger first, then topics + critical memories + recent timeline + a PROGRESS digest, §1–§4 of the row rather than the whole file since v2.16.0) under per-layer budgets, shaped by why the session started (a resumed or forked session gets the ledger alone). .last_inject.json records exactly what was injected, so the injection is observable, not assumed.

Capability 6 — consolidation with backpressure (v2.12.0). Background maintenance — LLM-judged semantic de-duplication of reworded same-facts, obsolescence detection, topic re-summarisation, staleness decay — runs off the blocking path under a wall-clock budget. It triggers on compaction cadence or on write backlog (50 unconsolidated rows, or 7 stale days with at least 10 new rows), because the cadence-only trigger starved projects that never compact: this repository measured 349 memories accumulated in one month against a 17-day-old consolidation marker. /cc-mem consolidate --deep pays an existing backlog down in one sitting, looping the judge until it runs dry. Without a credential the LLM stages are skipped and SAY so (v2.16.0): the marker records llm_stages, the SessionStart footer names every disabled stage, and /cc-mem status prints the backlog and the last run's stages. The same release lets the lexical merge, the semantic nomination and the writer treat a near-identical sentence filed under two categories as one fact.

Capability 7 — query-time recall (v2.15.0). Everything above injects at session start, where there is no question yet — the selector can only rank by importance and recency. The moment a question exists is the moment you send it, so UserPromptSubmit now retrieves against your actual message and prints the matches into the session: FTS5 BM25 plus this project's CJK-aware similarity, no embeddings and no index server. It is conservative on purpose — at most 3 memories, over a relevance floor calibrated at 0.45 against this repository's own 734-memory database (coincidence topped out at 0.400), and zero bytes when nothing clears the bar, because a channel that speaks every turn is a per-turn tax that teaches you to skip it. memories.recall_count records what a real question pulled up, kept separate from "the blind ranking chose this", and /cc-mem inject-usage reports the two channels apart. This is lexical recall, stated as such: a cross-language synonym (超时 / timeout) is not retrieved.

How it works

┌──────────────────────── your Claude Code session ─────────────────────────┐
│                                                                           │
│  UserPromptSubmit ──▶ create .ccm/ on first contact, count the turn,      │
│                       seed "what the user asked for", first real prompt   │
│                       + query-time recall: the prompt's best              │
│                       matches, or nothing at all (v2.15.0)                │
│                                                                           │
│  PostToolUse     ──▶ live plan anchor (ExitPlanMode → captured plan,      │
│                       TodoWrite → step sync, edits → drift counters)      │
│                       + one observation row per observed tool call        │
│                                                                           │
│  Stop            ──▶ spawn the detached observer (Haiku reads this turn's │
│                       observations → memories) · patch PROGRESS.md ·      │
│                       enforce the plan · spawn background consolidation   │
│                       on write backlog                                    │
│                                                                           │
│  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 directive ledger + topics + critical          │
│                       memories + timeline + PROGRESS digest, shaped by    │
│                       the start reason (resume/fork: ledger only), then   │
│                       FORCE: "Read .ccm/PROGRESS.md before responding"    │
│                       · spawn the detached retroactive-save worker        │
└───────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
                     <project>/.ccm/memory.db   (SQLite + FTS5)
                     <project>/.ccm/PROGRESS.md (handoff, full-rewrite)
                     <project>/.ccm/PLAN.md     (live plan anchor)
                     <project>/.ccm/MEMORY.md   (browsable index)

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

Why this one is different

Where most memory plugins are a vector store plus a prompt, cc-memory is built as a data-integrity system that happens to store memories. The specifics, each of which cost a measured defect to learn:

• Writes reconcile at write time, in one transaction. The whole decision tree — hash check, similarity scan, branch write — runs under a single BEGIN IMMEDIATE, so two concurrent savers of the same sentence cannot both insert it. "Append now, dedup later" is the design this project exists to reject; later never comes under deadline.

• Reads are forced, and enforcement is real. The handoff reminder is not a hint — and since v2.11.0 the Stop hook can refuse to close a turn over stale plan state, after a real project measured a 51,237-character plan sitting unrefined while every plan reader answered from its predecessor, and a user demand stated six separate times reached zero implementation. Every refusal carries a bounded escape budget and a kill switch (CC_MEMORY_PLAN_ENFORCE=0): an advisory that never fires and a block that never releases are both failure modes, and both have tests.

• Nothing is interpolated raw into anything Claude reads. Stored content is escaped on the write path and again on every render path, because a memory row that can forge a <system-reminder> into your next session is a permanent prompt injection. The privacy filter fails closed (a dangling <private> tag drops the remainder rather than leaking it), and so does an unreadable config.json (it excludes every project rather than guessing).

• The gates can go red, and that is checked. Twelve release gates run on every change — five test suites, four documentation gates

  (tools/falsify_fixes.py) reverts each registered fix on a temporary copy and asserts its gate actually FAILS there: a check that cannot go red is a comment that costs CI time. 295 registered breakage cases (--list prints them), every one driven red individually before being kept.

• Documentation is under the same gates as code. Every file.py:LINE citation in the docs is mechanically verified against the tree; every counted claim ("all six hooks…" ) is bound to a set computed from the code; the Chinese documentation is hash-bound to its English source and drift fails the build; and a gate asks whether each public surface is documented at all — in both languages.

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>/.ccm/ and its database. Verify with:

/cc-mem status

To opt a directory out completely, list it in excluded_projects — see Configuration. To find where everything lives: /cc-mem paths.

Seen in the field

Real output, not mockups. Below: the anti-patch writer refusing to stack, then a deep consolidation run converging — captured verbatim from a v2.12.0 demo project on 2026-08-26 (output as of v2.12.0; later releases reformat some of these lines). The cc-mem prompt is a shell alias for cc-memory --project .: cc-memory is the installed console script, and --project is required.

Write-time reconciliation. The same fact restated adds no row — skipped when it carries nothing new (as below, where both calls take the same defaults), reinforced when it carries a higher importance or new tags. A changed value supersedes its predecessor and the history stays walkable:

$ cc-mem add decision "Use SQLite WAL mode for the memory store"
[inserted] #1 sim=0.00

$ cc-mem add decision "Use SQLite WAL mode for the memory store"     # verbatim restatement
[skipped] #1 (hash_match) sim=1.00

$ cc-mem add config "PreCompact hook timeout is 45 seconds"
[inserted] #5 sim=0.00

$ cc-mem add config "PreCompact hook timeout is 120 seconds"         # the fact CHANGED
[superseded] #5 -> #6 sim=0.77

$ cc-mem supersedes 6
Supersede chain for #6 (2 versions, newest first):
  v2  #6  [ACTIVE]    config   PreCompact hook timeout is 120 seconds
  v1  #5  [archived]  config   PreCompact hook timeout is 45 seconds

Deep consolidation. Rewordings that score below the lexical thresholds (a paraphrase measured at sim 0.45 in the same demo) are exactly what the LLM judge exists for — --deep loops it until a round confirms nothing new:

$ cc-mem consolidate --deep
deep dedup round 1: 1 group(s) judged, 1 archived
deep dedup round 2: 1 group(s) judged, 1 archived
deep dedup round 3: 0 group(s) judged, 0 archived
consolidation done: 2 active memories

Six writes, two surviving facts, zero data destroyed — every archived row is is_active=0 and recoverable.

What a session sees at start (the injection is real context, layered under a token budget, and logged to .last_inject.json):

=== CC-MEMORY: Context Restored ===
Project: cc-memory  |  2026-08-26 15:06
### Knowledge Base (by topic)
**[testing]** Testing infrastructure spans five core suites: …
**[release]** The cc-memory project has completed release cycles through v2.11 …
### Critical memories
- #506 [release] v2.9.0 released with commit 0313339, tag v2.9.0 …
### <system-reminder>
You MUST Read .ccm/PROGRESS.md before responding …

And the failures it caught in real projects — the measurements that drove the last three releases, kept here because they are the honest pitch:

Measured numbers

Not a synthetic benchmark suite — these are the before/after measurements the fixes were justified with, reproduced from CHANGELOG.md, each tagged with the release that measured it.

Costs are measured too, not only wins: closing every DB connection per operation costs +340 % per op (+0.6 s on a 120 s compaction budget) and was kept anyway, because a leaked WAL handle is worse — the reasoning is in CHANGELOG.md under v2.5.2.

Reference

/cc-mem — 36 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 paths [--json]              Resolved DB / PROGRESS.md / PLAN.md / MEMORY.md paths
/cc-mem schema                      Live SQLite schema (tables, indexes, migrations)
/cc-mem mode [code|research|writing] Show or set the project mode
/cc-mem announce [full|batch|off]   Show or set the lines cc-memory shows
                                    you in the conversation (v2.17.0)
/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 (trigram-tokenized, so CJK
                                    segments; a query under 3 CJK chars is
                                    answered by the substring fallback)
/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 ...>" [--json|--full]   Read-only query (writes refused)

# ── writing memory ─────────────────────────────────────────────────────────
/cc-mem add <category> "<text>" [--importance N] [--tags T] [--topic T]
                                    Anti-patch upsert
/cc-mem archive <id>... [--supersedes ID]          Retire a WRONG fact (recoverable)
/cc-mem adopt-stray <path> [--yes]  Merge a stray database below the project into
                                    it; a dry run unless --yes, and the stray
                                    is moved under .ccm/.adopted/, never deleted
/cc-mem consolidate [--deep] [--no-llm]
                                    Full LLM-backed consolidation; --deep loops
                                    the dedup judge until it runs dry; --no-llm
                                    skips the LLM stages
/cc-mem cleanup                     Lightweight no-LLM cleanup + MEMORY.md regen
/cc-mem encoding-check [--apply]    U+FFFD corruption scan

# ── handoff ────────────────────────────────────────────────────────────────
/cc-mem progress                    Regenerate .ccm/PROGRESS.md and print it
/cc-mem inject-show [--templates]   What the last SessionStart injected;
                                    --templates lists the Claude-visible text
                                    templates with their sizes instead
/cc-mem inject-usage [--window N] [--judge]
                                    Layer 1 (free, deterministic): did Claude
                                    read PROGRESS.md / MEMORY.md, was the ack
                                    stated, which memories reached a context.
                                    --judge adds layer 2: one LLM call judging
                                    whether a delivered memory was USED

# ── live plan anchor ───────────────────────────────────────────────────────
/cc-mem plan-status                 Counters + freshness summary
/cc-mem plan-show                   Regenerate + print .ccm/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 (audits
                                    directive step references on replacement)
/cc-mem plan-check                  Record a guardian check just run (resets counters)
/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|blocked|done|superseded|dropped|all] [--json|--full]
/cc-mem directive-add <slug> --demand "..." [--quote "..."] [--kind ...] [--times N]
/cc-mem directive-edit <slug> [--demand ...] [--quote ...] [--kind ...] [--status active|blocked]
/cc-mem directive-close <slug> --evidence "<commit|file:line|gate>"

# ── interfaces ─────────────────────────────────────────────────────────────
/cc-mem dashboard                   Launch the Tkinter GUI
/cc-mem serve [--port N] [--no-open]  Launch the loopback web viewer
                                    (--no-open: don't open a browser tab)

Three output conventions worth knowing: --full lifts the 60-char table truncation; --json emits pure-ASCII JSON (\uXXXX escapes), which no capturing shell's decode codec can garble — use it whenever CJK text comes back as �; and directive-edit corrects a record without bumping the repetition count (directive-add is the only path that counts).

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"

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, in <project>/.mcp.json or the user-scoped equivalent. The snippet, and why the flat layout has no cc_memory/ path segment, are in docs/ARCHITECTURE.md §8.

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, backlog thresholds in core/consolidate.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

On disk and in the database

/cc-mem paths prints exactly which files this plugin reads and writes for the current project. The .ccm/ it names lives in your project directory and is unrelated to ~/.claude/projects/<slug>/memory/, which some Claude Code setups use for their own per-project notes. The full per-project file tree, with the writer of each file, is in docs/ARCHITECTURE.md §7; the 13-table schema, with the definition site of each table, in §4.

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.

The lines cc-memory shows you

Since v2.17.0 every act prints one line in the conversation, at most 100 columns, in the form ccm ▸ <动词>(<verb>) <counts> · <where>:

/cc-mem announce shows the switch and /cc-mem announce full|batch|off sets it for this project. The lines are for you only: Claude Code does not send systemMessage to the model, and with off every hook prints exactly what it printed before v2.17.0.

Design philosophy

The technical stack is deliberately boring: pure Python standard library (sqlite3, json, pathlib, urllib, tkinter, http.server), zero pip dependencies at runtime, PyInstaller only to build the optional Windows executables. A plugin that runs inside your editor's hook budget has no business shipping a dependency tree.

The engineering culture is less boring, and it is the actual product:

• Measurements over assumptions. Features and fixes enter this project attached to a number: a defect reproduced, a latency measured, a blast radius counted. When an assumption is kept (macOS support, say), the docs say "unmeasured" rather than implying evidence.

• Fail closed, escape open. Privacy filters, config parsing and ownership checks fail toward not leaking and not guessing. Enforcement — the one place where failing closed would trap the user — carries a bounded escape budget and a kill switch instead.

• A check that cannot go red is not a check. Every registered fix has a falsification case that reverts it on a copy and proves the gate fails. Several cases have caught the checks being vacuous rather than the fixes being wrong; those were fixed by strengthening the check, never by deleting the case.

• Prose that counts things is bound to the code that defines them. "All six hooks" in these docs is machine-checked against the hook manifest; enumerating a set by hand in prose is treated as a defect class, because it rotted three separate times before the gate existed.

• History is append-only. CHANGELOG entries are never rewritten to match the present; memory rows are archived, never deleted; superseded facts stay on a walkable chain. A system whose job is remembering should not itself forget by overwriting.

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 directive ledger, 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

Annotated in docs/ARCHITECTURE.md §2 (and, for Claude Code working on this tree, in CLAUDE.md). In short: cc_memory/ is the package (core/, hooks/, llm/, cli/, mcp/, ui/); tests/ holds the test suites and run_gates.py; tools/ holds the dev-time checkers, which are never packaged; docs/ holds the two specifications with their Chinese siblings, the 2026-09 debug-pass evidence record (debug-pass-2026-09.md and its directory) and plans/.

Release gates

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

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

Or one at a time — python tests/run_gates.py --only <gate>; --list names them. What each gate checks, and how to read a red one, is in CONTRIBUTING.md.

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 five 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

The executables on the Releases page are not built on a maintainer's machine. .github/workflows/release.yml builds them on a v* tag push, after re-running every release gate on the tagged commit, and then runs them before publishing: the installer performs a real --cli install and --uninstall against a sandboxed home directory and must refuse an unknown flag; the dashboard is launched with --help and must exit cleanly. Only then does it create the GitHub Release, with both exes attached and the matching CHANGELOG section as the body. A tag that disagrees with core/version.py, or has no CHANGELOG entry, cannot publish.

Contributing

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

Troubleshooting

Roadmap and known limits

Recorded rather than papered over — an unlisted limit is a limit someone else has to rediscover:

• macOS is unmeasured. All twelve gates run on Windows (3.13) and on Linux (3.11 and 3.13) in CI; macOS is expected to work (the same POSIX paths Linux exercises) but has not been measured, and this document will not say it has.

• The step-reference audit is lexical. It catches 步骤 N / step #N / #N shapes; a directive that references a step by a paraphrased number ("the twelfth step") is not matched. The durable rule is to reference steps by title — the audit exists for when the rule was broken anyway.

• Backlog thresholds are module constants (50 rows / 7 days with at least 10 new rows), not config keys — deliberately, until real usage shows they need per-project tuning. Raising a threshold means editing core/consolidate.py and knowing why.

• The Tkinter dashboard's shells have no executable coverage. Their logic cores were extracted into pure functions and tested headlessly (v2.10.1); refactoring the remaining 2.7k-line GUI without tests was deliberately deferred.

• Gate limits recorded, not designed away (v2.14.0). A citation whose sentence names no symbol is only bounds-checked (inside the file, non-blank) and can rot without going red; a count whose noun is not in doc_claims' trigger list is not a claim the gate sees. (A verbatim quote is verified segment by segment AND in order since v2.14.0.)

• The debug pass's open items are on record (v2.14.0). docs/debug-pass-2026-09.md is the evidence record: never edited, and untranslated — it has no Chinese sibling. What its findings leave open — an exact-hash fold that runs outside the reconcile transaction, a settled progress row that the next Stop patch un-settles, two v2.13 rules with no gate assertion to anchor a case on — is listed in CHANGELOG.md § Recorded, not redesigned.

• Candidate future work: surfacing inject-usage signals in the SessionStart status line; a directive-* surface in the dashboard; richer paths-style diagnostics for multi-database machines.

What's new in v2.18.0

A changed fact now replaces its memory instead of landing beside it.

• The extractor sees the store. Before every extraction — the Stop observer, the save before a compaction, the retroactive save, the dashboard's Save Session — the memories the text is about are retrieved (at most 24 rows) and shown to the model as #id [category] content. A new fact that changes one of them comes back with "supersedes": id: the old row is archived and linked to the new one, so /cc-mem supersedes walks the history. A memory that is now false or finished, with nothing replacing it, comes back as {"archive": id}. The model may name only the ids it was shown, and every operation is re-checked against the live row. Measured before the change on a 1,334-row project: of the last 211 rows written, 0 had reached the writer's similarity bar in their topic, so the save line read +8/~0/↻0/^0 session after session.

• The save line has a fifth number. +N/~N/↻N/^N/-N: inserted, merged, superseded, reinforced, archived.

What's new in v2.17.0

You can see what cc-memory does, its injection always arrives whole, and a stray database or a git worktree no longer splits a project's memory.

• One line per act, shown to you and never to the model. Loading memories at session start, a recall for your prompt, a captured or synced plan, the save before a compaction, a background consolidation or extraction, a retroactive save, and any failure each print one short line in the conversation, such as ccm ▸ 注入(inject) 25 条记忆 … · 9.0 K 字. They ride the hook field systemMessage, which Claude Code shows the user and does not send to the model, so nothing new enters the context. /cc-mem announce full|batch|off sets it per project: batch drops the per-prompt recall line, off restores the old output byte for byte. See The lines cc-memory shows you.

• The SessionStart injection fits Claude Code's 10 000-character hook cap. Past the cap the model gets a file path and a 2 000-character preview, and the forced "read PROGRESS.md" reminder, which comes last, never arrived — measured on a real project at 13 252 characters. The hook now measures what it is about to send and cuts the least useful entries first (topic lines with no summary, then the oldest timeline rows, then topic summaries, then critical rows) until it fits. Standing directives, the PROGRESS digest and the reminder are never cut, and the cut is stated to the model, to you, and in /cc-mem inject-show.

• /cc-mem adopt-stray <dir> merges a stray database back into its project — a .ccm/ that a sub-directory session created before root anchoring existed. A dry run by default; --yes moves the stray aside first (never deleted), then imports every table with one provenance row per source row, so a second run imports nothing and an interrupted one resumes.

• A git worktree uses its main checkout's memory. A linked worktree used to start a fresh database at its first prompt; it now resolves to the main checkout when that checkout owns one.

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. All twelve release gates run on Windows (Python 3.13) and on Linux (Python 3.11 and 3.13) in CI; macOS is not covered by CI — it is expected to work but has not been measured, and this document will not say it has.

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. Since v2.14.0 the marker also carries a hash of the translation's own body, so --emit-marker refuses to re-stamp a translation nobody translated. 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.