context-optimization

Context Optimization

Small context is fast context. Apply these rules on any task that reads files or calls tools.

Procedure

The rules

1. Don't dump — summarize. When a tool returns >2K tokens, return a summary + the path. Not the whole blob.
2. Sandbox large files. A 5,000-line file → write the interesting parts to a sandbox path, return the path + a grep tool the agent can use. Re-reads are free.
3. Reference, don't repeat. If you read it once, don't paste it again. Quote the file path and the line range.
4. One tool call, one purpose. Don't bundle a read + a search + a write in one step. Each call has its own tool result overhead.
5. Stop when you have enough. First successful outcome is enough. Don't run the test 10 times to "be sure."

When output really is the answer

Some outputs must be verbatim:

• Stack traces with file:line
• Exact error messages
• Test diffs
• The user's quoted text

For these, the rule is truncate the noise, keep the signal — remove timestamps, request IDs, repeated headers.

When this conflicts with other goals

If the user asks for a literal paste of a file, do it. Context is a default, not a law.

When to skip

• The user is debugging interactively and needs the full output once.
• The tool returns <500 tokens — already small enough.

Worked example

A failing test run reduced to a pointer plus the decisive frames.

tool result (2,000 lines):
  ... 3 failed, 197 passed ... (saved to .foundry/spill/pytest-42.log)

answer:
  3 failures; first is KeyError in cache.py:88
  File "agent_foundry/cache.py", line 88, in load
    value = raw["value"]

Anti-patterns

• Pasting a 5,000-line file when a line range and summary answer the question.
• Repeating a file body instead of citing path and lines.
• Truncating the only copy of an output.
• Treating a spill locator as a parsed path.

Verification Checklist

• [ ] Large output has a summary plus a retrieval reference. (step 1)
• [ ] Exact errors and stack frames are preserved verbatim. (step 2)
• [ ] The full output survives before any truncation. (step 2)
• [ ] Cited line ranges still resolve. (step 3)
• [ ] Output collection stops at the first sufficient result. (step 5)

Compaction and Spill

• Cap history by estimated tokens and keep the newest N turns. Record compacted_turns and dropped tokens; silent loss is a correctness bug.
• Compaction is destructive. State the approximation: dropped turns are gone, not summarized, unless a summary backend exists.
• Spill the full output to a private artifact and keep a bounded inline preview. Never truncate the only copy.
• Return an opaque locator plus retrieval guidance. Treat the locator as a handle, not a path to parse.
• A spill failure keeps the inline result; it must not fail the model call.
• Create artifact directories private (0700) and files exclusively (0600). Never derive a filename from user text.
• Publish artifacts by temp file, fsync, rename. A half-written artifact is worse than a missing one.