🗜️ context-compressor

Never run out of context in LM Studio again. When a long or agentic chat approaches the model's context limit, context-compressor automatically compresses old messages into a faithful, task-aware summary and the conversation just keeps going — the way Claude Code compacts its context, but for your local models. Your full chat stays on screen; only the prompt sent to the model shrinks.

Real numbers from a real chat: a 645,516-token agentic conversation (600%+ over a 122k context window) compacted to a 33,214-token prompt — 95% smaller, with the model still answering questions about things said before compaction.

what the model receives           what you see on screen
┌────────────────────────┐        ┌────────────────────────┐
│ system prompt          │        │ every message you ever │
│ + task-aware summary   │   ◀──  │ sent, untouched, fully │
│ + recent messages      │        │ scrollable             │
└────────────────────────┘        └────────────────────────┘
        ~33k tokens                      ~645k tokens

Features

🤖 Auto-compaction with hysteresis — deterministic, like Claude Code: when the prompt would cross a threshold (default 75% of the model's real context window), the oldest complete rounds are summarized down to a floor (default 55%), so compaction doesn't re-trigger every few turns. No relying on the model to "decide" to compress.
🏃 Mid-task compaction — long agentic turns run in capped tool-round passes; between passes the grown context is measured and compacted if needed, then the task continues seamlessly. A marathon tool loop can never overflow the context — the failure mode every simpler compressor still has.
🎯 Exact token accounting — the final prompt is rendered through the model's real chat template and counted with its real tokenizer, with a reserved-output budget, before every reply. Estimates plan; exact numbers decide.
⌨️ /compress or /compact — type either in chat to force compaction now. You get a token before/after report instead of a model reply.
📈 /usage — instant report of real context usage: prompt size vs context window, auto-compact headroom, transcript size, and compression state. The model also gets a get_context_usage tool, so just asking it "how much context do I have left?" works too.
🧠 Task-aware summaries — the summarizer must preserve what continuing your task needs: coding state (file paths, code verbatim, commands, errors + fixes), research findings with sources, decisions and rationale, constraints, current state, next steps. Empty sections are omitted.
🧭 Native Agentic Workspace state preservation — understands agentic-workspace/v1 tool results before generic truncation. It keeps transaction/run/job/To-Do/research/query/source IDs, next actions, command exit evidence, hashes, URLs, report/state paths, and artifact references while dropping declared bulky diffs, page bodies, listings, and command streams.
🔧 Tool passthrough with result capping — tools from your other enabled plugins keep working through compaction, and oversized tool results (default > 4000 tokens) are truncated before they can flood the context. Tool spam is the #1 cause of overflow in agentic tasks.
📎 Attachment memory — before compressing past an attachment, its content is preserved: documents become fact-sheets (exact numbers/names verbatim), images get described by vision models. Extracted once per file, cached across sessions; anything unextractable is explicitly marked "content not retained" instead of silently vanishing.
📏 Benchmarked — a reproducible benchmark suite (npm run bench) measures seeded-fact recall after compaction and after consolidation, prompt reduction, latency, structural integrity, and cache determinism; results are committed under bench/results/.
♾️ Bounded summary growth — when accumulated chunk summaries outgrow their budget (default 12k tokens), the oldest are consolidated into one denser summary with provenance preserved. Summaries can never swallow the context, no matter how long the chat gets — this is what makes "never run out of context" technically true, not just a slogan.
🔁 Transient-failure resilience — engine hiccups ("terminated", connection resets) get one automatic retry, gated so it only happens when provably nothing side-effectful ran — a tool that already executed is never executed twice.
⚡ KV-cache friendly — chunks are summarized from original messages (never from previous summaries), so summary text is byte-stable across compactions and your prompt prefix stays cacheable. Compacting can make generation faster.
📊 Honest progress & metering — compaction shows a live progress bar (Compacting ▓▓▓▓░░░░░░░░ 34% — chunk 2/5), and while compression is active each turn shows the real prompt size (Prompt: ~33,214 tokens ▓▓░░░░░░ 27% of 122,112). Configurable: status line, sender name, or off.
🛡️ Robust by construction — summaries are cached content-addressed (~/.lm-context-compressor/cache.json, atomic writes) and survive restarts. Edit or regenerate any old message and the cache cleanly recomputes. Abort mid-compaction and finished chunks are kept. Failures are visible, never silent, and never corrupt state.

Quick start

Install the plugin and open a chat.
Keep your real model selected as usual (any normal chat model works).
Enable context-compressor in the chat's plugin list.
Chat. That's it — compaction triggers itself when needed, or type /compress anytime.

From source

For live-reload development use lms dev instead.

Settings (per chat)

Setting	Default	Meaning
Auto-compact	on	Turn off for bulk-data tasks where the past IS the data
Compaction threshold	75%	Of the model's context window
Compact down to	55%	Hysteresis floor: once triggered, compact well below the trigger so long agentic turns have headroom
Reserved output tokens	2000	The prompt must fit within context minus this reply reserve
Absolute token trigger	0 (off)	Absolute-token alternative to the %, handy for testing
Recent context kept verbatim	6000 tokens	The newest conversation is never summarized
Summarize in chunks of	16000 tokens	Chunks are cached and reused across compactions
Max chunks per pass	0 (auto)	Cap the work per run; progress carries over
Tool rounds per pass	6	Agentic turns run in passes so compaction can happen mid-task; 0 = one uncapped loop
Max tool result size	4000 tokens	0 = unlimited
Max tokens per chunk summary	1500
Summarizer prompt	Auto (recommended)	Auto/Full (10-section)/Compact — auto always uses the full prompt (bench-confirmed best recall); Compact can be forced here and is also used automatically as a rescue when a model's reasoning runs away
Summary budget	12000 tokens	Above this, oldest summaries consolidate into one (0 = unbounded)
Attachment memory	on	Preserve document/image content before compressing past it
Announce compaction in chat	on	Token before/after note
Prompt meter	Status line	Where the real prompt size is shown

Agentic Workspace integration

With Agentic Workspace 0.2.0+, context-compressor does more than pass tools through. It recognizes the plugin's durable result protocol and compacts it structurally:

The summary schema now has dedicated Durable workflow state, Verification & evidence, and Source ledger sections. Search snippets remain discovery hints; fetched source_* records and their stored paths remain evidence. The summarizer-prompt change is included in the cache namespace, so old summaries are not silently reused under the new preservation rules.

See AGENTIC_WORKSPACE_INTEGRATION.md for the protocol and end-to-end test sequence. Release validation — the full native test runs and a live benchmark matrix across eight model families — is documented in RELEASE_VALIDATION.md.

FAQ

The context ring at the bottom still shows a huge percentage — is it working? Yes. LM Studio's built-in ring counts the visible transcript, which this plugin deliberately never shrinks (your scrollback is sacred). The prompt the model actually receives is what gets compressed — read the plugin's own meter line for the true number. A feature request is open with LM Studio to let plugins update the built-in ring.

Does the model really remember things from before compaction? It continues from a structured summary that preserves goals, decisions, code, findings, and next steps verbatim where it matters. It is compression — fine detail in the middle of old conversation fades first. Anything in the recent-tokens window is untouched.

When should I NOT use it? When the old messages are the data: log analysis, hex dumps, bulk document review. Summarizing destroys exactly what you need. Flip Auto-compact off for those chats (/compress stays available if you change your mind).

What models does it work with? Any normal chat model — token math uses each model's own tokenizer and reported context length; prompt formatting goes through LM Studio's template machinery. Tool passthrough needs a tool-capable model. Selecting a generator plugin as the model isn't supported (nothing to count tokens with) — the plugin says so and passes through.

A first compaction on a giant chat takes a while. Each chunk is one summarization call on your local model. The progress bar shows real progress, aborting keeps completed chunks, and "Max chunks per pass" lets you spread the work over multiple runs. Once cached, chunks are never re-summarized.

Model compatibility

Tested live against eight model families for the 0.7.0 release (Qwen3 and Qwen3.5/3.8, DeepSeek-R1 distill, Gemma 3, Llama 3.2 at 3B and 18B, gpt-oss, GLM) — results committed under bench/results/.

Any normal chat model works.
Thinking models (Qwen3/QwQ, DeepSeek-R1, gpt-oss, Magistral, Kimi, GLM, SmolLM3) — reasoning is kept out of summaries; where the model supports a no-think switch, summarization uses it so it doesn't burn reasoning tokens on every chunk. Models that ignore the switch and think anyway get an escalating retry (more headroom, then a leaner prompt), and if a model truly refuses to stop reasoning, the chunk falls back to a verbatim digest — compaction completes either way.
Gemma-style templates with no system role — the summary is folded into the first user message instead of crashing.
Small context windows — the compressor's own sizes (keep-recent, chunk, reserved-output, summarizer-max) auto-scale to fit.
Models not trained for tool use — tools are disabled with a visible notice, and it keeps working.
Vision models — image attachments get memory (see Attachment memory above).

How it compares

The other context tools on the LM Studio Hub, honestly compared:

	context-compressor	context-compactor	kosmix/compact
Auto-compaction on threshold	✅ with hysteresis floor	✅	❌ manual
Bounded summary growth (hierarchical consolidation)	✅	❌ grows forever	❌
Attachment content preserved through compression	✅	❌	❌
Reproducible benchmark suite in-repo	✅	❌	❌
Mid-task compaction (marathon tool loops)	✅	❌	❌
`/compress` · `/compact` · `/usage` commands	✅	❌	partial
Exact templated-prompt token accounting	✅	❌ estimates	❌
Survives edited/regenerated messages	✅ content-addressed cache	❌ documented limitation	—
Resumable, abortable compaction	✅ chunk-granular, persisted	partial	❌
Tool passthrough + result capping	✅ + callId-correlated results	✅	❌
Ask the model "how much context is left?"	✅ `get_context_usage` tool	❌	❌
Summary injection hardening (provenance, no authority escalation)	✅

(persistent-memory solves a different problem — cross-chat fact storage — and composes fine with this plugin.)

Troubleshooting

You see	It means
`Compacting … chunk n/m (k cached chunks reused)`	Normal — previously summarized chunks are being reused; stopping is safe, finished chunks are saved
`Mid-task compaction … — continuing`	A long agentic turn grew the context; it was compacted between tool passes and the task continues
`Prompt … exceeds the safe budget`	Even after safety compaction the prompt is too big — raise the context length, lower "Reserved output tokens", or reduce "Recent context kept verbatim"
`Preserving attachment "x" (1/2)…`	A document/image is being extracted into attachment memory before its region compresses
`Consolidating N summaries into one…`	Accumulated summaries outgrew their budget and are being folded into one denser summary — normal on very long chats
`Transient engine error — retrying once…`	The engine dropped the connection mid-reply; the pass is retried (only when nothing side-effectful ran)
`Configured compact-down-to floor … is not reachable`	Your floor % is smaller than what the summary budget + kept-verbatim + system prompt need — raise the floor or shrink those settings
`context-compressor needs a real model as the token source`	A generator plugin is selected as the model; pick a real model
Meter says one thing, LM Studio's ring another	The ring counts the visible transcript (which never shrinks); the meter counts what the model actually receives — see FAQ

How it works

The plugin registers an LM Studio prediction loop handler: each turn it receives the full chat, maps it to a compressed view, and runs your selected model over that view.

Benchmarks

Measures seeded-fact recall from the compacted view (and again after a forced consolidation, to quantify drift), prompt reduction, per-chunk latency, structural integrity, and cache determinism across four synthetic fixtures (coding agent, research, contradictory updates, tool spam). Results are stamped with the model id and committed under bench/results/ — see bench/README.md for metric definitions and caveats.

Development

Pure logic (hashing, cut rules, chunk planning, truncation, caching) is fully unit-tested; the LM Studio integration layer is deliberately thin.

License

Free for personal and internal professional use — use it, modify it, self-host it at home or at work at no cost.

Commercial embedding requires a license: incorporating this software (or a derivative) into a product or service that people pay for requires a separate commercial agreement with the author — contact via GitHub or the LM Studio Hub profile. See LICENSE for the full terms. (Hub revisions 1–15 were published under MIT; that grant remains valid for those copies.)