Pocketclaw

SKILL.md

---
name: pocketclaw
description: Household memory vault for group chat agents. Tracks gift cards, coupons, store credit, grocery habits, and standing arrangements. Use when someone mentions a gift card, coupon, store credit, shopping, groceries, recurring purchases, cleaning lady, babysitter, or any household arrangement. Triggers on phrases like "I have a gift card", "save this coupon", "we usually buy", "the cleaner comes on", "do we have any coupons for", "what's the Castro card balance", "add store credit".
---

# 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

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

### Commands

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

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

**Store credit:**
```bash
python3 {skill_dir}/scripts/save.py store_credit --workspace {workspace} \
  --store "H&M" --balance 50 --currency ILS
```

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

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

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

**Update balance (after use):**
```bash
python3 {skill_dir}/scripts/save.py update_balance --workspace {workspace} \
  --store Castro --type gift_card --new-balance 150
```

**Recall (returns JSON):**
```bash
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:

```markdown
## 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