# ledger

Use governed ledger and reminder surfaces when an agent needs durable operational context.

- Canonical: https://docs.xmemo.dev/docs/tools/ledger
- Locale: en-US
- Content-Locale: en-US
- Canonical-Content-Digest: 3bc28bb66da214c9eceb8c96db997d55d16493cd954fb2e787f46cdc124e477e
- Edition-Digest: 5c500388aa9c2df3dc27bfbe92c48bbafa017a6b87a190bb978b72058fb93f79
- Source-Revision: sha256:5ae3da12a28b7c528cd1988ad36022f9c72af84d4498e1c17052666c465b4673

## Tool Reference: `ledger`

### Purpose

Manage governed financial transactions and external-service renewal reminders through the Ledger dispatcher, with structured summaries and audit boundaries.

### Parameters

- `action` (add_expense | list | summary | overview | update_transaction, required): Ledger operation selected by the caller. Only these five literal values are accepted.
- `item / amount / transaction_type / currency` (string / number, optional): Core transaction fields; amount and currency are required for financial writes.
- `transaction_date / category / merchant / payment_method / note` (string, optional): Optional transaction classification, date, and note fields.
- `query / date_from / date_to / min_amount / max_amount` (string / number, optional): List and summary filters.
- `transaction_id / expected_version / patch` (string / integer / object, optional): Exact update target, optimistic concurrency version, and allowed update fields.
- `owner_timezone / project_id` (string, optional): Date interpretation and authorized project/team boundary.
- `limit / offset / months` (integer / boolean, optional, default: 20 / 0 / 6 / false): Pagination, summary horizon, and structured-output controls.

### Returns

Structured output contains the requested transaction, summary groups, or overview plus a user-facing text summary. Widget callers may receive refresh metadata; raw secrets are never part of the response contract.

### Errors

- Authorization failure: the token lacks memory:read for reads or memory:write for mutations.
- Validation failure: required transaction fields, date formats, currency, or action values are invalid.
- Concurrency failure: an update has a stale expected_version or the exact transaction is not found.
- Aggregation boundary: records in different currencies are reported separately instead of producing a false combined total.

### Examples

#### Record an expense



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

#### Review a monthly summary



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

### Related Tools

- [remember](/docs/tools/remember): Use only for non-financial durable context around the record.
- [todos](/docs/tools/todos): Use TODO for general follow-up tasks; ledger can opt into review reminders.
- [forget](/docs/tools/forget): Remove a reviewed Ledger record through its governed lifecycle.

## Review before recording

Check the current summary first; ledger records are financial data and a duplicate entry is harder to reason about than a missing one.

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