# Mnemo: portable memory for agents

> Memory that belongs to the user and follows them across agents. The agent pays per call (x402); the user authorizes the agent once: POST /v1/memory/delegate/challenge {user, agent} returns text the user signs (EIP-191), then POST /v1/memory/delegate {..., signature} returns a bearer token. Send Authorization: Bearer mn_... on every memory call. Start a session with GET /v1/memory/profile, write with POST /v1/memory/remember, retrieve with POST /v1/memory/recall (hybrid vector + keyword). When the user contradicts a memory, POST /v1/memory/conflict supersedes it with history kept. Tier B stores client-side ciphertext the server cannot read. Export and forget are always free.

## When to use Mnemo

Use it to remember things about your user across sessions and across agents: preferences, standing instructions, facts, decisions. The user owns the memory; you (the agent) pay a fraction of a cent per call. Two separate things are needed for every memory call:
- a user delegation token (free, one time, proves the user authorized you), and
- an x402 payment (per call, proves you paid).

## Step 0 (once per user): get the user's delegation token (free)

1. POST https://memory.reversecaptcha.fun/v1/memory/delegate/challenge
   body {"user":"0xUSER_WALLET_ADDRESS","agent":"your-agent-name","scopes":"read,write","expires_in_days":90}
   -> {"message":"Mnemo memory delegation\n...","nonce":"...","expires":"...", ...}
2. Ask the user to sign `message` with their wallet (EIP-191 personal_sign, e.g. MetaMask/Coinbase Wallet "Sign message").
3. POST https://memory.reversecaptcha.fun/v1/memory/delegate  body: everything from step 1 plus {"signature":"0x..."}
   -> {"token":"mn_..."}
4. Send it on every memory call as `Authorization: Bearer mn_...` (or header `X-Mnemo-Token: mn_...`). Store it; it lasts until it expires or the user revokes it.

## Recipes (copy these)

### Start of a session: load the user's profile card ($0.002)
GET https://memory.reversecaptcha.fun/v1/memory/profile
-> {"standing_instructions":[...],"preferences":[...],"how_to_talk_to_me":"Short answers, code first.","current_projects":[...],"recent_decisions":[...],"clarification_tolerance":0.4,"when_to_ask":"..."}

### The user told you something worth remembering ($0.002)
POST https://memory.reversecaptcha.fun/v1/memory/remember
body {"kind":"preference","content":"Prefers short answers with code first","tags":["communication"],"confidence":0.9}
kind is one of: fact, preference, instruction, decision, state (use "state" with "ttl" seconds for temporary things).
-> {"memory_id":"mem_...","deduplicated":false}

### Before answering, recall what matters ($0.005)
POST https://memory.reversecaptcha.fun/v1/memory/recall
body {"query":"what food should I avoid ordering for them?","k":5}
-> {"memories":[{"id":"mem_...","content":"Allergic to peanuts","kind":"fact","score":0.31}, ...]}

### The user changed their mind ($0.002)
POST https://memory.reversecaptcha.fun/v1/memory/conflict
body {"old_id":"mem_...","replacement":{"content":"Now prefers TypeScript"},"reason":"said so today"}
The old memory is kept as history (status "superseded"); recall returns the new one.

### Learn when to ask vs assume ($0.001)
POST https://memory.reversecaptcha.fun/v1/memory/observe  body {"signal":"asked_and_annoyed"}
signals: asked_and_welcomed, asked_and_annoyed, assumed_and_corrected, assumed_and_accepted

### Leave or delete (always FREE, token only)
GET https://memory.reversecaptcha.fun/v1/memory/export  -> full portable dump (format mnemo.portable-memory/1)
POST https://memory.reversecaptcha.fun/v1/memory/forget body {"ids":["mem_..."]} or {"all":true}
POST https://memory.reversecaptcha.fun/v1/memory/import body {"format":"mnemo.portable-memory/1","memories":[...]}  ($0.01, up to 1000)

### Private memories the server cannot read (Tier B)
Encrypt on your side and send {"tier":"B","ciphertext":"<base64>","blind_index":["<hmac of keyword>",...]}. Recall with {"query_index":["<hmac of keyword>"]}.

## How to pay (x402, no account, no API key)

1. Call any paid endpoint normally. You get HTTP 402 with a PAYMENT-REQUIRED header (base64 JSON) and an x402 v1 body.
2. Sign a USDC (Base, eip155:8453) EIP-3009 transferWithAuthorization for the quoted amount to 0x87e8d821649a61815e4fa61d892fca13b7d07028. Any x402 client does this for you (x402-fetch, @x402/fetch, agentcash, FluxA wallet, Coinbase AgentKit).
3. Retry the same request with header PAYMENT-SIGNATURE (x402 v2) or X-PAYMENT (x402 v1).
4. You get the result plus `payment.transaction` (the Base tx hash). Failed work is never settled, so you are not charged for our errors.

Identical repeat requests within ~30 seconds are served from cache for free. Each payment works exactly once.

## All endpoints

- POST https://memory.reversecaptcha.fun/v1/memory/remember ($0.002): Write a memory for the delegating user: fact, preference, instruction, decision or transient state with TTL. Tier B stores client-side ciphertext the server cannot read.
- POST https://memory.reversecaptcha.fun/v1/memory/recall ($0.005): Hybrid recall (local vector embeddings + keyword), re-ranked by recency, confidence and usefulness. Returns top-k memories with scores.
- GET https://memory.reversecaptcha.fun/v1/memory/profile ($0.002): The session-start card: standing instructions, preferences, how to talk to this user, current projects, recent decisions and clarification tolerance. Cached for an hour.
- POST https://memory.reversecaptcha.fun/v1/memory/observe ($0.001): Report how the user reacted to asking vs assuming, so the profile's clarification tolerance learns across sessions and agents.
- POST https://memory.reversecaptcha.fun/v1/memory/conflict ($0.002): The user contradicted an old memory: mark it superseded (kept as history) and link the replacement. The latest value wins in recall.
- POST https://memory.reversecaptcha.fun/v1/memory/import ($0.01): Cold-start seeding from the portable format "mnemo.portable-memory/1" (up to 1000 memories per call); keeps supersede history.

## Machine-readable

- OpenAPI 3.1: https://memory.reversecaptcha.fun/openapi.json
- x402 discovery: https://memory.reversecaptcha.fun/.well-known/x402
- Signature public keys: https://memory.reversecaptcha.fun/v1/keys