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