# AI agent memory concepts

> The whole model — layers, organizers, and who writes what.

OceanDB has a small model that compounds. Learn these few pieces and the rest
follows.

## Three layers

Memory lives in three layers, from raw to refined:

- **`entries`** — the append-only **log**. Episodic notes, decisions, and
  documents your agent captures as it works. Cheap to write, never rewritten in
  bulk.
- **`pages`** — the consolidated **wiki**. One page per entity or topic, each
  fact cited back to the entry it came from. This is what you read first.
- **`links`** — the typed **edge graph** over entries and pages:
  `mentions`, `relates`, `part_of`, `derived_from`, `contradicts`,
  `merged_into`.

## A clear boundary

Your agent writes **entries** — nothing else. Consolidating entries into pages
and drawing links between them is the **Dreamer's** job. Capture stays cheap
and fast; the deeper, structural work happens on its own pass. See
[The Dreamer](/docs/dreamer).

## Two axes of organization

Where a memory can be seen and what a memory is about are different questions,
kept apart on purpose:

- A **workspace** is the **sharing boundary** — who can see this. Your
  **personal** space is a private workspace of one, and the default. Shared
  spaces are teams you co-own. See [Workspaces](/docs/workspaces).
- A **project** is a **topical scope inside a workspace** — what a memory is
  about (Health, Finance, the Acme launch). An entry has one home project;
  a page can span several.

Alongside projects, **tags** are the cross-cutting labels — many per memory,
emergent, applied as your agent goes. A project is the folder; tags are the
labels.

## Insights

There's one more layer, and it flows the other way. Every other layer runs
*toward* memory; **`insights`** runs back *from* it. When your agent notices
something non-obvious — a pattern, a connection you never stated, a
blind-spot — it writes a short note to its **notebook**, and you can read it in
the dashboard. See [Insights](/docs/insights).

## Who writes what

| Role | Writes | Reads |
|---|---|---|
| Your agent (capture) | entries, tags, insights | pages first, then entries |
| The Dreamer | pages, links | everything, per workspace |
| You (dashboard) | edits, approvals, archives | everything |

Memory compounds because the cheap path and the careful path stay separate —
your agent captures freely, and the Dreamer keeps the whole thing in order.