# todos

Mantenha o estado das tarefas e as notas de handoff junto do contexto do projeto que lhes dá utilidade.

- Canonical: https://docs.xmemo.dev/pt-br/docs/tools/todos
- Locale: pt-BR
- Content-Locale: pt-BR
- Canonical-Content-Digest: 191848e34c6130ea7c7026f86e247cf62ccb063ecf6fa01d5f4acce533a64867
- Edition-Digest: 215b899ee9345dc9f1cb490429fceca8e450a46efef272e47361ce2c2ce4d00f
- Source-Revision: sha256:a208365f51d49c201b173728a752a5cec89775c71d38b55619b7bdb6846d5717

## Tool Reference: `todo`

### Purpose

Crie, atualize, conclua, liste ou exclua explicitamente em massa os TODOs do projeto, mantendo o estado da tarefa junto ao contexto autorizado do projeto.

### Parameters

- `action` (create | update | complete | list | delete_all, required): Operação do dispatcher.
- `todo_id` (string, optional): ID exato do item para atualização ou conclusão.
- `content / title` (string, optional): Texto da tarefa; quando ambos forem fornecidos, eles precisam coincidir.
- `project_id` (string, optional): Identificador do workspace de projeto autorizado.
- `priority / due_at / status / note` (string, optional): Prioridade da tarefa, timestamp de vencimento, transição de status e nota de handoff.
- `item_status / due_before / search / query` (string, optional): Filtros de lista; search e query são exclusivos de list e precisam concordar quando ambos forem fornecidos.
- `limit / cursor / owner_timezone` (integer / string, optional, default: 20 / empty / configured timezone): Controles de paginação e interpretação de datas.
- `client_mutation_id / expected_version` (string / integer, optional): Chave de idempotência para create/update e versão de concorrência otimista para update.
- `confirm_delete_all` (boolean, optional, default: false): true é obrigatório para uma exclusão em massa recuperável e explícita.

### Returns

A saída estruturada identifica a ação e retorna o(s) item(ns) afetado(s), o cursor de paginação, o status da alteração e metadados seguros da tarefa. A exclusão em massa é sempre uma exclusão lógica recuperável.

### Errors

- Falha de autorização: list não possui memory:read ou uma alteração não possui memory:write/capacidade de projeto.
- Falha de validação: create não possui client_mutation_id, update não possui um expected_version positivo ou os campos da ação entram em conflito.
- Rejeição de segurança: delete_all exige confirmação explícita e não está disponível para chamadores de widget/mount-capability.
- Erros de fuso horário, projeto ou concorrência otimista são retornados explicitamente; o dispatcher não ignora campos silenciosamente.

### Examples

#### Crie uma tarefa idempotente



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

#### Liste as tarefas abertas



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

### Related Tools

- [remember](/docs/tools/remember): Salve a decisão ou o fato duradouro por trás de uma tarefa.
- [recall_context](/docs/tools/recall-context): Restaure o contexto da tarefa e do projeto antes de continuar.
- [forget](/docs/tools/forget): Remova um TODO revisado pelo ID exato quando necessário.

## Liste os itens abertos antes de adicionar outro

Ler primeiro evita TODOs duplicados quando vários agentes trabalham no mesmo escopo do projeto.

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