Transaction Categorization Skill

Purpose

Automatically categorize financial transactions by analyzing merchant names, amounts, and context to assign appropriate spending categories with confidence scores.

Input Format

You will receive a JSON object with:

• transactions: Array of transactions to categorize
• available_categories: List of valid category names
• existing_rules: Array of existing pattern-to-category mappings for reference
• memory_context (optional): Content from TRANSACTION_MEMORY.md with personal context and learnings

Transaction Object

{
  "id": 1,
  "date": "2024-12-15",
  "amount": -45.23,
  "merchant_original": "WHOLEFDS MKTPL #12345",
  "merchant_cleaned": "WHOLEFDS MKTPL",
  "description": "WHOLE FOODS MARKET PURCHASE",
  "account_type": "credit_card"
}

Expected Output

Return a JSON object with categorizations:

{
  "categorizations": [
    {
      "transaction_id": 1,
      "category": "Groceries",
      "confidence": 0.95,
      "rule_pattern": "WHOLEFDS*",
      "reasoning": "Whole Foods Market is a well-known grocery store chain."
    }
  ]
}

Confidence Scoring Guidelines

• 1.00: Absolutely certain (e.g., "WHOLE FOODS" -> Groceries)
• 0.90-0.99: Very confident (e.g., "CHEVRON" -> Transportation)
• 0.80-0.89: Confident with minor ambiguity (e.g., "CVS" could vary)
• 0.70-0.79: Moderately confident (e.g., "AMAZON" - varies widely)
• <0.70: Low confidence, flag for review (e.g., "ACH TRANSFER XYZ")

Context Clues

Amount

• Small pharmacy amounts (<$20): likely Healthcare
• Large pharmacy amounts (>$100): likely Shopping

Account Type

• Credit card payments -> "Credit Card Payment"
• Transfers between accounts -> "Transfer"

Description Keywords

• "PAYMENT THANK YOU" -> Credit Card Payment
• "ATM WITHDRAWAL" -> Transfer
• Contains "MARKET", "FOODS", "GROCERY" -> Groceries
• Contains "RESTAURANT", "CAFE", "PIZZA" -> Dining & Restaurants
• Contains "GAS", "FUEL", "CHEVRON", "SHELL" -> Transportation

Recurring Patterns

• Same merchant, same amount, recurring -> likely Subscription

Ambiguous Cases

• Amazon/Online Retailers: Default to "Shopping" unless description gives clue
• Walmart/Target: Prefer "Shopping" as more general
• CVS/Walgreens: "Healthcare" for small amounts, "Shopping" for large
• ACH Transfers: Flag for review if purpose unclear
• Venmo/PayPal/Zelle: Flag for review - person-to-person

Rule Pattern Guidelines

Use wildcards (*) for flexible matching:

• WHOLEFDS* matches all Whole Foods locations
• SPOTIFY* matches various Spotify formats
• AMAZON.COM* matches Amazon purchases

Avoid overly generic patterns:

• Don't use MARKET* (too broad)
• Don't use CAFE* alone (could match unrelated)

Categories Available

Income

• Salary, Freelance, Investment Income, Other Income

Expenses

• Groceries
• Dining & Restaurants
• Transportation
• Housing
• Healthcare
• Entertainment
• Shopping
• Subscriptions
• Travel
• Personal Care
• Education
• Insurance
• Gifts & Donations
• Pets
• Childcare & Kids
• Home Improvement
• Professional Services
• Fees & Interest
• Taxes

Special

• Uncategorized
• Transfer
• Credit Card Payment

Memory Context Integration (Phase 3)

When memory_context is provided, use it to improve categorization accuracy:

How to Use Memory

1. Read the memory before categorizing transactions
2. Apply learned patterns from "Merchant Patterns & Preferences" section
3. Use personal context (location, household, payment methods) to resolve ambiguities
4. Follow anti-patterns documented in the memory
5. Increase confidence when memory provides clear guidance
6. Decrease confidence when memory suggests ambiguity

Examples of Memory-Enhanced Categorization

Example 1: Time-Based Patterns

Memory says: "Grab weekday mornings (7-9am): Transportation (commute)"
Transaction: GRAB HOLDINGS, $8.50, 2025-08-15 07:30
Without memory: Dining & Restaurants (0.70) - uncertain
With memory: Transportation (0.90) - high confidence due to time pattern

Example 2: Merchant-Specific Rules

Memory says: "Amazon - always flag for review, too varied"
Transaction: AMAZON.COM, $45.99
Without memory: Shopping (0.75)
With memory: Shopping (0.65) - lower confidence, flag for review

Example 3: PayLah/PayNow Extraction

Memory says: "PayLah - check description for actual merchant"
Transaction: PAYLAH, description: "FAIRPRICE FINEST"
Without memory: Transfer (0.80)
With memory: Groceries (0.85) - extracted merchant from description

Example 4: Amount-Based Rules

Memory says: "Guardian Pharmacy: <$20 = Healthcare, >$50 = Shopping"
Transaction: GUARDIAN, $15.50
Without memory: Healthcare (0.75)
With memory: Healthcare (0.90) - amount confirms it's medicine

Example 5: Personal Context

Memory says: "Location: Singapore, Smart Buddy is school canteen"
Transaction: SMART BUDDY, $3.50
Without memory: Dining & Restaurants (0.70)
With memory: Childcare & Kids (0.95) - local context provides certainty

Confidence Adjustments with Memory

When memory provides clear guidance:

• Increase confidence by +0.10 to +0.20 (e.g., 0.75 → 0.90)
• Prefer specific categories over general ones when memory suggests it
• Add memory reference in reasoning: "Based on transaction memory, Grab on weekday mornings is typically commute transportation"

When memory indicates ambiguity or "always flag":

• Decrease confidence by -0.05 to -0.10 (e.g., 0.80 → 0.70)
• Flag for review even if you'd normally be confident
• Note in reasoning: "Transaction memory indicates this merchant varies, flagging for review"

Memory Sections to Pay Attention To

1. Personal Context: Understand user's location, banks, household
2. Merchant Patterns & Preferences: Time-based, usage patterns for specific merchants
3. Known Ambiguous Merchants: Amount-based thresholds, context clues
4. Category Preferences: User's preferences for edge cases
5. Learnings from Past Reviews: Recent confirmations and rejections
6. Anti-Patterns: Things to never auto-categorize
7. Complex Rules & Patterns: Amount ranges, time windows, description parsing

Rule Pattern Suggestions with Memory

When memory shows confirmed patterns:

• Suggest rules confidently if memory confirms the pattern multiple times
• Don't suggest rules if memory says "always flag for review"
• Include conditions (amount ranges) if memory specifies them
• Reference memory in reasoning: "Pattern confirmed in transaction memory"

Important Notes

1. Always provide reasoning for transparency
2. If genuinely unsure, prefer flagging over guessing (confidence < 0.7)
3. Suggest rules conservatively - only for clear patterns
4. Be consistent across similar merchants
5. Process all transactions in the batch
6. NEW: When memory_context is provided, prioritize it over generic categorization logic
7. NEW: Reference memory in reasoning when it influenced your decision