Concepts

Roma has a small number of things a person keeps, and every tool works on one of them. The names below are the ones the tools use.

Tasks

A task is a to-do: a title, an optional Markdown body, a status, a priority and an optional due time. It lives in one project or is unsorted.

  • Status is one of todo, inProgress and completed. Move a task to inProgress when you start working on it and to completed when it is done; the person sees the change on every device within a second.
  • Priority is low, medium or high. Most tasks carry none.
  • Due is an ISO instant. A due time at midnight in the person's zone is read as a due day; a time of day is a moment, and the person is reminded then.
  • Subtasks are tasks with a parent. get_task_context returns a task with its subtasks and its project, the picture you need before picking work up.
  • A task's body is Markdown. update_task appends to it by default; a full replacement needs mode: "replace" and confirmReplace: true.

Notes

A note is prose the person keeps: a plan, meeting notes, a draft, a reference. It lives in a project or is unsorted, and its body is Markdown: headings, lists, task lists, bold, links.

  • create_note stores what you send as written. No cleanup pass runs on it.
  • update_note appends by default. prepend, insertAfter (place text after a line you name) and replace are the other modes; replace needs confirmReplace: true.
  • A note a meeting was recorded into also returns the attributed transcript through get_note once the recording is done.

Projects

A project groups tasks, notes and collections. Every item is in exactly one project or in none. There are no tags.

  • list_projects resolves names to ids. Do that before filing anything: a task filed under a guessed id lands nowhere.
  • create_project and update_project create and rename. One project, Life Admin, is Roma's own and cannot be created or written to from outside.
  • Moving a task is update_task with a projectId; null moves it to unsorted.

Collections

A collection is a typed list: a table with named columns, one row per thing. A reading list, a list of contacts, expenses, wines.

  • Columns have a type: text, number, date, url, select or multiSelect. A select or multiSelect column has options, each with a stable id.
  • Rows carry values keyed by column id. A select value is an option id and a multiSelect value is an array of them; when adding rows you may send the option's label and an unknown label becomes a new option.
  • list_collections returns every list with its columns and their ids, the ids you need before writing rows. get_collection_items pages through a list's rows, newest first, 200 per page.
  • add_collection_items adds up to 200 rows in one call. Without matchOn every row is inserted, so a retried batch duplicates; pass matchOn to merge into rows that match on a column.
  • update_collection_items corrects up to 200 rows of one list per call. Values merge per row: only the keys you send change, and an empty string clears a cell.
  • A row can be archived (set aside, hidden from the list, reversible) or deleted (to the trash).
  • Column editing is not available from outside Roma; a list's name and instructions are.
  • Images on rows come from URLs or from create_image_upload, which hands back short-lived upload slots for raw bytes.

Automations

An automation is a standing order: something Roma does on its own on a schedule or when started, working from the person's connected apps and everything in Roma. "Every weekday at 8, read my inbox and leave a digest in my chat."

  • list_automations returns each live automation with its schedule, its next run and the last run's status.
  • get_automation_runs returns an automation's recent runs: what it did, the closing message it left, any error.
  • run_automation starts one now. The run happens inside Roma, can act through the person's connected apps, and its result lands in the person's Roma chat, not in your conversation. Read it back with get_automation_runs.
  • Creating or updating an automation is not available from outside Roma. The person sets those up in the app, where an approval card shows the schedule and the steps.

Memory

The small set of facts Roma knows about the person before every turn: where they live, what they are working on, how they like things done. get_context returns it read-only, so an outside conversation can be consistent with the one inside Roma. Writing to it stays in Roma.

The trash

Every delete is soft. delete_task, delete_note, delete_collection and delete_collection_items tombstone the item, and list_deleted shows the trash with the day each item is purged, about 30 days on. restore_deleted brings one item back per call; restoring a collection restores the rows deleted with it. An already-live item is a success, not an error.

Context

get_context is the one call to make at the start of a conversation. It returns:

  • the person's name, timezone, today's date, weekday and local time
  • what they asked Roma to remember, read-only
  • their projects
  • tasks that are overdue, due today, in progress or due in the next seven days, each once
  • the newest unsorted tasks and how many there are
  • recent notes
  • collections with their columns
  • automations with their last run
  • three days of activity

Every item carries its id, so the next call needs no lookup. Optional focusProjectId narrows the task sections to one project.

Identity and audit

What an agent writes is recorded in the person's event log as their own action, since they asked for it, and is marked as coming through this connection. Body edits are versioned, so a bad edit can be undone in Roma.