AI SDK - Session Log

This package is experimental.

Append-only event log for durable agent sessions. Append events and pass references from workflow steps; resume a session by reading the log.

Event ids are caller-supplied. Re-appending an id returns the stored event unchanged, so deterministic ids (`${turn}:${seq}`) are safe inside a retried durable step. payload is any JSON. watch() streams appends as they land.

Setup

npm i ai-sdk-session-log

Usage

import { jsonlSessionLog } from 'ai-sdk-session-log';

const log = jsonlSessionLog({ sessionId: 's1', dir: '.sessions' });
await log.append([
  {
    id: '0:0',
    type: 'message',
    turn: 0,
    payload: { role: 'user', content: 'hi' },
  },
  {
    id: '0:1',
    type: 'message',
    turn: 0,
    payload: { role: 'assistant', content: 'hello' },
  },
]);

for await (const event of log.read({ types: ['message'] })) {
  // project into AI SDK messages, a UI stream, or analytics
}

Backends

| Backend | Import | Use | | --- | --- | --- | | memorySessionLog | ai-sdk-session-log | Tests and ephemeral sessions. | | jsonlSessionLog | ai-sdk-session-log | Local and single-process runtimes. One <sessionId>.jsonl per session. | | sqliteSessionLog | ai-sdk-session-log/sqlite | Single-writer deployments. Uses node:sqlite (Node >= 22.5). The subpath keeps that import off the main entry. | | durableObjectSessionLog | ai-sdk-session-log/durable-object | A Durable Object's SQLite (ctx.storage.sql). |

SessionLog is the whole contract if you need another backend. All shipped backends run one shared test suite (session-log.shared.test.ts).

Blob store

Engines cap checkpoint sizes (1 MiB on Cloudflare Workflows, 2 MB on Temporal). BlobStore keeps large payloads out of line:

import { fsBlobStore } from 'ai-sdk-session-log';

const blobs = fsBlobStore({ dir: '.sessions/blobs' });
const ref = await blobs.put('s1/turn-3/tool-output', bigText);
await log.append([{ id: '3:2', type: 'tool', payload: { output: ref } }]);

memoryBlobStore and fsBlobStore ship here. An R2 or S3 store implements the same four methods.

License

Apache-2.0