Session Stores

Unified memory, SQLite, Postgres, Redis, MySQL, MongoDB, and libSQL/Turso persistence.

For new Node applications, configure a complete persistence bundle rather than a session store in isolation. A bundle keeps session history, durable submissions, conversation offsets, attachments, run events, cost totals, health, and deletion on one backend:

.fabricharness/config.ts

import { sqlitePersistence } from '@fabric-harness/node';

export default {
  persistence: sqlitePersistence({
    path: '.fabricharness/fabric-harness.sqlite',
  }),
};

Use memoryPersistence() for ephemeral tests, sqlitePersistence() for a durable single process, and postgresPersistence() or redisPersistence() for high-throughput multiple replicas. mysqlPersistence(), mongodbPersistence(), and libsqlPersistence() provide the same complete contract through version-fenced snapshots for moderate operational state. Third-party backends can verify the same behavior with definePersistenceBundleContractTests from @fabric-harness/sdk/testing/contracts.

The session store is where Fabric persists session entries, events, tasks, approvals, checkpoints, and artifact metadata. The default is a file store. The full notes live in docs/session-stores.md.

First-party stores implement SessionStore.appendEntries() for one atomic, ordered entry batch. The optional expectedLeafId is a compare-and-swap fence: a stale writer receives false, an exact replay is a successful no-op, and reuse of an entry id with different content fails. Harness uses this boundary to settle interrupted tool calls, task ends, and recovery advisories together, so a process crash cannot expose a partially repaired session. Third-party stores that implement the method should provide the same semantics.

Backends

Backend	Where it stores	When to use
File (default)	`.fabricharness/sessions/<id>/`	Local development, CI smoke tests, single-host services.
SQLite	`.fabricharness/sessions.sqlite` (configurable)	Single-host services that want SQL queries and `BEGIN IMMEDIATE` atomic batches.
Postgres	external Postgres	Multi-host services, Temporal worker fleets, production.
Redis / Valkey	external Redis-compatible cluster	Multi-host services needing low-latency leases, offsets, retention TTLs, and atomic budgets.
MySQL	versioned snapshot rows in MySQL 8	Existing MySQL estates with moderate agent-state write volume.
MongoDB	versioned snapshot documents	Existing Mongo deployments; standalone or replica set.
libSQL / Turso	local file or remote versioned snapshot rows	Lightweight local/serverless deployments with moderate state.

Configuration

.fabricharness/config.ts:

export default {
  store: {
    backend: 'sqlite',
    path: '.fabricharness/sessions.sqlite',
  },
};

export default {
  store: {
    backend: 'postgres',
    connectionString: process.env.DATABASE_URL,
  },
};

What gets stored

For each session:

session header (id, created, updated, agent),
ordered entries (prompts, assistant turns, tool calls, shell commands, task events, approvals, compactions, checkpoints),
the event stream,
artifact metadata + content (or external blob URLs),
task records,
approval records.

Examples

examples/with-config — central config including SQLite session storage.
examples/with-postgres-store — Postgres-backed session/artifact storage.
examples/database-persistence — select libSQL/Turso, MySQL, or MongoDB from one config.