Session Memory: Persist Agent Conversational State

Session memory gives each conversation its own typed key-value scope over the same pluggable StateStore used for durability checkpoints — no hand-rolled per-project memory table, and no separate persistence layer to configure.

Attaching memory to routes

withMemory is a middleware that attaches a MemoryStore to ctx.state, namespaced per request:

// server/routes/_middleware.ts
import { withMemory } from 'anvil-sdk/memory';
import { SqliteStateStore } from 'anvil-sdk/store';

const store = await SqliteStateStore.open('.anvil/memory.db');

export default [withMemory(store)];

By default, the namespace is the x-session-id request header, falling back to 'default' if the header is absent. Pass a custom function to derive the namespace differently — from a JWT claim, a cookie, or a route param:

export default [withMemory(store, (ctx) => ctx.headers.get('x-user-id') ?? 'anonymous')];

Reading and writing memory in a handler

// server/routes/chat/agent.ts
import { getMemory } from 'anvil-sdk/memory';
import type { Context } from 'anvil-sdk';

export default async function handler(ctx: Context) {
  const memory = getMemory(ctx);
  if (!memory) throw new Error('withMemory middleware not attached');

  await memory.append('history', { role: 'user', text: 'What did I ask before?' });
  const history = await memory.get('history');

  return { history };
}

getMemory(ctx) returns undefined if withMemory wasn’t attached upstream — always check before use, or attach it at the root _middleware.ts so every route has it.

`MemoryStore` API

<T>(key: string) => Promise<T | undefined>

Read a typed value. Returns undefined if the key was never set.

(key: string, value: unknown) => Promise<void>

Write a value, overwriting anything already stored under key.

<T>(key: string, item: T) => Promise<number>

Append item to an array value, creating the array if it doesn’t exist yet. Returns the new array length. Useful for conversation history without a separate read-modify-write round trip in handler code.

(key: string) => Promise<void>

Remove a key.

() => Promise<string[]>

List all keys currently set within this instance’s namespace.

Every key is stored under a namespaced prefix (anvil:memory:<namespace>:<key>) in the underlying StateStore, so different sessions never collide even when sharing one store instance.

Choosing a backing store

MemoryStore works over any StateStore implementation:

import { MemoryStateStore } from 'anvil-sdk/store';
// Zero-dependency, in-memory — good for tests and local dev. Lost on restart.

import { SqliteStateStore } from 'anvil-sdk/store';
// Persists to disk. Requires the optional better-sqlite3 peer dependency.

SqliteStateStore also backs durable execution checkpoints — a single store instance can serve both session memory and agent-run checkpointing, since they write to different key prefixes.

Attaching memory to routes

withMemory is a middleware that attaches a MemoryStore to ctx.state, namespaced per request:

// server/routes/_middleware.ts
import { withMemory } from 'anvil-sdk/memory';
import { SqliteStateStore } from 'anvil-sdk/store';

const store = await SqliteStateStore.open('.anvil/memory.db');

export default [withMemory(store)];

export default [withMemory(store, (ctx) => ctx.headers.get('x-user-id') ?? 'anonymous')];

Reading and writing memory in a handler

// server/routes/chat/agent.ts
import { getMemory } from 'anvil-sdk/memory';
import type { Context } from 'anvil-sdk';

export default async function handler(ctx: Context) {
  const memory = getMemory(ctx);
  if (!memory) throw new Error('withMemory middleware not attached');

  await memory.append('history', { role: 'user', text: 'What did I ask before?' });
  const history = await memory.get('history');

  return { history };
}

getMemory(ctx) returns undefined if withMemory wasn’t attached upstream — always check before use, or attach it at the root _middleware.ts so every route has it.

`MemoryStore` API

<T>(key: string) => Promise<T | undefined>

Read a typed value. Returns undefined if the key was never set.

(key: string, value: unknown) => Promise<void>

Write a value, overwriting anything already stored under key.

<T>(key: string, item: T) => Promise<number>

(key: string) => Promise<void>

Remove a key.

() => Promise<string[]>

List all keys currently set within this instance’s namespace.

Every key is stored under a namespaced prefix (anvil:memory:<namespace>:<key>) in the underlying StateStore, so different sessions never collide even when sharing one store instance.

Choosing a backing store

MemoryStore works over any StateStore implementation:

import { MemoryStateStore } from 'anvil-sdk/store';
// Zero-dependency, in-memory — good for tests and local dev. Lost on restart.

import { SqliteStateStore } from 'anvil-sdk/store';
// Persists to disk. Requires the optional better-sqlite3 peer dependency.

SqliteStateStore also backs durable execution checkpoints — a single store instance can serve both session memory and agent-run checkpointing, since they write to different key prefixes.

Get Started

Routing

MCP & Tools

Agent Routes

Observability

Safety & Durability

Memory & RAG

Background Tasks

Session Memory: Persist Agent Conversational State

Attaching memory to routes

Reading and writing memory in a handler

`MemoryStore` API

Choosing a backing store

See also

Attaching memory to routes

Reading and writing memory in a handler

`MemoryStore` API

Choosing a backing store

See also

​Attaching memory to routes

​Reading and writing memory in a handler

​MemoryStore API

​Choosing a backing store

​See also

​Attaching memory to routes

​Reading and writing memory in a handler

​MemoryStore API

​Choosing a backing store

​See also

Attaching memory to routes

Reading and writing memory in a handler

`MemoryStore` API

Choosing a backing store

See also

Attaching memory to routes

Reading and writing memory in a handler

`MemoryStore` API

Choosing a backing store

See also