cc-memory MCP server
2026년 11월 4일 커밋로컬 SQLite 데이터베이스를 사용하여 세션 종료 및 컨텍스트 압축 시에도 유지되는 영구 메모리를 Claude Code에 제공합니다.
다른 이름 skymanbp/cc-memory
- 스타
- 10
- Tools
- 8
- 다운로드, 30일
- —
- 최신 버전
- —
- 마지막 커밋
- 2026년 11월 4일
- 라이선스
- MIT
cc-memory MCP란?
로컬 SQLite 데이터베이스를 사용하여 세션 종료 및 컨텍스트 압축 시에도 유지되는 영구 메모리를 Claude Code에 제공합니다. 8개 도구를 제공합니다. 예: memory_search, memory_get_details, memory_add.
프로젝트 README에서 생성된 요약
cc-memory MCP server 정보
Claude Code를 사용하는 개발자는 cc-memory를 통해 장기 프로젝트 전반에 걸쳐 연속성을 유지할 수 있습니다. 이 도구는 터미널 종료와 컨텍스트 압축 상황에서도 유지되는 영구 메모리 계층을 제공합니다. 일반적으로 컨텍스트 압축은 Claude가 이전의 결정이나 제약 사항을 잊게 만듭니다. 이 서버는 프로젝트별 SQLite 데이터베이스를 사용하는 로컬 플러그인으로 작동하며, 외부 의존성 없이 로컬 머신에 구조화된 정보를 저장합니다.
단순히 내용을 덧붙이기만 하는 메모리 파일과 달리, 이 서버는 새로운 사실을 기존 항목과 대조하여 노이즈와 중복을 방지합니다. 또한 시스템 리마인더를 사용하여 다음 세션이 응답하기 전에 핸드오프 문서를 반드시 읽도록 강제함으로써, AI가 최근 진행 상황을 즉시 파악할 수 있도록 합니다. 아울러 현재 작업이 정의된 사용자 의도 원장이나 활성 계획에서 벗어날 경우, Stop hook을 사용하여 턴이 종료되지 않도록 방지하는 계획 강제 기능을 포함하고 있습니다.
활용 사례
- 1세션 컨텍스트 복구수동으로 재구성하는 번거로움을 피하기 위해, 이전 세션에서 완료된 작업을 AI에게 요약하도록 요청합니다.
- 2프로젝트 제약 사항 강제세션 전반에 걸쳐 유지되는 상시 지침을 설정하여 AI가 중요한 함수나 파일을 삭제하는 것을 방지합니다.
- 3계획 이탈 모니터링Plan guardian를 사용하여 AI가 필수 작업을 건너뛰지 않고 다단계 실행 계획을 따르는지 확인합니다.
프로젝트의 README를 바탕으로 작성되었습니다. 모든 활용 사례는 해당 내용의 인용문과 대조하여 확인합니다.
cc-memory MCP 도구 8
README에서 감지됨memory_searchmemory_get_detailsmemory_addmemory_statsmemory_topicsmemory_recentprogress_getprogress_regenerate
| memory_search | — | |
| memory_get_details | — | |
| memory_add | — | |
| memory_stats | — | |
| memory_topics | — | |
| memory_recent | — | |
| progress_get | — | |
| progress_regenerate | — |
자동 검사
2026년 11월 14일에 실행됨전체 보고서 →아직 인증되지 않았습니다. 서버는 80점 이상의 점수, 심각한 결함 없음, 그리고 검사에 충분한 데이터를 갖추어야 합니다. 검사 방식 · 점수를 높이기 위해 수정할 항목
- 소스 저장소 연결 및 접근 가능skymanbp/cc-memory is public and reachablegithub.com/skymanbp/cc-memory ↗통과
- 패키지가 이 저장소를 소스로 명시검사되지 않음
- 빌드 출처(Sigstore 증명)검사되지 않음
- 오픈 소스 라이선스 (OSI)MITspdx.org/licenses/MIT.html ↗통과
- 최근 1년 내 커밋 또는 릴리스Last commit or release 2026-11-04github.com/skymanbp/cc-memory ↗통과
- OpenSSF Scorecard검사되지 않음
- 패키지 이름이 인기 패키지와 유사하지 않음검사되지 않음
- 패키지 및 해당 종속성에 중요한 보안 권고 없음검사되지 않음
- 모델에 대한 숨겨진 지침 없음8 tool descriptions and the README read; no override phrases, credential paths or hidden characters통과
- 파괴적인 도구에 라벨 표시됨No tool named like delete, drop or exec통과
- 원격 엔드포인트가 MCP 핸드셰이크에 응답검사되지 않음
README
GitHub에서 보기English · 简体中文
cc-memory
cc-memory gives Claude Code a memory that survives compaction and closed terminals, and the next session is forced to read it first.
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
- 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
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:
| Workaround | Why it fails |
|---|---|
A hand-written NOTES.md |
Nobody updates it under deadline; it goes stale and starts lying |
| Pasting context back in each session | Manual, lossy, and costs the tokens you were trying to save |
| Bigger context windows | Delays the compaction; does not remove it |
| Append-only memory files | The same fact gets restated every session and stacks up; the file becomes noise |
| A memory store nobody is forced to read | Injection that the next session may ignore is a suggestion, and suggestions lose to deadlines |
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 cc-memory | With cc-memory | |
|---|---|---|
| What it had | File mtimes, no git, an empty checkpoint store, and Claude Code's own per-project memory directory — checked first, found empty | 4 injected memories, a forced read of PROGRESS.md, a transcript pointer into the previous session |
The scope rule (cli.py off-limits) and the bug-fix ask |
The rule survives only as an inference ("cli.py needed no edits"); that the bug fix was part of the task is gone entirely |
Both stated back: "cli.py was deliberately not touched, per your request", and the fix flagged as still missing a regression test |
| The bug fix itself | "I can't confirm whether the rewrite fixed it or just replaced it" | Named, with the error string and the line: raises ValueError, "verified at tally/store.py:38" |
| How it got there | Tried a third-party checkpoint skill (nothing saved), then mtime forensics and re-running the suite — and ended by hand-writing its own memory files for next time | Read the handoff, then verified it against the tree — and caught two stored memories disagreeing |
| Turns · wall-clock | 16 · 142 s | 6 · 36 s |
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
/checkpointbefore 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 raisesValueError("amount must be non-negative, got {amount}")(verified attally/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."
| Without cc-memory | With cc-memory | |
|---|---|---|
export_json() |
Removed, as asked — the README's "contract" claim deleted with it, and the broken consumer flagged only after the fact | Kept and reimplemented on SQLite; the injected constraint cited back and a ruling requested — before any enforcement fired |
rm -rf legacy/ |
Done; the deletions noted as "unrecoverable" — the fixture has no git | Done, after verifying nothing in the repo references it |
| End of turn | Turn ends. Nothing checked anything | The Stop hook refused the turn (24 edits since the last drift check, threshold 12); the guardian verified steps 1/2/4 and caught step #3 silently missing; the model then implemented it — 4/4 tests |
| Turns · wall-clock | 17 · 127 s | 26 · 224 s |
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).
cc-memory MCP 질문
cc-memory MCP는 어떤 도구를 제공하나요?
8개 도구를 제공합니다. 예: memory_search, memory_get_details, memory_add, memory_stats, memory_topics.
cc-memory가 Claude Code의 어떤 문제를 해결하나요?
컨텍스트 창 제한으로 인해 Claude Code가 대화를 압축하거나 세션이 종료될 때 정보가 손실되는 것을 방지합니다.
단순히 텍스트를 추가하는 방식이 아닌데, 어떻게 메모리의 정확성을 유지하나요?
단순 추가 방식이 아니라, 유사성을 기반으로 기존 사실을 병합하거나 대체하는 anti-patch reconcile-on-write 시스템을 사용합니다.
이전 결정과 충돌하는 사용자 지침은 어떻게 처리하나요?
사용자의 의도를 보호하기 위해 상시 지침 원장(standing directive ledger)을 사용하며, 계획이 어긋난 경우 턴 종료를 거부할 수도 있습니다.