# ledger

agentが永続的な運用contextを必要とする場合に、governed ledgerとreminderのsurfaceを利用します。

- Canonical: https://docs.xmemo.dev/ja/docs/tools/ledger
- Locale: ja-JP
- Content-Locale: ja-JP
- Canonical-Content-Digest: 3bc28bb66da214c9eceb8c96db997d55d16493cd954fb2e787f46cdc124e477e
- Edition-Digest: 2b3f117b771bace2278813cb351067a1752b9e75dec6e486d9e520ce37562252
- Source-Revision: sha256:5ae3da12a28b7c528cd1988ad36022f9c72af84d4498e1c17052666c465b4673

## Tool Reference: `ledger`

### Purpose

governedなfinancial transactionとexternal-service renewal reminderをLedger dispatcherで管理し、structured summaryとaudit boundaryを提供します。

### Parameters

- `action` (add_expense | list | summary | overview | update_transaction, required): callerが選択したLedger operationです。これら5つのliteral valueだけが受け付けられます。
- `item / amount / transaction_type / currency` (string / number, optional): 主要なtransaction fieldです。financial writeにはamountとcurrencyが必要です。
- `transaction_date / category / merchant / payment_method / note` (string, optional): 任意のtransaction classification、date、note fieldです。
- `query / date_from / date_to / min_amount / max_amount` (string / number, optional): Listとsummaryのfilterです。
- `transaction_id / expected_version / patch` (string / integer / object, optional): exact update target、optimistic concurrency version、許可されたupdate fieldです。
- `owner_timezone / project_id` (string, optional): date interpretationと認可済みproject/team boundaryです。
- `limit / offset / months` (integer / boolean, optional, default: 20 / 0 / 6 / false): pagination、summary horizon、structured-output controlです。

### Returns

Structured outputには要求されたtransaction、summary group、またはoverviewと、user-facing text summaryが含まれます。Widget callerにはrefresh metadataが返る場合があります。raw secretsはresponse contractに決して含まれません。

### Errors

- Authorization failure: tokenにread用のmemory:read、またはmutation用のmemory:writeがありません。
- Validation failure: 必須のtransaction field、date format、currency、またはaction valueが無効です。
- Concurrency failure: updateのexpected_versionが古いか、exact transactionが見つかりません。
- Aggregation boundary: 異なるcurrencyのrecordは、誤った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周辺のnon-financial durable contextにだけ使用します。
- [todos](/docs/tools/todos): 一般的なfollow-up taskにはTODOを使い、ledgerではreview reminderを任意に追加できます。
- [forget](/docs/tools/forget): review済みのLedger recordを、そのgoverned lifecycleを通じて削除します。

## 記録する前に確認する

まず現在のsummaryを確認します。ledger recordはfinancial dataであり、欠落よりも重複のほうが判断しにくいためです。

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