Mobius

Sign inGet started
GuidesAPI Reference
Sign inGet started

Concepts

Tables

A table is a project-scoped collection of JSON rows with an optional schema. Tables give automations, agents, and humans a shared structured data surface without standing up a separate database.

Use tables for:

  • Durable agent memory.
  • Work queues and triage state.
  • Small operational datasets.
  • Lookup data used by actions or prompts.
  • State that should emit row-change source events.

Shape

Each table has:

  • A stable name.
  • Optional description.
  • Optional JSON Schema for row validation.
  • Optional declared indexes.
  • Access mode and owner scope.

Rows store JSON data keyed by column name. Each row has a version for optimistic concurrency. Pass the current version on updates; a mismatch returns 409 Conflict.

Access modes

Tables can be project-visible or private to an owner principal. Agents use private or granted tables as long-term memory. Project tables are better for shared operational data that humans and multiple automations need to inspect.

Agent table grants decide whether an agent can read, append, or write a table:

PUT /v1/projects/{project}/agents/{id}/table-grants

Reading and writing rows

The API supports CRUD, query, and search:

POST /v1/projects/{project}/tables
POST /v1/projects/{project}/tables/{table_name}/rows
POST /v1/projects/{project}/tables/{table_name}/rows/query
POST /v1/projects/{project}/tables/{table_name}/rows/search

Filters can use direct equality or operators such as $eq, $ne, $gt, $gte, $lt, $lte, $in, and $exists.

Agent memory

When an agent step or session has table grants, Mobius can surface those tables to the agent as memory. The agent sees the table names and access mode; tools enforce the actual read/write behavior.

Keep memory tables narrow:

  • One table per durable concept.
  • JSON Schema for important fields.
  • Private owner scope when the memory belongs to one agent.
  • Project scope when the data is intentionally shared.

Source events

Table row changes emit public events:

table.row.inserted
table.row.updated
table.row.deleted

These events can start automations or resume wait_for_event steps. They include table and row metadata in the source-event envelope.