✓ Verified 📁 File Management ✓ Enhanced Data

Finance Skill

Personal finance memory layer.

Rating: 4.5 (33 reviews)
Downloads: 13,966 downloads
Version: 1.0.0

Overview

Personal finance memory layer.

Complete Documentation

View Source →

Finance Skill

Personal finance memory layer. Parse statements, store transactions, query spending.

Data Location

Transactions: ~/.openclaw/workspace/finance/transactions.json
Raw statements: ~/.openclaw/workspace/finance/statements/

Storage convention: OpenClaw workspace (~/.openclaw/workspace/) is the standard location for persistent user data. This matches where session-memory and other hooks store agent data. Credentials/config would go in ~/.config/finance/ if needed.

Tools

1. Parse Statement

When user shares a statement (image or PDF):

⚠️ IMPORTANT: Telegram/channel previews truncate PDFs! Always extract with pypdf first to get ALL pages:

bash

python3 -c "
import pypdf
reader = pypdf.PdfReader('/path/to/statement.pdf')
for i, page in enumerate(reader.pages):
    print(f'=== PAGE {i+1} ===')
    print(page.extract_text())
"

Then parse the full text output:

Extract transactions from ALL pages
Return JSON array: [{date, merchant, amount, category}, ...]
Run scripts/add-transactions.sh to append to store
Verify total matches statement (sum of expenses should equal "Total purchases")

Extraction format:

text

Each transaction: {"date": "YYYY-MM-DD", "merchant": "name", "amount": -XX.XX, "category": "food|transport|shopping|bills|entertainment|health|travel|other"}
Negative = expense, positive = income/refund.

Categories:

food: restaurants, groceries, coffee, fast food
transport: Waymo, Uber, gas, public transit
shopping: retail, online purchases
bills: utilities, subscriptions
entertainment: movies, concerts, theme parks
health: pharmacy, doctors
travel: hotels, flights

2. Query Transactions

User asks about spending → read transactions.json → filter/aggregate → answer

Example queries:

"How much did I spend last month?" → sum all negative amounts in date range
"What did I spend on food?" → filter by category
"Show my biggest expenses" → sort by amount

3. Add Manual Transaction

User says "I spent $X at Y" → append to transactions.json

File Format

json

{
  "transactions": [
    {
      "id": "uuid",
      "date": "2026-02-01",
      "merchant": "Whole Foods",
      "amount": -87.32,
      "category": "food",
      "source": "statement-2026-01.pdf",
      "added": "2026-02-09T19:48:00Z"
    }
  ],
  "accounts": [
    {
      "id": "uuid",
      "name": "Coinbase Card",
      "type": "credit",
      "lastUpdated": "2026-02-09T19:48:00Z"
    }
  ]
}

Usage Flow

User: shares statement image
Agent: extracts transactions via vision, confirms count
Agent: runs add script to store
User: "how much did I spend on food?"
Agent: reads store, filters, answers

Dependencies

jq — for JSON transaction storage and querying (apt install jq / brew install jq)
pypdf — for full PDF text extraction (pip3 install pypdf)

Lessons Learned

Telegram truncates PDF previews — always use pypdf to get all pages
Verify totals — sum extracted expenses and compare to statement total before importing
Coinbase Card — no Plaid support, statement upload only

Future: Plaid Integration

Add finance_connect tool for Plaid OAuth flow
Auto-sync transactions from connected banks
Same query interface, different data source

Installation

Terminal bash


openclaw install finance-skill

Copied!

💻Code Examples

"

.txt

Then parse the full text output:
1. Extract transactions from ALL pages
2. Return JSON array: `[{date, merchant, amount, category}, ...]`
3. Run `scripts/add-transactions.sh` to append to store
4. **Verify total matches statement** (sum of expenses should equal "Total purchases")

**Extraction format:**

Negative = expense, positive = income/refund.

negative--expense-positive--incomerefund.txt

**Categories:**
- food: restaurants, groceries, coffee, fast food
- transport: Waymo, Uber, gas, public transit
- shopping: retail, online purchases
- bills: utilities, subscriptions
- entertainment: movies, concerts, theme parks
- health: pharmacy, doctors
- travel: hotels, flights

### 2. Query Transactions
User asks about spending → read transactions.json → filter/aggregate → answer

**Example queries:**
- "How much did I spend last month?" → sum all negative amounts in date range
- "What did I spend on food?" → filter by category
- "Show my biggest expenses" → sort by amount

### 3. Add Manual Transaction
User says "I spent $X at Y" → append to transactions.json

## File Format

example.sh

python3 -c "
import pypdf
reader = pypdf.PdfReader('/path/to/statement.pdf')
for i, page in enumerate(reader.pages):
    print(f'=== PAGE {i+1} ===')
    print(page.extract_text())
"

example.json

{
  "transactions": [
    {
      "id": "uuid",
      "date": "2026-02-01",
      "merchant": "Whole Foods",
      "amount": -87.32,
      "category": "food",
      "source": "statement-2026-01.pdf",
      "added": "2026-02-09T19:48:00Z"
    }
  ],
  "accounts": [
    {
      "id": "uuid",
      "name": "Coinbase Card",
      "type": "credit",
      "lastUpdated": "2026-02-09T19:48:00Z"
    }
  ]
}