Session Persistence

A3S Code supports pluggable session storage backends. Sessions save conversation history and can be resumed across restarts.

Quick Start

use a3s_code_core::{Agent, SessionOptions};
use a3s_code_core::store::FileSessionStore;

let agent = Agent::new("agent.hcl").await?;

// File-based session with auto-save
let session = agent.session(".", Some(
    SessionOptions::new()
        .with_file_session_store(".a3s/sessions")
        .with_session_id("my-session")
        .with_auto_save(true)
))?;

let result = session.send("Refactor auth", None).await?;
// Session is auto-saved after each send()

// Manual save
session.save().await?;

// Resume later
let session = agent.resume_session("my-session", SessionOptions::new()
    .with_file_session_store(".a3s/sessions")
)?;
println!("Resumed with {} messages", session.history().len());

const agent = await Agent.create('agent.hcl');

// Create with auto-save
const session = agent.session('.', {
  fileSessionStore: '.a3s/sessions',
  sessionId: 'my-session',
  autoSave: true,
});

await session.send('Refactor auth');

// Resume
const resumed = agent.resumeSession('my-session', {
  fileSessionStore: '.a3s/sessions',
});

agent = Agent.create("agent.hcl")

session = agent.session(".", SessionOptions(
    file_session_store=".a3s/sessions",
    session_id="my-session",
    auto_save=True,
))

session.send("Refactor auth")

# Resume
resumed = agent.resume_session("my-session", SessionOptions(
    file_session_store=".a3s/sessions",
))

File Storage

FileSessionStore stores each session as a JSON file:

sessions_dir/
├── my-session.json
├── other-session.json
└── ...

Atomic writes (write .tmp → rename) — safe on crash
Full conversation history preserved
Human-readable JSON format

Session API

Prop

Type

Auto-Save

When with_auto_save(true) is set, the session saves after each send() call that uses internal history. Failures are logged as warnings (non-fatal).

SessionOptions::new()
    .with_file_session_store(".a3s/sessions")
    .with_auto_save(true)

Custom Storage Backend

For production deployments (PostgreSQL, Redis, S3, etc.), implement the SessionStore trait:

use a3s_code_core::store::{SessionStore, SessionData};

#[async_trait::async_trait]
impl SessionStore for PostgresStore {
    async fn save(&self, session: &SessionData) -> Result<()> { /* ... */ }
    async fn load(&self, id: &str) -> Result<Option<SessionData>> { /* ... */ }
    async fn delete(&self, id: &str) -> Result<()> { /* ... */ }
    async fn list(&self) -> Result<Vec<String>> { /* ... */ }
    async fn exists(&self, id: &str) -> Result<bool> { /* ... */ }
}

// Use it
let session = agent.session(".", Some(
    SessionOptions::new()
        .with_session_store(Arc::new(PostgresStore::new(...).await?))
))?;