todos

List open items before adding another

Reading first avoids duplicate TODOs when several agents work in the same project scope.

todo({ action: "list" })

Public MCP tool

todo

Purpose

Create, update, complete, list, or explicitly bulk-delete project TODOs while preserving task state near its authorized project context.

When to use

A user needs durable task state, due dates, priority, completion, or a handoff list.
A project workspace needs a governed TODO mutation with its signed mount capability.
The caller needs to list open, in-progress, completed, or all authorized items.

When NOT to use

Do not use TODOs for general durable facts or decisions; use remember.
Do not store financial transactions as TODO content; use ledger.
Do not call delete_all without an explicit user request and confirm_delete_all=true.
The REST API accepts a wider field set than the public MCP tool; see /docs/api/memory for scope, bucket, team and provenance filters.

Required scope

List uses memory:read; create, update, complete, and delete_all use memory:write in the public chat surface.
Project Workspace mutations additionally require a valid mount_capability and project_id.

Parameters

Name	Type	Description
`action`	create \| update \| complete \| list \| delete_all · required	Dispatcher operation.
`todo_id`	string	Exact item ID for update or completion.
`content / title`	string	Task text; when both are supplied they must match.
`project_id`	string	Authorized project workspace identifier.
`priority / due_at / status / note`	string	Task priority, due timestamp, status transition, and handoff note.
`item_status / due_before / search / query`	string	List filters; search and query are list-only and must agree when both are supplied.
`limit / cursor / owner_timezone`	integer / string · default: 20 / empty / configured timezone	Pagination and date interpretation controls.
`client_mutation_id / expected_version`	string / integer	Idempotency key for create/update and optimistic concurrency version for update.
`confirm_delete_all`	boolean · default: false	Required true for explicit recoverable bulk deletion.

Return schema

Structured output identifies the action and returns the affected item(s), pagination cursor, mutation status, and safe task metadata. Bulk deletion is always recoverable soft deletion.

Examples

Create an idempotent task

todo({
  action: "create",
  content: "Review the MCP scope matrix",
  client_mutation_id: "task-review-scope-001",
  due_at: "2026-08-25T09:00:00Z"
})

List open tasks

todo({ action: "list", item_status: "open", limit: 10 })

Errors

Authorization failure: list lacks memory:read or a mutation lacks memory:write/project capability.
Validation failure: create lacks client_mutation_id, update lacks a positive expected_version, or action fields conflict.
Safety rejection: delete_all requires explicit confirmation and is unavailable to widget/mount-capability callers.
Timezone, project, or optimistic-concurrency errors are returned explicitly; the dispatcher does not silently ignore fields.

remember — Save the durable decision or fact behind a task.
recall_context — Restore task and project context before continuing work.
forget — Remove one reviewed TODO by exact ID when needed.

Source: SDK workflow helpers