Skip to main content

​
Sessions

Sessions are 6-hour windows where agents are active and can access memories.

​
Session Lifecycle

Inactive Agent
     ↓ (activate)
ACTIVE SESSION (6 hours)
     ├─ Can store memories
     ├─ Can recall memories
     ├─ Can answer questions
     └─ Session expires after 6 hours
     ↓ (after 6 hours or deactivate)
Inactive Agent
     ↓ (reactivate later)
New Session (with access to all old memories)

​
Why Sessions?

Sessions serve two purposes:
  1. Authentication - Session token proves you’re authorized
  2. State Management - Clear boundary between conversation periods

​
Session Properties

Each session has:
  • Agent ID - Which agent is active
  • Session Token - JWT for authentication
  • Created At - When session started
  • Expires At - When session ends (6 hours)
  • Duration - How long agent has been active

​
Session Examples

​
Example 1: Single Agent, Multiple Sessions

Day 1, Morning (8am-2pm)
  Session 1 Active
  - Learn customer preferences
  - Store 5 memories

Day 1, Afternoon (3pm-9pm)
  Session 1 Expired (6 hours passed)
  Session 2 Activated
  - Recall preferences from Session 1
  - Serve customers with context
  - Store 8 more memories

Day 2, Morning (9am-3pm)
  Session 2 Expired
  Session 3 Activated
  - Recall all 13 memories
  - Continue with full context
All memories persist across sessions.

​
Example 2: Multiple Agents, Concurrent Sessions

Time: 2pm on March 30

Customer Support Agent
  └─ Session Active
     ├─ Helping customers
     └─ Recalling customer history

Project Manager Agent
  └─ Session Active
     ├─ Tracking project progress
     └─ Recalling decisions

Research Bot
  └─ Session Active
     ├─ Analyzing papers
     └─ Recalling previous findings

(All three agents active simultaneously with separate sessions)

​
Extending Sessions

Default session is 6 hours. Extend if you need longer: 
Session expires in 1 hour
           ↓ (extend by 6 hours)
Session now expires in 7 hours
           ↓ (extend by 12 hours)
Session now expires in 19 hours
Use cases for extending:
  • Long-running batch operations
  • Overnight processing
  • Extended interactive sessions
  • Continuous monitoring

​
Session vs Memory

Important distinction:
  • Session - Temporary authentication window (6 hours max)
  • Memory - Persistent data (survives sessions)
Session A expires
    ↓
Memories REMAIN
    ↓
New Session B can access old memories

​
Token Security

Session tokens are JWTs (JSON Web Tokens): 
Token = Base64(Header.Payload.Signature)
Contains:
  • Agent ID
  • Expiry time
  • Signature (validates authenticity)
Never:
  • Log tokens
  • Hardcode in code
  • Share between users
  • Store permanently

​
Practical Workflow

​
Long-Running Agent

import httpx
import time

api_key = "mk_key"
agent_id = "continuous-bot"
base = "http://localhost:8000/api/v2"

# 1. Activate session
activate = httpx.post(
    f"{base}/agents/{agent_id}/activate",
    headers={"Authorization": f"Bearer {api_key}"}
)
token = activate.json()["session_token"]

# 2. Process for hours
while True:
    # Do work...
    httpx.post(
        f"{base}/agents/{agent_id}/remember",
        params={"content": "...", "type": "fact"},
        headers={
            "Authorization": f"Bearer {api_key}",
            "X-Session-Token": token
        }
    )

    # Check if expiring soon
    check = httpx.get(
        f"{base}/session/current",
        headers={
            "Authorization": f"Bearer {api_key}",
            "X-Session-Token": token
        }
    )
    remaining = check.json()["time_remaining_minutes"]

    # Extend if less than 1 hour left
    if remaining < 60:
        httpx.post(
            f"{base}/session/extend",
            params={"extend_hours": 6},
            headers={
                "Authorization": f"Bearer {api_key}",
                "X-Session-Token": token
            }
        )
        print("Session extended")

    time.sleep(300)  # Check every 5 minutes

​
Best Practices

​
DO

  • Extend sessions proactively (before expiry)
  • One session per agent at a time
  • Store session token securely
  • Monitor expiry times
  • Activate new session if token expires

​
DON’T

  • Let sessions expire during critical work
  • Create multiple sessions for same agent simultaneously
  • Log or expose tokens
  • Assume session is permanent
  • Reuse expired tokens

​
Next Steps