mnemospark 1.5.1 → 2026.4.6

package/README.md

@@ -31,23 +31,17 @@ openclaw gateway start
 > Plugin registration is done by `openclaw plugins install mnemospark`.
 > The install also bundles the `skills/mnemospark` skill package so the main agent can delegate mnemospark workflows.
 
-### 2) (Optional) Initialize wallet helpers
+By default the plugin uses the production mnemospark API at **https://api.mnemospark.ai**. Set **`MNEMOSPARK_BACKEND_API_BASE_URL`** only when you need a different endpoint (for example staging or a private API URL).
 
-```bash
-npx mnemospark install --standard
-```
-
-This creates/reuses local wallet helper files under `~/.openclaw/mnemospark/`.
-
-### 3) Restart gateway after updates
+### 2) Restart gateway after updates
 
 ```bash
 openclaw gateway restart
 ```
 
-### 4) Use slash commands in OpenClaw chat
+### 3) Use slash commands in OpenClaw chat
 
-- `/mnemospark wallet` → wallet status; `/mnemospark wallet help` → commands
+- `/mnemospark wallet` → wallet status; `/mnemospark wallet help` → commands; `/mnemospark wallet create` → new key (backs up existing default `wallet.key` if present)
 - `/mnemospark cloud help` → storage command guide
 
 ---
@@ -85,6 +79,7 @@ Have ChatGPT or your favorite LLM evaluate the mnemospark codebase. Here's a [st
 
 - `/mnemospark wallet` — address, balance, and key file path
 - `/mnemospark wallet help` — command list and funding link
+- `/mnemospark wallet create` — create a new wallet (and backup an existing default key file)
 - `/mnemospark wallet export` — export private key for backup (sensitive)
 
 ---
@@ -155,20 +150,20 @@ The blockchain transaction is the payment record.
 
 Optional unless noted. All names use the `MNEMOSPARK_` prefix.
 
-| Variable                             | Purpose                                                                                                                                                                                                                                   |
-| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `MNEMOSPARK_BACKEND_API_BASE_URL`    | Base URL for the mnemospark backend API (required for the local HTTP proxy to forward storage calls). Example: `https://{api-id}.execute-api.{region}.amazonaws.com/{stage}`.                                                             |
-| `MNEMOSPARK_PROXY_PORT`              | TCP port for the mnemospark HTTP proxy (default `7120`).                                                                                                                                                                                  |
-| `MNEMOSPARK_DOWNLOAD_DIR`            | Directory where the proxy writes downloaded objects (default `~/.openclaw/mnemospark/downloads/`).                                                                                                                                        |
-| `MNEMOSPARK_WALLET_KEY`              | Path to the wallet private key file when not using the default `~/.openclaw/mnemospark/wallet/wallet.key`.                                                                                                                                |
-| `MNEMOSPARK_REMOVE_BACKUP_FILE`      | After a **successful** cloud upload, delete the local backup archive under `~/.openclaw/mnemospark/backup/`. **Default when unset:** remove the file. Set to `0`, `false`, `no`, or `n` to keep it; `1`, `true`, `yes`, or `y` to remove. |
-| `MNEMOSPARK_DISABLED`                | Set to `true` or `1` to disable plugin registration.                                                                                                                                                                                      |
-| `MNEMOSPARK_DISABLE_SQLITE`          | Set to `1` to disable local SQLite (`state.db`); cloud commands that need local state will fail.                                                                                                                                          |
-| `MNEMOSPARK_SQLITE_STRICT`           | Set to `1` so certain SQLite consistency checks (e.g. friendly-name verification after upload) throw instead of warning.                                                                                                                  |
-| `MNEMOSPARK_PROXY_VERBOSE_404`       | When `1`, `true`, or `yes`, the local HTTP proxy includes a `message` field on **404** responses describing supported paths. Default (unset) is a generic JSON body `{ "error": "Not found" }` only (reduces reconnaissance).             |
-| `MNEMOSPARK_CRON_AGENT_ID`           | OpenClaw agent id used for the monthly renewal cron (default `mnemospark-renewal`).                                                                                                                                                       |
-| `MNEMOSPARK_CRON_NODE_BIN`           | Absolute path to `node` for renewal cron exec (default `/usr/bin/node`).                                                                                                                                                                  |
-| `MNEMOSPARK_DISABLE_OPENCLAW_PREREQ` | Set to `1` to skip automatic runbook application everywhere it runs (plugin load, CLI install/update; for advanced debugging only).                                                                                                       |
+| Variable                             | Purpose                                                                                                                                                                                                                                          |
+| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `MNEMOSPARK_BACKEND_API_BASE_URL`    | Base URL for the mnemospark backend API (required for the local HTTP proxy to forward storage calls). **Default:** `https://api.mnemospark.ai` (production). Set this variable only to override—for example staging or a custom API Gateway URL. |
+| `MNEMOSPARK_PROXY_PORT`              | TCP port for the mnemospark HTTP proxy (default `7120`).                                                                                                                                                                                         |
+| `MNEMOSPARK_DOWNLOAD_DIR`            | Directory where the proxy writes downloaded objects (default `~/.openclaw/mnemospark/downloads/`).                                                                                                                                               |
+| `MNEMOSPARK_WALLET_KEY`              | Path to the wallet private key file when not using the default `~/.openclaw/mnemospark/wallet/wallet.key`.                                                                                                                                       |
+| `MNEMOSPARK_REMOVE_BACKUP_FILE`      | After a **successful** cloud upload, delete the local backup archive under `~/.openclaw/mnemospark/backup/`. **Default when unset:** remove the file. Set to `0`, `false`, `no`, or `n` to keep it; `1`, `true`, `yes`, or `y` to remove.        |
+| `MNEMOSPARK_DISABLED`                | Set to `true` or `1` to disable plugin registration.                                                                                                                                                                                             |
+| `MNEMOSPARK_DISABLE_SQLITE`          | Set to `1` to disable local SQLite (`state.db`); cloud commands that need local state will fail.                                                                                                                                                 |
+| `MNEMOSPARK_SQLITE_STRICT`           | Set to `1` so certain SQLite consistency checks (e.g. friendly-name verification after upload) throw instead of warning.                                                                                                                         |
+| `MNEMOSPARK_PROXY_VERBOSE_404`       | When `1`, `true`, or `yes`, the local HTTP proxy includes a `message` field on **404** responses describing supported paths. Default (unset) is a generic JSON body `{ "error": "Not found" }` only (reduces reconnaissance).                    |
+| `MNEMOSPARK_CRON_AGENT_ID`           | OpenClaw agent id used for the monthly renewal cron (default `mnemospark-renewal`).                                                                                                                                                              |
+| `MNEMOSPARK_CRON_NODE_BIN`           | Absolute path to `node` for renewal cron exec (default `/usr/bin/node`).                                                                                                                                                                         |
+| `MNEMOSPARK_DISABLE_OPENCLAW_PREREQ` | Set to `1` to skip automatic runbook application everywhere it runs (plugin load, CLI install/update; for advanced debugging only).                                                                                                              |
 
 ---
 

package/dist/cli.js

@@ -146,6 +146,7 @@ var BalanceMonitor = class {
 
 // src/config.ts
 var DEFAULT_PORT = 7120;
+var DEFAULT_BACKEND_API_BASE_URL = "https://api.mnemospark.ai";
 var PROXY_PORT = (() => {
   const envPort = process.env.MNEMOSPARK_PROXY_PORT;
   if (envPort) {
@@ -156,7 +157,7 @@ var PROXY_PORT = (() => {
   }
   return DEFAULT_PORT;
 })();
-var MNEMOSPARK_BACKEND_API_BASE_URL = (process.env.MNEMOSPARK_BACKEND_API_BASE_URL ?? "").trim();
+var MNEMOSPARK_BACKEND_API_BASE_URL = (process.env.MNEMOSPARK_BACKEND_API_BASE_URL || DEFAULT_BACKEND_API_BASE_URL).trim();
 var MNEMOSPARK_PROXY_VERBOSE_404 = (() => {
   const v = process.env.MNEMOSPARK_PROXY_VERBOSE_404?.trim().toLowerCase();
   return v === "1" || v === "true" || v === "yes";
@@ -2912,7 +2913,8 @@ async function startProxy(options) {
 }
 
 // src/auth.ts
-import { writeFile as writeFile2, readFile as readFile2, mkdir as mkdir3 } from "fs/promises";
+import { existsSync, readFileSync } from "fs";
+import { copyFile, writeFile as writeFile2, readFile as readFile2, mkdir as mkdir3 } from "fs/promises";
 import { join as join5 } from "path";
 import { homedir as homedir4 } from "os";
 import { generatePrivateKey, privateKeyToAccount as privateKeyToAccount4 } from "viem/accounts";
@@ -2927,6 +2929,32 @@ var LEGACY_WALLET_DIR = join5(homedir4(), ".openclaw", "blockrun");
 var LEGACY_WALLET_FILE = join5(LEGACY_WALLET_DIR, "wallet.key");
 var WALLET_DIR = join5(homedir4(), ".openclaw", "mnemospark", "wallet");
 var WALLET_FILE = join5(WALLET_DIR, "wallet.key");
+function resolveWalletKeyForSlashCommandsSync() {
+  const envKey = process.env.MNEMOSPARK_WALLET_KEY?.trim();
+  if (isValidWalletPrivateKey(envKey)) {
+    const account = privateKeyToAccount4(envKey);
+    return {
+      walletKey: envKey,
+      address: account.address,
+      keyPathLabel: "MNEMOSPARK_WALLET_KEY (environment variable)"
+    };
+  }
+  for (const path of [WALLET_FILE, LEGACY_WALLET_FILE]) {
+    try {
+      if (!existsSync(path)) {
+        continue;
+      }
+      const raw = readFileSync(path, "utf-8").trim();
+      if (!isValidWalletPrivateKey(raw)) {
+        continue;
+      }
+      const account = privateKeyToAccount4(raw);
+      return { walletKey: raw, address: account.address, keyPathLabel: path };
+    } catch {
+    }
+  }
+  return null;
+}
 async function loadSavedWallet() {
   for (const path of [WALLET_FILE, LEGACY_WALLET_FILE]) {
     try {
@@ -2964,6 +2992,33 @@ async function generateAndSaveWallet() {
   }
   return { key, address: account.address };
 }
+function pickUniqueWalletKeyBackupPath(walletKeyPath) {
+  const d = /* @__PURE__ */ new Date();
+  const y = d.getFullYear();
+  const m = String(d.getMonth() + 1).padStart(2, "0");
+  const day = String(d.getDate()).padStart(2, "0");
+  const base2 = `${walletKeyPath}.bak-${y}-${m}-${day}`;
+  if (!existsSync(base2)) {
+    return base2;
+  }
+  let n = 2;
+  for (; ; ) {
+    const candidate = `${base2}-${n}`;
+    if (!existsSync(candidate)) {
+      return candidate;
+    }
+    n += 1;
+  }
+}
+async function createMnemosparkWalletWithOptionalBackup() {
+  let backupPath;
+  if (existsSync(WALLET_FILE)) {
+    backupPath = pickUniqueWalletKeyBackupPath(WALLET_FILE);
+    await copyFile(WALLET_FILE, backupPath);
+  }
+  const { key, address } = await generateAndSaveWallet();
+  return { backupPath, key, address };
+}
 async function resolveOrGenerateWalletKey() {
   const envKey = process.env.MNEMOSPARK_WALLET_KEY?.trim();
   if (isValidWalletPrivateKey(envKey)) {
@@ -2990,10 +3045,6 @@ var pkg = require2(join6(__dirname, "..", "package.json"));
 var VERSION = pkg.version;
 var USER_AGENT = `mnemospark/${VERSION}`;
 
-// src/mnemospark-handler.ts
-import { existsSync, readFileSync } from "fs";
-import { privateKeyToAccount as privateKeyToAccount6 } from "viem/accounts";
-
 // src/cloud-help-onboarding.ts
 var CLOUD_ONBOARDING_BLOCK_LINES = [
   "",
@@ -4147,7 +4198,8 @@ function routeMnemosparkArgs(args) {
       "\u2022 `/mnemospark help` \u2014 overview",
       "\u2022 `/mnemospark cloud help` \u2014 cloud commands",
       "\u2022 `/mnemospark wallet` \u2014 wallet status",
-      "\u2022 `/mnemospark wallet help` \u2014 wallet commands"
+      "\u2022 `/mnemospark wallet help` \u2014 wallet commands",
+      "\u2022 `/mnemospark wallet create` \u2014 new wallet (backs up existing default key)"
     ].join("\n")
   };
 }
@@ -7607,6 +7659,7 @@ var MNEMOSPARK_ROOT_HELP_TEXT = [
   "**Wallet status and funding link:**",
   "\u2022 `/mnemospark wallet`",
   "\u2022 `/mnemospark wallet help`",
+  "\u2022 `/mnemospark wallet create`",
   "",
   "**Let your agent run mnemospark for you:**",
   "",
@@ -7620,6 +7673,7 @@ var MNEMOSPARK_WALLET_HELP_TEXT = (address) => [
   "**Commands:**",
   "\u2022 `/mnemospark wallet` \u2014 Show address, balance, and key file path",
   "\u2022 `/mnemospark wallet help` \u2014 This message",
+  "\u2022 `/mnemospark wallet create` \u2014 Create a new wallet (and backup an existing wallet)",
   "\u2022 `/mnemospark wallet export` \u2014 Export private key for backup (sensitive)",
   "",
   `**Fund with USDC on Base:** https://basescan.org/address/${address}`
@@ -7629,26 +7683,7 @@ function getDefaultCloudCommandHandler() {
   defaultCloudCommandHandler ??= createCloudCommand().handler;
   return defaultCloudCommandHandler;
 }
-var NO_WALLET_FOUND_TEXT = "No mnemospark wallet found. Run `openclaw plugins install mnemospark`.";
-function resolveWalletFileSync() {
-  try {
-    if (!existsSync(WALLET_FILE)) {
-      return null;
-    }
-    const walletKey = readFileSync(WALLET_FILE, "utf-8").trim();
-    if (!walletKey.startsWith("0x") || walletKey.length !== 66) {
-      return null;
-    }
-    const account = privateKeyToAccount6(walletKey);
-    const address = account.address.replace(/\s/g, "");
-    if (!address) {
-      return null;
-    }
-    return { walletKey, address };
-  } catch {
-    return null;
-  }
-}
+var NO_WALLET_FOUND_TEXT = "No mnemospark wallet found. Run `openclaw plugins install mnemospark` or set MNEMOSPARK_WALLET_KEY.";
 async function runMnemosparkSlashHandler(ctx, options) {
   const route = routeMnemosparkArgs(ctx.args);
   if (route.kind === "root-help") {
@@ -7694,6 +7729,15 @@ async function handleWalletSlash(rest) {
     }
     return buildWalletExportResponse();
   }
+  if (parsed.name === "create") {
+    if (afterFirst.trim()) {
+      return {
+        text: "Unexpected extra arguments after `create`. Use `/mnemospark wallet create` alone.",
+        isError: true
+      };
+    }
+    return buildWalletCreateResponse();
+  }
   if (parsed.name === "status") {
     return buildWalletStatusResponse();
   }
@@ -7702,15 +7746,15 @@ async function handleWalletSlash(rest) {
     isError: true
   };
 }
-async function buildWalletStatusResponse() {
-  const wallet = resolveWalletFileSync();
+async function buildWalletStatusResponse(walletOverride) {
+  const wallet = walletOverride ?? resolveWalletKeyForSlashCommandsSync();
   if (!wallet) {
     return {
       text: NO_WALLET_FOUND_TEXT,
       isError: true
     };
   }
-  const { address } = wallet;
+  const { address, keyPathLabel } = wallet;
   let balanceText = "Balance: (checking...)";
   try {
     const monitor = new BalanceMonitor(address);
@@ -7725,19 +7769,47 @@ async function buildWalletStatusResponse() {
       "",
       `**Address:** \`${address}\``,
       `**${balanceText}**`,
-      `**Key File:** \`${WALLET_FILE}\``,
+      `**Key File:** \`${keyPathLabel}\``,
       "",
       "**Commands:**",
       "\u2022 `/mnemospark wallet` \u2014 Show this status",
       "\u2022 `/mnemospark wallet help` \u2014 Commands and funding link",
+      "\u2022 `/mnemospark wallet create` \u2014 Create a new wallet (and backup an existing wallet)",
       "\u2022 `/mnemospark wallet export` \u2014 Export private key for backup",
       "",
       `**Fund with USDC on Base:** https://basescan.org/address/${address}`
     ].join("\n")
   };
 }
+async function buildWalletCreateResponse() {
+  let backupPath;
+  let createdAddress = "";
+  try {
+    ({ backupPath, address: createdAddress } = await createMnemosparkWalletWithOptionalBackup());
+  } catch (err) {
+    return {
+      text: `Failed to create wallet: ${err instanceof Error ? err.message : String(err)}`,
+      isError: true
+    };
+  }
+  const statusResponse = await buildWalletStatusResponse({
+    address: createdAddress,
+    keyPathLabel: WALLET_FILE
+  });
+  if (statusResponse.isError) {
+    return statusResponse;
+  }
+  const createMessageLines = backupPath ? [
+    "\u2705 Existing wallet key was backed up before creating the new wallet.",
+    `**Backup File:** \`${backupPath}\``
+  ] : ["\u2705 New wallet created."];
+  return {
+    ...statusResponse,
+    text: [...createMessageLines, "", statusResponse.text ?? ""].join("\n")
+  };
+}
 async function buildWalletHelpResponse() {
-  const wallet = resolveWalletFileSync();
+  const wallet = resolveWalletKeyForSlashCommandsSync();
   if (!wallet) {
     return {
       text: NO_WALLET_FOUND_TEXT,
@@ -7748,7 +7820,7 @@ async function buildWalletHelpResponse() {
   return { text: MNEMOSPARK_WALLET_HELP_TEXT(address) };
 }
 async function buildWalletExportResponse() {
-  const wallet = resolveWalletFileSync();
+  const wallet = resolveWalletKeyForSlashCommandsSync();
   if (!wallet) {
     return {
       text: NO_WALLET_FOUND_TEXT,