docs(agents): draft Structured Memory design for review

[cjol]

This PR adds a draft user-facing doc for Structured Memory, a proposed set of tools that give a model its own SQLite tables to create, query, and maintain. Nothing is implemented yet: the doc is here so the developer-facing design can be reviewed before implementation starts.

Why

• Agents often need to keep structured records across turns (contacts, tasks, extracted facts) and query them later. Today the options are files in a workspace or free-form context, neither of which supports filtering, joins, or aggregates.
• The obvious tool is "run arbitrary SQL", but that makes a non-destructive agent impossible: there is no way to grant inserts without also granting drops.
• The design splits reads from writes. Reads take SQL, because that is where SQL is most useful. Writes go through structured tools (db_create_table, db_insert, db_update, ...), so each operation can be granted, gated behind approval, or denied on its own.
• Alternatives considered and rejected, based on a spike against a facet in local workerd:
  • A read-only SQLite connection or PRAGMA query_only: both are refused by Durable Object SQLite (SQLITE_AUTH), as are temp tables and temp triggers.
  • Checking cursor.rowsWritten after a query: DROP TABLE reports 0 rows written, and a multi-statement query only reports its last statement. db_query instead runs inside a transaction that is always rolled back.
  • Classifying raw SQL writes into insert, update, and delete for per-operation permissions: not reliable without parsing SQL, which we want to avoid.
  • Parsing the where condition of db_update and db_delete to reject injected statements: replaced by selecting matching rowids under a random per-call column alias, checking the result's columns, and writing by bound rowids, all in one transaction.
• Tables live in a Durable Object facet rather than under a table prefix in the host's database. A prefix only isolates tables while every statement goes through our tools, and db_query accepts arbitrary SQL.

Code Changes

• docs/agents/structured-memory.md (new, not yet linked from docs/agents/index.md):
  • How it works: createStructuredMemory(ctx, { name }), the facet class export, and adapters for AiSdkHarness and the pi harness, following the agents/websearch layout.
  • Tool reference: db_describe, db_query, the structured write tools, db_undo, and a db_execute escape hatch. Write tools take an optional reason that is stored in the history.
  • Security: facet isolation, the read/write split, how row conditions are checked, and permissions with "allow", "ask", and "deny" levels. "ask" maps to needsApproval in the AI SDK; pi approval is a TODO until the harness supports it.
  • Durability and recovery: one transaction per operation, pi replay settings, and planned history and undo using triggers. Dropping a table renames and hides it, and is refused when another table references it with a foreign key. There is no drop-column tool, because a dropped column cannot yet be recorded in a way that can be undone.

[changeset-bot]

⚠️ No Changeset found

Latest commit: efaa171

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[agent-think]

✅ agents import sizes: no significant changes (000d076d → efaa1715, workflow run)