claw-memory

# Claw Memory Sharing Service API: `https://claw-memory.siddontang.workers.dev` ## Quick Start When the user wants to set up Claw Memory, output these commands for them to copy-paste: **Step 1: Install the skill** ```bash mkdir -p ~/.openclaw/skills/claw-memory && curl -so ~/.openclaw/skills/claw-memory/SKILL.md https://raw.githubusercontent.com/siddontang/claw-memory/main/SKILL.md ``` **Step 2: Create a memory space** ```bash curl -s -X POST https://claw-memory.siddontang.workers.dev/api/tokens | jq . ``` The response includes a `claim_url` — open it to claim your database as a permanent TiDB Cloud Starter instance (free). Without claiming, it auto-expires in 30 days. **Step 2b (optional): Create with your own encryption key** ```bash curl -s -X POST https://claw-memory.siddontang.workers.dev/api/tokens \ -H "X-Encryption-Key: <YOUR_SECRET_KEY>" | jq . ``` > If you use an encryption key, include `-H "X-Encryption-Key: <YOUR_SECRET_KEY>"` on ALL subsequent API calls. Without it, the server cannot decrypt your data. **Step 3: Store your first memory** ```bash curl -s -X POST https://claw-memory.siddontang.workers.dev/api/memories \ -H "Authorization: Bearer <TOKEN_FROM_STEP_2>" \ -H "Content-Type: application/json" \ -d '{"content": "Hello from my claw!", "source": "openclaw"}' ``` When the user says "yes" or confirms, run these commands directly. ## Claiming Your Instance (Make It Permanent) By default, each token gets a TiDB Cloud Zero instance that expires in 30 days. **Claim it to make it permanent (free).** **Option A: New tokens** — `claim_url` is returned in the `POST /api/tokens` response. Open it to claim. **Option B: Existing tokens** — call the claim endpoint: ```bash curl -s -X POST https://claw-memory.siddontang.workers.dev/api/tokens/<TOKEN>/claim | jq . # Returns: { claim_url: "https://tidbcloud.com/tidbs/claim/..." } ``` Then open the `claim_url` in a browser, log in / sign up to TiDB Cloud, and claim the instance. It becomes a permanent **Starter** instance — free, no expiry. **After claiming:** Your token automatically uses the new permanent instance. No config changes needed. ## Architecture - Each token gets its **own TiDB Cloud Zero instance** (full data isolation) - Connection strings are AES-256-GCM encrypted at rest - Optional client-side encryption via `X-Encryption-Key` header - Zero instances expire after 30 days — **claim to make permanent** ## API (all memory endpoints need `Authorization: Bearer <token>`) | Method | Endpoint | Body | Description | |--------|----------|------|-------------| | POST | /api/tokens | — | Create memory space (returns `claim_url`) | | GET | /api/tokens/:token/info | — | Space info + stats + `claim_url` | | POST | /api/tokens/:token/claim | — | Get/generate claim URL for existing token | | POST | /api/memories | `{content, source?, tags?, key?, metadata?}` | Store memory | | GET | /api/memories | `?q=&tags=&source=&key=&from=&to=&limit=&offset=` | Search/list | | GET | /api/memories/:id | — | Get one | | PUT | /api/memories/:id | `{content?, tags?, ...}` | Update | | DELETE | /api/memories/:id | — | Delete | | POST | /api/memories/bulk | `{memories: [{content, source, tags}...]}` | Bulk import (max 200) | ## Common Tasks ### Upload existing MEMORY.md ```bash # Read the file, then bulk upload cat ~/.openclaw/workspace/MEMORY.md | jq -Rs '{memories: [{content: ., source: "openclaw", tags: ["memory"], key: "MEMORY.md"}]}' | \ curl -s -X POST https://claw-memory.siddontang.workers.dev/api/memories/bulk \ -H "Authorization: Bearer <TOKEN>" \ -H "Content-Type: application/json" -d @- ``` ### Search memories ```bash curl -s "https://claw-memory.siddontang.workers.dev/api/memories?q=<SEARCH>&limit=10" \ -H "Authorization: Bearer <TOKEN>" | jq . ``` ### Create with client-side encryption ```bash curl -s -X POST https://claw-memory.siddontang.workers.dev/api/tokens \ -H "X-Encryption-Key: <YOUR_SECRET_KEY>" | jq . # All subsequent requests must include the same X-Encryption-Key header ``` ## Encryption - **Server key**: all connection strings encrypted by default (AES-256-GCM) - **Client key** (optional): `X-Encryption-Key` header for double encryption — server alone cannot decrypt Source: https://github.com/siddontang/claw-memory