# The execute_sql contract

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

**`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:

```sql
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:

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

## Helpful one-liners

```sql
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](/docs/capturing),
[Organizing memory](/docs/organizing), [Insights](/docs/insights), and the
[Schema reference](/docs/schema).