# Session Context (/learning/stores/session-context)
The Session Context Store captures the current state of a conversation: what's been discussed, what the goal is, and what progress has been made. Unlike other stores that accumulate data, session context is a snapshot that gets replaced on each update.
| Aspect | Value |
| ------------------- | ------------------------------------- |
| **Scope** | Per session |
| **Persistence** | Session lifetime (replaced on update) |
| **Default mode** | Always |
| **Supported modes** | Always |
## Setup [#setup]
```bash
pip install agno openai sqlalchemy "psycopg[binary]" pgvector
export OPENAI_API_KEY="your-api-key"
```
The examples use a local PostgreSQL database on port 5532. With Docker running, start it using:
macOS / Linux
Windows
```bash
docker run -d \
-e POSTGRES_DB=ai \
-e POSTGRES_USER=ai \
-e POSTGRES_PASSWORD=ai \
-e PGDATA=/var/lib/postgresql \
-v pgvolume:/var/lib/postgresql \
-p 5532:5432 \
--name pgvector \
agnohq/pgvector:18
```
```powershell
docker run -d `
-e POSTGRES_DB=ai `
-e POSTGRES_USER=ai `
-e POSTGRES_PASSWORD=ai `
-e PGDATA=/var/lib/postgresql `
-v pgvolume:/var/lib/postgresql `
-p 5532:5432 `
--name pgvector `
agnohq/pgvector:18
```
Later configuration fragments reuse the imports and `db` from the first complete example.
## Basic Usage [#basic-usage]
```python
from agno.agent import Agent
from agno.db.postgres import PostgresDb
from agno.learn import LearningMachine
from agno.models.openai import OpenAIResponses
db = PostgresDb(db_url="postgresql+psycopg://ai:ai@localhost:5532/ai")
agent = Agent(
model=OpenAIResponses(id="gpt-5.2"),
db=db,
add_history_to_context=True,
learning=LearningMachine(session_context=True),
)
# Session tracks what's being discussed
agent.print_response(
"I'm designing a REST API for a todo app. Should I use PUT or PATCH for updates?",
user_id="alice@example.com",
session_id="api_design",
)
# Later in the session, context is maintained
agent.print_response(
"What about the delete endpoint?",
user_id="alice@example.com",
session_id="api_design",
)
```
The agent knows the ongoing context about REST API design.
## Summary Mode [#summary-mode]
Summary mode is the default. It captures the essence of the conversation without detailed planning.
```python
from agno.learn import LearningMachine, SessionContextConfig
agent = Agent(
model=OpenAIResponses(id="gpt-5.2"),
db=db,
add_history_to_context=True,
learning=LearningMachine(
session_context=SessionContextConfig(),
),
)
```
What gets captured: what's being worked on, key decisions made, current state, open questions.
## Planning Mode [#planning-mode]
Enable planning to track goals, plan steps, and progress. Learning starts before the current response, so include chat history to make the assistant's earlier plan available to later extraction and follow-up requests.
```python
from agno.learn import LearningMachine, SessionContextConfig
agent = Agent(
model=OpenAIResponses(id="gpt-5.2"),
db=db,
add_history_to_context=True,
learning=LearningMachine(
session_context=SessionContextConfig(enable_planning=True),
),
)
agent.print_response(
"Help me deploy a Python app to production. Give me the steps.",
user_id="alice@example.com",
session_id="deploy_app",
)
# Later, progress is tracked
agent.print_response(
"Done with step 1. What's next?",
user_id="alice@example.com",
session_id="deploy_app",
)
```
## Data Model [#data-model]
| Field | Description |
| ------------ | ------------------------------------------------- |
| `session_id` | Unique session identifier |
| `user_id` | User this session belongs to |
| `summary` | What's been discussed |
| `goal` | What user is trying to accomplish (planning mode) |
| `plan` | Steps to achieve goal (planning mode) |
| `progress` | Completed steps (planning mode) |
| `created_at` | When created |
| `updated_at` | Last update |
## Accessing Session Context [#accessing-session-context]
```python
lm = agent.learning_machine
context = lm.session_context_store.get(session_id="api_design")
if context:
print(f"Summary: {context.summary}")
if context.goal:
print(f"Goal: {context.goal}")
# Debug output
lm.session_context_store.print(session_id="api_design")
```
## Context Injection [#context-injection]
Session context is injected into the system prompt:
```
Summary: Helping user design a REST API for a todo app. Discussed resource naming conventions. Currently exploring HTTP methods for CRUD operations.
Goal: Design complete REST API for todo application
Plan:
1. Define resource endpoints
2. Choose HTTP methods for each operation
3. Design request/response schemas
4. Add authentication
Completed:
✓ Define resource endpoints
```
## When to Use [#when-to-use]
Session context is essential when:
* **Message history gets truncated**: long conversations lose early context
* **Sessions are resumed**: user returns after a break
* **Complex multi-step tasks**: track progress through long workflows
* **Handoffs**: another agent or human needs to understand the state
## Combining with Other Stores [#combining-with-other-stores]
Session context works well alongside user-level stores:
```python
from agno.learn import LearningMachine, SessionContextConfig
agent = Agent(
model=OpenAIResponses(id="gpt-5.2"),
db=db,
add_history_to_context=True,
learning=LearningMachine(
user_profile=True, # Who the user is
session_context=SessionContextConfig(enable_planning=True), # Current state
),
)
```
This pairs long-term user knowledge with short-term session state.