SouveraineOS/docs/substrate/COMPACTION_STRATEGIES.md

Compaction Strategies

How Ani, Aster, and subagents reclaim context room. Each strategy is a different tool for a different kind of fullness.

---

Overview

Souveraine offers five compaction strategies. None are forced — the agent chooses via memory compact --strategy <name>. Pressure warnings at 80%/90% are advisory; only at 95% does the substrate narrow output tokens, and even then the agent may decline (ignore_compaction).

Strategy	LLM?	What it does	Best for
Microcompact	No	Clears old tool result contents, keeps the call shells	First response to pressure — cheap, safe
SlidingWindow	No	Drops middle messages, keeps system + tail	Aster, subagents, analytical agents
Summary	Yes (any model)	Replaces old messages with a structured 9-section boundary	Ani — prose agents who need the throughline
Cull	No	Drops trivial messages (greetings, single words)	Last resort — clears noise without losing substance
Defer	No	Does nothing. The agent continues until natural truncation	When compaction would lose more than it saves

---

Microcompact

Source: OpenHarness (port of Claude Code microCompact.ts)

What it does: Walks the conversation, finds tool results from known compactable tools (read, bash, grep, glob, list_dir, edit, write), and replaces their output content with [Old tool result content cleared]. Keeps the most recent 5 results intact so the current working state is preserved.

The tool call shells (id, name, args) remain untouched. The model still knows what was done, only the verbose return value is gone.

When to reach for it:

• First response to context pressure — it's cheap (no LLM call), safe (no data loss, just truncation), and often recovers 20-40% of context room in a single pass
• After a long tool-heavy session where read, bash, and grep calls filled the window with file contents
• As a pre-pass before Summary if you want to maximize what the summary model can see

What it costs: ~O(n) walk of the message list. No LLM tokens.

---

SlidingWindow

Source: claw-open, jcode (shared pattern — "keep last N, drop middle")

What it does: Preserves the system anchor message (index 0) plus the last N messages (configurable via min_messages). Everything in the middle is dropped.

Tool-pair aware: if the cut boundary would land on a tool-result message (separating a tool call from its result), the cut slides backward up to 8 positions until the pair is reunited.

When to reach for it:

• Aster's N+1 pass — she only needs the immediate exchange, not the whole history. Her job is verification and surfacing, not narrative continuity.
• Subagents — ephemeral, task-scoped, don't need historical context beyond the current work head
• Any analytical agent that processes turns independently rather than following a narrative arc

What it costs: Zero. Deterministic, no LLM call. The dropped messages still exist in git history.

---

Summary

Source: OpenHarness (port of Claude Code autoCompact.ts), claw-open

What it does: Sends the older messages (everything before the last N) to an LLM with a structured 9-section prompt. The model produces:

1. Primary Request and Intent — what the user actually asked for
2. Key Technical Concepts — frameworks, patterns, conventions
3. Files and Code Sections — every file touched, with paths and snippets
4. Errors and Fixes — what broke and how it was resolved
5. Problem Solving — approaches that worked vs. didn't
6. All User Messages — exact wording of non-tool user messages
7. Pending Tasks — explicitly requested but unfinished work
8. Current Work — what was being done when compaction hit
9. Optional Next Step — the logical thing to do next

The output is wrapped in <analysis> (scratchpad the model uses internally) and <summary> (the actual boundary message). Only the <summary> section replaces the old messages.

When to reach for it:

• Ani's primary conversation — she works in prose and narrative. A straight SlidingWindow would lose the throughline. Summary preserves it.
• After Microcompact has already cleared tool bloat but pressure is still high — Summary then works on a cleaner signal
• Any agent where continuity across the compact boundary matters more than speed

What it costs: One LLM call at the compaction model's rate. The prompt template is fixed and does not include tool definitions, so it's cheaper than a full turn. The 9-section structure is what makes the compact survivable — without it the agent resumes blind.

---

Cull

Source: hermes-agent (pruning pre-pass pattern), Souveraine-specific

What it does: Scans older messages and drops those whose text content is trivial — single-word acknowledgments, greetings, simple affirmations ("ok", "thanks", "got it", "sure", etc.). Role-aware guard: System messages, Tool messages, and any assistant message carrying a ToolUse or ToolResult block are never dropped regardless of content length.

A message is only culled if all its Text blocks are trivial. A single substantive line in an otherwise short message keeps the whole thing.

When to reach for it:

• Last resort before natural truncation — if you're going to lose messages anyway, at least drop the ones with zero information content first
• Pre-pass before Summary on a very long conversation — clears out the greetings and setup messages so the summary model sees a denser signal
• Agents with very short contexts (e.g. subagents on small models) where every token matters

What it costs: O(n) string matching. No LLM call.

---

Defer

Source: Souveraine design (CONSCIOUSNESS_CYCLE.md)

What it does: Nothing. The agent continues without compacting. If pressure reaches 100%, the model's output tokens narrow to a trickle (floor at 512) and the turn naturally truncates. The agent may end with "I can't continue" or produce a fragmented response.

When to reach for it:

• When compaction would lose more than it saves — the conversation is so dense that every message is load-bearing
• When the agent is close to a natural stopping point anyway
• As an explicit choice after evaluating the cost: "I'm at 94% pressure but I need all of this context to finish the current task"

Not yet implemented. Currently the body shifts at 95% (output tokens tighten) but there is no ignore_compaction(reason) mechanism to let the agent explicitly decline and have the harness honor it. That's tracked in the compaction-rebuild task.

---

Per-Agent Defaults

[compaction.per_type]
# Ani — narrative, prose, episodic. Summary preserves the throughline.
"primary" = { strategy = "summary", min_messages = 10 }

# Aster — analytical, terse, fires every turn. Sliding window is cheap
# and she only needs the current exchange to verify and surface.
"subconscious" = { strategy = "sliding_window", min_messages = 4 }

# Subagents — ephemeral, task-scoped. Sliding window keeps the work head
# and drops setup.
"subagent" = { strategy = "sliding_window", min_messages = 2 }

---

Reference Map

Strategy	claw-open	jcode	OpenHarness	hermes-agent	letta-code
Microcompact	—	—	microCompact.ts + microcompact_messages()	—	—
SlidingWindow	compact_session() — keep last N, summarize middle	RECENT_TURNS_TO_KEEP = 10	—	—	MIN_CONTEXT_WINDOW_TOKENS (pre-emptive)
Summary	<summary> tag prompt	SUMMARY_PROMPT constant	compact_conversation() with 9-section prompt	_generate_summary() with structured template	—
Cull	—	—	—	_prune_old_tool_results() + _truncate_tool_call_args_json()	—
Defer	—	ensure_context_fits() → CompactionAction::None	—	—	—

---

Strategy Selection Guide

Is pressure coming from tool result bloat?
  → Microcompact (clears results, keeps calls)
  → Still high? Microcompact again with lower keep_recent

Is this Aster or a subagent?
  → SlidingWindow (cheap, fast, only needs the tail)

Is this Ani in a narrative conversation?
  → Microcompact first (clear the tool noise)
  → Summary next (compress the story into a boundary)

Is the conversation full of pleasantries and setup?
  → Cull (drops greetings, keeps substance)

Is none of the above good enough?
  → Defer (ride the constraint, maybe she truncates naturally)