Memory API

Memory persists state across runs: task outputs are per-run, memory is per-namespace. The store keeps three kinds of state, detailed below: namespaced facts, ordered message threads, and append-only notes. All memory values and non-generic types are re-exported from the canonical smthrs facade; the smthrs/memory subpath exports the same surface.

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

createMemoryStore(db) preserves the local SQLite implementation; pass it 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,
});

HINDSIGHT_URL is the base URL of a reachable Hindsight deployment: http://127.0.0.1:8888 for the default self-hosted Docker image, or a Hindsight Cloud workspace URL. Obtaining one (cloud signup or self-host deploy) is a human step, covered in the Product API at Set Up Semantic Memory; HINDSIGHT_API_KEY is the bearer token for endpoints that require one. The contract store stays authoritative for atomic exact records and global message/note ids; Hindsight projection is best-effort, logging and queueing a remote failure for in-process retry (not durable across restarts) without rejecting an already-committed contract mutation. HindsightMemoryStore is exported for its recallMemory, getPrimers, and retainMemory engine-facing methods.

Note types (MemoryNote, SaveNoteInput, NoteReadFilter, MemoryProvenance) are exported from smthrs/memory. WorkingMemoryConfig<T> is generic over a Zod schema (documented below). Task, imported directly or from createSmithers, exposes the same memory prop; see Memory for the declarative <Task memory={...}> metadata.

Concepts

A MemoryNamespace scopes everything you store: kind matches the data’s lifetime, id identifies the specific workflow, agent, or user.

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

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

required

Lifetime scope: workflow 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.

object

Show MemoryFact

string

required

The namespace, serialized via namespaceToString.

string

required

Fact key, unique within the namespace.

string

required

The value, JSON-stringified.

string | null

Optional schema signature for the stored value.

number

required

Creation time, epoch milliseconds.

number

required

Last-write time, epoch milliseconds.

number | null

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

A thread groups ordered messages.

object

Show MemoryThread

string

required

Thread identifier.

string

required

Owning namespace, serialized.

string | null

Optional human-readable title.

string | null

Optional JSON metadata.

number

required

number

required

object

Show MemoryMessage

string

required

Message identifier.

string

required

Owning thread.

string

required

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

string

required

Message content, JSON-stringified.

string | null

Run that produced the message, if any (RUN_ID).

string | null

Node that produced the message, if any (NODE_ID).

number

required

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

A note is append-only knowledge: facts are mutable KV, notes are immutable rows, body/labels/provenance fixed 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.

object

Show MemoryNote

string

required

Note identifier (see saveNote below for idempotency).

string

required

Owning namespace, serialized via namespaceToString.

string

required

The knowledge itself. Immutable after insert.

string | null

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

string | null

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

string | null

Optional, policy-free author label.

string

required

Free-form, defaulting to "accepted" (conventionally pending | accepted | rejected); the one mutable field.

number | null

When setNoteStatus last flipped the status; null until then.

number

required

Creation time, epoch milliseconds.

string | string | number | null

Provenance: the writing run’s coordinate (see MemoryProvenance).

MemoryProvenance is the run coordinate a memory write was made from, passed explicitly by the caller on setFact and saveNote. It’s never inferred from ambient context, which doesn’t 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 (idempotency key, see saveNote). NoteReadFilter shapes listNotes/searchNotes reads. The default read contract (no filter): 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 instead of reopening the database per task.

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

BunSQLiteDatabase

required

A Drizzle bun-sqlite database handle; the memory tables live on the same database your workflow uses.

import { createMemoryStore } from "smthrs";
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, etc.) with the same arguments, for use inside an Effect pipeline.

methods

Show fact methods

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

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

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

(ns, key) => Promise<void>

(ns) => Promise<MemoryFact[]>

() => Promise<number>

Removes facts whose TTL elapsed; returns the count deleted.

methods

Show note methods

(input: SaveNoteInput) => Promise<MemoryNote>

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

(id) => Promise<MemoryNote | undefined>

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

Notes in one namespace, oldest first, under the default read contract unless filter widens.

(id, status) => Promise<void>

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

(kind) => Promise<void>

Opts a namespace kind into FTS note search, creating FTS5 artifacts lazily on first call and backfilling existing notes of that kind; until then note writes pay nothing extra. Idempotent.

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

Full-text search over note bodies, rank-ordered, 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 applies only to the top limit * 5 FTS matches, so a heavily superseded corpus may return fewer than limit despite more live matches further down.

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

methods

Thread and message reads/writes use the portable Drizzle tables, except the transactional deleteThread, which requires bun:sqlite and raises DB_WRITE_FAILED on Postgres/PGlite.

Show thread and message methods

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

(threadId) => Promise<MemoryThread | undefined>

() => Promise<MemoryThread[]>

(threadId) => Promise<void>

(msg) => Promise<void>

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

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

(threadId) => Promise<number>

(threadId, messageIds) => Promise<number>

Deletes the named messages, returning the count deleted; used by processors to compact history.

MemoryService

An Effect Context.Tag whose service value is a MemoryServiceApi: 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.

object

Show members

Effect

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

Effect

Thread lifecycle, Effect-returning.

Effect

Message operations, Effect-returning.

Effect

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

() => Effect<number, SmithersError>

MemoryStore

The underlying Promise-and-Effect store, for methods the service doesn’t 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>;

MemoryLayerConfig

required

Show MemoryLayerConfig

BunSQLiteDatabase

required

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

import { Effect } from "effect";
import { createMemoryLayer, MemoryService } from "smthrs";

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>;
};

(agent) => MemoryProcessor

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

(maxTokens) => MemoryProcessor

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

() => MemoryProcessor

Deletes expired facts across all namespaces by calling deleteExpiredFacts.

MemoryProcessorConfig selects which named processors to run.

object

Show MemoryProcessorConfig

string[]

E.g. ["Summarizer", "TtlGarbageCollector"].

import { TtlGarbageCollector, Summarizer } from "smthrs";

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.

TaskMemoryConfig

Show TaskMemoryConfig

string

One memory bank. Mutually exclusive with banks.

string[]

Memory banks recalled in parallel. Mutually exclusive with bank.

string[]

Stable branch, stream, source, and scope dimensions for recall and retention.

"auto" | string | false | { namespace?; query?; topK? }

"auto" derives the query from the task prompt, a string supplies the query, false disables prompt recall. The object form is legacy compatibility metadata, preserved but inert.

"low" | "mid" | "high"

Hindsight candidate-search budget. Defaults to "mid".

number

Hard cap for the injected memory block and serialized recall tool result. Defaults to 2048.

string[]

Mental-model ids fetched across the selected banks and injected verbatim.

"on-complete" | "off"

Retain successful task output asynchronously, or disable automatic retention. Defaults to "off".

boolean

Expose remember and recall tools to the task agent. Defaults to false.

string | MemoryNamespace

Legacy compatibility metadata. Preserved but inert.

{ namespace?; key? }

Legacy compatibility metadata. Preserved but inert.

string

Legacy compatibility metadata. Preserved but inert.

Object-form recall, remember, namespace, and threadId inject no facts, retain no output, and append no message history. Use the bank-based fields for runtime memory, or the store APIs directly for exact local records. SemanticRecallConfig and MessageHistoryConfig describe the two recall strategies a memory-aware runtime can apply.

object

Show SemanticRecallConfig

number

Maximum number of facts to recall.

MemoryNamespace

Namespace to recall from.

number

Minimum similarity score for a match.

object

Show MessageHistoryConfig

number

How many recent messages to include.

string

Thread to read history from.

Working memory is a typed, single-document fact validated against a Zod schema. Its config is generic over the schema type:

type WorkingMemoryConfig<
  T extends import("zod").ZodObject<import("zod").ZodRawShape> = import("zod").ZodObject<import("zod").ZodRawShape>,
> = {
  schema?: T;
  namespace: MemoryNamespace;
  ttlMs?: number;
};

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.

(ns: MemoryNamespace) => string

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

(str: string) => MemoryNamespace

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

import { namespaceToString, parseNamespace } from "smthrs";

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 smthrs 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