@totalreclaw/totalreclaw 1.5.0 → 3.0.6

package/index.ts

@@ -8,14 +8,17 @@
  *   - totalreclaw_export       -- export all memories (JSON or Markdown)
  *   - totalreclaw_status       -- check billing/subscription status
  *   - totalreclaw_consolidate  -- scan and merge near-duplicate memories
+ *   - totalreclaw_pin          -- pin a memory so auto-resolution can never supersede it
+ *   - totalreclaw_unpin        -- remove a pin, returning the memory to active status
  *   - 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
+ *   - totalreclaw_setup        -- initialize with recovery phrase (no gateway restart needed)
  *
  * Also registers a `before_agent_start` hook that automatically injects
  * relevant memories into the agent's context.
  *
- * All data is encrypted client-side with AES-256-GCM. The server never
+ * All data is encrypted client-side with XChaCha20-Poly1305. The server never
  * sees plaintext.
  */
 
@@ -29,8 +32,24 @@ import {
   generateContentFingerprint,
 } from './crypto.js';
 import { createApiClient, type StoreFactPayload } from './api-client.js';
-import { extractFacts, type ExtractedFact } from './extractor.js';
-import { initLLMClient, generateEmbedding, getEmbeddingDims } from './llm-client.js';
+import {
+  extractFacts,
+  extractDebrief,
+  isValidMemoryType,
+  parseEntity,
+  VALID_MEMORY_TYPES,
+  LEGACY_V0_MEMORY_TYPES,
+  VALID_MEMORY_SOURCES,
+  VALID_MEMORY_SCOPES,
+  EXTRACTION_SYSTEM_PROMPT,
+  extractFactsForCompaction,
+  type ExtractedFact,
+  type ExtractedEntity,
+  type MemoryType,
+  type MemorySource,
+  type MemoryScope,
+} from './extractor.js';
+import { initLLMClient, resolveLLMConfig, chatCompletion, generateEmbedding, getEmbeddingDims } from './llm-client.js';
 import { LSHHasher } from './lsh.js';
 import { rerank, cosineSimilarity, detectQueryIntent, INTENT_WEIGHTS, type RerankerCandidate } from './reranker.js';
 import { deduplicateBatch } from './semantic-dedup.js';
@@ -43,9 +62,39 @@ import {
   STORE_DEDUP_MAX_CANDIDATES,
   type DecryptedCandidate,
 } from './consolidation.js';
-import { isSubgraphMode, getSubgraphConfig, encodeFactProtobuf, submitFactOnChain, submitFactBatchOnChain, deriveSmartAccountAddress, type FactPayload } from './subgraph-store.js';
-import { searchSubgraph, getSubgraphFactCount } from './subgraph-search.js';
+import { isSubgraphMode, getSubgraphConfig, encodeFactProtobuf, submitFactOnChain, submitFactBatchOnChain, deriveSmartAccountAddress, PROTOBUF_VERSION_V4, type FactPayload } from './subgraph-store.js';
+import {
+  DIGEST_TRAPDOOR,
+  buildCanonicalClaim,
+  computeEntityTrapdoor,
+  computeEntityTrapdoors,
+  isDigestBlob,
+  normalizeToV1Type,
+  readClaimFromBlob,
+  resolveDigestMode,
+  type DigestMode,
+} from './claims-helper.js';
+import {
+  maybeInjectDigest,
+  recompileDigest,
+  fetchAllActiveClaims,
+  isRecompileInProgress,
+  tryBeginRecompile,
+  endRecompile,
+} from './digest-sync.js';
+import {
+  detectAndResolveContradictions,
+  runWeightTuningLoop,
+  type ResolutionDecision as ContradictionDecision,
+} from './contradiction-sync.js';
+import { searchSubgraph, searchSubgraphBroadened, getSubgraphFactCount, fetchFactById } from './subgraph-search.js';
+import {
+  executePinOperation,
+  validatePinArgs,
+  type PinOpDeps,
+} from './pin.js';
 import { PluginHotCache, type HotFact } from './hot-cache-wrapper.js';
+import { CONFIG, setRecoveryPhraseOverride, setChainIdOverride } from './config.js';
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
@@ -68,6 +117,16 @@ interface OpenClawPluginApi {
         };
       };
     };
+    models?: {
+      providers?: Record<string, {
+        baseUrl: string;
+        apiKey?: string;
+        api?: string;
+        models?: Array<{ id: string; [k: string]: unknown }>;
+        [k: string]: unknown;
+      }>;
+      [k: string]: unknown;
+    };
     [key: string]: unknown;
   };
   pluginConfig?: Record<string, unknown>;
@@ -76,12 +135,44 @@ interface OpenClawPluginApi {
   on(hookName: string, handler: (...args: unknown[]) => unknown, opts?: { priority?: number }): void;
 }
 
+// ---------------------------------------------------------------------------
+// Human-friendly error messages
+// ---------------------------------------------------------------------------
+
+/**
+ * Translate technical error messages from the on-chain submission pipeline
+ * into user-friendly messages. The original technical details are still
+ * logged via api.logger — this only affects what the agent sees.
+ */
+function humanizeError(rawMessage: string): string {
+  if (rawMessage.includes('AA23')) {
+    return 'Memory storage temporarily unavailable. Will retry next time.';
+  }
+  if (rawMessage.includes('AA10')) {
+    return 'Please wait a moment before storing more memories.';
+  }
+  if (rawMessage.includes('AA25')) {
+    return 'Memory storage busy. Will retry.';
+  }
+  if (rawMessage.includes('pm_sponsorUserOperation')) {
+    return 'Memory storage service temporarily unavailable.';
+  }
+  if (/Relay returned HTTP\s*404/.test(rawMessage)) {
+    return 'Memory service is temporarily offline.';
+  }
+  if (/Relay returned HTTP\s*5\d\d/.test(rawMessage)) {
+    return 'Memory service encountered a temporary error. Will retry next time.';
+  }
+  // Pass through non-technical messages as-is.
+  return rawMessage;
+}
+
 // ---------------------------------------------------------------------------
 // Persistent credential storage
 // ---------------------------------------------------------------------------
 
 /** Path where we persist userId + salt across restarts. */
-const CREDENTIALS_PATH = process.env.TOTALRECLAW_CREDENTIALS_PATH || `${process.env.HOME ?? '/home/node'}/.totalreclaw/credentials.json`;
+const CREDENTIALS_PATH = CONFIG.credentialsPath;
 
 // ---------------------------------------------------------------------------
 // Cosine similarity threshold — skip injection when top result is below this
@@ -92,12 +183,10 @@ const CREDENTIALS_PATH = process.env.TOTALRECLAW_CREDENTIALS_PATH || `${process.
  * memories into context. Below this threshold, the query is considered
  * irrelevant to any stored memories and results are suppressed.
  *
- * Default 0.15 is tuned for bge-small-en-v1.5 which produces lower
+ * Default 0.15 is tuned for local ONNX models which produce lower
  * similarity scores than OpenAI models. Configurable via env var.
  */
-const COSINE_THRESHOLD = parseFloat(
-  process.env.TOTALRECLAW_COSINE_THRESHOLD ?? '0.15',
-);
+const COSINE_THRESHOLD = CONFIG.cosineThreshold;
 
 // ---------------------------------------------------------------------------
 // Module-level state (persists across tool calls within a session)
@@ -123,30 +212,36 @@ let lastSearchTimestamp = 0;
 let lastQueryEmbedding: number[] | null = null;
 
 // Feature flags — configurable for A/B testing
-const CACHE_TTL_MS = parseInt(process.env.TOTALRECLAW_CACHE_TTL_MS ?? String(5 * 60 * 1000), 10);
-const SEMANTIC_SKIP_THRESHOLD = parseFloat(process.env.TOTALRECLAW_SEMANTIC_SKIP_THRESHOLD ?? '0.85');
+const CACHE_TTL_MS = CONFIG.cacheTtlMs;
+const SEMANTIC_SKIP_THRESHOLD = CONFIG.semanticSkipThreshold;
 
 // 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 ?? '3', 10);
+
+// BUG-2 fix: Skip agent_end extraction during import operations.
+// Import failures previously triggered agent_end → re-extraction → re-import loops.
+let _importInProgress = false;
+const AUTO_EXTRACT_EVERY_TURNS_ENV = CONFIG.extractInterval;
 
 // 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';
+// Store-time near-duplicate detection is always ON in v1.
+// The TOTALRECLAW_STORE_DEDUP env var was removed.
+const STORE_DEDUP_ENABLED = true;
 
 // 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');
+// B2: COSINE_THRESHOLD (above) is the single relevance gate for both
+// the before_agent_start hook and the recall tool.  The former "RELEVANCE_THRESHOLD"
+// (0.3) was too aggressive and silently suppressed auto-recall at session start.
 
 // ---------------------------------------------------------------------------
 // Billing cache infrastructure
 // ---------------------------------------------------------------------------
 
-const BILLING_CACHE_PATH = path.join(process.env.HOME ?? '/home/node', '.totalreclaw', 'billing-cache.json');
+const BILLING_CACHE_PATH = CONFIG.billingCachePath;
 const BILLING_CACHE_TTL = 2 * 60 * 60 * 1000; // 2 hours
 const QUOTA_WARNING_THRESHOLD = 0.8; // 80%
 
@@ -165,11 +260,34 @@ interface BillingCache {
   checked_at: number;
 }
 
+/**
+ * Apply the billing tier to the runtime chain override.
+ *
+ * Pro tier → chain 100 (Gnosis mainnet). Free tier (or unknown) stays on
+ * 84532 (Base Sepolia). The relay routes Pro UserOps to Gnosis, so the
+ * client MUST sign them against chain 100 — otherwise the bundler returns
+ * AA23 (invalid signature). See MCP's equivalent path in mcp/src/index.ts.
+ *
+ * Called from `readBillingCache` and `writeBillingCache` so that every cache
+ * read or write keeps the chain override in sync with the cached tier.
+ * Idempotent — calling with the same tier is a no-op.
+ */
+function syncChainIdFromTier(tier: string | undefined): void {
+  if (tier === 'pro') {
+    setChainIdOverride(100);
+  } else {
+    // Free or unknown → reset to the default free-tier chain.
+    setChainIdOverride(84532);
+  }
+}
+
 function readBillingCache(): BillingCache | null {
   try {
     if (!fs.existsSync(BILLING_CACHE_PATH)) return null;
     const raw = JSON.parse(fs.readFileSync(BILLING_CACHE_PATH, 'utf-8')) as BillingCache;
     if (!raw.checked_at || Date.now() - raw.checked_at > BILLING_CACHE_TTL) return null;
+    // Keep chain override in sync with persisted tier across process restarts.
+    syncChainIdFromTier(raw.tier);
     return raw;
   } catch {
     return null;
@@ -184,18 +302,22 @@ function writeBillingCache(cache: BillingCache): void {
   } catch {
     // Best-effort — don't block on cache write failure.
   }
+  // Sync chain override AFTER the write so in-process UserOp signing picks
+  // up the correct chain immediately, even if the disk write failed.
+  syncChainIdFromTier(cache.tier);
 }
 
 /**
- * Check if LLM-guided dedup is enabled for the current tier.
- * Returns true for Pro users, or when no billing cache exists (fail-open for self-hosters).
+ * Check if LLM-guided dedup is enabled.
+ *
+ * Always returns true — LLM extraction runs client-side using the user's
+ * own API key, so there is no cost to us. The server flag is respected as
+ * a kill-switch but defaults to true for all tiers.
  */
 function isLlmDedupEnabled(): boolean {
   const cache = readBillingCache();
-  if (!cache) return true;
-  if (cache.tier === 'pro') return true;
-  if (cache.features?.llm_dedup !== undefined) return cache.features.llm_dedup;
-  return false;
+  if (cache?.features?.llm_dedup === false) return false; // Server kill-switch
+  return true;
 }
 
 /**
@@ -241,7 +363,7 @@ const MEMORY_HEADER = `# Memory
 
 function ensureMemoryHeader(logger: OpenClawPluginApi['logger']): void {
   try {
-    const workspace = path.join(process.env.HOME ?? '/home/node', '.openclaw', 'workspace');
+    const workspace = CONFIG.openclawWorkspace;
     const memoryMd = path.join(workspace, 'MEMORY.md');
 
     if (fs.existsSync(memoryMd)) {
@@ -332,14 +454,16 @@ 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.
  */
 async function initialize(logger: OpenClawPluginApi['logger']): Promise<void> {
-  const serverUrl =
-    process.env.TOTALRECLAW_SERVER_URL || 'https://api.totalreclaw.xyz';
-  const masterPassword = process.env.TOTALRECLAW_RECOVERY_PHRASE;
+  const serverUrl = CONFIG.serverUrl || 'https://api.totalreclaw.xyz';
+  const masterPassword = CONFIG.recoveryPhrase;
 
   if (!masterPassword) {
     needsSetup = true;
@@ -356,7 +480,14 @@ async function initialize(logger: OpenClawPluginApi['logger']): Promise<void> {
   try {
     if (fs.existsSync(CREDENTIALS_PATH)) {
       const creds = JSON.parse(fs.readFileSync(CREDENTIALS_PATH, 'utf8'));
-      existingSalt = Buffer.from(creds.salt, 'base64');
+      // Salt may be stored as base64 (plugin-written) or hex (MCP setup-written).
+      // Detect format: hex strings are 64 chars of [0-9a-f], base64 uses [A-Z+/=].
+      const saltStr: string = creds.salt;
+      if (saltStr && /^[0-9a-f]{64}$/i.test(saltStr)) {
+        existingSalt = Buffer.from(saltStr, 'hex');
+      } else if (saltStr) {
+        existingSalt = Buffer.from(saltStr, 'base64');
+      }
       existingUserId = creds.userId;
       logger.info(`Loaded existing credentials for user ${existingUserId}`);
     }
@@ -377,6 +508,20 @@ async function initialize(logger: OpenClawPluginApi['logger']): Promise<void> {
   if (existingUserId) {
     userId = existingUserId;
     logger.info(`Authenticated as user ${userId}`);
+
+    // Idempotent registration — ensure auth key is registered with the relay.
+    // Without this, returning users get 401 if the relay database was reset or
+    // if credentials were created by the MCP setup CLI (different process).
+    try {
+      const authHash = computeAuthKeyHash(keys.authKey);
+      const saltHex = keys.salt.toString('hex');
+      await apiClient.register(authHash, saltHex);
+    } catch {
+      // Best-effort — relay returns 200 for already-registered users.
+      // Only fails on network errors; bearer token auth still works if
+      // a prior registration succeeded.
+      logger.warn('Idempotent relay registration failed (best-effort, will retry on next start)');
+    }
   } else {
     // First run -- register with the server.
     const authHash = computeAuthKeyHash(keys.authKey);
@@ -402,14 +547,20 @@ async function initialize(logger: OpenClawPluginApi['logger']): Promise<void> {
     userId = registeredUserId!;
 
     // Persist credentials so we can resume later.
+    // Include the mnemonic so hot-reload works without env var.
     const dir = path.dirname(CREDENTIALS_PATH);
     if (!fs.existsSync(dir)) {
       fs.mkdirSync(dir, { recursive: true });
     }
-    fs.writeFileSync(
-      CREDENTIALS_PATH,
-      JSON.stringify({ userId, salt: keys.salt.toString('base64') }),
-    );
+    const credsToSave: Record<string, string> = {
+      userId,
+      salt: keys.salt.toString('base64'),
+    };
+    // Only persist mnemonic if we have one (avoid writing empty string).
+    if (masterPassword) {
+      credsToSave.mnemonic = masterPassword;
+    }
+    fs.writeFileSync(CREDENTIALS_PATH, JSON.stringify(credsToSave), { mode: 0o600 });
 
     logger.info(`Registered new user: ${userId}`);
   }
@@ -433,7 +584,7 @@ async function initialize(logger: OpenClawPluginApi['logger']): Promise<void> {
     try {
       const walletAddr = subgraphOwner || userId || '';
       if (walletAddr) {
-        const billingUrl = (process.env.TOTALRECLAW_SERVER_URL || 'https://api.totalreclaw.xyz').replace(/\/+$/, '');
+        const billingUrl = CONFIG.serverUrl;
         const resp = await fetch(`${billingUrl}/v1/billing/status?wallet_address=${encodeURIComponent(walletAddr)}`, {
           method: 'GET',
           headers: {
@@ -476,6 +627,13 @@ function isDocker(): boolean {
 }
 
 function buildSetupErrorMsg(): string {
+  return 'TotalReclaw setup required. Use the `totalreclaw_setup` tool with a 12-word BIP-39 recovery phrase.\n\n' +
+    '1. Ask the user if they have an existing recovery phrase, or generate a new one with `npx @totalreclaw/mcp-server setup`.\n' +
+    '2. Call `totalreclaw_setup` with the phrase — no gateway restart needed.\n' +
+    '   (Optional: set TOTALRECLAW_SELF_HOSTED=true if using your own server instead of the managed service.)';
+}
+
+function buildSetupErrorMsgLegacy(): string {
   const base =
     'TotalReclaw setup required:\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' +
@@ -506,12 +664,101 @@ const SETUP_ERROR_MSG = buildSetupErrorMsg();
 
 /**
  * Ensure `initialize()` has completed (runs at most once).
+ *
+ * If `needsSetup` is true after init, attempts a hot-reload from
+ * credentials.json in case the mnemonic was written there by a
+ * `totalreclaw_setup` tool call or `npx @totalreclaw/mcp-server setup`.
  */
 async function ensureInitialized(logger: OpenClawPluginApi['logger']): Promise<void> {
   if (!initPromise) {
     initPromise = initialize(logger);
   }
   await initPromise;
+
+  // Hot-reload: if setup is still needed, check if credentials.json
+  // now has a mnemonic (written by totalreclaw_setup or MCP setup CLI).
+  if (needsSetup) {
+    await attemptHotReload(logger);
+  }
+}
+
+/**
+ * Attempt to hot-reload credentials from credentials.json.
+ *
+ * Called when `needsSetup` is true — checks if credentials.json contains
+ * a mnemonic (written by the `totalreclaw_setup` tool or MCP setup CLI).
+ * If found, re-derives keys and completes initialization without requiring
+ * a gateway restart.
+ */
+async function attemptHotReload(logger: OpenClawPluginApi['logger']): Promise<void> {
+  try {
+    if (!fs.existsSync(CREDENTIALS_PATH)) return;
+
+    const creds = JSON.parse(fs.readFileSync(CREDENTIALS_PATH, 'utf8'));
+    if (!creds.mnemonic) return;
+
+    logger.info('Hot-reloading credentials from credentials.json (no restart needed)');
+
+    // Set the runtime override so CONFIG.recoveryPhrase returns the mnemonic.
+    setRecoveryPhraseOverride(creds.mnemonic);
+
+    // Re-run initialization with the newly available mnemonic.
+    needsSetup = false;
+    initPromise = initialize(logger);
+    await initPromise;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    logger.warn(`Hot-reload from credentials.json failed: ${msg}`);
+    // Leave needsSetup as true — user will see the setup prompt.
+  }
+}
+
+/**
+ * Force re-initialization with a specific mnemonic.
+ *
+ * Called by the `totalreclaw_setup` tool. Clears stale credentials from
+ * disk so that `initialize()` treats this as a fresh registration and
+ * persists the NEW mnemonic + freshly derived salt/userId.
+ *
+ * Without clearing credentials.json first, `initialize()` would load the
+ * OLD salt and userId, derive keys from (new mnemonic + old salt), skip
+ * writing credentials (because existingUserId is set), and the new
+ * mnemonic would never be persisted — a critical data-loss bug.
+ */
+async function forceReinitialization(mnemonic: string, logger: OpenClawPluginApi['logger']): Promise<void> {
+  // Set the runtime override so CONFIG.recoveryPhrase returns this mnemonic.
+  setRecoveryPhraseOverride(mnemonic);
+
+  // CRITICAL: Remove stale credentials so initialize() does a fresh
+  // registration with a new salt. If we leave the old file, initialize()
+  // loads the old salt + userId and never writes the new mnemonic.
+  try {
+    if (fs.existsSync(CREDENTIALS_PATH)) {
+      fs.unlinkSync(CREDENTIALS_PATH);
+      logger.info('Cleared stale credentials.json for fresh setup');
+    }
+  } catch (err) {
+    logger.warn(`Could not remove old credentials.json: ${err instanceof Error ? err.message : String(err)}`);
+  }
+
+  // Reset module state for a clean re-init.
+  needsSetup = false;
+  authKeyHex = null;
+  encryptionKey = null;
+  dedupKey = null;
+  userId = null;
+  subgraphOwner = null;
+  apiClient = null;
+  lshHasher = null;
+  lshInitFailed = false;
+  masterPasswordCache = null;
+  saltCache = null;
+  pluginHotCache = null;
+  firstRunAfterInit = true;
+
+  // Re-run initialization — will register fresh and persist new credentials.
+  initPromise = initialize(logger);
+  await initPromise;
 }
 
 /**
@@ -631,7 +878,8 @@ async function searchForNearDuplicates(
       for (const result of results) {
         try {
           const docJson = decryptFromHex(result.encryptedBlob, encryptionKey);
-          const doc = JSON.parse(docJson) as { text: string; metadata?: Record<string, unknown> };
+          if (isDigestBlob(docJson)) continue;
+          const doc = readClaimFromBlob(docJson);
 
           let embedding: number[] | null = null;
           if (result.encryptedEmbedding) {
@@ -644,9 +892,7 @@ async function searchForNearDuplicates(
             id: result.id,
             text: doc.text,
             embedding,
-            importance: doc.metadata?.importance
-              ? Math.round((doc.metadata.importance as number) * 10)
-              : 5,
+            importance: doc.importance,
             decayScore: 5,
             createdAt: result.timestamp ? parseInt(result.timestamp, 10) * 1000 : Date.now(),
             version: 1,
@@ -663,7 +909,8 @@ async function searchForNearDuplicates(
       for (const candidate of candidates) {
         try {
           const docJson = decryptFromHex(candidate.encrypted_blob, encryptionKey);
-          const doc = JSON.parse(docJson) as { text: string; metadata?: Record<string, unknown> };
+          if (isDigestBlob(docJson)) continue;
+          const doc = readClaimFromBlob(docJson);
 
           let embedding: number[] | null = null;
           if (candidate.encrypted_embedding) {
@@ -676,9 +923,7 @@ async function searchForNearDuplicates(
             id: candidate.fact_id,
             text: doc.text,
             embedding,
-            importance: doc.metadata?.importance
-              ? Math.round((doc.metadata.importance as number) * 10)
-              : 5,
+            importance: doc.importance,
             decayScore: candidate.decay_score,
             createdAt: typeof candidate.timestamp === 'number'
               ? candidate.timestamp
@@ -717,6 +962,182 @@ function encryptToHex(plaintext: string, key: Buffer): string {
   return Buffer.from(b64, 'base64').toString('hex');
 }
 
+// Plugin v3.0.0 removed the legacy claim-format fallback. Write path
+// always emits Memory Taxonomy v1 JSON blobs. The logClaimFormatOnce
+// helper is gone along with TOTALRECLAW_CLAIM_FORMAT / TOTALRECLAW_TAXONOMY_VERSION.
+
+let _loggedDigestMode = false;
+function logDigestModeOnce(mode: DigestMode, logger: OpenClawPluginApi['logger']): void {
+  if (_loggedDigestMode) return;
+  _loggedDigestMode = true;
+  logger.info(`TotalReclaw: digest injection mode = ${mode}`);
+}
+
+/**
+ * How many active facts to pull into a digest recompilation.
+ * Digest compiler itself will apply DIGEST_CLAIM_CAP for the LLM path.
+ */
+const DIGEST_FETCH_LIMIT = 500;
+
+/**
+ * Schedule a background digest recompile. Fire-and-forget.
+ *
+ * The caller must check `!isRecompileInProgress()` before invoking.
+ * Errors are logged and swallowed; the guard flag is always released.
+ */
+function scheduleDigestRecompile(
+  previousClaimId: string | null,
+  logger: OpenClawPluginApi['logger'],
+): void {
+  if (!isRecompileInProgress()) {
+    if (!tryBeginRecompile()) return;
+  } else {
+    return;
+  }
+
+  const mode = resolveDigestMode();
+  const owner = subgraphOwner || userId;
+  const authKey = authKeyHex;
+  const encKey = encryptionKey;
+  const ownerForBatch = subgraphOwner ?? undefined;
+
+  if (!owner || !authKey || !encKey) {
+    endRecompile();
+    return;
+  }
+
+  // Capture llmFn from the current LLM config (cheap variant of the user's
+  // provider, already resolved by resolveLLMConfig).
+  const llmConfig = resolveLLMConfig();
+  const llmFn = llmConfig
+    ? async (prompt: string): Promise<string> => {
+        const out = await chatCompletion(
+          llmConfig,
+          [
+            { role: 'system', content: 'You return only valid JSON. No markdown fences, no commentary.' },
+            { role: 'user', content: prompt },
+          ],
+          { maxTokens: 800, temperature: 0 },
+        );
+        return out ?? '';
+      }
+    : null;
+
+  // Build the I/O deps closures. We capture the owner/auth/key values so the
+  // background task doesn't race with module-level state resets.
+  const fetchFn = () =>
+    fetchAllActiveClaims(
+      owner,
+      authKey,
+      encKey,
+      DIGEST_FETCH_LIMIT,
+      {
+        searchSubgraphBroadened: async (o, n, a) => searchSubgraphBroadened(o, n, a),
+        decryptFromHex: (hex, key) => decryptFromHex(hex, key),
+      },
+      logger,
+    );
+
+  const storeFn = async (canonicalClaimJson: string, compiledAt: string): Promise<void> => {
+    if (!isSubgraphMode()) {
+      // Self-hosted mode — store via the REST API.
+      if (!apiClient) throw new Error('apiClient not initialized');
+      const encryptedBlob = encryptToHex(canonicalClaimJson, encKey);
+      const contentFp = generateContentFingerprint(canonicalClaimJson, dedupKey!);
+      const payload: StoreFactPayload = {
+        id: crypto.randomUUID(),
+        timestamp: compiledAt,
+        encrypted_blob: encryptedBlob,
+        blind_indices: [DIGEST_TRAPDOOR],
+        decay_score: 10,
+        source: 'openclaw-plugin-digest',
+        content_fp: contentFp,
+        agent_id: 'openclaw-plugin-digest',
+      };
+      await apiClient.store(userId!, [payload], authKey);
+      return;
+    }
+
+    // Subgraph / managed-service mode — encrypt, encode, submit as a single-fact UserOp.
+    const encryptedBlob = encryptToHex(canonicalClaimJson, encKey);
+    const contentFp = generateContentFingerprint(canonicalClaimJson, dedupKey!);
+    const protobuf = encodeFactProtobuf({
+      id: crypto.randomUUID(),
+      timestamp: compiledAt,
+      owner,
+      encryptedBlob,
+      blindIndices: [DIGEST_TRAPDOOR],
+      decayScore: 10,
+      source: 'openclaw-plugin-digest',
+      contentFp,
+      agentId: 'openclaw-plugin-digest',
+      version: PROTOBUF_VERSION_V4,
+    });
+    const config = { ...getSubgraphConfig(), authKeyHex: authKey, walletAddress: ownerForBatch };
+    const result = await submitFactBatchOnChain([protobuf], config);
+    if (!result.success) {
+      throw new Error('Digest store UserOp did not succeed on-chain');
+    }
+  };
+
+  const tombstoneFn = async (claimId: string): Promise<void> => {
+    if (!isSubgraphMode()) {
+      if (apiClient) {
+        try { await apiClient.deleteFact(claimId, authKey); } catch { /* best-effort */ }
+      }
+      return;
+    }
+    const tombstone: FactPayload = {
+      id: claimId,
+      timestamp: new Date().toISOString(),
+      owner,
+      encryptedBlob: '00',
+      blindIndices: [],
+      decayScore: 0,
+      source: 'tombstone',
+      contentFp: '',
+      agentId: 'openclaw-plugin-digest',
+      version: PROTOBUF_VERSION_V4,
+    };
+    const protobuf = encodeFactProtobuf(tombstone);
+    const config = { ...getSubgraphConfig(), authKeyHex: authKey, walletAddress: ownerForBatch };
+    const result = await submitFactBatchOnChain([protobuf], config);
+    if (!result.success) {
+      throw new Error('Digest tombstone UserOp did not succeed on-chain');
+    }
+  };
+
+  // Slice 2f: run the weight-tuning loop as a fire-and-forget pre-compile step.
+  // This consumes any feedback.jsonl entries written since the last compile
+  // and nudges ~/.totalreclaw/weights.json, so the NEXT contradiction detection
+  // uses the adjusted weights. Rate-limited and idempotent — see
+  // runWeightTuningLoop for details. Failures are logged, never fatal.
+  void runWeightTuningLoop(Math.floor(Date.now() / 1000), logger).catch((err: unknown) => {
+    const msg = err instanceof Error ? err.message : String(err);
+    logger.warn(`Digest: tuning loop threw: ${msg}`);
+  });
+
+  void recompileDigest({
+    mode,
+    previousClaimId,
+    nowUnixSeconds: Math.floor(Date.now() / 1000),
+    deps: {
+      storeDigestClaim: storeFn,
+      tombstoneDigest: tombstoneFn,
+      fetchAllActiveClaimsFn: fetchFn,
+      llmFn,
+    },
+    logger,
+  })
+    .catch((err: unknown) => {
+      const msg = err instanceof Error ? err.message : String(err);
+      logger.warn(`Digest: background recompile threw: ${msg}`);
+    })
+    .finally(() => {
+      endRecompile();
+    });
+}
+
 /**
  * Decrypt a hex-encoded ciphertext blob into a UTF-8 string.
  */
@@ -906,7 +1327,8 @@ async function fetchExistingMemoriesForExtraction(
       for (const r of rawResults) {
         try {
           const docJson = decryptFromHex(r.encryptedBlob, encryptionKey);
-          const doc = JSON.parse(docJson) as { text: string };
+          if (isDigestBlob(docJson)) continue;
+          const doc = readClaimFromBlob(docJson);
           results.push({ id: r.id, text: doc.text });
         } catch { /* skip undecryptable */ }
       }
@@ -915,7 +1337,8 @@ async function fetchExistingMemoriesForExtraction(
       for (const c of candidates) {
         try {
           const docJson = decryptFromHex(c.encrypted_blob, encryptionKey);
-          const doc = JSON.parse(docJson) as { text: string };
+          if (isDigestBlob(docJson)) continue;
+          const doc = readClaimFromBlob(docJson);
           results.push({ id: c.fact_id, text: doc.text });
         } catch { /* skip undecryptable */ }
       }
@@ -972,10 +1395,7 @@ function relativeTime(isoOrMs: string | number): string {
  * NOTE: This filter is ONLY applied to auto-extraction (hooks).
  * The explicit `totalreclaw_remember` tool always stores regardless of importance.
  */
-const MIN_IMPORTANCE_THRESHOLD = Math.max(
-  1,
-  Math.min(10, Number(process.env.TOTALRECLAW_MIN_IMPORTANCE) || 3),
-);
+const MIN_IMPORTANCE_THRESHOLD = CONFIG.minImportance;
 
 /**
  * Filter extracted facts by importance threshold.
@@ -998,10 +1418,20 @@ function filterByImportance(
     }
   }
 
-  if (dropped > 0) {
+  // Phase 2.2.5: always log the filter outcome so the agent_end path can
+  // distinguish "LLM returned 0 facts" from "LLM returned N facts all dropped
+  // below threshold" from "LLM returned N facts, all kept". Prior to 2.2.5
+  // this only logged on drops, which made empty-input invisible.
+  if (facts.length === 0) {
+    logger.info('Importance filter: input=0 (nothing to filter)');
+  } else if (dropped > 0) {
     logger.info(
       `Importance filter: dropped ${dropped}/${facts.length} facts below threshold ${MIN_IMPORTANCE_THRESHOLD}`,
     );
+  } else {
+    logger.info(
+      `Importance filter: kept all ${facts.length} facts (threshold ${MIN_IMPORTANCE_THRESHOLD})`,
+    );
   }
 
   return { kept, dropped };
@@ -1023,6 +1453,7 @@ function filterByImportance(
 async function storeExtractedFacts(
   facts: ExtractedFact[],
   logger: OpenClawPluginApi['logger'],
+  sourceOverride?: string,
 ): Promise<number> {
   if (!encryptionKey || !dedupKey || !authKeyHex || !userId || !apiClient) return 0;
 
@@ -1060,18 +1491,24 @@ async function storeExtractedFacts(
   let stored = 0;
   let superseded = 0;
   let skipped = 0;
+  let failedFacts = 0;
   const pendingPayloads: Buffer[] = []; // Batched subgraph payloads
   let preparedForSubgraph = 0;
 
+  // Plugin v3.0.0: always emit Memory Taxonomy v1 JSON blobs. The
+  // TOTALRECLAW_TAXONOMY_VERSION opt-in and the TOTALRECLAW_CLAIM_FORMAT
+  // legacy fallback have both been retired — v1 is the single write path.
+
   for (const fact of dedupedFacts) {
     try {
       const blindIndices = generateBlindIndices(fact.text);
+      const entityTrapdoors = computeEntityTrapdoors(fact.entities);
 
       // Use pre-computed embedding result if available.
       const embeddingResult = embeddingResultMap.get(fact.text) ?? null;
       const allIndices = embeddingResult
-        ? [...blindIndices, ...embeddingResult.lshBuckets]
-        : blindIndices;
+        ? [...blindIndices, ...embeddingResult.lshBuckets, ...entityTrapdoors]
+        : [...blindIndices, ...entityTrapdoors];
 
       // LLM-guided dedup: handle UPDATE/DELETE/NOOP actions.
       if (fact.action === 'NOOP') {
@@ -1093,6 +1530,7 @@ async function storeExtractedFacts(
             source: 'tombstone',
             contentFp: '',
             agentId: 'openclaw-plugin-auto',
+            version: PROTOBUF_VERSION_V4,
           };
           pendingPayloads.push(encodeFactProtobuf(tombstone));
           logger.info(`LLM dedup: DELETE — queued tombstone for ${fact.existingFactId}`);
@@ -1121,6 +1559,7 @@ async function storeExtractedFacts(
             source: 'tombstone',
             contentFp: '',
             agentId: 'openclaw-plugin-auto',
+            version: PROTOBUF_VERSION_V4,
           };
           pendingPayloads.push(encodeFactProtobuf(tombstone));
           logger.info(`LLM dedup: UPDATE — queued tombstone for ${fact.existingFactId}, storing replacement`);
@@ -1171,6 +1610,7 @@ async function storeExtractedFacts(
               source: 'tombstone',
               contentFp: '',
               agentId: 'openclaw-plugin-auto',
+              version: PROTOBUF_VERSION_V4,
             };
             pendingPayloads.push(encodeFactProtobuf(tombstone));
             logger.info(
@@ -1193,20 +1633,133 @@ async function storeExtractedFacts(
         }
       }
 
-      const doc = {
-        text: fact.text,
-        metadata: {
-          type: fact.type,
-          importance: effectiveImportance / 10,
-          source: 'auto-extraction',
-          created_at: new Date().toISOString(),
-        },
-      };
+      const factSource = sourceOverride || 'auto-extraction';
+
+      // Plugin v3.0.0: always build a Memory Taxonomy v1 JSON blob. The
+      // blob is decryptable by `readClaimFromBlob` which prefers v1 →
+      // falls back to v0 short-key → then plugin-legacy {text, metadata}
+      // for pre-v3 vault entries.
+      //
+      // We build it BEFORE the on-chain write so Phase 2 contradiction
+      // detection can inspect the same canonical Claim the write path will
+      // actually store. The string is encrypted byte-identically below.
+      //
+      // Defensive: if the extraction hook didn't populate `fact.source`
+      // (e.g. explicit tool path, legacy caller), default to 'user-inferred'
+      // so v1 schema validation passes.
+      const factForBlob: ExtractedFact = fact.source
+        ? fact
+        : { ...fact, source: 'user-inferred' };
+      const blobPlaintext = buildCanonicalClaim({
+        fact: factForBlob,
+        importance: effectiveImportance,
+        sourceAgent: factSource,
+      });
 
-      const encryptedBlob = encryptToHex(JSON.stringify(doc), encryptionKey);
+      const factId = crypto.randomUUID();
+
+      // Phase 2 Slice 2d: contradiction detection + auto-resolution.
+      //
+      // Runs only when the canonical Claim format is active (legacy blobs
+      // carry no entity refs, so there is nothing to check), only for
+      // Subgraph / managed-service mode (self-hosted contradiction handling
+      // can come later), and only when the new fact has entities. The helper
+      // is a no-op in all other cases.
+      //
+      // Returns one decision per candidate contradicting claim:
+      //   - supersede_existing → queue a tombstone + proceed with the new write
+      //   - skip_new → do not write the new fact; record the skip reason
+      //   - empty list → no contradiction, proceed unchanged
+      //
+      // On any error (subgraph, decrypt, WASM), the helper returns [] and we
+      // fall back to Phase 1 behaviour.
+      let contradictionSkipNew = false;
+      if (
+        isSubgraphMode() &&
+        fact.entities &&
+        fact.entities.length > 0 &&
+        embeddingResult
+      ) {
+        const newClaimObj = JSON.parse(blobPlaintext) as Record<string, unknown>;
+        let decisions: ContradictionDecision[] = [];
+        try {
+          decisions = await detectAndResolveContradictions({
+            newClaim: newClaimObj,
+            newClaimId: factId,
+            newEmbedding: embeddingResult.embedding,
+            subgraphOwner: subgraphOwner || userId!,
+            authKeyHex: authKeyHex!,
+            encryptionKey: encryptionKey!,
+            deps: {
+              searchSubgraph: (owner, trapdoors, maxCandidates, authKey) =>
+                searchSubgraph(owner, trapdoors, maxCandidates, authKey).then((rows) =>
+                  rows.map((r) => ({
+                    id: r.id,
+                    encryptedBlob: r.encryptedBlob,
+                    encryptedEmbedding: r.encryptedEmbedding ?? null,
+                    timestamp: r.timestamp,
+                    isActive: r.isActive,
+                  })),
+                ),
+              decryptFromHex: (hex, key) => decryptFromHex(hex, key),
+            },
+            logger: {
+              info: (m) => logger.info(m),
+              warn: (m) => logger.warn(m),
+            },
+          });
+        } catch (crErr) {
+          // detectAndResolveContradictions is supposed to never throw — if
+          // it does, we log and continue with Phase 1 behaviour.
+          const msg = crErr instanceof Error ? crErr.message : String(crErr);
+          logger.warn(`Contradiction detection failed (proceeding with store): ${msg}`);
+          decisions = [];
+        }
+
+        for (const decision of decisions) {
+          if (decision.action === 'supersede_existing') {
+            const tombstone: FactPayload = {
+              id: decision.existingFactId,
+              timestamp: new Date().toISOString(),
+              owner: subgraphOwner || userId!,
+              encryptedBlob: '00',
+              blindIndices: [],
+              decayScore: 0,
+              source: 'tombstone',
+              contentFp: '',
+              agentId: 'openclaw-plugin-auto',
+              version: PROTOBUF_VERSION_V4,
+            };
+            pendingPayloads.push(encodeFactProtobuf(tombstone));
+            superseded++;
+            logger.info(
+              `Auto-resolve: queued supersede for ${decision.existingFactId.slice(0, 10)}… ` +
+                `(sim=${decision.similarity.toFixed(3)}, entity=${decision.entityId})`,
+            );
+          } else if (decision.action === 'skip_new') {
+            if (decision.reason === 'existing_pinned') {
+              logger.warn(
+                `Auto-resolve: skipped new write — existing claim ${decision.existingFactId.slice(0, 10)}… is pinned ` +
+                  `(sim=${decision.similarity.toFixed(3)}, entity=${decision.entityId})`,
+              );
+            } else {
+              logger.info(
+                `Auto-resolve: skipped new write — existing ${decision.existingFactId.slice(0, 10)}… wins ` +
+                  `(sim=${decision.similarity.toFixed(3)}, entity=${decision.entityId})`,
+              );
+            }
+            contradictionSkipNew = true;
+          }
+        }
+      }
+
+      if (contradictionSkipNew) {
+        skipped++;
+        continue;
+      }
 
+      const encryptedBlob = encryptToHex(blobPlaintext, encryptionKey);
       const contentFp = generateContentFingerprint(fact.text, dedupKey);
-      const factId = crypto.randomUUID();
 
       if (isSubgraphMode()) {
         const protobuf = encodeFactProtobuf({
@@ -1216,9 +1769,10 @@ async function storeExtractedFacts(
           encryptedBlob: encryptedBlob,
           blindIndices: allIndices,
           decayScore: effectiveImportance,
-          source: 'auto-extraction',
+          source: factSource,
           contentFp: contentFp,
           agentId: 'openclaw-plugin-auto',
+          version: PROTOBUF_VERSION_V4,
           encryptedEmbedding: embeddingResult?.encryptedEmbedding,
         });
         pendingPayloads.push(protobuf);
@@ -1230,7 +1784,7 @@ async function storeExtractedFacts(
           encrypted_blob: encryptedBlob,
           blind_indices: allIndices,
           decay_score: effectiveImportance,
-          source: 'auto-extraction',
+          source: factSource,
           content_fp: contentFp,
           agent_id: 'openclaw-plugin-auto',
           encrypted_embedding: embeddingResult?.encryptedEmbedding,
@@ -1241,40 +1795,68 @@ async function storeExtractedFacts(
     } catch (err: unknown) {
       // Check for 403 / quota exceeded — invalidate billing cache so next
       // before_agent_start re-fetches and warns the user.
-      const errMsg = err instanceof Error ? err.message : String(err);
-      if (errMsg.includes('403') || errMsg.toLowerCase().includes('quota')) {
+      const factErrMsg = err instanceof Error ? err.message : String(err);
+      if (factErrMsg.includes('403') || factErrMsg.toLowerCase().includes('quota')) {
         try { fs.unlinkSync(BILLING_CACHE_PATH); } catch { /* ignore */ }
-        logger.warn(`Quota exceeded — billing cache invalidated. ${errMsg}`);
+        logger.warn(`Quota exceeded — billing cache invalidated. ${factErrMsg}`);
         break; // Stop trying to store remaining facts — they'll all fail too
       }
-      // Otherwise skip failed facts (e.g., duplicates return success with duplicate_ids)
+      // Otherwise log and continue — individual fact failures shouldn't block remaining facts
+      logger.warn(`Failed to store fact "${fact.text.slice(0, 60)}…": ${factErrMsg}`);
+      failedFacts++;
     }
   }
 
-  // Batch-submit all subgraph payloads in a single UserOp (gas-efficient).
+  // Submit subgraph payloads one fact at a time (sequential single-call UserOps).
+  // Batch executeBatch UserOps have persistent gas estimation issues on Base Sepolia
+  // that cause on-chain reverts. Single-fact UserOps use the simpler submitFactOnChain
+  // path which works reliably (same path as totalreclaw_remember). Each submission
+  // polls for receipt (120s) before proceeding, so nonce is consumed before the next.
+  let batchError: string | undefined;
   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}`);
+    const batchConfig = { ...getSubgraphConfig(), authKeyHex: authKeyHex!, walletAddress: subgraphOwner ?? undefined };
+    for (let i = 0; i < pendingPayloads.length; i++) {
+      const slice = [pendingPayloads[i]]; // Single fact per UserOp
+      try {
+        const result = await submitFactBatchOnChain(slice, batchConfig);
+        if (result.success) {
+          stored += slice.length;
+          logger.info(`Fact ${i + 1}/${pendingPayloads.length}: submitted on-chain (tx=${result.txHash.slice(0, 10)}…)`);
+        } else {
+          batchError = `On-chain batch submission failed (tx=${result.txHash.slice(0, 10)}…)`;
+          logger.warn(batchError);
+          break; // Stop submitting remaining batches
+        }
+      } 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 */ }
+          batchError = `Quota exceeded — billing cache invalidated. ${errMsg}`;
+          logger.warn(batchError);
+          break;
+        } else {
+          batchError = `Batch submission failed: ${errMsg}`;
+          logger.warn(batchError);
+          break;
+        }
       }
     }
   }
 
-  if (stored > 0 || superseded > 0 || skipped > 0) {
-    logger.info(`Auto-extraction results: stored=${stored}, superseded=${superseded}, skipped=${skipped}`);
+  if (stored > 0 || superseded > 0 || skipped > 0 || failedFacts > 0) {
+    logger.info(`Auto-extraction results: stored=${stored}, superseded=${superseded}, skipped=${skipped}, failed=${failedFacts}`);
+  }
+
+  // If ANY batch failed, throw — even if some facts were stored earlier.
+  // A failed/timed-out UserOp may still linger in the bundler mempool as a
+  // "nonce zombie." If we return normally, the caller's next storeExtractedFacts
+  // call will fetch the same on-chain nonce and hit AA25 ("invalid account nonce").
+  // Throwing forces all callers (import loops, chunk handlers) to stop submitting.
+  if (batchError) {
+    throw new Error(`Memory storage failed (${stored} stored before failure): ${batchError}`);
+  }
+  if (stored === 0 && failedFacts > 0) {
+    throw new Error(`Memory storage failed: ${failedFacts} fact(s) failed to store`);
   }
 
   return stored;
@@ -1287,16 +1869,22 @@ 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>,
   logger: OpenClawPluginApi['logger'],
 ): Promise<Record<string, unknown>> {
+  _importInProgress = true;
   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', 'gemini', 'memoclaw', 'generic-json', 'generic-csv'];
 
   if (!source || !validSources.includes(source)) {
     return { success: false, error: `Invalid source. Must be one of: ${validSources.join(', ')}` };
@@ -1314,7 +1902,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`,
@@ -1322,7 +1913,37 @@ async function handlePluginImportFrom(
       };
     }
 
+    // Dry run: report what was parsed (chunks or facts)
     if (params.dry_run) {
+      if (hasChunks) {
+        const totalChunks = parseResult.chunks.length;
+        const EXTRACTION_RATIO = 2.5; // avg facts per chunk, from empirical data
+        const BATCH_SIZE = 25;
+        const SECONDS_PER_BATCH = 45; // ~30s extraction + ~15s embed+store
+        const estimatedFacts = Math.round(totalChunks * EXTRACTION_RATIO);
+        const estimatedBatches = Math.ceil(totalChunks / BATCH_SIZE);
+        const estimatedMinutes = Math.ceil(estimatedBatches * SECONDS_PER_BATCH / 60);
+
+        return {
+          success: true,
+          dry_run: true,
+          source,
+          total_chunks: totalChunks,
+          total_messages: parseResult.totalMessages,
+          estimated_facts: estimatedFacts,
+          estimated_batches: estimatedBatches,
+          estimated_minutes: estimatedMinutes,
+          batch_size: BATCH_SIZE,
+          use_background: totalChunks > 50,
+          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: `Estimated ${estimatedFacts} facts from ${totalChunks} chunks (~${estimatedMinutes} min).${totalChunks > 50 ? ' Recommended: background import via sessions_spawn.' : ''}`,
+          warnings: parseResult.warnings,
+        };
+      }
       return {
         success: true,
         dry_run: true,
@@ -1337,7 +1958,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,
@@ -1345,28 +1971,42 @@ async function handlePluginImportFrom(
       action: 'ADD' as const,
     }));
 
-    // Store in batches of 50
+    // Store in batches of 50. Stop on any batch failure to prevent
+    // nonce zombies from blocking subsequent UserOps (AA25).
     let totalStored = 0;
+    let storeError: string | undefined;
     const batchSize = 50;
 
     for (let i = 0; i < extractedFacts.length; i += batchSize) {
       const batch = extractedFacts.slice(i, i + batchSize);
-      const stored = await storeExtractedFacts(batch, logger);
-      totalStored += stored;
+      try {
+        const stored = await storeExtractedFacts(batch, logger);
+        totalStored += stored;
 
-      logger.info(
-        `Import progress: ${Math.min(i + batchSize, extractedFacts.length)}/${extractedFacts.length} processed, ${totalStored} stored`,
-      );
+        logger.info(
+          `Import progress: ${Math.min(i + batchSize, extractedFacts.length)}/${extractedFacts.length} processed, ${totalStored} stored`,
+        );
+      } catch (err: unknown) {
+        storeError = err instanceof Error ? err.message : String(err);
+        logger.warn(`Import stopped at batch ${Math.floor(i / batchSize) + 1}: ${storeError}`);
+        break; // Stop processing further batches
+      }
+    }
+
+    const importWarnings = [...parseResult.warnings];
+    if (storeError) {
+      importWarnings.push(`Import stopped early: ${storeError}`);
     }
 
     return {
-      success: true,
+      success: totalStored > 0,
       source,
       import_id: crypto.randomUUID(),
       total_found: parseResult.facts.length,
       imported: totalStored,
       skipped: parseResult.facts.length - totalStored,
-      warnings: parseResult.warnings,
+      stopped_early: !!storeError,
+      warnings: importWarnings,
       duration_ms: Date.now() - startTime,
     };
   } catch (e) {
@@ -1376,6 +2016,459 @@ async function handlePluginImportFrom(
   }
 }
 
+// ---------------------------------------------------------------------------
+// Smart Import — Two-Pass Pipeline (Profile + Triage)
+// ---------------------------------------------------------------------------
+
+// Lazy-load WASM for smart import functions (same pattern as crypto.ts / subgraph-store.ts).
+let _smartImportWasm: typeof import('@totalreclaw/core') | null = null;
+function getSmartImportWasm() {
+  if (!_smartImportWasm) _smartImportWasm = require('@totalreclaw/core');
+  return _smartImportWasm;
+}
+
+/**
+ * Check whether the @totalreclaw/core WASM module exposes smart import functions.
+ * Returns false if the module is an older version without smart import support.
+ */
+function hasSmartImportSupport(): boolean {
+  try {
+    const wasm = getSmartImportWasm();
+    return typeof wasm.chunksToSummaries === 'function' &&
+      typeof wasm.buildProfileBatchPrompt === 'function' &&
+      typeof wasm.parseProfileBatchResponse === 'function' &&
+      typeof wasm.buildTriagePrompt === 'function' &&
+      typeof wasm.parseTriageResponse === 'function' &&
+      typeof wasm.enrichExtractionPrompt === 'function';
+  } catch {
+    return false;
+  }
+}
+
+/** Smart import result containing profile, triage decisions, and enriched system prompt. */
+interface SmartImportContext {
+  /** JSON-serialized UserProfile (for WASM calls that require profile_json) */
+  profileJson: string;
+  /** Triage decisions indexed by chunk_index */
+  decisions: Array<{ chunk_index: number; decision: string; reason: string }>;
+  /** Enriched system prompt for extraction (profile context injected) */
+  enrichedSystemPrompt: string;
+  /** Number of chunks marked for extraction */
+  extractCount: number;
+  /** Number of chunks marked for skipping */
+  skipCount: number;
+  /** Duration of the profiling + triage pipeline in ms */
+  durationMs: number;
+}
+
+/**
+ * Run the smart import two-pass pipeline: profile the user from conversation
+ * summaries, then triage chunks as EXTRACT or SKIP.
+ *
+ * All prompt construction and response parsing happens in @totalreclaw/core WASM.
+ * LLM calls use the plugin's existing chatCompletion() function.
+ *
+ * Returns null if smart import is unavailable (old WASM, no LLM config, etc.)
+ * so the caller can fall back to blind extraction.
+ */
+async function runSmartImportPipeline(
+  chunks: import('./import-adapters/types.js').ConversationChunk[],
+  logger: { info: (msg: string) => void; warn: (msg: string) => void },
+): Promise<SmartImportContext | null> {
+  // Guard: WASM must have smart import functions
+  if (!hasSmartImportSupport()) {
+    logger.info('Smart import: WASM module does not support smart import, falling back to blind extraction');
+    return null;
+  }
+
+  // Guard: LLM must be available
+  const llmConfig = resolveLLMConfig();
+  if (!llmConfig) {
+    logger.info('Smart import: no LLM available, falling back to blind extraction');
+    return null;
+  }
+
+  const pipelineStart = Date.now();
+  const wasm = getSmartImportWasm();
+
+  try {
+    // Step 0: Convert chunks to compact summaries (first + last message)
+    const wasmChunks = chunks.map((c, i) => ({
+      index: i,
+      title: c.title || 'Untitled',
+      messages: c.messages.map((m) => ({ role: m.role, content: m.text })),
+      timestamp: c.timestamp || null,
+    }));
+    const summaries = wasm.chunksToSummaries(JSON.stringify(wasmChunks));
+    const summariesJson = JSON.stringify(summaries);
+
+    // Step 1: Build user profile (batch summarize -> merge)
+    const PROFILE_BATCH_SIZE = 50;
+    const profileStart = Date.now();
+    const partials: unknown[] = [];
+
+    for (let i = 0; i < summaries.length; i += PROFILE_BATCH_SIZE) {
+      const batch = summaries.slice(i, i + PROFILE_BATCH_SIZE);
+      const prompt = wasm.buildProfileBatchPrompt(JSON.stringify(batch));
+      const response = await chatCompletion(llmConfig, [
+        { role: 'user', content: prompt },
+      ], { maxTokens: 2048, temperature: 0 });
+
+      if (!response) {
+        logger.warn(`Smart import: LLM returned empty response for profile batch ${Math.floor(i / PROFILE_BATCH_SIZE) + 1}`);
+        continue;
+      }
+
+      const partial = wasm.parseProfileBatchResponse(response);
+      partials.push(partial);
+    }
+
+    if (partials.length === 0) {
+      logger.warn('Smart import: no profile batches produced, falling back to blind extraction');
+      return null;
+    }
+
+    let profile: unknown;
+    if (partials.length === 1) {
+      // Single batch — skip merge, promote partial to full profile
+      // parseProfileBatchResponse returns a PartialProfile; convert to UserProfile shape
+      const p = partials[0] as Record<string, unknown>;
+      profile = {
+        identity: p.identity ?? null,
+        themes: p.themes ?? [],
+        projects: p.projects ?? [],
+        stack: p.stack ?? [],
+        decisions: p.decisions ?? [],
+        interests: p.interests ?? [],
+        skip_patterns: p.skip_patterns ?? [],
+      };
+    } else {
+      const mergePrompt = wasm.buildProfileMergePrompt(JSON.stringify(partials));
+      const mergeResponse = await chatCompletion(llmConfig, [
+        { role: 'user', content: mergePrompt },
+      ], { maxTokens: 2048, temperature: 0 });
+
+      if (!mergeResponse) {
+        logger.warn('Smart import: LLM returned empty response for profile merge, falling back to blind extraction');
+        return null;
+      }
+
+      profile = wasm.parseProfileResponse(mergeResponse);
+    }
+
+    const profileJson = JSON.stringify(profile);
+    const profileDuration = Date.now() - profileStart;
+
+    const p = profile as Record<string, unknown>;
+    const themeCount = Array.isArray(p.themes) ? p.themes.length : 0;
+    const skipPatternCount = Array.isArray(p.skip_patterns) ? p.skip_patterns.length : 0;
+    logger.info(
+      `Smart import: profile built in ${profileDuration}ms (themes=${themeCount}, skip_patterns=${skipPatternCount})`,
+    );
+
+    // Step 1.5: Chunk triage (EXTRACT or SKIP)
+    const triageStart = Date.now();
+    const allDecisions: Array<{ chunk_index: number; decision: string; reason: string }> = [];
+    const TRIAGE_BATCH_SIZE = 50;
+
+    for (let i = 0; i < summaries.length; i += TRIAGE_BATCH_SIZE) {
+      const batch = summaries.slice(i, i + TRIAGE_BATCH_SIZE);
+      const triagePrompt = wasm.buildTriagePrompt(profileJson, JSON.stringify(batch));
+      const triageResponse = await chatCompletion(llmConfig, [
+        { role: 'user', content: triagePrompt },
+      ], { maxTokens: 4096, temperature: 0 });
+
+      if (!triageResponse) {
+        logger.warn(`Smart import: LLM returned empty response for triage batch ${Math.floor(i / TRIAGE_BATCH_SIZE) + 1}, defaulting to EXTRACT`);
+        // Default all chunks in this batch to EXTRACT
+        for (let j = i; j < Math.min(i + TRIAGE_BATCH_SIZE, summaries.length); j++) {
+          allDecisions.push({ chunk_index: j, decision: 'EXTRACT', reason: 'triage LLM unavailable' });
+        }
+        continue;
+      }
+
+      const batchDecisions = wasm.parseTriageResponse(triageResponse) as Array<{
+        chunk_index: number;
+        decision: string;
+        reason: string;
+      }>;
+      allDecisions.push(...batchDecisions);
+    }
+
+    const triageDuration = Date.now() - triageStart;
+
+    const extractCount = allDecisions.filter((d) => d.decision !== 'SKIP').length;
+    const skipCount = allDecisions.filter((d) => d.decision === 'SKIP').length;
+    logger.info(
+      `Smart import: triage complete in ${triageDuration}ms (extract=${extractCount}, skip=${skipCount}, total=${chunks.length})`,
+    );
+
+    // Step 2: Build enriched system prompt for extraction
+    const enrichedSystemPrompt = wasm.enrichExtractionPrompt(profileJson, EXTRACTION_SYSTEM_PROMPT);
+
+    const totalDuration = Date.now() - pipelineStart;
+    logger.info(`Smart import: pipeline complete in ${totalDuration}ms`);
+
+    return {
+      profileJson,
+      decisions: allDecisions,
+      enrichedSystemPrompt,
+      extractCount,
+      skipCount,
+      durationMs: totalDuration,
+    };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    logger.warn(`Smart import: pipeline failed (${msg}), falling back to blind extraction`);
+    return null;
+  }
+}
+
+/**
+ * Check if a chunk should be skipped based on triage decisions.
+ * If no decision exists for the chunk index, defaults to EXTRACT (safe default).
+ */
+function isChunkSkipped(
+  chunkIndex: number,
+  decisions: Array<{ chunk_index: number; decision: string }>,
+): { skipped: boolean; reason: string } {
+  const decision = decisions.find((d) => d.chunk_index === chunkIndex);
+  if (decision && decision.decision === 'SKIP') {
+    return { skipped: true, reason: (decision as { reason?: string }).reason || 'triage: skip' };
+  }
+  return { skipped: false, reason: '' };
+}
+
+/**
+ * Process a batch (slice) of conversation chunks from a file.
+ * Called repeatedly by the agent for large imports.
+ */
+async function handleBatchImport(
+  params: Record<string, unknown>,
+  logger: OpenClawPluginApi['logger'],
+): Promise<Record<string, unknown>> {
+  _importInProgress = true;
+  const source = params.source as string;
+  const filePath = params.file_path as string | undefined;
+  const content = params.content as string | undefined;
+  const offset = (params.offset as number) ?? 0;
+  const batchSize = (params.batch_size as number) ?? 25;
+
+  const validSources = ['mem0', 'mcp-memory', 'chatgpt', 'claude', 'gemini', 'memoclaw', 'generic-json', 'generic-csv'];
+  if (!source || !validSources.includes(source)) {
+    return { success: false, error: `Invalid source. Must be one of: ${validSources.join(', ')}` };
+  }
+
+  const startTime = Date.now();
+
+  const { getAdapter } = await import('./import-adapters/index.js');
+  const adapter = getAdapter(source as import('./import-adapters/types.js').ImportSource);
+
+  const parseResult = await adapter.parse({ content, file_path: filePath });
+
+  if (parseResult.errors.length > 0 && parseResult.chunks.length === 0) {
+    return { success: false, error: parseResult.errors.join('; ') };
+  }
+
+  const totalChunks = parseResult.chunks.length;
+  const slice = parseResult.chunks.slice(offset, offset + batchSize);
+  const remaining = Math.max(0, totalChunks - offset - slice.length);
+
+  // --- Smart Import: Profile + Triage ---
+  // Build profile from ALL chunks (not just the slice) for full context,
+  // then triage only the current slice. For simplicity, we rebuild on every
+  // batch call — optimization (caching) can come later.
+  const smartCtx = await runSmartImportPipeline(parseResult.chunks, logger);
+  let chunksSkipped = 0;
+
+  // Process the slice through the normal extraction + storage pipeline.
+  // If a batch fails (nonce zombie, quota exceeded, etc.), stop immediately
+  // to prevent subsequent UserOps from hitting AA25 nonce conflicts.
+  let factsExtracted = 0;
+  let factsStored = 0;
+  let chunksProcessed = 0;
+  let storeError: string | undefined;
+
+  for (let i = 0; i < slice.length; i++) {
+    const chunk = slice[i];
+    const globalIndex = offset + i; // Index in the full chunks array
+
+    // Smart import: skip chunks triaged as SKIP
+    if (smartCtx) {
+      const { skipped, reason } = isChunkSkipped(globalIndex, smartCtx.decisions);
+      if (skipped) {
+        logger.info(`Import: skipping chunk ${globalIndex + 1}/${totalChunks}: "${chunk.title}" (${reason})`);
+        chunksSkipped++;
+        chunksProcessed++;
+        continue;
+      }
+    }
+
+    logger.info(`Import: extracting facts from chunk ${globalIndex + 1}/${totalChunks}: "${chunk.title}"`);
+
+    const messages = chunk.messages.map((m) => ({ role: m.role, content: m.text }));
+    const facts = await extractFacts(
+      messages,
+      'full',
+      undefined, // no existing memories for dedup during import
+      smartCtx?.enrichedSystemPrompt, // profile-enriched extraction prompt
+    );
+    chunksProcessed++;
+
+    if (facts.length > 0) {
+      factsExtracted += facts.length;
+      try {
+        const stored = await storeExtractedFacts(facts, logger);
+        factsStored += stored;
+      } catch (err: unknown) {
+        storeError = err instanceof Error ? err.message : String(err);
+        logger.warn(`Import batch stopped at chunk ${globalIndex + 1}/${totalChunks}: ${storeError}`);
+        break; // Stop processing further chunks — a zombie UserOp may block writes
+      }
+    }
+  }
+
+  return {
+    success: factsStored > 0 || (!storeError && factsExtracted === 0),
+    batch_offset: offset,
+    batch_size: chunksProcessed,
+    total_chunks: totalChunks,
+    facts_extracted: factsExtracted,
+    facts_stored: factsStored,
+    chunks_skipped: chunksSkipped,
+    remaining_chunks: remaining,
+    is_complete: remaining === 0 && !storeError,
+    stopped_early: !!storeError,
+    error: storeError,
+    smart_import: smartCtx ? {
+      profile_duration_ms: smartCtx.durationMs,
+      extract_count: smartCtx.extractCount,
+      skip_count: smartCtx.skipCount,
+    } : null,
+    // Estimation for the full import
+    estimated_total_facts: Math.round(totalChunks * 2.5),
+    estimated_total_userops: Math.ceil(totalChunks * 2.5 / 15),
+    estimated_minutes: Math.ceil(Math.ceil(totalChunks / batchSize) * 45 / 60),
+    duration_ms: Date.now() - startTime,
+  };
+}
+
+/**
+ * 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;
+  let chunksSkipped = 0;
+
+  let storeError: string | undefined;
+
+  // --- Smart Import: Profile + Triage ---
+  const smartCtx = await runSmartImportPipeline(chunks, logger);
+
+  for (let i = 0; i < chunks.length; i++) {
+    const chunk = chunks[i];
+    chunksProcessed++;
+
+    // Smart import: skip chunks triaged as SKIP
+    if (smartCtx) {
+      const { skipped, reason } = isChunkSkipped(i, smartCtx.decisions);
+      if (skipped) {
+        logger.info(
+          `Import: skipping chunk ${chunksProcessed}/${chunks.length}: "${chunk.title}" (${reason})`,
+        );
+        chunksSkipped++;
+        continue;
+      }
+    }
+
+    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).
+    // Smart import: pass enriched system prompt with user profile context.
+    const facts = await extractFacts(
+      messages,
+      'full',
+      undefined, // no existing memories for dedup during import
+      smartCtx?.enrichedSystemPrompt, // profile-enriched extraction prompt
+    );
+
+    if (facts.length > 0) {
+      totalExtracted += facts.length;
+
+      try {
+        // Store through the normal pipeline (dedup, encrypt, store).
+        // storeExtractedFacts throws on batch failure to prevent nonce zombies.
+        const stored = await storeExtractedFacts(facts, logger);
+        totalStored += stored;
+
+        logger.info(
+          `Import chunk ${chunksProcessed}/${chunks.length}: extracted ${facts.length} facts, stored ${stored}`,
+        );
+      } catch (err: unknown) {
+        storeError = err instanceof Error ? err.message : String(err);
+        logger.warn(`Import stopped at chunk ${chunksProcessed}/${chunks.length}: ${storeError}`);
+        break; // Stop processing further chunks — a zombie UserOp may block writes
+      }
+    }
+  }
+
+  if (totalExtracted === 0 && chunks.length > 0 && !storeError && chunksSkipped < chunks.length) {
+    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.`,
+    );
+  }
+
+  if (storeError) {
+    warnings.push(`Import stopped early: ${storeError}. ${chunks.length - chunksProcessed} chunk(s) not processed.`);
+  }
+
+  return {
+    success: totalStored > 0 || totalExtracted > 0,
+    source,
+    import_id: crypto.randomUUID(),
+    total_chunks: chunks.length,
+    chunks_processed: chunksProcessed,
+    chunks_skipped: chunksSkipped,
+    total_messages: totalMessages,
+    facts_extracted: totalExtracted,
+    imported: totalStored,
+    skipped: totalExtracted - totalStored,
+    stopped_early: !!storeError,
+    smart_import: smartCtx ? {
+      profile_duration_ms: smartCtx.durationMs,
+      extract_count: smartCtx.extractCount,
+      skip_count: smartCtx.skipCount,
+    } : null,
+    warnings,
+    duration_ms: Date.now() - startTime,
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Plugin definition
 // ---------------------------------------------------------------------------
@@ -1408,6 +2501,7 @@ const plugin = {
     initLLMClient({
       primaryModel: api.config?.agents?.defaults?.model?.primary as string | undefined,
       pluginConfig: api.pluginConfig,
+      openclawProviders: api.config?.models?.providers,
       logger: api.logger,
     });
 
@@ -1444,160 +2538,164 @@ const plugin = {
             },
             type: {
               type: 'string',
-              enum: ['fact', 'preference', 'decision', 'episodic', 'goal', 'context', 'summary'],
-              description: 'The kind of memory (default: fact)',
+              enum: [...VALID_MEMORY_TYPES, ...LEGACY_V0_MEMORY_TYPES],
+              description:
+                'Memory Taxonomy v1 type: claim, preference, directive, commitment, episode, summary. ' +
+                'Use "claim" for factual assertions and decisions (populate `reasoning` with the why clause). ' +
+                'Use "directive" for imperative rules ("always X", "never Y"), "commitment" for future intent, ' +
+                'and "episode" for notable events. Legacy v0 tokens (fact, decision, episodic, goal, context, ' +
+                'rule) are silently coerced to their v1 equivalents. Default: claim.',
+            },
+            source: {
+              type: 'string',
+              enum: [...VALID_MEMORY_SOURCES],
+              description:
+                'v1 provenance tag. "user" = user explicitly stated it, "user-inferred" = inferred from user ' +
+                'signals, "assistant" = assistant-authored (downgrade unless user affirmed), "external" / ' +
+                '"derived" = rare. Explicit remembers default to "user".',
+            },
+            scope: {
+              type: 'string',
+              enum: [...VALID_MEMORY_SCOPES],
+              description:
+                'v1 life-domain scope: work, personal, health, family, creative, finance, misc, unspecified. ' +
+                'Default: unspecified.',
+            },
+            reasoning: {
+              type: 'string',
+              description:
+                'For type=claim expressing a decision, the WHY clause ("because Y"). Max 256 chars. ' +
+                'Omit for non-decision claims.',
+              maxLength: 256,
             },
             importance: {
               type: 'number',
               minimum: 1,
               maximum: 10,
-              description: 'Importance score 1-10 (default: 5)',
+              description: 'Importance score 1-10 (default: 8 for explicit remember)',
+            },
+            entities: {
+              type: 'array',
+              description:
+                'Named entities this memory is about (people, projects, tools, companies, concepts, places). ' +
+                'Supplying entities enables Phase 2 contradiction detection against existing facts about the same entity. ' +
+                'Omit if unclear — a best-effort fallback will still store the memory.',
+              items: {
+                type: 'object',
+                properties: {
+                  name: { type: 'string' },
+                  type: {
+                    type: 'string',
+                    enum: ['person', 'project', 'tool', 'company', 'concept', 'place'],
+                  },
+                  role: { type: 'string' },
+                },
+                required: ['name', 'type'],
+                additionalProperties: false,
+              },
             },
           },
           required: ['text'],
           additionalProperties: false,
         },
-        async execute(_toolCallId: string, params: { text: string; type?: string; importance?: number }) {
+        async execute(
+          _toolCallId: string,
+          params: {
+            text: string;
+            type?: string;
+            source?: string;
+            scope?: string;
+            reasoning?: string;
+            importance?: number;
+            entities?: Array<{ name: string; type: string; role?: string }>;
+          },
+        ) {
           try {
             await requireFullSetup(api.logger);
 
-            const memoryType = params.type ?? 'fact';
-            let importance = params.importance ?? 5;
-
-            // Generate blind indices for server-side search.
-            const blindIndices = generateBlindIndices(params.text);
-
-            // Generate embedding + LSH bucket hashes (PoC v2).
-            // Falls back to word-only indices if embedding generation fails.
-            const embeddingResult = await generateEmbeddingAndLSH(params.text, api.logger);
-
-            // Merge LSH bucket hashes into blind indices.
-            const allIndices = embeddingResult
-              ? [...blindIndices, ...embeddingResult.lshBuckets]
-              : blindIndices;
-
-            // Store-time dedup: for explicit remember, ALWAYS supersede
-            // (user explicitly wants this stored — just remove the old one).
-            let supersededId: string | undefined;
-            if (STORE_DEDUP_ENABLED && embeddingResult) {
-              const dupResult = await searchForNearDuplicates(
-                params.text,
-                embeddingResult.embedding,
-                allIndices,
-                api.logger,
-              );
-              if (dupResult) {
-                // Inherit higher importance from existing fact.
-                importance = Math.max(importance, dupResult.match.decayScore);
-                supersededId = dupResult.match.id;
-
-                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',
-                    };
-                    const tombProtobuf = encodeFactProtobuf(tombstone);
-                    await submitFactOnChain(tombProtobuf, tombConfig);
-                    api.logger.info(
-                      `Remember dedup: superseded ${dupResult.match.id} on-chain (sim=${dupResult.similarity.toFixed(3)})`,
-                    );
-                  } catch (tombErr) {
-                    api.logger.warn(
-                      `Remember dedup: failed to tombstone ${dupResult.match.id}: ${tombErr instanceof Error ? tombErr.message : String(tombErr)}`,
-                    );
-                    supersededId = undefined;
-                  }
-                } else if (apiClient && authKeyHex) {
-                  try {
-                    await apiClient.deleteFact(dupResult.match.id, authKeyHex);
-                    api.logger.info(
-                      `Remember dedup: superseded ${dupResult.match.id} (sim=${dupResult.similarity.toFixed(3)})`,
-                    );
-                  } catch (delErr) {
-                    api.logger.warn(
-                      `Remember dedup: failed to delete superseded fact ${dupResult.match.id}: ${delErr instanceof Error ? delErr.message : String(delErr)}`,
-                    );
-                    supersededId = undefined; // Don't report supersession if delete failed
-                  }
-                }
-              }
-            }
-
-            // Build the document JSON that will be encrypted.
-            const doc = {
-              text: params.text,
-              metadata: {
-                type: memoryType,
-                importance: importance / 10, // normalise to 0-1 range
-                source: 'explicit',
-                created_at: new Date().toISOString(),
-              },
-            };
-
-            // Encrypt the document.
-            const encryptedBlob = encryptToHex(JSON.stringify(doc), encryptionKey!);
-
-            // Generate content fingerprint for dedup.
-            const contentFp = generateContentFingerprint(params.text, dedupKey!);
-
-            // Generate a unique fact ID.
-            const factId = crypto.randomUUID();
+            // v1 taxonomy: route explicit remembers through the same canonical
+            // store path that auto-extraction uses (`storeExtractedFacts`). This
+            // emits a Memory Taxonomy v1 JSON blob, generates entity trapdoors,
+            // and runs through the Phase 2 contradiction-resolution pipeline.
+            //
+            // Accept legacy v0 tokens on input and coerce to v1 via
+            // `normalizeToV1Type` so agents that still emit the pre-v3
+            // taxonomy keep working.
+            const rawType = typeof params.type === 'string' ? params.type.toLowerCase() : 'claim';
+            const memoryType: MemoryType = isValidMemoryType(rawType)
+              ? rawType
+              : normalizeToV1Type(rawType);
+
+            // Source defaults to 'user' for explicit remembers (the user is
+            // the author by definition). Ignored if the caller passes an
+            // invalid value.
+            const rawSource = typeof params.source === 'string' ? params.source.toLowerCase() : 'user';
+            const memorySource: MemorySource =
+              (VALID_MEMORY_SOURCES as readonly string[]).includes(rawSource)
+                ? (rawSource as MemorySource)
+                : 'user';
+
+            const rawScope = typeof params.scope === 'string' ? params.scope.toLowerCase() : 'unspecified';
+            const memoryScope: MemoryScope =
+              (VALID_MEMORY_SCOPES as readonly string[]).includes(rawScope)
+                ? (rawScope as MemoryScope)
+                : 'unspecified';
+
+            const reasoning =
+              typeof params.reasoning === 'string' && params.reasoning.length > 0
+                ? params.reasoning.slice(0, 256)
+                : undefined;
+
+            // Explicit remember defaults to importance 8 (above auto-extraction's
+            // typical 6-7), so store-time dedup's shouldSupersede prefers the
+            // explicit call when it collides with an auto-extracted claim.
+            const importance = Math.max(1, Math.min(10, params.importance ?? 8));
+
+            const validatedEntities: ExtractedEntity[] = Array.isArray(params.entities)
+              ? params.entities
+                  .map((e) => parseEntity(e))
+                  .filter((e): e is ExtractedEntity => e !== null)
+              : [];
 
-            // Build the payload matching the server's FactJSON schema.
-            const factPayload: StoreFactPayload = {
-              id: factId,
-              timestamp: new Date().toISOString(),
-              encrypted_blob: encryptedBlob,
-              blind_indices: allIndices,
-              decay_score: importance,
-              source: 'explicit',
-              content_fp: contentFp,
-              agent_id: 'openclaw-plugin',
-              encrypted_embedding: embeddingResult?.encryptedEmbedding,
+            const fact: ExtractedFact = {
+              text: params.text.slice(0, 512),
+              type: memoryType,
+              source: memorySource,
+              scope: memoryScope,
+              reasoning,
+              importance,
+              action: 'ADD',
+              confidence: 1.0, // user explicitly asked to remember — highest confidence
             };
+            if (validatedEntities.length > 0) fact.entities = validatedEntities;
 
-            if (isSubgraphMode()) {
-              // Subgraph mode: encode as Protobuf and submit on-chain via relay UserOp
-              const config = { ...getSubgraphConfig(), authKeyHex: authKeyHex!, walletAddress: subgraphOwner ?? undefined };
-              const protobuf = encodeFactProtobuf({
-                id: factId,
-                timestamp: new Date().toISOString(),
-                owner: subgraphOwner || userId!,
-                encryptedBlob: encryptedBlob,
-                blindIndices: allIndices,
-                decayScore: importance,
-                source: 'explicit',
-                contentFp: contentFp,
-                agentId: 'openclaw-plugin',
-                encryptedEmbedding: embeddingResult?.encryptedEmbedding,
-              });
-              await submitFactOnChain(protobuf, config);
-            } else {
-              await apiClient!.store(userId!, [factPayload], authKeyHex!);
-            }
+            const stored = await storeExtractedFacts([fact], api.logger, 'explicit');
+            api.logger.info(
+              `totalreclaw_remember: routed to storeExtractedFacts (stored=${stored}, entities=${validatedEntities.length})`,
+            );
 
-            const statusMsg = supersededId
-              ? `Memory stored (ID: ${factId}). Superseded an older similar memory.`
-              : `Memory stored (ID: ${factId})`;
+            if (stored === 0) {
+              // Dedup or supersession consumed the write. Treat as success from
+              // the user's perspective — the memory's content is already in the
+              // vault (possibly under a different ID).
+              return {
+                content: [
+                  {
+                    type: 'text',
+                    text: 'Memory noted (matched existing content in vault).',
+                  },
+                ],
+              };
+            }
 
             return {
-              content: [{ type: 'text', text: statusMsg }],
-              details: { factId, supersededId },
+              content: [{ type: 'text', text: 'Memory encrypted and stored.' }],
             };
           } catch (err: unknown) {
             const message = err instanceof Error ? err.message : String(err);
             api.logger.error(`totalreclaw_remember failed: ${message}`);
             return {
-              content: [{ type: 'text', text: `Failed to store memory: ${message}` }],
+              content: [{ type: 'text', text: `Failed to store memory: ${humanizeError(message)}` }],
             };
           }
         },
@@ -1674,12 +2772,27 @@ const plugin = {
               // --- Subgraph search path ---
               const factCount = await getSubgraphFactCount(subgraphOwner || userId!, authKeyHex!);
               const pool = computeCandidatePool(factCount);
-              const subgraphResults = await searchSubgraph(subgraphOwner || userId!, allTrapdoors, pool, authKeyHex!);
+              let subgraphResults = await searchSubgraph(subgraphOwner || userId!, allTrapdoors, pool, authKeyHex!);
+
+              // Always run broadened search and merge — ensures vocabulary mismatches
+              // (e.g., "preferences" vs "prefer") don't cause recall failures.
+              // The reranker handles scoring; extra cost is ~1 GraphQL query per recall.
+              try {
+                const broadenedResults = await searchSubgraphBroadened(subgraphOwner || userId!, pool, authKeyHex!);
+                // Merge broadened results with existing (deduplicate by ID)
+                const existingIds = new Set(subgraphResults.map(r => r.id));
+                for (const br of broadenedResults) {
+                  if (!existingIds.has(br.id)) {
+                    subgraphResults.push(br);
+                  }
+                }
+              } catch { /* best-effort */ }
 
               for (const result of subgraphResults) {
                 try {
                   const docJson = decryptFromHex(result.encryptedBlob, encryptionKey!);
-                  const doc = JSON.parse(docJson) as { text: string; metadata?: Record<string, unknown> };
+                  if (isDigestBlob(docJson)) continue;
+                  const doc = readClaimFromBlob(docJson);
 
                   let decryptedEmbedding: number[] | undefined;
                   if (result.encryptedEmbedding) {
@@ -1692,17 +2805,29 @@ const plugin = {
                     }
                   }
 
+                  if (decryptedEmbedding && decryptedEmbedding.length !== getEmbeddingDims()) {
+                    try {
+                      decryptedEmbedding = await generateEmbedding(doc.text);
+                    } catch {
+                      decryptedEmbedding = undefined;
+                    }
+                  }
+
                   rerankerCandidates.push({
                     id: result.id,
                     text: doc.text,
                     embedding: decryptedEmbedding,
-                    importance: (doc.metadata?.importance as number) ?? 0.5,
+                    importance: doc.importance / 10,
                     createdAt: result.timestamp ? parseInt(result.timestamp, 10) : undefined,
+                    // Retrieval v2 Tier 1: surface v1 source so applySourceWeights
+                    // can multiply the final RRF score by the source weight.
+                    source: typeof doc.metadata?.source === 'string' ? doc.metadata.source : undefined,
                   });
 
                   metaMap.set(result.id, {
                     metadata: doc.metadata ?? {},
-                    timestamp: Date.now(), // Subgraph doesn't return ms timestamp; use current
+                    timestamp: Date.now(),
+                    category: doc.category,
                   });
                 } catch {
                   // Skip candidates we cannot decrypt.
@@ -1745,7 +2870,8 @@ const plugin = {
               for (const candidate of candidates) {
                 try {
                   const docJson = decryptFromHex(candidate.encrypted_blob, encryptionKey!);
-                  const doc = JSON.parse(docJson) as { text: string; metadata?: Record<string, unknown> };
+                  if (isDigestBlob(docJson)) continue;
+                  const doc = readClaimFromBlob(docJson);
 
                   let decryptedEmbedding: number[] | undefined;
                   if (candidate.encrypted_embedding) {
@@ -1758,19 +2884,29 @@ const plugin = {
                     }
                   }
 
+                  if (decryptedEmbedding && decryptedEmbedding.length !== getEmbeddingDims()) {
+                    try {
+                      decryptedEmbedding = await generateEmbedding(doc.text);
+                    } catch {
+                      decryptedEmbedding = undefined;
+                    }
+                  }
+
                   rerankerCandidates.push({
                     id: candidate.fact_id,
                     text: doc.text,
                     embedding: decryptedEmbedding,
-                    importance: (doc.metadata?.importance as number) ?? 0.5,
+                    importance: doc.importance / 10,
                     createdAt: typeof candidate.timestamp === 'number'
                       ? candidate.timestamp / 1000
                       : new Date(candidate.timestamp).getTime() / 1000,
+                    source: typeof doc.metadata?.source === 'string' ? doc.metadata.source : undefined,
                   });
 
                   metaMap.set(candidate.fact_id, {
                     metadata: doc.metadata ?? {},
                     timestamp: candidate.timestamp,
+                    category: doc.category,
                   });
                 } catch {
                   // Skip candidates we cannot decrypt (e.g. corrupted data).
@@ -1786,6 +2922,7 @@ const plugin = {
               rerankerCandidates,
               k,
               INTENT_WEIGHTS[queryIntent],
+              /* applySourceWeights (Retrieval v2 Tier 1) */ true,
             );
 
             if (reranked.length === 0) {
@@ -1817,7 +2954,8 @@ const plugin = {
                 ? ` (importance: ${Math.round((meta.metadata.importance as number) * 10)}/10)`
                 : '';
               const age = meta ? relativeTime(meta.timestamp) : '';
-              return `${i + 1}. ${m.text}${imp} -- ${age} [ID: ${m.id}]`;
+              const typeTag = meta?.category ? `[${meta.category}] ` : '';
+              return `${i + 1}. ${typeTag}${m.text}${imp} -- ${age} [ID: ${m.id}]`;
             });
 
             const formatted = lines.join('\n');
@@ -1836,7 +2974,7 @@ const plugin = {
             const message = err instanceof Error ? err.message : String(err);
             api.logger.error(`totalreclaw_recall failed: ${message}`);
             return {
-              content: [{ type: 'text', text: `Failed to search memories: ${message}` }],
+              content: [{ type: 'text', text: `Failed to search memories: ${humanizeError(message)}` }],
             };
           }
         },
@@ -1882,9 +3020,13 @@ const plugin = {
                 source: 'tombstone',
                 contentFp: '',
                 agentId: 'openclaw-plugin',
+                version: PROTOBUF_VERSION_V4,
               };
               const protobuf = encodeFactProtobuf(tombstone);
               const result = await submitFactOnChain(protobuf, config);
+              if (!result.success) {
+                throw new Error(`On-chain tombstone failed (tx=${result.txHash?.slice(0, 10) || 'none'}…)`);
+              }
               api.logger.info(`Tombstone written for ${params.factId}: tx=${result.txHash}`);
               return {
                 content: [{ type: 'text', text: `Memory ${params.factId} deleted (on-chain tombstone, tx: ${result.txHash})` }],
@@ -1901,7 +3043,7 @@ const plugin = {
             const message = err instanceof Error ? err.message : String(err);
             api.logger.error(`totalreclaw_forget failed: ${message}`);
             return {
-              content: [{ type: 'text', text: `Failed to delete memory: ${message}` }],
+              content: [{ type: 'text', text: `Failed to delete memory: ${humanizeError(message)}` }],
             };
           }
         },
@@ -1945,16 +3087,22 @@ const plugin = {
             }> = [];
 
             if (isSubgraphMode()) {
-              // Query subgraph for all active facts
+              // Query subgraph for all active facts (cursor-based pagination via id_gt)
               const config = getSubgraphConfig();
               const relayUrl = config.relayUrl;
               const PAGE_SIZE = 1000;
-              let skip = 0;
-              let hasMore = true;
+              let lastId = '';
               const owner = subgraphOwner || userId || '';
+              console.error(`[TotalReclaw Export] owner=${owner} subgraphOwner=${subgraphOwner} userId=${userId} relayUrl=${relayUrl} authKey=${authKeyHex ? authKeyHex.slice(0, 8) + '...' : 'MISSING'} isSubgraph=${isSubgraphMode()}`);
 
-              while (hasMore) {
-                const query = `{ facts(where: { owner: "${owner}", isActive: true }, first: ${PAGE_SIZE}, skip: ${skip}, orderBy: sequenceId, orderDirection: asc) { id encryptedBlob source agentId timestamp sequenceId } }`;
+              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 encryptedBlob timestamp sequenceId}}`
+                  : `query($owner:Bytes!,$first:Int!){facts(where:{owner:$owner,isActive:true},first:$first,orderBy:id,orderDirection:asc){id encryptedBlob timestamp sequenceId}}`;
+                const variables: Record<string, unknown> = hasLastId
+                  ? { owner, first: PAGE_SIZE, lastId }
+                  : { owner, first: PAGE_SIZE };
 
                 const res = await fetch(`${relayUrl}/v1/subgraph`, {
                   method: 'POST',
@@ -1963,24 +3111,36 @@ const plugin = {
                     'X-TotalReclaw-Client': 'openclaw-plugin',
                     ...(authKeyHex ? { Authorization: `Bearer ${authKeyHex}` } : {}),
                   },
-                  body: JSON.stringify({ query }),
+                  body: JSON.stringify({ query, variables }),
                 });
 
                 const json = (await res.json()) as {
                   data?: { facts?: Array<{ id: string; encryptedBlob: string; source: string; agentId: string; timestamp: string; sequenceId: string }> };
+                  error?: string;
+                  errors?: Array<{ message: string }>;
                 };
+                // Surface relay/subgraph errors instead of silently returning empty
+                if (json.error || json.errors) {
+                  const errMsg = json.error || json.errors?.map(e => e.message).join('; ') || 'Unknown error';
+                  api.logger.error(`Export subgraph query failed: ${errMsg} (owner=${owner}, status=${res.status})`);
+                  return {
+                    content: [{ type: 'text', text: `Export failed: ${errMsg}` }],
+                  };
+                }
                 const facts = json?.data?.facts || [];
+                if (facts.length === 0) break;
 
                 for (const fact of facts) {
                   try {
                     let hexBlob = fact.encryptedBlob;
                     if (hexBlob.startsWith('0x')) hexBlob = hexBlob.slice(2);
                     const docJson = decryptFromHex(hexBlob, encryptionKey!);
-                    const doc = JSON.parse(docJson) as { text: string; metadata?: Record<string, unknown> };
+                    if (isDigestBlob(docJson)) continue;
+                    const doc = readClaimFromBlob(docJson);
                     allFacts.push({
                       id: fact.id,
                       text: doc.text,
-                      metadata: doc.metadata ?? {},
+                      metadata: doc.metadata,
                       created_at: new Date(parseInt(fact.timestamp) * 1000).toISOString(),
                     });
                   } catch {
@@ -1988,8 +3148,8 @@ const plugin = {
                   }
                 }
 
-                skip += PAGE_SIZE;
-                hasMore = facts.length === PAGE_SIZE;
+                if (facts.length < PAGE_SIZE) break;
+                lastId = facts[facts.length - 1].id;
               }
             } else {
               // HTTP server mode — paginate through PostgreSQL facts
@@ -2002,11 +3162,12 @@ const plugin = {
                 for (const fact of page.facts) {
                   try {
                     const docJson = decryptFromHex(fact.encrypted_blob, encryptionKey!);
-                    const doc = JSON.parse(docJson) as { text: string; metadata?: Record<string, unknown> };
+                    if (isDigestBlob(docJson)) continue;
+                    const doc = readClaimFromBlob(docJson);
                     allFacts.push({
                       id: fact.id,
                       text: doc.text,
-                      metadata: doc.metadata ?? {},
+                      metadata: doc.metadata,
                       created_at: fact.created_at,
                     });
                   } catch {
@@ -2048,7 +3209,7 @@ const plugin = {
             const message = err instanceof Error ? err.message : String(err);
             api.logger.error(`totalreclaw_export failed: ${message}`);
             return {
-              content: [{ type: 'text', text: `Failed to export memories: ${message}` }],
+              content: [{ type: 'text', text: `Failed to export memories: ${humanizeError(message)}` }],
             };
           }
         },
@@ -2081,7 +3242,7 @@ const plugin = {
               };
             }
 
-            const serverUrl = (process.env.TOTALRECLAW_SERVER_URL || 'https://api.totalreclaw.xyz').replace(/\/+$/, '');
+            const serverUrl = CONFIG.serverUrl;
             const walletAddr = subgraphOwner || userId || '';
             const response = await fetch(`${serverUrl}/v1/billing/status?wallet_address=${encodeURIComponent(walletAddr)}`, {
               method: 'GET',
@@ -2134,7 +3295,7 @@ const plugin = {
             const message = err instanceof Error ? err.message : String(err);
             api.logger.error(`totalreclaw_status failed: ${message}`);
             return {
-              content: [{ type: 'text', text: `Failed to check status: ${message}` }],
+              content: [{ type: 'text', text: `Failed to check status: ${humanizeError(message)}` }],
             };
           }
         },
@@ -2151,13 +3312,13 @@ const plugin = {
         name: 'totalreclaw_consolidate',
         label: 'Consolidate',
         description:
-          'Scan all stored memories and merge near-duplicates. Keeps the most important/recent version and removes redundant copies.',
+          'Deduplicate and merge related memories. Self-hosted mode only.',
         parameters: {
           type: 'object',
           properties: {
             dry_run: {
               type: 'boolean',
-              description: 'Preview consolidation without deleting (default: false)',
+              description: 'Preview only (default: false)',
             },
           },
           additionalProperties: false,
@@ -2194,11 +3355,10 @@ const plugin = {
               for (const fact of page.facts) {
                 try {
                   const docJson = decryptFromHex(fact.encrypted_blob, encryptionKey);
-                  const doc = JSON.parse(docJson) as { text: string; metadata?: Record<string, unknown> };
+                  if (isDigestBlob(docJson)) continue;
+                  const doc = readClaimFromBlob(docJson);
 
                   let embedding: number[] | null = null;
-                  // ExportedFact does not include encrypted_embedding — generate it on-the-fly.
-                  // For consolidation we need embeddings, so generate them.
                   try {
                     embedding = await generateEmbedding(doc.text);
                   } catch { /* skip — fact will not be clustered */ }
@@ -2207,9 +3367,7 @@ const plugin = {
                     id: fact.id,
                     text: doc.text,
                     embedding,
-                    importance: doc.metadata?.importance
-                      ? Math.round((doc.metadata.importance as number) * 10)
-                      : 5,
+                    importance: doc.importance,
                     decayScore: fact.decay_score,
                     createdAt: new Date(fact.created_at).getTime(),
                     version: fact.version,
@@ -2291,7 +3449,7 @@ const plugin = {
             const message = err instanceof Error ? err.message : String(err);
             api.logger.error(`totalreclaw_consolidate failed: ${message}`);
             return {
-              content: [{ type: 'text', text: `Failed to consolidate memories: ${message}` }],
+              content: [{ type: 'text', text: `Failed to consolidate memories: ${humanizeError(message)}` }],
             };
           }
         },
@@ -2299,6 +3457,205 @@ const plugin = {
       { name: 'totalreclaw_consolidate' },
     );
 
+    // ---------------------------------------------------------------
+    // Helper: build PinOpDeps bound to the live plugin state
+    // ---------------------------------------------------------------
+    // Wires the pure pin/unpin operation to the managed-service transport +
+    // crypto layer. Mirrors MCP's buildPinDepsFromState and Python's
+    // _change_claim_status argument plumbing.
+    const buildPinDeps = (): PinOpDeps => {
+      const owner = subgraphOwner || userId || '';
+      const config = {
+        ...getSubgraphConfig(),
+        authKeyHex: authKeyHex!,
+        walletAddress: subgraphOwner ?? undefined,
+      };
+      return {
+        owner,
+        sourceAgent: 'openclaw-plugin',
+        fetchFactById: (factId: string) => fetchFactById(owner, factId, authKeyHex!),
+        decryptBlob: (hex: string) => decryptFromHex(hex, encryptionKey!),
+        encryptBlob: (plaintext: string) => encryptToHex(plaintext, encryptionKey!),
+        submitBatch: async (payloads: Buffer[]) => {
+          const result = await submitFactBatchOnChain(payloads, config);
+          return { txHash: result.txHash, success: result.success };
+        },
+        generateIndices: async (text: string, entityNames: string[]) => {
+          if (!text) return { blindIndices: [] };
+          const wordIndices = generateBlindIndices(text);
+          let lshIndices: string[] = [];
+          let encryptedEmbedding: string | undefined;
+          try {
+            const embedding = await generateEmbedding(text);
+            const hasher = getLSHHasher(api.logger);
+            if (hasher) lshIndices = hasher.hash(embedding);
+            encryptedEmbedding = encryptToHex(JSON.stringify(embedding), encryptionKey!);
+          } catch {
+            // Best-effort: word + entity trapdoors alone still surface the claim.
+          }
+          const entityTrapdoors = entityNames.map((n) => computeEntityTrapdoor(n));
+          return {
+            blindIndices: [...wordIndices, ...lshIndices, ...entityTrapdoors],
+            encryptedEmbedding,
+          };
+        },
+      };
+    };
+
+    // ---------------------------------------------------------------
+    // Tool: totalreclaw_pin
+    // ---------------------------------------------------------------
+
+    api.registerTool(
+      {
+        name: 'totalreclaw_pin',
+        label: 'Pin',
+        description:
+          'Pin a memory so the auto-resolution engine will never override or supersede it. ' +
+          "Use when the user explicitly confirms a claim is still valid after you or another agent " +
+          "tried to retract/contradict it (e.g. 'wait, I still use Vim sometimes'). " +
+          'Takes fact_id (from a prior recall result). Pinning is idempotent — pinning an already-pinned ' +
+          'claim is a no-op. Cross-device: the pin propagates via the on-chain supersession chain.',
+        parameters: {
+          type: 'object',
+          properties: {
+            fact_id: {
+              type: 'string',
+              description: 'The ID of the fact to pin (from a totalreclaw_recall result).',
+            },
+            reason: {
+              type: 'string',
+              description: 'Optional human-readable reason for pinning (logged locally for tuning).',
+            },
+          },
+          required: ['fact_id'],
+          additionalProperties: false,
+        },
+        async execute(_toolCallId: string, params: Record<string, unknown>) {
+          try {
+            await requireFullSetup(api.logger);
+            if (!isSubgraphMode()) {
+              return {
+                content: [{
+                  type: 'text',
+                  text: 'Pin/unpin is only supported with the managed service. Self-hosted mode does not yet implement the status-flip supersession flow.',
+                }],
+              };
+            }
+            const validation = validatePinArgs(params);
+            if (!validation.ok) {
+              return { content: [{ type: 'text', text: validation.error }] };
+            }
+            const deps = buildPinDeps();
+            const result = await executePinOperation(validation.factId, 'pinned', deps, validation.reason);
+            if (result.success && result.idempotent) {
+              api.logger.info(`totalreclaw_pin: ${result.fact_id} already pinned (no-op)`);
+              return {
+                content: [{ type: 'text', text: `Memory ${result.fact_id} is already pinned.` }],
+                details: result,
+              };
+            }
+            if (result.success) {
+              api.logger.info(`totalreclaw_pin: ${result.fact_id} → ${result.new_fact_id} (tx ${result.tx_hash?.slice(0, 10)})`);
+              return {
+                content: [{
+                  type: 'text',
+                  text: `Pinned memory ${result.fact_id}. New fact id: ${result.new_fact_id} (tx: ${result.tx_hash}).`,
+                }],
+                details: result,
+              };
+            }
+            api.logger.error(`totalreclaw_pin failed: ${result.error}`);
+            return {
+              content: [{ type: 'text', text: `Failed to pin memory: ${humanizeError(result.error ?? 'unknown error')}` }],
+              details: result,
+            };
+          } catch (err: unknown) {
+            const message = err instanceof Error ? err.message : String(err);
+            api.logger.error(`totalreclaw_pin failed: ${message}`);
+            return {
+              content: [{ type: 'text', text: `Failed to pin memory: ${humanizeError(message)}` }],
+            };
+          }
+        },
+      },
+      { name: 'totalreclaw_pin' },
+    );
+
+    // ---------------------------------------------------------------
+    // Tool: totalreclaw_unpin
+    // ---------------------------------------------------------------
+
+    api.registerTool(
+      {
+        name: 'totalreclaw_unpin',
+        label: 'Unpin',
+        description:
+          'Remove the pin from a previously pinned memory, returning it to active status so the ' +
+          'auto-resolution engine can supersede or retract it again. Takes fact_id. Idempotent — ' +
+          'unpinning a non-pinned claim is a no-op.',
+        parameters: {
+          type: 'object',
+          properties: {
+            fact_id: {
+              type: 'string',
+              description: 'The ID of the fact to unpin (from a totalreclaw_recall result).',
+            },
+          },
+          required: ['fact_id'],
+          additionalProperties: false,
+        },
+        async execute(_toolCallId: string, params: Record<string, unknown>) {
+          try {
+            await requireFullSetup(api.logger);
+            if (!isSubgraphMode()) {
+              return {
+                content: [{
+                  type: 'text',
+                  text: 'Pin/unpin is only supported with the managed service. Self-hosted mode does not yet implement the status-flip supersession flow.',
+                }],
+              };
+            }
+            const validation = validatePinArgs(params);
+            if (!validation.ok) {
+              return { content: [{ type: 'text', text: validation.error }] };
+            }
+            const deps = buildPinDeps();
+            const result = await executePinOperation(validation.factId, 'active', deps);
+            if (result.success && result.idempotent) {
+              api.logger.info(`totalreclaw_unpin: ${result.fact_id} already active (no-op)`);
+              return {
+                content: [{ type: 'text', text: `Memory ${result.fact_id} is not pinned.` }],
+                details: result,
+              };
+            }
+            if (result.success) {
+              api.logger.info(`totalreclaw_unpin: ${result.fact_id} → ${result.new_fact_id} (tx ${result.tx_hash?.slice(0, 10)})`);
+              return {
+                content: [{
+                  type: 'text',
+                  text: `Unpinned memory ${result.fact_id}. New fact id: ${result.new_fact_id} (tx: ${result.tx_hash}).`,
+                }],
+                details: result,
+              };
+            }
+            api.logger.error(`totalreclaw_unpin failed: ${result.error}`);
+            return {
+              content: [{ type: 'text', text: `Failed to unpin memory: ${humanizeError(result.error ?? 'unknown error')}` }],
+              details: result,
+            };
+          } catch (err: unknown) {
+            const message = err instanceof Error ? err.message : String(err);
+            api.logger.error(`totalreclaw_unpin failed: ${message}`);
+            return {
+              content: [{ type: 'text', text: `Failed to unpin memory: ${humanizeError(message)}` }],
+            };
+          }
+        },
+      },
+      { name: 'totalreclaw_unpin' },
+    );
+
     // ---------------------------------------------------------------
     // Tool: totalreclaw_import_from
     // ---------------------------------------------------------------
@@ -2308,16 +3665,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, Gemini, 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', 'gemini', 'memoclaw', 'generic-json', 'generic-csv'],
+              description: 'The source system to import from (gemini: Google Takeout HTML; chatgpt: conversations.json or memory text; claude: memory text)',
             },
             api_key: {
               type: 'string',
@@ -2359,6 +3716,56 @@ const plugin = {
       { name: 'totalreclaw_import_from' },
     );
 
+    // ---------------------------------------------------------------
+    // Tool: totalreclaw_import_batch
+    // ---------------------------------------------------------------
+
+    api.registerTool(
+      {
+        name: 'totalreclaw_import_batch',
+        label: 'Import Batch',
+        description:
+          'Process one batch of a large import. Call repeatedly with increasing offset until is_complete=true.',
+        parameters: {
+          type: 'object',
+          properties: {
+            source: {
+              type: 'string',
+              enum: ['gemini', 'chatgpt', 'claude'],
+              description: 'Source format',
+            },
+            file_path: {
+              type: 'string',
+              description: 'Path to source file',
+            },
+            content: {
+              type: 'string',
+              description: 'File content (text sources)',
+            },
+            offset: {
+              type: 'number',
+              description: 'Starting chunk index (0-based)',
+            },
+            batch_size: {
+              type: 'number',
+              description: 'Chunks per call (default 25)',
+            },
+          },
+          required: ['source'],
+        },
+        async execute(_toolCallId: string, params: Record<string, unknown>) {
+          try {
+            await requireFullSetup(api.logger);
+            return handleBatchImport(params, api.logger);
+          } catch (err: unknown) {
+            const message = err instanceof Error ? err.message : String(err);
+            return { error: message };
+          }
+        },
+      },
+      { name: 'totalreclaw_import_batch' },
+    );
+
     // ---------------------------------------------------------------
     // Tool: totalreclaw_upgrade
     // ---------------------------------------------------------------
@@ -2385,7 +3792,7 @@ const plugin = {
               };
             }
 
-            const serverUrl = (process.env.TOTALRECLAW_SERVER_URL || 'https://api.totalreclaw.xyz').replace(/\/+$/, '');
+            const serverUrl = CONFIG.serverUrl;
             const walletAddr = subgraphOwner || userId || '';
 
             if (!walletAddr) {
@@ -2430,7 +3837,7 @@ const plugin = {
             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}` }],
+              content: [{ type: 'text', text: `Failed to create checkout session: ${humanizeError(message)}` }],
             };
           }
         },
@@ -2477,7 +3884,7 @@ const plugin = {
             }
 
             const confirm = _params?.confirm === true;
-            const serverUrl = (process.env.TOTALRECLAW_SERVER_URL || 'https://api.totalreclaw.xyz').replace(/\/+$/, '');
+            const serverUrl = CONFIG.serverUrl;
 
             // 1. Check billing tier
             const billingResp = await fetch(
@@ -2564,6 +3971,7 @@ const plugin = {
                 contentFp: fact.contentFp || '',
                 agentId: fact.agentId || 'openclaw-plugin',
                 encryptedEmbedding: fact.encryptedEmbedding || undefined,
+                version: PROTOBUF_VERSION_V4,
               };
               payloads.push(encodeFactProtobuf(factPayload));
             }
@@ -2613,7 +4021,7 @@ const plugin = {
             const message = err instanceof Error ? err.message : String(err);
             api.logger.error(`totalreclaw_migrate failed: ${message}`);
             return {
-              content: [{ type: 'text', text: `Migration failed: ${message}` }],
+              content: [{ type: 'text', text: `Migration failed: ${humanizeError(message)}` }],
             };
           }
         },
@@ -2621,6 +4029,107 @@ const plugin = {
       { name: 'totalreclaw_migrate' },
     );
 
+    // ---------------------------------------------------------------
+    // Tool: totalreclaw_setup
+    // ---------------------------------------------------------------
+
+    api.registerTool(
+      {
+        name: 'totalreclaw_setup',
+        label: 'Setup TotalReclaw',
+        description:
+          'Initialize TotalReclaw with a recovery phrase. Derives encryption keys and registers with the server. ' +
+          'Use this during first-time setup instead of setting environment variables — no gateway restart needed.',
+        parameters: {
+          type: 'object',
+          properties: {
+            recovery_phrase: {
+              type: 'string',
+              description: 'Optional 12-word BIP-39 recovery phrase. If not provided, generates a new one automatically. For returning users, pass their existing phrase.',
+            },
+          },
+          additionalProperties: false,
+        },
+        async execute(_toolCallId: string, params: { recovery_phrase?: string }) {
+          try {
+            let mnemonic = params.recovery_phrase?.trim() || '';
+
+            // Auto-generate if not provided
+            if (!mnemonic) {
+              const { generateMnemonic } = await import('@scure/bip39');
+              const { wordlist } = await import('@scure/bip39/wordlists/english');
+              mnemonic = generateMnemonic(wordlist, 128);
+              api.logger.info('totalreclaw_setup: generated new BIP-39 mnemonic');
+            }
+
+            // Guard: refuse to overwrite existing credentials with a DIFFERENT phrase
+            // (prevents data loss when background sessions_spawn workers call setup).
+            // Allow re-init with the SAME phrase (handles agent exec → setup flow).
+            try {
+              const existing = fs.readFileSync(CREDENTIALS_PATH, 'utf-8');
+              const creds = JSON.parse(existing);
+              if (creds.mnemonic && creds.userId && creds.mnemonic !== mnemonic) {
+                api.logger.info('totalreclaw_setup: credentials exist with different mnemonic, refusing to overwrite');
+                return {
+                  content: [{
+                    type: 'text',
+                    text: 'TotalReclaw is already set up with an existing recovery phrase. Your encrypted memories are tied to that phrase.\n\n' +
+                          'If you intentionally want to start fresh with a NEW phrase (this will make existing memories inaccessible), ' +
+                          'delete ~/.totalreclaw/credentials.json first, then call this tool again.',
+                  }],
+                };
+              }
+            } catch { /* credentials.json doesn't exist or is corrupted — proceed with setup */ }
+
+            // Basic validation: must be 12 words
+            const words = mnemonic.split(/\s+/);
+            if (words.length !== 12) {
+              return {
+                content: [{
+                  type: 'text',
+                  text: `Error: Recovery phrase must be exactly 12 words (got ${words.length}). Use \`npx @totalreclaw/mcp-server setup\` to generate a valid BIP-39 mnemonic.`,
+                }],
+              };
+            }
+
+            api.logger.info('totalreclaw_setup: initializing with provided recovery phrase');
+
+            // Force re-initialization with the new mnemonic.
+            // This derives keys, registers with the server, saves credentials,
+            // and sets up LSH/auth — all without a gateway restart.
+            await forceReinitialization(mnemonic, api.logger);
+
+            if (needsSetup) {
+              return {
+                content: [{
+                  type: 'text',
+                  text: 'Setup failed — could not initialize with the provided recovery phrase. Check the logs for details.',
+                }],
+              };
+            }
+
+            const wasGenerated = !params.recovery_phrase?.trim();
+            return {
+              content: [{
+                type: 'text',
+                text: 'TotalReclaw setup complete! Encryption keys derived, server registration confirmed. ' +
+                      'You can now use totalreclaw_remember, totalreclaw_recall, and all other tools immediately — no restart needed.\n\n' +
+                      (wasGenerated ? `Recovery phrase: ${mnemonic}\n\n` : '') +
+                      'From now on, I will automatically remember important things from our conversations and recall relevant context at the start of each session.',
+              }],
+            };
+          } catch (err: unknown) {
+            const message = err instanceof Error ? err.message : String(err);
+            api.logger.error(`totalreclaw_setup failed: ${message}`);
+            return {
+              content: [{ type: 'text', text: `Setup failed: ${humanizeError(message)}` }],
+            };
+          }
+        },
+      },
+      { name: 'totalreclaw_setup' },
+    );
+
     // ---------------------------------------------------------------
     // Hook: before_agent_start
     // ---------------------------------------------------------------
@@ -2641,21 +4150,37 @@ 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:** Run `npx @totalreclaw/mcp-server setup` to generate a cryptographically valid recovery phrase. Do NOT generate the phrase yourself — LLMs cannot compute BIP-39 checksums. The command will output the phrase. Then call the `totalreclaw_setup` tool with the phrase. Display the phrase 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, then call `totalreclaw_setup` with that phrase.\n\n' +
+                '**IMPORTANT:** Use the `totalreclaw_setup` tool to complete setup. This initializes encryption keys immediately — no gateway restart needed. The user can continue chatting right away.\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.
@@ -2664,7 +4189,7 @@ const plugin = {
             let cache = readBillingCache();
             if (!cache && authKeyHex) {
               // Cache is stale or missing — fetch fresh billing status.
-              const billingUrl = (process.env.TOTALRECLAW_SERVER_URL || 'https://api.totalreclaw.xyz').replace(/\/+$/, '');
+              const billingUrl = CONFIG.serverUrl;
               const walletParam = encodeURIComponent(subgraphOwner || userId || '');
               const billingResp = await fetch(`${billingUrl}/v1/billing/status?wallet_address=${walletParam}`, {
                 method: 'GET',
@@ -2693,7 +4218,46 @@ const plugin = {
           }
 
           if (isSubgraphMode()) {
-            // --- Subgraph mode: hot cache first, then background refresh ---
+            // --- Subgraph mode: digest fast path → hot cache → background refresh ---
+
+            // Digest fast path (Stage 3b). When a digest exists and the mode is
+            // not 'off', inject its pre-compiled promptText instead of running
+            // the per-query search. A stale digest triggers a background
+            // recompile (non-blocking). Failures fall through to the legacy
+            // path silently.
+            const digestMode = resolveDigestMode();
+            logDigestModeOnce(digestMode, api.logger);
+            if (digestMode !== 'off' && encryptionKey && authKeyHex && (subgraphOwner || userId)) {
+              try {
+                const injectResult = await maybeInjectDigest({
+                  owner: subgraphOwner || userId!,
+                  authKeyHex: authKeyHex!,
+                  encryptionKey: encryptionKey!,
+                  mode: digestMode,
+                  nowMs: Date.now(),
+                  loadDeps: {
+                    searchSubgraph: async (o, tds, n, a) => searchSubgraph(o, tds, n, a),
+                    decryptFromHex: (hex, key) => decryptFromHex(hex, key),
+                  },
+                  probeDeps: {
+                    searchSubgraphBroadened: async (o, n, a) => searchSubgraphBroadened(o, n, a),
+                  },
+                  recompileFn: (prev) => scheduleDigestRecompile(prev, api.logger),
+                  logger: api.logger,
+                });
+                if (injectResult.promptText) {
+                  api.logger.info(`Digest injection: state=${injectResult.state}`);
+                  return {
+                    prependContext:
+                      `## Your Memory\n\n${injectResult.promptText}` + welcomeBack + billingWarning,
+                  };
+                }
+              } catch (err) {
+                // Never block session start on digest failure.
+                const msg = err instanceof Error ? err.message : String(err);
+                api.logger.warn(`Digest fast path failed: ${msg}`);
+              }
+            }
 
             // Initialize hot cache if needed.
             if (!pluginHotCache && encryptionKey) {
@@ -2766,6 +4330,21 @@ const plugin = {
               return undefined;
             }
 
+            // Always run broadened search and merge — ensures vocabulary mismatches
+            // (e.g., "preferences" vs "prefer") don't cause recall failures.
+            // The reranker handles scoring; extra cost is ~1 GraphQL query per recall.
+            try {
+              const broadPool = computeCandidatePool(0);
+              const broadenedResults = await searchSubgraphBroadened(subgraphOwner || userId!, broadPool, authKeyHex!);
+              // Merge broadened results with existing (deduplicate by ID)
+              const existingIds = new Set(subgraphResults.map(r => r.id));
+              for (const br of broadenedResults) {
+                if (!existingIds.has(br.id)) {
+                  subgraphResults.push(br);
+                }
+              }
+            } catch { /* best-effort */ }
+
             if (subgraphResults.length === 0 && cachedFacts.length === 0) return undefined;
 
             // If subgraph returned no results but we have cache, use cache.
@@ -2783,7 +4362,10 @@ const plugin = {
             for (const result of subgraphResults) {
               try {
                 const docJson = decryptFromHex(result.encryptedBlob, encryptionKey!);
-                const doc = JSON.parse(docJson) as { text: string; metadata?: Record<string, unknown> };
+                // Filter out digest infrastructure blobs — they have no user
+                // text and should never surface in recall results.
+                if (isDigestBlob(docJson)) continue;
+                const doc = readClaimFromBlob(docJson);
 
                 let decryptedEmbedding: number[] | undefined;
                 if (result.encryptedEmbedding) {
@@ -2796,22 +4378,20 @@ const plugin = {
                   }
                 }
 
-                const importanceRaw = (doc.metadata?.importance as number) ?? 0.5;
                 const createdAtSec = result.timestamp ? parseInt(result.timestamp, 10) : undefined;
                 rerankerCandidates.push({
                   id: result.id,
                   text: doc.text,
                   embedding: decryptedEmbedding,
-                  importance: importanceRaw,
+                  importance: doc.importance / 10,
                   createdAt: createdAtSec,
+                  source: typeof doc.metadata?.source === 'string' ? doc.metadata.source : undefined,
                 });
 
-                const importance = doc.metadata?.importance
-                  ? Math.round((doc.metadata.importance as number) * 10)
-                  : 5;
                 hookMetaMap.set(result.id, {
-                  importance,
+                  importance: doc.importance,
                   age: 'subgraph',
+                  category: doc.category,
                 });
               } catch {
                 // Skip un-decryptable candidates.
@@ -2826,17 +4406,9 @@ const plugin = {
               rerankerCandidates,
               8,
               INTENT_WEIGHTS[hookQueryIntent],
+              /* applySourceWeights (Retrieval v2 Tier 1) */ true,
             );
 
-            // B2: Minimum relevance threshold — skip noise injection for irrelevant turns.
-            const candidatesWithEmb = rerankerCandidates.filter(c => c.embedding && c.embedding.length > 0);
-            if (candidatesWithEmb.length > 0 && queryEmbedding && queryEmbedding.length > 0) {
-              const topCosine = Math.max(
-                ...candidatesWithEmb.map(c => cosineSimilarity(queryEmbedding!, c.embedding!))
-              );
-              if (topCosine < RELEVANCE_THRESHOLD) return undefined;
-            }
-
             // Update hot cache with reranked results.
             try {
               if (pluginHotCache) {
@@ -2875,7 +4447,8 @@ const plugin = {
               const meta = hookMetaMap.get(m.id);
               const importance = meta?.importance ?? 5;
               const age = meta?.age ?? '';
-              return `${i + 1}. ${m.text} (importance: ${importance}/10, ${age})`;
+              const typeTag = meta?.category ? `[${meta.category}] ` : '';
+              return `${i + 1}. ${typeTag}${m.text} (importance: ${importance}/10, ${age})`;
             });
             const contextString = `## Relevant Memories\n\n${lines.join('\n')}`;
 
@@ -2923,9 +4496,10 @@ const plugin = {
           for (const candidate of candidates) {
             try {
               const docJson = decryptFromHex(candidate.encrypted_blob, encryptionKey!);
-              const doc = JSON.parse(docJson) as { text: string; metadata?: Record<string, unknown> };
+              // Skip digest infrastructure blobs.
+              if (isDigestBlob(docJson)) continue;
+              const doc = readClaimFromBlob(docJson);
 
-              // Decrypt embedding if present.
               let decryptedEmbedding: number[] | undefined;
               if (candidate.encrypted_embedding) {
                 try {
@@ -2937,7 +4511,6 @@ const plugin = {
                 }
               }
 
-              const importanceRaw = (doc.metadata?.importance as number) ?? 0.5;
               const createdAtSec = typeof candidate.timestamp === 'number'
                 ? candidate.timestamp / 1000
                 : new Date(candidate.timestamp).getTime() / 1000;
@@ -2945,15 +4518,13 @@ const plugin = {
                 id: candidate.fact_id,
                 text: doc.text,
                 embedding: decryptedEmbedding,
-                importance: importanceRaw,
+                importance: doc.importance / 10,
                 createdAt: createdAtSec,
+                source: typeof doc.metadata?.source === 'string' ? doc.metadata.source : undefined,
               });
 
-              const importance = doc.metadata?.importance
-                ? Math.round((doc.metadata.importance as number) * 10)
-                : 5;
               hookMetaMap.set(candidate.fact_id, {
-                importance,
+                importance: doc.importance,
                 age: relativeTime(candidate.timestamp),
               });
             } catch {
@@ -2969,19 +4540,23 @@ const plugin = {
             rerankerCandidates,
             8,
             INTENT_WEIGHTS[srvHookIntent],
-          );
-
-          // B2: Minimum relevance threshold — skip noise injection for irrelevant turns.
-          const candidatesWithEmbSrv = rerankerCandidates.filter(c => c.embedding && c.embedding.length > 0);
-          if (candidatesWithEmbSrv.length > 0 && queryEmbedding && queryEmbedding.length > 0) {
-            const topCosine = Math.max(
-              ...candidatesWithEmbSrv.map(c => cosineSimilarity(queryEmbedding!, c.embedding!))
+            /* applySourceWeights (Retrieval v2 Tier 1) */ true,
             );
-            if (topCosine < RELEVANCE_THRESHOLD) return undefined;
-          }
 
           if (reranked.length === 0) return undefined;
 
+          // Cosine similarity threshold gate — skip injection when the
+          // best match is below the minimum relevance threshold.
+          const srvMaxCosine = Math.max(
+            ...reranked.map((r) => r.cosineSimilarity ?? 0),
+          );
+          if (srvMaxCosine < COSINE_THRESHOLD) {
+            api.logger.info(
+              `Hook: cosine threshold gate filtered results (max=${srvMaxCosine.toFixed(3)}, threshold=${COSINE_THRESHOLD})`,
+            );
+            return undefined;
+          }
+
           // 7. Build context string.
           const lines = reranked.map((m, i) => {
             const meta = hookMetaMap.get(m.id);
@@ -3009,21 +4584,73 @@ const plugin = {
     api.on(
       'agent_end',
       async (event: unknown) => {
+        // CRITICAL: Always return { memoryHandled: true } so OpenClaw's default
+        // memory system does NOT fall back to writing plaintext MEMORY.md.
+        // Losing facts on error is acceptable; leaking them in cleartext is not.
         try {
+          // Defensive: ensure MEMORY.md header is present so OpenClaw's default
+          // memory system doesn't write sensitive data in cleartext, even if
+          // our extraction fails below.
+          ensureMemoryHeader(api.logger);
+
+          // BUG-2 fix: skip extraction if an import was in progress this turn.
+          // Import failures were retriggering agent_end → extraction → import loops.
+          if (_importInProgress) {
+            _importInProgress = false; // auto-reset for next turn
+            api.logger.info('agent_end: skipping extraction (import was in progress)');
+            return { memoryHandled: true };
+          }
+
           const evt = event as { messages?: unknown[]; success?: boolean } | undefined;
-          if (!evt?.success || !evt?.messages || evt.messages.length < 2) return;
+          if (!evt?.messages || evt.messages.length < 2) {
+            api.logger.info('agent_end: skipping extraction (no messages)');
+            return { memoryHandled: true };
+          }
+          // Proceed with extraction even when evt.success is false or undefined.
+          // A single LLM timeout on one turn should not prevent extraction of
+          // facts from the (potentially many) successful turns in the message
+          // history. The extractor processes the full message array and can
+          // extract valuable facts from content before the failure.
+          if (evt.success === false) {
+            api.logger.info('agent_end: turn reported failure, but proceeding with extraction from message history');
+          }
 
           await ensureInitialized(api.logger);
-          if (needsSetup) return;
+          if (needsSetup) return { memoryHandled: true };
 
           // C3: Throttle auto-extraction to every N turns (configurable via env).
+          // Phase 2.2.5: every branch of the extraction pipeline now logs its
+          // outcome. Prior to 2.2.5, only the "stored N facts" happy path
+          // produced a log line, so silent JSON parse failures / chatCompletion
+          // timeouts / importance-filter-drops-everything scenarios left no
+          // trace whatsoever in the gateway log. See the investigation report
+          // in CHANGELOG for the full failure chain we uncovered.
           turnsSinceLastExtraction++;
-          if (turnsSinceLastExtraction >= getExtractInterval()) {
+          const extractInterval = getExtractInterval();
+          api.logger.info(
+            `agent_end: turn ${turnsSinceLastExtraction}/${extractInterval} (messages=${evt.messages.length})`,
+          );
+          if (turnsSinceLastExtraction >= extractInterval) {
             const existingMemories = isLlmDedupEnabled()
               ? await fetchExistingMemoriesForExtraction(api.logger, 20, evt.messages)
               : [];
-            const rawFacts = await extractFacts(evt.messages, 'turn', existingMemories);
-            const { kept: importanceFiltered } = filterByImportance(rawFacts, api.logger);
+            const rawFacts = await extractFacts(
+              evt.messages,
+              'turn',
+              existingMemories,
+              undefined,
+              api.logger,
+            );
+            api.logger.info(
+              `agent_end: extractFacts returned ${rawFacts.length} raw facts`,
+            );
+            const { kept: importanceFiltered, dropped } = filterByImportance(
+              rawFacts,
+              api.logger,
+            );
+            api.logger.info(
+              `agent_end: after importance filter: kept=${importanceFiltered.length}, dropped=${dropped}`,
+            );
             const maxFacts = getMaxFactsPerExtraction();
             if (importanceFiltered.length > maxFacts) {
               api.logger.info(
@@ -3033,13 +4660,23 @@ const plugin = {
             const facts = importanceFiltered.slice(0, maxFacts);
             if (facts.length > 0) {
               await storeExtractedFacts(facts, api.logger);
+              api.logger.info(`agent_end: stored ${facts.length} facts to encrypted vault`);
+            } else {
+              // Phase 2.2.5: no longer silent when extraction produces nothing.
+              api.logger.info(
+                `agent_end: extraction produced 0 storable facts (raw=${rawFacts.length}, after-importance=${importanceFiltered.length})`,
+              );
             }
             turnsSinceLastExtraction = 0;
           }
         } catch (err: unknown) {
           const message = err instanceof Error ? err.message : String(err);
-          api.logger.warn(`agent_end extraction failed: ${message}`);
+          api.logger.error(`agent_end extraction failed: ${message}`);
+          // Re-assert MEMORY.md header even on failure — last line of defense.
+          ensureMemoryHeader(api.logger);
         }
+        // Always signal that memory is handled — prevent plaintext fallback.
+        return { memoryHandled: true };
       },
       { priority: 90 },
     );
@@ -3059,13 +4696,13 @@ const plugin = {
           if (needsSetup) return;
 
           api.logger.info(
-            `Pre-compaction extraction: processing ${evt.messages.length} messages`,
+            `pre_compaction: using compaction-aware extraction (importance >= 5), processing ${evt.messages.length} messages`,
           );
 
           const existingMemories = isLlmDedupEnabled()
             ? await fetchExistingMemoriesForExtraction(api.logger, 50, evt.messages)
             : [];
-          const rawCompactFacts = await extractFacts(evt.messages, 'full', existingMemories);
+          const rawCompactFacts = await extractFactsForCompaction(evt.messages, existingMemories, api.logger);
           const { kept: compactImportanceFiltered } = filterByImportance(rawCompactFacts, api.logger);
           const maxFactsCompact = getMaxFactsPerExtraction();
           if (compactImportanceFiltered.length > maxFactsCompact) {
@@ -3078,6 +4715,29 @@ const plugin = {
             await storeExtractedFacts(facts, api.logger);
           }
           turnsSinceLastExtraction = 0; // Reset C3 counter on compaction.
+
+          // Session debrief — after regular extraction.
+          // v1 mapping: DebriefItem { type: 'summary'|'context' } →
+          //   v1 type 'summary' (always, since context → claim would lose
+          //   the "this is a session summary" signal) + source 'derived'
+          //   (session debrief is a derived synthesis by definition).
+          try {
+            const storedTexts = facts.map((f) => f.text);
+            const debriefItems = await extractDebrief(evt.messages, storedTexts);
+            if (debriefItems.length > 0) {
+              const debriefFacts: ExtractedFact[] = debriefItems.map((d) => ({
+                text: d.text,
+                type: 'summary' as MemoryType,
+                source: 'derived' as MemorySource,
+                importance: d.importance,
+                action: 'ADD' as const,
+              }));
+              await storeExtractedFacts(debriefFacts, api.logger, 'openclaw_debrief');
+              api.logger.info(`Session debrief: stored ${debriefItems.length} items`);
+            }
+          } catch (debriefErr: unknown) {
+            api.logger.warn(`before_compaction debrief failed: ${debriefErr instanceof Error ? debriefErr.message : String(debriefErr)}`);
+          }
         } catch (err: unknown) {
           const message = err instanceof Error ? err.message : String(err);
           api.logger.warn(`before_compaction extraction failed: ${message}`);
@@ -3120,6 +4780,29 @@ const plugin = {
             await storeExtractedFacts(facts, api.logger);
           }
           turnsSinceLastExtraction = 0; // Reset C3 counter on reset.
+
+          // Session debrief — after regular extraction.
+          // v1 mapping: DebriefItem { type: 'summary'|'context' } →
+          //   v1 type 'summary' (always, since context → claim would lose
+          //   the "this is a session summary" signal) + source 'derived'
+          //   (session debrief is a derived synthesis by definition).
+          try {
+            const storedTexts = facts.map((f) => f.text);
+            const debriefItems = await extractDebrief(evt.messages, storedTexts);
+            if (debriefItems.length > 0) {
+              const debriefFacts: ExtractedFact[] = debriefItems.map((d) => ({
+                text: d.text,
+                type: 'summary' as MemoryType,
+                source: 'derived' as MemorySource,
+                importance: d.importance,
+                action: 'ADD' as const,
+              }));
+              await storeExtractedFacts(debriefFacts, api.logger, 'openclaw_debrief');
+              api.logger.info(`Session debrief: stored ${debriefItems.length} items`);
+            }
+          } catch (debriefErr: unknown) {
+            api.logger.warn(`before_reset debrief failed: ${debriefErr instanceof Error ? debriefErr.message : String(debriefErr)}`);
+          }
         } catch (err: unknown) {
           const message = err instanceof Error ? err.message : String(err);
           api.logger.warn(`before_reset extraction failed: ${message}`);