| name | supercontexter |
| description | Lossless context saving via index + on-demand retrieval (progressive disclosure). Use when a large file/spec/doc would otherwise be pasted whole into context, when the user says /sc (index a file) or /uc (load index card or retrieve sections), or asks to "compress context", "save tokens on this doc", or "load only what's needed". Keeps a small index card in context; the full text stays on disk and exact sections load only when a task needs them. Not a summarizer — retrieval is verbatim. |
Supercontexter — index + on-demand retrieval
Real mechanism, honest math: the saving comes from NOT loading text you don't need yet. The index card (≤ ~100 tokens) sits in context; the full document (thousands of tokens) stays on disk, hash-verified, retrievable per section, verbatim. Nothing is summarized away, so nothing can be hallucinated back.
/sc <file> — index
python supercontexter/scripts/quantum_compressor.py <file>
Parses the file into sections (markdown headings; 50-line chunks otherwise), writes compressed_states/Ψ_<hash>.qstate (+ latest.qstate), prints the index card: one line per section with id, line range, token estimate, title, extract.
/uc [state] [section-ids…] — use
python supercontexter/scripts/quantum_decompressor.py
python supercontexter/scripts/quantum_decompressor.py Ψ_ab12cd34 s1 s3
Section mode verifies the source file's sha256 first — source changed → refuses and demands re-index (never serves stale line ranges).
Agent contract
- Keep only the card in context. Retrieve the specific sections the CURRENT task needs — not the whole file "just in case".
- Answer from retrieved sections only. Card extract insufficient → retrieve the section; never guess from the extract.
- Task needs most sections → just Read the file normally; the index has no value there.
- Never quote token-savings ratios as quality claims: this is lossless deferral, not compression. The card-vs-file ratio only says how much loading was deferred.
Limits (state honestly when relevant)
- Saves input tokens only; no effect on output or thinking tokens.
- Section retrieval that eventually loads the whole file costs slightly MORE than one full Read — the win exists only when tasks touch a subset.
