.memory() | XSAF

Signature

agent.memory(driver: XsafMemoryDriver): XsafAgent

The memory driver stores ordered model messages by session ID.

Usage

Durable SQL with db0

Install db0 (optional peer of @xsaf/agent) and wrap any db0 Database. Rows live in xsaf_messages and support substring search via .search() (all sessions by default; pass sessionId to narrow):

import { createDatabase } from "db0";
import sqlite from "db0/connectors/bun-sqlite";
import { db0 } from "@xsaf/agent/memory/db0";

const memory = db0(createDatabase(sqlite({ name: "xsaf-memory" })));

agent.memory(memory);

const hits = await memory.search({ query: "weather", limit: 10 });
const scoped = await memory.search({ query: "weather", sessionId: "customer-1" });

On Nitro, enable the experimental database layer and reuse useDatabase() (default SQLite under .data/):

// nitro.config.ts
export default defineConfig({
  experimental: { database: true },
  database: {
    default: { connector: "sqlite", options: { name: "xsaf" } },
  },
});

// server.ts
import { useDatabase } from "nitro/database";
import { db0 } from "@xsaf/agent/memory/db0";

agent.memory(db0(useDatabase(), { dispose: false }));

Pass { dispose: false } when Nitro (or another owner) still needs the database after agent shutdown.

Durable KV with unstorage

Install unstorage and wrap any Storage backend — filesystem, Redis, Cloudflare, and more:

import { createStorage } from "unstorage";
import fsDriver from "unstorage/drivers/fs";
import { unstorage } from "@xsaf/agent/memory/unstorage";

agent.memory(
  unstorage(
    createStorage({
      driver: fsDriver({ base: "./data/memory" }),
    }),
  ),
);

Custom driver

agent.memory({
  async get(sessionId) {
    return database.readMessages(sessionId);
  },
  async append(sessionId, message) {
    await database.appendMessage(sessionId, message);
  },
  async clear(sessionId) {
    await database.deleteMessages(sessionId);
  },
  async close() {
    await database.close();
  },
});

Register at most one memory driver. Without .memory(), XSAF uses its built-in in-memory implementation. Memory resources are closed during agent shutdown.

Requests sharing a session ID execute serially; different sessions can run concurrently. See Sessions & Memory for ordering, streaming persistence, and HTTP session IDs.