PhoenixClaw Ledger: Zero-Effort Financial Tracking

PhoenixClaw Ledger automatically extracts financial transactions from your daily conversations and payment screenshots, requiring zero manual input.

Core Capabilities

| Feature | Description | |---------|-------------| | Semantic Expense Detection | AI identifies spending mentions in natural conversation | | Screenshot Recognition | Extracts transaction data from payment app screenshots | | Smart Categorization | Auto-categorizes based on merchant and context | | Budget Tracking | Monthly budget alerts and progress visualization | | Financial Insights | Pattern analysis integrated into journal Growth Notes | | Goal Management | Savings, budget control, habit, and wishlist goals | | Weekly Reports | Automated Sunday 9 PM spending recap | | Query Support | Real-time natural language financial inquiries | | Spending Trends | Multi-month analytical spending visualization | | Transaction Browser | Interactive complete transaction history view |

Workflow

As a PhoenixClaw plugin, Ledger hooks into the post-moment-analysis phase:

1. Receive Moments: Get identified moments from PhoenixClaw Core
2. Detect Finances: Scan for expense/income signals in text and media
   • Text: Semantic patterns (see references/expense-detection.md)
   • Media: Payment screenshots (see references/payment-screenshot.md)
3. Extract Data: Parse amount, merchant, category, timestamp
4. Categorize: Apply rules from references/merchant-category-map.md
5. Deduplicate: Prevent double-counting same transaction
6. Store: Write to ~/PhoenixClaw/Finance/ledger.yaml
7. Export: Generate journal section using assets/daily-finance-section.md

Explicit Triggers

While passive by design, users can interact directly:

• "How much did I spend today/this week/this month?"
• "Show my expense breakdown"
• "Set my monthly budget to [amount]"
• "What are my top spending categories?"
• "Generate financial report for [period]"
• "Set a savings goal for [amount] by [date]"
• "Show my spending trends"
• "Browse all my transactions"
• "How am I doing on my goals?"

Output Structure

~/PhoenixClaw/
├── Journal/
│   ├── daily/2026-02-02.md    # Contains 💰 Finance section
│   └── weekly/2026-W05.md     # Weekly financial recaps
│
└── Finance/                    # Ledger-specific directory
    ├── ledger.yaml             # Structured transaction data
    ├── budget.yaml             # Budget configuration
    ├── goals.yaml              # Financial goals tracking
    ├── transactions.md         # Transaction browser view
    ├── monthly/
    │   └── 2026-02.md          # Monthly financial reports
    └── yearly/
        └── 2026.md             # Annual summaries

Configuration

Ledger-specific settings in ~/.phoenixclaw/config.yaml:

plugins:
  phoenixclaw-ledger:
    enabled: true
    default_currency: CNY       # or USD, EUR, etc.
    budget_monthly: 5000        # Monthly budget amount
    categories_custom: []       # User-defined categories
    screenshot_confidence: 0.7  # Min confidence for auto-record

Cron & Scheduled Reports

Ledger uses PhoenixClaw Core's cron infrastructure plus additional scheduled tasks:

| Task | Schedule | Description | |------|----------|-------------| | Daily Processing | 10 PM (via Core) | Extracts transactions, generates daily section | | Monthly Report | 1st of month, 8 AM | Comprehensive monthly financial summary | | Weekly Summary | Sunday 9 PM (optional) | Weekly spending recap |

Daily Processing (Automatic)

No separate setup required. Ledger hooks into Core's nightly cron:

• Core runs at 10 PM → triggers post-moment-analysis
• Ledger activates, extracts finances, exports to journal

Monthly Report Setup

openclaw cron add \
  --name "PhoenixClaw Ledger monthly report" \
  --cron "0 8 1 * *" \
  --tz "auto" \
  --session isolated \
  --message "Generate monthly financial report for the previous month."

See references/cron-setup.md for full configuration details.

Documentation Reference

References (references/)

• expense-detection.md: Semantic patterns for conversation parsing
• payment-screenshot.md: Screenshot recognition and OCR extraction
• merchant-category-map.md: Merchant to category mapping rules
• category-rules.md: Category definitions and hierarchy
• budget-tracking.md: Budget alerts and progress calculation
• financial-insights.md: Pattern analysis for Growth Notes
• cron-setup.md: Scheduled tasks and report automation
• goal-management.md: Financial goals and progress tracking
• query-patterns.md: Natural language query templates and logic

Assets (assets/)

• expense-callout.md: Template for conversation-detected expenses
• receipt-callout.md: Template for screenshot-detected expenses
• daily-finance-section.md: Journal integration template
• monthly-report.md: Monthly summary template
• yearly-report.md: Annual summary template

---