consolidate-memory

Give your next Claude Code session the lessons your last one earned.
A plugin that turns work history into verified, reusable memory — checked against the
current code, kept behind an explicit recall cue, and shared only with the projects you choose.

_{Current release v0.4.79 · what changed}

🧠 Why · 🚀 Quick start · 🌌 Dashboard · 🕸️ Memory network · 🧭 Commands
🔬 How it works · 🔒 Privacy · 🛠️ Contribute

🧠 The two costs it removes

An assistant with no durable memory pays the same two bills forever: it re-derives conclusions it already reached, and it trusts an index that quietly rotted while the code moved on. Both are charged in context window and in your attention — on every session, in every repository, whether or not you noticed.

One explicit dream settles both. It proposes candidate lessons from the session, checks each one against the live files, symbols, and commit history, keeps a short recall cue pointing at the ones that survived, and hands you a report of exactly what changed and why. A claim with no supporting evidence is flagged or dropped.

When this happens…	What a dream helps you retain
You fix a subtle bug, then meet it again months later	The verified cause and a recall cue that points to the explanation
The README, agent instructions, and memory disagree	A correction grounded in the live files and commit history
Several repos use the same tools	Relevant shared lessons, absorbed into each enrolled project's own memory
Client work and personal experiments must stay separate	Explicit trust domains, with narrowly granted exceptions through groups
The memory index keeps growing	Measured context cost, stale-fact review, and proposals to move detail out of the always-loaded tier
You repeat the same multi-step checks across projects	Evidence for a reusable command or skill, proposed for your decision

Useful when you maintain several repositories, return to work after a break, or keep re-explaining the same testing conventions, architectural decisions, and hard-won gotchas.

How this relates to Claude Code's native memory

Claude Code's native memory supplies project instructions and recall, and this plugin builds on that rather than replacing it.

	Native memory	With consolidate-memory
Scope	One project at a time	One project, plus a governed cross-project store
A lesson's status	Recorded as written	Survives a claim-vs-code check, or is flagged/dropped
Growth	Index grows until someone trims it	Context cost measured each cycle; stale facts surfaced for review
Sharing	—	Explicit trust domains; sharing only through named, revocable grants
Audit	Session history	An inspectable cycle record and a local HTML archive

The scripts use Python's standard library; the agent performs the reasoning and source checks.

🚀 From install to your first dream

Requires: Claude Code with plugins enabled, python3 3.8+ on PATH, and a POSIX environment (Linux, macOS, or WSL). The SQLite is the one bundled with Python — the dialect uses UPSERT, so it must be ≥ 3.24 — and no system sqlite3 binary is involved.

Nothing to install, and nothing to enable. The scripts are stdlib-only, so there are no runtime packages. Native Auto-Memory is not required: the plugin is self-contained, and a disabled auto-memory is reported as a supported skip, never a failure. git is optional — dream scope degrades without it.

Check the environment first with /cm-doctor after installing. Exit 0 = clean; exit 2 = a named check FAILed — fix it before dreaming.

In Claude Code:

/plugin marketplace add Zenetusken/consolidate-memory
/plugin install consolidate-memory@zenetusken-plugins

Use the Git owner/repo form above: relative plugin paths do not resolve from a direct URL to marketplace.json.

Then, after a useful work session:

dream

Or say “consolidate my memory.” The pass gathers candidate lessons, checks the current code, shows the proposed changes, and records the decisions. Its final output links to your local HTML report.

Start with one project. Local consolidation works without enrollment. To share between two repos, run /cm-connect ../other-repo; it surveys both, presents the enrollment plans for your confirmation, offers a first shared fact, and syncs both. It uses the personal domain for unenrolled projects; use /cm-domain for a different boundary. An existing domain is never silently switched.

Tip

Ask /cm-doctor to show the resolved stores, enrollment, and registry health. UNENROLLED LOCAL-ONLY means local memory works and cross-project sharing is off.

🌌 See what the system actually kept

Every dream closes with Nocturne, the memory observatory: a self-contained HTML archive, rendered from the same structured cycle record as the terminal summary. Open the generated file in a browser; it needs no server or internet connection.

What do you want to know?	Where to look
What did this dream accomplish?	Dream summary — the recorded outcome, verified claims, observed changes, and attention items, with the complete narration as one passage of italic paragraphs.
Who holds this lesson, and who may receive it?	Memory network — unfolds from fleet → domains → projects. Pick a fact or group in View to see its holders or permitted members.
What changed over time?	Memory activity — captured decisions and reads on two aligned timelines; select a dream for its summary, then Open this dream.
What needs attention, and what supports the result?	Verification & health — exceptions first. Each disclosure names its status; open it for readable findings and evidence.
Why was a lesson changed or kept?	Changes & decisions — each action, lesson, and reason, with sources, declared files, and captured diffs.

The header keeps the memory-index trajectory and budget projection; historical fact counts and cadence remain in the activity table. Missing observations stay explicitly Not captured, and a dream's save time is never presented as a live check. Token figures are estimates, approximately characters ÷ 4. The complete saved data is always available in the page's Inspect the complete captured cycle record disclosure.

Pick a theme

Theme	Character
◉ Deep Field (default)	A near-black observatory canvas with hairline structure and luminous evidence. Colour marks data, never decoration.
● Nocturne	The original midnight-and-glacier palette, still shipped and still the archive's namesake.
◒ Original	The warm espresso palette the plugin shipped before Nocturne.
○ Light	A bright, high-contrast working theme.
◐ System	Follows your OS preference.

Whichever you pick, the archive retains filtering, sorting, previous/next navigation, compact mode, keyboard controls, reduced motion, print support, and complete captured records. Archive returns to the dream list; unavailable previous/next actions are disabled. Narration, charts, and evidence use the section width, with mobile layouts that keep long text readable.

Try the fictional preview: HTML archive · dashboard network SVG · design and validation notes. Download the HTML and open it locally at #sel=7; GitHub shows its source rather than running it. All screenshots and preview data use fictional projects.

🕸️ Build a network with boundaries

Imagine maintaining a product, a research lab, and shared developer tools on one machine. You want lessons to travel where they apply, while each area keeps its own memory boundary.

The VLAN analogy, made concrete

Network idea	Memory-system equivalent	What it actually means
VLAN / isolated segment	Domain	A project joins one domain by operator grant. Ordinary shared facts stay inside it.
Selected endpoints with a routing rule	Group	A named recipient set can narrow delivery within a domain or bridge specific projects across domains.
Traffic selected by purpose	Scope and stack relevance	user-global applies throughout the authorized audience; stack-general also requires a matching detected stack.
Endpoint fetching an update	Pull	A receiving project absorbs admitted facts on its next dream or /cm-sync.
Disconnected endpoint	Unenrolled project	Local memory only; it cannot create or pull shared canonicals.

This is a local memory-delivery policy, not an IP network or an OS security sandbox. Domains and groups do not create network sockets or synchronize machines.

One common topology, four delivery cases

The example has work (atlas-api, atlas-web, team-docs), research (eval-lab, model-notes), and tools (release-tools, dotfiles). scratch stays unenrolled.

Example fact	Intended audience	Who stays outside
A verified account/tooling convention, user-global in work	All three work projects	research, tools, and scratch
A Python lesson, stack-general, no group	Matching Python projects in the fact's home domain	Nonmatching projects and other domains
A lesson addressed to api-contract	Only atlas-api and atlas-web, subject to scope/relevance checks	Even team-docs, despite sharing their domain
A lesson addressed to release-kit	atlas-api, eval-lab, and release-tools, subject to scope/relevance checks	Every other repo; their domains are not opened wholesale

Groups narrow the audience. A fact naming release-kit reaches eligible members of that group; it does not also broadcast to all of work. A group has a home domain, and a canonical fact can target only groups created in that same home domain. Multiple named groups form a recipient union; stack relevance still applies.

Set it up in Claude Code

1. Create the boundaries. In each repo, use /cm-domain and specify work, research, or tools. Review each enrollment plan. Leave scratch unenrolled.
2. Grant the bridges. Use /cm-group to create release-kit in work and add atlas-api, eval-lab, and release-tools. Create api-contract in work and add atlas-api and atlas-web. The command presents each grant for confirmation.
3. Share a verified lesson. In atlas-api, run /cm-share "<one claim sentence>". When asked about delivery, choose a group or the whole domain. Review the exact fact and recipient exclusions before confirming.
4. Absorb and inspect. In each recipient, run /cm-sync, or wait for its next dream. Run /cm-network to inspect recorded holdings, costs, and utility.

For exact CLI syntax, a complete enrollment/group walkthrough, revocation behavior, and troubleshooting, see the network guide.

Important

Permission is not delivery. A recipient may not have pulled yet, may not match the stack, or may be held at its memory budget ceiling. The dashboard distinguishes physical holdings, registry holder counts, and group permissions. These measure different things; a partial count alone does not establish failed synchronization.

🧭 A command for each intent

These are the packaged commands available to marketplace users:

Intent	Command	Behavior
Consolidate this project's memory	dream	Full six-phase pass
Connect two projects	/cm-connect <other-repo>	Survey, confirmed enrollment, optional share, sync both
Show or change a trust boundary	/cm-domain	Show, enroll, move, or unenroll
Manage selected recipients	/cm-group	List, create, add, remove, or delete groups
Author one shared lesson	/cm-share "<claim>"	Verify, deduplicate, show, then write on confirmation
Absorb approved shared memory	/cm-sync	List, pull, and harvest usage; reports held facts
Inspect the fleet	/cm-network	Read-only topology, costs, and recall utility
Diagnose resolved paths and grants	/cm-doctor	Read-only setup, registry, and environment inspection
Manage retained plugin data	/cm-data	Inventory, export, compact, or scoped purge

The SessionStart beacon can add one factual reminder when memory is behind. It is read-only, never pulls, and stays silent on failure. Dreams run only when requested.

🔬 How a lesson becomes memory

flowchart LR
    A["0 · Locate stores"] --> B["1 · Orient & pull"]
    B --> C["2 · Gather claims"]
    C --> D["3 · Verify sources"]
    D --> E["4 · Review & consolidate"]
    E --> F["5 · Prune, measure & report"]

Loading

Verification uses live files, symbols, git history, and documentation consistency. Unverifiable claims are flagged or dropped. The proposal makes authoring and irreversible changes reviewable; already-approved shared facts can be pulled earlier in the pass. Every decision lands in the cycle record.

A pass that reaches the end with a gating duty still unfilled fails loudly at the terminal render instead of rendering as silence, naming the field and its remedy.

Put detail where it costs the least

Tier	What belongs there	When it loads
Always loaded	Concise project instructions and the MEMORY.md index	At session start
Recall	A useful description in the index pointing to a detailed fact	The cue loads first; the body is read when relevant
On demand	Full explanations, references, and repository documents	When the work calls for them

The index target is 1,500 estimated tokens; the pull ceiling is approximately 3,840. CLAUDE.md has a 4,000-token target and is edited conservatively. Scope decides who can use a fact; tier decides how it enters context.

Repeated work can become a reusable workflow

The distill step looks for recurring command templates and command chains, including how many days and projects supplied the evidence. It can propose a command or skill. Existing coverage, weak evidence, or ordinary repeated commands can produce a “create nothing” verdict; that decision is recorded too. Nothing is auto-authored.

🔒 Local storage, explicit sharing

The bundled scripts make no network calls or telemetry requests. Memory files and the HTML report stay local. The agent uses Claude Code's configured model service for reasoning; this is not a claim that the entire agent session runs offline.

• Enrolled by choice: repositories cannot grant themselves cross-project access.
• Protected writes: the canonical writer journals updates; locally edited mirrors enter conflict handling instead of being silently overwritten.
• Secret filtering: credential-shaped transcript text is omitted at retrieval; the firewall also guards shared-fact authoring and workflow emission.
• Bounded context: oversized indexes hold new pulls, with the held count surfaced.

See SECURITY.md for the enforced properties and limitations.

Updating, migration, and removing your data

Use Claude Code's /plugin manager to update or uninstall the plugin. Marketplace refresh and installed-plugin updates are separate operations; see the official plugin reference.

[!WARNING] Coming from the legacy global store (before v0.3.0)? Domain enrollment changed the trust boundary. Use an enrolled maintenance project to inventory, explicitly assign or exclude, and migrate the legacy facts before enrolling the remaining recipients. First enrollment revokes managed mirrors the destination does not admit, so review the maintenance caller's enrollment plan too. Verify the migration before finalizing; rollback is available only before finalization. The network guide includes the commands.

[!WARNING] Revocation is lazy, not immediate. Revocation through forget is acknowledged on subsequent pulls or GC; an offline copy retains bytes until it runs. Do not treat a forgotten fact as erased from a machine that has not synced since.

Uninstalling removes plugin code; it leaves memory data intact. Use /cm-data for scoped cleanup. Do not delete the native memory directory wholesale: it also contains Claude Code memory that this plugin does not own. Resolve actual paths with /cm-doctor.

Native Windows mutation is unsupported; use WSL. Missing POSIX locking fails closed.

🛠️ Develop and contribute

Clone this repository and dogfood the packaged artifact:

claude plugin marketplace add ./
claude plugin install consolidate-memory@zenetusken-plugins

The checkout's ./cm wrapper is a maintainer CLI. Marketplace users use the commands above. Common development checks:

python3 tests/smoke.py
python3 tests/simulate_accumulation.py
mypy --config-file mypy.ini
./cm status
python3 tests/validate_manifests.py
claude plugin validate ./plugins/consolidate-memory --strict

Runtime scripts stay stdlib-only. Mypy and the separate Chromium CI checks are development tools. For a reproducible visual preview:

python3 tests/dashboard_fixture.py --out /tmp/cm-preview
# Open /tmp/cm-preview/index.html#sel=7 in a browser.
# With the development-only Playwright + Chromium tools installed:
python3 tests/dashboard_browser.py --out /tmp/cm-browser

README contributions are checked too: python3 tests/docs_links.py verifies that the version badge matches plugin.json and that every relative link resolves. See CONTRIBUTING.md for the gate list and the code of conduct for community expectations.

The optional dream-beta-tester companion tests the consolidation skill itself, combining deterministic invariants with an agent judgment pass. Install with /plugin install dream-beta-tester@zenetusken-plugins and invoke /dream-beta-test. See its design and report contract.

🗺️ Find your way around

Find your way around	Source
Repository conventions and required gates	AGENTS.md
The six-phase workflow and tier rules	SKILL.md
Store topology, fact schema, verification recipes	Harness map
Native/canonical path resolution	store_context.py
Canonical writes and journal authority	canonical_ingress.py, control_plane.py
Dashboard data and presentation	Renderer, template, network exploration, report sections
The Deep Field visual system	deep-field-theme.spec.md
Decisions, release history, license	ADRs, CHANGELOG.md, MIT

License

MIT. This repository ships the plugin and its documentation only — it contains no personal memory; your facts stay in your own store.