Builtin Library
README.md
modules.memory
Agent memories in two scopes. Personal memories (scope = "personal") are
the signed-in person's own, kept the same way in their home world's
authoring folder (shown at /zero/home/<owner>/.authoring/memory/); the
engine's trusted runtime keeps them: it runs each verb of their store
(memory.personal) only for a tool call of the person's own agent, shows the
person each change, and refuses every other caller naming why. store(place)
is the store of one scope, and every change keeps the version it replaced in
memory-history/ beside it (history, restore) and a record of itself
there (changes, change, undo).
World memories: what a world's writers and their agents keep for each other
across conversations (decisions, conventions, the layout, what is done and
what is left). Each entry is one markdown file in the world's authoring
folder, /zero/source/.authoring/memory/, opened by a header block:
---
name: lighting-conventions
description: Scenes use one sun at 45 degrees and moodLight presets.
agent: terrain
harness: dotbot
person: ada
updated_at: 2026-11-12T10:00:00Z
---
The body, markdown.
name is unique in the world (lowercase letters, digits and dashes, at most
64 characters), description is the one line the brief shows (at most 200
characters), and the body holds at most 16 KiB. The world keeps at most 256
entries and 1 MiB of them. A new entry's file is named by an id derived from
its name, the next id when another entry's file holds that one; a file a
person writes there by hand is an entry too, named by its header (or by its
file name when it has none) and read, edited and removed by that name.
Every read answers the entry's revision, the checksum of its file as
stored. Replacing an entry takes the revision it was read at, and a write
over a newer one answers the current entry instead; edit replaces one
occurrence of a text in the body, so agents changing different parts of an
entry do not overwrite each other. A write whose text reads as a credential
(an API key, a token, a private key block, a password field with a value) is
refused, naming what it found.
The folder is the world's authoring folder, so the world's writers and their
own code (the editor, an agent's tools, execute) reach it, code a world
ships never does, and no pack, export or play session carries it.
brief() is the index every agent working in the world is given when its
conversation starts and again after an entry changes.
Memories stay out of the world's history. Before a change writes its first
file, the store writes an ignore file (.zmignore, IGNORE_BODY) into each
folder of the scope that holds none yet, naming every file there and itself:
the entries and their history sync live to the world's writers and stay in
its working tree from one session to the next, while a status read counts
them among its ignored rows rather than its changes, zm add . leaves them
out, and the unpublished-work reminder never names them. Recording a memory
after the last push leaves the world as clean as that push left it. The
home world's folders hold the same files, so personal memories stay out of
the home world's history the same way.
Every write, edit, removal, restore and undo is also recorded as one JSON
file in the scope's memory-history/ (/zero/source/.authoring/memory-history/
for the world), beside the folders of earlier versions: the kind of change
(created, replaced, edited, removed, restored, undone), the entry's name and
file, who made it (agent, harness, person; a person's own edit in the editor
names the signed-in person) and the entry's file as it stood before and
after. The record is written before the change, so a change the history
cannot record is refused, and each changing answer names it as change.
changes(scope, limit?) lists the newest first, change(scope, id) answers
one with both versions, and undo { id, revision?, scope? } puts the entry
back byte for byte as it stood before the change: a created entry is
removed, any other brought back. An undo over a later change writes nothing
unless revision names the revision the entry stands at now (absent when
it is gone), and answers both versions instead. A scope keeps the
CHANGES_MAX (64) newest changes.