Recipe: Context Compaction

This recipe shows how to compact long conversations before they hit context limits.

Compaction means:

1. summarize prior discussion,
2. reset old context, then
3. continue from a short handoff summary.

Recommended automatic hook (external summarizer)

This version is robust in practice and avoids recursive compaction.

Hook definition

hooks:
  - name: compact
    on: assistant_message
    inline: true
    do: $LECTIC_CONFIG/hooks/compact.sh

Compaction script

Create $LECTIC_CONFIG/hooks/compact.sh:

#!/usr/bin/env bash

# Trigger compaction once total tokens reach this value.
LIMIT=200000
TOTAL="${TOKEN_USAGE_TOTAL:-0}"

if [[ "$TOTAL" -lt "$LIMIT" ]]; then
  exit 0
fi

# Prevent recursion when this script itself calls `lectic`.
if [[ -n "${COMPACTION_UNDERWAY:-}" ]]; then
  exit 0
fi
export COMPACTION_UNDERWAY=1

# Only compact if there's more work to be done.
if [[ -n $TOOL_USE_DONE ]]; then
exit 0  
fi

PROMPT_FILE="$LECTIC_CONFIG/hooks/compact-prompt.md"

# The conversation body comes in on stdin.
CONVERSATION="$(cat <<EOF

$(cat)

**WARNING, context almost full at $TOTAL tokens.**"

$(cat "$PROMPT_FILE")
EOF
)"

SUMMARY=$(echo "$CONVERSATION" | lectic --format clean)

cat <<EOF
LECTIC:reset
LECTIC:final

**Context compacted at $TOTAL tokens.**

Summary of previous discussion:
<summary>
$SUMMARY
</summary>

Please continue with your task.
EOF

Make it executable:

chmod +x "$LECTIC_CONFIG/hooks/compact.sh"

Summarizer instructions

Create $LECTIC_CONFIG/hooks/compact-prompt.md:

Summarize the conversation for handoff to a fresh context.

Include:
- current objective
- key decisions and constraints
- important file paths, commands, and outputs
- open questions and next concrete step

Keep it concise but complete. Return summary text only.

How this works

1. Hook runs after each assistant pass.
2. If token usage is below LIMIT, nothing happens.
3. If over LIMIT, stdin conversation is piped to a separate lectic -S summarizer call.
4. Hook outputs LECTIC:reset to drop prior context and LECTIC:final to stop an extra follow-up pass.
5. Next turn starts from the compacted summary.

Variation: use the active assistant to summarize first

If you want compaction to use the same assistant (including its reasoning behavior), use an in-band reset flow with :reset[].

macros:
  - name: compact
    expansion: |
      exec:#!/usr/bin/env bash
      cat <<'EOF'
      :reset[]

      Before reset applies, summarize our discussion with:
      - current goal
      - decisions and constraints
      - important files/commands
      - remaining tasks
      EOF

Usage: :compact[]

This is not as automatic, but it gives the model one response to produce the handoff summary before context is truncated.