Sessions & Persistence

AgentSession

The AgentSession manages conversation persistence. Every agent has a session that stores conversation history and metadata on disk automatically.

Creating Sessions

use picrust::session::AgentSession;

// Create new session
let session = AgentSession::new(
    "unique-session-id",  // Unique identifier
    "assistant",          // Agent type (for filtering)
    "My Assistant",       // Display name
    "Helps with tasks",   // Description
)?;

// Session is immediately persisted to disk at:
// ./sessions/unique-session-id/

Session Structure

Each session creates a directory:

./sessions/unique-session-id/
├── metadata.json       # Session metadata
├── history.json        # Conversation messages
└── debugger/           # Debug logs (if enabled)
    ├── api_request_1.json
    ├── api_response_1.json
    ├── tool_call_1.json
    └── tool_result_1.json

Metadata

Session Metadata

pub struct SessionMetadata {
    pub session_id: String,
    pub agent_type: String,
    pub name: String,
    pub description: String,
    pub created_at: DateTime<Utc>,
    pub updated_at: DateTime<Utc>,
    pub conversation_name: Option<String>,
    pub parent_session_id: Option<String>,
    pub parent_tool_use_id: Option<String>,
    pub child_session_ids: Vec<String>,
    pub custom_metadata: HashMap<String, serde_json::Value>,
    pub model: Option<String>,
    pub provider: Option<String>,
}

Accessing Metadata

// From loaded session
let session = AgentSession::load("session-id")?;
println!("Created: {}", session.metadata().created_at);
println!("Type: {}", session.metadata().agent_type);

// Without loading full session
let metadata = AgentSession::get_metadata("session-id")?;
println!("Name: {}", metadata.name);

Custom Metadata

Store application-specific data:

// Through running agent
handle.set_custom_metadata("working_folder", "/path/to/project").await?;
handle.set_custom_metadata("user_preferences", serde_json::json!({
    "theme": "dark",
    "language": "en"
})).await?;

// Read it back
let folder = handle.get_custom_metadata("working_folder").await;

When an agent is running, always update metadata through the AgentHandle to avoid race conditions. The handle provides thread-safe access to the session.

Conversation History

Message Storage

Messages are stored as JSON:

[
  {
    "role": "user",
    "content": "Hello"
  },
  {
    "role": "assistant",
    "content": [
      {
        "type": "text",
        "text": "Hi! How can I help you?"
      }
    ]
  }
]

Reading History

// Get history without loading full session (efficient)
let history = AgentSession::get_history("session-id")?;

for message in history {
    match message.role.as_str() {
        "user" => println!("User: {:?}", message.content),
        "assistant" => println!("Agent: {:?}", message.content),
        _ => {}
    }
}

Message Types

Messages can contain various content types:

use picrust::llm::{Message, ContentBlock};

// Simple text
let msg = Message::user("Hello");

// With multiple blocks
let msg = Message::user_with_blocks(vec![
    ContentBlock::text("Analyze this code:"),
    ContentBlock::text("fn main() { println!(\"Hello\"); }"),
]);

// Tool use (from agent)
let msg = Message::assistant_with_blocks(vec![
    ContentBlock::text("I'll read that file for you."),
    ContentBlock::tool_use("tool_123", "Read", serde_json::json!({
        "file_path": "./README.md"
    })),
]);

// Tool result (from tool execution)
let msg = Message::user_with_blocks(vec![
    ContentBlock::tool_result("tool_123", "File contents...", false),
]);

Write-Through Persistence

Automatic Saving

Messages are written to disk immediately after each turn: This ensures conversation state survives crashes.

Manual Saving

Force a save (rarely needed):

session.save()?;

Useful if you’ve modified metadata directly.

Listing Sessions

List All Sessions

// Get all session IDs
let all_sessions = AgentSession::list_all()?;

for session_id in all_sessions {
    println!("Session: {}", session_id);
}

List Top-Level Only

Filter out subagent sessions:

// Only get parent sessions
let top_level = AgentSession::list_top_level()?;

for session_id in top_level {
    println!("Top-level session: {}", session_id);
}

List with Metadata

More efficient when you need metadata:

// Returns Vec<(String, SessionMetadata)>
let sessions = AgentSession::list_with_metadata(true)?;  // true = top-level only

for (session_id, metadata) in sessions {
    println!("{}: {} ({})",
        session_id,
        metadata.name,
        metadata.agent_type
    );
    println!("  Created: {}", metadata.created_at);
    println!("  Is subagent: {}", metadata.is_subagent());
}

Loading Sessions

Load Existing Session

// Load complete session from disk
let session = AgentSession::load("session-id")?;

// Access history
let messages = session.history();
println!("Message count: {}", messages.len());

// Access metadata
let metadata = session.metadata();
println!("Agent type: {}", metadata.agent_type);

Check Existence

if AgentSession::exists("session-id") {
    let session = AgentSession::load("session-id")?;
} else {
    let session = AgentSession::new("session-id", "type", "name", "desc")?;
}

Parent-Child Relationships

Subagent Sessions

When agents spawn subagents, sessions are linked:

// Create child session
let child_session = AgentSession::new_subagent(
    "child-session-id",
    "researcher",
    "Research Agent",
    "Finds information",
    "parent-session-id",     // Parent session ID
    "tool_use_123",          // Parent tool use ID
)?;

// Child knows its parent
assert!(child_session.is_subagent());
assert_eq!(child_session.parent_session_id(), Some("parent-session-id"));

// Parent tracks children
let parent = AgentSession::load("parent-session-id")?;
assert!(parent.child_session_ids().contains(&"child-session-id".to_string()));

Use Cases

Parent-child relationships enable:

Hierarchical agents: Parent delegates to specialized children
Conversation trees: Track conversation branches
Cleanup: Delete parent and all children together
Tracing: Follow execution across agents

Conversation Naming

Automatic Naming

StandardAgent automatically generates conversation names after the first turn:

let config = AgentConfig::new("You are helpful")
    .with_auto_name(true);  // Enabled by default

// After first turn, session gets a name like:
// "Help with Rust debugging"
// "Build a web scraper"
// "Explain async/await"

Disable automatic naming:

let config = AgentConfig::new("You are helpful")
    .with_auto_name(false);

Manual Naming

Set conversation name explicitly:

// Through running agent
handle.set_conversation_name("Debug Python script").await?;

// Or on session directly
session.set_conversation_name("My Conversation")?;

// Check if named
if session.has_conversation_name() {
    println!("Name: {}", session.conversation_name().unwrap());
}

Custom Naming LLM

Use a cheaper/faster model for naming:

let naming_llm = llm.create_variant("claude-3-5-haiku-20241022", 1024);

let config = AgentConfig::new("You are helpful")
    .with_naming_llm(naming_llm);

Session Management

Deleting Sessions

// Delete a session
session.delete()?;

// Session directory is removed from disk

Deleting a parent session does NOT automatically delete child sessions. Delete children first if needed.

Updating Metadata (Running Agents)

When an agent is running, use the handle:

// Good: Thread-safe
if let Some(handle) = runtime.get("session-id").await {
    handle.set_custom_metadata("key", "value").await?;
    handle.set_conversation_name("New Name").await?;
}

// Bad: Race condition!
let mut metadata = SessionStorage::default().load_metadata("session-id")?;
metadata.set_custom("key", "value");
// Agent might overwrite this when it saves!

Updating Metadata (Stopped Agents)

When agent is not running, direct access is safe:

use picrust::session::SessionStorage;

let mut metadata = SessionStorage::default().load_metadata("session-id")?;
metadata.set_custom("key", "value");
SessionStorage::default().save_metadata(&metadata)?;

Custom Storage Location

Change Storage Directory

use picrust::session::SessionStorage;

// Use custom directory
let storage = SessionStorage::with_dir("/custom/path/sessions");

// Create session with custom storage
let session = AgentSession::new_with_storage(
    "session-id",
    "type",
    "name",
    "desc",
    storage,
)?;

Storage Interface

Implement custom storage backends:

pub trait SessionStore {
    fn save_metadata(&self, metadata: &SessionMetadata) -> Result<()>;
    fn load_metadata(&self, session_id: &str) -> Result<SessionMetadata>;
    fn save_history(&self, session_id: &str, history: &[Message]) -> Result<()>;
    fn load_history(&self, session_id: &str) -> Result<Vec<Message>>;
    fn delete(&self, session_id: &str) -> Result<()>;
    fn list_all(&self) -> Result<Vec<String>>;
}

Could implement:

Database storage (PostgreSQL, SQLite)
Cloud storage (S3, GCS)
In-memory storage (testing)
Encrypted storage

Best Practices

1. Unique Session IDs

use uuid::Uuid;

// Generate unique IDs
let session_id = Uuid::new_v4().to_string();
let session = AgentSession::new(&session_id, "type", "name", "desc")?;

2. Meaningful Names

// Good: Descriptive
let session = AgentSession::new(
    &session_id,
    "code-assistant",
    "Python Debugger",
    "Helps debug Python code",
)?;

// Bad: Generic
let session = AgentSession::new(
    &session_id,
    "agent",
    "Agent",
    "An agent",
)?;

3. Clean Up Old Sessions

// Delete sessions older than 30 days
let sessions = AgentSession::list_with_metadata(false)?;

for (session_id, metadata) in sessions {
    let age = Utc::now() - metadata.created_at;
    if age.num_days() > 30 {
        if let Ok(session) = AgentSession::load(&session_id) {
            session.delete()?;
        }
    }
}

4. Backup Sessions

use std::fs;

// Backup session directory
let source = "./sessions/session-id";
let backup = "./backups/session-id";
fs::copy(source, backup)?;

5. Monitor Disk Usage

use walkdir::WalkDir;

fn get_sessions_size() -> u64 {
    WalkDir::new("./sessions")
        .into_iter()
        .filter_map(|e| e.ok())
        .filter(|e| e.file_type().is_file())
        .filter_map(|e| e.metadata().ok())
        .map(|m| m.len())
        .sum()
}

Advanced Patterns

Session Migrations

// Migrate old session format
let old_session = load_old_format("session-id")?;

let new_session = AgentSession::new(
    &old_session.id,
    &old_session.type_,
    &old_session.name,
    &old_session.description,
)?;

// Migrate history
for message in old_session.messages {
    new_session.add_message(convert_message(message))?;
}

new_session.save()?;

Session Templates

fn create_code_assistant_session(id: &str) -> Result<AgentSession> {
    let session = AgentSession::new(
        id,
        "code-assistant",
        "Code Assistant",
        "Helps with coding tasks",
    )?;

    // Set default metadata
    session.set_custom_metadata("preferred_language", "rust")?;
    session.set_custom_metadata("max_file_size", 1024 * 1024)?;

    Ok(session)
}

Session Cloning

// Clone session for branching conversations
let original = AgentSession::load("original-session")?;

let clone = AgentSession::new(
    "cloned-session",
    &original.metadata().agent_type,
    &format!("{} (clone)", original.metadata().name),
    &original.metadata().description,
)?;

// Copy history
for message in original.history() {
    clone.add_message(message.clone())?;
}

clone.save()?;

Next Steps

Message Flow

Understand input/output communication patterns

Streaming & History

Critical dual-channel architecture

AgentSession API

Complete session API reference

Custom Storage

Implement custom storage backends

​AgentSession

​Creating Sessions

​Session Structure

​Metadata

​Session Metadata

​Accessing Metadata

​Custom Metadata

​Conversation History

​Message Storage

​Reading History

​Message Types

​Write-Through Persistence

​Automatic Saving

​Manual Saving

​Listing Sessions

​List All Sessions

​List Top-Level Only

​List with Metadata

​Loading Sessions

​Load Existing Session

​Check Existence

​Parent-Child Relationships

​Subagent Sessions

​Use Cases

​Conversation Naming

​Automatic Naming

​Manual Naming

​Custom Naming LLM

​Session Management

​Deleting Sessions

​Updating Metadata (Running Agents)

​Updating Metadata (Stopped Agents)

​Custom Storage Location

​Change Storage Directory

​Storage Interface

​Best Practices

​1. Unique Session IDs

​2. Meaningful Names

​3. Clean Up Old Sessions

​4. Backup Sessions

​5. Monitor Disk Usage

​Advanced Patterns

​Session Migrations

​Session Templates

​Session Cloning

​Next Steps

Message Flow

Streaming & History

AgentSession API

Custom Storage

AgentSession

Creating Sessions

Session Structure

Metadata

Session Metadata

Accessing Metadata

Custom Metadata

Conversation History

Message Storage

Reading History

Message Types

Write-Through Persistence

Automatic Saving

Manual Saving

Listing Sessions

List All Sessions

List Top-Level Only

List with Metadata

Loading Sessions

Load Existing Session

Check Existence

Parent-Child Relationships

Subagent Sessions

Use Cases

Conversation Naming

Automatic Naming

Manual Naming

Custom Naming LLM

Session Management

Deleting Sessions

Updating Metadata (Running Agents)

Updating Metadata (Stopped Agents)

Custom Storage Location

Change Storage Directory

Storage Interface

Best Practices

1. Unique Session IDs

2. Meaningful Names

3. Clean Up Old Sessions

4. Backup Sessions

5. Monitor Disk Usage

Advanced Patterns

Session Migrations

Session Templates

Session Cloning

Next Steps