Memory

Import from @anvia/core or @anvia/core/memory.

MemoryStore

interface MemoryStore {
  load(context: MemoryContext): Promise<Message[]>;
  append(input: MemoryAppendInput): Promise<void>;
  clear(context: MemoryContext): Promise<void>;
  recordError?(input: MemoryErrorInput): Promise<void>;
}

Purpose: application-owned persistence adapter for durable agent sessions.

Return behavior: load(...) returns prior transcript messages for a session; append(...) persists new run messages; clear(...) deletes the session transcript; recordError(...) optionally receives partial run messages when a prompt run fails.

Notable errors: store implementations should reject when persistence fails. Rejections from load(...), append(...), clear(...), or recordError(...) surface through session prompt calls.

MemoryContext

type MemoryContext = {
  sessionId: string;
  userId?: string | undefined;
  metadata?: JsonObject | undefined;
};

Purpose: identifies the conversation scope loaded and saved by a MemoryStore.

Return behavior: passed to every store method. sessionId comes from agent.session(sessionId, options?); userId and metadata come from SessionOptions.

Notable errors: agent.session(...) rejects empty session ids before creating a MemoryContext.

MemoryAppendInput and MemoryErrorInput

type MemoryAppendInput = {
  context: MemoryContext;
  runId: string;
  turn: number;
  messages: Message[];
};

type MemoryErrorInput = {
  context: MemoryContext;
  runId: string;
  error: unknown;
  messages: Message[];
};

Purpose: structured inputs for normal message persistence and failure recording.

Return behavior: messages contains the transcript messages Anvia is asking the store to persist for that save point. runId and turn let stores group messages by run or model/tool loop turn.

Notable errors: none directly; store implementations decide how to handle duplicate or partially persisted messages.

MemoryOptions

type MemorySavePolicy = "message" | "turn" | "run";

type MemoryOptions = {
  savePolicy?: MemorySavePolicy | undefined;
};

type ResolvedMemoryOptions = {
  savePolicy: MemorySavePolicy;
};

function resolveMemoryOptions(options?: MemoryOptions): ResolvedMemoryOptions;

Purpose: configures when AgentSession appends messages to the configured store.

Return behavior: resolveMemoryOptions(...) fills the default savePolicy: "message". AgentBuilder.memory(store, options?) stores the resolved policy in MemoryRegistration.

Notable errors: none directly.

Registration and Session Types

type MemoryRegistration = {
  store: MemoryStore;
  options: ResolvedMemoryOptions;
};

type SessionOptions = {
  userId?: string | undefined;
  metadata?: JsonObject | undefined;
};

Purpose: internal agent configuration and per-session metadata contracts.

Return behavior: MemoryRegistration is created by AgentBuilder.memory(...); SessionOptions is passed to agent.session(sessionId, options?) and becomes part of MemoryContext.

Notable errors: agent.session(...) throws when the agent has no memory store configured.

Example

import { AgentBuilder, type MemoryStore, type Message } from "@anvia/core";

class InProcessMemoryStore implements MemoryStore {
  private readonly sessions = new Map<string, Message[]>();

  async load({ sessionId }) {
    return this.sessions.get(sessionId) ?? [];
  }

  async append({ context, messages }) {
    this.sessions.set(context.sessionId, [...(this.sessions.get(context.sessionId) ?? []), ...messages]);
  }

  async clear({ sessionId }) {
    this.sessions.delete(sessionId);
  }
}

const agent = new AgentBuilder("support", model)
  .memory(new InProcessMemoryStore(), { savePolicy: "turn" })
  .build();

const response = await agent
  .session("thread_123", { userId: "user_456" })
  .prompt("Continue from the previous answer.")
  .send();

Related Guides