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

git clone <this repo>
cd lm-context-compressor
npm install
lms dev --install -y     # installs into LM Studio (or run update.bat on Windows)

For live-reload development use lms dev instead.

Settings (per chat)

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:

large tool result
├── preserve: summary, retention.facts, IDs, status, next action
├── preserve: source URL/hash/path and transaction/job/run artifacts
├── omit: declared diff preview, page text, search result bulk, stdout/stderr
└── recover later from .agentic state using the preserved IDs

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:

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

Troubleshooting

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.

• Content-addressed cache — a rolling hash chain over the canonicalized messages. A cached entry at prefix-hash H means "these messages are covered by these chunk summaries." Same prefix ⇒ same hash ⇒ instant reuse, across turns and restarts. Any edit upstream changes the hashes ⇒ clean recompute, never corruption.
• Cut rules — history is only cut where no tool call gets separated from its result, so the model always sees well-formed rounds.
• Chunked summarization — old rounds are summarized in ~16k-token chunks from the original messages, never from prior summaries: no compounding drift, byte-stable output, KV-cache-preserving. Auto mode is lazy (only enough chunks to fit); /compress does the lot.
• The view — [system prompt + summary (merged into one system message) + recent tail] streams through your model with tools passed through and results rendered back into the chat.

Benchmarks

npm run bench:static   # structural/determinism checks, no model needed
npm run bench          # full run against your local LM Studio model

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

npm install
npm test            # 282 unit tests (vitest), written test-first
npm run typecheck
lms dev             # hot-reload dev server

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.)

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

git clone <this repo>
cd lm-context-compressor
npm install
lms dev --install -y     # installs into LM Studio (or run update.bat on Windows)

For live-reload development use lms dev instead.

Settings (per chat)

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:

large tool result
├── preserve: summary, retention.facts, IDs, status, next action
├── preserve: source URL/hash/path and transaction/job/run artifacts
├── omit: declared diff preview, page text, search result bulk, stdout/stderr
└── recover later from .agentic state using the preserved IDs

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:

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

Troubleshooting

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.

• Content-addressed cache — a rolling hash chain over the canonicalized messages. A cached entry at prefix-hash H means "these messages are covered by these chunk summaries." Same prefix ⇒ same hash ⇒ instant reuse, across turns and restarts. Any edit upstream changes the hashes ⇒ clean recompute, never corruption.
• Cut rules — history is only cut where no tool call gets separated from its result, so the model always sees well-formed rounds.
• Chunked summarization — old rounds are summarized in ~16k-token chunks from the original messages, never from prior summaries: no compounding drift, byte-stable output, KV-cache-preserving. Auto mode is lazy (only enough chunks to fit); /compress does the lot.
• The view — [system prompt + summary (merged into one system message) + recent tail] streams through your model with tools passed through and results rendered back into the chat.

Benchmarks

npm run bench:static   # structural/determinism checks, no model needed
npm run bench          # full run against your local LM Studio model

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

npm install
npm test            # 282 unit tests (vitest), written test-first
npm run typecheck
lms dev             # hot-reload dev server

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.)