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

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

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

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

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:

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 instance gets a NEW connection string. You must update it:

# 1. Get your new connection details from TiDB Cloud console (Connect > General)
# 2. Update your token's connection:
curl -s -X POST https://claw-memory.siddontang.workers.dev/api/tokens/<TOKEN>/update-connection \
  -H "Content-Type: application/json" \
  -d '{"host": "<NEW_HOST>", "user": "<NEW_USER>", "password": "<NEW_PASSWORD>"}'
# 3. Verify:
curl -s https://claw-memory.siddontang.workers.dev/api/tokens/<TOKEN>/connection | jq .

⚠️ Important: Copy the new connection string from TiDB Cloud console immediately after claiming. The old Zero instance will expire.

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>)

Common Tasks

Upload existing MEMORY.md

# 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

curl -s "https://claw-memory.siddontang.workers.dev/api/memories?q=<SEARCH>&limit=10" \
  -H "Authorization: Bearer <TOKEN>" | jq .

Create with client-side encryption

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