Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Loop engineering

Running an agent in a loop, where each iteration adds to a context window that does not grow. Contexere’s part is tracking what the loop has spent and carrying memory across iterations that would otherwise reset.

Setting a loop up

export CONTEXERE_LOOP_ID=$(uuidgen)
export CONTEXERE_LOOP_GOAL="Migrate the billing service off the legacy queue"
export CONTEXERE_LOOP_BUDGET=100000
export CONTEXERE_LOOP_ITERATION=0
variableconstraint
CONTEXERE_LOOP_IDalphanumeric and dash, 64 characters
CONTEXERE_LOOP_GOAL500 characters, no shell metacharacters
CONTEXERE_LOOP_BUDGETtoken budget per iteration, up to 10M
CONTEXERE_LOOP_ITERATIONcurrent iteration, default 0
CONTEXERE_SUBAGENT=1sub-agent mode
CONTEXERE_AGENT_IDidentity, so traces stay separable

Budget

The budget is estimated context window usage per iteration, not a spend limit.

loop shapebudgetwhat Contexere does
quick fix, 1 to 5 iterations200,000passive tracking
feature work, 5 to 20100,000active distillation, engrams
large refactor, 20 to 10080,000aggressive distillation, predictive warnings
marathon, 100+60,000maximum compression, loop memory persistence

Warnings fire at 65% and critical at 82%, adjustable with CONTEXERE_PRESSURE_WARN and CONTEXERE_PRESSURE_CRITICAL.

Do not set a budget above 1M: warnings will never fire before real exhaustion. Do not set one below 30K: the agent will compact constantly and lose short-term memory.

The goal string also shifts distillation aggressiveness. A goal containing “test” preserves test detail, “debug” keeps error context, “refactor” compresses harder.

Tools an orchestrator calls

None of these are advertised by default. Contexere tells a host about the tools its tier actually uses, and the loop tools are outside that set, so an orchestrator that calls them needs CONTEXERE_MCP_TOOLS=all in its environment. contexere doctor prints which set is in force. The MCP tools reference has the per-tier lists.

toolwhen
contexere_loop_statusonce before each iteration, the cheapest full picture
contexere_budget_statusbefore anything expensive
contexere_set_loop_contextwhen the goal or scope shifts mid-loop
contexere_loop_memoryread and write memory that survives a session restart
contexere_verifyas a checker, to evaluate the maker’s recent work

Maker and checker

Two agents, one shared context layer.

LOOP_ID=$(uuidgen)

# the loop tools are outside the default advertised set
export CONTEXERE_MCP_TOOLS=all

# maker
export CONTEXERE_AGENT_ID=maker CONTEXERE_LOOP_ID=$LOOP_ID
claude "Implement: $GOAL"

# checker
export CONTEXERE_AGENT_ID=checker CONTEXERE_SUBAGENT=1
RESULT=$(claude "Verify the implementation of: $GOAL. Use the contexere_verify tool.")

case "$RESULT" in
  *PASS*) echo "verification passed" ;;
  *)      echo "checker found issues" ;;
esac

Distinct CONTEXERE_AGENT_ID values are what keep the two from contaminating each other. Traces are tagged by agent, so contexere_verify can read across sessions while writes stay isolated.

Four things that make it work: give the checker specific measurable criteria, keep last_n_calls between 5 and 20, escalate to a human after three consecutive checker failures, and remember that every interaction is logged so the audit trail is real.

Monitoring

contexere stats                 # real-time
contexere stats --view detail
contexere stats --json          # for an orchestrator to read
contexere doctor                # health

contexere handoff is not a CLI subcommand. It was removed. The contexere_handoff MCP tool is unchanged, so session export is reachable from an MCP client rather than a shell.

A caution about the numbers

Every figure a loop reports is scoped by agent_id. If the orchestrator and the agents share one id, the maker’s savings and the checker’s are one number and neither is meaningful. Set the id per role before the first iteration, not after you notice.