@totalreclaw/totalreclaw 3.3.12-rc.6 → 3.3.12-rc.7

package/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: totalreclaw
 description: "End-to-end encrypted, decentralized memory for OpenClaw. Set up an account once, then call totalreclaw_remember / totalreclaw_recall (or the tr CLI under hybrid-primary) instead of writing to MEMORY.md / USER.md / local files. Trigger on 'install TotalReclaw', 'set up TotalReclaw', 'restore my recovery phrase', any remember / recall request, AND any user statement that contains a preference / fact / decision / commitment about themselves."
-version: 3.3.12-rc.6
+version: 3.3.12-rc.7
 author: TotalReclaw Team
 license: MIT
 homepage: https://totalreclaw.xyz
@@ -22,299 +22,55 @@ metadata:
       - persistent-context
 ---
 
-# TotalReclaw — OpenClaw
+# TotalReclaw — OpenClaw plugin
 
-> **Agent-executable quickstart**: <https://github.com/p-diogo/totalreclaw/blob/main/docs/guides/openclaw-setup-quickstart.md>
->
-> **Human-readable setup guide**: <https://github.com/p-diogo/totalreclaw/blob/main/docs/guides/openclaw-setup.md>
+End-to-end encrypted memory stored across a decentralized network (not on a single company server). The plugin handles install + account-setup autonomously; this skill tells the agent what to call and when.
 
-## TOP RULE — MEMORY STORAGE (read this before anything else)
+## TOP RULE — MEMORY STORAGE
 
-**When the user states ANYTHING about themselves, their preferences, decisions, plans, identity, work, location, or facts they want retained, you MUST call `totalreclaw_remember` (NOT `write`, NOT `edit`, NOT MEMORY.md/USER.md).** Under hybrid-primary mode (OpenClaw 2026.5.x), if `totalreclaw_remember` is not bound as a tool, fall back to the `tr` CLI: `node "$TR_CLI" remember --json "<fact>"`. Either path lands the fact encrypted, on-chain. Both are valid.
+When the user states ANYTHING about themselves — preferences, decisions, identity, work, location, plans, tools, commitments — call `totalreclaw_remember` (or `tr remember --json "<fact>"` under hybrid-primary). NEVER write user facts to `MEMORY.md`, `USER.md`, or any local file. Those are agent-persona configuration; user memories live encrypted on-chain.
 
-### ABSOLUTE PROHIBITION
+**Trigger immediately, no "should I?":** "I prefer / like / love / hate X", "my favorite is X", "I'm X", "my name is X", "I live / work at X", "I use X", "I decided X", "I'm going to X", "from now on X", "we agreed X", "I'll X by Y", "remind me to X", "remember that X", "save X", "note X". If a message contains MULTIPLE facts, call `totalreclaw_remember` once per fact — never blob.
 
-**NEVER use the `write` or `edit` tools to store user statements in `MEMORY.md`, `USER.md`, `~/.claude/memory/*.md`, `~/.openclaw/memory/*.md`, or any other file.** Those files are for AGENT PERSONA and CODEBASE INSTRUCTIONS — read-only operational config the agent loads at startup. Storing user data there is a SKILL VIOLATION. User memories live encrypted on-chain via TotalReclaw, not in flat files.
+When the user asks about themselves ("what's my X?", "do I X?", "what do you remember?"), call `totalreclaw_recall` FIRST. If 0 results, say so plainly — don't guess from session history.
 
-- ✅ DO call `totalreclaw_remember` (or `tr remember --json` under hybrid-primary).
-- ❌ DO NOT `Write` to `MEMORY.md`.
-- ❌ DO NOT `Edit` `USER.md` to append a user fact.
-- ❌ DO NOT echo "saving this to MEMORY.md…" — that file is not yours to write to.
+Do not describe storage as `"local"`, `"local-only"`, `"stored locally"`, `"on disk"`, `"local memory"`, `"local storage"`, or `"without an account"` — memories are decentralized on-chain (not on any single company server) and an account is required to derive the encryption key.
 
-### Trigger phrases — call `totalreclaw_remember` on detection
+## Phrase safety (HARD)
 
-Do not wait for an explicit "remember this". These are first-class triggers — every one of them MUST result in a `totalreclaw_remember` call (parallel with your normal reply):
+The 12-word recovery phrase MUST NEVER enter chat or the agent's LLM context. The plugin's browser-based pair flow handles phrase generation and import. Never echo it, never ask the user to paste it, never pass it to any tool. If the user pastes one anyway, tell them it's compromised and re-pair for a fresh wallet.
 
-- **Preferences**: "I prefer X", "I like X", "I love X", "I hate X", "my favorite X is Y", "I'd rather X", "X over Y"
-- **Identity**: "I'm a X", "I am X", "my name is X", "I'm based in X", "I live in X", "I work at X", "I work on X", "I have X"
-- **Tools / setup**: "I use X", "I'm running X", "my X is Y", "I've configured X to Y"
-- **Decisions / plans**: "I decided to X", "I'm going to X", "I'm planning X", "we agreed X", "we settled on X", "let's call this X", "from now on X"
-- **Commitments**: "I'll X by Y", "remind me to X", "I need to X by Y", "don't forget X"
-- **Explicit asks**: "remember that X", "save X", "note that X", "store X", "make a note of X"
-- **Possessive assertions**: "my [anything] is [value]" (preference assertion pattern)
-- **Any 1st-person factual claim worth retaining** about identity, work, location, tools, preferences, ongoing projects, contacts, schedule.
+## Install
 
-If a single user message contains MULTIPLE such facts (e.g. "I'm Pedro. I live in Porto. I prefer PostgreSQL over MySQL."), call `totalreclaw_remember` MULTIPLE TIMES — once per atomic fact. Don't blob multiple unrelated facts into a single memory.
-
-### When to call `totalreclaw_recall`
-
-**ALWAYS call `totalreclaw_recall` first when the user asks about themselves, their preferences, or anything from past conversations.** Trigger phrases:
-
-- "what's my X?", "do I X?", "where do I X?", "when did I X?", "have I told you X?"
-- "what do you remember about me?", "what do you know about my X?"
-- "remind me about X", "what did we decide about X?"
-- "do you remember when X?"
-
-Recall first, then answer from the returned facts. If 0 results come back, say so plainly — do not guess from session history.
-
-## CRITICAL: How TotalReclaw actually stores memories
-
-**TotalReclaw is end-to-end encrypted memory stored across a DECENTRALIZED NETWORK — not on a single company server.** Memories are encrypted with keys derived from the user's 12-word recovery phrase, submitted as Account Abstraction UserOps, and persisted on a public blockchain (Base / Gnosis depending on tier). The Graph subgraph indexes them. The TotalReclaw relay only forwards encrypted bundles to the bundler and proxies subgraph reads — it never sees plaintext, can't read memories, and could be replaced by any compatible relay without losing data. No single company controls or can read user memories.
-
-Forbidden vocabulary — these claims are WRONG:
-- "local", "local-only", "stored locally", "on disk", "local memory", "local storage" — wrong direction (implies local-only).
-- "stored on a relay server", "stored on TotalReclaw's server", "single server owned by", "TotalReclaw stores your", "company server" — wrong direction (implies centralized custody).
-- "without an account" — wrong (an account is required to derive the encryption key).
-
-Canonical line: **"Memories are encrypted with a key derived from your recovery phrase, submitted on-chain via Account Abstraction, and stored across a decentralized network. The relay only forwards encrypted bundles — it never sees plaintext. Only you can decrypt them, and only with your recovery phrase."**
-
-## User-facing vocabulary
-
-| Internal term | Say to the user |
-|---|---|
-| pair / pairing / paired account | "set up an account" / "your TotalReclaw account" |
-| relay / relay server | (don't mention; if forced, say "the encrypted-bundle forwarder") |
-| WS / WebSocket / handshake | (don't mention) |
-| trapdoor / blind index / dedup-key | (don't mention) |
-| subgraph / bundler / UserOp / Account Abstraction | (don't mention; if forced, "submitted on-chain to a decentralized network") |
-| credentials.json / mnemonic file | "your recovery phrase" |
-| `tr pair --json` / `setsid -f` / shell exec | (don't mention; just do the work silently) |
-
-The word "pair" is internal jargon — never use it in user-visible prose. Use "set up an account", "your account", "your recovery phrase", "your memories".
-
-## Install / setup top-level rule
-
-**Emit ONLY the user-visible lines listed below. Do not narrate tool calls. Do not describe what you're doing or about to do.** Errors are the only allowed deviation, and only as a single tight line. The expected user-facing transcript for a healthy install is **4–5 short lines TOTAL**.
-
-### ⚡ MANDATORY ACK BEFORE FIRST TOOL CALL
-
-**User-visible line 1 MUST be your FIRST output — emitted BEFORE you run any shell tool, plugin install, or `tr` command.** Install + setup takes 1–2 minutes of silent tool-execution; without an immediate ack the user assumes the request didn't register and may resend or abandon.
-
-The ack is unconditional. Send line 1, THEN start the work.
-
-Forbidden order (silent-then-narrate): ❌ run `openclaw plugins install` → wait 60s → emit line 1.
-Required order (ack-then-work): ✅ emit line 1 → run `openclaw plugins install` silently → emit line 2 when `tr status` returns.
-
-## ⛔ FORBIDDEN ACTIONS
-
-These specific actions break the install / pair flow:
-
-1. **Do NOT restart the gateway.** No `kill -USR1`, no `docker restart`, no `openclaw gateway restart`. The plugin self-patches and signals its own restart needs (SIGUSR1 in-process, automatic). You restarting it kills the in-flight `setsid -f` pair subprocess → 502 on browser respond. If for some specific reason a restart IS required, issue the literal slash command `/totalreclaw-restart` — nothing else. **NEVER prompt the user to manually restart anything**; the plugin handles its own restart.
-
-2. **Do NOT write to `~/.openclaw/openclaw.json`.** The plugin's `patchOpenClawConfig()` already wrote the required keys. Any further write triggers a deferred SIGUSR1 reload that kills pair. No `openclaw config set …`, no `jq …>openclaw.json`, no `sed -i openclaw.json`.
-
-3. **Do NOT save QR PNGs.** `tr pair --json` returns `qr_ascii` — emit that inline in a triple-backticked code block. No `/tmp/totalreclaw-pair-qr.png` (OpenClaw media-policy blocks it: `LocalMediaAccessError`). No PNG decode.
-
-4. **`tr pair --json` MUST run via `setsid -f`** (exact form below). Foreground invocation is killed when your shell-tool exec returns → 502.
-
-5. **Do NOT pass `--allow-dangerous` to any TotalReclaw command.** The plugin is sandboxed by design.
-
-6. **Do NOT manually edit `~/.totalreclaw/credentials.json`.** Round-trip via `tr pair --json` (re-generate) instead.
-
-7. **Do NOT install the legacy from-source path alongside the published plugin.** The two paths overlap and will double-write facts.
-
-## Hybrid-primary architecture (3.3.9-rc.1)
-
-OpenClaw 2026.5.2 has a tool-policy-pipeline bug (issue #223) that strips non-bundled plugin tools before they reach the agent toolset. **3.3.9-rc.1 makes the `tr` CLI the PRIMARY path for all memory operations.** Native tools (`totalreclaw_*`) are kept for back-compat with older OpenClaw versions where they work, but the agent MUST NOT depend on them. Use `tr` from your shell tool for everything.
-
-**The `tr` binary is installed at one of two paths depending on OpenClaw version:**
-- Modern (2026.5.x npm-managed): `~/.openclaw/npm/node_modules/@totalreclaw/totalreclaw/dist/tr-cli.js`
-- Legacy (extensions tree): `~/.openclaw/extensions/totalreclaw/dist/tr-cli.js`
-
-**Resolve the path once at the top of your shell session and reuse:**
-```bash
-TR_CLI="$(ls -d ~/.openclaw/npm/node_modules/@totalreclaw/totalreclaw/dist/tr-cli.js ~/.openclaw/extensions/totalreclaw/dist/tr-cli.js 2>/dev/null | head -1)"
 ```
-Then invoke as `node "$TR_CLI" <cmd> [--json]`.
-
-**Never rely on `totalreclaw_*` tool binding** — it may not be available due to issue #223. If `totalreclaw_remember` IS bound, use it (preferred). If not, use `tr remember --json` from the shell. EITHER way, the user fact MUST land in TotalReclaw — never in `MEMORY.md`/`USER.md`.
-
-## User-visible line set (THIS IS ALL YOU SAY)
-
-Speak only these lines, in order. Substitute the bracketed placeholders with the real values. No prefaces. No suffixes. No narration.
-
-1. (FIRST output, emitted BEFORE any shell tool call — see "MANDATORY ACK" rule above)
-   > Setting up TotalReclaw — this takes about a minute…
-2. (after install + CLI verify — `tr status` works)
-   > ✓ Installed (totalreclaw &lt;version&gt;, hybrid mode)
-3. (account-setup URL + PIN, IMMEDIATELY after `tr pair --json` returns — no consent gate)
-   > Open &lt;url&gt; in your browser. Enter PIN &lt;pin&gt;. Generate or paste a 12-word recovery phrase. Reply `done` once it's sealed.
-4. (done + free-tier confirmation)
-   > ✓ You're set up on the TotalReclaw free tier — 500 memories/month, unlimited reads. https://totalreclaw.xyz/pricing. Ask me to remember anything.
-
-If existing credentials are detected, emit ONLY this line and stop:
-   > ✓ TotalReclaw is already set up.
-
-### Hard silence rules between numbered lines
-
-Do NOT emit transitional / narrative lines between any of the four user-visible lines above. Specifically forbidden:
-
-- ❌ "Now let me verify the install:" → silent. Just run `tr status --json`.
-- ❌ "Now let me check if you already have credentials:" → silent.
-- ❌ "Need to pair. Let me kick that off:" → silent.
-- ❌ "Standing by." → silent.
-- ❌ Any "Let me X" / "Now I'll Y" / "Just give me a second" prelude.
-- ❌ **Skipping line 1 entirely and going straight to shell tool calls.**
-
-## Setup flow (hybrid-primary)
-
-1. **Install plugin first, skill second.** Run via your shell tool, in this exact order:
-   ```
-   openclaw plugins install @totalreclaw/totalreclaw
-   openclaw skills install totalreclaw
-   ```
-   For RC: replace the first command with `openclaw plugins install @totalreclaw/totalreclaw@rc`. Plugin BEFORE skill is deliberate.
-
-   If either shell call fails with `command not found` / ENOENT / "not authorized" (managed-service or shell-restricted environment), tell the user verbatim: *"Your environment doesn't expose the OpenClaw CLI to me. Please install `totalreclaw` from your service's plugins / skills UI, then reply `done`."* Wait for `done` and skip to step 3.
+openclaw plugins install @totalreclaw/totalreclaw@rc
+openclaw skills install totalreclaw
+```
 
-2. **Verify CLI works — emit user-visible line 2 when successful.** Resolve `TR_CLI` and run:
-   ```bash
-   TR_CLI="$(ls -d ~/.openclaw/npm/node_modules/@totalreclaw/totalreclaw/dist/tr-cli.js ~/.openclaw/extensions/totalreclaw/dist/tr-cli.js 2>/dev/null | head -1)"
-   node "$TR_CLI" status --json
-   ```
-   Parse the JSON. When you get `{"version": "...", "hybrid_mode": true, ...}`, emit user-visible line 2.
+Plugin is published on npm + ClawHub (`p-diogo`, GitHub-verified). Stable: drop `@rc`. Under hybrid-primary, the `tr` CLI is the primary path; native `totalreclaw_*` tools are also bound when OpenClaw exposes them — use whichever your runtime binds.
 
-3. **Check for existing credentials (silent unless found).** Run `test -s ~/.totalreclaw/credentials.json`. If it exists, emit *"✓ TotalReclaw is already set up."* and stop.
+## Setup (plugin-driven)
 
-4. **Set up the user's TotalReclaw account IMMEDIATELY — no consent gate.** Use `setsid -f` so the pair process survives gateway SIGUSR1 reloads. The handshake URL+PIN is written to a tmp file the moment the WS opens:
-   ```bash
-   PAIR_OUT="/tmp/tr-pair-out-$(date +%s).json"
-   setsid -f node "$TR_CLI" pair --json > "$PAIR_OUT" 2>&1 < /dev/null
-   sleep 2
-   cat "$PAIR_OUT"
-   ```
-   Parse the JSON `{"url": "...", "pin": "...", "expires_at_ms": ...}` and emit user-visible line 3. This is UNCONDITIONAL — do NOT ask "Would you like to set up an account?". The URL + PIN itself is the consent moment.
+The plugin auto-creates a pair session on first load when no credentials exist, writes `{url, pin, sid, expires_at_ms}` to `~/.totalreclaw/.pair-pending.json`, and injects a `before_agent_start` context block to you. **When you see that block, surface the URL and PIN to the user VERBATIM — read from the injected context; never invent values.** Confirm on pair completion: `✓ TotalReclaw set up.` (If credentials already exist: `✓ TotalReclaw is already set up.`)
 
-5. **Verify and confirm.** After the user says `done`, re-run `test -s ~/.totalreclaw/credentials.json`. If missing, the PIN expired — repeat the pair block and resend line 3 once. If present, emit user-visible line 4 and stop.
+If a restart is needed (rare — plugin self-handles via gateway config-watcher), issue the literal slash command `/totalreclaw-restart`. Never `kill`, `docker restart`, or prompt the user to restart.
 
-## `tr` CLI reference
+## Hybrid-primary CLI
 
-Always use `--json` flag when running from shell for machine-parseable output.
+OpenClaw 2026.5.x may strip non-bundled tool bindings (issue #223). Never rely on `totalreclaw_*` tool binding alone. Fall back via shell:
 
 ```bash
-# Status
-node "$TR_CLI" status --json
-# Returns: {"version":"3.3.12-rc.5","onboarded":false,"next_step":"pair","tool_count":17,"hybrid_mode":true}
-
-# Pair (always via setsid -f)
-PAIR_OUT="/tmp/tr-pair-out-$(date +%s).json"
-setsid -f node "$TR_CLI" pair --json > "$PAIR_OUT" 2>&1 < /dev/null && sleep 2 && cat "$PAIR_OUT"
-# Returns: {"v":1,"sid":"...","url":"https://...","pin":"123456","mode":"generate","expires_at_ms":...,"qr_ascii":"..."}
-
-# Remember a fact (foreground OK — non-blocking single-shot HTTP call)
+TR_CLI="$(ls -d ~/.openclaw/npm/node_modules/@totalreclaw/totalreclaw/dist/tr-cli.js ~/.openclaw/extensions/totalreclaw/dist/tr-cli.js 2>/dev/null | head -1)"
+node "$TR_CLI" status --json     # {"version":"...","hybrid_mode":true,"tool_count":17}
 node "$TR_CLI" remember --json "I work at Graph Foundation"
-# Returns: {"ok":true,"id":"...","claim_count":N}
-
-# Recall memories
-node "$TR_CLI" recall --json "where does the user work" --limit 5
-# Returns: {"results":[{"text":"...","score":0.8},...]}
+node "$TR_CLI" recall --json "where does the user work" --limit 5   # {"results":[{"text":"...","score":0.8}]}
+node "$TR_CLI" pair --json       # {"url":"...","pin":"123456","expires_at_ms":...} — plugin's auto-pair is preferred; only use this for re-pair
 ```
 
-## Tool reference (all 17 plugin tools)
-
-The plugin exposes these tools via OpenClaw's plugin runtime. Under hybrid-primary mode, prefer the `tr` CLI for `pair` / `remember` / `recall` / `status`; the rest below are typically only available as native tools.
-
-| Tool | Use case |
-|---|---|
-| `totalreclaw_pair` | Set up the user's account (browser-side phrase generation/import) |
-| `totalreclaw_remember` | **Store a fact / preference / decision (encrypted, on-chain). PRIMARY tool for user statements.** |
-| `totalreclaw_recall` | Semantic search across the user's memories |
-| `totalreclaw_forget` | Delete a memory by id (tombstone on-chain) |
-| `totalreclaw_pin` | Mark a memory as never-supersedable |
-| `totalreclaw_unpin` | Remove pin status |
-| `totalreclaw_retype` | Change a memory's type (claim/preference/directive/etc.) |
-| `totalreclaw_set_scope` | Change a memory's scope (work / personal / health / family / creative / finance / misc) |
-| `totalreclaw_export` | Export all memories (json / markdown) |
-| `totalreclaw_import_from` | Import from another tool (Mem0, MCP-Memory, ChatGPT, Claude, Gemini) |
-| `totalreclaw_import_batch` | Bulk import with chunking + extraction |
-| `totalreclaw_consolidate` | Merge near-duplicates after a fresh import |
-| `totalreclaw_status` | Check onboarding state, version, billing tier, quota |
-| `totalreclaw_upgrade` | Open the Stripe upgrade flow (free → paid tier) |
-| `totalreclaw_migrate` | Move testnet memories to mainnet (Pro tier) |
-| `totalreclaw_onboarding_start` | (Internal — used by setup flow) |
-| `totalreclaw_report_qa_bug` | (RC only) Surface a QA bug into the agent log |
-
-All tools accept JSON input and return structured JSON.
-
-## Auto-extraction (background, no agent action required)
-
-The plugin runs a trajectory poller every 60 seconds that scans `~/.openclaw/agents/<agent>/sessions/*.trajectory.jsonl` for new conversation turns and runs LLM-driven extraction. Extracted facts go through importance filtering and dedup before landing on-chain.
-
-**Auto-extraction is a SAFETY NET, not a substitute for explicit `totalreclaw_remember` calls.** Explicit calls are higher-fidelity (the agent decides the importance, type, and scope). Auto-extraction catches things the agent missed.
-
-## Phrase safety (HARD — never break)
-
-The 12-word recovery phrase is the master key. Hard rules:
-
-- **NEVER echo, generate, log, or ask the user to paste a recovery phrase in chat.** The browser at the pair URL handles phrase generation and import. The phrase NEVER enters the agent's LLM context.
-- **NEVER include a recovery phrase as input to ANY tool call** — not `totalreclaw_pair` (its only inputs are `mode` + optional config), not `totalreclaw_remember`, not `Bash`, not `Write`, not `Edit`. Anything that surfaces the phrase to the agent's context is a security incident.
-- **NEVER invoke any phrase-touching CLI via your shell tool.** `openclaw totalreclaw onboard` (bare interactive form) and `totalreclaw setup` print phrase material to stdout, which enters LLM context. The ONLY agent-facilitated account-setup paths are: (1) `tr pair --json` (preferred); (2) the `totalreclaw_pair` tool; (3) `openclaw totalreclaw pair generate --url-pin-only` or `openclaw totalreclaw onboard --pair-only` (single-line URL+PIN JSON, zero phrase material — both account-setup payloads are x25519-only, not BIP-39).
-- **NEVER display the recovery phrase back to the user in chat** even if the browser leaks it to you somehow.
-- **If the user pastes a phrase anyway**: tell them the phrase is now compromised, re-run `tr pair --json` for a fresh wallet.
-
-## Browser flow context
-
-After you emit user-visible line 3, the user opens the URL on their phone or desktop browser. They walk through a 3-step wizard:
-
-1. **Step 1 — Enter PIN.** 6 digits matching what you sent.
-2. **Step 2 — Recovery phrase.** Two tabs: **Set up** (generates fresh BIP-39 phrase locally) or **Log in** (paste existing phrase to restore). User checks "I've written this down" and clicks Set up.
-3. **Step 3 — You're all set.** Browser already POSTed the encrypted phrase. Plugin writes `~/.totalreclaw/credentials.json`.
-
-Common user-side issues during pair:
-
-- **"The page won't load"** → confirm URL host. Default for both stable and RC is `api.totalreclaw.xyz`. Staging via `TOTALRECLAW_SERVER_URL=https://api-staging.totalreclaw.xyz`.
-- **"PIN expired"** → re-run pair block, resend line 3.
-- **"Invalid phrase"** during Log in → user pasted a non-BIP-39-valid phrase. Tell them to re-paste or switch to Set up tab.
-- **502 on Set up** → the gateway WS dropped. Pair subprocess is alive (`setsid -f`). Wait 30s; re-run pair if still 502.
-- **"Where do I write down the phrase?"** → paper, password manager, encrypted note. NOT in this chat.
-
-## Forbidden vocabulary in agent prose
-
-Unless the user explicitly asks how the install works, these patterns must not appear:
-
-- "Let me check that…"
-- "Plugin loaded. Let me verify…"
-- "I'll now…"
-- "Quick fix…"
-- "However, I don't see…"
-- "I need to use…"
-- "Should I /totalreclaw-restart" / "Want me to restart" / "Let me check if the tool is bound" / "Do you have a public URL"
-- "Now installing…" / "Got it" / "In parallel…" / "Step 1a/1b/1c"
-- "local" / "local-only" / "stored locally" / "on disk" / "without an account" / "local memory" / "local storage"
-
-## Diagnostics
-
-- `tr` CLI not found → plugin not installed or install still in progress. Wait 5s, retry.
-- `totalreclaw_*` tools not visible → EXPECTED under OpenClaw 2026.5.2 (issue #223). Use `tr` CLI instead.
-- User says done but `credentials.json` missing → PIN expired; re-run `tr pair --json` and resend line 3.
-- `onboarding required` → credentials missing; redo from the account-setup step.
-- `quota exceeded` → `tr status --json`, then offer `totalreclaw_upgrade`.
-- `No LLM available for auto-extraction` → check `~/.openclaw/agents/<agent>/agent/auth-profiles.json`.
-
-## How does TotalReclaw work? (canonical answer for user questions)
-
-When the user asks "how does this work?" / "where are my memories stored?" / "is this safe?" — answer:
-
-> **End-to-end encrypted, decentralized memory.** When you tell me to remember something, I encrypt it locally with a key derived from your 12-word recovery phrase, then submit it on-chain via Account Abstraction (a UserOperation). It lives on a public blockchain (Base Sepolia for free tier, Gnosis mainnet for paid). The Graph subgraph indexes it for fast retrieval. The TotalReclaw relay only forwards encrypted bundles between your client and the chain — it never sees plaintext, can't read your memories, and could be replaced by any compatible relay without losing data. Your recovery phrase is the only thing that can decrypt the memories.
-
-Shorter slices:
-- **"Where are memories stored?"** → "Encrypted, on-chain (Base or Gnosis depending on your tier), indexed by The Graph. Not on any single company's server."
-- **"Is the relay reading my data?"** → "No. The relay only forwards encrypted bundles. Plaintext never leaves your device."
-- **"What if TotalReclaw shuts down?"** → "Your memories survive. They're on a public blockchain. Any compatible relay (or self-hosted relay) can read them with your recovery phrase."
+Pair is UNCONDITIONAL when no credentials — pasting the install URL IS the consent. `tr --help` lists every subcommand.
 
-## Tool surface summary
+## Tools (17 native; same surface via `tr`)
 
-Hybrid-primary: `tr remember` · `tr recall` · `tr pair` · `tr status` (primary path under OpenClaw 2026.5.x).
-Native fallback (when bound): `totalreclaw_pair` · `_remember` · `_recall` · `_forget` · `_pin` · `_unpin` · `_retype` · `_set_scope` · `_export` · `_status` · `_upgrade` · `_migrate` · `_import_from` · `_import_batch` · `_consolidate` · `_onboarding_start` · `_report_qa_bug` (RC only).
+`totalreclaw_remember` · `totalreclaw_recall` · `totalreclaw_forget` · `totalreclaw_pair` · `totalreclaw_pin` · `totalreclaw_unpin` · `totalreclaw_retype` · `totalreclaw_set_scope` · `totalreclaw_export` · `totalreclaw_import_from` · `totalreclaw_import_batch` · `totalreclaw_consolidate` · `totalreclaw_status` · `totalreclaw_upgrade` · `totalreclaw_migrate` · `totalreclaw_onboarding_start` · `totalreclaw_report_qa_bug` (RC only).
 
-**Default behavior summary**: the agent's job is to call `totalreclaw_remember` aggressively on user statements that match the trigger-phrase list, and `totalreclaw_recall` when the user asks about themselves. Local files (`MEMORY.md`, `USER.md`, etc.) are NOT for user memory — they are agent-persona configuration only.
+Full guides: <https://github.com/p-diogo/totalreclaw/blob/main/docs/guides/openclaw-setup.md>