Memory

Memory is Anvia's durable conversation API. Core owns when to load and append messages; your application owns where those messages are stored.

const agent = new AgentBuilder("support", model)
  .memory(memoryStore)
  .build();

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

Mental Model

Use agent.prompt("...") for stateless one-off requests.

Use agent.prompt([...messages]) when your application already owns an explicit transcript. The last message is the active prompt and earlier messages are temporary request history.

Use agent.session(id).prompt("...") when Anvia should load and save durable conversation messages through the configured memory store.

Memory stores model transcript messages for future context. It does not store runtime stream events such as text deltas, tool progress, or child-agent events from asTool({ stream: true }). Use Event Store when you need replay/debug history for runtime events.

Public API

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

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

interface MemoryStore {
  load(context: MemoryContext): Promise<Message[]>;

  append(input: {
    context: MemoryContext;
    runId: string;
    turn: number;
    messages: Message[];
  }): Promise<void>;

  clear(context: MemoryContext): Promise<void>;

  recordError?(input: {
    context: MemoryContext;
    runId: string;
    error: unknown;
    messages: Message[];
  }): Promise<void>;
}

type MemoryOptions = {
  savePolicy?: MemorySavePolicy;
};

Configure the store and optional save policy on the agent:

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

Save Policy

Memory defaults to savePolicy: "message".

On failure, stores that implement recordError(...) receive the error and partial run messages.

For delegation-specific behavior, read Multi-Agent Memory.

Adapter Examples

Choose the adapter style that matches your application: