Memory API

Memory persists state across runs. Task outputs are per-run; memory is per-namespace and survives every workflow execution. The store keeps three kinds of state: namespaced facts (JSON values with optional TTL), ordered message threads, and append-only notes (durable knowledge with supersession and a status gate). All memory values and non-generic types are re-exported from the smithers-orchestrator facade, which is canonical. The smithers-orchestrator/memory subpath exports the same surface.

import {
  createMemoryStore,
  createHindsightMemoryStore,
  HindsightMemoryStore,
  createMemoryLayer,
  MemoryService,
  Summarizer,
  TokenLimiter,
  TtlGarbageCollector,
  namespaceToString,
  parseNamespace,
} from "smithers-orchestrator";
import type {
  MemoryNamespace,
  MemoryNamespaceKind,
  MemoryFact,
  MemoryThread,
  MemoryMessage,
  MemoryStore,
  MemoryServiceApi,
  MemoryProcessor,
  MemoryProcessorConfig,
  MemoryLayerConfig,
  HindsightMemoryStoreOptions,
  TaskMemoryConfig,
  SemanticRecallConfig,
  MessageHistoryConfig,
} from "smithers-orchestrator";

createMemoryStore(db) preserves the local SQLite implementation. Pass that store as contractStore when constructing the Hindsight adapter:

const contractStore = createMemoryStore(db);
const memory = createHindsightMemoryStore({
  baseUrl: process.env.HINDSIGHT_URL!,
  contractStore,
  apiKey: process.env.HINDSIGHT_API_KEY,
});

The contract store remains authoritative for atomic exact records and global message and note ids. Hindsight projection is best-effort: a remote failure is logged and queued for an in-process retry, but it does not reject a contract mutation that already committed. The queue is not durable across process restarts. The HindsightMemoryStore class is exported for callers that need its recallMemory, getPrimers, or retainMemory engine-facing methods.

The note types (MemoryNote, SaveNoteInput, NoteReadFilter, and MemoryProvenance) are exported from the smithers-orchestrator/memory subpath. WorkingMemoryConfig<T> is generic over a Zod schema and is documented inline below. Task can be imported directly or taken from createSmithers; both expose the same memory prop. See Memory for the declarative <Task memory={...}> metadata.

Concepts

A MemoryNamespace scopes everything you store. Pick the kind to match the lifetime of the data, and the id to identify the specific workflow, agent, or user.

type MemoryNamespace = { kind: MemoryNamespaceKind; id: string };
type MemoryNamespaceKind = "workflow" | "agent" | "user" | "global";

kind

"workflow" | "agent" | "user" | "global"

required

Lifetime scope. workflow is per workflow definition, agent per agent identity, user per end user, global shared across everything.

string

required

Identifier within the kind.

A fact is a namespaced JSON value, last-write-wins, with an optional TTL.

MemoryFact

object

Show MemoryFact

namespace

string

required

The namespace, serialized via namespaceToString.

key

string

required

Fact key, unique within the namespace.

valueJson

string

required

The value, JSON-stringified.

schemaSig

string | null

Optional schema signature for the stored value.

createdAtMs

number

required

Creation time, epoch milliseconds.

updatedAtMs

number

required

Last-write time, epoch milliseconds.

ttlMs

number | null

Time-to-live in milliseconds. Expired facts are removed by deleteExpiredFacts and TtlGarbageCollector.

A thread groups ordered messages.

MemoryThread

object

Show MemoryThread

threadId

string

required

Thread identifier.

namespace

string

required

Owning namespace, serialized.

title

string | null

Optional human-readable title.

metadataJson

string | null

Optional JSON metadata.

createdAtMs

number

required

updatedAtMs

number

required

MemoryMessage

object

Show MemoryMessage

string

required

Message identifier.

threadId

string

required

Owning thread.

role

string

required

Message role, e.g. "user", "assistant", "system".

contentJson

string

required

Message content, JSON-stringified.

runId

string | null

Run that produced the message, if any. Use RUN_ID.

nodeId

string | null

Node that produced the message, if any. Use NODE_ID.

createdAtMs

number

required

Creation time, epoch milliseconds. Optional on saveMessage input (defaults to now).

A note is append-only knowledge. Facts are mutable KV (upsert semantics); notes are immutable rows: body, labels, and provenance never change after insert. status is the one deliberate exception: setNoteStatus lets a human or workflow gate write an answer about an existing note without churning its id. Notes carry no TTL: knowledge dies by supersession or rejection, not by clock.

MemoryNote

object

Show MemoryNote

string

required

Note identifier. Pass your own on saveNote to make retries idempotent.

namespace

string

required

Owning namespace, serialized via namespaceToString.

body

string

required

The knowledge itself. Immutable after insert.

kind

string | null

Optional, policy-free label (e.g. "lesson", "runbook-rule"). The engine never interprets it.

tagsJson

string | null

JSON-encoded string array; null when the note has no tags.

author

string | null

Optional, policy-free author label.

status

string

required

Free-form; defaults to "accepted". Conventionally pending | accepted | rejected. The one mutable field.

statusChangedAtMs

number | null

When setNoteStatus last flipped the status; null until then.

createdAtMs

number

required

Creation time, epoch milliseconds.

runId / nodeId / iteration

string | string | number | null

Provenance: the run coordinate that wrote the note (see MemoryProvenance).

MemoryProvenance is the run coordinate a memory write was made from. It is passed explicitly by the caller on setFact and saveNote, never inferred from ambient context, which does not survive agent/tool boundaries.

type MemoryProvenance = {
  runId?: string | null;
  nodeId?: string | null;
  iteration?: number | null;
};

SaveNoteInput is the saveNote argument: the namespace as the structured object, tags as an array, plus optional kind, author, status, provenance, supersedes (note ids this note replaces; junction rows are written atomically with the note), and id (pass one to make retries idempotent). NoteReadFilter shapes listNotes/searchNotes reads. The default read contract (no filter) is a stability contract: it returns notes that are (a) not superseded by an accepted note and (b) status = "accepted". A pending or rejected superseder hides nothing. Filters widen or narrow:

type NoteReadFilter = {
  status?: string | string[] | "any";
  includeSuperseded?: boolean;
  kind?: string;
  namespace?: MemoryNamespace; // scope searchNotes to one namespace of the kind
};

createMemoryStore

Build a MemoryStore over a Drizzle SQLite handle. Synchronous. Create one at module scope and reuse it across tasks rather than re-opening the database in every task body.

function createMemoryStore(db: BunSQLiteDatabase<any>): MemoryStore;

BunSQLiteDatabase

required

A Drizzle bun-sqlite database handle. The memory tables are created on the same database your workflow uses.

import { createMemoryStore } from "smithers-orchestrator";
import { Database } from "bun:sqlite";
import { drizzle } from "drizzle-orm/bun-sqlite";

const store = createMemoryStore(drizzle(new Database("smithers.db")));
const ns = { kind: "workflow" as const, id: "code-review" };

await store.setFact(ns, "model", "gpt-4");
const fact = await store.getFact(ns, "model"); // MemoryFact | undefined
const all = await store.listFacts(ns);

MemoryStore

The Promise-based read/write surface. Every method has an Effect-returning twin (getFactEffect, setFactEffect, listThreadsEffect, deleteMessagesEffect, and so on) with the same arguments, for use inside an Effect pipeline.

Facts

methods

Show fact methods

getFact

(ns, key) => Promise<MemoryFact | undefined>

setFact

(ns, key, value, ttlMs?) => Promise<void>

Last-write-wins. value is any JSON-serializable value; ttlMs sets an optional expiry.

deleteFact

(ns, key) => Promise<void>

listFacts

(ns) => Promise<MemoryFact[]>

deleteExpiredFacts

() => Promise<number>

Removes facts whose TTL has elapsed. Returns the count deleted.

Notes

methods

Show note methods

saveNote

(input: SaveNoteInput) => Promise<MemoryNote>

Appends a note and its supersession edges atomically. Idempotent on id: a re-save with the same id is a no-op (never an upsert, so history cannot be destroyed), and the returned note is the row the database holds, not the ignored input.

getNote

(id) => Promise<MemoryNote | undefined>

listNotes

(ns, filter?) => Promise<MemoryNote[]>

Notes in one namespace, oldest first, under the default read contract (accepted, not superseded by an accepted note) unless filter widens.

setNoteStatus

(id, status) => Promise<void>

The one mutable write: flips status and stamps statusChangedAtMs. Fails loud when the note does not exist.

enableNoteSearch

(kind) => Promise<void>

Opts a namespace kind into FTS note search. Creates the FTS5 artifacts lazily on first call and backfills existing notes of that kind; until then note writes pay nothing per write. Idempotent.

searchNotes

(kind, query, limit?, filter?) => Promise<MemoryNote[]>

Full-text search over note bodies, rank order, honoring the same read contract as listNotes. Fails loud, not silently empty, when the kind was never enabled. The index spans every namespace of the kind; pass filter.namespace to keep results namespace-local on a shared database. The read contract is applied to the top limit * 5 FTS matches, so a heavily superseded corpus can return fewer than limit even when more live matches exist further down the rank order.

Note writes and search require the bun:sqlite backend: transactions provide note+edge atomicity and FTS5 provides search. Migration 0023 creates the note tables on Postgres/PGlite, but the runtime still rejects saveNote and enableNoteSearch there with DB_WRITE_FAILED, and searchNotes with DB_QUERY_FAILED.

Threads & messages

methods

Thread and message reads/writes use the portable Drizzle tables. The transactional deleteThread operation is the exception: it currently requires bun:sqlite and raises DB_WRITE_FAILED on Postgres/PGlite.

Show thread and message methods

createThread

(ns, title?) => Promise<MemoryThread>

getThread

(threadId) => Promise<MemoryThread | undefined>

listThreads

() => Promise<MemoryThread[]>

deleteThread

(threadId) => Promise<void>

saveMessage

(msg) => Promise<void>

msg is a MemoryMessage with an optional createdAtMs (defaults to now).

listMessages

(threadId, limit?) => Promise<MemoryMessage[]>

countMessages

(threadId) => Promise<number>

deleteMessages

(threadId, messageIds) => Promise<number>

Deletes the named messages. Returns the count deleted. Used by processors to compact history.

MemoryService

An Effect Context.Tag whose service value is a MemoryServiceApi. It exposes the same operations as the store, but every method returns Effect.Effect<T, SmithersError> instead of a Promise. The underlying store is reachable via .store.

MemoryServiceApi

object

Show members

getFact / setFact / deleteFact / listFacts

Effect

Fact operations, Effect-returning. setFact(ns, key, value, ttlMs?).

createThread / getThread / deleteThread

Effect

Thread lifecycle, Effect-returning.

saveMessage / listMessages / countMessages

Effect

Message operations, Effect-returning.

saveNote / getNote / listNotes / setNoteStatus / enableNoteSearch / searchNotes

Effect

Note operations, Effect-returning, with the same semantics as the store methods above.

deleteExpiredFacts

() => Effect<number, SmithersError>

store

MemoryStore

The underlying Promise-and-Effect store, for the few methods the service does not surface directly (e.g. listThreads, deleteMessages).

createMemoryLayer

Build the Effect Layer that provides MemoryService. Pass it a MemoryLayerConfig carrying the Drizzle database; provide the resulting layer to any Effect that depends on MemoryService.

function createMemoryLayer(
  config: MemoryLayerConfig,
): Layer.Layer<MemoryService, never, never>;

config

MemoryLayerConfig

required

Show MemoryLayerConfig

BunSQLiteDatabase

required

The Drizzle bun-sqlite handle the memory tables live on.

import { Effect } from "effect";
import { createMemoryLayer, MemoryService } from "smithers-orchestrator";

const program = Effect.gen(function* () {
  const memory = yield* MemoryService;
  yield* memory.setFact({ kind: "user", id: "u1" }, "tier", "pro");
});

Effect.runPromise(program.pipe(Effect.provide(createMemoryLayer({ db }))));

Processors

A MemoryProcessor is a named maintenance pass over a MemoryStore. Each exposes a Promise process(store) and an Effect processEffect(store).

type MemoryProcessor = {
  name: string;
  process: (store: MemoryStore) => Promise<void>;
  processEffect: (store: MemoryStore) => Effect.Effect<void, SmithersError>;
};

Summarizer

(agent) => MemoryProcessor

Compresses older messages in each thread into a single system summary message, keeping the two most recent. agent is any { run: (prompt: string) => Promise<unknown> }; its output text becomes the summary.

TokenLimiter

(maxTokens) => MemoryProcessor

Trims oldest messages per thread until each thread fits a rough token budget (approximated as maxTokens * 4 characters).

TtlGarbageCollector

() => MemoryProcessor

Deletes expired facts across all namespaces by calling deleteExpiredFacts.

MemoryProcessorConfig selects which named processors to run.

MemoryProcessorConfig

object

Show MemoryProcessorConfig

processors

string[]

Names of the processors to run, e.g. ["Summarizer", "TtlGarbageCollector"].

import { TtlGarbageCollector, Summarizer } from "smithers-orchestrator";

await TtlGarbageCollector().process(store);
await Summarizer(myAgent).process(store);

Task-level config

TaskMemoryConfig is the shape of the memory prop on Task. A bank or banks selection activates engine recall, primers, retention, and tools.

memory

TaskMemoryConfig

Show TaskMemoryConfig

bank

string

One memory bank. Mutually exclusive with banks.

banks

string[]

Memory banks recalled in parallel. Mutually exclusive with bank.

Helpers

Namespaces are stored as strings. These two helpers round-trip a MemoryNamespace to and from its canonical kind:id form, percent-encoding : and % in the id.

namespaceToString

(ns: MemoryNamespace) => string

Serializes a namespace, e.g. { kind: "user", id: "u1" } becomes "user:u1".

parseNamespace

(str: string) => MemoryNamespace

Parses a serialized namespace back. Strings without a known kind prefix parse as { kind: "global", id: str }.

import { namespaceToString, parseNamespace } from "smithers-orchestrator";

namespaceToString({ kind: "user", id: "u1" }); // "user:u1"
parseNamespace("workflow:code-review"); // { kind: "workflow", id: "code-review" }

Cross-run facts are also viewable from the CLI:

bunx smithers-orchestrator memory

Source store/MemoryStore.ts · MemoryServiceApi.ts · MemoryNote.ts · createMemoryLayer.js · processors.js · Tests store.test.js · notes.test.js · service.test.js · processors.test.js · See also Memory, Types reference

Overview

Core API

Runtime

Types & errors

Gateway RPC

Concepts

createMemoryStore

MemoryStore

MemoryService

createMemoryLayer

Processors

Task-level config

Helpers

​Concepts

​createMemoryStore

​MemoryStore

​MemoryService

​createMemoryLayer

​Processors

​Task-level config

​Helpers

Concepts

createMemoryStore

MemoryStore

MemoryService

createMemoryLayer

Processors

Task-level config

Helpers