Context

Every model has a context window — the maximum amount of text it can “see” at once during a conversation. This includes your messages, any file contents you’ve shared, tool outputs, and the model’s own responses. It’s measured in tokens (roughly ¾ of a word).

Context windows vary by model

Context window sizes vary a lot between models:

• Large flagship models (Claude, GPT, Gemini) typically have context windows of 128K tokens or more — some go up to 1 million tokens. At that scale, you can work through long sessions without worrying about running out of space.
• Smaller and free models often have much smaller context windows. That’s enough for focused tasks, but it fills up quickly if you’re pasting in big files or having a long back-and-forth.

Compaction

As a conversation grows longer, the context window fills up. When it gets close to full, Pi triggers compaction — automatically summarizing older parts of the conversation to free up space so the session can continue, working from a summary rather than the full original context. You can also trigger this manually with /compact.

Three settings control compaction, in ~/.pi/agent/settings.json or a project’s .pi/settings.json:

{
  "compaction": {
    "enabled": true,
    "reserveTokens": 16384,
    "keepRecentTokens": 20000
  }
}

What this means in practice

With a big flagship model, you often don’t need to think about context at all — typical sessions, even complex ones, don’t come close to filling the window.

With a smaller or free model, context management matters more:

• Keep sessions focused. One task per session is easier on the context window than trying to do everything in one long conversation.
• Start fresh for new tasks. If you’ve finished one thing and want to move on to something unrelated, start a new session rather than continuing the old one.
• Watch for signs of drift. If the model starts giving responses that seem to ignore earlier instructions or context, the window may be getting full. Starting a fresh session, or running /compact, usually helps.

Reading the context meter

The footer shows something like 91.1%/1.0M (auto):

• 1.0M is the model’s context window.
• 91.1% is how full the context is right now.
• (auto) means auto-compaction is enabled.

It turns red as a warning near the limit — that’s a color threshold, not an error. Auto-compaction only fires once usage passes contextWindow - reserveTokens, which works out to roughly 98% on a 1M-token window with the default 16384 reserve. So a red-but-not-full meter still means the whole conversation is being sent to the model; nothing has been cut yet.

Proactive /compact vs. letting auto handle it

The default is to let auto-compaction handle it. It waits until you’re near the limit, so you keep the most useful context for as long as possible, and since summarization is lossy, fewer compactions mean less cumulative information loss.

A proactive /compact is worth running:

• At a clean task boundary, before pivoting to unrelated work — a better cut point than wherever an auto trigger happens to land mid-turn.
• To steer the summary, since auto-compaction can’t take instructions: /compact focus on the API changes, skip the debugging tangents.
• Before a long autonomous run, to buy headroom in advance.

Avoid running it mid-task, especially mid-turn — a single huge turn that gets compacted produces a lower-quality “split turn” summary. Better to finish the thought first.

Pi doesn’t currently prompt you to compact when you switch topics or start a long run — that judgment call is on you. The context meter in the footer is your best reminder: check it before pivoting to unrelated work or kicking off a long autonomous task.