#Sessions

A session is a persistent, resumable conversation. With createLiteAgent, every run is event-sourced to disk through a Checkpointer, and the agent owns a current session: successive send() calls share the full conversation, you can list and resume past sessions across restarts, and you can roll a session back to any earlier prompt. You get durable multi-turn agents without writing any storage code.

Nothing to enable — persistence is on by default via the built-in fileCheckpointer:

import { createLiteAgent } from "@lite-agent/sdk";
import { anthropic } from "@lite-agent/provider";

const agent = createLiteAgent({
  model: anthropic(),
  modelName: "claude-sonnet-4-6",
  workdir: process.cwd(),
});

await agent.send("Refactor src/auth.ts to use async/await.");
const result = await agent.send("Now add tests for it."); // same session, full context

#Managing sessions

LiteAgent exposes the whole session lifecycle:

const sessions = await agent.listSessions();
agent.resume(sessions[0].id);            // continue the most recent session

const checkpoints = await agent.listCheckpoints(agent.sessionId);
await agent.restore(agent.sessionId, checkpoints[2].seq); // undo everything after that prompt

Time travel works because the file tools snapshot every file before modifying it: restore replays those snapshots to undo changes on disk, then truncates the event log. See Checkpointing for the full rewind model.

Set sessions: false to keep conversation state in memory without writing a session transcript (persistent session methods then reject). User goals remain available to background completion turns until the agent is closed.

#Persisting to external storage

The default fileCheckpointer serializes each session with file locks, including async encoding. For database transactions and efficient concurrent readers, use SQLite. When several processes on one host must share sessions — an HTTP server, a worker pool, parallel CLI runs — swap in the SQLite backend from @lite-agent/checkpoint-sqlite:

pnpm add @lite-agent/checkpoint-sqlite

import { createLiteAgent } from "@lite-agent/sdk";
import { anthropic } from "@lite-agent/provider";
import { sqliteCheckpointer } from "@lite-agent/checkpoint-sqlite";

const checkpointer = sqliteCheckpointer({ file: "./sessions.db" }); // or ":memory:"

const agent = createLiteAgent({
  model: anthropic(),
  modelName: "claude-sonnet-4-6",
  workdir: process.cwd(),
  checkpointer,
});

await agent.send("Hello!");
// Sessions persist to sessions.db, shared across processes on this host.

checkpointer.close(); // when you're done

The SQLite backend gives you WAL-based concurrent readers, atomic seq allocation, and optimistic concurrency: a stale writer gets a clean CheckpointConflictError instead of silently clobbering the log. Any custom backend that implements the core Checkpointer interface (append / read / head / list / delete / truncate) works the same way — pass it via the checkpointer (or store) option, which overrides sessions.

#See also

• Checkpointing — the listCheckpoints / restore time-travel model in detail.
• Events — the SessionEvent stream that gets persisted.
• Agent loop — what happens inside each turn of a session.

close() aborts active foreground streams, background work and maintenance operations before releasing owned state. Approval and input handlers accept an optional second AbortSignal; use it to dismiss prompts. Custom tools/providers must cooperate with cancellation. Deleting a session removes its archive and its private task list; explicitly shared task lists remain.

Configure the directory namespace and runtime encoding through Storage and namespaces. Custom checkpoint backends own their serialization.