zzallirog/weighted-compact

**A provably faithful recap and local inspectable substrate for your Claude Code sessions.**
~/.claude/projects/ is the record of every correction you pushed back on.
weighted-compact reads it and gives you two local artifacts: a task-segmented
**recap** per session (stdlib-only, provably faithful, ~5 ms/session), and a
**substrate** of every correction turn as inspectable numpy columns.
Zero outbound. Zero idle RAM.
> **Three claims, kept apart so none borrows another's credibility:**
>
> - **recap** — *provably faithful*: four invariants re-checked on **1007/1007**
> sessions (weighted-compact recap --all). Stdlib-only, no model, no judge.
> The one consumer with a positive, re-checkable result.
> - **manifesto control** — your keep/skip labels are a *hard constraint*, not a
> soft boost: 100 % keep-label survival at k ≤ 0.7 (vs recency baseline 62 %).
> The first compaction claim that beats a cheap baseline.
> - **mixture fidelity** — the six-signal importance mixture has **no measured
> edge** over recency or bm25 at current N. We say so, with the numbers, in
> How it compares.
>
> Reach for this if you want local artifacts you can *audit* and steer; reach
> for a drop-in like claude-mem if you want set-and-forget recall.
→ Docker / Windows install ·
Operating guide ·
Bench vs claude-mem ·
Stability promise ·
Extension recipe ·
Pick your door
---
By the numbers
Every figure here is re-checkable on your own corpus, and each carries its
own asterisk in plain sight — the project's stance is that an honest number
beats a flattering one.
- **1007 / 1007** sessions pass all four recap faithfulness invariants —
coverage · conservation · provenance · determinism
(weighted-compact recap --all). This proves the map does not *lie*
about the session — not that it is the optimal summary.
- **~5 ms / session** — 584 MB of transcripts mapped in 5.2 s, standard
library only (no numpy, no model, no judge in the recap path).
- **0** outbound network calls · **0 MB** idle RAM — the first is enforced
by the outbound-zero
CI workflow, the second because nothing runs between invocations.
- Querying the substrate beats a one-pass LLM summary by **~3.5×** on
reconstruction fidelity (11.3 % vs 3.2 %, N=62, gemma3 judge). That is
the one axis with a measured edge; the importance **mixture** does *not*
beat cheap baselines at this N, and the comparison
table says so.
- recap shrinks a session **~180×** — as a **lossy** navigation map, not a
reconstructable archive. For lossless archival, zstd -19 (~3×) wins and
this repo points you to it rather than shipping a weaker custom fold.
---
How it compares
A 30-second product map vs the dominant adjacent tool:
| | weighted-compact | claude-mem (77 k ★) |
|---|---|---|
| **Capture** | reads ~/.claude/projects/ on demand | 5 always-on lifecycle hooks |
| **Importance ranking** | 6 inspectable signals + REM-decay | ORDER BY recency DESC LIMIT k |
| **Manifesto control** | keep/skip labels honored as a hard constraint (pin / drop) | none |
| **Compaction** | top-K vector selection → markdown | LLM-summary, opaque |
| **Auto-injection** | none — client polls | every session start |
| **Outbound network** | zero (default) | configurable LLM provider per turn |
| **Substrate inspection** | numpy columns on disk | SQLite + Chroma |
| **Idle RAM** | 0 MB (nothing runs) | ~80–150 MB worker |
| **Reconstruction fidelity** | no measured edge — ties recency/bm25 | not measured by them |
The honest trade: the structural rows above (local, zero-outbound,
inspectable, 0 idle RAM, manifesto control) are real and verifiable. The
*quality* row is not a win — on reconstruction-fidelity the six-signal mixture
has not been shown to beat cheap baselines like recency or bm25, and neither
does hand-curation (see docs/baselines.md). What *is* a
real, exclusive property is **manifesto control**: your keep/skip labels are
honored as a hard selection constraint — a keep-labeled pair is guaranteed to
survive compaction (up to budget), a skip-labeled pair is dropped first. Measured
on a 16-pair labeled session: **100 % keep-label survival at k ≤ 0.7** (vs
recency baseline 62 %). That is a deterministic control guarantee, not a
compression-quality claim (proven by construction in tests/test_manifesto.py;
default-on in the compact_session MCP tool, meta.manifesto reports what it
honored). claude-mem is
hook-installed in seconds and feels magic; weighted-compact is a transparent
substrate you own, steer with a manifesto, and query with intent. Pick on
transparency / locality / control, not on compression quality — see