@digitalforgestudios/openclaw-sulcus 4.2.0 → 5.2.0

package/hooks.defaults.json

@@ -23,6 +23,11 @@
     "before_compaction": {
       "action": "pre_compaction_capture",
       "enabled": true
+    },
+    "llm_output_evaluation": {
+      "action": "evaluate_output",
+      "enabled": false,
+      "description": "Send LLM output to SILU for semantic alignment evaluation against memory. Requires silu_output_evaluation=true on the server per-agent config."
     }
   },
   "tools": {
@@ -37,6 +42,8 @@
     "siu_status": { "enabled": false },
     "siu_retrain": { "enabled": false },
     "trigger_feedback": { "enabled": false },
-    "__sulcus_workflow__": { "enabled": true }
+    "__sulcus_workflow__": { "enabled": true },
+    "memory_share": { "enabled": false },
+    "memory_cross_recall": { "enabled": false }
   }
 }

package/index.ts

@@ -233,64 +233,73 @@ const hookHandlers: Record<string, HookHandler> = {
     }
   },
 
-  pre_compaction_capture: async (event: Record<string, unknown>, _config: HookConfig, ctx: HookHandlerCtx) => {
+  pre_compaction_capture: async (event: Record<string, unknown>, config: HookConfig, ctx: HookHandlerCtx) => {
     const { sulcusMem, logger } = ctx;
     if (!sulcusMem) return;
 
     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 lastAssistant = [...messages].reverse().find((m) => m.role === "assistant" || m.type === "ai");
-
-    const firstUserText = typeof firstUser?.content === "string"
-      ? firstUser.content.substring(0, 200)
-      : typeof firstUser?.text === "string"
-        ? (firstUser.text as string).substring(0, 200)
-        : "(none)";
-
-    const lastAssistantText = typeof lastAssistant?.content === "string"
-      ? lastAssistant.content.substring(0, 200)
-      : typeof lastAssistant?.text === "string"
-        ? (lastAssistant.text as string).substring(0, 200)
-        : "(none)";
-
-    const filesModified: string[] = [];
-    for (const msg of messages) {
-      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);
-        }
-      }
+    const { decisions, preferences, facts, summary } = extractConversationInsights(messages);
+
+    const maxPerType = (config.maxCapturePerTurn as number) ?? 3;
+    const maxTotal = Math.min(maxPerType * 3, 9);
+
+    const stores: Promise<unknown>[] = [];
+    let dCount = 0, pCount = 0, fCount = 0;
+
+    for (const decision of decisions.slice(0, Math.min(3, maxPerType))) {
+      if (stores.length >= maxTotal) break;
+      if (!shouldCapture(decision)) continue;
+      stores.push(sulcusMem.add_memory(decision, "procedural").catch(() => {}));
+      dCount++;
     }
 
-    const summaryParts = [
-      `Session compaction — ${messages.length} messages`,
-      `First user message: ${firstUserText}`,
-      `Last assistant message: ${lastAssistantText}`,
-    ];
-    if (filesModified.length > 0) summaryParts.push(`Files modified: ${filesModified.join(", ")}`);
-    const summary = summaryParts.join("\n");
+    for (const pref of preferences.slice(0, Math.min(3, maxPerType))) {
+      if (stores.length >= maxTotal) break;
+      if (!shouldCapture(pref)) continue;
+      stores.push(sulcusMem.add_memory(pref, "preference").catch(() => {}));
+      pCount++;
+    }
 
-    if (!shouldCapture(summary)) {
-      logger.debug?.("sulcus: pre_compaction_capture — dedup skip");
-      return;
+    for (const fact of facts.slice(0, Math.min(3, maxPerType))) {
+      if (stores.length >= maxTotal) break;
+      if (!shouldCapture(fact)) continue;
+      stores.push(sulcusMem.add_memory(fact, "fact").catch(() => {}));
+      fCount++;
     }
 
-    try {
-      const res = await sulcusMem.add_memory(summary, "episodic");
-      logger.info(`sulcus: pre_compaction_capture — stored session summary (id: ${res?.id ?? "?"})`);
-    } catch (e: unknown) {
-      const msg = e instanceof Error ? e.message : String(e);
-      logger.debug?.(`sulcus: pre_compaction_capture — store failed: ${msg}`);
+    if (shouldCapture(summary)) {
+      stores.push(sulcusMem.add_memory(summary, "episodic").catch(() => {}));
     }
+
+    Promise.allSettled(stores);
+
+    logger.info(`sulcus: compaction mining — ${dCount} decisions, ${pCount} preferences, ${fCount} facts, 1 summary`);
   },
 };
 
+// ─── ENTITY CONTEXT TYPES ────────────────────────────────────────────────────
+
+interface EntityContextMemory {
+  id: string;
+  pointer_summary: string;
+  memory_type: string;
+  current_heat: number;
+}
+
+interface EntityConnection {
+  name: string;
+  relationship: string;
+}
+
+interface EntityContextResult {
+  name: string;
+  type: string;
+  related_memories: EntityContextMemory[];
+  connections: EntityConnection[];
+}
+
 // ─── CLOUD HTTP CLIENT ───────────────────────────────────────────────────────
 
 class SulcusCloudClient {
@@ -365,9 +374,36 @@ class SulcusCloudClient {
     return { results };
   }
 
-  async add_memory(content: string, memoryType?: string | null): Promise<{ id: string; [key: string]: unknown }> {
+  async hot_context(limit?: number, namespace?: string): Promise<{ results: Record<string, unknown>[] }> {
+    const body: Record<string, unknown> = {};
+    if (limit !== undefined) body.limit = limit;
+    if (namespace !== undefined) body.namespace = namespace;
+    const res = await this.request("POST", "/api/v1/agent/hot-context", body) as Record<string, unknown> | null;
+    const results = (res?.results ?? res?.items ?? res?.nodes ?? (Array.isArray(res) ? res : [])) as Record<string, unknown>[];
+    return { results };
+  }
+
+  async entity_context(entityNames: string[], namespace?: string, limit?: number): Promise<{ entities: EntityContextResult[] }> {
+    const body: Record<string, unknown> = { entity_names: entityNames };
+    if (namespace !== undefined) body.namespace = namespace;
+    if (limit !== undefined) body.limit = limit;
+    const res = await this.request("POST", "/api/v1/agent/entity-context", body) as Record<string, unknown> | null;
+    const entities = (res?.entities ?? (Array.isArray(res) ? res : [])) as EntityContextResult[];
+    return { entities };
+  }
+
+  async cross_namespace_search(query: string, targetNamespace: string, limit?: number): Promise<{ results: Record<string, unknown>[] }> {
+    const body: Record<string, unknown> = { query, namespace: targetNamespace };
+    if (limit !== undefined) body.limit = limit;
+    const res = await this.request("POST", "/api/v1/agent/search", body) as Record<string, unknown> | null;
+    const results = (res?.results ?? res?.items ?? res?.nodes ?? (Array.isArray(res) ? res : [])) as Record<string, unknown>[];
+    return { results };
+  }
+
+  async add_memory(content: string, memoryType?: string | null, namespace?: string): Promise<{ id: string; [key: string]: unknown }> {
     const body: Record<string, unknown> = { label: content };
     if (memoryType) body.memory_type = memoryType;
+    if (namespace) body.namespace = namespace;
     const res = await this.request("POST", "/api/v1/agent/nodes", body) as Record<string, unknown> | null;
     return (res ?? { id: "unknown" }) as { id: string; [key: string]: unknown };
   }
@@ -401,6 +437,21 @@ class SulcusCloudClient {
     return this.request("POST", "/api/v1/agent/import", { format: "markdown", content: text });
   }
 
+  async evaluate_output(
+    output: string,
+    context?: { prompt_summary?: string; agent_label?: string; model?: string },
+  ): Promise<{
+    alignment: { score: number; status: string; issues: unknown[]; corrections: unknown[] };
+    meta: { memories_checked: number; evaluation_ms: number; model: string };
+  }> {
+    const body: Record<string, unknown> = { output };
+    if (context) body.context = context;
+    return this.request("POST", "/api/v1/agent/evaluate-output", body) as Promise<{
+      alignment: { score: number; status: string; issues: unknown[]; corrections: unknown[] };
+      meta: { memories_checked: number; evaluation_ms: number; model: string };
+    }>;
+  }
+
   async evaluate_triggers(event: unknown, contextJson?: string): Promise<unknown> {
     const body: Record<string, unknown> = { event };
     if (contextJson) {
@@ -587,6 +638,132 @@ function shouldCapture(content: string): boolean {
   return true;
 }
 
+// ─── CONVERSATION INSIGHTS EXTRACTOR ─────────────────────────────────────────
+
+interface ConversationInsights {
+  decisions: string[];
+  preferences: string[];
+  facts: string[];
+  summary: string;
+}
+
+const DECISION_RE = /\b(decided to|going with|let'?s use|we'?ll go with|the plan is|agreed on)\b/i;
+const PREFERENCE_RE = /\b(actually[,\s]|no,\s|I prefer|don'?t use|always use\b|never\b|that'?s wrong|I meant)\b/i;
+const FACT_RE = /\bhttps?:\/\/\S+|\b\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}\b|port\s+\d{2,5}|v\d+\.\d+(?:\.\d+)?\b|version\s+\d|\bendpoint[s]?[:\s]+\S+|\bservice[:\s]+\S+/i;
+const CREDENTIAL_VALUE_RE = /\b(?:sk-[a-f0-9]{40,}|[A-Za-z0-9+/]{40,}={0,2})\b|(?:api[_-]?key|secret|password|token|auth)\s*[:=]\s*["']?[A-Za-z0-9._~+/=-]{16,}/i;
+
+function extractMsgText(msg: Record<string, unknown>): string {
+  const content = msg.content ?? msg.text;
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) {
+    return (content as Record<string, unknown>[])
+      .map((c) => (typeof c.text === "string" ? c.text : ""))
+      .join(" ");
+  }
+  return "";
+}
+
+function extractConversationInsights(messages: Record<string, unknown>[]): ConversationInsights {
+  const decisions: string[] = [];
+  const preferences: string[] = [];
+  const facts: string[] = [];
+  const seenDecisions = new Set<string>();
+  const seenPreferences = new Set<string>();
+  const seenFacts = new Set<string>();
+
+  let firstTimestamp: string | undefined;
+  let lastTimestamp: string | undefined;
+  const topicWords: string[] = [];
+
+  const TOPIC_STOP = new Set(["would", "could", "should", "there", "their", "about", "which", "where", "doing", "using", "while", "before", "after", "these", "those", "being", "other", "every", "under", "until"]);
+
+  const trunc = (s: string): string => s.length > 300 ? s.slice(0, 297) + "..." : s;
+
+  for (const msg of messages) {
+    const role = (msg.role ?? msg.type) as string | undefined;
+    const isUser = role === "user" || role === "human";
+    const isAssistant = role === "assistant" || role === "ai";
+    if (!isUser && !isAssistant) continue;
+
+    const ts = (msg.created_at ?? msg.timestamp ?? msg.ts) as string | undefined;
+    if (ts && !firstTimestamp) firstTimestamp = ts;
+    if (ts) lastTimestamp = ts;
+
+    const text = extractMsgText(msg);
+    if (!text) continue;
+
+    for (const line of text.split(/\n/)) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.length < 10) continue;
+      if (CREDENTIAL_VALUE_RE.test(trimmed)) continue;
+
+      if (decisions.length < 3 && DECISION_RE.test(trimmed)) {
+        const key = trimmed.slice(0, 60).toLowerCase();
+        if (!seenDecisions.has(key)) {
+          seenDecisions.add(key);
+          decisions.push(trunc(`Decision: ${trimmed}`));
+        }
+      }
+
+      if (preferences.length < 3 && isUser && PREFERENCE_RE.test(trimmed)) {
+        const key = trimmed.slice(0, 60).toLowerCase();
+        if (!seenPreferences.has(key)) {
+          seenPreferences.add(key);
+          preferences.push(trunc(`User preference: ${trimmed}`));
+        }
+      }
+
+      if (facts.length < 3 && FACT_RE.test(trimmed)) {
+        const key = trimmed.slice(0, 60).toLowerCase();
+        if (!seenFacts.has(key)) {
+          seenFacts.add(key);
+          facts.push(trunc(trimmed));
+        }
+      }
+    }
+
+    if (isUser && topicWords.length < 8) {
+      const words = text.match(/\b[a-zA-Z]{5,}\b/g) ?? [];
+      for (const w of words) {
+        const wl = w.toLowerCase();
+        if (!TOPIC_STOP.has(wl) && !topicWords.includes(wl)) {
+          topicWords.push(wl);
+          if (topicWords.length >= 8) break;
+        }
+      }
+    }
+  }
+
+  const firstUser = messages.find((m) => m.role === "user" || m.type === "human");
+  const lastAssistant = [...messages].reverse().find((m) => m.role === "assistant" || m.type === "ai");
+  const firstUserText = extractMsgText(firstUser ?? {}).substring(0, 200) || "(none)";
+  const lastAssistantText = extractMsgText(lastAssistant ?? {}).substring(0, 200) || "(none)";
+
+  const filesModified: string[] = [];
+  for (const msg of messages) {
+    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);
+      }
+    }
+  }
+
+  const summaryParts = [`Session compaction — ${messages.length} messages`];
+  if (firstTimestamp || lastTimestamp) {
+    summaryParts.push(`Time range: ${[firstTimestamp, lastTimestamp].filter(Boolean).join(" → ")}`);
+  }
+  if (topicWords.length > 0) summaryParts.push(`Topics: ${topicWords.join(", ")}`);
+  summaryParts.push(`First user message: ${firstUserText}`);
+  summaryParts.push(`Last assistant message: ${lastAssistantText}`);
+  if (filesModified.length > 0) summaryParts.push(`Files modified: ${filesModified.join(", ")}`);
+
+  return { decisions, preferences, facts, summary: summaryParts.join("\n") };
+}
+
 // ─── HOOKS CONFIG LOADER ─────────────────────────────────────────────────────
 
 function loadHooksConfig(apiConfig: Record<string, unknown>): HooksConfig {
@@ -614,6 +791,8 @@ function loadHooksConfig(apiConfig: Record<string, unknown>): HooksConfig {
         import_markdown: { enabled: false },
         evaluate_triggers: { enabled: false },
         __sulcus_workflow__: { enabled: true },
+        memory_share: { enabled: false },
+        memory_cross_recall: { enabled: false },
       },
     };
   }
@@ -664,6 +843,27 @@ function formatRelativeTime(isoTimestamp: string): string {
   }
 }
 
+// ─── ENTITY EXTRACTION HELPER ────────────────────────────────────────────────
+
+/// Extract candidate entity names from memory recall results.
+/// Heuristic: capitalized words/tokens longer than 3 chars from label/pointer_summary.
+/// Returns up to 5 unique names.
+function extractEntityNames(results: Record<string, unknown>[]): string[] {
+  const seen = new Set<string>();
+  for (const r of results) {
+    const text = ((r.label ?? r.pointer_summary ?? "") as string).trim();
+    if (!text) continue;
+    for (const token of text.split(/\s+/)) {
+      const clean = token.replace(/[^a-zA-Z0-9]/g, "");
+      if (clean.length > 3 && /^[A-Z]/.test(clean) && !seen.has(clean)) {
+        seen.add(clean);
+        if (seen.size >= 5) return Array.from(seen);
+      }
+    }
+  }
+  return Array.from(seen);
+}
+
 // ─── SDK RECALL HANDLER (for before_agent_start with prependContext) ──────────
 
 interface ProfileCache {
@@ -761,6 +961,266 @@ function buildSdkRecallHandler(
   };
 }
 
+// ─── PROMPT BUILD HANDLER ─────────────────────────────────────────────────────
+
+function buildPromptBuildHandler(
+  sulcusMem: SulcusCloudClient,
+  namespace: string,
+  maxResults: number,
+  tokenBudget: number,
+  logger: PluginLogger,
+  sharedNamespaces: string[] = [],
+  triggerProcessor?: TriggerResultProcessor
+) {
+  return async (event: Record<string, unknown>, _ctx: unknown): Promise<{ prependContext: string } | undefined> => {
+    // Extract the latest user message from event.messages or fall back to event.prompt
+    let query = "";
+    const messages = event?.messages;
+    if (Array.isArray(messages)) {
+      for (let i = messages.length - 1; i >= 0; i--) {
+        const msg = messages[i] as Record<string, unknown>;
+        if (msg?.role === "user") {
+          const content = msg?.content;
+          query = typeof content === "string" ? content : (Array.isArray(content) ? content.map((c) => (c as Record<string, unknown>)?.text ?? "").join(" ") : "");
+          break;
+        }
+      }
+    }
+    if (!query && typeof event?.prompt === "string") query = event.prompt;
+    if (!query || query.length < 5) return undefined;
+
+    const charBudget = tokenBudget * 4;
+    const allResults: Record<string, unknown>[] = [];
+    const seenIds = new Set<string>();
+
+    // L0/L1: hot-context first (always-on, highest priority)
+    try {
+      const hotRes = await sulcusMem.hot_context(5, namespace);
+      for (const r of hotRes.results) {
+        const id = r.id as string;
+        if (id && !seenIds.has(id)) { seenIds.add(id); allResults.push(r); }
+      }
+    } catch (err) {
+      logger.warn(`sulcus: hot-context unavailable, falling back to search-only: ${err}`);
+    }
+
+    // Semantic search against the user's message
+    try {
+      const searchRes = await sulcusMem.search_memory(query, maxResults, namespace);
+      for (const r of searchRes.results) {
+        const id = r.id as string;
+        if (id && !seenIds.has(id)) { seenIds.add(id); allResults.push(r); }
+      }
+    } catch (err) {
+      logger.warn(`sulcus: prompt-build search failed: ${err}`);
+    }
+
+    if (allResults.length === 0) return undefined;
+
+    // Extract entity names from recall results for graph enrichment
+    const entityNames = extractEntityNames(allResults);
+
+    // Graph enrichment: fetch entity context (best-effort, 2s timeout)
+    let entityContextResults: EntityContextResult[] = [];
+    if (entityNames.length > 0) {
+      try {
+        const entityRes = await Promise.race([
+          sulcusMem.entity_context(entityNames, namespace, 3),
+          new Promise<never>((_, reject) => setTimeout(() => reject(new Error("timeout")), 2000)),
+        ]);
+        entityContextResults = entityRes.entities;
+      } catch (_err) {
+        // best-effort — skip silently
+      }
+    }
+
+    // Format memories, respecting the token budget
+    const memLines: string[] = [];
+    let usedChars = 0;
+    for (const r of allResults) {
+      const heat = ((r.current_heat as number) ?? (r.score as number) ?? 0);
+      const pct = `[${Math.round(heat * 100)}%]`;
+      const updatedAt = r.updated_at as string | undefined;
+      const timeStr = updatedAt ? `[${formatRelativeTime(updatedAt)}]` : "";
+      const label = (r.label ?? r.pointer_summary ?? r.id ?? "") as string;
+      const line = `- ${pct} ${timeStr} ${label}`.trim();
+      if (usedChars + line.length > charBudget) break;
+      memLines.push(line);
+      usedChars += line.length + 1;
+    }
+
+    if (memLines.length === 0) return undefined;
+
+    const intro =
+      "The following is background context from long-term memory. Use it silently to inform your understanding — only reference it when the conversation naturally calls for it.";
+
+    const bodySections: string[] = [`## Relevant Memories\n${memLines.join("\n")}`];
+
+    // Entity Context: one line per entity showing connections (budget-capped)
+    if (entityContextResults.length > 0) {
+      const entityLines: string[] = [];
+      for (const entity of entityContextResults) {
+        const connNames = entity.connections.map((c) => c.name).filter(Boolean);
+        const memCount = entity.related_memories.length;
+        const parts: string[] = [];
+        if (connNames.length > 0) parts.push(`connected to [${connNames.join(", ")}]`);
+        if (memCount > 0) parts.push(`${memCount} related memories`);
+        if (parts.length === 0) continue;
+        const line = `- ${entity.name}: ${parts.join(", ")}`;
+        if (usedChars + line.length > charBudget) break;
+        entityLines.push(line);
+        usedChars += line.length + 1;
+      }
+      if (entityLines.length > 0) {
+        bodySections.push(`## Entity Context\n${entityLines.join("\n")}`);
+      }
+    }
+
+    // Drain up to 3 pending trigger notifications (oldest first)
+    if (triggerProcessor) {
+      const notifications = triggerProcessor.drainNotifications(3);
+      if (notifications.length > 0) {
+        const notifLines = notifications.map((n) => `- You should know: ${n}`).join("\n");
+        bodySections.push(`## Trigger Notifications\n${notifLines}`);
+      }
+    }
+
+    // Shared context from cross-namespace namespaces (opt-in via sharedNamespaces config)
+    if (sharedNamespaces.length > 0) {
+      const sharedLines: string[] = [];
+      for (const sharedNs of sharedNamespaces) {
+        try {
+          const sharedRes = await sulcusMem.cross_namespace_search(query, sharedNs, Math.min(maxResults, 3));
+          for (const r of sharedRes.results) {
+            if (usedChars >= charBudget) break;
+            const heat = ((r.current_heat as number) ?? (r.score as number) ?? 0);
+            const pct = `[${Math.round(heat * 100)}%]`;
+            const label = (r.label ?? r.pointer_summary ?? r.id ?? "") as string;
+            const line = `- [${sharedNs}] ${pct} ${label}`.trim();
+            if (usedChars + line.length > charBudget) break;
+            sharedLines.push(line);
+            usedChars += line.length + 1;
+          }
+        } catch (_sharedErr) {
+          // best-effort cross-namespace fetch — skip silently
+        }
+      }
+      if (sharedLines.length > 0) {
+        bodySections.push(`## Shared Context\n${sharedLines.join("\n")}`);
+      }
+    }
+
+    const body = bodySections.join("\n\n");
+    const context = `<sulcus_context token_budget="${tokenBudget}" namespace="${namespace}">\n${intro}\n\n${body}\n</sulcus_context>`;
+
+    logger.info(`sulcus: before_prompt_build injecting context (${context.length} chars, ${memLines.length} memories)`);
+    return { prependContext: context };
+  };
+}
+
+// ─── TRIGGER RESULT PROCESSOR ────────────────────────────────────────────────
+
+interface TriggerResult {
+  trigger_id: string;
+  trigger_name: string;
+  action: string;
+  success: boolean;
+  message?: string;
+  data?: Record<string, unknown>;
+}
+
+class TriggerResultProcessor {
+  private notificationBuffer: string[] = [];
+  private readonly MAX_BUFFER = 10;
+
+  // Session telemetry
+  totalTriggerFires = 0;
+  triggerFiresByAction: Record<string, number> = {};
+
+  constructor(
+    private sulcusMem: SulcusCloudClient | null,
+    private logger: PluginLogger
+  ) {}
+
+  process(results: unknown): void {
+    let items: TriggerResult[];
+    try {
+      if (Array.isArray(results)) {
+        items = results as TriggerResult[];
+      } else if (results && typeof results === "object") {
+        const r = results as Record<string, unknown>;
+        items = Array.isArray(r.results) ? (r.results as TriggerResult[]) : [(results as TriggerResult)];
+      } else {
+        return;
+      }
+    } catch {
+      return;
+    }
+
+    for (const result of items) {
+      try {
+        this._processOne(result);
+      } catch (e) {
+        this.logger.warn(`sulcus: trigger processor error on '${result?.trigger_name ?? "?"}': ${e}`);
+      }
+    }
+  }
+
+  private _processOne(result: TriggerResult): void {
+    if (!result.success) {
+      this.logger.warn(`sulcus: trigger '${result.trigger_name}' failed: ${result.message ?? "(no message)"}`);
+      return;
+    }
+
+    this.totalTriggerFires++;
+    this.triggerFiresByAction[result.action] = (this.triggerFiresByAction[result.action] ?? 0) + 1;
+
+    const action = result.action;
+
+    if (action === "notify") {
+      const msg =
+        result.message ??
+        (result.data?.message as string | undefined) ??
+        `Trigger '${result.trigger_name}' fired`;
+      this.logger.info(`sulcus: trigger notify — ${msg}`);
+
+      // Store as episodic memory (fire-and-forget) so the notification survives
+      if (this.sulcusMem) {
+        this.sulcusMem.add_memory(`[trigger_notification] ${msg}`, "episodic").catch((e: unknown) => {
+          this.logger.warn(`sulcus: trigger notification store failed: ${e instanceof Error ? e.message : String(e)}`);
+        });
+      }
+
+      // Append to circular buffer (oldest evicted when full)
+      this.notificationBuffer.push(msg);
+      if (this.notificationBuffer.length > this.MAX_BUFFER) {
+        this.notificationBuffer.shift();
+      }
+    } else if (action === "boost" || action === "pin" || action === "tag" || action === "deprecate") {
+      this.logger.info(`sulcus: trigger server-side action '${action}' completed for trigger '${result.trigger_name}'`);
+    } else if (action === "webhook") {
+      this.logger.info(`sulcus: trigger webhook fired for '${result.trigger_name}'`);
+    } else if (action === "chain") {
+      this.logger.info(`sulcus: trigger chain fired for '${result.trigger_name}'`);
+    } else {
+      this.logger.info(`sulcus: trigger '${result.trigger_name}' action='${action}' completed`);
+    }
+  }
+
+  /** Drain up to `max` notifications from the front of the buffer (oldest first). */
+  drainNotifications(max: number): string[] {
+    return this.notificationBuffer.splice(0, max);
+  }
+
+  logSessionSummary(): void {
+    if (this.totalTriggerFires === 0) return;
+    const byAction = Object.entries(this.triggerFiresByAction)
+      .map(([a, n]) => `${a}: ${n}`)
+      .join(", ");
+    this.logger.info(`sulcus: session trigger summary — total=${this.totalTriggerFires} (${byAction})`);
+  }
+}
+
 // ─── MEMORY RUNTIME BUILDER ───────────────────────────────────────────────────
 
 function buildMemoryRuntime(sulcusMem: SulcusCloudClient, backendMode: string) {
@@ -769,7 +1229,7 @@ function buildMemoryRuntime(sulcusMem: SulcusCloudClient, backendMode: string) {
       return {
         backend: "builtin" as const,
         provider: "sulcus",
-        model: backendMode === "cloud" ? "sulcus-cloud" : "sulcus-local",
+        model: backendMode === "cloud" ? "sulcus-cloud" : "sulcus",
         custom: { backendMode, transport: backendMode === "cloud" ? "remote" : "local" },
       };
     },
@@ -836,6 +1296,7 @@ interface ToolDeps {
   logger: PluginLogger;
   isAvailable: boolean;
   siuRequest: ((method: string, path: string, body?: unknown) => Promise<unknown>) | null;
+  triggerProcessor?: TriggerResultProcessor;
 }
 
 interface ToolDefinition {
@@ -857,12 +1318,22 @@ const toolDefinitions: Record<string, ToolDefinition> = {
       }),
     },
     options: { name: "memory_recall" },
-    makeExecute: ({ sulcusMem, backendMode, namespace, nativeLoader, isAvailable }) =>
+    makeExecute: ({ sulcusMem, backendMode, namespace, nativeLoader, isAvailable, logger, triggerProcessor }) =>
       async (_id, params) => {
         if (!isAvailable || !sulcusMem) throw new Error(`Sulcus unavailable: ${nativeLoader.error || "not loaded"}`);
         const searchNamespace = (params.namespace as string | undefined) ?? namespace;
         const res = await sulcusMem.search_memory(params.query as string, (params.limit as number | undefined) ?? 5, searchNamespace);
         const results = res?.results ?? [];
+
+        // Fire-and-forget: evaluate on_recall triggers concurrently (non-blocking)
+        if (triggerProcessor) {
+          const topIds = results.slice(0, 3).map((r) => r.id as string).filter(Boolean);
+          const triggerCtx = JSON.stringify({ query: params.query as string, result_ids: topIds });
+          sulcusMem.evaluate_triggers("on_recall", triggerCtx)
+            .then((triggerResults) => triggerProcessor.process(triggerResults))
+            .catch((e: unknown) => logger.warn(`sulcus: on_recall trigger evaluation failed: ${e instanceof Error ? e.message : String(e)}`));
+        }
+
         return {
           content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
           details: { results: results as unknown as Record<string, unknown>[], backend: backendMode, namespace: searchNamespace },
@@ -885,7 +1356,7 @@ const toolDefinitions: Record<string, ToolDefinition> = {
       }),
     },
     options: { name: "memory_store" },
-    makeExecute: ({ sulcusMem, backendMode, namespace, nativeLoader, isAvailable, logger }) =>
+    makeExecute: ({ sulcusMem, backendMode, namespace, nativeLoader, isAvailable, logger, triggerProcessor }) =>
       async (_id, params) => {
         const content = params.content as string;
         if (isJunkMemory(content)) {
@@ -896,6 +1367,15 @@ const toolDefinitions: Record<string, ToolDefinition> = {
         const mtype = (params.memory_type as string | undefined) || "episodic";
         const res = await sulcusMem.add_memory(content, mtype);
         const nodeId = res?.id ?? "unknown";
+
+        // Fire-and-forget: evaluate on_store triggers (non-blocking)
+        if (triggerProcessor) {
+          const triggerCtx = JSON.stringify({ content, memory_type: mtype, id: nodeId });
+          sulcusMem.evaluate_triggers("on_store", triggerCtx)
+            .then((triggerResults) => triggerProcessor.process(triggerResults))
+            .catch((e: unknown) => logger.warn(`sulcus: on_store trigger evaluation failed: ${e instanceof Error ? e.message : String(e)}`));
+        }
+
         let trainResult: string | null = null;
         if (params.train === true) {
           try {
@@ -1159,6 +1639,96 @@ const toolDefinitions: Record<string, ToolDefinition> = {
         };
       },
   },
+
+  memory_share: {
+    schema: {
+      name: "memory_share",
+      label: "Memory Share",
+      description: "Share a memory with another agent by storing it in their namespace. Use for cross-agent context sharing.",
+      parameters: Type.Object({
+        content: Type.String({ description: "The memory to share." }),
+        target_namespace: Type.String({ description: "The agent namespace to share with." }),
+        memory_type: Type.Optional(Type.String({ description: "Memory type. Defaults to 'semantic'." })),
+        source_note: Type.Optional(Type.String({ description: "Optional note about where this came from." })),
+      }),
+    },
+    options: { name: "memory_share" },
+    makeExecute: ({ sulcusMem, namespace, nativeLoader, isAvailable, logger }) =>
+      async (_id, params) => {
+        if (!isAvailable || !sulcusMem) throw new Error(`Sulcus unavailable: ${nativeLoader.error || "not loaded"}`);
+        const content = params.content as string;
+        const targetNamespace = params.target_namespace as string;
+        const memoryType = (params.memory_type as string | undefined) ?? "semantic";
+        const sourceNote = params.source_note as string | undefined;
+
+        const sharedContent = `[Shared by ${namespace}] ${content}${sourceNote ? ` (source: ${sourceNote})` : ""}`;
+        const refContent = `[Shared to ${targetNamespace}] ${content.substring(0, 100)}${content.length > 100 ? "..." : ""}`;
+
+        let sharedId = "unknown";
+        let refId = "unknown";
+
+        try {
+          const sharedRes = await (sulcusMem as SulcusCloudClient).add_memory(sharedContent, memoryType, targetNamespace);
+          sharedId = sharedRes?.id ?? "unknown";
+        } catch (e: unknown) {
+          const msg = e instanceof Error ? e.message : String(e);
+          logger.warn(`sulcus: memory_share — failed to store in target namespace: ${msg}`);
+          return { content: [{ type: "text", text: `Failed to share memory to namespace '${targetNamespace}': ${msg}` }] };
+        }
+
+        try {
+          const refRes = await (sulcusMem as SulcusCloudClient).add_memory(refContent, "semantic");
+          refId = refRes?.id ?? "unknown";
+        } catch (_e) {
+          // best-effort reference store
+        }
+
+        logger.info(`sulcus: memory_share — shared to '${targetNamespace}' (shared_id: ${sharedId}, ref_id: ${refId})`);
+        return {
+          content: [{ type: "text", text: `Shared memory to namespace '${targetNamespace}' (id: ${sharedId}). Reference stored locally (id: ${refId}).` }],
+          details: { shared_id: sharedId, ref_id: refId, target_namespace: targetNamespace, memory_type: memoryType },
+        };
+      },
+  },
+
+  memory_cross_recall: {
+    schema: {
+      name: "memory_cross_recall",
+      label: "Memory Cross-Recall",
+      description: "Search another agent's memories. Useful for checking what another agent knows about a topic. Requires cross-namespace access.",
+      parameters: Type.Object({
+        query: Type.String({ description: "Search query string." }),
+        target_namespace: Type.String({ description: "The agent namespace to search in." }),
+        limit: Type.Optional(Type.Number({ default: 5, description: "Maximum number of results to return (1-10)." })),
+      }),
+    },
+    options: { name: "memory_cross_recall" },
+    makeExecute: ({ sulcusMem, nativeLoader, isAvailable, logger }) =>
+      async (_id, params) => {
+        if (!isAvailable || !sulcusMem) throw new Error(`Sulcus unavailable: ${nativeLoader.error || "not loaded"}`);
+        const targetNamespace = params.target_namespace as string;
+        const query = params.query as string;
+        const limit = (params.limit as number | undefined) ?? 5;
+
+        try {
+          const res = await (sulcusMem as SulcusCloudClient).cross_namespace_search(query, targetNamespace, limit);
+          const results = res?.results ?? [];
+          const prefixed = results.map((r) => ({ ...r, _source: `[from ${targetNamespace}]` }));
+          logger.info(`sulcus: memory_cross_recall — ${results.length} results from '${targetNamespace}'`);
+          return {
+            content: [{ type: "text", text: JSON.stringify(prefixed, null, 2) }],
+            details: { results: prefixed as unknown as Record<string, unknown>[], target_namespace: targetNamespace },
+          };
+        } catch (e: unknown) {
+          const msg = e instanceof Error ? e.message : String(e);
+          if (msg.includes("HTTP 403") || msg.includes("403")) {
+            return { content: [{ type: "text", text: `Access denied to namespace '${targetNamespace}': insufficient permissions (403).` }] };
+          }
+          logger.warn(`sulcus: memory_cross_recall — failed: ${msg}`);
+          return { content: [{ type: "text", text: `Cross-namespace recall failed for '${targetNamespace}': ${msg}` }] };
+        }
+      },
+  },
 };
 
 // ─── FIRST-INSTALL HISTORY IMPORT ────────────────────────────────────────────
@@ -1270,6 +1840,10 @@ const sulcusPlugin = {
     const autoCapture: boolean = (pluginConfig?.autoCapture as boolean | undefined) ?? false;
     const maxRecallResults: number = Math.min(20, Math.max(1, (pluginConfig?.maxRecallResults as number | undefined) ?? 5));
     const profileFrequency: number = Math.min(500, Math.max(1, (pluginConfig?.profileFrequency as number | undefined) ?? 10));
+    // Phase 6: cross-agent config (v4.7.0)
+    const sharedNamespaces: string[] = Array.isArray(pluginConfig?.sharedNamespaces)
+      ? (pluginConfig.sharedNamespaces as string[]).filter((s) => typeof s === "string" && s.length > 0)
+      : [];
 
     // ── Load hooks config ──
     const hooksConfig = loadHooksConfig(pluginConfig);
@@ -1335,6 +1909,11 @@ const sulcusPlugin = {
       ? (method: string, path: string, body?: unknown) => (sulcusMem as SulcusCloudClient).request(method, path, body)
       : null;
 
+    // ── Trigger result processor (Phase 3) ──
+    const triggerProcessor = isCloudBackend && sulcusMem
+      ? new TriggerResultProcessor(sulcusMem, logger)
+      : undefined;
+
     // ── Shared deps ──
     const toolDeps: ToolDeps = {
       sulcusMem,
@@ -1347,6 +1926,7 @@ const sulcusPlugin = {
       logger,
       isAvailable,
       siuRequest: siuRequestFn,
+      triggerProcessor,
     };
 
     const handlerCtx: HookHandlerCtx = {
@@ -1429,27 +2009,86 @@ const sulcusPlugin = {
       }
     }
 
-    // 5. Enhanced before_agent_start with prependContext (SDK path)
-    //    When autoRecall=true and cloud backend available, use prependContext SDK pattern.
-    //    Falls back to legacy hook-based path when SDK is not available.
+    // 5. before_prompt_build: hot-context + semantic recall injection (SDK path)
+    //    Fires every turn, has access to event.messages and event.prompt.
+    //    Uses hot-context endpoint first (L0/L1), then falls back to search.
     if (autoRecall && isCloudBackend && sulcusMem) {
-      const sdkRecallHandler = buildSdkRecallHandler(
+      const promptBuildHandler = buildPromptBuildHandler(
         sulcusMem as SulcusCloudClient,
         namespace,
         maxRecallResults,
-        profileFrequency,
-        logger
+        500,
+        logger,
+        sharedNamespaces,
+        triggerProcessor
       );
       const apiOn = api.on as (event: string, handler: unknown) => void;
-      apiOn("before_agent_start", async (event: Record<string, unknown>, ctx: unknown) => {
+      apiOn("before_prompt_build", async (event: Record<string, unknown>, ctx: unknown) => {
         try {
-          return await sdkRecallHandler(event, ctx);
+          return await promptBuildHandler(event, ctx);
         } catch (err) {
-          logger.warn("sulcus: SDK recall hook threw: " + err);
+          logger.warn("sulcus: before_prompt_build hook threw: " + err);
           return undefined;
         }
       });
-      logger.info("sulcus: registered SDK auto-recall (prependContext path)");
+      logger.info("sulcus: registered before_prompt_build recall (hot-context + search)");
+    }
+
+    // 5b. Lifecycle hooks: session_start, session_end, before_reset
+    {
+      const apiOn = api.on as (event: string, handler: unknown) => void;
+
+      apiOn("session_start", async (_event: Record<string, unknown>, _ctx: unknown) => {
+        try {
+          logger.info("sulcus: session_start — session opened");
+        } catch (err) {
+          logger.warn("sulcus: session_start hook threw: " + err);
+        }
+        return undefined;
+      });
+
+      // session_end trigger telemetry (always registered)
+      apiOn("session_end", async (_event: Record<string, unknown>, _ctx: unknown) => {
+        try {
+          triggerProcessor?.logSessionSummary();
+        } catch (err) {
+          logger.warn("sulcus: session_end trigger telemetry threw: " + err);
+        }
+        return undefined;
+      });
+
+      if (autoCapture && sulcusMem) {
+        const captureConfig: HookConfig = {
+          action: "sivu_auto_capture",
+          enabled: true,
+          min_store_confidence: 0.5,
+          fallback_on_error: true,
+        };
+
+        apiOn("session_end", async (event: Record<string, unknown>, _ctx: unknown) => {
+          try {
+            logger.info("sulcus: session_end — running final memory extraction");
+            return await hookHandlers.sivu_auto_capture(event, captureConfig, handlerCtx);
+          } catch (err) {
+            logger.warn("sulcus: session_end hook threw: " + err);
+            return undefined;
+          }
+        });
+
+        apiOn("before_reset", async (event: Record<string, unknown>, _ctx: unknown) => {
+          try {
+            logger.info("sulcus: before_reset — extracting memories before context wipe");
+            return await hookHandlers.sivu_auto_capture(event, captureConfig, handlerCtx);
+          } catch (err) {
+            logger.warn("sulcus: before_reset hook threw: " + err);
+            return undefined;
+          }
+        });
+
+        logger.info("sulcus: registered session_start, session_end, before_reset lifecycle hooks");
+      } else {
+        logger.info("sulcus: registered session_start lifecycle hook");
+      }
     }
 
     // 6. auto-capture on agent_end
@@ -1472,6 +2111,308 @@ const sulcusPlugin = {
       logger.info("sulcus: registered auto-capture (agent_end)");
     }
 
+    // ─────────────────────────────────────────────────────────────────────────
+    // PHASE 2: OBSERVATION LAYER HOOKS
+    // ─────────────────────────────────────────────────────────────────────────
+    {
+      const apiOn = api.on as (event: string, handler: unknown) => void;
+
+      // llm_input — observe the final payload sent to the LLM
+      if (isCloudBackend) {
+        apiOn("llm_input", async (event: Record<string, unknown>, _ctx: unknown) => {
+          try {
+            const systemPrompt = (event.systemPrompt as string) ?? "";
+            const prompt = (event.prompt as string) ?? "";
+            const model = (event.model as string) ?? "unknown";
+            const historyMessages = (event.historyMessages as unknown[]) ?? [];
+
+            // Count memories that made it into the prompt via sulcus_context block
+            const sulcusContextMatch = (systemPrompt + prompt).match(/<sulcus_context>([\s\S]*?)<\/sulcus_context>/);
+            const memoryLines = sulcusContextMatch
+              ? sulcusContextMatch[1].split("\n").filter((l) => l.trim().length > 0).length
+              : 0;
+
+            // Approximate token count (rough: chars / 4)
+            const totalChars =
+              systemPrompt.length +
+              prompt.length +
+              historyMessages.reduce((sum: number, m: unknown) => {
+                const msg = m as Record<string, unknown>;
+                return sum + String(msg.content ?? "").length;
+              }, 0);
+            const approxTokens = Math.round(totalChars / 4);
+
+            logger.info(
+              `sulcus: llm_input — ${memoryLines} memories in context, ~${approxTokens} tokens, model=${model}`
+            );
+          } catch (err) {
+            logger.warn("sulcus: llm_input hook threw: " + err);
+          }
+          return undefined;
+        });
+      }
+
+      // llm_output — observe the raw response from the LLM
+      if (isCloudBackend) {
+        const failurePattern = /\b(error|failed|doesn['']t work|cannot|unable to)\b/i;
+        apiOn("llm_output", async (event: Record<string, unknown>, _ctx: unknown) => {
+          try {
+            const assistantTexts = (event.assistantTexts as string[]) ?? [];
+            const usage = (event.usage as Record<string, number>) ?? {};
+            const inputTokens = usage.inputTokens ?? 0;
+            const outputTokens = usage.outputTokens ?? 0;
+            const cacheReadTokens = usage.cacheReadTokens ?? 0;
+
+            logger.info(
+              `sulcus: llm_output — input=${inputTokens}, output=${outputTokens}, cache_read=${cacheReadTokens}`
+            );
+
+            if (autoCapture && sulcusMem) {
+              const fullText = assistantTexts.join(" ");
+              if (failurePattern.test(fullText)) {
+                const snippet = fullText.slice(0, 200);
+                try {
+                  await (sulcusMem as SulcusCloudClient).add_memory(
+                    `[Agent reported failure] ${snippet}`,
+                    "episodic"
+                  );
+                } catch (storeErr) {
+                  logger.warn("sulcus: llm_output failure memory store threw: " + storeErr);
+                }
+              }
+            }
+
+            // --- SILU Output Evaluation (recursive LM supervisor) ---
+            const evalHook = hooksConfig.hooks["llm_output_evaluation"];
+            if (evalHook?.enabled && sulcusMem && isCloudBackend) {
+              const fullText = assistantTexts.join(" ");
+              if (fullText.length > 20) {
+                // Fire-and-forget: don't block the response pipeline
+                const promptSummary = String(event.promptSummary ?? event.prompt_summary ?? "");
+                const model = String(event.model ?? "");
+                (sulcusMem as SulcusCloudClient).evaluate_output(
+                  fullText,
+                  { prompt_summary: promptSummary || undefined, model: model || undefined }
+                ).then((result) => {
+                  if (result?.alignment?.status !== "aligned") {
+                    logger.info(
+                      `sulcus: SILU evaluation — score=${result.alignment.score}, ` +
+                      `status=${result.alignment.status}, issues=${result.alignment.issues.length}, ` +
+                      `corrections=${result.alignment.corrections.length}`
+                    );
+                    // Store misalignment as episodic memory for learning
+                    if (result.alignment.issues.length > 0) {
+                      const issuesSummary = result.alignment.issues
+                        .map((i: unknown) => {
+                          const issue = i as Record<string, string>;
+                          return `[${issue.type}] ${issue.description ?? issue.detail ?? ""}`;
+                        })
+                        .join("; ");
+                      (sulcusMem as SulcusCloudClient).add_memory(
+                        `[SILU evaluation — ${result.alignment.status}] score=${result.alignment.score}: ${issuesSummary}`,
+                        "episodic"
+                      ).catch((e: unknown) => logger.warn(`sulcus: SILU eval memory store failed: ${e}`));
+                    }
+                  } else {
+                    logger.debug?.(`sulcus: SILU evaluation — aligned (score=${result.alignment.score})`);
+                  }
+                }).catch((e: unknown) => {
+                  logger.warn(`sulcus: SILU output evaluation failed: ${e}`);
+                });
+              }
+            }
+          } catch (err) {
+            logger.warn("sulcus: llm_output hook threw: " + err);
+          }
+          return undefined;
+        });
+      }
+
+      // message_received — classify inbound message for telemetry (observation only)
+      apiOn("message_received", async (event: Record<string, unknown>, _ctx: unknown) => {
+        try {
+          const message = String(event.message ?? event.content ?? "");
+          if (/\b(actually|no,|that'?s wrong|correction:|I meant)\b/i.test(message)) {
+            logger.info("sulcus: message_received — classified as correction");
+          } else if (/\b(I prefer|I like|I don'?t like|always use|never use)\b/i.test(message)) {
+            logger.info("sulcus: message_received — classified as preference statement");
+          } else if (/\b(remember when|did we|what was|last time)\b/i.test(message)) {
+            logger.info("sulcus: message_received — classified as question about past");
+          }
+        } catch (err) {
+          logger.warn("sulcus: message_received hook threw: " + err);
+        }
+        return undefined;
+      });
+
+      // before_dispatch — lightweight telemetry before the agent loop
+      apiOn("before_dispatch", async (event: Record<string, unknown>, _ctx: unknown) => {
+        try {
+          const message = String(event.message ?? event.content ?? "");
+          logger.info(`sulcus: before_dispatch — message length=${message.length}`);
+        } catch (err) {
+          logger.warn("sulcus: before_dispatch hook threw: " + err);
+        }
+        return undefined;
+      });
+
+      logger.info("sulcus: registered observation layer hooks (llm_input, llm_output, message_received, before_dispatch)");
+    }
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // PHASE 3: FULL LIFECYCLE COVERAGE
+    // ─────────────────────────────────────────────────────────────────────────
+    {
+      const apiOn = api.on as (event: string, handler: unknown) => void;
+
+      // after_compaction — store a summary of the compacted context as an episodic memory
+      apiOn("after_compaction", async (event: Record<string, unknown>, _ctx: unknown) => {
+        try {
+          const messageCount = (event.messageCount as number) ?? (event.compactedCount as number) ?? 0;
+          const summary = (event.summary as string) ?? (event.compactionSummary as string) ?? "";
+          logger.info(`sulcus: after_compaction — ${messageCount} messages compacted`);
+          if (sulcusMem && summary) {
+            const memContent = `[after_compaction] ${messageCount} messages compacted. ${summary.slice(0, 400)}`;
+            await (sulcusMem as SulcusCloudClient).add_memory(memContent, "episodic").catch((e: unknown) => {
+              logger.warn(`sulcus: after_compaction memory store failed: ${e instanceof Error ? e.message : String(e)}`);
+            });
+          }
+        } catch (err) {
+          logger.warn("sulcus: after_compaction hook threw: " + err);
+        }
+        return undefined;
+      });
+
+      // message_sending — check for memory-related corrections before outbound send
+      apiOn("message_sending", async (event: Record<string, unknown>, _ctx: unknown) => {
+        try {
+          const content = String(event.content ?? event.message ?? event.text ?? "");
+          if (/\bI was wrong about\b|\bcorrection:\b/i.test(content)) {
+            logger.info("sulcus: message_sending — correction detected in outbound message");
+          }
+        } catch (err) {
+          logger.warn("sulcus: message_sending hook threw: " + err);
+        }
+        return undefined;
+      });
+
+      // message_sent — telemetry; optionally capture long messages as episodic memory
+      apiOn("message_sent", async (event: Record<string, unknown>, _ctx: unknown) => {
+        try {
+          const content = String(event.content ?? event.message ?? event.text ?? "");
+          logger.info(`sulcus: message_sent — length=${content.length}`);
+          if (autoCapture && sulcusMem && content.length > 500) {
+            const snippet = content.slice(0, 300);
+            await (sulcusMem as SulcusCloudClient).add_memory(
+              `[message_sent summary] ${snippet}`,
+              "episodic"
+            ).catch((e: unknown) => {
+              logger.warn(`sulcus: message_sent memory store failed: ${e instanceof Error ? e.message : String(e)}`);
+            });
+          }
+        } catch (err) {
+          logger.warn("sulcus: message_sent hook threw: " + err);
+        }
+        return undefined;
+      });
+
+      // before_tool_call — log memory/sulcus tool invocations
+      apiOn("before_tool_call", async (event: Record<string, unknown>, _ctx: unknown) => {
+        try {
+          const toolName = String(event.toolName ?? event.tool_name ?? event.name ?? "");
+          if (toolName && (toolName.toLowerCase().includes("memory") || toolName.toLowerCase().includes("sulcus"))) {
+            logger.info(`sulcus: before_tool_call — memory/sulcus tool invoked: ${toolName}`);
+          }
+        } catch (err) {
+          logger.warn("sulcus: before_tool_call hook threw: " + err);
+        }
+        return undefined;
+      });
+
+      // before_message_write — observation only, log message type
+      apiOn("before_message_write", async (event: Record<string, unknown>, _ctx: unknown) => {
+        try {
+          const role = String(event.role ?? event.type ?? "unknown");
+          logger.info(`sulcus: before_message_write — role=${role}`);
+        } catch (err) {
+          logger.warn("sulcus: before_message_write hook threw: " + err);
+        }
+        return undefined;
+      });
+
+      // subagent_spawning — log namespace inheritance if shared namespaces are configured
+      apiOn("subagent_spawning", async (event: Record<string, unknown>, _ctx: unknown) => {
+        try {
+          const agentId = String(event.agentId ?? event.agent_id ?? "(unknown)");
+          if (sharedNamespaces.length > 0) {
+            logger.info(`sulcus: subagent_spawning — agent=${agentId}, inheriting namespaces: [${sharedNamespaces.join(", ")}]`);
+          } else {
+            logger.info(`sulcus: subagent_spawning — agent=${agentId}`);
+          }
+        } catch (err) {
+          logger.warn("sulcus: subagent_spawning hook threw: " + err);
+        }
+        return undefined;
+      });
+
+      // subagent_spawned — log after subagent spawn
+      apiOn("subagent_spawned", async (event: Record<string, unknown>, _ctx: unknown) => {
+        try {
+          const agentId = String(event.agentId ?? event.agent_id ?? "(unknown)");
+          logger.info(`sulcus: subagent_spawned — agent=${agentId}`);
+        } catch (err) {
+          logger.warn("sulcus: subagent_spawned hook threw: " + err);
+        }
+        return undefined;
+      });
+
+      // subagent_ended — optionally capture what the subagent did as an episodic memory
+      apiOn("subagent_ended", async (event: Record<string, unknown>, _ctx: unknown) => {
+        try {
+          const agentId = String(event.agentId ?? event.agent_id ?? "(unknown)");
+          const result = String(event.result ?? event.output ?? event.summary ?? "");
+          logger.info(`sulcus: subagent_ended — agent=${agentId}`);
+          if (autoCapture && sulcusMem && result) {
+            const snippet = result.slice(0, 300);
+            await (sulcusMem as SulcusCloudClient).add_memory(
+              `[subagent_ended] agent=${agentId}: ${snippet}`,
+              "episodic"
+            ).catch((e: unknown) => {
+              logger.warn(`sulcus: subagent_ended memory store failed: ${e instanceof Error ? e.message : String(e)}`);
+            });
+          }
+        } catch (err) {
+          logger.warn("sulcus: subagent_ended hook threw: " + err);
+        }
+        return undefined;
+      });
+
+      // gateway_start — log plugin version and config summary
+      apiOn("gateway_start", async (_event: Record<string, unknown>, _ctx: unknown) => {
+        try {
+          logger.info(
+            `sulcus: gateway_start — openclaw-sulcus v5.0.0 | backend=${backendMode} | namespace=${namespace} | autoRecall=${autoRecall} | autoCapture=${autoCapture} | sharedNamespaces=[${sharedNamespaces.join(", ")}]`
+          );
+        } catch (err) {
+          logger.warn("sulcus: gateway_start hook threw: " + err);
+        }
+        return undefined;
+      });
+
+      // gateway_stop — log session stats
+      apiOn("gateway_stop", async (_event: Record<string, unknown>, _ctx: unknown) => {
+        try {
+          logger.info("sulcus: gateway_stop — session ending");
+          triggerProcessor?.logSessionSummary();
+        } catch (err) {
+          logger.warn("sulcus: gateway_stop hook threw: " + err);
+        }
+        return undefined;
+      });
+
+      logger.info("sulcus: registered Phase 3 lifecycle hooks (after_compaction, message_sending, message_sent, before_tool_call, before_message_write, subagent_spawning, subagent_spawned, subagent_ended, gateway_start, gateway_stop)");
+    }
+
     // ─────────────────────────────────────────────────────────────────────────
     // LEGACY HOOK REGISTRATION (config-driven, backward compat)
     // ─────────────────────────────────────────────────────────────────────────
@@ -1479,8 +2420,10 @@ const sulcusPlugin = {
     for (const [hookName, hookConfig] of Object.entries(hooksConfig.hooks)) {
       if (!hookConfig.enabled) continue;
 
-      // Skip before_agent_start if we already registered the SDK path
-      if (hookName === "before_agent_start" && autoRecall && isCloudBackend) continue;
+      // Skip before_agent_start — replaced by before_prompt_build SDK path
+      if (hookName === "before_agent_start") continue;
+      // Skip before_prompt_build if we already registered the SDK path
+      if (hookName === "before_prompt_build" && autoRecall && isCloudBackend) continue;
       // Skip agent_end if autoCapture SDK path already registered
       if (hookName === "agent_end" && autoCapture && hookConfig.action === "sivu_auto_capture") continue;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@digitalforgestudios/openclaw-sulcus",
-  "version": "4.2.0",
+  "version": "5.2.0",
   "description": "Sulcus — thermodynamic memory + Apache AGE knowledge graph for OpenClaw agents. v4: registerMemoryRuntime, prependContext recall, registerMemoryPromptSection, registerService lifecycle, uiHints, provider-filtered auto-capture. SIU v2 pipeline auto-classifies and scores memories. Interaction-based decay (3 modes). Curator sleep-cycle. Relevance-weighted recall. Cross-agent sync.",
   "keywords": [
     "openclaw",