Anvia Docs

Memory is durable conversation state owned by an agent. Configure a memory store once, then choose a session id for each conversation.

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

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

  async load(context: MemoryContext): Promise<Message[]> {
    return [...(this.sessions.get(context.sessionId) ?? [])];
  }

  async append(input: MemoryAppendInput): Promise<void> {
    const current = this.sessions.get(input.context.sessionId) ?? [];
    this.sessions.set(input.context.sessionId, [...current, ...input.messages]);
  }

  async clear(context: MemoryContext): Promise<void> {
    this.sessions.delete(context.sessionId);
  }
}

const memory = new AppMemoryStore();

const agent = new AgentBuilder("support", model)
  .instructions("Answer support questions clearly.")
  .memory(memory)
  .build();

await agent.session("thread_123", { userId: "user_456" }).prompt("Remember my plan.").send();
await agent.session("thread_123", { userId: "user_456" }).prompt("What is my plan?").send();

Mental Model

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

Use agent.prompt([...messages]) when you already have 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.

Save Policy

Memory defaults to savePolicy: "message". This saves the user prompt, completed assistant messages, and completed tool result messages as soon as they are ready.

new AgentBuilder("support", model).memory(memory, { savePolicy: "turn" });

Available policies are:

Policy	Behavior
`"message"`	Save each completed message immediately. Best recovery for long failed runs.
`"turn"`	Save completed messages after each model/tool turn. Fewer writes.
`"run"`	Save only after a successful final response. Simplest persistence behavior.

On failure, memory stores with recordError(...) receive the error and partial run messages.

Migration From Explicit History

Old request history should become an explicit transcript:

const history = await conversations.loadMessages(conversationId);

const response = await agent
  .prompt([...history, Message.user(userInput)])
  .send();

Use sessions when you want core to own the load/save cycle:

const response = await agent.session(conversationId).prompt(userInput).send();

For storage adapter examples, see the dedicated Memory section.

Memory and Sessions

Mental Model

Save Policy

Migration From Explicit History