Pi Agent: Context Management
Last updated: 2026-08-31
Context is the Agent's "short-term memory" — manage it well, or the Agent will "forget what it was talking about."
1. What Is Context
Context is all information accumulated during a session:
- System Prompt
- Chat History
- Tool Call Records
- Injected Extra Information
TEXT
📖 Display only
Context Structure
├── System Prompt -> Fixed instructions (role definition, behavioral constraints)
├── Chat History -> Dynamic accumulation (user messages + Agent responses)
├── Tool Calls -> Tool call process and results
└── Injected Context -> Extra injections (file contents, API data, etc.)
2. Context Window
The context window determines how much the Agent can "remember" at once:
(1) Setting Window Size
PYTHON
from pi_agent import Agent
agent = Agent(name="quick", context_window=2048) # Small: save tokens
agent = Agent(name="long", context_window=16384) # Large: remember more
agent = Agent(name="full", context_window=65536) # Maximum: full model capability
(2) Window vs Cost
| Window Size | Best For | Token Cost |
|---|---|---|
| 2K | Q&A, simple instructions | Low |
| 8K | Multi-turn conversations, code review | Medium |
| 32K | Long document analysis | High |
| 64K | Large project analysis | Very high |
3. Truncation Strategies
When conversation exceeds the window, Pi Agent offers multiple strategies:
PYTHON
from pi_agent import Agent
agent = Agent(truncation_strategy="remove_oldest") # Remove oldest messages
agent = Agent(truncation_strategy="summarize") # AI summarizes old messages
agent = Agent(truncation_strategy="sliding_window", keep_recent=10) # Keep last N turns
| Strategy | Pros | Cons |
|---|---|---|
| remove_oldest | Simple and efficient | Loses early information |
| summarize | Preserves key points | Extra token cost |
| sliding_window | Controllable | May miss important context |
4. Context Injection
(1) Manual Injection
PYTHON
from pi_agent import Agent
agent = Agent(name="coder")
with open("main.py") as f:
agent.inject_context("current_file", f.read())
agent.inject_context("project_info", {
"name": "my_app",
"framework": "FastAPI",
"python_version": "3.11"
})
response = agent.chat("Help me add a health check endpoint")
# Agent knows the project uses FastAPI, generates FastAPI-style code
(2) Auto Injection
PYTHON
agent = Agent(name="auto", auto_context=True)
# Automatically injects working directory structure, git info, etc.
5. Optimization Techniques
(1) Concise System Prompts
PYTHON
# Verbose
agent = Agent(system_prompt="You are a very excellent programming assistant, skilled in Python, respond in detail...")
# Concise
agent = Agent(system_prompt="Python expert. Be concise.")
(2) Clean Unnecessary History
PYTHON
agent.clear_history() # Clear all when switching topics
agent.keep_recent(5) # Keep only last 5 turns
(3) Auto Summarization
PYTHON
agent.summarize_context() # Manual trigger
agent = Agent(auto_summarize_threshold=3000) # Auto at threshold
FAQ
Q Context window vs model's context length?
A The window is your Agent-level limit and can't exceed the model's maximum. E.g., deepseek-chat supports 64K; setting 100K is ineffective.
Q inject_context vs writing in messages?
A inject_context content persists (not removed by truncation), while message content may be truncated. Best for important project info.
Q How many extra tokens does auto-summarization cost?
A About 10-20% of the summarized content. E.g., summarizing 4000 tokens costs ~400-800 extra.
Summary
- Context = system prompt + chat history + tool calls + injected content
- Context window determines memory limit; bigger is stronger but costlier
- Three truncation strategies: remove_oldest, summarize, sliding_window
- inject_context for persistent info that won't be truncated
- Three optimization techniques: concise prompts, clean history, auto summarization
Exercises
- Basic (Difficulty: ⭐): Create an Agent with different context_window values, observe when it starts "forgetting" in multi-turn conversations.
- Intermediate (Difficulty: ⭐⭐): Compare remove_oldest vs summarize truncation strategies.
- Advanced (Difficulty: ⭐⭐⭐): Implement a "smart context manager" that auto-detects when to clean history and when to summarize.
