# todos

Keep task state and handoff notes close to the project context that makes them useful.

- Canonical: https://docs.xmemo.dev/docs/tools/todos
- Locale: en-US
- Content-Locale: en-US
- Canonical-Content-Digest: 191848e34c6130ea7c7026f86e247cf62ccb063ecf6fa01d5f4acce533a64867
- Edition-Digest: 28decb202b4aef96f1f25bcf8a9aa4774d1718981f439475f5e8c1df50506587
- Source-Revision: sha256:a208365f51d49c201b173728a752a5cec89775c71d38b55619b7bdb6846d5717

## Tool Reference: `todo`

### Purpose

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

### Parameters

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

### Returns

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.

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

### Examples

#### Create an idempotent task



```typescript
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



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

### Related Tools

- [remember](/docs/tools/remember): Save the durable decision or fact behind a task.
- [recall_context](/docs/tools/recall-context): Restore task and project context before continuing work.
- [forget](/docs/tools/forget): Remove one reviewed TODO by exact ID when needed.

## List open items before adding another

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

```ts
todo({ action: "list" })
```