# todos

将 task state 和 handoff note 保存在使其有用的 project context 附近。

- Canonical: https://docs.xmemo.dev/zh/docs/tools/todos
- Locale: zh-CN
- Content-Locale: zh-CN
- Canonical-Content-Digest: 191848e34c6130ea7c7026f86e247cf62ccb063ecf6fa01d5f4acce533a64867
- Edition-Digest: 29a27b150b19b39a974d00662432325a2ec2c3399873e7e181964b1f853bd9b1
- Source-Revision: sha256:a208365f51d49c201b173728a752a5cec89775c71d38b55619b7bdb6846d5717

## Tool Reference: `todo`

### Purpose

创建、更新、完成、列出或明确批量删除 project TODO，同时将 task state 保存在其已授权的 project context 附近。

### Parameters

- `action` (create | update | complete | list | delete_all, required): Dispatcher operation。
- `todo_id` (string, optional): 用于 update 或 completion 的准确 item ID。
- `content / title` (string, optional): Task text；如果同时提供，两者必须一致。
- `project_id` (string, optional): 已授权的 project workspace identifier。
- `priority / due_at / status / note` (string, optional): Task priority、due timestamp、status transition 和 handoff note。
- `item_status / due_before / search / query` (string, optional): List filters；search 和 query 仅用于 list，如果同时提供则必须一致。
- `limit / cursor / owner_timezone` (integer / string, optional, default: 20 / empty / configured timezone): Pagination 和日期解释控制项。
- `client_mutation_id / expected_version` (string / integer, optional): create/update 的幂等 key，以及 update 的 optimistic concurrency version。
- `confirm_delete_all` (boolean, optional, default: false): 执行明确的可恢复批量删除所需的 true 值。

### Returns

Structured output 会标识 action，并返回受影响的 item(s)、pagination cursor、mutation status 和安全的 task metadata。Bulk deletion 始终是可恢复的 soft deletion。

### Errors

- Authorization failure：list 缺少 memory:read，或 mutation 缺少 memory:write/project capability。
- Validation failure：create 缺少 client_mutation_id，update 缺少正数 expected_version，或 action fields 互相冲突。
- Safety rejection：delete_all 需要明确确认，widget/mount-capability caller 不可使用。
- Timezone、project 或 optimistic-concurrency errors 会被明确返回；dispatcher 不会静默忽略 fields。

### Examples

#### 创建幂等 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"
})
```

#### 列出未完成 task



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

### Related Tools

- [remember](/docs/tools/remember): 保存 task 背后的持久 decision 或 fact。
- [recall_context](/docs/tools/recall-context): 继续工作前恢复 task 和 project context。
- [forget](/docs/tools/forget): 需要时按准确 ID 删除一个经过审查的 TODO。

## 添加新项前先列出未完成项

先读取可以避免多个 agent 在同一 project scope 中工作时创建重复的 TODO。

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