Pi Agent: Session Management
Last updated: 2026-08-31
Sessions are the Agent's "memory capsules" — save them to continue later; branch them to explore possibilities.
1. What Is a Session
A Session records a complete interaction, including:
- Conversation history
- Context state
- Tool call records
- Agent configuration
PYTHON
from pi_agent import Agent, Session
session = Session(name="project_review")
agent = Agent(name="reviewer", session=session)
agent.chat("Review main.py")
agent.chat("What security issues are there?")
print(len(session.messages)) # 4 (2 user + 2 assistant)
2. Session Persistence
(1) Save to File
PYTHON
from pi_agent import Agent
agent = Agent(name="tutor")
agent.chat("Teach me Python decorators")
agent.session.save("decorator_session.json")
(2) Load from File
PYTHON
from pi_agent import Agent
agent = Agent(name="tutor")
agent.session.load("decorator_session.json")
agent.chat("How does it differ from class method decorators?")
(3) Auto Save
PYTHON
agent = Agent(name="tutor", auto_save=True, save_dir="./sessions/")
3. Session Branching
Branching creates parallel conversation paths from any point:
Example 1: Exploring Different Approaches (Difficulty: ⭐⭐)
PYTHON
from pi_agent import Agent
agent = Agent(name="architect")
agent.chat("Design a user authentication system architecture")
# Agent gave JWT approach
branch1 = agent.branch(name="jwt_branch")
agent.chat("Redesign using OAuth2")
# Agent gave OAuth2 approach
branch1.chat("How to handle token refresh in JWT?")
# Two independent sessions
print(agent.session.messages) # JWT -> OAuth2 path
print(branch1.session.messages) # JWT -> refresh path
4. Session Management CLI
BASH
pi-agent sessions list
pi-agent sessions show decorator_session
pi-agent chat --session decorator_session
pi-agent sessions delete old_session
pi-agent sessions export decorator_session --format markdown --output chat.md
5. Session Search & Tags
(1) Add Tags
PYTHON
agent.session.add_tag("python")
agent.session.add_tag("decorator")
agent.session.add_tag("advanced")
(2) Search Sessions
PYTHON
from pi_agent import SessionManager
manager = SessionManager()
sessions = manager.find_by_tag("python")
sessions = manager.find_by_date("2026-08-28")
sessions = manager.search("decorator closure")
(3) CLI Search
BASH
pi-agent sessions search "decorator"
pi-agent sessions list --tag python --date 2026-08-28
6. Session Sharing
(1) Export as Markdown
PYTHON
agent.session.export("chat.md", format="markdown")
(2) Export as JSON
PYTHON
agent.session.export("chat.json", format="json")
(3) Share with Another Agent
PYTHON
new_agent = Agent(name="continuer")
new_agent.session.import_from(agent.session)
new_agent.chat("Continue the discussion, dive deeper into metaclasses")
FAQ
Q Where are session files stored?
A Default is
~/.pi-agent/sessions/. Customize with the save_dir parameter.Q How large do session files get?
A Depends on conversation length. ~50-200KB for 100 turns. Images and long code increase size.
Q Can I merge two sessions?
A Yes. Use
session.merge(other_session). Messages are sorted by timestamp.Summary
- Sessions record complete interactions; support save, load, auto-save
- Branching explores different approaches without affecting the main line
- Tags and search help find historical sessions quickly
- Export as Markdown/JSON for sharing and archiving
Exercises
- Basic (Difficulty: ⭐): Create a session, have 5 rounds of conversation, save and reload.
- Intermediate (Difficulty: ⭐⭐): Create two branches from one session, explore different approaches, compare results.
- Advanced (Difficulty: ⭐⭐⭐): Build a "session dashboard" script that shows stats for all sessions: tags, turn count, token usage.
