# ledger

에이전트가 지속적인 운영 context를 필요로 할 때 관리되는 ledger와 reminder 표면을 사용합니다.

- Canonical: https://docs.xmemo.dev/ko/docs/tools/ledger
- Locale: ko-KR
- Content-Locale: ko-KR
- Canonical-Content-Digest: 3bc28bb66da214c9eceb8c96db997d55d16493cd954fb2e787f46cdc124e477e
- Edition-Digest: 345113d40b6dc6dff981cffe9489b25088eb6d58e164f523c647d85f9398d272
- Source-Revision: sha256:5ae3da12a28b7c528cd1988ad36022f9c72af84d4498e1c17052666c465b4673

## Tool Reference: `ledger`

### Purpose

Ledger dispatcher를 통해 관리되는 financial transaction과 external-service renewal reminder를 구조화된 summary 및 audit 경계와 함께 관리합니다.

### Parameters

- `action` (add_expense | list | summary | overview | update_transaction, required): caller가 선택하는 Ledger operation이며 이 다섯 가지 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 분류, 날짜 및 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): 정확한 update target, optimistic concurrency version 및 허용되는 update field입니다.
- `owner_timezone / project_id` (string, optional): 날짜 해석과 authorized project/team boundary입니다.
- `limit / offset / months` (integer / boolean, optional, default: 20 / 0 / 6 / false): pagination, summary horizon 및 structured-output control입니다.

### Returns

요청한 transaction, summary group 또는 overview와 user-facing text summary가 structured output에 포함됩니다. Widget caller는 refresh metadata를 받을 수 있으며 raw secret은 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): governed lifecycle을 통해 검토된 Ledger record를 제거합니다.

## 기록하기 전에 검토하기

현재 summary를 먼저 확인합니다. ledger record는 financial data이므로 중복 항목은 누락된 항목보다 판단하기 어렵습니다.

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