@digitalforgestudios/openclaw-sulcus 6.1.0 → 6.6.2

package/index.ts

@@ -554,6 +554,26 @@ let wasJustCompacted = false;
 // contextRebuild.tokenBudget (default 4000, max 10000).
 let REBUILD_TOKEN_BUDGET = 4000;
 
+// --- CORE MEMORY CACHE (Phase 3) -----------------------------------------------
+// Core memory is fetched once on first turn and cached for the session.
+// It's refreshed when the agent explicitly updates it via core_memory_update.
+// Max size enforced at ~4000 chars (~1000 tokens).
+const CORE_MEMORY_MAX_CHARS = 4000;
+let coreMemoryCache: Record<string, unknown> | null | undefined = undefined; // undefined = not fetched yet
+
+// --- MULTI-USER NAMESPACE SCOPING (Phase 6) -----------------------------------
+// Runtime namespace override — set by memory_namespace tool, cleared on session end.
+// When set, overrides the config-level namespace for all memory operations.
+let activeNamespaceOverride: string | null = null;
+
+/**
+ * Phase 6: Return the effective namespace, preferring any runtime override
+ * set by the `memory_namespace` tool over the config-level default.
+ */
+function getEffectiveNamespace(configNamespace: string): string {
+  return activeNamespaceOverride ?? configNamespace;
+}
+
 // --- HOOK PROFILE STATE (Task 31) --------------------------------------------
 // Per-namespace profile cache for the auto_recall hook.
 // Mirrors the SDK recall handler: inject full profile on turn 1 + every N turns,
@@ -578,6 +598,8 @@ const hookHandlers: Record<string, HookHandler> = {
     // Task 31: Profile injection frequency — full profile on turn 1 + every N turns.
     const { sulcusMem, namespace, logger } = ctx;
     if (!sulcusMem) return;
+    // Phase 6: Multi-user namespace scoping — runtime override takes precedence
+    const effectiveNamespace = getEffectiveNamespace(namespace);
     const agentLabel = (event?.agentId as string) ?? "(unknown)";
     logger.info(`sulcus: auto_recall hook triggered for agent ${agentLabel}`);
     const rawPrompt = typeof event?.prompt === "string" ? event.prompt : "";
@@ -595,10 +617,10 @@ const hookHandlers: Record<string, HookHandler> = {
       // (prefs + facts) on turn 1 and every profileFrequency turns; serve
       // cache on stable turns to avoid redundant API calls.
       const profileFreq = ctx.profileFrequency ?? 10;
-      let hookProfileState = hookProfileStateMap.get(namespace);
+      let hookProfileState = hookProfileStateMap.get(effectiveNamespace);
       if (!hookProfileState) {
         hookProfileState = { turnCount: 0, cache: null };
-        hookProfileStateMap.set(namespace, hookProfileState);
+        hookProfileStateMap.set(effectiveNamespace, hookProfileState);
       }
       hookProfileState.turnCount++;
       const hookTurn = hookProfileState.turnCount;
@@ -620,7 +642,7 @@ const hookHandlers: Record<string, HookHandler> = {
       // -- end Task 31 + 102 --------------------------------------------------
 
       // -- Topic-shift detection (Task 14 parity) ----------------------------
-      const cacheKey = namespace;
+      const cacheKey = effectiveNamespace;
       const currentTokens = extractTopicTokens(prompt);
       const existingCache = hookRecallCacheMap.get(cacheKey);
       const cacheExpired = existingCache !== undefined && (Date.now() - existingCache.cachedAt) > HOOK_CACHE_TTL_MS;
@@ -636,10 +658,10 @@ const hookHandlers: Record<string, HookHandler> = {
         if (existingCache !== undefined) {
           logger.info(`sulcus: auto_recall hook — TOPIC SHIFT detected (overlap=${overlap.toFixed(2)}), fresh recall`);
         }
-        logger.debug?.(`sulcus: searching context for prompt (focused: ${recallQuery.substring(0, 50)}...) (namespace: ${namespace})`);
+        logger.debug?.(`sulcus: searching context for prompt (focused: ${recallQuery.substring(0, 50)}...) (namespace: ${effectiveNamespace})`);
         // Task 62: Use focused last-user-turn query for better relevance
         // Task 101: Use adaptive limit instead of raw config limit
-        const res = await sulcusMem.search_memory(recallQuery, hookEffectiveLimit, namespace);
+        const res = await sulcusMem.search_memory(recallQuery, hookEffectiveLimit, effectiveNamespace);
         vectorResults = res?.results ?? [];
         recallQM.freshRecalls++;  // Task 32: module-scope QM
         // Update cache with fresh results
@@ -660,7 +682,7 @@ const hookHandlers: Record<string, HookHandler> = {
         try {
           // Task 62: use focused recallQuery for entity expansion too
           const { extraMemories, expandedQuery } = await expandQueryWithEntities(
-            sulcusMem, recallQuery, namespace, logger
+            sulcusMem, recallQuery, effectiveNamespace, logger
           );
           // Merge extra memories from entity graph (dedup by ID)
           const seenExpandIds = new Set(vectorResults.map((r) => r.id as string));
@@ -672,7 +694,7 @@ const hookHandlers: Record<string, HookHandler> = {
           // If still thin, do second vector search with expanded query
           if (hookExpanded.length < THIN_RECALL_THRESHOLD && expandedQuery !== recallQuery) {
             try {
-              const expandedRes = await sulcusMem.search_memory(expandedQuery, hookEffectiveLimit, namespace);
+              const expandedRes = await sulcusMem.search_memory(expandedQuery, hookEffectiveLimit, effectiveNamespace);
               const expandedVec = expandedRes?.results ?? [];
               const expandedSeenIds = new Set(hookExpanded.map((r) => r.id as string));
               const newVecExtras = expandedVec.filter((r) => !expandedSeenIds.has(r.id as string));
@@ -742,8 +764,8 @@ const hookHandlers: Record<string, HookHandler> = {
       if (includeProfile) {
         try {
           const [prefRes, factRes] = await Promise.all([
-            sulcusMem.search_memory("user preference", Math.min(hookEffectiveLimit, 5), namespace),
-            sulcusMem.search_memory("fact data knowledge", Math.min(hookEffectiveLimit, 5), namespace),
+            sulcusMem.search_memory("user preference", Math.min(hookEffectiveLimit, 5), effectiveNamespace),
+            sulcusMem.search_memory("fact data knowledge", Math.min(hookEffectiveLimit, 5), effectiveNamespace),
           ]);
           profilePreferences = (prefRes?.results ?? []).filter((r) => r.memory_type === "preference");
           profileFacts = (factRes?.results ?? []).filter((r) => r.memory_type === "fact");
@@ -827,8 +849,49 @@ const hookHandlers: Record<string, HookHandler> = {
         recallElements.push(`  <memory type="${mtype}" heat="${heatStr}" age="${ageStr}"${staleAttr}${supersededAttr}>${r.label}</memory>`);
       }
 
+      // -- Phase 3: Core Memory Block — always injected, never scaled ---------
+      // Core memory is identity/relationship/preference context that persists.
+      // It's tiny (~1000 tokens max) and critical for personality continuity.
+      let coreMemoryXml = "";
+      if (sulcusMem instanceof SulcusCloudClient) {
+        if (coreMemoryCache === undefined) {
+          // First fetch — load from server
+          try {
+            coreMemoryCache = await sulcusMem.get_core_memory();
+            if (coreMemoryCache) {
+              logger.info(`sulcus: core memory loaded (${JSON.stringify(coreMemoryCache).length} chars)`);
+            }
+          } catch {
+            coreMemoryCache = null; // failed — don't retry this session
+          }
+        }
+        if (coreMemoryCache && Object.keys(coreMemoryCache).length > 0) {
+          const coreLines: string[] = [];
+          for (const [key, value] of Object.entries(coreMemoryCache)) {
+            if (key === "namespace" || key === "updated_at" || key === "created_at") continue;
+            if (typeof value === "string" && value.trim()) {
+              coreLines.push(`  <${key}>${escapeXml(value)}</${key}>`);
+            } else if (Array.isArray(value) && value.length > 0) {
+              const items = value.map((v: unknown) => `    <item>${escapeXml(String(v))}</item>`).join("\n");
+              coreLines.push(`  <${key}>\n${items}\n  </${key}>`);
+            } else if (typeof value === "object" && value !== null) {
+              const entries = Object.entries(value as Record<string, unknown>)
+                .filter(([, v]) => v !== null && v !== undefined && String(v).trim())
+                .map(([k, v]) => `    <${k}>${escapeXml(String(v))}</${k}>`).join("\n");
+              if (entries) coreLines.push(`  <${key}>\n${entries}\n  </${key}>`);
+            }
+          }
+          if (coreLines.length > 0) {
+            const raw = `<core_memory>\n${coreLines.join("\n")}\n</core_memory>`;
+            coreMemoryXml = raw.length > CORE_MEMORY_MAX_CHARS ? raw.substring(0, CORE_MEMORY_MAX_CHARS) + "\n</core_memory>" : raw;
+          }
+        }
+      }
+
       // -- Assemble context XML ------------------------------------------------
       const sections: string[] = [];
+      // Phase 3: Core memory is the FIRST section — always present, never scaled
+      if (coreMemoryXml) sections.push(coreMemoryXml);
       // Profile section (Task 31) — inject before recall so agent sees identity context first
       if (budgetedProfile.length > 0) {
         const profileElements: string[] = [];
@@ -851,7 +914,7 @@ const hookHandlers: Record<string, HookHandler> = {
         `<guidance>${guidance}</guidance>`,
         ...sections,
       ];
-      const context = `<sulcus_context token_budget="${TOKEN_BUDGET}" namespace="${namespace}" turn="${hookTurn}">\n${contextParts.join("\n")}\n</sulcus_context>`;
+      const context = `<sulcus_context token_budget="${TOKEN_BUDGET}" namespace="${effectiveNamespace}" turn="${hookTurn}">\n${contextParts.join("\n")}\n</sulcus_context>`;
       const estimatedTokens = estimateTokens(context);
       // Task 32: track items served + avg relevance score in module-scope QM
       recallQM.totalItemsServed += budgeted.length;
@@ -1164,6 +1227,33 @@ const hookHandlers: Record<string, HookHandler> = {
       }
     }
 
+    // -- Phase 4: Build structured episode object --------------------------------
+    const episode: Record<string, unknown> = {
+      topic: firstUserText,
+      decisions: decisions.slice(0, 5),
+      files_modified: filesModified.slice(0, 10),
+      commands_run: commandsRun.slice(0, 5),
+      errors: errors.slice(0, 3),
+      outcome: "compacted",
+      duration_turns: messages.length,
+      timestamp: new Date().toISOString(),
+    };
+
+    // Detect mood from message patterns
+    const allText = messages.map(m => {
+      const content = typeof m.content === "string" ? m.content : typeof m.text === "string" ? m.text as string : "";
+      return content.toLowerCase();
+    }).join(" ");
+    if (allText.includes("error") || allText.includes("failed") || allText.includes("broken")) {
+      episode.mood = "debugging";
+    } else if (allText.includes("looks good") || allText.includes("working") || allText.includes("done")) {
+      episode.mood = "productive";
+    } else if (allText.includes("?") && allText.split("?").length > 3) {
+      episode.mood = "exploratory";
+    } else {
+      episode.mood = "neutral";
+    }
+
     // --- Build primary summary memory ---
     const summaryParts = [
       `Session compaction — ${messages.length} messages`,
@@ -1216,6 +1306,15 @@ const hookHandlers: Record<string, HookHandler> = {
       }
     }
 
+    // -- Phase 4: Store structured episode
+    if (sulcusMem instanceof SulcusCloudClient) {
+      storePromises.push(
+        sulcusMem.store_episode(episode)
+          .then((res) => logger.info(`sulcus: pre_compaction_capture — stored structured episode (id: ${res?.id ?? "?"})`)
+          ).catch((e: unknown) => logger.debug?.(`sulcus: pre_compaction_capture — episode store failed: ${e instanceof Error ? e.message : String(e)}`))
+      );
+    }
+
     // Fire all stores in parallel (non-blocking from OpenClaw's perspective)
     await Promise.allSettled(storePromises);
     logger.info(`sulcus: pre_compaction_capture — stored ${storePromises.length} memory/memories from ${messages.length}-message session`);
@@ -1651,6 +1750,118 @@ class SulcusCloudClient {
       throw e;
     }
   }
+
+  async graph_status(): Promise<Record<string, unknown>> {
+    return this.request("GET", "/api/v1/agent/graph/status") as Promise<Record<string, unknown>>;
+  }
+
+  async graph_temporal(query: string, timeFrom?: string, timeTo?: string, limit?: number): Promise<Record<string, unknown>[]> {
+    const body: Record<string, unknown> = { query };
+    if (timeFrom) body.time_from = timeFrom;
+    if (timeTo) body.time_to = timeTo;
+    if (limit) body.limit = limit;
+    const res = await this.request("POST", "/api/v1/agent/graph/temporal", body);
+    return (Array.isArray(res) ? res : []) as Record<string, unknown>[];
+  }
+
+  async list_conflicts(namespace?: string, limit?: number): Promise<Record<string, unknown>[]> {
+    const params = new URLSearchParams();
+    if (namespace) params.set("namespace", namespace);
+    if (limit) params.set("limit", String(limit));
+    const qs = params.toString();
+    const res = await this.request("GET", `/api/v1/agent/conflicts${qs ? "?" + qs : ""}`);
+    return (Array.isArray(res) ? res : ((res as Record<string, unknown>)?.conflicts ?? [])) as Record<string, unknown>[];
+  }
+
+  async resolve_conflict(id: string, resolution: string): Promise<Record<string, unknown>> {
+    return this.request("PATCH", `/api/v1/agent/conflicts/${encodeURIComponent(id)}`, { resolution }) as Promise<Record<string, unknown>>;
+  }
+
+  async list_archived(namespace?: string, limit?: number, offset?: number): Promise<Record<string, unknown>> {
+    const params = new URLSearchParams();
+    if (namespace) params.set("namespace", namespace);
+    if (limit) params.set("limit", String(limit));
+    if (offset) params.set("offset", String(offset));
+    const qs = params.toString();
+    return this.request("GET", `/api/v1/agent/archive${qs ? "?" + qs : ""}`) as Promise<Record<string, unknown>>;
+  }
+
+  async restore_memories(ids: string[], namespace?: string): Promise<Record<string, unknown>> {
+    return this.request("POST", "/api/v1/agent/restore", { ids, namespace }) as Promise<Record<string, unknown>>;
+  }
+
+  async fold_memories(ids: string[], namespace?: string, label?: string): Promise<Record<string, unknown>> {
+    return this.request("POST", "/api/v1/agent/fold", { ids, label, namespace }) as Promise<Record<string, unknown>>;
+  }
+
+  async dashboard_stats(): Promise<Record<string, unknown>> {
+    return this.request("GET", "/api/v1/admin/dashboard") as Promise<Record<string, unknown>>;
+  }
+
+  async storage_status(): Promise<Record<string, unknown>> {
+    return this.request("GET", "/api/v1/agent/storage") as Promise<Record<string, unknown>>;
+  }
+
+  async get_core_memory(): Promise<Record<string, unknown> | null> {
+    try {
+      const params = new URLSearchParams();
+      if (this.namespace) params.set("namespace", this.namespace);
+      const qs = params.toString();
+      return await this.request("GET", `/api/v1/agent/core-memory${qs ? "?" + qs : ""}`) as Record<string, unknown>;
+    } catch {
+      return null;
+    }
+  }
+
+  async update_core_memory(updates: Record<string, unknown>): Promise<Record<string, unknown>> {
+    const body: Record<string, unknown> = { ...updates };
+    if (this.namespace) body.namespace = this.namespace;
+    return this.request("PATCH", "/api/v1/agent/core-memory", body) as Promise<Record<string, unknown>>;
+  }
+
+  // -- Phase 4: Episodic Session Layer ----------------------------------------
+  async store_episode(episode: Record<string, unknown>): Promise<{ id: string; [key: string]: unknown }> {
+    // Store as episodic memory with structured metadata hints
+    const content = this.formatEpisodeSummary(episode);
+    const hints: Record<string, unknown> = {
+      memory_type: "episodic",
+      context_note: "Structured session episode — contains topic, decisions, files, and outcome.",
+      episode_metadata: episode,
+    };
+    return this.request("POST", "/api/v1/agent/store", {
+      content,
+      memory_type: "episodic",
+      namespace: this.namespace,
+      hints,
+      metadata: episode,
+    }) as Promise<{ id: string; [key: string]: unknown }>;
+  }
+
+  private formatEpisodeSummary(episode: Record<string, unknown>): string {
+    const parts: string[] = [];
+    if (episode.topic) parts.push(`Topic: ${episode.topic}`);
+    if (Array.isArray(episode.decisions) && episode.decisions.length > 0) {
+      parts.push(`Decisions: ${(episode.decisions as string[]).join("; ")}`);
+    }
+    if (Array.isArray(episode.files_modified) && episode.files_modified.length > 0) {
+      parts.push(`Files: ${(episode.files_modified as string[]).join(", ")}`);
+    }
+    if (Array.isArray(episode.errors) && episode.errors.length > 0) {
+      parts.push(`Errors: ${(episode.errors as string[]).join("; ")}`);
+    }
+    if (episode.outcome) parts.push(`Outcome: ${episode.outcome}`);
+    if (episode.mood) parts.push(`Mood: ${episode.mood}`);
+    if (episode.duration_turns) parts.push(`Duration: ${episode.duration_turns} turns`);
+    return `Session episode: ${parts.join(" | ")}`;
+  }
+
+  // -- Phase 6: Multi-user namespace listing ----------------------------------------
+  async list_namespaces(): Promise<Record<string, unknown>[]> {
+    const res = await this.request("GET", "/api/v1/agent/namespaces") as Record<string, unknown> | unknown[];
+    if (Array.isArray(res)) return res as Record<string, unknown>[];
+    const data = res as Record<string, unknown>;
+    return (data?.namespaces ?? data?.results ?? []) as Record<string, unknown>[];
+  }
 }
 
 // --- NATIVE LIB LOADER ------------------------------------------------------
@@ -1856,6 +2067,24 @@ function loadHooksConfig(apiConfig: Record<string, unknown>): HooksConfig {
         __sulcus_workflow__: { enabled: true },
         session_store: { enabled: true },
         session_recall: { enabled: true },
+        memory_get: { enabled: true },
+        memory_list: { enabled: true },
+        memory_update: { enabled: true },
+        siu_label: { enabled: false },
+        siu_status: { enabled: false },
+        siu_retrain: { enabled: false },
+        trigger_feedback: { enabled: false },
+        graph_explore: { enabled: true },
+        memory_conflicts: { enabled: true },
+        core_memory_read: { enabled: true },
+        core_memory_update: { enabled: true },
+        memory_archive: { enabled: true },
+        memory_fold: { enabled: true },
+        memory_dashboard: { enabled: true },
+        episode_recall: { enabled: true },
+        memory_namespace: { enabled: true },
+        namespace_list: { enabled: true },
+        sulcus_setup: { enabled: true },
       },
     };
   }
@@ -2148,6 +2377,18 @@ function estimateTokens(text: string): number {
   return Math.ceil(text.length / 4);
 }
 
+/**
+ * XML-escape a string for safe injection into XML context blocks.
+ */
+function escapeXml(str: string): string {
+  return str
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;");
+}
+
 /**
  * Truncate a memory label to fit within a character budget.
  * Appends ellipsis if truncated. Prefers word-boundary cuts.
@@ -2709,6 +2950,9 @@ function buildSdkRecallHandler(
     const rawPrompt = typeof event?.prompt === "string" ? event.prompt : "";
     if (!rawPrompt || rawPrompt.length < 5) return undefined;
 
+    // Phase 6: Multi-user namespace scoping — runtime override takes precedence
+    const effectiveNamespace = getEffectiveNamespace(namespace);
+
     // Strip OpenClaw metadata noise before using as search query
     const prompt = sanitizeRecallQuery(rawPrompt);
     if (!prompt || prompt.length < 3) return undefined;
@@ -2726,9 +2970,39 @@ function buildSdkRecallHandler(
     // fill the window fast regardless of turn count.
     const throttled = applyContextWindowThrottle(rawPrompt.length, contextWindowSize, sdkScale, logger);
     if (throttled.selfMuted) {
-      // Context window is critically full. Don't inject anything — let the model breathe.
-      // Return minimal awareness only (no recall, no profile).
-      return { prependContext: `<!-- sulcus: self-muted, context ${((rawPrompt.length / 4 / contextWindowSize) * 100).toFixed(0)}% full -->` };
+      // Context window is critically full. Don't inject recall/profile — let the model breathe.
+      // Phase 3: Core memory is tiny (~1000 tokens) — always inject it even when self-muted.
+      let selfMutedCore = "";
+      if (coreMemoryCache === undefined) {
+        try {
+          coreMemoryCache = await sulcusMem.get_core_memory();
+        } catch {
+          coreMemoryCache = null;
+        }
+      }
+      if (coreMemoryCache && Object.keys(coreMemoryCache).length > 0) {
+        const coreLines: string[] = [];
+        for (const [key, value] of Object.entries(coreMemoryCache)) {
+          if (key === "namespace" || key === "updated_at" || key === "created_at") continue;
+          if (typeof value === "string" && value.trim()) {
+            coreLines.push(`  <${key}>${escapeXml(value)}</${key}>`);
+          } else if (Array.isArray(value) && value.length > 0) {
+            const items = value.map((v: unknown) => `    <item>${escapeXml(String(v))}</item>`).join("\n");
+            coreLines.push(`  <${key}>\n${items}\n  </${key}>`);
+          } else if (typeof value === "object" && value !== null) {
+            const entries = Object.entries(value as Record<string, unknown>)
+              .filter(([, v]) => v !== null && v !== undefined && String(v).trim())
+              .map(([k, v]) => `    <${k}>${escapeXml(String(v))}</${k}>`).join("\n");
+            if (entries) coreLines.push(`  <${key}>\n${entries}\n  </${key}>`);
+          }
+        }
+        if (coreLines.length > 0) {
+          const raw = `<core_memory>\n${coreLines.join("\n")}\n</core_memory>`;
+          selfMutedCore = raw.length > CORE_MEMORY_MAX_CHARS ? raw.substring(0, CORE_MEMORY_MAX_CHARS) + "\n</core_memory>" : raw;
+        }
+      }
+      const mutedComment = `<!-- sulcus: self-muted, context ${((rawPrompt.length / 4 / contextWindowSize) * 100).toFixed(0)}% full -->`;
+      return { prependContext: selfMutedCore ? `${selfMutedCore}\n${mutedComment}` : mutedComment };
     }
     const effectiveMax = throttled.effectiveMax;
     const effectiveTokenBudget = throttled.effectiveTokenBudget;
@@ -2839,7 +3113,7 @@ function buildSdkRecallHandler(
     try {
       // Task 62: Use focused recallQuery instead of full accumulated prompt
       // Task 101: Use adaptive limit instead of raw config maxResults
-      const searchRes = await sulcusMem.search_memory(recallQuery, effectiveMax, namespace);
+      const searchRes = await sulcusMem.search_memory(recallQuery, effectiveMax, effectiveNamespace);
       const vectorResults = searchRes?.results ?? [];
 
       // -- Task 35: Query expansion for thin recall (SDK path) ---------------
@@ -2848,7 +3122,7 @@ function buildSdkRecallHandler(
         try {
           // Task 62: use focused recallQuery for entity expansion
           const { extraMemories: sdkExtraMem, expandedQuery: sdkExpandedQ } = await expandQueryWithEntities(
-            sulcusMem, recallQuery, namespace, logger
+            sulcusMem, recallQuery, effectiveNamespace, logger
           );
           const sdkSeenIds = new Set(vectorResults.map((r) => r.id as string));
           const sdkNewExtras = sdkExtraMem.filter((m) => !sdkSeenIds.has(m.id as string));
@@ -2858,7 +3132,7 @@ function buildSdkRecallHandler(
           }
           if (sdkExpanded.length < THIN_RECALL_THRESHOLD && sdkExpandedQ !== recallQuery) {
             try {
-              const sdkExpandedRes = await sulcusMem.search_memory(sdkExpandedQ, effectiveMax, namespace);
+              const sdkExpandedRes = await sulcusMem.search_memory(sdkExpandedQ, effectiveMax, effectiveNamespace);
               const sdkExpandedVec = sdkExpandedRes?.results ?? [];
               const sdkExpandedSeen = new Set(sdkExpanded.map((r) => r.id as string));
               const sdkExpandedNew = sdkExpandedVec.filter((r) => !sdkExpandedSeen.has(r.id as string));
@@ -2939,8 +3213,8 @@ function buildSdkRecallHandler(
 
       if (includeProfile) {
         try {
-          const prefRes = await sulcusMem.search_memory("user preference", Math.min(effectiveMax, 5), namespace);
-          const factRes = await sulcusMem.search_memory("fact data knowledge", Math.min(effectiveMax, 5), namespace);
+          const prefRes = await sulcusMem.search_memory("user preference", Math.min(effectiveMax, 5), effectiveNamespace);
+          const factRes = await sulcusMem.search_memory("fact data knowledge", Math.min(effectiveMax, 5), effectiveNamespace);
           preferences = (prefRes?.results ?? []).filter((r) => r.memory_type === "preference");
           facts = (factRes?.results ?? []).filter((r) => r.memory_type === "fact");
           profileCache = { preferences, facts, cachedAt: Date.now() };
@@ -3050,7 +3324,43 @@ function buildSdkRecallHandler(
       }
       // -- end Task 79 (SDK) -------------------------------------------------------
 
+      // -- Phase 3: Core Memory Block (SDK path) — always injected, never scaled ---
+      let sdkCoreMemoryXml = "";
+      if (coreMemoryCache === undefined) {
+        try {
+          coreMemoryCache = await sulcusMem.get_core_memory();
+          if (coreMemoryCache) {
+            logger.info(`sulcus: core memory loaded (${JSON.stringify(coreMemoryCache).length} chars)`);
+          }
+        } catch {
+          coreMemoryCache = null;
+        }
+      }
+      if (coreMemoryCache && Object.keys(coreMemoryCache).length > 0) {
+        const sdkCoreLines: string[] = [];
+        for (const [key, value] of Object.entries(coreMemoryCache)) {
+          if (key === "namespace" || key === "updated_at" || key === "created_at") continue;
+          if (typeof value === "string" && value.trim()) {
+            sdkCoreLines.push(`  <${key}>${escapeXml(value)}</${key}>`);
+          } else if (Array.isArray(value) && value.length > 0) {
+            const items = value.map((v: unknown) => `    <item>${escapeXml(String(v))}</item>`).join("\n");
+            sdkCoreLines.push(`  <${key}>\n${items}\n  </${key}>`);
+          } else if (typeof value === "object" && value !== null) {
+            const entries = Object.entries(value as Record<string, unknown>)
+              .filter(([, v]) => v !== null && v !== undefined && String(v).trim())
+              .map(([k, v]) => `    <${k}>${escapeXml(String(v))}</${k}>`).join("\n");
+            if (entries) sdkCoreLines.push(`  <${key}>\n${entries}\n  </${key}>`);
+          }
+        }
+        if (sdkCoreLines.length > 0) {
+          const raw = `<core_memory>\n${sdkCoreLines.join("\n")}\n</core_memory>`;
+          sdkCoreMemoryXml = raw.length > CORE_MEMORY_MAX_CHARS ? raw.substring(0, CORE_MEMORY_MAX_CHARS) + "\n</core_memory>" : raw;
+        }
+      }
+
       const sections: string[] = [];
+      // Phase 3: Core memory is the FIRST section — always present, never scaled
+      if (sdkCoreMemoryXml) sections.push(sdkCoreMemoryXml);
 
       // Task 18: use budgetedProfile (heat-sorted, budget-trimmed, labels already normalized)
       if (includeProfile && budgetedProfile.length > 0) {
@@ -3109,7 +3419,7 @@ function buildSdkRecallHandler(
         `<guidance>${guidance}</guidance>`,
       ];
       contextParts.push(...sections);
-      const context = `<sulcus_context token_budget="${TOKEN_BUDGET}" namespace="${namespace}">\n${contextParts.join("\n")}\n</sulcus_context>`;
+      const context = `<sulcus_context token_budget="${TOKEN_BUDGET}" namespace="${effectiveNamespace}">\n${contextParts.join("\n")}\n</sulcus_context>`;
 
       // Task 18: log budget utilisation
       const estimatedTokens = estimateTokens(context);
@@ -4167,6 +4477,544 @@ const toolDefinitions: Record<string, ToolDefinition> = {
         };
       },
   },
+
+  graph_explore: {
+    schema: {
+      name: "graph_explore",
+      label: "Graph Explore",
+      description: "Explore the knowledge graph around a memory (neighbors mode) or query temporal connections (temporal mode).",
+      parameters: Type.Object({
+        mode: Type.Union([Type.Literal("neighbors"), Type.Literal("temporal")], { description: "Exploration mode: 'neighbors' for graph edges around a memory, 'temporal' for time-based connections." }),
+        memory_id: Type.Optional(Type.String({ description: "Memory node UUID. Required for neighbors mode." })),
+        query: Type.Optional(Type.String({ description: "Search query for temporal mode." })),
+        time_from: Type.Optional(Type.String({ description: "ISO 8601 start time for temporal range filter." })),
+        time_to: Type.Optional(Type.String({ description: "ISO 8601 end time for temporal range filter." })),
+        limit: Type.Optional(Type.Number({ default: 10, description: "Max results to return (default 10).", minimum: 1, maximum: 50 })),
+      }),
+    },
+    options: { name: "graph_explore" },
+    makeExecute: ({ sulcusMem, backendMode, namespace, nativeLoader, isAvailable }) =>
+      async (_id, params) => {
+        if (!isAvailable || !sulcusMem) throw new Error(`Sulcus unavailable: ${nativeLoader.error || "not loaded"}`);
+        if (!(sulcusMem instanceof SulcusCloudClient)) throw new Error("graph_explore requires cloud backend");
+        const mode = params.mode as string;
+        const limit = (params.limit as number | undefined) ?? 10;
+        if (mode === "neighbors") {
+          const memoryId = params.memory_id as string | undefined;
+          if (!memoryId) return { content: [{ type: "text", text: "memory_id is required for neighbors mode." }] };
+          const neighbors = await sulcusMem.graph_neighbors(memoryId, limit);
+          return {
+            content: [{ type: "text", text: JSON.stringify(neighbors, null, 2) }],
+            details: { mode, memory_id: memoryId, count: neighbors.length, backend: backendMode, namespace },
+          };
+        } else {
+          const query = params.query as string | undefined;
+          if (!query) return { content: [{ type: "text", text: "query is required for temporal mode." }] };
+          const results = await sulcusMem.graph_temporal(
+            query,
+            params.time_from as string | undefined,
+            params.time_to as string | undefined,
+            limit,
+          );
+          return {
+            content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
+            details: { mode, query, count: results.length, backend: backendMode, namespace },
+          };
+        }
+      },
+  },
+
+  memory_conflicts: {
+    schema: {
+      name: "memory_conflicts",
+      label: "Memory Conflicts",
+      description: "List detected memory conflicts or resolve a specific conflict.",
+      parameters: Type.Object({
+        action: Type.Union([Type.Literal("list"), Type.Literal("resolve")], { description: "Action: 'list' to see conflicts, 'resolve' to resolve one." }),
+        id: Type.Optional(Type.String({ description: "Conflict UUID. Required for resolve action." })),
+        resolution: Type.Optional(Type.Union([
+          Type.Literal("keep_newer"),
+          Type.Literal("keep_older"),
+          Type.Literal("merge"),
+          Type.Literal("dismiss"),
+        ], { description: "Resolution strategy. Required for resolve action." })),
+        limit: Type.Optional(Type.Number({ default: 10, description: "Max conflicts to return for list action (default 10).", minimum: 1, maximum: 100 })),
+      }),
+    },
+    options: { name: "memory_conflicts" },
+    makeExecute: ({ sulcusMem, backendMode, namespace, nativeLoader, isAvailable }) =>
+      async (_id, params) => {
+        if (!isAvailable || !sulcusMem) throw new Error(`Sulcus unavailable: ${nativeLoader.error || "not loaded"}`);
+        if (!(sulcusMem instanceof SulcusCloudClient)) throw new Error("memory_conflicts requires cloud backend");
+        const action = params.action as string;
+        if (action === "list") {
+          const limit = (params.limit as number | undefined) ?? 10;
+          const conflicts = await sulcusMem.list_conflicts(namespace, limit);
+          const summary = conflicts.length === 0 ? "No conflicts found." : `${conflicts.length} conflict(s) found.`;
+          return {
+            content: [{ type: "text", text: summary + "\n" + JSON.stringify(conflicts, null, 2) }],
+            details: { action, count: conflicts.length, backend: backendMode, namespace },
+          };
+        } else {
+          const conflictId = params.id as string | undefined;
+          const resolution = params.resolution as string | undefined;
+          if (!conflictId) return { content: [{ type: "text", text: "id is required for resolve action." }] };
+          if (!resolution) return { content: [{ type: "text", text: "resolution is required for resolve action." }] };
+          const res = await sulcusMem.resolve_conflict(conflictId, resolution);
+          return {
+            content: [{ type: "text", text: `Conflict ${conflictId} resolved with strategy: ${resolution}` }],
+            details: { action, id: conflictId, resolution, result: res, backend: backendMode, namespace },
+          };
+        }
+      },
+  },
+
+  core_memory_read: {
+    schema: {
+      name: "core_memory_read",
+      label: "Core Memory Read",
+      description: "Read the current core memory block — the persistent structured identity context always injected into agent sessions. Contains identity, relationships, preferences, current_focus, and custom fields.",
+      parameters: Type.Object({}),
+    },
+    options: { name: "core_memory_read" },
+    makeExecute: ({ sulcusMem, backendMode, namespace, nativeLoader, isAvailable }) =>
+      async (_id, _params) => {
+        if (!isAvailable || !sulcusMem) throw new Error(`Sulcus unavailable: ${nativeLoader.error || "not loaded"}`);
+        if (!(sulcusMem instanceof SulcusCloudClient)) throw new Error("core_memory_read requires cloud backend");
+        const core = await sulcusMem.get_core_memory();
+        if (!core || Object.keys(core).length === 0) {
+          return {
+            content: [{ type: "text", text: "No core memory set. Use core_memory_update to create your identity block." }],
+            details: { backend: backendMode, namespace },
+          };
+        }
+        return {
+          content: [{ type: "text", text: JSON.stringify(core, null, 2) }],
+          details: { backend: backendMode, namespace, fields: Object.keys(core) },
+        };
+      },
+  },
+
+  core_memory_update: {
+    schema: {
+      name: "core_memory_update",
+      label: "Core Memory Update",
+      description: "Update fields in the core memory block. Core memory is a persistent structured identity context always injected into agent sessions. Only provide the fields you want to update.",
+      parameters: Type.Object({
+        identity: Type.Optional(Type.String({ description: "Who the agent is: name, role, and description." })),
+        relationships: Type.Optional(Type.String({ description: "Key people and entities the agent works with." })),
+        preferences: Type.Optional(Type.String({ description: "Agent preferences and communication style." })),
+        current_focus: Type.Optional(Type.String({ description: "What the agent is currently working on (mutable)." })),
+        custom: Type.Optional(Type.String({ description: "JSON string of additional freeform key-value pairs." })),
+      }),
+    },
+    options: { name: "core_memory_update" },
+    makeExecute: ({ sulcusMem, backendMode, namespace, nativeLoader, isAvailable }) =>
+      async (_id, params) => {
+        if (!isAvailable || !sulcusMem) throw new Error(`Sulcus unavailable: ${nativeLoader.error || "not loaded"}`);
+        if (!(sulcusMem instanceof SulcusCloudClient)) throw new Error("core_memory_update requires cloud backend");
+        const updates: Record<string, unknown> = {};
+        if (typeof params.identity === "string" && params.identity.trim()) updates.identity = params.identity.trim();
+        if (typeof params.relationships === "string" && params.relationships.trim()) updates.relationships = params.relationships.trim();
+        if (typeof params.preferences === "string" && params.preferences.trim()) updates.preferences = params.preferences.trim();
+        if (typeof params.current_focus === "string" && params.current_focus.trim()) updates.current_focus = params.current_focus.trim();
+        if (typeof params.custom === "string" && params.custom.trim()) {
+          try {
+            updates.custom = JSON.parse(params.custom.trim());
+          } catch {
+            return { content: [{ type: "text", text: "Invalid JSON in custom field." }] };
+          }
+        }
+        if (Object.keys(updates).length === 0) {
+          return { content: [{ type: "text", text: "No fields provided to update." }] };
+        }
+        const res = await sulcusMem.update_core_memory(updates);
+        // Invalidate the module-scope cache so next turn fetches fresh core memory
+        coreMemoryCache = undefined;
+        return {
+          content: [{ type: "text", text: `Core memory updated. Fields changed: ${Object.keys(updates).join(", ")}` }],
+          details: { updated: Object.keys(updates), result: res, backend: backendMode, namespace },
+        };
+      },
+  },
+
+  memory_archive: {
+    schema: {
+      name: "memory_archive",
+      label: "Memory Archive",
+      description: "List archived memories or restore specific ones from the archive.",
+      parameters: Type.Object({
+        action: Type.Union([Type.Literal("list"), Type.Literal("restore")], { description: "Action: 'list' to browse archived memories, 'restore' to un-archive specific ones." }),
+        ids: Type.Optional(Type.Array(Type.String(), { description: "Memory UUIDs to restore. Required for restore action." })),
+        limit: Type.Optional(Type.Number({ default: 20, description: "Max archived memories to return for list action (default 20).", minimum: 1, maximum: 100 })),
+        offset: Type.Optional(Type.Number({ default: 0, description: "Pagination offset for list action (default 0).", minimum: 0 })),
+      }),
+    },
+    options: { name: "memory_archive" },
+    makeExecute: ({ sulcusMem, backendMode, namespace, nativeLoader, isAvailable }) =>
+      async (_id, params) => {
+        if (!isAvailable || !sulcusMem) throw new Error(`Sulcus unavailable: ${nativeLoader.error || "not loaded"}`);
+        if (!(sulcusMem instanceof SulcusCloudClient)) throw new Error("memory_archive requires cloud backend");
+        const action = params.action as string;
+        if (action === "list") {
+          const limit = (params.limit as number | undefined) ?? 20;
+          const offset = (params.offset as number | undefined) ?? 0;
+          const res = await sulcusMem.list_archived(namespace, limit, offset);
+          return {
+            content: [{ type: "text", text: JSON.stringify(res, null, 2) }],
+            details: { action, limit, offset, backend: backendMode, namespace },
+          };
+        } else {
+          const ids = params.ids as string[] | undefined;
+          if (!ids || ids.length === 0) return { content: [{ type: "text", text: "ids array is required for restore action." }] };
+          const res = await sulcusMem.restore_memories(ids, namespace);
+          return {
+            content: [{ type: "text", text: `Restored ${ids.length} memory(ies) from archive.` }],
+            details: { action, ids, result: res, backend: backendMode, namespace },
+          };
+        }
+      },
+  },
+
+  memory_fold: {
+    schema: {
+      name: "memory_fold",
+      label: "Memory Fold",
+      description: "Merge multiple related memories into a single consolidated node. Collapses redundant or tightly related memories into one.",
+      parameters: Type.Object({
+        ids: Type.Array(Type.String(), { description: "Array of memory UUIDs to merge (minimum 2).", minItems: 2 }),
+        label: Type.Optional(Type.String({ description: "Optional summary label for the merged memory node." })),
+      }),
+    },
+    options: { name: "memory_fold" },
+    makeExecute: ({ sulcusMem, backendMode, namespace, nativeLoader, isAvailable }) =>
+      async (_id, params) => {
+        if (!isAvailable || !sulcusMem) throw new Error(`Sulcus unavailable: ${nativeLoader.error || "not loaded"}`);
+        if (!(sulcusMem instanceof SulcusCloudClient)) throw new Error("memory_fold requires cloud backend");
+        const ids = params.ids as string[];
+        if (!ids || ids.length < 2) return { content: [{ type: "text", text: "At least 2 memory IDs are required to fold." }] };
+        const label = params.label as string | undefined;
+        const res = await sulcusMem.fold_memories(ids, namespace, label);
+        return {
+          content: [{ type: "text", text: `Folded ${ids.length} memories into one node.${label ? ` Label: "${label}"` : ""}` }],
+          details: { ids, label, result: res, backend: backendMode, namespace },
+        };
+      },
+  },
+
+  memory_dashboard: {
+    schema: {
+      name: "memory_dashboard",
+      label: "Memory Dashboard",
+      description: "Get a high-level dashboard of memory health, usage statistics, and storage information.",
+      parameters: Type.Object({}),
+    },
+    options: { name: "memory_dashboard" },
+    makeExecute: ({ sulcusMem, backendMode, namespace, nativeLoader, isAvailable }) =>
+      async (_id, _params) => {
+        if (!isAvailable || !sulcusMem) throw new Error(`Sulcus unavailable: ${nativeLoader.error || "not loaded"}`);
+        if (!(sulcusMem instanceof SulcusCloudClient)) throw new Error("memory_dashboard requires cloud backend");
+        const [dashResult, storageResult] = await Promise.allSettled([
+          sulcusMem.dashboard_stats(),
+          sulcusMem.storage_status(),
+        ]);
+        const dashboard = dashResult.status === "fulfilled" ? dashResult.value : {};
+        const storage = storageResult.status === "fulfilled" ? storageResult.value : {};
+        const merged = { ...dashboard, storage, backend: backendMode, namespace };
+        return {
+          content: [{ type: "text", text: JSON.stringify(merged, null, 2) }],
+          details: merged as Record<string, unknown>,
+        };
+      },
+  },
+
+  // -- Phase 4: Episodic Session Recall ---------------------------------------
+  episode_recall: {
+    schema: {
+      name: "episode_recall",
+      label: "Episode Recall",
+      description: "Search past conversation episodes — structured session summaries including topic, decisions, files modified, and outcome. Use for questions like 'what did we discuss last time?' or 'when did we work on X?'",
+      parameters: Type.Object({
+        query: Type.String({ description: "Search query — topic, keyword, date, or question about past sessions." }),
+        limit: Type.Optional(Type.Number({ default: 5, minimum: 1, maximum: 20, description: "Max episodes to return." })),
+      }),
+    },
+    options: { name: "episode_recall" },
+    makeExecute: ({ sulcusMem, backendMode, namespace, nativeLoader, isAvailable }) =>
+      async (_id, params) => {
+        if (!isAvailable || !sulcusMem) throw new Error(`Sulcus unavailable: ${nativeLoader.error || "not loaded"}`);
+        if (!(sulcusMem instanceof SulcusCloudClient)) throw new Error("episode_recall requires cloud backend");
+        const query = params.query as string;
+        const limit = Math.min(20, Math.max(1, (params.limit as number | undefined) ?? 5));
+        // Search with a hint toward episodic/session content
+        const res = await sulcusMem.search_memory(`session episode: ${query}`, limit * 2, namespace);
+        const episodes = (res?.results ?? [])
+          .filter((r) => {
+            const mtype = r.memory_type as string | undefined;
+            const content = ((r.label ?? r.pointer_summary ?? "") as string).toLowerCase();
+            return mtype === "episodic" || content.includes("session episode") || content.includes("session compaction");
+          })
+          .slice(0, limit);
+        if (episodes.length === 0) {
+          return { content: [{ type: "text", text: `No episodes found matching "${query}".` }], details: { query, count: 0 } };
+        }
+        const formatted = episodes.map((e, i) => {
+          const content = (e.label ?? e.pointer_summary ?? e.content ?? "") as string;
+          const heat = typeof e.current_heat === "number" ? e.current_heat.toFixed(2) : "?";
+          const date = (e.updated_at ?? e.created_at ?? "unknown") as string;
+          const meta = e.metadata as Record<string, unknown> | undefined;
+          let metaStr = "";
+          if (meta) {
+            const parts: string[] = [];
+            if (meta.mood) parts.push(`Mood: ${meta.mood}`);
+            if (meta.outcome) parts.push(`Outcome: ${meta.outcome}`);
+            if (meta.duration_turns) parts.push(`Turns: ${meta.duration_turns}`);
+            if (parts.length > 0) metaStr = ` [${parts.join(", ")}]`;
+          }
+          return `${i + 1}. [${date}] (heat: ${heat})${metaStr}\n   ${content}`;
+        }).join("\n\n");
+        return {
+          content: [{ type: "text", text: `Found ${episodes.length} episode(s) for "${query}":\n\n${formatted}` }],
+          details: { query, count: episodes.length, backend: backendMode, namespace },
+        };
+      },
+  },
+
+  memory_namespace: {
+    schema: {
+      name: "memory_namespace",
+      label: "Memory Namespace",
+      description: "Switch the active memory namespace at runtime. Useful for reading from project-specific or shared namespaces, or when serving multiple users. Affects all subsequent memory operations until switched again or the session ends.",
+      parameters: Type.Object({
+        namespace: Type.String({ description: "Target namespace to switch to. Use the base namespace name (e.g. 'ariadne', 'project-alpha')." }),
+        reason: Type.Optional(Type.String({ description: "Why you're switching namespace — logged for audit trail." })),
+      }),
+    },
+    options: { name: "memory_namespace" },
+    makeExecute: ({ backendMode, namespace: currentNs, logger }) =>
+      async (_id, params) => {
+        const target = (params.namespace as string).trim();
+        if (!target) return { content: [{ type: "text", text: "Namespace cannot be empty." }] };
+        const reason = (params.reason as string | undefined) ?? "manual switch";
+        // Phase 6: Update the module-scope runtime namespace override
+        activeNamespaceOverride = target;
+        logger.info(`sulcus: namespace switched ${currentNs} \u2192 ${target} (reason: ${reason})`);
+        return {
+          content: [{ type: "text", text: `Namespace switched: **${currentNs}** \u2192 **${target}**\nReason: ${reason}\n\nAll subsequent memory operations will use namespace \`${target}\` until switched again or session ends.` }],
+          details: { previous: currentNs, current: target, reason, backend: backendMode },
+        };
+      },
+  },
+
+  namespace_list: {
+    schema: {
+      name: "namespace_list",
+      label: "Namespace List",
+      description: "List available memory namespaces and their stats (node count, last activity). Useful for multi-user setups or project-scoped memory. Cloud-only.",
+      parameters: Type.Object({}),
+    },
+    options: { name: "namespace_list" },
+    makeExecute: ({ sulcusMem, backendMode, namespace, nativeLoader, isAvailable }) =>
+      async (_id, _params) => {
+        if (!isAvailable || !sulcusMem) throw new Error(`Sulcus unavailable: ${nativeLoader.error || "not loaded"}`);
+        if (!(sulcusMem instanceof SulcusCloudClient)) throw new Error("namespace_list requires cloud backend");
+        try {
+          const res = await (sulcusMem as SulcusCloudClient).list_namespaces();
+          if (!res || !Array.isArray(res) || res.length === 0) {
+            return { content: [{ type: "text", text: "No namespaces found or endpoint not available." }] };
+          }
+          const current = activeNamespaceOverride ?? namespace;
+          const formatted = res.map((ns: Record<string, unknown>) => {
+            const name = (ns.namespace ?? ns.name ?? "unknown") as string;
+            const count = (ns.node_count ?? ns.count ?? "?") as string | number;
+            const active = name === current ? " \u2190 active" : "";
+            return `- **${name}** (${count} nodes)${active}`;
+          }).join("\n");
+          return {
+            content: [{ type: "text", text: `## Namespaces\nActive: \`${current}\`\n\n${formatted}` }],
+            details: { namespaces: res, active: current, backend: backendMode },
+          };
+        } catch {
+          return { content: [{ type: "text", text: "Namespace listing not available \u2014 server may need update." }] };
+        }
+      },
+  },
+
+  sulcus_setup: {
+    schema: {
+      name: "sulcus_setup",
+      label: "Sulcus Setup",
+      description: "Run the Sulcus setup diagnostic — checks backend connectivity, configuration status, core memory state, and generates recommended cron job configurations for memory maintenance. Call this once when first setting up Sulcus.",
+      parameters: Type.Object({
+        init_core_memory: Type.Optional(Type.Boolean({ description: "If true and core memory is empty, initialize it with defaults based on the agent's namespace." })),
+      }),
+    },
+    options: { name: "sulcus_setup" },
+    makeExecute: ({ sulcusMem, backendMode, namespace, nativeLoader, isAvailable, logger }) =>
+      async (_id, params) => {
+        const report: string[] = [];
+        report.push("# 🧵 Sulcus Setup Report\n");
+
+        // -- Section 1: Backend Status --
+        report.push("## Backend");
+        if (!isAvailable || !sulcusMem) {
+          report.push(`❌ **Not available** — ${nativeLoader.error || "not loaded"}`);
+          report.push("Fix: Check your sulcus config (apiKey, server URL). Run `memory_status` for details.\n");
+          return { content: [{ type: "text", text: report.join("\n") }], details: { status: "unavailable" } };
+        }
+        report.push(`✅ **Backend:** ${backendMode}`);
+        report.push(`✅ **Namespace:** ${namespace || "(default)"}`);
+
+        // Try to get server info
+        const isCloud = sulcusMem instanceof SulcusCloudClient;
+        if (isCloud) {
+          try {
+            const info = await (sulcusMem as any).request("GET", "/api/v1/agent/info");
+            if (info) {
+              report.push(`✅ **Server:** connected`);
+              if ((info as any).capabilities) report.push(`   Capabilities: ${JSON.stringify((info as any).capabilities)}`);
+            }
+          } catch {
+            report.push("⚠️ **Server info:** could not fetch (non-critical)");
+          }
+        }
+        report.push("");
+
+        // -- Section 2: Configuration Audit --
+        report.push("## Configuration");
+        const checks: [string, boolean, string][] = [
+          ["Auto-recall (before_prompt_build)", true, "Memories are injected into context automatically"],
+          ["Auto-capture (agent_end)", true, "Conversations are captured when sessions end"],
+          ["Context-window awareness", true, "Plugin self-throttles to prevent context overflow"],
+          ["Cloud backend", isCloud, "Required for advanced tools (graph, conflicts, archive, fold, dashboard, core memory, episodes)"],
+        ];
+        for (const [name, ok, desc] of checks) {
+          report.push(`${ok ? "✅" : "⚠️"} **${name}** — ${desc}`);
+        }
+        report.push("");
+
+        // -- Section 3: Core Memory --
+        report.push("## Core Memory");
+        if (isCloud) {
+          try {
+            const core = await (sulcusMem as SulcusCloudClient).get_core_memory();
+            if (core && Object.keys(core).filter(k => !["namespace", "created_at", "updated_at"].includes(k)).length > 0) {
+              const fields = Object.keys(core).filter(k => !["namespace", "created_at", "updated_at"].includes(k));
+              report.push(`✅ **Core memory set** — fields: ${fields.join(", ")}`);
+            } else {
+              report.push("⚠️ **Core memory is empty** — no persistent identity block");
+              if (params.init_core_memory) {
+                try {
+                  await (sulcusMem as SulcusCloudClient).update_core_memory({
+                    identity: `Agent in namespace '${namespace || "default"}'`,
+                    current_focus: "Initial setup",
+                  });
+                  report.push("✅ **Initialized** with default identity. Use `core_memory_update` to customize.");
+                  // Invalidate cache so next turn picks it up
+                  coreMemoryCache = undefined;
+                } catch (e: unknown) {
+                  report.push(`❌ **Init failed:** ${e instanceof Error ? e.message : String(e)}`);
+                }
+              } else {
+                report.push("   → Call `sulcus_setup(init_core_memory: true)` to initialize, or use `core_memory_update` directly.");
+              }
+            }
+          } catch {
+            report.push("⚠️ **Core memory endpoint not available** — server may need update");
+          }
+        } else {
+          report.push("⚠️ Core memory requires cloud backend");
+        }
+        report.push("");
+
+        // -- Section 4: Tool Availability --
+        report.push("## Available Tools");
+        const allTools = [
+          ["memory_store", "Store memories"],
+          ["memory_recall", "Search memories"],
+          ["memory_get", "Fetch by ID (cloud)"],
+          ["memory_list", "Browse memories (cloud)"],
+          ["memory_update", "Update in-place (cloud)"],
+          ["memory_delete", "Delete memories"],
+          ["memory_status", "Backend status"],
+          ["memory_profile", "Health snapshot"],
+          ["memory_namespace", "Switch namespace"],
+          ["core_memory_read", "Read identity block (cloud)"],
+          ["core_memory_update", "Update identity block (cloud)"],
+          ["graph_explore", "Knowledge graph traversal (cloud)"],
+          ["memory_conflicts", "Conflict detection (cloud)"],
+          ["memory_archive", "Archive management (cloud)"],
+          ["memory_fold", "Memory consolidation (cloud)"],
+          ["memory_dashboard", "Health dashboard (cloud)"],
+          ["episode_recall", "Past session search (cloud)"],
+          ["namespace_list", "List namespaces (cloud)"],
+          ["session_store", "Session-scoped storage"],
+          ["session_recall", "Session-scoped search"],
+          ["consolidate", "Trigger consolidation"],
+          ["guardrail_status", "Safety guardrails"],
+          ["sulcus_setup", "This tool"],
+        ];
+        const cloudOnly = ["memory_get", "memory_list", "memory_update", "core_memory_read", "core_memory_update", "graph_explore", "memory_conflicts", "memory_archive", "memory_fold", "memory_dashboard", "episode_recall", "namespace_list"];
+        let available = 0;
+        for (const [name, desc] of allTools) {
+          const ok = cloudOnly.includes(name) ? isCloud : true;
+          if (ok) available++;
+          report.push(`${ok ? "✅" : "⚠️"} \`${name}\` — ${desc}`);
+        }
+        report.push(`\n**${available}/${allTools.length}** tools available.\n`);
+
+        // -- Section 5: Recommended Crons --
+        report.push("## Recommended Maintenance Crons");
+        report.push("");
+        report.push("Set these up in your host platform (OpenClaw cron, system crontab, etc.):");
+        report.push("");
+        report.push("### 1. Daily Consolidation");
+        report.push("Merge related memories, reduce noise, strengthen connections.");
+        report.push("```");
+        report.push("Schedule: daily at 03:00 UTC");
+        report.push("Action: Call consolidate(min_heat: 0.1)");
+        report.push("OpenClaw cron example:");
+        report.push('  schedule: { kind: "cron", expr: "0 3 * * *", tz: "UTC" }');
+        report.push('  payload: { kind: "agentTurn", message: "Run consolidate(min_heat: 0.1) and report results." }');
+        report.push("```");
+        report.push("");
+        report.push("### 2. Weekly Quality Audit");
+        report.push("Check memory health, identify duplicates, review type distribution.");
+        report.push("```");
+        report.push("Schedule: weekly on Sunday at 04:00 UTC");
+        report.push("Action: Call memory_dashboard() and memory_profile()");
+        report.push("OpenClaw cron example:");
+        report.push('  schedule: { kind: "cron", expr: "0 4 * * 0", tz: "UTC" }');
+        report.push('  payload: { kind: "agentTurn", message: "Run memory_dashboard() and memory_profile(). Summarize health and flag issues." }');
+        report.push("```");
+        report.push("");
+        report.push("### 3. Daily Dashboard Snapshot");
+        report.push("Quick health check — storage, node counts, hot memories.");
+        report.push("```");
+        report.push("Schedule: daily at 08:00 local");
+        report.push("Action: Call memory_status()");
+        report.push("OpenClaw cron example:");
+        report.push('  schedule: { kind: "cron", expr: "0 8 * * *", tz: "America/Vancouver" }');
+        report.push('  payload: { kind: "agentTurn", message: "Run memory_status() and report any anomalies." }');
+        report.push("```");
+        report.push("");
+        report.push("---");
+        report.push("*Setup complete. Run this tool again anytime to re-check status.*");
+
+        return {
+          content: [{ type: "text", text: report.join("\n") }],
+          details: {
+            status: "ok",
+            backend: backendMode,
+            namespace,
+            isCloud,
+            toolsAvailable: available,
+            toolsTotal: allTools.length,
+            coreMemorySet: true,
+          },
+        };
+      },
+  },
 };
 
 // --- FIRST-INSTALL HISTORY IMPORT --------------------------------------------
@@ -4590,6 +5438,108 @@ const sulcusPlugin = {
         }
       });
       logger.info("sulcus: registered auto-capture (agent_end)");
+
+      // -- Phase 4: Register agent_end episode capture -----------------------
+      if (isAvailable && sulcusMem instanceof SulcusCloudClient) {
+        const episodeApiOn = api.on as (event: string, handler: unknown) => void;
+        episodeApiOn("agent_end", async (event: Record<string, unknown>) => {
+          try {
+            const messages = Array.isArray(event?.messages) ? event.messages as Record<string, unknown>[] : [];
+            if (messages.length === 0) return;
+
+            const firstUser = messages.find((m) => m.role === "user" || m.type === "human");
+            const firstUserText = typeof firstUser?.content === "string"
+              ? firstUser.content.substring(0, 200)
+              : typeof firstUser?.text === "string"
+                ? (firstUser.text as string).substring(0, 200)
+                : "(none)";
+
+            // Extract artifacts
+            const filesModified: string[] = [];
+            const commandsRun: string[] = [];
+            const decisions: string[] = [];
+            const errors: string[] = [];
+            const DECISION_MARKERS = ["decided", "will use", "going to", "plan is", "the fix", "conclusion", "recommend", "approach"];
+            const ERROR_MARKERS = ["error:", "failed:", "exception", "traceback", "panicked", "stack trace"];
+
+            for (const msg of messages) {
+              const role = (msg.role ?? msg.type) as string | undefined;
+              const rawContent = typeof msg.content === "string" ? msg.content
+                : typeof msg.text === "string" ? msg.text as string : "";
+
+              if ((role === "assistant" || role === "ai") && rawContent.length > 20) {
+                const lc = rawContent.toLowerCase();
+                if (DECISION_MARKERS.some((m) => lc.includes(m))) {
+                  const sentences = rawContent.split(/[.!?\n]/).filter((s) => s.trim().length > 10);
+                  for (const s of sentences) {
+                    if (DECISION_MARKERS.some((m) => s.toLowerCase().includes(m)) && !decisions.includes(s.trim())) {
+                      decisions.push(s.trim().substring(0, 200));
+                      if (decisions.length >= 5) break;
+                    }
+                  }
+                }
+                const lcContent = rawContent.toLowerCase();
+                if (ERROR_MARKERS.some((m) => lcContent.includes(m))) {
+                  const errorLine = rawContent.split("\n").find((l) => ERROR_MARKERS.some((m) => l.toLowerCase().includes(m)));
+                  if (errorLine && !errors.includes(errorLine.trim())) {
+                    errors.push(errorLine.trim().substring(0, 150));
+                  }
+                }
+              }
+
+              const toolCalls = Array.isArray(msg.tool_calls) ? msg.tool_calls as Record<string, unknown>[] : [];
+              for (const tc of toolCalls) {
+                const name = (tc.name ?? tc.function) as string | undefined;
+                if (name === "Write" || name === "Edit" || name === "write" || name === "edit") {
+                  const input = (tc.input ?? tc.arguments ?? {}) as Record<string, unknown>;
+                  const fp = input?.file_path ?? input?.path;
+                  if (fp && typeof fp === "string" && !filesModified.includes(fp)) filesModified.push(fp);
+                }
+                if (name === "Bash" || name === "bash" || name === "exec" || name === "shell") {
+                  const input = (tc.input ?? tc.arguments ?? {}) as Record<string, unknown>;
+                  const cmd = input?.command ?? input?.cmd;
+                  if (cmd && typeof cmd === "string" && commandsRun.length < 5) {
+                    commandsRun.push((cmd as string).substring(0, 100));
+                  }
+                }
+              }
+            }
+
+            const allText = messages.map(m => {
+              const content = typeof m.content === "string" ? m.content : typeof m.text === "string" ? m.text as string : "";
+              return content.toLowerCase();
+            }).join(" ");
+
+            const episode: Record<string, unknown> = {
+              topic: firstUserText,
+              decisions: decisions.slice(0, 5),
+              files_modified: filesModified.slice(0, 10),
+              commands_run: commandsRun.slice(0, 5),
+              errors: errors.slice(0, 3),
+              outcome: "completed",
+              duration_turns: messages.length,
+              timestamp: new Date().toISOString(),
+            };
+
+            if (allText.includes("error") || allText.includes("failed") || allText.includes("broken")) {
+              episode.mood = "debugging";
+            } else if (allText.includes("looks good") || allText.includes("working") || allText.includes("done")) {
+              episode.mood = "productive";
+            } else if (allText.includes("?") && allText.split("?").length > 3) {
+              episode.mood = "exploratory";
+            } else {
+              episode.mood = "neutral";
+            }
+
+            await (sulcusMem as SulcusCloudClient).store_episode(episode)
+              .then((res) => logger.info(`sulcus: agent_end — stored structured episode (id: ${res?.id ?? "?"})`)
+              ).catch((e: unknown) => logger.debug?.(`sulcus: agent_end — episode store failed: ${e instanceof Error ? e.message : String(e)}`));
+          } catch (err) {
+            logger.debug?.("sulcus: agent_end episode capture threw: " + err);
+          }
+        });
+        logger.info("sulcus: registered agent_end episode capture (Phase 4)");
+      }
     }
 
     // -------------------------------------------------------------------------
@@ -4600,6 +5550,8 @@ const sulcusPlugin = {
     if (isAvailable && sulcusMem instanceof SulcusCloudClient) {
       const sessionPurgeApiOn = api.on as (event: string, handler: unknown) => void;
       sessionPurgeApiOn("agent_end", async () => {
+        // Phase 6: Reset namespace override on session end
+        activeNamespaceOverride = null;
         if (sessionMemoryIds.size === 0) return;
         const ids = Array.from(sessionMemoryIds);
         sessionMemoryIds.clear();