Context Management Plugin

The Context Management plugin keeps long conversations usable by summarizing
older turns in the background and, when it helps, replacing distant history
with those summaries before the next model call. Unlike
Context Summarization (which reacts when the
context window overflows), this plugin runs after every turn.

It maintains several summaries of the same conversation at different lengths
(15, 50, 250, and 1000 tokens by default). When the topic shifts, older
summaries cascade down to shorter levels so distant history stays compact
while recent discussion stays detailed.

How compression looks

Context sent to the model:
┌────────────────────────────────────────────────────────┐
│ Distant history  — ~15 tokens (oldest, most compressed)│
│ Older history    — ~50 tokens                          │
│ Past history     — ~250 tokens                         │
│ Recent history   — ~1000 tokens                        │
│ Raw messages from after the latest compaction point    │
└────────────────────────────────────────────────────────┘

A topic shift moves the previous 1000-token summary down to 250 tokens, 250
down to 50, and 50 down to 15, and starts a new 1000-token summary at the
shift. Detail increases as you approach the present.

When estimate_sufficient_tokens is on (the default), each turn also gets an
estimate of how short a summary can be and still be adequate — a typo-fix
might need ~30 tokens; an architecture discussion might need ~800. Smaller
levels are used when they are already enough.

Compacted summaries can include retrieval hints: short phrases naming
details that were compressed away (for example "JWT expiry, refresh flow,
error codes") so the agent knows what it can ask about.

Configuration

plugins:
  - module: codumentor.plugins.context_management
    class: ContextManagementPlugin
    args:
      enabled: true
      target_token_levels: [15, 50, 250, 1000]
      provide_retrieval_tool: true
      min_turns_before_compaction: 3
      compaction_token_threshold: 1000
      ui_verbosity: normal

Parameters

• enabled (optional): Whether the plugin is active (default: true)
• target_token_levels (optional): Token budgets for the stacked summaries, sorted ascending (default: [15, 50, 250, 1000]). Must not be empty.
• provide_retrieval_tool (optional): Give the agent retrieve_conversation_history so it can pull earlier turns back (default: true)
• state_store_path (optional): Directory for per-conversation state. When unset, state is stored under the app data dir (context_management/).
• state_generation_model (optional): Model used to write summaries. Unset = the main agent model.
• drift_detection_model (optional): Model used to detect topic shifts. Unset = the main agent model.
• min_turns_before_compaction (optional): Compaction cannot start before this many turns (default: 3, minimum 1)
• compaction_token_threshold (optional): Replace raw older messages with summaries only when that prefix exceeds this many tokens (default: 1000, minimum 100)
• drift_window_size (optional): How many recent short summaries to look at when judging a topic shift (default: 10)
• estimate_sufficient_tokens (optional): Estimate a minimum adequate summary size per turn and pick a smaller level when it is enough (default: true)
• ui_verbosity (optional): Which events appear as transcript cards (default: "normal")

UI verbosity

Level	Cards shown
"all"	Per-turn state updates, topic shifts, and compaction
"normal"	Topic shifts and compaction (default)
"minimal"	Topic shifts only
"off"	None

Each user can also change Card Visibility in Settings (same four values).

args:
  ui_verbosity: minimal   # only topic-shift cards

Custom token levels

args:
  target_token_levels: [10, 100, 500, 2000]
  compaction_token_threshold: 2000

The retrieve_conversation_history tool's brief / medium / full levels
still map to 50 / 250 / 1000 tokens even if you change target_token_levels.

Retrieval tool

When provide_retrieval_tool is true, the agent can call
retrieve_conversation_history:

Argument	Meaning
start_turn	First turn (1-based)
end_turn	Last turn, inclusive
detail_level	"brief" (~50 tokens), "medium" (~250, default), "full" (~1000), or "raw" (original messages)

Disable the tool if you do not want the agent pulling old turns back:

args:
  provide_retrieval_tool: false

Notes

• Compaction starts only after min_turns_before_compaction and only when the older prefix is larger than compaction_token_threshold.
• State is kept per conversation, so summaries survive across turns.
• Use Context Summarization for overflow-only shrinking; use this plugin when you want ongoing compression of long threads. See Context Summarization.