Memory Companion

SKILL.md

---
name: memory-companion
description: |
  Ultra-low-cost AI memory persistence — give any agent persistent memory across sessions
  for just $0.001/call (~5000 memories per $5). Captures conversation highlights, decisions,
  preferences, and action items without burning your token budget. Uses SkillPay.me billing
  (BNB Chain USDT). Activate when user says "remember this", asks to save context, or when
  the agent detects important information worth preserving between sessions.
---

# Memory Companion ⚡

**Why this skill?** LLM agents forget everything between sessions. Memory Companion fixes that
at mass-market cost — $0.001 per memory write, ~5000 entries on a $5 deposit. No vector DB,
no embeddings server, no infra. Just flat Markdown files + a billing gate.

## How It Works

1. Agent detects memorable content (or user says "remember this")
2. `scripts/memory-gate.sh` calls SkillPay `/billing/charge` ($0.001)
3. If balance OK → append to `memory/YYYY-MM-DD.md` + update index
4. If insufficient → return BNB Chain USDT payment link (first top-up: $5 recommended)

## Setup

Set two env vars (get from https://skillpay.me → dashboard → Integration):

```bash
export SKILLPAY_API_KEY="sk_your_key_here"
export SKILLPAY_SKILL_ID="4bd0320d-5319-4117-baf0-a773b7ab9093"
```

## Usage

### Save a Memory

```bash
# Returns "OK" or a payment URL if balance insufficient
scripts/memory-gate.sh save "Brett prefers direct communication, no fluff"
```

### Save with Category

```bash
scripts/memory-gate.sh save "PayTheFly contract on BSC chain 56" --tag project
scripts/memory-gate.sh save "Meeting with investors Thursday 3pm" --tag calendar
scripts/memory-gate.sh save "Always use trash instead of rm" --tag preference
```

### Search Memories

```bash
# Free — no billing charge for reads
scripts/memory-gate.sh search "PayTheFly"
scripts/memory-gate.sh search "investor"
```

### Check Balance

```bash
scripts/memory-gate.sh balance
```

### List Recent

```bash
scripts/memory-gate.sh recent        # last 10
scripts/memory-gate.sh recent 20     # last 20
```

## When to Auto-Save

Save automatically when you detect:
- User decisions ("let's go with option B")
- Personal preferences ("I like dark mode", "call me Brett")
- Project facts ("deployed to BSC mainnet", "API key rotated")
- Action items ("need to fix the withdrawal bug tomorrow")
- Important dates ("demo on March 15th")
- Corrections ("actually it's chain 56, not 97")

Do NOT save:
- Routine greetings
- Obvious facts the model already knows
- Temporary debugging output
- Duplicate information already saved

## Memory Format

Memories are stored in `memory/YYYY-MM-DD.md`:

```markdown
## 2026-03-03

- [14:32] [preference] Brett prefers Chinese for daily comms, English for docs
- [14:35] [project] PayTheFly contract deployed on BSC chain 56
- [15:01] [decision] Abandoned Polymarket MM strategy, moved funds to Hyperliquid
```

An index file `memory/INDEX.md` tracks all entries for fast grep search.

## Cost Breakdown

| Action | Cost |
|--------|------|
| Save memory | $0.001 |
| Search | Free |
| Check balance | Free |
| First deposit | $5 recommended (5000 saves) |