# ledger

当 agent 需要持久 operational context 时，使用受治理的 ledger 和 reminder 界面。

- Canonical: https://docs.xmemo.dev/zh/docs/tools/ledger
- Locale: zh-CN
- Content-Locale: zh-CN
- Canonical-Content-Digest: 3bc28bb66da214c9eceb8c96db997d55d16493cd954fb2e787f46cdc124e477e
- Edition-Digest: d5afcc72ea3515ee67247deab3f5aa4014d1add01f07c8cc8bc54647e78845b3
- Source-Revision: sha256:5ae3da12a28b7c528cd1988ad36022f9c72af84d4498e1c17052666c465b4673

## Tool Reference: `ledger`

### Purpose

通过 Ledger dispatcher 管理受治理的 financial transaction 和 external-service renewal reminder，并提供结构化 summary 与 audit boundary。

### Parameters

- `action` (add_expense | list | summary | overview | update_transaction, required): 由 caller 选择的 Ledger operation。只接受这五个 literal values。
- `item / amount / transaction_type / currency` (string / number, optional): 核心 transaction fields；financial write 必须提供 amount 和 currency。
- `transaction_date / category / merchant / payment_method / note` (string, optional): 可选的 transaction classification、date 和 note fields。
- `query / date_from / date_to / min_amount / max_amount` (string / number, optional): List 和 summary filters。
- `transaction_id / expected_version / patch` (string / integer / object, optional): 准确的 update target、optimistic concurrency version 和允许的 update fields。
- `owner_timezone / project_id` (string, optional): 日期解释和已授权的 project/team boundary。
- `limit / offset / months` (integer / boolean, optional, default: 20 / 0 / 6 / false): Pagination、summary horizon 和 structured-output controls。

### Returns

Structured output 包含请求的 transaction、summary groups 或 overview，以及面向用户的 text summary。Widget caller 可能收到 refresh metadata；raw secrets 永远不属于 response contract。

### Errors

- Authorization failure：token 在读取时缺少 memory:read，或在 mutation 时缺少 memory:write。
- Validation failure：所需 transaction fields、date formats、currency 或 action values 无效。
- Concurrency failure：update 使用了过时的 expected_version，或找不到准确的 transaction。
- Aggregation boundary：不同 currencies 的 records 会分开报告，不会生成虚假的 combined total。

### Examples

#### 记录 expense



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

#### 审查月度 summary



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

### Related Tools

- [remember](/docs/tools/remember): 只用于 record 周围的非 financial durable context。
- [todos](/docs/tools/todos): 一般 follow-up task 使用 TODO；ledger 可以选择加入 review reminder。
- [forget](/docs/tools/forget): 通过受治理的 lifecycle 移除经过审查的 Ledger record。

## 记录前先审查

先检查当前 summary；ledger record 属于 financial data，重复条目比缺失条目更难判断。

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