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
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
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
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
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
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
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
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
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
toJSON()
toJSON():
string
Defined in: packages/agentos/src/orchestration/checkpoint/SqlCheckpointStore.ts:369
Redacts the adapter and its connection details.
Returns
string