fix: QA-driven fixes for Hermes + OpenClaw integrations

Hermes:
- Guide: ~600MB → ~34MB disk space (e5-small model)
- Setup tool: generate mnemonic when none provided (via eth_account)
- Schema: recovery_phrase now optional
- Bump to 1.2.0 for PyPI republish

OpenClaw:
- Pimlico 429: add exponential backoff retry (1s/2s/4s, max 3)
- Lazy-load @totalreclaw/core WASM (fixes first-boot crash)
- Add INFO-level txHash logging for successful stores
- Guide: note about restart after first install

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: p-diogo

docs/guides/beta-tester-guide.md

@@ -32,7 +32,7 @@ openclaw skills install totalreclaw
 openclaw plugins install ~/.openclaw/workspace/skills/totalreclaw
 ```
 
-Restart the gateway if prompted. You may see a "1 suspicious code pattern" warning -- this is normal (the plugin reads configuration and makes encrypted network calls).
+Restart the gateway if prompted. You may see a "1 suspicious code pattern" warning -- this is normal (the plugin reads configuration and makes encrypted network calls). If the plugin fails to load on the very first install, restart the gateway once more -- npm dependencies may still be installing in the background.
 
 **Step 2: Set up your recovery phrase**
 

docs/guides/hermes-setup.md

@@ -7,7 +7,7 @@ Set up TotalReclaw as the encrypted memory layer for your Hermes Agent. Your mem
 - **Hermes Agent v0.5.0+** (with plugin lifecycle hooks)
 - **Python 3.11+**
 - **C compiler** (gcc/g++) -- needed to build PyStemmer from source
-- ~600 MB disk space for the local embedding model (one-time download)
+- ~34 MB disk space for the local embedding model (one-time download)
 
 > **Docker users:** On slim images (e.g., `python:3.12-slim`), install a C compiler first:
 > ```bash
@@ -57,8 +57,8 @@ The first time you mention anything worth remembering, the agent will:
 
 1. Detect that TotalReclaw is not configured yet
 2. Ask: "Do you have an existing recovery phrase, or should I generate a new one?"
-3. Run `totalreclaw_setup` with your phrase
-4. Register with the relay, download the embedding model, and activate
+3. Run `totalreclaw_setup` — if you don't have a phrase, the tool generates one automatically
+4. Register with the relay, download the embedding model (~34 MB, one-time), and activate
 
 Your recovery phrase and credentials are saved to `~/.totalreclaw/credentials.json` (owner-only permissions). On subsequent restarts, the plugin loads them automatically.
 
@@ -179,9 +179,9 @@ Or set the env var (auto-registers with relay on first use):
 export TOTALRECLAW_RECOVERY_PHRASE="your twelve word phrase here"
 ```
 
-### Embedding model download slow
+### Embedding model download
 
-The first recall/remember downloads ~600 MB. Subsequent calls use the cached model. If download fails, the plugin falls back to keyword-only search (no semantic similarity).
+The first recall/remember downloads ~34 MB (e5-small model). Subsequent calls use the cached model. If download fails, the plugin falls back to keyword-only search (no semantic similarity).
 
 ### Permission denied on model download (Docker)
 

python/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "totalreclaw"
-version = "1.1.0"
+version = "1.2.0"
 description = "End-to-end encrypted memory for AI agents — Python client"
 readme = "README.md"
 license = "MIT"

python/src/totalreclaw/hermes/schemas.py

@@ -81,17 +81,17 @@
 SETUP = {
     "name": "totalreclaw_setup",
     "description": (
-        "Configure TotalReclaw with a recovery phrase. Run this once to set up "
-        "the encrypted memory vault."
+        "Configure TotalReclaw with a recovery phrase. If no phrase is provided, "
+        "a new one is generated automatically. Run this once to set up the "
+        "encrypted memory vault."
     ),
     "parameters": {
         "type": "object",
         "properties": {
             "recovery_phrase": {
                 "type": "string",
-                "description": "BIP-39 recovery phrase (12 or 24 words)",
+                "description": "BIP-39 recovery phrase (12 or 24 words). If omitted, a new phrase is generated.",
             },
         },
-        "required": ["recovery_phrase"],
     },
 }

python/src/totalreclaw/hermes/tools.py

@@ -123,17 +123,31 @@ async def status(args: dict, state: "PluginState", **kwargs) -> str:
 
 
 def setup(args: dict, state: "PluginState", **kwargs) -> str:
-    """Configure TotalReclaw credentials."""
+    """Configure TotalReclaw credentials. Generates a new recovery phrase if none provided."""
     recovery_phrase = args.get("recovery_phrase", "").strip()
+    generated = False
+
     if not recovery_phrase:
-        return json.dumps({"error": "No recovery phrase provided"})
+        # Generate a new BIP-39 mnemonic using eth_account (already a dependency)
+        try:
+            from eth_account import Account
+            Account.enable_unaudited_hdwallet_features()
+            _acct, recovery_phrase = Account.create_with_mnemonic()
+            generated = True
+        except Exception as e:
+            logger.error("Failed to generate recovery phrase: %s", e)
+            return json.dumps({"error": f"Failed to generate recovery phrase: {e}"})
 
     try:
         state.configure(recovery_phrase)
-        return json.dumps({
+        result = {
             "configured": True,
             "wallet_address": state.get_client().wallet_address,
-        })
+        }
+        if generated:
+            result["recovery_phrase"] = recovery_phrase
+            result["generated"] = True
+        return json.dumps(result)
     except Exception as e:
         logger.error("totalreclaw_setup failed: %s", e)
         return json.dumps({"error": str(e)})

python/tests/test_hermes_plugin.py

@@ -170,7 +170,9 @@ def test_status_schema(self):
 
     def test_setup_schema(self):
         assert schemas.SETUP["name"] == "totalreclaw_setup"
-        assert "recovery_phrase" in schemas.SETUP["parameters"]["required"]
+        assert "recovery_phrase" in schemas.SETUP["parameters"]["properties"]
+        # recovery_phrase is optional (generates one if omitted)
+        assert "required" not in schemas.SETUP["parameters"]
 
 
 class TestTools:
@@ -201,13 +203,18 @@ async def test_recall_not_configured(self):
         result = json.loads(await recall({"query": "test"}, state))
         assert "error" in result
 
-    def test_setup_no_phrase(self):
+    def test_setup_no_phrase_generates_one(self):
         from totalreclaw.hermes.tools import setup
         with patch.dict(os.environ, {}, clear=True):
             with patch.object(Path, "exists", return_value=False):
                 state = PluginState()
-        result = json.loads(setup({"recovery_phrase": ""}, state))
-        assert "error" in result
+        with patch.object(Path, "write_text"), patch.object(Path, "chmod"), \
+             patch.object(Path, "mkdir", return_value=None):
+            result = json.loads(setup({"recovery_phrase": ""}, state))
+        assert result["configured"] is True
+        assert result["generated"] is True
+        assert len(result["recovery_phrase"].split()) == 12
+        assert result["wallet_address"].startswith("0x")
 
     def test_setup_success(self):
         from totalreclaw.hermes.tools import setup

skill/plugin/crypto.ts

@@ -15,7 +15,12 @@
  *     -> HKDF-SHA256(seed, salt, "openmemory-dedup-v1",           32) -> dedupKey
  */
 
-import * as wasm from '@totalreclaw/core';
+// Lazy-load WASM to avoid crash when npm install hasn't finished yet.
+let _wasm: typeof import('@totalreclaw/core') | null = null;
+function getWasm() {
+  if (!_wasm) _wasm = require('@totalreclaw/core');
+  return _wasm;
+}
 
 // ---------------------------------------------------------------------------
 // BIP-39 Validation
@@ -58,9 +63,9 @@ export function deriveKeys(
   // Try strict validation first, fall back to lenient
   let result: { auth_key: string; encryption_key: string; dedup_key: string; salt: string };
   try {
-    result = wasm.deriveKeysFromMnemonic(trimmed);
+    result = getWasm().deriveKeysFromMnemonic(trimmed);
   } catch {
-    result = wasm.deriveKeysFromMnemonicLenient(trimmed);
+    result = getWasm().deriveKeysFromMnemonicLenient(trimmed);
   }
 
   return {
@@ -84,7 +89,7 @@ export function deriveLshSeed(
   password: string,
   salt: Buffer,
 ): Uint8Array {
-  const seedHex = wasm.deriveLshSeed(password.trim(), salt.toString('hex'));
+  const seedHex = getWasm().deriveLshSeed(password.trim(), salt.toString('hex'));
   return new Uint8Array(Buffer.from(seedHex, 'hex'));
 }
 
@@ -96,7 +101,7 @@ export function deriveLshSeed(
  * Compute the SHA-256 hash of the auth key.
  */
 export function computeAuthKeyHash(authKey: Buffer): string {
-  return wasm.computeAuthKeyHash(authKey.toString('hex'));
+  return getWasm().computeAuthKeyHash(authKey.toString('hex'));
 }
 
 // ---------------------------------------------------------------------------
@@ -110,14 +115,14 @@ export function computeAuthKeyHash(authKey: Buffer): string {
  *   [iv: 12 bytes][tag: 16 bytes][ciphertext: variable]
  */
 export function encrypt(plaintext: string, encryptionKey: Buffer): string {
-  return wasm.encrypt(plaintext, encryptionKey.toString('hex'));
+  return getWasm().encrypt(plaintext, encryptionKey.toString('hex'));
 }
 
 /**
  * Decrypt a base64-encoded AES-256-GCM blob back to a UTF-8 string.
  */
 export function decrypt(encryptedBase64: string, encryptionKey: Buffer): string {
-  return wasm.decrypt(encryptedBase64, encryptionKey.toString('hex'));
+  return getWasm().decrypt(encryptedBase64, encryptionKey.toString('hex'));
 }
 
 // ---------------------------------------------------------------------------
@@ -131,7 +136,7 @@ export function decrypt(encryptedBase64: string, encryptionKey: Buffer): string
  * and SHA-256 hashing.
  */
 export function generateBlindIndices(text: string): string[] {
-  return wasm.generateBlindIndices(text);
+  return getWasm().generateBlindIndices(text);
 }
 
 // ---------------------------------------------------------------------------
@@ -144,5 +149,5 @@ export function generateBlindIndices(text: string): string[] {
  * @returns 64-character hex string.
  */
 export function generateContentFingerprint(plaintext: string, dedupKey: Buffer): string {
-  return wasm.generateContentFingerprint(plaintext, dedupKey.toString('hex'));
+  return getWasm().generateContentFingerprint(plaintext, dedupKey.toString('hex'));
 }

skill/plugin/index.ts

@@ -1867,6 +1867,7 @@ const plugin = {
               if (!result.success) {
                 throw new Error(`On-chain submission failed (tx=${result.txHash?.slice(0, 10) || 'none'}…)`);
               }
+              api.logger.info(`totalreclaw_remember: stored on-chain (tx=${result.txHash.slice(0, 10)}…)`);
             } else {
               await apiClient!.store(userId!, [factPayload], authKeyHex!);
             }

skill/plugin/lsh.ts

@@ -7,7 +7,12 @@
  * Default parameters: 32 bits per table, 20 tables.
  */
 
-import { WasmLshHasher } from '@totalreclaw/core';
+// Lazy-load WASM to avoid crash when npm install hasn't finished yet.
+let _WasmLshHasher: typeof import('@totalreclaw/core')['WasmLshHasher'] | null = null;
+function getWasmLshHasher() {
+  if (!_WasmLshHasher) _WasmLshHasher = require('@totalreclaw/core').WasmLshHasher;
+  return _WasmLshHasher!;
+}
 
 /**
  * Random Hyperplane LSH hasher.
@@ -16,7 +21,7 @@ import { WasmLshHasher } from '@totalreclaw/core';
  * Construct once per session; call `hash()` for every store/search operation.
  */
 export class LSHHasher {
-  private inner: WasmLshHasher;
+  private inner: InstanceType<typeof import('@totalreclaw/core')['WasmLshHasher']>;
 
   /**
    * Create a new LSH hasher.
@@ -33,7 +38,7 @@ export class LSHHasher {
     nBits: number = 32,
   ) {
     const seedHex = Buffer.from(seed).toString('hex');
-    this.inner = WasmLshHasher.withParams(seedHex, dims, nTables, nBits);
+    this.inner = getWasmLshHasher().withParams(seedHex, dims, nTables, nBits);
   }
 
   /**