PocketClaw

Household memory vault. Stores gift cards, coupons, grocery preferences, and standing arrangements so nothing gets lost.

Data Files

Data files live in the agent's workspace root (same directory as MEMORY.md, AGENTS.md):

• wallet.json — gift cards, coupons, store credit
• grocery-history.json — recurring items, brand preferences, usual stores
• arrangements.json — standing appointments (cleaner, babysitter, etc.)

Use the exact paths the agent already uses for MEMORY.md — same directory.

Data Model

Gift card fields: store, balance, currency (default ILS), code, expiry, link, added_date Coupon fields: store, code, discount, discount_type (percent|amount), expiry, conditions, valid (default true), added_date Store credit fields: store, balance, currency (default ILS), expiry, added_date Arrangement fields: what, when, contact, notes, added_date Grocery fields:

• recurring_items[]: { item, brand (optional), store (optional), frequency (optional), last_bought (optional) }
• brand_preferences: { item_category: preferred_brand } (object mapping categories to brands)
• usual_stores: string[] (array of store names)

Write Protocol

Use scripts/save.py for all writes — never write files directly.

The save.py CLI handles all file operations deterministically:

• Deduplication (store+code matching)
• Store name normalization (case-insensitive)
• Auto-populating added_date
• Atomic writes
• MEMORY.md table sync

CLI Location

# skill_dir = directory containing SKILL.md (this file)
python3 {skill_dir}/scripts/save.py <command> --workspace {workspace} [args]

Commands

Gift card:

python3 {skill_dir}/scripts/save.py gift_card --workspace {workspace} \
  --store "Castro" --balance 200 --currency ILS --code ABC123 --expiry 12/26 --link null

Coupon:

python3 {skill_dir}/scripts/save.py coupon --workspace {workspace} \
  --store "Zara" --code SAVE20 --discount 20 --discount-type percent --expiry 2026-06-01

Store credit:

python3 {skill_dir}/scripts/save.py store_credit --workspace {workspace} \
  --store "H&M" --balance 50 --currency ILS

Grocery item:

python3 {skill_dir}/scripts/save.py grocery --workspace {workspace} \
  --item "חלב תנובה 3%" --store "סופר באבא" --frequency weekly

Brand preference:

python3 {skill_dir}/scripts/save.py brand_pref --workspace {workspace} \
  --category milk --brand "תנובה 3%"

Arrangement:

python3 {skill_dir}/scripts/save.py arrangement --workspace {workspace} \
  --what "cleaning lady" --when "every Thursday" --contact null --notes null

Update balance (after use):

python3 {skill_dir}/scripts/save.py update_balance --workspace {workspace} \
  --store Castro --type gift_card --new-balance 150

Recall (returns JSON):

python3 {skill_dir}/scripts/save.py recall --workspace {workspace} --type gift_cards
python3 {skill_dir}/scripts/save.py recall --workspace {workspace} --type all
# Types: gift_cards, coupons, store_credit, wallet, grocery, arrangements, all

Output Format

Write commands return human-readable confirmation:

• saved: Castro ₪200, code ABC123, expires 12/26
• updated: Castro gift card ₪200 → ₪150
• saved: Zara coupon SAVE20 (20%), expires 2026-06-01

Recall commands return JSON for parsing.

Operations

STORE

When user provides a new item:

1. Identify type:

   • Has depletable balance → gift_card or store_credit
   • Discount code only (no balance) → coupon
   • Grocery habit → grocery
   • Standing appointment → arrangement

2. Extract fields from message. Handle missing fields based on criticality:

Critical fields (ask ONCE if missing):

• gift_card: code — a gift card without a code is unusable. Ask once: "What's the code on the card?" If user says they don't have it, pass --code null.
• coupon: code — same logic.
• arrangement: what + when — both required to make sense. Ask once if either missing.

Non-critical fields (pass null or omit, don't ask):

• expiry, link, conditions, discount_type, contact, notes, brand, frequency

3. Call save.py with extracted fields.

Multi-turn Data Completion

When user provides partial data then follows up with more details (code, expiry, etc.) in the next message, call save.py again with the same store — it will update the existing entry rather than creating a duplicate.

RECALL

1. Parse intent (gift card? coupon? arrangement? grocery?)
2. Call save.py recall --type <type> to get JSON
3. Filter/format response for user
4. Match user's language (Hebrew/English)
5. Flag expired items but don't delete them

UPDATE

1. For balance updates: use update_balance command
2. For other updates: call the original command again (e.g., gift_card, arrangement) — dedup logic will update existing entry

Common updates:

• Balance decrease after use: "used ₪50 from Castro card" → update_balance --new-balance <current-50>
• Mark coupon invalid: read, then re-save with valid: false (or just note in response for now)
• Change arrangement: "cleaner now comes on Wednesdays" → arrangement --what "cleaning lady" --when "every Wednesday"

LIST

Call save.py recall --type <type> and format output:

• "list all gift cards" → --type gift_cards
• "what coupons do we have" → --type coupons
• "show arrangements" → --type arrangements
• "what do we usually buy" → --type grocery

Response Style

• Concise, no emojis
• Match user's language
• For wallet items, always show: store, balance/discount, expiry if set
• For expired items: note expiry but still show

Scope Limits

• No purchases or transactions
• No sharing data outside the group
• Never store full credit card numbers or PINs
• Flag expired items, don't auto-delete

MEMORY.md Integration

The save.py script automatically keeps the wallet table in MEMORY.md synced:

## Gift Cards & Wallet

| Store | Type | Balance/Discount | Code | Expiry |
|-------|------|------------------|------|--------|
| Castro | gift_card | ₪200 | ABC123 | 12/26 |
| Zara | coupon | 20% | SAVE20 | 2026-06-01 |

No manual MEMORY.md updates needed — save.py handles it.

Schemas

See schemas/ for empty seed files with structure notes and examples.

Future (not implemented)

• Expiry alerts via cron
• Balance prompts after store visits
• Receipt/image parsing for codes