Skip to content
OceanDB

The execute_sql contract

One statement, a de-fanged role — the full language under the agent surface.

Ocean Labs

execute_sql is the full language under your agent’s tools. It runs a single SQL statement against a private Postgres memory that belongs to one person. remember and recall are shortcuts over it; everything they don’t cover — organizing, dreaming, analytics — is expressed through it.

The rules

  • One statement per call. Each call runs a single SQL statement.
  • A de-fanged role. You may SELECT, INSERT, and UPDATE. DELETE, TRUNCATE, and schema changes are rejected. Nothing is ever deleted — you retire things by setting a flag (archived = true, status = 'dismissed').
  • Reads span all your workspaces. RLS scopes every result to your membership, so no workspace filter is needed.
  • Writes default to personal. A bare insert lands in your personal workspace. Set workspace_id explicitly only to write into a shared space.
  • Attribution is automatic. Omit author_id — it defaults to you. Never write fts — it’s generated.

The shape of a turn

Capture is one insert, plus tags:

insert into entries (title, content, entry_type)
values ('Chose Supavisor', 'Port 6543, prepare:false for serverless.', 'decision')
returning id;

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

Retrieval reads the wiki first, then drills to sources:

select id, slug, title, summary from pages
where status = 'active'
  and fts @@ websearch_to_tsquery('english', 'supavisor pooler')
limit 10;

Helpful one-liners

select id, name, kind from workspaces;             -- your spaces
select id, name, description from projects;        -- topical scopes
select my_personal_workspace();                    -- your personal workspace id

Read the manuals in-place

The server ships its own documentation as MCP resources, so your agent can pull the authoritative detail without leaving the session:

  • oceandb://docs/ocean — capture, retrieve, and organize.
  • oceandb://docs/dreamer — the nightly consolidation pass.
  • oceandb://schema — the live schema.

From here: Capturing memory, Organizing memory, Insights, and the Schema reference.