Log inGet started
World

Builtin Library

Branchmain
Branchesmainpublish
Commit15ce14a4c1

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.