@totalreclaw/totalreclaw 1.4.0 → 1.6.0

package/import-adapters/types.ts

@@ -19,7 +19,7 @@ export interface NormalizedFact {
   tags?: string[];
 }
 
-export type ImportSource = 'mem0' | 'mcp-memory' | 'memoclaw' | 'generic-json' | 'generic-csv';
+export type ImportSource = 'mem0' | 'mcp-memory' | 'chatgpt' | 'claude' | 'memoclaw' | 'generic-json' | 'generic-csv';
 
 /**
  * What the user passes to the import tool.
@@ -73,15 +73,38 @@ export interface ImportResult {
 export type ProgressCallback = (progress: {
   current: number;
   total: number;
-  phase: 'fetching' | 'parsing' | 'storing';
+  phase: 'fetching' | 'parsing' | 'storing' | 'extracting';
   message: string;
 }) => void;
 
+/**
+ * A chunk of conversation messages for LLM-based fact extraction.
+ * Adapters that parse conversation data (ChatGPT, Claude) return these
+ * instead of pre-extracted facts, delegating extraction to the LLM.
+ */
+export interface ConversationChunk {
+  /** Human-readable title for progress reporting */
+  title: string;
+  /** Ordered messages in this chunk */
+  messages: Array<{ role: 'user' | 'assistant'; text: string }>;
+  /** Original timestamp (ISO 8601) if available */
+  timestamp?: string;
+}
+
 /**
  * Adapter parse result — returned by each adapter's parse method.
+ *
+ * Adapters return EITHER `facts` (pre-structured sources like Mem0, MCP Memory)
+ * OR `chunks` (conversation-based sources like ChatGPT, Claude) that need
+ * LLM extraction. The caller checks which field is populated.
  */
 export interface AdapterParseResult {
+  /** Pre-structured facts (Mem0, MCP Memory adapters) */
   facts: NormalizedFact[];
+  /** Conversation chunks needing LLM extraction (ChatGPT, Claude adapters) */
+  chunks: ConversationChunk[];
+  /** Total message count across all chunks */
+  totalMessages: number;
   warnings: string[];
   errors: string[];
   /** Metadata about the source (for logging) */

package/index.ts

@@ -10,6 +10,7 @@
  *   - 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
+ *   - totalreclaw_migrate      -- migrate testnet memories to mainnet after Pro upgrade
  *
  * Also registers a `before_agent_start` hook that automatically injects
  * relevant memories into the agent's context.
@@ -331,6 +332,9 @@ async function getFactCount(logger: OpenClawPluginApi['logger']): Promise<number
 /** True when recovery phrase is missing — tools return setup instructions. */
 let needsSetup = false;
 
+/** True on first before_agent_start after successful init — show welcome message once. */
+let firstRunAfterInit = true;
+
 /**
  * Derive keys from the recovery phrase, load or create credentials, and
  * register with the server if this is the first run.
@@ -725,6 +729,138 @@ function decryptFromHex(hexBlob: string, key: Buffer): string {
   return decrypt(b64, key);
 }
 
+// ---------------------------------------------------------------------------
+// Migration GraphQL helpers
+// ---------------------------------------------------------------------------
+
+interface MigrationFact {
+  id: string;
+  owner: string;
+  encryptedBlob: string;
+  encryptedEmbedding: string | null;
+  decayScore: string;
+  isActive: boolean;
+  contentFp: string;
+  source: string;
+  agentId: string;
+  version: number;
+  timestamp: string;
+}
+
+const MIGRATION_PAGE_SIZE = 1000;
+
+/** Execute a GraphQL query against a subgraph endpoint. Returns null on error. */
+async function migrationGqlQuery<T>(
+  endpoint: string,
+  query: string,
+  variables: Record<string, unknown>,
+  authKey?: string,
+): Promise<T | null> {
+  try {
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+      'X-TotalReclaw-Client': 'openclaw-plugin',
+    };
+    if (authKey) headers['Authorization'] = `Bearer ${authKey}`;
+    const response = await fetch(endpoint, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify({ query, variables }),
+    });
+    if (!response.ok) return null;
+    const json = await response.json() as { data?: T; errors?: unknown[] };
+    return json.data ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/** Fetch all active facts by owner from a subgraph, paginated. */
+async function fetchAllFactsByOwner(
+  subgraphUrl: string,
+  owner: string,
+  authKey: string,
+): Promise<MigrationFact[]> {
+  const allFacts: MigrationFact[] = [];
+  let lastId = '';
+
+  while (true) {
+    const hasLastId = lastId !== '';
+    const query = hasLastId
+      ? `query($owner:Bytes!,$first:Int!,$lastId:String!){facts(where:{owner:$owner,isActive:true,id_gt:$lastId},first:$first,orderBy:id,orderDirection:asc){id owner encryptedBlob encryptedEmbedding decayScore isActive contentFp source agentId version timestamp}}`
+      : `query($owner:Bytes!,$first:Int!){facts(where:{owner:$owner,isActive:true},first:$first,orderBy:id,orderDirection:asc){id owner encryptedBlob encryptedEmbedding decayScore isActive contentFp source agentId version timestamp}}`;
+    const vars: Record<string, unknown> = hasLastId
+      ? { owner, first: MIGRATION_PAGE_SIZE, lastId }
+      : { owner, first: MIGRATION_PAGE_SIZE };
+
+    const data = await migrationGqlQuery<{ facts?: MigrationFact[] }>(subgraphUrl, query, vars, authKey);
+    const facts = data?.facts ?? [];
+    if (facts.length === 0) break;
+    allFacts.push(...facts);
+    if (facts.length < MIGRATION_PAGE_SIZE) break;
+    lastId = facts[facts.length - 1].id;
+  }
+
+  return allFacts;
+}
+
+/** Fetch content fingerprints from a subgraph for idempotency. */
+async function fetchContentFingerprintsByOwner(
+  subgraphUrl: string,
+  owner: string,
+  authKey: string,
+): Promise<Set<string>> {
+  const fps = new Set<string>();
+  let lastId = '';
+
+  while (true) {
+    const hasLastId = lastId !== '';
+    const query = hasLastId
+      ? `query($owner:Bytes!,$first:Int!,$lastId:String!){facts(where:{owner:$owner,isActive:true,id_gt:$lastId},first:$first,orderBy:id,orderDirection:asc){id contentFp}}`
+      : `query($owner:Bytes!,$first:Int!){facts(where:{owner:$owner,isActive:true},first:$first,orderBy:id,orderDirection:asc){id contentFp}}`;
+    const vars: Record<string, unknown> = hasLastId
+      ? { owner, first: MIGRATION_PAGE_SIZE, lastId }
+      : { owner, first: MIGRATION_PAGE_SIZE };
+
+    const data = await migrationGqlQuery<{ facts?: Array<{ id: string; contentFp: string }> }>(subgraphUrl, query, vars, authKey);
+    const facts = data?.facts ?? [];
+    if (facts.length === 0) break;
+    for (const f of facts) {
+      if (f.contentFp) fps.add(f.contentFp);
+    }
+    if (facts.length < MIGRATION_PAGE_SIZE) break;
+    lastId = facts[facts.length - 1].id;
+  }
+
+  return fps;
+}
+
+/** Fetch blind index hashes for given fact IDs. */
+async function fetchBlindIndicesByFactIds(
+  subgraphUrl: string,
+  factIds: string[],
+  authKey: string,
+): Promise<Map<string, string[]>> {
+  const result = new Map<string, string[]>();
+  const CHUNK = 50;
+
+  for (let i = 0; i < factIds.length; i += CHUNK) {
+    const chunk = factIds.slice(i, i + CHUNK);
+    const query = `query($factIds:[String!]!,$first:Int!){blindIndexes(where:{fact_in:$factIds},first:$first){hash fact{id}}}`;
+    const data = await migrationGqlQuery<{
+      blindIndexes?: Array<{ hash: string; fact: { id: string } }>;
+    }>(subgraphUrl, query, { factIds: chunk, first: 1000 }, authKey);
+
+    for (const entry of data?.blindIndexes ?? []) {
+      const existing = result.get(entry.fact.id) || [];
+      existing.push(entry.hash);
+      result.set(entry.fact.id, existing);
+    }
+  }
+
+  return result;
+}
+
 /**
  * Fetch existing memories from the vault to provide dedup context for extraction.
  * Returns a lightweight list of {id, text} pairs for the LLM prompt.
@@ -1154,7 +1290,12 @@ async function storeExtractedFacts(
 /**
  * Handle import_from tool calls in the plugin context.
  *
- * Uses the shared adapters to parse, then stores via storeExtractedFacts().
+ * Two paths:
+ * 1. Pre-structured sources (Mem0, MCP Memory) — adapter returns facts directly,
+ *    stored via storeExtractedFacts().
+ * 2. Conversation-based sources (ChatGPT, Claude) — adapter returns conversation
+ *    chunks, each chunk is passed through extractFacts() (the same LLM extraction
+ *    pipeline used for auto-extraction), then stored via storeExtractedFacts().
  */
 async function handlePluginImportFrom(
   params: Record<string, unknown>,
@@ -1163,7 +1304,7 @@ async function handlePluginImportFrom(
   const startTime = Date.now();
 
   const source = params.source as string;
-  const validSources = ['mem0', 'mcp-memory', 'memoclaw', 'generic-json', 'generic-csv'];
+  const validSources = ['mem0', 'mcp-memory', 'chatgpt', 'claude', 'memoclaw', 'generic-json', 'generic-csv'];
 
   if (!source || !validSources.includes(source)) {
     return { success: false, error: `Invalid source. Must be one of: ${validSources.join(', ')}` };
@@ -1181,7 +1322,10 @@ async function handlePluginImportFrom(
       file_path: params.file_path as string | undefined,
     });
 
-    if (parseResult.errors.length > 0 && parseResult.facts.length === 0) {
+    const hasChunks = parseResult.chunks && parseResult.chunks.length > 0;
+    const hasFacts = parseResult.facts && parseResult.facts.length > 0;
+
+    if (parseResult.errors.length > 0 && !hasFacts && !hasChunks) {
       return {
         success: false,
         error: `Failed to parse ${adapter.displayName} data`,
@@ -1189,7 +1333,24 @@ async function handlePluginImportFrom(
       };
     }
 
+    // Dry run: report what was parsed (chunks or facts)
     if (params.dry_run) {
+      if (hasChunks) {
+        return {
+          success: true,
+          dry_run: true,
+          source,
+          total_chunks: parseResult.chunks.length,
+          total_messages: parseResult.totalMessages,
+          preview: parseResult.chunks.slice(0, 5).map((c) => ({
+            title: c.title,
+            messages: c.messages.length,
+            first_message: c.messages[0]?.text.slice(0, 100),
+          })),
+          note: 'Chunks will be processed through LLM extraction (same quality as auto-extraction).',
+          warnings: parseResult.warnings,
+        };
+      }
       return {
         success: true,
         dry_run: true,
@@ -1204,7 +1365,12 @@ async function handlePluginImportFrom(
       };
     }
 
-    // Convert NormalizedFact[] to ExtractedFact[] for storeExtractedFacts()
+    // ── Path 1: Conversation chunks (ChatGPT, Claude) — LLM extraction ──
+    if (hasChunks) {
+      return handleChunkImport(parseResult.chunks, parseResult.totalMessages, source, logger, startTime, parseResult.warnings);
+    }
+
+    // ── Path 2: Pre-structured facts (Mem0, MCP Memory) — direct store ──
     const extractedFacts: ExtractedFact[] = parseResult.facts.map((f) => ({
       text: f.text,
       type: f.type,
@@ -1243,6 +1409,77 @@ async function handlePluginImportFrom(
   }
 }
 
+/**
+ * Process conversation chunks through LLM extraction and store results.
+ *
+ * Each chunk is passed to extractFacts() — the same extraction pipeline used
+ * for auto-extraction during live conversations. This ensures import quality
+ * matches conversation extraction quality.
+ */
+async function handleChunkImport(
+  chunks: import('./import-adapters/types.js').ConversationChunk[],
+  totalMessages: number,
+  source: string,
+  logger: OpenClawPluginApi['logger'],
+  startTime: number,
+  warnings: string[],
+): Promise<Record<string, unknown>> {
+  let totalExtracted = 0;
+  let totalStored = 0;
+  let chunksProcessed = 0;
+
+  for (const chunk of chunks) {
+    chunksProcessed++;
+    logger.info(
+      `Import: extracting facts from chunk ${chunksProcessed}/${chunks.length}: "${chunk.title}"`,
+    );
+
+    // Convert chunk messages to the format extractFacts() expects.
+    // extractFacts() takes an array of message-like objects with { role, content }.
+    const messages = chunk.messages.map((m) => ({
+      role: m.role,
+      content: m.text,
+    }));
+
+    // Use 'full' mode to extract ALL valuable memories from the chunk
+    // (not just the last few messages like 'turn' mode does).
+    const facts = await extractFacts(messages, 'full');
+
+    if (facts.length > 0) {
+      totalExtracted += facts.length;
+
+      // Store through the normal pipeline (dedup, encrypt, store)
+      const stored = await storeExtractedFacts(facts, logger);
+      totalStored += stored;
+
+      logger.info(
+        `Import chunk ${chunksProcessed}/${chunks.length}: extracted ${facts.length} facts, stored ${stored}`,
+      );
+    }
+  }
+
+  if (totalExtracted === 0 && chunks.length > 0) {
+    warnings.push(
+      `Processed ${chunks.length} conversation chunks (${totalMessages} messages) but the LLM ` +
+      `did not extract any facts worth storing. This can happen if the conversations are mostly ` +
+      `generic/ephemeral content without personal facts, preferences, or decisions.`,
+    );
+  }
+
+  return {
+    success: totalStored > 0 || totalExtracted > 0,
+    source,
+    import_id: crypto.randomUUID(),
+    total_chunks: chunks.length,
+    total_messages: totalMessages,
+    facts_extracted: totalExtracted,
+    imported: totalStored,
+    skipped: totalExtracted - totalStored,
+    warnings,
+    duration_ms: Date.now() - startTime,
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Plugin definition
 // ---------------------------------------------------------------------------
@@ -2175,16 +2412,16 @@ const plugin = {
         name: 'totalreclaw_import_from',
         label: 'Import From',
         description:
-          'Import memories from other AI memory tools (Mem0, MCP Memory Server, MemoClaw, or generic JSON/CSV). ' +
-          'Provide the source name and either an API key or file content. ' +
+          'Import memories from other AI memory tools (Mem0, MCP Memory Server, ChatGPT, Claude, MemoClaw, or generic JSON/CSV). ' +
+          'Provide the source name and either an API key, file content, or file path. ' +
           'Use dry_run=true to preview before importing. Idempotent — safe to run multiple times.',
         parameters: {
           type: 'object',
           properties: {
             source: {
               type: 'string',
-              enum: ['mem0', 'mcp-memory', 'memoclaw', 'generic-json', 'generic-csv'],
-              description: 'The source system to import from',
+              enum: ['mem0', 'mcp-memory', 'chatgpt', 'claude', 'memoclaw', 'generic-json', 'generic-csv'],
+              description: 'The source system to import from (chatgpt: conversations.json or memory text; claude: memory text)',
             },
             api_key: {
               type: 'string',
@@ -2305,6 +2542,189 @@ const plugin = {
       { name: 'totalreclaw_upgrade' },
     );
 
+    // ---------------------------------------------------------------
+    // Tool: totalreclaw_migrate
+    // ---------------------------------------------------------------
+
+    api.registerTool(
+      {
+        name: 'totalreclaw_migrate',
+        label: 'Migrate Testnet to Mainnet',
+        description:
+          'Migrate memories from testnet (Base Sepolia) to mainnet (Gnosis) after upgrading to Pro. ' +
+          'Dry-run by default — set confirm=true to execute. Idempotent: re-running skips already-migrated facts.',
+        parameters: {
+          type: 'object',
+          properties: {
+            confirm: {
+              type: 'boolean',
+              description: 'Set to true to execute the migration. Without it, returns a dry-run preview.',
+              default: false,
+            },
+          },
+          additionalProperties: false,
+        },
+        async execute(_params: { confirm?: boolean }) {
+          try {
+            await requireFullSetup(api.logger);
+
+            if (!authKeyHex || !subgraphOwner) {
+              return {
+                content: [{ type: 'text', text: 'Plugin not fully initialized. Ensure TOTALRECLAW_RECOVERY_PHRASE is set.' }],
+              };
+            }
+
+            if (!isSubgraphMode()) {
+              return {
+                content: [{ type: 'text', text: 'Migration is only available with the managed service (subgraph mode).' }],
+              };
+            }
+
+            const confirm = _params?.confirm === true;
+            const serverUrl = (process.env.TOTALRECLAW_SERVER_URL || 'https://api.totalreclaw.xyz').replace(/\/+$/, '');
+
+            // 1. Check billing tier
+            const billingResp = await fetch(
+              `${serverUrl}/v1/billing/status?wallet_address=${encodeURIComponent(subgraphOwner)}`,
+              {
+                method: 'GET',
+                headers: {
+                  'Authorization': `Bearer ${authKeyHex}`,
+                  'Content-Type': 'application/json',
+                  'X-TotalReclaw-Client': 'openclaw-plugin',
+                },
+              },
+            );
+            if (!billingResp.ok) {
+              return { content: [{ type: 'text', text: `Failed to check billing tier (HTTP ${billingResp.status}).` }] };
+            }
+            const billingData = await billingResp.json() as { tier: string };
+            if (billingData.tier !== 'pro') {
+              return {
+                content: [{ type: 'text', text: 'Migration requires Pro tier. Use totalreclaw_upgrade to upgrade first.' }],
+              };
+            }
+
+            // 2. Fetch testnet facts via relay (chain=testnet query param)
+            const testnetSubgraphUrl = `${serverUrl}/v1/subgraph?chain=testnet`;
+            const mainnetSubgraphUrl = `${serverUrl}/v1/subgraph`;
+
+            api.logger.info('Fetching testnet facts...');
+            const testnetFacts = await fetchAllFactsByOwner(testnetSubgraphUrl, subgraphOwner, authKeyHex);
+
+            if (testnetFacts.length === 0) {
+              return {
+                content: [{ type: 'text', text: 'No facts found on testnet. Nothing to migrate.' }],
+              };
+            }
+
+            // 3. Check mainnet for existing facts (idempotency)
+            api.logger.info('Checking mainnet for existing facts...');
+            const mainnetFps = await fetchContentFingerprintsByOwner(mainnetSubgraphUrl, subgraphOwner, authKeyHex);
+            const factsToMigrate = testnetFacts.filter(f => !f.contentFp || !mainnetFps.has(f.contentFp));
+            const alreadyOnMainnet = testnetFacts.length - factsToMigrate.length;
+
+            // 4. Dry-run
+            if (!confirm) {
+              const msg = factsToMigrate.length === 0
+                ? `All ${testnetFacts.length} testnet facts already exist on mainnet. Nothing to migrate.`
+                : `Found ${factsToMigrate.length} facts to migrate from testnet to Gnosis mainnet (${alreadyOnMainnet} already on mainnet). Call with confirm=true to proceed.`;
+              return {
+                content: [{ type: 'text', text: msg }],
+                details: {
+                  mode: 'dry_run',
+                  testnet_facts: testnetFacts.length,
+                  already_on_mainnet: alreadyOnMainnet,
+                  to_migrate: factsToMigrate.length,
+                },
+              };
+            }
+
+            // 5. Execute migration
+            if (factsToMigrate.length === 0) {
+              return {
+                content: [{ type: 'text', text: `All ${testnetFacts.length} testnet facts already exist on mainnet. Nothing to migrate.` }],
+              };
+            }
+
+            // Fetch blind indices
+            api.logger.info(`Fetching blind indices for ${factsToMigrate.length} facts...`);
+            const factIds = factsToMigrate.map(f => f.id);
+            const blindIndicesMap = await fetchBlindIndicesByFactIds(testnetSubgraphUrl, factIds, authKeyHex);
+
+            // Build protobuf payloads
+            const payloads: Buffer[] = [];
+            for (const fact of factsToMigrate) {
+              const blobHex = fact.encryptedBlob.startsWith('0x') ? fact.encryptedBlob.slice(2) : fact.encryptedBlob;
+              const indices = blindIndicesMap.get(fact.id) || [];
+              const factPayload: FactPayload = {
+                id: fact.id,
+                timestamp: new Date().toISOString(),
+                owner: subgraphOwner,
+                encryptedBlob: blobHex,
+                blindIndices: indices,
+                decayScore: parseFloat(fact.decayScore) || 0.5,
+                source: fact.source || 'migration',
+                contentFp: fact.contentFp || '',
+                agentId: fact.agentId || 'openclaw-plugin',
+                encryptedEmbedding: fact.encryptedEmbedding || undefined,
+              };
+              payloads.push(encodeFactProtobuf(factPayload));
+            }
+
+            // Batch submit (15 per UserOp)
+            const BATCH_SIZE = 15;
+            const batchConfig = { ...getSubgraphConfig(), authKeyHex: authKeyHex!, walletAddress: subgraphOwner ?? undefined };
+            let migrated = 0;
+            let failedBatches = 0;
+
+            for (let i = 0; i < payloads.length; i += BATCH_SIZE) {
+              const batch = payloads.slice(i, i + BATCH_SIZE);
+              const batchNum = Math.floor(i / BATCH_SIZE) + 1;
+              const totalBatches = Math.ceil(payloads.length / BATCH_SIZE);
+              api.logger.info(`Migrating batch ${batchNum}/${totalBatches} (${batch.length} facts)...`);
+
+              try {
+                const result = await submitFactBatchOnChain(batch, batchConfig);
+                if (result.success) {
+                  migrated += batch.length;
+                } else {
+                  failedBatches++;
+                }
+              } catch (err: unknown) {
+                const msg = err instanceof Error ? err.message : String(err);
+                api.logger.error(`Migration batch ${batchNum} failed: ${msg}`);
+                failedBatches++;
+              }
+            }
+
+            const resultMsg = failedBatches === 0
+              ? `Successfully migrated ${migrated} memories from testnet to Gnosis mainnet.`
+              : `Migrated ${migrated}/${factsToMigrate.length} memories. ${failedBatches} batch(es) failed — re-run to retry (idempotent).`;
+
+            return {
+              content: [{ type: 'text', text: resultMsg }],
+              details: {
+                mode: 'executed',
+                testnet_facts: testnetFacts.length,
+                already_on_mainnet: alreadyOnMainnet,
+                to_migrate: factsToMigrate.length,
+                migrated,
+                failed_batches: failedBatches,
+              },
+            };
+          } catch (err: unknown) {
+            const message = err instanceof Error ? err.message : String(err);
+            api.logger.error(`totalreclaw_migrate failed: ${message}`);
+            return {
+              content: [{ type: 'text', text: `Migration failed: ${message}` }],
+            };
+          }
+        },
+      },
+      { name: 'totalreclaw_migrate' },
+    );
+
     // ---------------------------------------------------------------
     // Hook: before_agent_start
     // ---------------------------------------------------------------
@@ -2325,21 +2745,36 @@ const plugin = {
 
           await ensureInitialized(api.logger);
 
-          // If setup is still needed after init, inject setup instructions
+          // If setup is still needed after init, inject guided onboarding
           if (needsSetup) {
             return {
               prependContext:
-                '## TotalReclaw Setup Required\n\n' +
-                'TotalReclaw is installed but needs configuration. Follow the "Post-Install Setup" steps in SKILL.md to complete setup.\n' +
-                'Ask the user: "Do you have an existing TotalReclaw recovery phrase, or should I generate a new one?"',
+                '## TotalReclaw — First-Time Setup\n\n' +
+                'TotalReclaw is an end-to-end encrypted memory vault. It remembers things across conversations — preferences, decisions, project context — all encrypted so no one (not even the server) can read your memories.\n\n' +
+                '**To get started, ask the user:** "Do you have an existing TotalReclaw recovery phrase you\'d like to restore, or should I generate a new one?"\n\n' +
+                '**If new user:** Generate a random 12-word BIP-39 mnemonic and set it as the TOTALRECLAW_RECOVERY_PHRASE environment variable. Display it prominently and warn:\n' +
+                '- "This is your ONLY way to access your memories. Write it down and store it securely."\n' +
+                '- "NEVER use a recovery phrase from an existing crypto wallet — keep this separate from any wallet that holds funds."\n' +
+                '- "If you lose this phrase, your memories are gone forever — there is no recovery."\n\n' +
+                '**If returning user:** Ask them to provide their 12-word phrase, validate it, and set it as TOTALRECLAW_RECOVERY_PHRASE.\n\n' +
+                '**After setup:** Explain that from now on, you will automatically remember important things from conversations and recall relevant memories at the start of each session. The user can also explicitly ask you to remember, recall, forget, or export memories.',
             };
           }
 
-          // One-time welcome-back message for returning Pro users.
+          // One-time welcome message (first conversation after setup or returning user)
           let welcomeBack = '';
           if (welcomeBackMessage) {
             welcomeBack = `\n\n${welcomeBackMessage}`;
             welcomeBackMessage = null; // Consume — only show once
+          } else if (firstRunAfterInit) {
+            // First conversation with a configured user — explain what's happening
+            firstRunAfterInit = false;
+            const cache = readBillingCache();
+            const tier = cache?.tier || 'free';
+            const tierInfo = tier === 'pro'
+              ? 'You are on the **Pro** tier — unlimited memories, permanently stored on Gnosis mainnet.'
+              : 'You are on the **Free** tier — memories stored on testnet. Use the totalreclaw_upgrade tool to upgrade to Pro for permanent on-chain storage.';
+            welcomeBack = `\n\nTotalReclaw is active. I will automatically remember important things from our conversations and recall relevant context at the start of each session. ${tierInfo}`;
           }
 
           // Billing cache check — warn if quota is approaching limit.

package/package.json

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