Reference

ledger

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

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.

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

Public MCP tool

ledger

Purpose

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

When to use

Record an expense or other supported transaction with amount, currency, date, and merchant context.
List, summarize, or overview authorized Ledger records with date, category, currency, or project filters.
Create or manage subscription renewal reminders and optionally connect their review cycle to TODOs.

When NOT to use

Do not use generic remember for financial records; ledger preserves the financial data contract.
Do not infer a cross-currency total; summaries keep currencies separate when aggregation is unsafe.
Do not update or delete a record without the required exact ID/version and user authorization.
The REST API accepts a wider field set than the public MCP tool; see https://xmemo.dev/docs/api/memory for scope, bucket, team and provenance filters.

Required scope

Read actions require memory:read; transaction and subscription mutations require memory:write in the public chat surface.
The authenticated owner/team/scope boundary governs every Ledger record and reminder operation.

Parameters

Name	Type	Description
`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	Core transaction fields; amount and currency are required for financial writes.
`transaction_date / category / merchant / payment_method / note`	string	Optional transaction classification, date, and note fields.
`query / date_from / date_to / min_amount / max_amount`	string / number	List and summary filters.
`transaction_id / expected_version / patch`	string / integer / object	Exact update target, optimistic concurrency version, and allowed update fields.
`owner_timezone / project_id`	string	Date interpretation and authorized project/team boundary.
`limit / offset / months`	integer / boolean · default: 20 / 0 / 6 / false	Pagination, summary horizon, and structured-output controls.

Return schema

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.

Examples

Record an expense

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

Review a monthly summary

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

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.

remember — Use only for non-financial durable context around the record.
todos — Use TODO for general follow-up tasks; ledger can opt into review reminders.
forget — Remove a reviewed Ledger record through its governed lifecycle.

Source: MCP reference