Household memory vault for group chat agents. Tracks gift cards, coupons, store credit, grocery habits, and standing arrangements. Use when someone mentions...
---
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
don't have the plugin yet? install it then click "run inline in claude" again.