Storage Reference

API reference for the storage function, StorageHandlers, StorageStep, and localStorage.

Passed to agent(name, { storage: ... }) to configure the storage backend.

The Storage Function

Storage is a function that receives a StorageStep and dispatches it to your handlers via store.on():

agent("my-agent", {
  async storage(store) {
    return await store.on({
      "session.get": async ({ id }) => { /* ... */ },
      // ...
    });
  },
})

To add workflow support, add "use step" at the top:

agent("my-agent", {
  async storage(store) {
    "use step";
    return await store.on({ /* same handlers */ });
  },
})

The function signature is:

type StorageStepFunction = (store: StorageStep) => Promise<any>;

StorageHandlers

The object passed to store.on(). A flat map of async handler functions, one per storage operation.

type StorageHandlers = {
  "session.get"(p: { id: string }): Promise<Session | null>;
  "session.set"(p: { id: string; value: Session }): Promise<void>;
  "session.update"(p: { id: string; updates: Partial<Session> }): Promise<Session>;

  "message.get"(p: { id: string }): Promise<Message | null>;
  "message.set"(p: { id: string; value: Message }): Promise<void>;
  "message.update"(p: { id: string; updates: Partial<Message> }): Promise<Message>;
  "message.listBySession"(p: { sessionId: string }): Promise<Message[]>;

  "part.get"(p: { id: string }): Promise<Part | null>;
  "part.set"(p: { id: string; value: Part }): Promise<void>;
  "part.listBySession"(p: { sessionId: string }): Promise<Part[]>;

  "sandbox.get"(p: { id: string }): Promise<Sandbox | null>;
  "sandbox.set"(p: { id: string; value: Sandbox }): Promise<void>;
  "sandbox.update"(p: { id: string; updates: Partial<Sandbox> }): Promise<Sandbox>;

  "setup.get"(p: { id: string }): Promise<Setup | null>;
  "setup.set"(p: { id: string; value: Setup }): Promise<void>;
};

StorageStep

A serializable envelope that carries a storage operation. Dispatches to your handlers via store.on().

class StorageStep {
  event: StorageCall;
  on(handlers: StorageHandlers): Promise<any>;
}

StorageCall is a discriminated union derived from StorageHandlers — each variant has a method field and the corresponding parameters:

type StorageCall = {
  [K in keyof StorageHandlers]: { method: K } & Parameters<StorageHandlers[K]>[0];
}[keyof StorageHandlers];

StorageStep implements @workflow/serde serialization, so it survives workflow replay without any extra configuration.

localStorage

Built-in filesystem-backed storage for development. Returns a function compatible with the storage option.

import { localStorage } from "experimental-agent/storage";

Parameter	Type	Default	Description
`dir`	`string`	`".agent"`	Directory path for JSON storage files.

// @fragment expression
localStorage()
localStorage({ dir: ".my-data" })

Data is stored as {dir}/session/{id}.json, {dir}/message/{id}.json, etc.

Stored Types

Session

Field	Type	Description
`id`	`string`	Session identifier.
`createdAt`	`number`	Creation timestamp.
`updatedAt`	`number`	Last update timestamp.
`model`	`string`	Model ID.
`system`	`string \| undefined`	System prompt.
`generation`	`object \| undefined`	Generation options.
`lastMessageId`	`string \| undefined`	ID of the most recent message.
`activeTools`	`string[] \| undefined`	Active tool names.

Message

Field	Type	Description
`id`	`string`	Message identifier.
`sessionId`	`string`	Parent session.
`role`	`"user" \| "assistant"`	Message role.
`createdAt`	`number`	Creation timestamp.
`usage`	`object \| undefined`	Token usage for this message.
`workflowRunId`	`string \| undefined`	Workflow run that generated this message.

Part

Field	Type	Description
`id`	`string`	Part identifier.
`sessionId`	`string`	Parent session.
`messageId`	`string`	Parent message.
`type`	`string`	Part type (text, tool-call, tool-result, etc.).
`index`	`number`	Position within the message.

Sandbox

Field	Type	Description
`id`	`string`	Sandbox identifier.
`createdAt`	`number`	Creation timestamp.
`updatedAt`	`number`	Last update timestamp.
`binding`	`string`	Sandbox binding type.
`metadata`	`object \| undefined`	Provider-specific metadata.