# Wicked Memory

Portable, framework-agnostic long-term memory for AI agents over plain HTTP. Works the same from
LangGraph, CrewAI, AutoGen, PydanticAI, or curl. Every memory is scoped to the wallet that wrote it.

Base URL: https://memory.wickedapi.com. Responses: { "data": ..., "meta": { ..., "timestamp" } }; errors: { "error", "source" }.
Network for paid search: Base mainnet (real USDC). Price per search without a key: 0.001 USDC.

## Fastest start: use a client (it does the signing and payment for you)
  Python:     curl -O https://memory.wickedapi.com/clients/wicked_memory.py     (pip install httpx eth-account; add "x402[httpx,evm]" to pay per search)
  TypeScript: curl -O https://memory.wickedapi.com/clients/wicked-memory.ts      (npm i viem; add @x402/fetch @x402/evm to pay per search)
  Examples:   https://memory.wickedapi.com/cookbook/quickstart.py   https://memory.wickedapi.com/cookbook/quickstart.ts
              https://memory.wickedapi.com/cookbook/agent_tools.py   (remember/recall tools for any tool-calling LLM)
  MCP:        https://mcp.wickedapi.com/mcp   (tools: memory_prepare, memory_store, memory_search, memory_get,
              memory_update, memory_history, memory_delete, memory_deletions)
  Python:  mem = WickedMemorySync(private_key=KEY, api_key=COMMUNITY_KEY); mem.store("fact"); mem.search("question")
  The private key is an Ethereum key used only to sign locally; it is never sent. It IS the agent's identity:
  whoever holds it can read that agent's memories.

## Free community key (try it now)
Send this header on GET /memories/search to search for free (shared across all community users, rate limited to 30 requests/min):
  x-api-key: wm_community_21ac164a3af1b665cee57d9fe7ac9fc6
It does NOT give access to anyone's memories: the wallet signature still decides whose memories you touch. For heavy use, skip the key and pay 0.001 USDC per search via x402 (the clients do it automatically).

## Raw HTTP auth (every /memories* route): wallet signature, one per request
Headers:
  x-wallet-address:   0x... (your wallet)
  x-wallet-timestamp: unix seconds (must be within 5 minutes of server time)
  x-wallet-nonce:     random string, 16-128 chars, single use
  x-wallet-signature: EIP-191 personal_sign over this exact message (newline-separated, no trailing newline):
    Wicked Memory auth
    wallet: <lowercased address>
    method: <UPPERCASE METHOD>
    path: <request path including ?query exactly as sent>
    timestamp: <same as header>
    nonce: <same as header>
    body-sha256: <hex sha256 of the raw request body; of the empty string for GET/DELETE>
Wallets are registered automatically on their first authenticated request.

## Endpoints
POST   /memories                 body {content, tags?: string[], metadata?: object, source?: string}  -> 201 (free, rate-limited per owner)
GET    /memories/search          ?q=...&limit=10&tags=a,b&created_after=ISO&created_before=ISO&as_of=ISO&include_superseded=true
                                 Real embedding similarity (cosine); results carry `score`. Metered: send `x-api-key` (free,
                                 120 req/min) OR pay via x402 (unpaid request -> 402 with PAYMENT-REQUIRED header; retry with payment).
                                 Still needs wallet-signature headers: the wallet decides WHOSE memories are searched.
GET    /memories/{id}            one memory (404 for ids you don't own -- same as nonexistent)
PATCH  /memories/{id}            body {content?, tags?, metadata?, source?} -> supersedes: creates a new version, closes the old
                                 one (valid_until / superseded_by). 409 if {id} is already superseded.
GET    /memories/{id}/history    full version chain, oldest first
DELETE /memories/{id}            ?scope=chain (default, all versions) | version ; ?reason=... ; hard delete, audit row kept
GET    /memory-deletions         your deletion audit log (no content retained)
GET    /health, GET /v1/status   liveness / config status

## Temporal model
Versions carry valid_from / valid_until (null = currently active). Search returns only active versions by default;
as_of=<ISO> searches the state of memory at that instant; include_superseded=true searches all versions.

## Limits
Storage quota per owner (default 5 MB; larger for Wicked Identity-verified wallets), 16 KB per memory, 20 tags, 8 KB metadata,
60 writes/min per owner. Quota and rate limits apply to x402 payers as well.