Concepts

Koma has two things a person keeps, lists and the items on them, and every tool works on one of the two. The names below are the ones the tools use.

Lists

A list is the one container. The Tasks list, the Notes list, a reading list, a list of contacts, expenses, wines: each is a list with a name, an icon, standing instructions (what the person told Koma about how entries on it are handled) and properties.

  • list_lists returns every live list with its id, its properties with their stable ids, its item count and the ids of the Tasks and Notes lists (tasksListId, notesListId). Resolve a name to an id there before writing: an item filed under a guessed id lands nowhere.
  • create_list creates one. template: "tasks" gives a list of to-dos, which keeps a status and a due date on its items; otherwise properties shape it; omitting both starts it with one text property. Check list_lists first so an existing list is not duplicated.
  • update_list renames a list, changes its icon or layout, replaces its instructions (send the whole text; what you leave out is gone) and adds, renames, retypes, reorders or removes properties. A retype that would lose values answers a preview and writes nothing until the same call is repeated with acknowledgeDataLoss: true.
  • delete_list sends a list and every item on it to the trash; a list that still holds items needs confirmDeleteItems: true. The Tasks list and Life Admin, Koma's own list, refuse.
  • A list opens in one of three layouts, list, kanban or table. A layout is how the list is drawn, not a kind of list.

Items

An item is the one thing on a list: a to-do on the Tasks list, a note on the Notes list, a book on a reading list. Every item has a title, a body as Markdown and a value per property of its list; on a list made for tasks it also has a status and a due date.

  • Status is one of todo, inProgress and completed, on a list that keeps one. Move an item to inProgress when you actually start working on it; leave completed to the person, who decides when something is done. The person sees the change on every device within a second.
  • Due is an ISO instant, on a list that keeps one. 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.
  • The body is Markdown: headings, lists, task lists, bold, links. get_item returns it with a short handle in front of every block and a bodyVersion; update_items changes it with edits against those handles: replace a block, insert next to one, delete, setChecked a checklist item, move, replaceText, or rewrite the whole body pinned to the version read. The older body with a mode still works: append by default, prepend, insertAfter an anchor line, or replace with confirmReplace: true.
  • Subtasks are a checklist in the body, ticked with setChecked as the work moves.
  • get_item returns one item in full: the body with handles, its status and due date where its list keeps them, its values by property id with cells by property name beside them, its list, a line of guidance about its state and, for an item a meeting was recorded into, the attributed transcript once the recording is done.
  • list_items reads one list, or with no listId every item on a list that keeps a status and a due date, ordered by due date. With changedSince it is the changes feed instead: every item whose record moved after that instant, oldest first, deletions as deleted tombstones, and nextChangedSince to pass next time, so an agent that polls makes one call per cycle. query_items filters, sorts, counts or sums one list by its properties, paged with offset and limit.
  • create_items stores up to 100 items on one list in one call, as written; no cleanup pass runs unless enrich is true. An entry's externalId makes re-sending safe, and matchOn merges an entry into the item it matches instead of adding a second. update_items corrects up to 200 items per call: only the fields you send change, values merge per item, and an empty string clears a cell.
  • An item can be archived (set aside, hidden from the list, reversible) or deleted (to the trash).
  • Images on items come from URLs or from create_image_upload, which hands back short-lived upload slots for raw bytes.

Properties

A property is a labelled slot a list gives its items: Author, Status, Price. Each has a type, text, number, date, url, select or multiSelect; a select or multiSelect property has options, each with a stable id.

  • Values are keyed by the property's stable id, or by its name. A select value is an option id or its label, a multiSelect value is an array of them, and an unknown label becomes a new option.
  • Two property ids are reserved, status and dueDate: the pair a list made for tasks keeps. They bind to the status and due date above, can be renamed, and are never retyped or removed. query_items reads them like any other property.
  • A list's properties change through update_list; an item's values through create_items and update_items.

The Tasks and Notes lists

Every account has a Tasks list and a Notes list, and the tools take two words for them wherever a listId goes: "tasks" and "notes".

  • The Tasks list is where a to-do with no other home lands: "remind me to call the dentist" is create_items on "tasks", the default when listId is left out. It keeps a status and a due date, and so does every list made with template: "tasks"; together they are what list_items reads with no listId.
  • The Notes list keeps prose: a plan, meeting notes, a draft, a reference. It is a plain list with no properties, which the person can rename or delete; "notes" reaches it either way and recreates it when it is gone.
  • One list, Life Admin, is Koma's own and cannot be created, written to or deleted from outside.

Moving between lists

move_items re-files items onto another list, by id or by the words "tasks" and "notes". An item keeps its id, body, chat and history; its values follow their properties by id, then by name and type. A value the destination has no place for would be dropped, so a first call that would drop one answers a preview (preview: true, droppedValues) and moves nothing; the same call with acknowledgeDataLoss: true then moves. The status and due date ride along unseen onto a list that keeps neither and show again on the way back. Turning a task into a note is a move to the Notes list; a move into a shared list someone else owns hands the item over to them.

Automations

An automation is a standing order: something Koma does on its own on a schedule or when started, working from the person's connected apps and everything in Koma. "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 Koma, can act through the person's connected apps, and its result lands in the person's Koma chat, not in your conversation. Read it back with get_automation_runs.
  • Creating or updating an automation is not available from outside Koma. The person sets those up in the app, where an approval card shows the schedule and the steps.

Memory

The small set of facts Koma 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 Koma. Writing to it stays in Koma.

The trash

Every delete is soft. delete_items and delete_list tombstone what they delete, and list_deleted shows the trash with the day each entry is purged, about 30 days on. restore_deleted brings one item or list back per call (type: "item" or "list"); restoring a list restores the items deleted with it, and an item whose list is still in the trash asks you to restore the list first. An item whose list is gone for good lands on the Tasks list (movedToDefaultList: true). An already-live entry 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 Koma to remember, read-only
  • their lists with their ids, properties and item counts, the Tasks and Notes lists named by id
  • tasks that are overdue, due today, in progress or due in the next seven days, each once, with its list
  • the newest tasks on the Tasks list and how many there are
  • recent notes
  • automations with their last run
  • three days of activity

Every entry carries its id, so the next call needs no lookup. Optional focusListId narrows the task sections to one list.

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 Koma.