Session Persistence

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

Quick Start

import { Agent, FileSessionStore } from '@a3s-lab/code';

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

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

await session.send('Refactor auth');

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

from a3s_code import Agent, FileSessionStore

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

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

session.send("Refactor auth")

# Resume
resumed = agent.resume_session("my-session",
    session_store=FileSessionStore(".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).