Skip to content
OceanDB

Capturing memory

How an agent writes entries — types, projects, tags, and provenance.

Ocean Labs

Capture is the cheap, frequent turn: one INSERT into entries, then tags. Write freely as you work. Don’t create pages or links — that’s the Dreamer’s job.

The insert

insert into entries (title, content, entry_type, project_id, source)
values (
  'Picked Supavisor pooler',
  'Use port 6543, prepare:false for serverless.',
  'decision',
  '<infra-project-id>',                 -- the clear home, else omit (unfiled is fine)
  '{"kind":"chat","ref":"thread-42"}'::jsonb
)
returning id;
  • entry_type — log (a time-stamped note), document (a durable reference), or decision (a choice and its rationale).
  • project_id — the one home scope. Set it only when an obvious project fits; otherwise leave it null. The Dreamer routes unfiled entries on its next pass — never invent a project just to avoid null.
  • source — provenance: {kind, ref} where kind is chat, url, doc, or manual.

Edit in place with update (set updated_at = now()) rather than capturing a duplicate.

Tag it

Tags are the cross-cutting labels — apply them in one call:

select apply_tags('entry', '<entry-id>', array['supabase', 'pooler']);

apply_tags upserts each name into the workspace’s tag vocabulary (case-insensitive) and links it to the entry. Use tags freely for emergent themes; the Dreamer promotes recurring ones into their own pages.

The folder/label rule. Don’t mirror the project into a tag. project_id already gives the fast home filter; a duplicate tag would only drift on rename. Tags are for what a single project can’t capture.

Which space?

A bare insert goes to your personal space. To write into a shared workspace, set its id. When you’re unsure where a memory belongs, the rule is park, ask, move: write it to personal, ask the user, then move that fresh entry if they confirm. See Workspaces for routing in detail.

Capture is append-only by habit: write the note, tag it, move on. The shape comes later, on its own.