@totalreclaw/totalreclaw 1.1.0 → 1.3.0

package/README.md

@@ -1,32 +1,52 @@
-# @totalreclaw/totalreclaw
+<p align="center">
+  <img src="../../docs/assets/logo.png" alt="TotalReclaw" width="80" />
+</p>
 
-Encrypted memory for your AI agent — zero-knowledge E2EE vault with automatic extraction, semantic search, and portable storage.
+<h1 align="center">@totalreclaw/totalreclaw</h1>
 
-Built for [OpenClaw](https://openclaw.ai). Your memories are encrypted on your device before leaving — no one can read them, not even us.
+<p align="center">
+  <strong>End-to-end encrypted memory for OpenClaw -- fully automatic, yours forever</strong>
+</p>
 
-**[totalreclaw.xyz](https://totalreclaw.xyz)**
+<p align="center">
+  <a href="https://totalreclaw.xyz">Website</a> &middot;
+  <a href="https://www.npmjs.com/package/@totalreclaw/totalreclaw">npm</a> &middot;
+  <a href="../../docs/guides/beta-tester-guide.md">Getting Started</a>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@totalreclaw/totalreclaw"><img src="https://img.shields.io/npm/v/@totalreclaw/totalreclaw?color=7B5CFF" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/@totalreclaw/totalreclaw"><img src="https://img.shields.io/npm/dm/@totalreclaw/totalreclaw" alt="npm downloads"></a>
+  <a href="../../LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="License"></a>
+</p>
+
+---
+
+Your AI agent remembers everything -- preferences, decisions, facts -- encrypted so only you can read it. Built for [OpenClaw](https://openclaw.ai) with fully automatic memory extraction and recall.
 
 ## Install
 
+Ask your OpenClaw agent:
+
+> "Install the @totalreclaw/totalreclaw plugin"
+
+Or from the terminal:
+
 ```bash
 openclaw plugins install @totalreclaw/totalreclaw
 ```
 
-Or just ask your agent:
-
-> "Install the totalreclaw plugin"
-
-The agent handles setup: generates your encryption keys and registers you. You'll be asked to write down a 12-word recovery phrase — that's the only thing you need to keep safe.
+The agent handles setup: generates your encryption keys, asks you to save a 12-word recovery phrase, and registers you. After that, memory is fully automatic.
 
 ## How It Works
 
-After setup, memory is **fully automatic**:
+After setup, everything happens in the background:
 
-- **Start of conversation** — loads relevant memories from your vault
-- **End of conversation** — extracts and encrypts new facts before storing them
-- **Before context compaction** — saves everything important before the context window is trimmed
+- **Start of conversation** -- loads relevant memories from your encrypted vault
+- **During conversation** -- extracts facts, preferences, and decisions automatically
+- **Before context compaction** -- saves important context before the window is trimmed
 
-All encryption happens client-side using AES-256-GCM. Search uses blind indices (SHA-256 hashes) — the server never sees your queries or data. Your 12-word recovery phrase derives all keys via Argon2id + HKDF.
+All encryption happens client-side using AES-256-GCM. The server never sees your plaintext data.
 
 ## Tools
 
@@ -39,48 +59,45 @@ Your agent gets these tools automatically:
 | `totalreclaw_forget` | Delete a specific memory |
 | `totalreclaw_export` | Export all memories as plaintext |
 | `totalreclaw_status` | Check billing status and quota |
+| `totalreclaw_consolidate` | Merge duplicate memories |
+| `totalreclaw_import_from` | Import from Mem0 or MCP Memory Server |
 
-Most of the time you won't use these directly — the automatic hooks handle memory for you.
+Most of the time you won't use these directly -- the automatic hooks handle memory for you.
 
 ## Features
 
-- **Zero-knowledge E2EE** — AES-256-GCM encryption, blind index search, HKDF auth
-- **Semantic search** — Local embeddings (bge-small-en-v1.5) + BM25 + cosine reranking with RRF
-- **Automatic extraction** — LLM extracts facts from conversations, no manual input needed
-- **Dedup** — Cosine similarity catches paraphrases; LLM-guided dedup catches contradictions (Pro)
-- **On-chain storage** — Encrypted data stored on Gnosis Chain, indexed by The Graph
-- **Portable** — One 12-word phrase. Any device, same memories, no lock-in
-- **Import** — Migrate from Mem0 or MCP Memory Server
+- **End-to-end encrypted** -- AES-256-GCM encryption, blind index search, HKDF auth
+- **Automatic extraction** -- LLM extracts facts from conversations, no manual input needed
+- **Semantic search** -- Local embeddings + BM25 + cosine reranking with RRF fusion
+- **Smart dedup** -- Cosine similarity catches paraphrases; LLM-guided dedup catches contradictions (Pro)
+- **On-chain storage** -- Encrypted data stored on Gnosis Chain, indexed by The Graph
+- **Portable** -- One 12-word phrase. Any device, same memories, no lock-in
+- **Import** -- Migrate from Mem0 or MCP Memory Server
 
 ## Free Tier & Pricing
 
-| Tier | Writes | Reads | Price |
-|------|--------|-------|-------|
-| **Free** | 250/month | Unlimited | $0 |
-| **Pro** | 10,000/month | Unlimited | $2-5/month |
-
-Pay with card (Stripe) or crypto (Coinbase Commerce). Counter resets monthly.
-
-## Configuration
+| Tier | Memories | Reads | Storage | Price |
+|------|----------|-------|---------|-------|
+| **Free** | 500/month | Unlimited | Testnet (trial) | $0 |
+| **Pro** | Unlimited | Unlimited | Permanent on-chain (Gnosis) | $5/month |
 
-Set these environment variables before the agent starts:
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `TOTALRECLAW_SERVER_URL` | Server URL | `https://api.totalreclaw.xyz` |
-| `TOTALRECLAW_CREDENTIALS_PATH` | Path to credentials file | `~/.totalreclaw/credentials.json` |
-| `TOTALRECLAW_SELF_HOSTED` | Set to `true` to use your own self-hosted server instead of the managed service | `false` (managed service) |
-| `TOTALRECLAW_EXTRACT_EVERY_TURNS` | Auto-extract interval (turns) | `5` (Free) / `2` (Pro min) |
+Pay with card via Stripe. Counter resets monthly.
 
 ## Using with Other Agents
 
 TotalReclaw also works outside OpenClaw:
 
-- **Claude Desktop / Cursor / Windsurf** — Use [@totalreclaw/mcp-server](https://www.npmjs.com/package/@totalreclaw/mcp-server)
-- **NanoClaw** — Lightweight skill with MCP bridge
+- **Claude Desktop / Cursor / Windsurf** -- Use [@totalreclaw/mcp-server](https://www.npmjs.com/package/@totalreclaw/mcp-server)
+- **NanoClaw** -- Built-in support via MCP bridge
 
 Same encryption, same recovery phrase, same memories across all agents.
 
+## Learn More
+
+- [Getting Started Guide](../../docs/guides/beta-tester-guide.md)
+- [totalreclaw.xyz](https://totalreclaw.xyz)
+- [Main Repository](https://github.com/p-diogo/totalreclaw)
+
 ## License
 
 MIT

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/embedding.ts

@@ -1,73 +1,64 @@
 /**
  * TotalReclaw Plugin - Local Embedding via @huggingface/transformers
  *
- * Uses the Xenova/bge-small-en-v1.5 ONNX model to generate 384-dimensional
+ * Uses the Qwen3-Embedding-0.6B ONNX model to generate 1024-dimensional
  * text embeddings locally. No API key needed, no data leaves the machine.
+ * Supports 100+ languages (EN, PT, ES, ZH, etc.).
  *
- * This preserves the zero-knowledge guarantee: embeddings are generated
+ * This preserves the E2EE guarantee: embeddings are generated
  * CLIENT-SIDE before encryption, so no plaintext ever reaches an external API.
  *
  * Model details:
- *   - Quantized (int8) ONNX model: ~33.8MB download on first use
+ *   - Quantized (int8) ONNX model: ~600MB download on first use
  *   - Cached in ~/.cache/huggingface/ after first download
- *   - Lazy initialization: first call ~2-3s (model load), subsequent ~15ms
- *   - Output: 384-dimensional normalized embedding vector
- *   - For retrieval, queries should be prefixed with an instruction string
- *     (documents/passages should NOT be prefixed)
+ *   - Lazy initialization: first call ~3-5s (model load), subsequent ~100ms
+ *   - Output: 1024-dimensional normalized embedding vector
+ *   - No instruction prefix needed (bare queries perform better)
  *
- * Dependencies: @huggingface/transformers (handles model download, WordPiece
- * tokenization, ONNX inference, mean pooling, and normalization).
+ * Dependencies: @huggingface/transformers (handles model download,
+ * tokenization, ONNX inference, last-token pooling, and normalization).
  */
 
 // @ts-ignore - @huggingface/transformers types may not be perfect
 import { pipeline, type FeatureExtractionPipeline } from '@huggingface/transformers';
 
-/** ONNX-optimized bge-small-en-v1.5 from HuggingFace Hub. */
-const MODEL_ID = 'Xenova/bge-small-en-v1.5';
+/** ONNX-optimized Qwen3-Embedding-0.6B from HuggingFace Hub. */
+const MODEL_ID = 'onnx-community/Qwen3-Embedding-0.6B-ONNX';
 
-/** Fixed output dimensionality for bge-small-en-v1.5. */
-const EMBEDDING_DIM = 384;
-
-/**
- * Query instruction prefix for bge-small-en-v1.5 retrieval tasks.
- *
- * Per the BAAI model card: prepend this to short queries when searching
- * for relevant passages. Do NOT prepend for documents/passages being stored.
- */
-const QUERY_PREFIX = 'Represent this sentence for searching relevant passages: ';
+/** Fixed output dimensionality for Qwen3-Embedding-0.6B. */
+const EMBEDDING_DIM = 1024;
 
 /** Lazily initialized feature extraction pipeline. */
 let extractor: FeatureExtractionPipeline | null = null;
 
 /**
- * Generate a 384-dimensional embedding vector for the given text.
+ * Generate a 1024-dimensional embedding vector for the given text.
  *
- * On first call, downloads and loads the ONNX model (~33.8MB, cached).
- * Subsequent calls reuse the loaded model and run in ~15ms.
+ * On first call, downloads and loads the ONNX model (~600MB, cached).
+ * Subsequent calls reuse the loaded model and run in ~100ms.
  *
- * For bge-small-en-v1.5, queries should set `isQuery: true` to prepend the
- * retrieval instruction prefix. Documents being stored should use the default
- * (`isQuery: false`) so no prefix is added.
+ * The isQuery option is accepted for forward compatibility but does not
+ * change behavior -- Qwen3 performs better without instruction prefixes.
  *
  * @param text - The text to embed.
  * @param options - Optional settings.
- * @param options.isQuery - If true, prepend the BGE query instruction prefix
- *                          for improved retrieval accuracy (default: false).
- * @returns 384-dimensional normalized embedding as a number array.
+ * @param options.isQuery - Accepted for forward compatibility (no-op).
+ * @returns 1024-dimensional normalized embedding as a number array.
  */
 export async function generateEmbedding(
   text: string,
   options?: { isQuery?: boolean },
 ): Promise<number[]> {
   if (!extractor) {
+    console.log('Downloading embedding model (one-time setup, ~600MB)...');
     extractor = await pipeline('feature-extraction', MODEL_ID, {
-      // Use quantized (int8) model for smaller download (~33.8MB vs ~67MB)
       quantized: true,
     });
+    console.log('Embedding model ready.');
   }
 
-  const input = options?.isQuery ? QUERY_PREFIX + text : text;
-  const output = await extractor(input, { pooling: 'mean', normalize: true });
+  const input = text;
+  const output = await extractor(input, { pooling: 'last_token', normalize: true });
   // output.data is a Float32Array; convert to plain number[]
   return Array.from(output.data as Float32Array);
 }
@@ -75,7 +66,7 @@ export async function generateEmbedding(
 /**
  * Get the embedding vector dimensionality.
  *
- * Always returns 384 (fixed for bge-small-en-v1.5).
+ * Always returns 1024 (fixed for Qwen3-Embedding-0.6B).
  * This is needed by downstream code (e.g. LSH hasher) to know the vector
  * size without calling the embedding model.
  */

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

@@ -41,7 +41,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';
@@ -126,7 +126,10 @@ const SEMANTIC_SKIP_THRESHOLD = parseFloat(process.env.TOTALRECLAW_SEMANTIC_SKIP
 
 // Auto-extract throttle (C3): only extract every N turns in agent_end hook
 let turnsSinceLastExtraction = 0;
-const AUTO_EXTRACT_EVERY_TURNS_ENV = parseInt(process.env.TOTALRECLAW_EXTRACT_EVERY_TURNS ?? '5', 10);
+const AUTO_EXTRACT_EVERY_TURNS_ENV = parseInt(process.env.TOTALRECLAW_EXTRACT_EVERY_TURNS ?? '3', 10);
+
+// Hard cap on facts per extraction to prevent LLM over-extraction from dense conversations
+const MAX_FACTS_PER_EXTRACTION = 15;
 
 // Store-time near-duplicate detection (consolidation module)
 const STORE_DEDUP_ENABLED = process.env.TOTALRECLAW_STORE_DEDUP !== 'false';
@@ -139,7 +142,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 {
@@ -150,6 +153,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;
 }
@@ -188,13 +194,24 @@ function isLlmDedupEnabled(): boolean {
 }
 
 /**
- * Get the effective extraction interval based on tier.
- * Pro users can set interval as low as 2 via env; Free users are clamped to minimum 5.
+ * Get the effective extraction interval.
+ * 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();
-  const minInterval = cache?.features?.min_extract_interval ?? 5;
-  return Math.max(AUTO_EXTRACT_EVERY_TURNS_ENV, minInterval);
+  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;
 }
 
 /**
@@ -254,12 +271,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);
 }
 
@@ -301,21 +324,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;
   }
 
@@ -411,27 +434,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';
 }
 
@@ -462,7 +485,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;
@@ -471,7 +494,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
@@ -517,7 +540,7 @@ async function generateEmbeddingAndLSH(
     const hasher = getLSHHasher(logger);
     const lshBuckets = hasher ? hasher.hash(embedding) : [];
 
-    // Encrypt the embedding (JSON array of numbers) for zero-knowledge storage
+    // Encrypt the embedding (JSON array of numbers) for server-blind storage
     const encryptedEmbedding = encryptToHex(JSON.stringify(embedding), encryptionKey!);
 
     return { embedding, lshBuckets, encryptedEmbedding };
@@ -856,9 +879,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 {
@@ -880,24 +907,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);
@@ -913,24 +935,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);
@@ -968,29 +985,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);
@@ -1023,20 +1032,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(),
@@ -1049,11 +1045,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.
@@ -1067,6 +1075,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}`);
   }
@@ -1177,7 +1207,7 @@ async function handlePluginImportFrom(
 const plugin = {
   id: 'totalreclaw',
   name: 'TotalReclaw',
-  description: 'Zero-knowledge encrypted memory vault for AI agents',
+  description: 'End-to-end encrypted memory vault for AI agents',
   kind: 'memory' as const,
   configSchema: {
     type: 'object',
@@ -1238,7 +1268,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: {
@@ -2548,7 +2578,14 @@ const plugin = {
               ? await fetchExistingMemoriesForExtraction(api.logger, 20, evt.messages)
               : [];
             const rawFacts = await extractFacts(evt.messages, 'turn', existingMemories);
-            const { kept: facts } = filterByImportance(rawFacts, api.logger);
+            const { kept: importanceFiltered } = filterByImportance(rawFacts, api.logger);
+            const maxFacts = getMaxFactsPerExtraction();
+            if (importanceFiltered.length > maxFacts) {
+              api.logger.info(
+                `Capped extraction from ${importanceFiltered.length} to ${maxFacts} facts`,
+              );
+            }
+            const facts = importanceFiltered.slice(0, maxFacts);
             if (facts.length > 0) {
               await storeExtractedFacts(facts, api.logger);
             }
@@ -2584,7 +2621,14 @@ const plugin = {
             ? await fetchExistingMemoriesForExtraction(api.logger, 50, evt.messages)
             : [];
           const rawCompactFacts = await extractFacts(evt.messages, 'full', existingMemories);
-          const { kept: facts } = filterByImportance(rawCompactFacts, api.logger);
+          const { kept: compactImportanceFiltered } = filterByImportance(rawCompactFacts, api.logger);
+          const maxFactsCompact = getMaxFactsPerExtraction();
+          if (compactImportanceFiltered.length > maxFactsCompact) {
+            api.logger.info(
+              `Capped compaction extraction from ${compactImportanceFiltered.length} to ${maxFactsCompact} facts`,
+            );
+          }
+          const facts = compactImportanceFiltered.slice(0, maxFactsCompact);
           if (facts.length > 0) {
             await storeExtractedFacts(facts, api.logger);
           }
@@ -2619,7 +2663,14 @@ const plugin = {
             ? await fetchExistingMemoriesForExtraction(api.logger, 50, evt.messages)
             : [];
           const rawResetFacts = await extractFacts(evt.messages, 'full', existingMemories);
-          const { kept: facts } = filterByImportance(rawResetFacts, api.logger);
+          const { kept: resetImportanceFiltered } = filterByImportance(rawResetFacts, api.logger);
+          const maxFactsReset = getMaxFactsPerExtraction();
+          if (resetImportanceFiltered.length > maxFactsReset) {
+            api.logger.info(
+              `Capped reset extraction from ${resetImportanceFiltered.length} to ${maxFactsReset} facts`,
+            );
+          }
+          const facts = resetImportanceFiltered.slice(0, maxFactsReset);
           if (facts.length > 0) {
             await storeExtractedFacts(facts, api.logger);
           }

package/lsh.ts

@@ -1,7 +1,7 @@
 /**
  * TotalReclaw Plugin - LSH Hasher (Locality-Sensitive Hashing)
  *
- * Pure TypeScript implementation of Random Hyperplane LSH for zero-knowledge
+ * Pure TypeScript implementation of Random Hyperplane LSH for server-blind
  * semantic search. Generates deterministic hyperplane matrices from a seed
  * derived from the user's master key, so the same embedding always hashes to
  * the same buckets across sessions.

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "totalreclaw",
   "name": "TotalReclaw",
   "kind": "memory",
-  "description": "Zero-knowledge encrypted memory vault for AI agents",
+  "description": "End-to-end encrypted memory vault for AI agents",
   "configSchema": {
     "type": "object",
     "properties": {

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@totalreclaw/totalreclaw",
-  "version": "1.1.0",
-  "description": "Encrypted memory for your AI agent — zero-knowledge E2EE vault with automatic extraction, semantic search, and on-chain storage",
+  "version": "1.3.0",
+  "description": "End-to-end encrypted memory for AI agents — portable, yours forever. Automatic extraction, semantic search, and on-chain storage",
   "type": "module",
   "keywords": [
     "totalreclaw",
     "openclaw",
     "ai-memory",
     "ai-agent",
-    "zero-knowledge",
+    "e2e-encryption",
     "encryption",
     "e2ee",
     "lsh",

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

@@ -13,7 +13,7 @@
 import { createPublicClient, http, type Hex, type Address, type Chain } from 'viem';
 import { entryPoint07Address } from 'viem/account-abstraction';
 import { mnemonicToAccount } from 'viem/accounts';
-import { gnosis, gnosisChiado } from 'viem/chains';
+import { gnosis, gnosisChiado, baseSepolia } from 'viem/chains';
 import { createSmartAccountClient } from 'permissionless';
 import { toSimpleSmartAccount } from 'permissionless/accounts';
 import { createPimlicoClient } from 'permissionless/clients/pimlico';
@@ -32,7 +32,7 @@ export interface SubgraphStoreConfig {
   relayUrl: string;           // TotalReclaw relay server URL (proxies bundler + subgraph)
   mnemonic: string;           // BIP-39 mnemonic for key derivation
   cachePath: string;          // Hot cache file path
-  chainId: number;            // 100 for Gnosis mainnet, 10200 for Chiado testnet
+  chainId: number;            // 100 for Gnosis mainnet, 10200 for Chiado testnet, 84532 for Base Sepolia
   dataEdgeAddress: string;    // EventfulDataEdge contract address
   entryPointAddress: string;  // ERC-4337 EntryPoint v0.7
   authKeyHex?: string;        // HKDF auth key for relay server Authorization header
@@ -151,8 +151,10 @@ function getChainFromId(chainId: number): Chain {
       return gnosis;
     case 10200:
       return gnosisChiado;
+    case 84532:
+      return baseSepolia;
     default:
-      return gnosisChiado;
+      return gnosis;
   }
 }
 
@@ -187,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);
@@ -279,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
 // ---------------------------------------------------------------------------
@@ -297,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)
@@ -311,7 +412,7 @@ export function isSubgraphMode(): boolean {
  * This is the on-chain owner identity used in the subgraph.
  */
 export async function deriveSmartAccountAddress(mnemonic: string, chainId?: number): Promise<string> {
-  const chain: Chain = (chainId ?? 100) === 100 ? gnosis : gnosisChiado;
+  const chain: Chain = getChainFromId(chainId ?? 100);
   const ownerAccount = mnemonicToAccount(mnemonic);
   const entryPointAddr = (process.env.TOTALRECLAW_ENTRYPOINT_ADDRESS || DEFAULT_ENTRYPOINT_ADDRESS) as Address;
   const rpcUrl = process.env.TOTALRECLAW_RPC_URL;
@@ -336,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,