Sessions and memory

Start from a fresh project

This guide is self-contained. Create an empty Ayjnt project, then replace the starter agent with the files shown below. Run commands from the new project directory unless a step says otherwise.

bunx ayjnt new try-sessions --empty
cd try-sessions
bun install

# remove agents/alive once you are ready to add the guide's files

One session

Ayjnt’s createSession() returns Cloudflare’s Session builder backed by the agent’s SQLite. Add stable identity or instructions as a context block, and give learned memory a bounded token budget.

import { Agent } from "ayjnt";

export default class Assistant extends Agent {
  session = this.createSession()
    .withContext("soul", {
      provider: { get: async () => "You are a careful project assistant." },
    })
    .withContext("memory", {
      description: "Useful facts learned about the person",
      maxTokens: 1100,
    })
    .withCachedPrompt();

  async remember(message: Parameters<typeof this.session.appendMessage>[0]) {
    await this.session.appendMessage(message);
    return this.session.getHistory();
  }
}

Many sessions

Use createSession(id) when you already know the namespace, or createSessionManager() to create, list, branch, and archive multiple conversations inside one agent instance.

Session compaction summarizes older turns without rewriting your agent’s state. Search providers and context blocks let a harness load relevant memory instead of replaying everything.

Run it and verify the result

Append two messages, restart the dev server, and request history again. The session is stored in the agent’s SQLite database.

bun run build
bun run dev

# the local app is now available at http://localhost:8787