@totalreclaw/totalreclaw 1.2.0 → 1.4.0

package/README.md

@@ -79,9 +79,9 @@ Most of the time you won't use these directly -- the automatic hooks handle memo
 | Tier | Memories | Reads | Storage | Price |
 |------|----------|-------|---------|-------|
 | **Free** | 500/month | Unlimited | Testnet (trial) | $0 |
-| **Pro** | Unlimited | Unlimited | Permanent on-chain (Gnosis) | $5/month |
+| **Pro** | Unlimited | Unlimited | Permanent on-chain (Gnosis) | See `totalreclaw_status` |
 
-Pay with card via Stripe. Counter resets monthly.
+Pay with card via Stripe. Use `totalreclaw_status` to check current pricing. Counter resets monthly.
 
 ## Using with Other Agents
 

package/crypto.ts

@@ -89,7 +89,7 @@ function deriveKeysFromMnemonic(
 }
 
 /**
- * Derive auth, encryption, and dedup keys from a master password.
+ * Derive auth, encryption, and dedup keys from a recovery phrase.
  *
  * If the password is a valid BIP-39 mnemonic (12 or 24 words), keys are
  * derived from the 512-bit BIP-39 seed via HKDF. Otherwise, the legacy

package/extractor-dedup.test.ts

@@ -57,7 +57,7 @@ function parseFactsResponse(response: string): ExtractedFact[] {
           : 'ADD';
         return {
           text: String(fact.text).slice(0, 512),
-          type: (['fact', 'preference', 'decision', 'episodic', 'goal'].includes(String(fact.type))
+          type: (['fact', 'preference', 'decision', 'episodic', 'goal', 'context', 'summary'].includes(String(fact.type))
             ? String(fact.type)
             : 'fact') as ExtractedFact['type'],
           importance: Math.max(1, Math.min(10, Number(fact.importance) || 5)),

package/extractor.ts

@@ -15,7 +15,7 @@ export type ExtractionAction = 'ADD' | 'UPDATE' | 'DELETE' | 'NOOP';
 
 export interface ExtractedFact {
   text: string;
-  type: 'fact' | 'preference' | 'decision' | 'episodic' | 'goal';
+  type: 'fact' | 'preference' | 'decision' | 'episodic' | 'goal' | 'context' | 'summary';
   importance: number; // 1-10
   action: ExtractionAction;
   existingFactId?: string;
@@ -37,28 +37,36 @@ interface ConversationMessage {
 // Extraction Prompt
 // ---------------------------------------------------------------------------
 
-const EXTRACTION_SYSTEM_PROMPT = `You are a memory extraction engine. Analyze the conversation and extract atomic facts worth remembering long-term.
+const EXTRACTION_SYSTEM_PROMPT = `You are a memory extraction engine. Analyze the conversation and extract valuable long-term memories.
 
 Rules:
-1. Each fact must be a single, atomic piece of information
-2. Focus on user-specific information: preferences, decisions, facts about them, their goals
-3. Skip generic knowledge, greetings, and small talk
-4. Skip information that is only relevant to the current conversation
-5. Score importance 1-10 (7+ = worth storing, below 7 = skip)
-6. Only extract facts with importance >= 6
+1. Each memory must be a single, self-contained piece of information
+2. Focus on user-specific information that would be useful in future conversations
+3. Skip generic knowledge, greetings, small talk, and ephemeral task coordination
+4. Score importance 1-10 (6+ = worth storing)
+5. Only extract memories with importance >= 6
 
 Types:
-- fact: Objective information about the user
-- preference: Likes, dislikes, or preferences
-- decision: Choices the user has made
-- episodic: Events or experiences
-- goal: Objectives or targets
+- fact: Objective information about the user (name, location, job, relationships)
+- preference: Likes, dislikes, or preferences ("prefers dark mode", "allergic to peanuts")
+- decision: Choices WITH reasoning ("chose PostgreSQL because data is relational and needs ACID")
+- episodic: Notable events or experiences ("deployed v1.0 to production on March 15")
+- goal: Objectives, targets, or plans ("wants to launch public beta by end of Q1")
+- context: Active project/task context ("working on TotalReclaw v1.2, staging on Base Sepolia")
+- summary: Key outcome or conclusion from a discussion ("agreed to use phased rollout for migration")
+
+Extraction guidance:
+- For decisions: ALWAYS include the reasoning. "Chose X" is weak. "Chose X because Y" is strong.
+- For context: Capture what the user is actively working on, including versions, environments, and status.
+- For summaries: Only extract when a conversation reaches a clear conclusion or agreement.
+- For facts: Prefer specific over vague. "Lives in Lisbon" beats "lives in Europe".
+- Decisions and context should be importance >= 7 (they are high-value for future conversations).
 
 Actions (compare against existing memories if provided):
-- ADD: New fact, no conflict with existing memories
-- UPDATE: Modifies or refines an existing memory (provide existingFactId)
-- DELETE: Contradicts an existing memory — the old one is now wrong (provide existingFactId)
-- NOOP: Already captured in existing memories or not worth storing
+- ADD: New memory, no conflict with existing
+- UPDATE: Refines or corrects an existing memory (provide existingFactId)
+- DELETE: Contradicts an existing memory -- the old one is now wrong (provide existingFactId)
+- NOOP: Already captured or not worth storing
 
 Return a JSON array (no markdown, no code fences):
 [{"text": "...", "type": "...", "importance": N, "action": "ADD|UPDATE|DELETE|NOOP", "existingFactId": "..."}, ...]
@@ -158,7 +166,7 @@ function parseFactsResponse(response: string): ExtractedFact[] {
           : 'ADD'; // Default to ADD for backward compatibility
         return {
           text: String(fact.text).slice(0, 512),
-          type: (['fact', 'preference', 'decision', 'episodic', 'goal'].includes(String(fact.type))
+          type: (['fact', 'preference', 'decision', 'episodic', 'goal', 'context', 'summary'].includes(String(fact.type))
             ? String(fact.type)
             : 'fact') as ExtractedFact['type'],
           importance: Math.max(1, Math.min(10, Number(fact.importance) || 5)),

package/generate-mnemonic.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env npx tsx
 /**
- * Generate a BIP-39 12-word mnemonic for use as TOTALRECLAW_MASTER_PASSWORD.
+ * Generate a BIP-39 12-word mnemonic for use as TOTALRECLAW_RECOVERY_PHRASE.
  *
  * Usage: npx tsx generate-mnemonic.ts
  */
@@ -8,7 +8,7 @@ import { generateMnemonic } from '@scure/bip39';
 import { wordlist } from '@scure/bip39/wordlists/english.js';
 
 const mnemonic = generateMnemonic(wordlist, 128);
-console.log('\n  Your TotalReclaw master mnemonic (12 words):\n');
+console.log('\n  Your TotalReclaw recovery phrase (12 words):\n');
 console.log(`  ${mnemonic}\n`);
 console.log('  WRITE THIS DOWN. If you lose it, your memories are unrecoverable.');
-console.log('  Set it as TOTALRECLAW_MASTER_PASSWORD in your .env file.\n');
+console.log('  Set it as TOTALRECLAW_RECOVERY_PHRASE in your .env file.\n');

package/import-adapters/base-adapter.ts

@@ -44,7 +44,7 @@ export abstract class BaseImportAdapter {
     const text = fact.text.trim().slice(0, 512);
 
     // Normalize type
-    const validTypes = ['fact', 'preference', 'decision', 'episodic', 'goal'] as const;
+    const validTypes = ['fact', 'preference', 'decision', 'episodic', 'goal', 'context', 'summary'] as const;
     const type = validTypes.includes(fact.type as typeof validTypes[number])
       ? (fact.type as NormalizedFact['type'])
       : 'fact';

package/import-adapters/import-adapters.test.ts

@@ -453,7 +453,7 @@ async function runTests(): Promise<void> {
 
   // --- type normalization ---
   {
-    const validTypes = ['fact', 'preference', 'decision', 'episodic', 'goal'] as const;
+    const validTypes = ['fact', 'preference', 'decision', 'episodic', 'goal', 'context', 'summary'] as const;
 
     for (const t of validTypes) {
       const result = testAdapter.testValidateFact({ text: 'test fact', type: t });

package/import-adapters/types.ts

@@ -6,7 +6,7 @@ export interface NormalizedFact {
   /** The atomic fact text (max 512 chars) */
   text: string;
   /** Fact type matching TotalReclaw's taxonomy */
-  type: 'fact' | 'preference' | 'decision' | 'episodic' | 'goal';
+  type: 'fact' | 'preference' | 'decision' | 'episodic' | 'goal' | 'context' | 'summary';
   /** Importance score 1-10 */
   importance: number;
   /** Original source system */

package/index.ts

@@ -9,6 +9,7 @@
  *   - totalreclaw_status       -- check billing/subscription status
  *   - totalreclaw_consolidate  -- scan and merge near-duplicate memories
  *   - totalreclaw_import_from  -- import memories from other tools (Mem0, MCP Memory, etc.)
+ *   - totalreclaw_upgrade      -- create Stripe checkout for Pro upgrade
  *
  * Also registers a `before_agent_start` hook that automatically injects
  * relevant memories into the agent's context.
@@ -41,7 +42,7 @@ import {
   STORE_DEDUP_MAX_CANDIDATES,
   type DecryptedCandidate,
 } from './consolidation.js';
-import { isSubgraphMode, getSubgraphConfig, encodeFactProtobuf, submitFactOnChain, deriveSmartAccountAddress, type FactPayload } from './subgraph-store.js';
+import { isSubgraphMode, getSubgraphConfig, encodeFactProtobuf, submitFactOnChain, submitFactBatchOnChain, deriveSmartAccountAddress, type FactPayload } from './subgraph-store.js';
 import { searchSubgraph, getSubgraphFactCount } from './subgraph-search.js';
 import { PluginHotCache, type HotFact } from './hot-cache-wrapper.js';
 import crypto from 'node:crypto';
@@ -134,6 +135,9 @@ const MAX_FACTS_PER_EXTRACTION = 15;
 // Store-time near-duplicate detection (consolidation module)
 const STORE_DEDUP_ENABLED = process.env.TOTALRECLAW_STORE_DEDUP !== 'false';
 
+// One-time welcome-back message for returning Pro users (set during init, consumed by first before_agent_start)
+let welcomeBackMessage: string | null = null;
+
 // B2: Minimum relevance threshold — cosine below this means no memory injection
 const RELEVANCE_THRESHOLD = parseFloat(process.env.TOTALRECLAW_RELEVANCE_THRESHOLD ?? '0.3');
 
@@ -142,7 +146,7 @@ const RELEVANCE_THRESHOLD = parseFloat(process.env.TOTALRECLAW_RELEVANCE_THRESHO
 // ---------------------------------------------------------------------------
 
 const BILLING_CACHE_PATH = path.join(process.env.HOME ?? '/home/node', '.totalreclaw', 'billing-cache.json');
-const BILLING_CACHE_TTL = 12 * 60 * 60 * 1000; // 12 hours
+const BILLING_CACHE_TTL = 2 * 60 * 60 * 1000; // 2 hours
 const QUOTA_WARNING_THRESHOLD = 0.8; // 80%
 
 interface BillingCache {
@@ -153,6 +157,9 @@ interface BillingCache {
     llm_dedup?: boolean;
     custom_extract_interval?: boolean;
     min_extract_interval?: number;
+    extraction_interval?: number;
+    max_facts_per_extraction?: number;
+    max_candidate_pool?: number;
   };
   checked_at: number;
 }
@@ -192,12 +199,25 @@ function isLlmDedupEnabled(): boolean {
 
 /**
  * Get the effective extraction interval.
- * Unified to 3 turns for all tiers (quota is per-transaction, not per-memory).
+ * Server-side config takes priority (from billing cache), then env var fallback.
+ * This allows the relay admin to tune extraction without an npm publish.
  */
 function getExtractInterval(): number {
+  const cache = readBillingCache();
+  if (cache?.features?.extraction_interval != null) return cache.features.extraction_interval;
   return AUTO_EXTRACT_EVERY_TURNS_ENV;
 }
 
+/**
+ * Get the max facts per extraction cycle.
+ * Server-side config takes priority (from billing cache), then env var / constant fallback.
+ */
+function getMaxFactsPerExtraction(): number {
+  const cache = readBillingCache();
+  if (cache?.features?.max_facts_per_extraction != null) return cache.features.max_facts_per_extraction;
+  return MAX_FACTS_PER_EXTRACTION;
+}
+
 /**
  * Ensure MEMORY.md has a TotalReclaw header so the agent knows encrypted
  * memories are injected automatically via the before_agent_start hook.
@@ -255,12 +275,18 @@ const FACT_COUNT_CACHE_TTL = 5 * 60 * 1000;
 /**
  * Compute the candidate pool size from a fact count.
  *
- * Formula: pool = min(max(factCount * 3, 400), 5000)
+ * Server-side config takes priority (from billing cache), then local fallback.
+ * The server computes the optimal pool based on vault size and tier caps.
+ *
+ * Local fallback formula: pool = min(max(factCount * 3, 400), 5000)
  *   - At least 400 candidates (even for tiny vaults)
  *   - At most 5000 candidates (to bound decryption + reranking cost)
  *   - 3x fact count in between
  */
 function computeCandidatePool(factCount: number): number {
+  const cache = readBillingCache();
+  if (cache?.features?.max_candidate_pool != null) return cache.features.max_candidate_pool;
+  // Fallback to local formula if no server config
   return Math.min(Math.max(factCount * 3, 400), 5000);
 }
 
@@ -302,21 +328,21 @@ async function getFactCount(logger: OpenClawPluginApi['logger']): Promise<number
 // Initialisation
 // ---------------------------------------------------------------------------
 
-/** True when master password is missing — tools return setup instructions. */
+/** True when recovery phrase is missing — tools return setup instructions. */
 let needsSetup = false;
 
 /**
- * Derive keys from the master password, load or create credentials, and
+ * Derive keys from the recovery phrase, load or create credentials, and
  * register with the server if this is the first run.
  */
 async function initialize(logger: OpenClawPluginApi['logger']): Promise<void> {
   const serverUrl =
     process.env.TOTALRECLAW_SERVER_URL || 'https://api.totalreclaw.xyz';
-  const masterPassword = process.env.TOTALRECLAW_MASTER_PASSWORD;
+  const masterPassword = process.env.TOTALRECLAW_RECOVERY_PHRASE;
 
   if (!masterPassword) {
     needsSetup = true;
-    logger.info('TOTALRECLAW_MASTER_PASSWORD not set — setup required (see SKILL.md Post-Install Setup)');
+    logger.info('TOTALRECLAW_RECOVERY_PHRASE not set — setup required (see SKILL.md Post-Install Setup)');
     return;
   }
 
@@ -399,6 +425,45 @@ async function initialize(logger: OpenClawPluginApi['logger']): Promise<void> {
       subgraphOwner = userId;
     }
   }
+
+  // One-time billing check for returning users (imported recovery phrase).
+  // If they already have an active Pro subscription, inform them on next conversation start.
+  if (existingUserId && authKeyHex) {
+    try {
+      const walletAddr = subgraphOwner || userId || '';
+      if (walletAddr) {
+        const billingUrl = (process.env.TOTALRECLAW_SERVER_URL || 'https://api.totalreclaw.xyz').replace(/\/+$/, '');
+        const resp = await fetch(`${billingUrl}/v1/billing/status?wallet_address=${encodeURIComponent(walletAddr)}`, {
+          method: 'GET',
+          headers: {
+            'Authorization': `Bearer ${authKeyHex}`,
+            'Accept': 'application/json',
+            'X-TotalReclaw-Client': 'openclaw-plugin',
+          },
+        });
+        if (resp.ok) {
+          const billingData = await resp.json() as Record<string, unknown>;
+          const tier = billingData.tier as string;
+          const expiresAt = billingData.expires_at as string | undefined;
+          // Populate billing cache for future use.
+          writeBillingCache({
+            tier: tier || 'free',
+            free_writes_used: (billingData.free_writes_used as number) ?? 0,
+            free_writes_limit: (billingData.free_writes_limit as number) ?? 0,
+            features: billingData.features as BillingCache['features'] | undefined,
+            checked_at: Date.now(),
+          });
+          if (tier === 'pro' && expiresAt) {
+            const expiryDate = new Date(expiresAt).toLocaleDateString();
+            welcomeBackMessage = `Welcome back! Your Pro subscription is active (expires: ${expiryDate}).`;
+            logger.info(`Returning Pro user detected — expires ${expiryDate}`);
+          }
+        }
+      }
+    } catch {
+      // Best-effort — don't block initialization on billing check failure.
+    }
+  }
 }
 
 function isDocker(): boolean {
@@ -412,27 +477,27 @@ function isDocker(): boolean {
 function buildSetupErrorMsg(): string {
   const base =
     'TotalReclaw setup required:\n' +
-    '1. Set TOTALRECLAW_MASTER_PASSWORD — ask the user if they have an existing recovery phrase or generate a new 12-word BIP-39 mnemonic.\n' +
+    '1. Set TOTALRECLAW_RECOVERY_PHRASE — ask the user if they have an existing recovery phrase or generate a new 12-word BIP-39 mnemonic.\n' +
     '2. Restart the gateway to apply changes.\n' +
     '   (Optional: set TOTALRECLAW_SELF_HOSTED=true if using your own server instead of the managed service.)\n\n';
 
   if (isDocker()) {
     return base +
       'Running in Docker — pass env vars via `-e` flags or your compose file:\n' +
-      '  -e TOTALRECLAW_MASTER_PASSWORD="word1 word2 ..."';
+      '  -e TOTALRECLAW_RECOVERY_PHRASE="word1 word2 ..."';
   }
 
   if (process.platform === 'darwin') {
     return base +
       'Running on macOS — add env vars to the LaunchAgent plist at\n' +
       '~/Library/LaunchAgents/ai.openclaw.gateway.plist under <key>EnvironmentVariables</key>:\n' +
-      '  <key>TOTALRECLAW_MASTER_PASSWORD</key><string>word1 word2 ...</string>\n' +
+      '  <key>TOTALRECLAW_RECOVERY_PHRASE</key><string>word1 word2 ...</string>\n' +
       'Then run: openclaw gateway restart';
   }
 
   return base +
     'Running on Linux — add env vars to the systemd unit override or your shell profile:\n' +
-    '  export TOTALRECLAW_MASTER_PASSWORD="word1 word2 ..."\n' +
+    '  export TOTALRECLAW_RECOVERY_PHRASE="word1 word2 ..."\n' +
     'Then run: openclaw gateway restart';
 }
 
@@ -463,7 +528,7 @@ async function requireFullSetup(logger: OpenClawPluginApi['logger']): Promise<vo
 // LSH + Embedding helpers
 // ---------------------------------------------------------------------------
 
-/** Master password cached for LSH seed derivation (set during initialize()). */
+/** Recovery phrase cached for LSH seed derivation (set during initialize()). */
 let masterPasswordCache: string | null = null;
 /** Salt cached for LSH seed derivation (set during initialize()). */
 let saltCache: Buffer | null = null;
@@ -472,7 +537,7 @@ let saltCache: Buffer | null = null;
  * Get or initialize the LSH hasher.
  *
  * The hasher is created lazily because it needs:
- *   1. The master password + salt (available after initialize())
+ *   1. The recovery phrase + salt (available after initialize())
  *   2. The embedding dimensions (available after initLLMClient())
  *
  * If the provider doesn't support embeddings, this returns null and
@@ -857,9 +922,13 @@ async function storeExtractedFacts(
   }
 
   // Phase 3: Store the deduplicated facts (with optional store-time dedup).
+  // In subgraph mode, collect all protobuf payloads (tombstones + new facts)
+  // and submit them in a single batched UserOp for gas efficiency.
   let stored = 0;
   let superseded = 0;
   let skipped = 0;
+  const pendingPayloads: Buffer[] = []; // Batched subgraph payloads
+  let preparedForSubgraph = 0;
 
   for (const fact of dedupedFacts) {
     try {
@@ -881,24 +950,19 @@ async function storeExtractedFacts(
       if (fact.action === 'DELETE' && fact.existingFactId) {
         // Tombstone the old fact, don't store anything new.
         if (isSubgraphMode()) {
-          try {
-            const tombConfig = { ...getSubgraphConfig(), authKeyHex: authKeyHex!, walletAddress: subgraphOwner ?? undefined };
-            const tombstone: FactPayload = {
-              id: fact.existingFactId,
-              timestamp: new Date().toISOString(),
-              owner: subgraphOwner || userId!,
-              encryptedBlob: '00',
-              blindIndices: [],
-              decayScore: 0,
-              source: 'tombstone',
-              contentFp: '',
-              agentId: 'openclaw-plugin-auto',
-            };
-            await submitFactOnChain(encodeFactProtobuf(tombstone), tombConfig);
-            logger.info(`LLM dedup: DELETE — tombstoned ${fact.existingFactId} on-chain`);
-          } catch (tombErr) {
-            logger.warn(`LLM dedup: DELETE failed for ${fact.existingFactId}: ${tombErr instanceof Error ? tombErr.message : String(tombErr)}`);
-          }
+          const tombstone: FactPayload = {
+            id: fact.existingFactId,
+            timestamp: new Date().toISOString(),
+            owner: subgraphOwner || userId!,
+            encryptedBlob: '00',
+            blindIndices: [],
+            decayScore: 0,
+            source: 'tombstone',
+            contentFp: '',
+            agentId: 'openclaw-plugin-auto',
+          };
+          pendingPayloads.push(encodeFactProtobuf(tombstone));
+          logger.info(`LLM dedup: DELETE — queued tombstone for ${fact.existingFactId}`);
         } else if (apiClient && authKeyHex) {
           try {
             await apiClient.deleteFact(fact.existingFactId, authKeyHex);
@@ -914,24 +978,19 @@ async function storeExtractedFacts(
       if (fact.action === 'UPDATE' && fact.existingFactId) {
         // Tombstone the old fact, then fall through to store the new version.
         if (isSubgraphMode()) {
-          try {
-            const tombConfig = { ...getSubgraphConfig(), authKeyHex: authKeyHex!, walletAddress: subgraphOwner ?? undefined };
-            const tombstone: FactPayload = {
-              id: fact.existingFactId,
-              timestamp: new Date().toISOString(),
-              owner: subgraphOwner || userId!,
-              encryptedBlob: '00',
-              blindIndices: [],
-              decayScore: 0,
-              source: 'tombstone',
-              contentFp: '',
-              agentId: 'openclaw-plugin-auto',
-            };
-            await submitFactOnChain(encodeFactProtobuf(tombstone), tombConfig);
-            logger.info(`LLM dedup: UPDATE — tombstoned ${fact.existingFactId} on-chain, storing replacement`);
-          } catch (tombErr) {
-            logger.warn(`LLM dedup: UPDATE tombstone failed for ${fact.existingFactId}: ${tombErr instanceof Error ? tombErr.message : String(tombErr)}`);
-          }
+          const tombstone: FactPayload = {
+            id: fact.existingFactId,
+            timestamp: new Date().toISOString(),
+            owner: subgraphOwner || userId!,
+            encryptedBlob: '00',
+            blindIndices: [],
+            decayScore: 0,
+            source: 'tombstone',
+            contentFp: '',
+            agentId: 'openclaw-plugin-auto',
+          };
+          pendingPayloads.push(encodeFactProtobuf(tombstone));
+          logger.info(`LLM dedup: UPDATE — queued tombstone for ${fact.existingFactId}, storing replacement`);
         } else if (apiClient && authKeyHex) {
           try {
             await apiClient.deleteFact(fact.existingFactId, authKeyHex);
@@ -969,29 +1028,21 @@ async function storeExtractedFacts(
           }
           // action === 'supersede': delete old fact, inherit higher importance
           if (isSubgraphMode()) {
-            try {
-              const tombConfig = { ...getSubgraphConfig(), authKeyHex: authKeyHex!, walletAddress: subgraphOwner ?? undefined };
-              const tombstone: FactPayload = {
-                id: dupResult.match.id,
-                timestamp: new Date().toISOString(),
-                owner: subgraphOwner || userId!,
-                encryptedBlob: '00',
-                blindIndices: [],
-                decayScore: 0,
-                source: 'tombstone',
-                contentFp: '',
-                agentId: 'openclaw-plugin-auto',
-              };
-              const tombProtobuf = encodeFactProtobuf(tombstone);
-              await submitFactOnChain(tombProtobuf, tombConfig);
-              logger.info(
-                `Store-time dedup: superseded ${dupResult.match.id} on-chain (sim=${dupResult.similarity.toFixed(3)})`,
-              );
-            } catch (tombErr) {
-              logger.warn(
-                `Store-time dedup: failed to tombstone ${dupResult.match.id}: ${tombErr instanceof Error ? tombErr.message : String(tombErr)}`,
-              );
-            }
+            const tombstone: FactPayload = {
+              id: dupResult.match.id,
+              timestamp: new Date().toISOString(),
+              owner: subgraphOwner || userId!,
+              encryptedBlob: '00',
+              blindIndices: [],
+              decayScore: 0,
+              source: 'tombstone',
+              contentFp: '',
+              agentId: 'openclaw-plugin-auto',
+            };
+            pendingPayloads.push(encodeFactProtobuf(tombstone));
+            logger.info(
+              `Store-time dedup: queued supersede for ${dupResult.match.id} (sim=${dupResult.similarity.toFixed(3)})`,
+            );
           } else if (apiClient && authKeyHex) {
             try {
               await apiClient.deleteFact(dupResult.match.id, authKeyHex);
@@ -1024,20 +1075,7 @@ async function storeExtractedFacts(
       const contentFp = generateContentFingerprint(fact.text, dedupKey);
       const factId = crypto.randomUUID();
 
-      const payload: StoreFactPayload = {
-        id: factId,
-        timestamp: new Date().toISOString(),
-        encrypted_blob: encryptedBlob,
-        blind_indices: allIndices,
-        decay_score: effectiveImportance,
-        source: 'auto-extraction',
-        content_fp: contentFp,
-        agent_id: 'openclaw-plugin-auto',
-        encrypted_embedding: embeddingResult?.encryptedEmbedding,
-      };
-
       if (isSubgraphMode()) {
-        const config = { ...getSubgraphConfig(), authKeyHex: authKeyHex!, walletAddress: subgraphOwner ?? undefined };
         const protobuf = encodeFactProtobuf({
           id: factId,
           timestamp: new Date().toISOString(),
@@ -1050,11 +1088,23 @@ async function storeExtractedFacts(
           agentId: 'openclaw-plugin-auto',
           encryptedEmbedding: embeddingResult?.encryptedEmbedding,
         });
-        await submitFactOnChain(protobuf, config);
+        pendingPayloads.push(protobuf);
+        preparedForSubgraph++;
       } else {
+        const payload: StoreFactPayload = {
+          id: factId,
+          timestamp: new Date().toISOString(),
+          encrypted_blob: encryptedBlob,
+          blind_indices: allIndices,
+          decay_score: effectiveImportance,
+          source: 'auto-extraction',
+          content_fp: contentFp,
+          agent_id: 'openclaw-plugin-auto',
+          encrypted_embedding: embeddingResult?.encryptedEmbedding,
+        };
         await apiClient.store(userId, [payload], authKeyHex);
+        stored++;
       }
-      stored++;
     } catch (err: unknown) {
       // Check for 403 / quota exceeded — invalidate billing cache so next
       // before_agent_start re-fetches and warns the user.
@@ -1068,6 +1118,28 @@ async function storeExtractedFacts(
     }
   }
 
+  // Batch-submit all subgraph payloads in a single UserOp (gas-efficient).
+  if (pendingPayloads.length > 0 && isSubgraphMode()) {
+    try {
+      const batchConfig = { ...getSubgraphConfig(), authKeyHex: authKeyHex!, walletAddress: subgraphOwner ?? undefined };
+      const result = await submitFactBatchOnChain(pendingPayloads, batchConfig);
+      if (result.success) {
+        stored += preparedForSubgraph;
+        logger.info(`Batch submitted ${result.batchSize} payloads in 1 UserOp (tx=${result.txHash.slice(0, 10)}…)`);
+      } else {
+        logger.warn(`Batch UserOp failed on-chain (tx=${result.txHash.slice(0, 10)}…)`);
+      }
+    } catch (err: unknown) {
+      const errMsg = err instanceof Error ? err.message : String(err);
+      if (errMsg.includes('403') || errMsg.toLowerCase().includes('quota')) {
+        try { fs.unlinkSync(BILLING_CACHE_PATH); } catch { /* ignore */ }
+        logger.warn(`Quota exceeded during batch submit — billing cache invalidated. ${errMsg}`);
+      } else {
+        logger.warn(`Batch submission failed: ${errMsg}`);
+      }
+    }
+  }
+
   if (stored > 0 || superseded > 0 || skipped > 0) {
     logger.info(`Auto-extraction results: stored=${stored}, superseded=${superseded}, skipped=${skipped}`);
   }
@@ -1239,7 +1311,7 @@ const plugin = {
             },
             type: {
               type: 'string',
-              enum: ['fact', 'preference', 'decision', 'episodic', 'goal'],
+              enum: ['fact', 'preference', 'decision', 'episodic', 'goal', 'context', 'summary'],
               description: 'The kind of memory (default: fact)',
             },
             importance: {
@@ -2154,6 +2226,85 @@ const plugin = {
       { name: 'totalreclaw_import_from' },
     );
 
+    // ---------------------------------------------------------------
+    // Tool: totalreclaw_upgrade
+    // ---------------------------------------------------------------
+
+    api.registerTool(
+      {
+        name: 'totalreclaw_upgrade',
+        label: 'Upgrade to Pro',
+        description:
+          'Upgrade to TotalReclaw Pro for unlimited encrypted memories. ' +
+          'Returns a Stripe checkout URL for the user to complete payment via credit/debit card.',
+        parameters: {
+          type: 'object',
+          properties: {},
+          additionalProperties: false,
+        },
+        async execute() {
+          try {
+            await requireFullSetup(api.logger);
+
+            if (!authKeyHex) {
+              return {
+                content: [{ type: 'text', text: 'Auth credentials are not available. Please initialize first.' }],
+              };
+            }
+
+            const serverUrl = (process.env.TOTALRECLAW_SERVER_URL || 'https://api.totalreclaw.xyz').replace(/\/+$/, '');
+            const walletAddr = subgraphOwner || userId || '';
+
+            if (!walletAddr) {
+              return {
+                content: [{ type: 'text', text: 'Wallet address not available. Please ensure the plugin is fully initialized.' }],
+              };
+            }
+
+            const response = await fetch(`${serverUrl}/v1/billing/checkout`, {
+              method: 'POST',
+              headers: {
+                'Authorization': `Bearer ${authKeyHex}`,
+                'Content-Type': 'application/json',
+                'X-TotalReclaw-Client': 'openclaw-plugin',
+              },
+              body: JSON.stringify({
+                wallet_address: walletAddr,
+                tier: 'pro',
+              }),
+            });
+
+            if (!response.ok) {
+              const body = await response.text().catch(() => '');
+              return {
+                content: [{ type: 'text', text: `Failed to create checkout session (HTTP ${response.status}): ${body || response.statusText}` }],
+              };
+            }
+
+            const data = await response.json() as { checkout_url?: string };
+
+            if (!data.checkout_url) {
+              return {
+                content: [{ type: 'text', text: 'Failed to create checkout session: no checkout URL returned.' }],
+              };
+            }
+
+            return {
+              content: [{ type: 'text', text: `Open this URL to upgrade to Pro: ${data.checkout_url}` }],
+              details: { checkout_url: data.checkout_url },
+            };
+          } catch (err: unknown) {
+            const message = err instanceof Error ? err.message : String(err);
+            api.logger.error(`totalreclaw_upgrade failed: ${message}`);
+            return {
+              content: [{ type: 'text', text: `Failed to create checkout session: ${message}` }],
+            };
+          }
+        },
+      },
+      { name: 'totalreclaw_upgrade' },
+    );
+
     // ---------------------------------------------------------------
     // Hook: before_agent_start
     // ---------------------------------------------------------------
@@ -2184,6 +2335,13 @@ const plugin = {
             };
           }
 
+          // One-time welcome-back message for returning Pro users.
+          let welcomeBack = '';
+          if (welcomeBackMessage) {
+            welcomeBack = `\n\n${welcomeBackMessage}`;
+            welcomeBackMessage = null; // Consume — only show once
+          }
+
           // Billing cache check — warn if quota is approaching limit.
           let billingWarning = '';
           try {
@@ -2257,7 +2415,7 @@ const plugin = {
                 const lines = cachedFacts.slice(0, 8).map((f, i) =>
                   `${i + 1}. ${f.text} (importance: ${f.importance}/10, cached)`,
                 );
-                return { prependContext: `## Relevant Memories\n\n${lines.join('\n')}` + billingWarning };
+                return { prependContext: `## Relevant Memories\n\n${lines.join('\n')}` + welcomeBack + billingWarning };
               }
             }
 
@@ -2270,7 +2428,7 @@ const plugin = {
               const lines = cachedFacts.slice(0, 8).map((f, i) =>
                 `${i + 1}. ${f.text} (importance: ${f.importance}/10, cached)`,
               );
-              return { prependContext: `## Relevant Memories\n\n${lines.join('\n')}` + billingWarning };
+              return { prependContext: `## Relevant Memories\n\n${lines.join('\n')}` + welcomeBack + billingWarning };
             }
 
             if (allTrapdoors.length === 0) return undefined;
@@ -2287,7 +2445,7 @@ const plugin = {
                 const lines = cachedFacts.slice(0, 8).map((f, i) =>
                   `${i + 1}. ${f.text} (importance: ${f.importance}/10, cached)`,
                 );
-                return { prependContext: `## Relevant Memories\n\n${lines.join('\n')}` + billingWarning };
+                return { prependContext: `## Relevant Memories\n\n${lines.join('\n')}` + welcomeBack + billingWarning };
               }
               return undefined;
             }
@@ -2299,7 +2457,7 @@ const plugin = {
               const lines = cachedFacts.slice(0, 8).map((f, i) =>
                 `${i + 1}. ${f.text} (importance: ${f.importance}/10, cached)`,
               );
-              return { prependContext: `## Relevant Memories\n\n${lines.join('\n')}` + billingWarning };
+              return { prependContext: `## Relevant Memories\n\n${lines.join('\n')}` + welcomeBack + billingWarning };
             }
 
             // 5. Decrypt subgraph results and build reranker input.
@@ -2405,7 +2563,7 @@ const plugin = {
             });
             const contextString = `## Relevant Memories\n\n${lines.join('\n')}`;
 
-            return { prependContext: contextString + billingWarning };
+            return { prependContext: contextString + welcomeBack + billingWarning };
           }
 
           // --- Server mode (existing behavior) ---
@@ -2517,7 +2675,7 @@ const plugin = {
           });
           const contextString = `## Relevant Memories\n\n${lines.join('\n')}`;
 
-          return { prependContext: contextString + billingWarning };
+          return { prependContext: contextString + welcomeBack + billingWarning };
         } catch (err: unknown) {
           // The hook must NEVER throw -- log and return undefined.
           const message = err instanceof Error ? err.message : String(err);
@@ -2550,12 +2708,13 @@ const plugin = {
               : [];
             const rawFacts = await extractFacts(evt.messages, 'turn', existingMemories);
             const { kept: importanceFiltered } = filterByImportance(rawFacts, api.logger);
-            if (importanceFiltered.length > MAX_FACTS_PER_EXTRACTION) {
+            const maxFacts = getMaxFactsPerExtraction();
+            if (importanceFiltered.length > maxFacts) {
               api.logger.info(
-                `Capped extraction from ${importanceFiltered.length} to ${MAX_FACTS_PER_EXTRACTION} facts`,
+                `Capped extraction from ${importanceFiltered.length} to ${maxFacts} facts`,
               );
             }
-            const facts = importanceFiltered.slice(0, MAX_FACTS_PER_EXTRACTION);
+            const facts = importanceFiltered.slice(0, maxFacts);
             if (facts.length > 0) {
               await storeExtractedFacts(facts, api.logger);
             }
@@ -2592,12 +2751,13 @@ const plugin = {
             : [];
           const rawCompactFacts = await extractFacts(evt.messages, 'full', existingMemories);
           const { kept: compactImportanceFiltered } = filterByImportance(rawCompactFacts, api.logger);
-          if (compactImportanceFiltered.length > MAX_FACTS_PER_EXTRACTION) {
+          const maxFactsCompact = getMaxFactsPerExtraction();
+          if (compactImportanceFiltered.length > maxFactsCompact) {
             api.logger.info(
-              `Capped compaction extraction from ${compactImportanceFiltered.length} to ${MAX_FACTS_PER_EXTRACTION} facts`,
+              `Capped compaction extraction from ${compactImportanceFiltered.length} to ${maxFactsCompact} facts`,
             );
           }
-          const facts = compactImportanceFiltered.slice(0, MAX_FACTS_PER_EXTRACTION);
+          const facts = compactImportanceFiltered.slice(0, maxFactsCompact);
           if (facts.length > 0) {
             await storeExtractedFacts(facts, api.logger);
           }
@@ -2633,12 +2793,13 @@ const plugin = {
             : [];
           const rawResetFacts = await extractFacts(evt.messages, 'full', existingMemories);
           const { kept: resetImportanceFiltered } = filterByImportance(rawResetFacts, api.logger);
-          if (resetImportanceFiltered.length > MAX_FACTS_PER_EXTRACTION) {
+          const maxFactsReset = getMaxFactsPerExtraction();
+          if (resetImportanceFiltered.length > maxFactsReset) {
             api.logger.info(
-              `Capped reset extraction from ${resetImportanceFiltered.length} to ${MAX_FACTS_PER_EXTRACTION} facts`,
+              `Capped reset extraction from ${resetImportanceFiltered.length} to ${maxFactsReset} facts`,
             );
           }
-          const facts = resetImportanceFiltered.slice(0, MAX_FACTS_PER_EXTRACTION);
+          const facts = resetImportanceFiltered.slice(0, maxFactsReset);
           if (facts.length > 0) {
             await storeExtractedFacts(facts, api.logger);
           }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@totalreclaw/totalreclaw",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "End-to-end encrypted memory for AI agents — portable, yours forever. Automatic extraction, semantic search, and on-chain storage",
   "type": "module",
   "keywords": [

package/setup.sh

@@ -16,4 +16,4 @@ echo "  cd testbed/functional-test"
 echo "  docker compose -f docker-compose.functional-test.yml up -d"
 echo ""
 echo "The plugin will auto-register on first use."
-echo "Set TOTALRECLAW_MASTER_PASSWORD in your .env file."
+echo "Set TOTALRECLAW_RECOVERY_PHRASE in your .env file."

package/subgraph-store.ts

@@ -189,7 +189,7 @@ export async function submitFactOnChain(
   }
 
   if (!config.mnemonic) {
-    throw new Error('Mnemonic (TOTALRECLAW_MASTER_PASSWORD) is required for on-chain submission');
+    throw new Error('Mnemonic (TOTALRECLAW_RECOVERY_PHRASE) is required for on-chain submission');
   }
 
   const chain = getChainFromId(config.chainId);
@@ -281,6 +281,105 @@ export async function submitFactOnChain(
   };
 }
 
+/**
+ * Submit multiple facts on-chain in a single ERC-4337 UserOp (batched).
+ *
+ * Each protobuf payload becomes one call in a multi-call UserOp. The
+ * DataEdge contract emits a separate Log(bytes) event per call, and the
+ * subgraph indexes each event independently (by txHash + logIndex).
+ *
+ * Falls back to single-fact path for batches of 1 (no multicall overhead).
+ */
+export async function submitFactBatchOnChain(
+  protobufPayloads: Buffer[],
+  config: SubgraphStoreConfig,
+): Promise<{ txHash: string; userOpHash: string; success: boolean; batchSize: number }> {
+  if (!protobufPayloads.length) {
+    return { txHash: '', userOpHash: '', success: true, batchSize: 0 };
+  }
+
+  // Single fact — use standard path (avoids multicall overhead)
+  if (protobufPayloads.length === 1) {
+    const result = await submitFactOnChain(protobufPayloads[0], config);
+    return { ...result, batchSize: 1 };
+  }
+
+  if (!config.relayUrl) {
+    throw new Error('Relay URL (TOTALRECLAW_SERVER_URL) is required for on-chain submission');
+  }
+  if (!config.mnemonic) {
+    throw new Error('Mnemonic (TOTALRECLAW_RECOVERY_PHRASE) is required for on-chain submission');
+  }
+
+  const chain = getChainFromId(config.chainId);
+  const bundlerRpcUrl = getRelayBundlerUrl(config.relayUrl);
+  const dataEdgeAddress = config.dataEdgeAddress as Address;
+  const entryPointAddr = (config.entryPointAddress || entryPoint07Address) as Address;
+
+  const headers: Record<string, string> = {
+    'X-TotalReclaw-Client': 'openclaw-plugin',
+  };
+  if (config.authKeyHex) headers['Authorization'] = `Bearer ${config.authKeyHex}`;
+  if (config.walletAddress) headers['X-Wallet-Address'] = config.walletAddress;
+
+  const authTransport = Object.keys(headers).length > 0
+    ? http(bundlerRpcUrl, { fetchOptions: { headers } })
+    : http(bundlerRpcUrl);
+
+  const ownerAccount = mnemonicToAccount(config.mnemonic);
+  const publicClient = createPublicClient({
+    chain,
+    transport: config.rpcUrl ? http(config.rpcUrl) : http(),
+  });
+
+  const pimlicoClient = createPimlicoClient({
+    chain,
+    transport: authTransport,
+    entryPoint: {
+      address: entryPointAddr,
+      version: '0.7',
+    },
+  });
+
+  const smartAccount = await toSimpleSmartAccount({
+    client: publicClient,
+    owner: ownerAccount,
+    entryPoint: {
+      address: entryPointAddr,
+      version: '0.7',
+    },
+  });
+
+  const smartAccountClient = createSmartAccountClient({
+    account: smartAccount,
+    chain,
+    bundlerTransport: authTransport,
+    paymaster: pimlicoClient,
+    userOperation: {
+      estimateFeesPerGas: async () => {
+        return (await pimlicoClient.getUserOperationGasPrice()).fast;
+      },
+    },
+  });
+
+  // Build multi-call batch: each payload → one call to DataEdge fallback()
+  const calls = protobufPayloads.map(payload => ({
+    to: dataEdgeAddress,
+    value: 0n,
+    data: `0x${payload.toString('hex')}` as Hex,
+  }));
+
+  const userOpHash = await smartAccountClient.sendUserOperation({ calls });
+  const receipt = await pimlicoClient.waitForUserOperationReceipt({ hash: userOpHash });
+
+  return {
+    txHash: receipt.receipt.transactionHash,
+    userOpHash,
+    success: receipt.success,
+    batchSize: protobufPayloads.length,
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Configuration
 // ---------------------------------------------------------------------------
@@ -299,7 +398,7 @@ export function isSubgraphMode(): boolean {
  * Get subgraph configuration from environment variables.
  *
  * After the relay refactor, clients only need:
- *   - TOTALRECLAW_MASTER_PASSWORD -- BIP-39 mnemonic
+ *   - TOTALRECLAW_RECOVERY_PHRASE -- BIP-39 mnemonic
  *   - TOTALRECLAW_SERVER_URL -- relay server URL (default: https://api.totalreclaw.xyz)
  *   - TOTALRECLAW_SELF_HOSTED -- set "true" to use self-hosted server (default: managed service)
  *   - TOTALRECLAW_CHAIN_ID -- optional, defaults to 100 (Gnosis mainnet)
@@ -338,7 +437,7 @@ export async function deriveSmartAccountAddress(mnemonic: string, chainId?: numb
 export function getSubgraphConfig(): SubgraphStoreConfig {
   return {
     relayUrl: process.env.TOTALRECLAW_SERVER_URL || 'https://api.totalreclaw.xyz',
-    mnemonic: process.env.TOTALRECLAW_MASTER_PASSWORD || '',
+    mnemonic: process.env.TOTALRECLAW_RECOVERY_PHRASE || '',
     cachePath: process.env.TOTALRECLAW_CACHE_PATH || `${process.env.HOME}/.totalreclaw/cache.enc`,
     chainId: parseInt(process.env.TOTALRECLAW_CHAIN_ID || '100'),
     dataEdgeAddress: process.env.TOTALRECLAW_DATA_EDGE_ADDRESS || DEFAULT_DATA_EDGE_ADDRESS,