@totalreclaw/totalreclaw 1.0.3 → 1.0.5

package/README.md

@@ -46,6 +46,7 @@ TotalReclaw also ships a standalone MCP server for Claude Desktop, Cursor, and o
 | `totalreclaw_forget` | Delete a specific memory (on-chain tombstone) |
 | `totalreclaw_export` | Export all memories as plaintext |
 | `totalreclaw_status` | Check subscription tier and quota |
+| `totalreclaw_generate_recovery_phrase` | Generate a secure 12-word BIP-39 mnemonic (onboarding) |
 
 ## Lifecycle hooks
 
@@ -80,18 +81,36 @@ Your recovery phrase is a 12-word BIP-39 mnemonic -- like a crypto wallet seed.
 | `TOTALRECLAW_SUBGRAPH_MODE` | `true` | Enable on-chain storage |
 | `TOTALRECLAW_EXTRACT_EVERY_TURNS` | `5` | Turns between automatic extractions |
 
-## Comparison
+## How TotalReclaw compares
 
-| Feature | TotalReclaw | Mem0 |
-|---------|-------------|------|
-| Encryption | Client-side (zero-knowledge) | Server-side (server can read) |
-| Data portability | One-click plaintext export | No export |
-| Key management | BIP-39 seed phrase (user-controlled) | Server-managed keys |
-| Search method | Blind-index + encrypted reranking | Plaintext vector search |
-| On-chain storage | Yes (Gnosis Chain subgraph) | No |
-| Cross-device | Same seed = same memories | Tied to account |
+Every AI memory tool stores your data on a server that can read it. TotalReclaw is the only one that encrypts on your device first -- a compromised server reveals nothing.
 
-The fundamental difference: with TotalReclaw, even a compromised server reveals nothing.
+| | TotalReclaw | Mem0 | Zep | Letta | MCP Memory | memU |
+|---|---|---|---|---|---|---|
+| **Server sees plaintext** | Never | Yes | Yes | Yes | N/A (local) | Yes |
+| **Client-side E2EE** | AES-256-GCM | No | No | No | No | No |
+| **Cross-device sync** | Seed phrase | Account | Account | Account | No | Account |
+| **Data export** | One-click plaintext | JSON (7-day link) | No | Via API | Copy file | No |
+| **On-chain storage** | Gnosis Chain | No | No | No | No | No |
+| **Self-hostable** | Yes | Yes | No | Yes | Yes (local) | Yes |
+| **OpenClaw plugin** | Yes | Yes | No | No | No | Yes |
+| **MCP server** | Yes | Yes | No | No | Yes | No |
+| **Knowledge graph** | No | Yes ($249/mo) | Yes | Yes | Simple | No |
+| **Free tier** | 100 writes/mo | 10K memories | 1K credits | 3 agents | Unlimited | Varies |
+
+### Where TotalReclaw wins
+
+- **Zero-knowledge encryption** -- No other memory tool encrypts client-side. Mem0 and Zep offer SOC 2 and HIPAA, but their servers still process your plaintext. TotalReclaw's server only ever sees encrypted blobs.
+- **Seed-phrase portability** -- One 12-word phrase, any device, any agent. No accounts, no passwords, no vendor. Works like a crypto wallet.
+- **On-chain anchoring** -- Memories are stored on Gnosis Chain and indexed by The Graph. No single server controls your data.
+- **True data ownership** -- One-click plaintext export. No 7-day expiry links, no API-only access. Your data, your format.
+
+### Where others win
+
+- **Knowledge graphs** -- Zep's temporal graph tracks how facts evolve over time. Mem0's graph memory ($249/mo) maps entity relationships. TotalReclaw can't build graphs because the server can't read the data -- that's the privacy trade-off.
+- **Ecosystem maturity** -- Mem0 has 49K GitHub stars, $24M in funding, and integrations with every major framework. TotalReclaw is a beta product.
+- **Offline simplicity** -- The official MCP Memory Server and Engram need zero network, zero accounts, zero setup. Good enough for single-device use.
+- **Enterprise compliance** -- Mem0 and Zep offer SOC 2, HIPAA, RBAC, SSO. TotalReclaw doesn't need most of these (zero-knowledge means there's nothing to comply about), but enterprises want the paperwork.
 
 ## Links
 

package/SKILL.md

@@ -208,6 +208,28 @@ Check subscription status and usage quota.
 
 ---
 
+### totalreclaw_generate_recovery_phrase
+
+Generate a cryptographically secure 12-word BIP-39 recovery phrase for new users. **Always use this tool** — never generate mnemonic words yourself.
+
+**Parameters:** None
+
+**Example:**
+```json
+{}
+```
+
+**Returns:**
+```json
+{
+  "mnemonic": "abandon ability able about above absent absorb abstract absurd abuse access accident",
+  "wordCount": 12,
+  "instructions": ["Display this phrase prominently to the user.", "..."]
+}
+```
+
+---
+
 ## Post-Install Setup
 
 After installing TotalReclaw, the agent MUST complete setup automatically. **Do NOT ask the user to set environment variables manually.**
@@ -227,7 +249,7 @@ The master password is a **12-word BIP-39 mnemonic** — like a crypto wallet se
 Ask the user:
 > "Do you have an existing TotalReclaw recovery phrase you'd like to restore, or should I generate a new one?"
 
-- **New user:** Generate a random 12-word BIP-39 mnemonic and set it as `TOTALRECLAW_MASTER_PASSWORD`. Then display it prominently with a warning:
+- **New user:** Call the `totalreclaw_generate_recovery_phrase` tool to generate a cryptographically secure 12-word BIP-39 mnemonic. **NEVER generate mnemonic words yourself** — always use this tool. Then set it as `TOTALRECLAW_MASTER_PASSWORD` and display it prominently with a warning:
   > "⚠️ SAVE YOUR RECOVERY PHRASE — it's the only way to recover your memories if you switch devices: `[phrase]`"
 - **Returning user:** Ask them to provide their existing 12-word phrase, then set it as `TOTALRECLAW_MASTER_PASSWORD`.
 

package/dist/index.js

@@ -9758,6 +9758,12 @@ function createHasher(hashCons, info = {}) {
   Object.assign(hashC, info);
   return Object.freeze(hashC);
 }
+function randomBytes(bytesLength = 32) {
+  const cr = typeof globalThis === "object" ? globalThis.crypto : null;
+  if (typeof cr?.getRandomValues !== "function")
+    throw new Error("crypto.getRandomValues must be defined");
+  return cr.getRandomValues(new Uint8Array(bytesLength));
+}
 var oidNist = (suffix) => ({
   oid: Uint8Array.from([6, 9, 96, 134, 72, 1, 101, 3, 4, 2, suffix])
 });
@@ -11512,6 +11518,7 @@ var utils = {
 };
 
 // node_modules/@scure/bip39/index.js
+var isJapanese = (wordlist2) => wordlist2[0] === "\u3042\u3044\u3053\u304F\u3057\u3093";
 function nfkd(str) {
   if (typeof str !== "string")
     throw new TypeError("invalid mnemonic type: " + typeof str);
@@ -11529,6 +11536,12 @@ function aentropy(ent) {
   if (![16, 20, 24, 28, 32].includes(ent.length))
     throw new Error("invalid entropy length");
 }
+function generateMnemonic(wordlist2, strength = 128) {
+  anumber(strength);
+  if (strength % 32 !== 0 || strength > 256)
+    throw new TypeError("Invalid entropy");
+  return entropyToMnemonic(randomBytes(strength / 8), wordlist2);
+}
 var calcChecksum = (entropy) => {
   const bitsLeft = 8 - entropy.length / 4;
   return new Uint8Array([sha256(entropy)[0] >> bitsLeft << bitsLeft]);
@@ -11548,6 +11561,11 @@ function mnemonicToEntropy(mnemonic, wordlist2) {
   aentropy(entropy);
   return entropy;
 }
+function entropyToMnemonic(entropy, wordlist2) {
+  aentropy(entropy);
+  const words = getCoder(wordlist2).encode(entropy);
+  return words.join(isJapanese(wordlist2) ? "\u3000" : " ");
+}
 function validateMnemonic(mnemonic, wordlist2) {
   try {
     mnemonicToEntropy(mnemonic, wordlist2);
@@ -13629,6 +13647,9 @@ function isBip39Mnemonic(input) {
   if (words.length !== 12 && words.length !== 24) return false;
   return validateMnemonic(input.trim(), wordlist);
 }
+function generateSecureMnemonic() {
+  return generateMnemonic(wordlist, 128);
+}
 function deriveKeysFromMnemonic(mnemonic) {
   const seed = mnemonicToSeedSync(mnemonic.trim());
   const salt = Buffer.from(seed.slice(0, 32));
@@ -30952,7 +30973,7 @@ async function initialize(logger) {
     }
   }
 }
-var SETUP_ERROR_MSG = 'TotalReclaw setup required. Follow the "Post-Install Setup" steps in SKILL.md:\n1. Set TOTALRECLAW_MASTER_PASSWORD \u2014 ask the user if they have an existing recovery phrase or generate a new 12-word BIP-39 mnemonic.\n2. Set TOTALRECLAW_SUBGRAPH_MODE=true\n3. Restart the gateway to apply changes.';
+var SETUP_ERROR_MSG = 'TotalReclaw setup required. Follow the "Post-Install Setup" steps in SKILL.md:\n1. Set TOTALRECLAW_MASTER_PASSWORD \u2014 ask the user if they have an existing recovery phrase, or call totalreclaw_generate_recovery_phrase to generate a secure one.\n2. Set TOTALRECLAW_SUBGRAPH_MODE=true\n3. Restart the gateway to apply changes.';
 async function ensureInitialized(logger) {
   if (!initPromise) {
     initPromise = initialize(logger);
@@ -31688,6 +31709,40 @@ ${lines.join("\n")}`;
       },
       { name: "totalreclaw_status" }
     );
+    api.registerTool(
+      {
+        name: "totalreclaw_generate_recovery_phrase",
+        label: "Generate Recovery Phrase",
+        description: "Generate a cryptographically secure 12-word BIP-39 recovery phrase. Call this during onboarding when the user needs a new recovery phrase. NEVER generate mnemonics yourself \u2014 always use this tool.",
+        parameters: {
+          type: "object",
+          properties: {},
+          additionalProperties: false
+        },
+        execute() {
+          const mnemonic = generateSecureMnemonic();
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify({
+                  mnemonic,
+                  wordCount: 12,
+                  instructions: [
+                    "Display this phrase prominently to the user.",
+                    "Warn them to save it \u2014 it is the ONLY way to recover their memories.",
+                    "Set it as TOTALRECLAW_MASTER_PASSWORD in the OpenClaw config.",
+                    "Set TOTALRECLAW_SUBGRAPH_MODE=true.",
+                    "Restart the gateway to apply changes."
+                  ]
+                })
+              }
+            ]
+          };
+        }
+      },
+      { name: "totalreclaw_generate_recovery_phrase" }
+    );
     api.on(
       "before_agent_start",
       async (event) => {
@@ -31700,7 +31755,7 @@ ${lines.join("\n")}`;
           await ensureInitialized(api.logger);
           if (needsSetup) {
             return {
-              prependContext: '## TotalReclaw Setup Required\n\nTotalReclaw is installed but needs configuration. Follow the "Post-Install Setup" steps in SKILL.md to complete setup.\nAsk the user: "Do you have an existing TotalReclaw recovery phrase, or should I generate a new one?"'
+              prependContext: '## TotalReclaw Setup Required\n\nTotalReclaw is installed but needs configuration. Follow the "Post-Install Setup" steps in SKILL.md to complete setup.\nAsk the user: "Do you have an existing TotalReclaw recovery phrase, or should I generate a new one?"\nIf they want a new one, call the `totalreclaw_generate_recovery_phrase` tool \u2014 NEVER generate mnemonic words yourself.'
             };
           }
           let billingWarning = "";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@totalreclaw/totalreclaw",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "Zero-knowledge encrypted memory vault for AI agents — the password manager for AI memory.",
   "type": "module",
   "license": "MIT",