Overview

An AI agent that works across more than one session has to write what it learns to a disk, because the next session can load only the rows that the one before it wrote. These guides show you how to keep that memory in a database file on a disk you control. Each guide starts from a problem you would meet while you operate a fleet of AI agents, then builds the files that solve it. You can execute those files against a real database before you adopt any of them. Where you want the whole of an API, each guide links to the reference page that covers it.

Every database that these guides open is one file, whether that file is on a laptop, on a server you rent, or on a phone somebody carries. Your AI agents' memory therefore stays where you put it.

Which part of an AI agent's memory Sirannon holds

These guides split an AI agent's memory three ways. Working memory holds the plan that the AI agent is following on the task in front of it, along with the results it has collected so far. Its episodic memory records every message, every tool call, and whatever each of those calls returned. Its semantic memory keeps what it learns about a person or a subject, which you can reach again by searching for meaning.

Sirannon holds the first two, since both of them are rows that you write and later read back by key, by time, or by a filter. A search by meaning takes an index that scores each note by the words in it. Narsil holds that index while Sirannon stays the system of record, so one subscriber on Sirannon's change feed applies every later write to Narsil. The retrieval guide connects them.

What these guides assume

Every guide here opens a database through a driver and then writes SQL against it, both of which the getting started guide covers from the install onwards. Where a guide serves an AI agent over a network, its code starts the server that the server page describes and calls the named operations that the registered operations page sets out.

Each guide calls a mock model, and every panel therefore prints the same text on every run. Name a real model in its place once you want that model to choose the calls.

The guides

• A database per AI agent gives every AI agent a file of its own, which the registry opens the first time your code resolves that agent and closes once that agent goes quiet.
• Memory and forgetting marks a row as replaced once a newer value supersedes it so that you can still read the value that was current on a date you name.
• Rewinding memory rebuilds an AI agent's memory as it stood at the moment you name, which is the repair you would reach for once a fetched page has written a false fact into that memory.
• AI agent tools puts every read and every write that the AI agent may call into one registry, where fromIdentity fills the customer identifier from the authenticated session.
• Shared state settles each claim inside the statement that makes it, leaving the AI agent that loses free to read that outcome and take the next job.
• Auditing a fleet records every write that the fleet completes into one journal, from a single onAfterQuery hook on the registry. Catching HookDeniedError at the tool adds the refused attempts to that journal.
• Retrieval with Narsil fills a search index from an AI agent's notes and keeps it in step with the change feed, which lets a student ask in their own words and still reach the right note. A filter on agent_id keeps each AI agent's search inside its own notes.
• Offline AI agents keeps an AI agent answering from a tablet with no route to any server, and device sync reconciles both sides once the connection returns. Sirannon refreshes the rows behind db.live for as long as that query is open.