Long sessions and compaction: keep your place

Compaction is the step where your agent shrinks the conversation to a short summary when its context window is full. After compaction, your agent asks what you were doing. Context Mode Engine keeps a session log on your machine and hands the agent a short state block on the next turn. The agent picks up the task, and ctx_resume reads any full row from the log by its seq, the row number that each step gets in the log.

Free · Local · Private · Yours to keep

Context Mode Engine is source-available under the Elastic License 2.0. Use it, copy it, change it and share it at zero cost, for as long as you follow the licence terms. It runs on your machine, sends zero usage data, and keeps your data in ~/.context-mode.

The problem: the agent starts over

A long session fills the context window. The agent then compacts: it swaps the old turns for a short summary and starts a fresh context. The next answer reads "What were we working on?" You explain the task again, and the agent reads the same files again.

What the Engine does: it keeps a session log

The hooks write each step of the session to context.db on your machine, one row per step. Each row has a number, called seq. The log holds:

• each prompt you type,
• each file the agent edits,
• each command it runs,
• each tool error, index call, cost row and decision.

The Engine builds this log with rules and BM25 ranking. It makes zero model calls.

At compaction: a state block of at most 2,048 B

When the agent compacts, the Engine builds a state block from the log. The block is at most 2,048 B. It draws on the rows that tell the story: your prompts, the edits, the commands and the tool errors. Every line stays whole. A long line becomes a ctx_resume(seq) pointer to the full row.

The agent gets the block on the next turn. Claude Code, Codex, Qwen Code and ZCode give it at SessionStart. Gemini CLI, Copilot CLI and VS Code give it with the next prompt. Pi and OpenCode give it from inside the agent process. The table on Ten agents, one plugin shows the events for each host.

In the 2026-10-31 benchmark, a long session of 40 tool outputs made a 432.5 KB transcript. ctx_resume gave it back as a 2.0 KB state block. That is the median of 5 runs on seeded test outputs, measured in bytes (raw file, source on GitHub).

Bring back any row with ctx_resume

Ask the agent to call ctx_resume. Called on its own, it returns the state block. With a seq, it returns that one row in full, for example the whole output of an earlier npm test.

ctx_resume()            # the state block, at most 2,048 B
ctx_resume({ seq: 3 })  # row 3 of the session log, in full

On each prompt: a recall block

In seven agents, the Engine also reads each new prompt and searches the log for rows that match it. It adds those rows to the prompt as a recall block of at most 2,048 B, always as whole rows. The same rows always give the same bytes. The seven agents are Claude Code, Codex, Gemini CLI, Qwen Code, Copilot CLI, VS Code and ZCode.

What you get

After compaction, the agent reads a short state block and goes on with the task. You skip the second explanation. The full log stays on your machine, and ctx_resume brings back any row when the agent needs the detail.

<context_mode_state session="s-4f2a" upto="7">
now: fix the login test
error #4 Bash: timeout in login.spec.ts
edited src/auth.ts x2
decided #7: keep the session cookie
more: ctx_search(queries:["login.spec.ts"], scope:"session")
</context_mode_state>