Skip to main content

Class: SqlCheckpointStore

Defined in: packages/agentos/src/orchestration/checkpoint/SqlCheckpointStore.ts:204

ICheckpointStore over a @framers/sql-storage-adapter store, with the behaviour of InMemoryCheckpointStore: a checkpoint saved again under its id is overwritten, the most recent checkpoint has the latest timestamp and, of checkpoints with the same timestamp, was saved last, and fork() merges each patchState partition into a copy of the source.

Every save takes the next save_seq, one more than the largest in the table, in the statement that writes the row, and a save under an id that exists takes a new one, so a save that starts after another has finished takes the larger number. A store runs its own saves one after another, in the order they were called, so saves of one store that overlap, as a parallel batch's branches make them, take numbers in that order, as InMemoryCheckpointStore keeps them: the save called last is the most recent, and a resume from it skips every branch it records. Saves of two stores, or two processes, that overlap can take the same number on Postgres; id orders them.

Each statement is one statement, so the store needs no transaction. A read, a save and a delete make the table first unless ensureSchema is false.

Example​

import { resolveStorageAdapter } from '@framers/sql-storage-adapter';
import { SqlCheckpointStore } from '@framers/agentos/orchestration/checkpoint';

const db = await resolveStorageAdapter({ filePath: './checkpoints.sqlite' });
const graph = new AgentGraph(state).compile({ checkpointStore: new SqlCheckpointStore({ db }) });

Implements​

Constructors​

Constructor​

new SqlCheckpointStore(options): SqlCheckpointStore

Defined in: packages/agentos/src/orchestration/checkpoint/SqlCheckpointStore.ts:220

Parameters​

options​

SqlCheckpointStoreOptions

The adapter, the table's prefix and whether the store makes its table.

Returns​

SqlCheckpointStore

Throws​

When tablePrefix is not a lower-case letter followed by at most 52 lower-case letters, digits or underscores.

Methods​

delete()​

delete(checkpointId): Promise<void>

Defined in: packages/agentos/src/orchestration/checkpoint/SqlCheckpointStore.ts:326

Permanently remove a checkpoint from the store.

Silently succeeds when checkpointId does not exist.

Parameters​

checkpointId​

string

The checkpoint to remove.

Returns​

Promise<void>

Implementation of​

ICheckpointStore.delete


ensureSchema()​

ensureSchema(): Promise<void>

Defined in: packages/agentos/src/orchestration/checkpoint/SqlCheckpointStore.ts:239

Creates the table and its indexes unless the table answers a read already, so a store over a table that exists runs no DDL: on Postgres each CREATE INDEX takes a SHARE lock on the table, which holds back its writes, before it looks for the index's name. Called before the first statement; safe to call again. Does nothing with ensureSchema: false.

Another session can make the table between the read and the DDL: two stores starting on an empty database both find it missing. On Postgres the DDL of the one that loses then fails once the other commits, IF NOT EXISTS notwithstanding, on the catalogue's unique index or as a duplicate table. The DDL runs again on such a failure, as the memory and learning stores run their schema steps, and finds what the other made, so the table and every index exist when it completes. Any other failure rejects, and the next call tries again.

Returns​

Promise<void>


fork()​

fork(checkpointId, patchState?): Promise<string>

Defined in: packages/agentos/src/orchestration/checkpoint/SqlCheckpointStore.ts:336

Create a new run branching from an existing checkpoint.

The operation deep-clones the source checkpoint, assigns a fresh runId and checkpoint id, applies any patchState overrides, persists the new checkpoint, and returns the new runId.

Parameters​

checkpointId​

string

The checkpoint to fork from.

patchState?​

Partial<GraphState<unknown, unknown, unknown>>

Optional partial GraphState overrides applied after cloning.

Returns​

Promise<string>

The new runId for the forked run.

Implementation of​

ICheckpointStore.fork


get()​

get(checkpointId): Promise<Checkpoint | null>

Defined in: packages/agentos/src/orchestration/checkpoint/SqlCheckpointStore.ts:273

Load a checkpoint by its unique checkpoint identifier.

Parameters​

checkpointId​

string

The exact checkpoint id assigned at save-time.

Returns​

Promise<Checkpoint | null>

The matching checkpoint, or null when none exists.

Implementation of​

ICheckpointStore.get


latest()​

latest(runId): Promise<Checkpoint | null>

Defined in: packages/agentos/src/orchestration/checkpoint/SqlCheckpointStore.ts:296

Return the most recently persisted checkpoint for a run, or null when the run has no checkpoints. Of checkpoints with the same timestamp, the one saved last is the most recent.

Parameters​

runId​

string

The graph run identifier.

Returns​

Promise<Checkpoint | null>

Implementation of​

ICheckpointStore.latest


list()​

list(graphId, options?): Promise<CheckpointMetadata[]>

Defined in: packages/agentos/src/orchestration/checkpoint/SqlCheckpointStore.ts:307

List lightweight metadata descriptors for all checkpoints belonging to a graph.

Parameters​

graphId​

string

The compiled graph identifier.

options?​
limit?​

number

runId?​

string

Returns​

Promise<CheckpointMetadata[]>

Array of CheckpointMetadata, sorted by timestamp descending.

Implementation of​

ICheckpointStore.list


load()​

load(runId, nodeId?): Promise<Checkpoint | null>

Defined in: packages/agentos/src/orchestration/checkpoint/SqlCheckpointStore.ts:280

Load a checkpoint for the given runId.

When nodeId is supplied, returns the most recent checkpoint for that specific node within the run. When nodeId is omitted, returns the most recent checkpoint for the run regardless of node (equivalent to latest(runId)). The most recent checkpoint has the latest timestamp and, of checkpoints with the same timestamp, was saved last: the runtime can save several in one millisecond.

Parameters​

runId​

string

The graph run identifier.

nodeId?​

string

Optional node filter.

Returns​

Promise<Checkpoint | null>

The matching checkpoint, or null when none exists.

Implementation of​

ICheckpointStore.load


save()​

save(checkpoint): Promise<void>

Defined in: packages/agentos/src/orchestration/checkpoint/SqlCheckpointStore.ts:268

Persist a checkpoint snapshot.

If a checkpoint with the same id already exists it is overwritten.

The runtime awaits each save and does not retry one that rejects: the run that asked for the checkpoint ends with the store's error, which GraphRuntime.stream() throws, and a resume by the run id continues from the last checkpoint the store saved. When a save inside a parallel batch rejects, the run ends with the error once the batch's other nodes have finished.

Parameters​

checkpoint​

Checkpoint

The snapshot to persist.

Returns​

Promise<void>

Throws​

A TypeError when the checkpoint's timestamp is not a whole number of milliseconds, which created_at holds as a BIGINT; the error JSON.stringify throws on a cycle or a BigInt; an error when the database reports writing no row.

Implementation of​

ICheckpointStore.save


toJSON()​

toJSON(): string

Defined in: packages/agentos/src/orchestration/checkpoint/SqlCheckpointStore.ts:369

Redacts the adapter and its connection details.

Returns​

string