franalgaba__grimoire/docs/reference/state-persistence.md

State Persistence Reference

State persistence is implemented via StateStore and used by CLI wrappers in packages/cli/src/commands/state-helpers.ts.

Lifecycle

Default CLI flow (simulate, cast):

1. Load prior persistent state by spell ID.
2. Execute spell with persistentState.
3. Save new persistent state.
4. Append run record.
5. Save ledger entries for run.

--no-state bypasses this flow.

Database

Default SQLite path:

• .grimoire/grimoire.db

Configurable via:

• --state-dir <dir> (CLI)
• SqliteStateStore({ dbPath }) (API)

Schema tables:

• spell_state: latest persistent state per spell
• runs: execution history
• ledger: ledger event arrays per run

Pruning:

• maxRuns defaults to 100 in SqliteStateStore
• older runs are pruned on insert

API

StateStore interface:

interface StateStore {
  load(spellId: string): Promise<Record<string, unknown> | null>;
  save(spellId: string, state: Record<string, unknown>): Promise<void>;
  addRun(spellId: string, run: RunRecord): Promise<void>;
  getRuns(spellId: string, limit?: number): Promise<RunRecord[]>;
  saveLedger(spellId: string, runId: string, entries: LedgerEntry[]): Promise<void>;
  loadLedger(spellId: string, runId: string): Promise<LedgerEntry[] | null>;
  listSpells(): Promise<string[]>;
}

Run record helper:

• createRunRecord(executionResult, provenance?)

Session Views

Derived rollups in runtime:

• getSessionLedgerView(store, spellId, limit?)
• getSessionPnlView(store, spellId, limit?)

history <spell> uses these to print:

• run counts and trigger distribution
• receipt status counts
• value-delta-derived P&L/accounting summary

Node/Bun Compatibility

SqliteStateStore behavior:

• Bun: uses bun:sqlite
• Node: uses better-sqlite3 via adapter

If running in Node without better-sqlite3, store initialization throws an install hint.

Operational Notes

• Ledger entries are stored as JSON (with bigint values stringified by replacer when needed).
• runId and timestamps are generated by runtime context.
• Persistent and ephemeral runtime state are distinct; only persistent state is saved across runs.