# ledger

Use as superfícies governadas de ledger e lembretes quando um agente precisar de contexto operacional duradouro.

- Canonical: https://docs.xmemo.dev/pt-br/docs/tools/ledger
- Locale: pt-BR
- Content-Locale: pt-BR
- Canonical-Content-Digest: 3bc28bb66da214c9eceb8c96db997d55d16493cd954fb2e787f46cdc124e477e
- Edition-Digest: 809c97440f28c5e98a7654f7b1d67188ab4ab81e8a5334ea6677a3f71419477f
- Source-Revision: sha256:5ae3da12a28b7c528cd1988ad36022f9c72af84d4498e1c17052666c465b4673

## Tool Reference: `ledger`

### Purpose

Gerencie transações financeiras e lembretes de renovação de serviços externos por meio do dispatcher do Ledger, com resumos estruturados e limites de auditoria.

### Parameters

- `action` (add_expense | list | summary | overview | update_transaction, required): Operação do Ledger escolhida pelo chamador. Somente estes cinco valores literais são aceitos.
- `item / amount / transaction_type / currency` (string / number, optional): Campos essenciais da transação; amount e currency são obrigatórios para gravações financeiras.
- `transaction_date / category / merchant / payment_method / note` (string, optional): Campos opcionais de classificação, data e observação da transação.
- `query / date_from / date_to / min_amount / max_amount` (string / number, optional): Filtros de lista e resumo.
- `transaction_id / expected_version / patch` (string / integer / object, optional): Alvo exato da atualização, versão de concorrência otimista e campos de atualização permitidos.
- `owner_timezone / project_id` (string, optional): Interpretação de datas e limite autorizado do projeto/equipe.
- `limit / offset / months` (integer / boolean, optional, default: 20 / 0 / 6 / false): Controles de paginação, horizonte do resumo e saída estruturada.

### Returns

A saída estruturada contém a transação, os grupos do resumo ou a visão geral solicitada, além de um resumo em texto voltado ao usuário. Chamadores de widget podem receber metadados de atualização; segredos brutos nunca fazem parte do contrato de resposta.

### Errors

- Falha de autorização: o token não possui memory:read para leituras ou memory:write para alterações.
- Falha de validação: campos obrigatórios da transação, formatos de data, moeda ou valores da ação são inválidos.
- Falha de concorrência: uma atualização tem expected_version antigo ou a transação exata não foi encontrada.
- Limite de agregação: registros em moedas diferentes são informados separadamente em vez de produzir um total combinado falso.

### Examples

#### Registre uma despesa



```typescript
ledger({
  action: "add_expense",
  item: "Domain renewal",
  amount: 18.00,
  currency: "USD",
  transaction_date: "2026-08-21",
  category: "software"
})
```

#### Revise um resumo mensal



```typescript
ledger({ action: "summary", months: 1 })
```

### Related Tools

- [remember](/docs/tools/remember): Use somente para contexto duradouro não financeiro relacionado ao registro.
- [todos](/docs/tools/todos): Use TODO para tarefas gerais de acompanhamento; o ledger pode adicionar lembretes de revisão.
- [forget](/docs/tools/forget): Remova um registro do Ledger revisado por meio do ciclo de vida governado.

## Revise antes de registrar

Confira o resumo atual primeiro; registros do ledger são dados financeiros, e uma entrada duplicada é mais difícil de analisar do que uma entrada ausente.

```ts
ledger({ action: "summary", months: 1 })
```