Skip to content

Welcome

Structured memory for agents and beyond

Structured memory turns text into facts that keep their sources and their dates. Memory for AI agents that help people with their work is the main use of SurrealDB Agent Memory, and the showcase has a demo of it. The same steps also work for any application whose input is text and whose questions need checkable answers, and most of the other demos have no conversation at all.

The problems on the earlier pages all come from long-running work: a conversation that outgrows the context window, a fact that changes halfway through, and a correction that a summary loses. A team whose members each work with an AI assistant for months meets all of them at once, and adds one more, which is that each person may only see some of what the others know.

Sundance Lake Loop simulates this. It follows a fictional natural gas pipeline project over twelve months, in six chapters. Six employees, from the project manager in the field to the internal auditor, each work with an assistant that has its own Agent Memory key:

  • Each assistant remembers its owner's conversations, so a decision from the first chapter is still there in the sixth, with the date it was made.

  • Each key reads only the scopes its owner may see. The supply chain specialist's assistant reads vendor files, and the accounts payable clerk's assistant reads approved invoices and payments.

  • Each assistant checks what its owner says against what the listener may read. It reviews an email before it is sent, and a call afterwards, and leaves a note when its owner shared something the listener was not allowed to see.

  • The auditor's questions can be answered for any date, including who could read a record at the time, because every fact keeps its source and when it was recorded.

The user memory in chat and multi-agent shared memory cookbooks show how to build the parts of this for your own agents.

The sections below describe the other uses, where the input is a body of text and nobody is talking to an agent.

A collection of documents, such as manuals, records, reports or letters, becomes a set of facts about the people, places and things in it. Each answer is built from those facts, and each fact points back to the passage it came from, so a reader can check any claim against the original.

  • Pompeii election notices ingests 127 campaign notices from the walls of Pompeii and answers questions about who backed whom, with every citation linked to its notice.

  • The Domesday Book, 1086 does the same with 52 entries of the Domesday survey, and checks each answer about lordship, wealth and mills against the data.

The historical and archaeological data pattern describes the approach for fragmentary sources, and knowledge-grounded agents covers what happens when documents and conversations disagree.

Every fact records when it was true, so the memory can answer for any date in the past as well as for today. This suits any record that changes over time: an article that is edited, a register of who holds an office, the price of a product, or the owner of a piece of land.

  • Vulcan, Alberta: an article's history loads 24 years of edits to one Wikipedia article and answers questions about what the article said at any point. A small model reading Agent Memory scores at least as well as a large model reading the edit history directly, for less than half the cost.

  • Rome, 753 BC to AD 1453 records every year of Roman history as structured facts, and reads back who ruled and who controlled each place as a history of values.

Each fact also records when the memory learnt it, and that time does not have to be a calendar date. It can be a position in a book, an episode of a series or a step in a course, so the memory answers only with what a reader has reached so far.

  • Robin Hood character graph ingests the book one chapter at a time and draws the cast as it is known at each point in the story.

The spoiler-safe narrative memory pattern explains how to ingest a whole work and still answer only as far as the reader has read.

Facts can be stored in scopes, and each key that reads the memory can be limited to some of them. One memory can then serve several people or programs, each of which sees only the facts it is allowed to. Sundance Lake Loop uses this for its assistants, and two more demos use it in other ways.

  • Calgary 1912-1913 explorer builds a walkable city from two volumes of a city directory, where every resident's answer comes from a scope you can inspect.

  • Night Owls gives seven agents on a simulated forum a scope each in one memory, and shows a private note written in 1999 coming back in 2019.

Agent Memory does its most important work when information arrives as text: it reads the text, extracts the facts, and reconciles them with what it already holds. When your data is already structured, such as orders, sensor readings or a product catalogue, it does not need extracting. Store it in SurrealDB directly, where records, graph relations, vector search and full-text search are all available without a model call on each write.

An application can use both: SurrealDB for the data it already has in structured form, and Agent Memory for what it learns from documents and conversations.

Was this page helpful?