# How OceanDB memory works

> The self-managing pass that turns a log into a wiki.

The **Dreamer** is what makes memory keep itself. Your agent captures entries
all day; the Dreamer runs a deeper, periodic pass that consolidates them into
clean, cited pages and draws the links between them. You never groom memory by
hand — it tends itself while you sleep.

The Dreamer is the same de-fanged agent as capture: one tool, one statement at
a time, read and add and update but never delete. It's just running a different,
more careful job.

## Where it runs

The Dreamer runs **client-side**, from your own agent — the server holds no
model of its own. You schedule it (nightly is typical, or on demand) and it
reads its playbook and works through the phases against your memory. Because it
runs as you, it sees exactly what you see, and nothing more.

## The leash

The Dreamer acts on its own where the change is safe, and asks first where it
isn't:

- **Reversible edits → it acts.** Creating and updating pages, citing facts,
  linking what relates, marking things stale, tidying labels. These can always
  be undone, so it just does them.
- **Structural changes → it proposes and waits.** Archiving a page, resolving a
  contradiction, merging duplicates. These it raises as **proposals** for you to
  approve in the [dashboard](/docs/dashboard-pages). Nothing structural happens
  behind your back.

## Per workspace, one at a time

Memory in a shared space is tended by one member at a time. The Dreamer takes a
short **lease** on each workspace before working it, holds it with a heartbeat,
and releases it when done — so two members never dream the same space at once.
It works each of your spaces in turn. See [Workspaces](/docs/workspaces).

## How it never loses or repeats work

The Dreamer keeps a **watermark** per workspace and only processes entries
newer than it. The watermark advances **only after a clean run**, with a small
safety lag — so a late-arriving capture is re-read rather than skipped, and a
re-run makes almost no new rows. It is, by design, safe to run again.

For the step-by-step, see [The nightly playbook](/docs/dreamer-playbook).