@digitalforgestudios/openclaw-sulcus 3.1.1 → 3.2.0

package/hooks.defaults.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "hooks-config",
+  "version": 1,
+  "hooks": {
+    "before_prompt_build": {
+      "action": "inject_awareness",
+      "enabled": true
+    },
+    "before_agent_start": {
+      "action": "auto_recall",
+      "enabled": false,
+      "limit": 5,
+      "minScore": 0.3
+    },
+    "agent_end": {
+      "action": "none",
+      "enabled": true
+    }
+  },
+  "tools": {
+    "memory_recall": { "enabled": true },
+    "memory_store": { "enabled": true },
+    "memory_status": { "enabled": true },
+    "consolidate": { "enabled": false },
+    "export_markdown": { "enabled": false },
+    "import_markdown": { "enabled": false },
+    "evaluate_triggers": { "enabled": false }
+  }
+}

package/index.ts

@@ -42,6 +42,92 @@ const FALLBACK_AWARENESS = `<sulcus_context token_budget="500">
   </cheatsheet>
 </sulcus_context>`;
 
+// ─── HOOKS CONFIG TYPES ──────────────────────────────────────────────────────
+
+interface HookConfig {
+  action: string;
+  enabled: boolean;
+  limit?: number;
+  minScore?: number;
+  [key: string]: any;
+}
+
+interface ToolConfig {
+  enabled: boolean;
+  [key: string]: any;
+}
+
+interface HooksConfig {
+  $schema?: string;
+  version?: number;
+  hooks: Record<string, HookConfig>;
+  tools: Record<string, ToolConfig>;
+}
+
+interface HookHandlerCtx {
+  sulcusMem: any;
+  backendMode: string;
+  namespace: string;
+  logger: any;
+  nativeError?: string | null;
+  storeLibPath?: string;
+  vectorsLibPath?: string;
+  wasmDir?: string;
+}
+
+type HookHandler = (event: any, config: HookConfig, ctx: HookHandlerCtx) => Promise<any>;
+
+// ─── HOOK HANDLERS ───────────────────────────────────────────────────────────
+
+const hookHandlers: Record<string, HookHandler> = {
+  /**
+   * inject_awareness — inject static Sulcus awareness into every prompt build.
+   * No network call — just a static string describing available tools.
+   */
+  inject_awareness: async (_event: any, _config: HookConfig, _ctx: HookHandlerCtx) => {
+    return { appendSystemContext: STATIC_AWARENESS };
+  },
+
+  /**
+   * auto_recall — search Sulcus memory for context relevant to the incoming prompt.
+   * Only runs when enabled. Falls back to FALLBACK_AWARENESS on error.
+   */
+  auto_recall: async (event: any, config: HookConfig, ctx: HookHandlerCtx) => {
+    const { sulcusMem, namespace, logger } = ctx;
+    if (!sulcusMem) return;
+    logger.info(`memory-sulcus: before_agent_start hook triggered for agent ${event.agentId}`);
+    if (!event.prompt) return;
+    try {
+      const limit = config.limit ?? 5;
+      logger.debug(`memory-sulcus: searching context for prompt: ${event.prompt.substring(0, 50)}...`);
+      const res = await sulcusMem.search_memory(event.prompt, limit);
+      const results = res?.results ?? [];
+      if (!results || results.length === 0) {
+        return { prependSystemContext: FALLBACK_AWARENESS };
+      }
+      // Format results as a concise XML context block
+      const items = results.map((r: any) =>
+        `    <memory id="${r.id}" heat="${(r.current_heat ?? r.score ?? 0).toFixed(2)}" type="${r.memory_type ?? "unknown"}">${r.label ?? r.pointer_summary ?? ""}</memory>`
+      ).join("\n");
+      const context = `<sulcus_context token_budget="500" namespace="${namespace}">\n${items}\n</sulcus_context>`;
+      logger.info(`memory-sulcus: injecting ${results.length} recalled memories (${context.length} chars)`);
+      return { prependSystemContext: context };
+    } catch (e) {
+      // build_context failed — inject fallback so the LLM isn't flying blind
+      logger.warn(`memory-sulcus: context build failed: ${e} — injecting fallback awareness`);
+      return { prependSystemContext: FALLBACK_AWARENESS };
+    }
+  },
+
+  /**
+   * none — no-op handler. Used for hooks that are enabled but should do nothing
+   * (e.g., agent_end where we want to log but not auto-record).
+   */
+  none: async (event: any, _config: HookConfig, ctx: HookHandlerCtx) => {
+    ctx.logger.debug(`memory-sulcus: hook fired (action=none) for agent ${event.agentId ?? "(unknown)"} (no-op)`);
+  },
+};
+
 // ─── NATIVE LIB LOADER ──────────────────────────────────────────────────────
 // Loads libsulcus_store.dylib (embedded PG) and libsulcus_vectors.dylib (embeddings)
 // via koffi FFI. Provides queryFn and embedFn callbacks for SulcusMem.create().
@@ -202,80 +288,88 @@ function isJunkMemory(text: string): boolean {
   return false;
 }
 
-// ─── PLUGIN ──────────────────────────────────────────────────────────────────
-
-const sulcusPlugin = {
-  id: "memory-sulcus",
-  name: "Sulcus vMMU",
-  description: "Sulcus-backed vMMU memory for OpenClaw — thermodynamic decay, reactive triggers, local-first",
-  kind: "memory" as const,
-
-  register(api: any) {
-    // ── Configuration ──
-    const libDir = api.config?.libDir
-      ? resolve(api.config.libDir)
-      : resolve(process.env.HOME || "~", ".sulcus/lib");
-
-    const storeLibPath = api.config?.storeLibPath
-      ? resolve(api.config.storeLibPath)
-      : resolve(libDir, process.platform === "darwin" ? "libsulcus_store.dylib" : "libsulcus_store.so");
-
-    const vectorsLibPath = api.config?.vectorsLibPath
-      ? resolve(api.config.vectorsLibPath)
-      : resolve(libDir, process.platform === "darwin" ? "libsulcus_vectors.dylib" : "libsulcus_vectors.so");
-
-    const wasmDir = api.config?.wasmDir
-      ? resolve(api.config.wasmDir)
-      : resolve(__dirname, "wasm");
-
-    // Default namespace = agent name (prevents everything landing in "default")
-    const agentId = api.config?.agentId || api.pluginConfig?.agentId;
-    const namespace = api.config?.namespace === "default" && agentId
-      ? agentId
-      : (api.config?.namespace || agentId || "default");
+// ─── HOOKS CONFIG LOADER ─────────────────────────────────────────────────────
+
+/**
+ * Load and merge hooks config.
+ * Precedence: user config (api.config.hooks/tools) > defaults from hooks.defaults.json
+ * Legacy `autoRecall` flag maps to hooks.before_agent_start.enabled for backward compat.
+ */
+function loadHooksConfig(apiConfig: any): HooksConfig {
+  // Load defaults
+  const defaultsPath = resolve(__dirname, "hooks.defaults.json");
+  let defaults: HooksConfig;
+  try {
+    defaults = JSON.parse(require("fs").readFileSync(defaultsPath, "utf-8")) as HooksConfig;
+  } catch (_e) {
+    // Fallback inline defaults if file is missing (safety net)
+    defaults = {
+      version: 1,
+      hooks: {
+        before_prompt_build: { action: "inject_awareness", enabled: true },
+        before_agent_start: { action: "auto_recall", enabled: false, limit: 5, minScore: 0.3 },
+        agent_end: { action: "none", enabled: true },
+      },
+      tools: {
+        memory_recall: { enabled: true },
+        memory_store: { enabled: true },
+        memory_status: { enabled: true },
+        consolidate: { enabled: false },
+        export_markdown: { enabled: false },
+        import_markdown: { enabled: false },
+        evaluate_triggers: { enabled: false },
+      },
+    };
+  }
 
-    // ── Load native dylibs ──
-    const nativeLoader = new NativeLibLoader(storeLibPath, vectorsLibPath);
-    nativeLoader.init(api.logger);
+  // Deep-merge user hook overrides (per-hook object merge, not replace)
+  const userHooks: Record<string, Partial<HookConfig>> = apiConfig?.hooks ?? {};
+  const userTools: Record<string, Partial<ToolConfig>> = apiConfig?.tools ?? {};
 
-    // ── Load WASM module ──
-    let sulcusMem: any = null;
-    let backendMode = "unavailable";
+  const mergedHooks: Record<string, HookConfig> = { ...defaults.hooks };
+  for (const [name, override] of Object.entries(userHooks)) {
+    mergedHooks[name] = { ...(mergedHooks[name] ?? { action: "none", enabled: false }), ...override };
+  }
 
-    if (nativeLoader.loaded) {
-      const wasmJsPath = resolve(wasmDir, "sulcus_wasm.js");
-      if (existsSync(wasmJsPath)) {
-        try {
-          const { SulcusMem, on_init } = require(wasmJsPath);
-          // on_init sets up WASM internals (panic hooks etc.)
-          if (typeof on_init === "function") on_init();
+  const mergedTools: Record<string, ToolConfig> = { ...defaults.tools };
+  for (const [name, override] of Object.entries(userTools)) {
+    mergedTools[name] = { ...(mergedTools[name] ?? { enabled: false }), ...override };
+  }
 
-          const queryFn = nativeLoader.makeQueryFn();
-          const embedFn = nativeLoader.makeEmbedFn();
-          sulcusMem = SulcusMem.create(queryFn, embedFn);
-          backendMode = "wasm";
-          api.logger.info(`memory-sulcus: SulcusMem created via WASM (wasm: ${wasmJsPath})`);
-        } catch (e: any) {
-          api.logger.warn(`memory-sulcus: WASM load failed: ${e.message}`);
-          backendMode = "unavailable";
-        }
-      } else {
-        api.logger.warn(`memory-sulcus: WASM module not found at ${wasmJsPath}`);
-      }
-    } else {
-      api.logger.warn(`memory-sulcus: native libs unavailable — ${nativeLoader.error}`);
-    }
+  // ── Legacy compat: autoRecall flag → hooks.before_agent_start.enabled ──
+  if (apiConfig?.autoRecall === true) {
+    mergedHooks["before_agent_start"] = {
+      ...(mergedHooks["before_agent_start"] ?? { action: "auto_recall", enabled: false }),
+      enabled: true,
+    };
+  }
 
-    const isAvailable = sulcusMem !== null;
+  return { version: defaults.version, hooks: mergedHooks, tools: mergedTools };
+}
 
-    // Update static awareness with runtime info
-    STATIC_AWARENESS = buildStaticAwareness(backendMode, namespace);
+// ─── TOOL DEFINITIONS ────────────────────────────────────────────────────────
 
-    api.logger.info(`memory-sulcus: registered (backend: ${backendMode}, namespace: ${namespace}, available: ${isAvailable})`);
+interface ToolDefinition {
+  schema: any;
+  options: { name: string };
+  makeExecute: (deps: ToolDeps) => (id: string, params: any) => Promise<any>;
+}
 
-    // ── Core memory tools ──
+interface ToolDeps {
+  sulcusMem: any;
+  backendMode: string;
+  namespace: string;
+  nativeLoader: NativeLibLoader;
+  storeLibPath: string;
+  vectorsLibPath: string;
+  wasmDir: string;
+  logger: any;
+  isAvailable: boolean;
+}
 
-    api.registerTool({
+const toolDefinitions: Record<string, ToolDefinition> = {
+  memory_recall: {
+    schema: {
       name: "memory_recall",
       label: "Memory Recall",
       description: "Search Sulcus memory for relevant context",
@@ -283,7 +377,10 @@ const sulcusPlugin = {
         query: Type.String({ description: "Search query string." }),
         limit: Type.Optional(Type.Number({ default: 5, description: "Maximum number of results to return (1-10)." }))
       }),
-      async execute(_id: string, params: any) {
+    },
+    options: { name: "memory_recall" },
+    makeExecute: ({ sulcusMem, backendMode, namespace, nativeLoader, isAvailable }) =>
+      async (_id: string, params: any) => {
         if (!isAvailable) {
           throw new Error(`Sulcus unavailable: ${nativeLoader.error || "WASM not loaded"}`);
         }
@@ -293,10 +390,11 @@ const sulcusPlugin = {
           content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
           details: { results, backend: backendMode, namespace }
         };
-      }
-    }, { name: "memory_recall" });
+      },
+  },
 
-    api.registerTool({
+  memory_store: {
+    schema: {
       name: "memory_store",
       label: "Memory Store",
       description: "Record information in Sulcus memory. Supports Markdown formatting. You control the memory type at creation time.",
@@ -310,20 +408,21 @@ const sulcusPlugin = {
           Type.Literal("fact")
         ], { description: "Memory type. preference=user preferences, procedural=how-to/processes, fact=stable knowledge, semantic=concepts/relationships, episodic=events/experiences. Default: episodic" })),
       }),
-      async execute(_id: string, params: any) {
+    },
+    options: { name: "memory_store" },
+    makeExecute: ({ sulcusMem, backendMode, namespace, nativeLoader, isAvailable, logger }) =>
+      async (_id: string, params: any) => {
         // Pre-send junk filter
         if (isJunkMemory(params.content)) {
-          api.logger.debug(`memory-sulcus: filtered junk memory: "${(params.content || "").substring(0, 50)}..."`);
+          logger.debug(`memory-sulcus: filtered junk memory: "${(params.content || "").substring(0, 50)}..."`);
           return {
             content: [{ type: "text", text: `Filtered: content looks like system noise, not a meaningful memory.` }],
             details: { filtered: true, reason: "junk_pattern" }
           };
         }
-
         if (!isAvailable) {
           throw new Error(`Sulcus unavailable: ${nativeLoader.error || "WASM not loaded"}`);
         }
-
         const res = await sulcusMem.add_memory(params.content, params.memory_type ?? null);
         const nodeId = res?.id ?? "unknown";
         const mtype = params.memory_type || "episodic";
@@ -331,15 +430,19 @@ const sulcusPlugin = {
           content: [{ type: "text", text: `Stored [${mtype}] memory (id: ${nodeId}) → backend: ${backendMode}, namespace: ${namespace}` }],
           details: { id: nodeId, memory_type: mtype, backend: backendMode, namespace, ...res }
         };
-      }
-    }, { name: "memory_store" });
+      },
+  },
 
-    api.registerTool({
+  memory_status: {
+    schema: {
       name: "memory_status",
       label: "Memory Status",
       description: "Check Sulcus memory backend status: connection, namespace, capabilities, and hot nodes.",
       parameters: Type.Object({}),
-      async execute(_id: string, _params: any) {
+    },
+    options: { name: "memory_status" },
+    makeExecute: ({ sulcusMem, backendMode, namespace, nativeLoader, storeLibPath, vectorsLibPath, wasmDir, isAvailable }) =>
+      async (_id: string, _params: any) => {
         if (!isAvailable) {
           return {
             content: [{ type: "text", text: JSON.stringify({
@@ -377,57 +480,229 @@ const sulcusPlugin = {
             }, null, 2) }],
           };
         }
-      }
-    }, { name: "memory_status" });
-
-    // ── Context injection: before every agent turn ──
-
-    // ── STATIC AWARENESS: fires on EVERY prompt build, unconditionally ──
-    // This guarantees the LLM always knows Sulcus exists and can use
-    // memory_store/memory_recall tools, even when autoRecall is off.
-    // No network call — just a static string describing available tools.
-    api.on("before_prompt_build", async (_event: any) => {
-      return { appendSystemContext: STATIC_AWARENESS };
-    });
-
-    // ── DYNAMIC CONTEXT: fires before each agent turn with live data ──
-    // GATED by autoRecall config (default: false). No API call unless opt-in.
-    const autoRecallEnabled = api.config?.autoRecall === true;
-    api.on("before_agent_start", async (event: any) => {
-      // Only call the Sulcus API if autoRecall is explicitly enabled
-      if (!autoRecallEnabled) {
-        api.logger.debug(`memory-sulcus: autoRecall is disabled, skipping context build`);
-        return;
-      }
-      if (!isAvailable) return;
-      api.logger.info(`memory-sulcus: before_agent_start hook triggered for agent ${event.agentId}`);
-      if (!event.prompt) return;
-      try {
-        api.logger.debug(`memory-sulcus: searching context for prompt: ${event.prompt.substring(0, 50)}...`);
-        const res = await sulcusMem.search_memory(event.prompt, 5);
-        const results = res?.results ?? [];
-        if (!results || results.length === 0) {
-          return { prependSystemContext: FALLBACK_AWARENESS };
+      },
+  },
+
+  // ── New WASM-capability tools (disabled by default) ──
+
+  consolidate: {
+    schema: {
+      name: "consolidate",
+      label: "Memory Consolidate",
+      description: "Consolidate cold memories: merges, prunes, or archives nodes below the given heat threshold.",
+      parameters: Type.Object({
+        min_heat: Type.Optional(Type.Number({ default: 0.1, description: "Nodes with heat below this value are candidates for consolidation (0.0–1.0)." }))
+      }),
+    },
+    options: { name: "consolidate" },
+    makeExecute: ({ sulcusMem, backendMode, namespace, nativeLoader, isAvailable }) =>
+      async (_id: string, params: any) => {
+        if (!isAvailable) {
+          throw new Error(`Sulcus unavailable: ${nativeLoader.error || "WASM not loaded"}`);
         }
-        // Format results as a concise XML context block
-        const items = results.map((r: any) =>
-          `    <memory id="${r.id}" heat="${(r.current_heat ?? r.score ?? 0).toFixed(2)}" type="${r.memory_type ?? "unknown"}">${r.label ?? r.pointer_summary ?? ""}</memory>`
-        ).join("\n");
-        const context = `<sulcus_context token_budget="500" namespace="${namespace}">\n${items}\n</sulcus_context>`;
-        api.logger.info(`memory-sulcus: injecting ${results.length} recalled memories (${context.length} chars)`);
-        return { prependSystemContext: context };
-      } catch (e) {
-        // build_context failed — inject fallback so the LLM isn't flying blind
-        api.logger.warn(`memory-sulcus: context build failed: ${e} — injecting fallback awareness`);
-        return { prependSystemContext: FALLBACK_AWARENESS };
+        const res = await sulcusMem.consolidate(params.min_heat ?? 0.1);
+        return {
+          content: [{ type: "text", text: JSON.stringify({ result: res, backend: backendMode, namespace }, null, 2) }],
+          details: { result: res, backend: backendMode, namespace }
+        };
+      },
+  },
+
+  export_markdown: {
+    schema: {
+      name: "export_markdown",
+      label: "Export Memory (Markdown)",
+      description: "Export all memories in the current namespace as a Markdown document.",
+      parameters: Type.Object({}),
+    },
+    options: { name: "export_markdown" },
+    makeExecute: ({ sulcusMem, backendMode, namespace, nativeLoader, isAvailable }) =>
+      async (_id: string, _params: any) => {
+        if (!isAvailable) {
+          throw new Error(`Sulcus unavailable: ${nativeLoader.error || "WASM not loaded"}`);
+        }
+        const markdown: string = await sulcusMem.export_markdown();
+        return {
+          content: [{ type: "text", text: markdown }],
+          details: { backend: backendMode, namespace, length: markdown.length }
+        };
+      },
+  },
+
+  import_markdown: {
+    schema: {
+      name: "import_markdown",
+      label: "Import Memory (Markdown)",
+      description: "Import memories from a Markdown document into the current namespace.",
+      parameters: Type.Object({
+        text: Type.String({ description: "Markdown content to import into Sulcus memory." })
+      }),
+    },
+    options: { name: "import_markdown" },
+    makeExecute: ({ sulcusMem, backendMode, namespace, nativeLoader, isAvailable }) =>
+      async (_id: string, params: any) => {
+        if (!isAvailable) {
+          throw new Error(`Sulcus unavailable: ${nativeLoader.error || "WASM not loaded"}`);
+        }
+        const res = await sulcusMem.import_markdown(params.text);
+        return {
+          content: [{ type: "text", text: JSON.stringify({ result: res, backend: backendMode, namespace }, null, 2) }],
+          details: { result: res, backend: backendMode, namespace }
+        };
+      },
+  },
+
+  evaluate_triggers: {
+    schema: {
+      name: "evaluate_triggers",
+      label: "Evaluate Memory Triggers",
+      description: "Evaluate reactive memory triggers against an event and context.",
+      parameters: Type.Object({
+        event: Type.String({ description: "Event name to evaluate triggers against (e.g. 'agent_end', 'user_message')." }),
+        context_json: Type.Optional(Type.String({ description: "JSON string of additional context to pass to trigger evaluation." }))
+      }),
+    },
+    options: { name: "evaluate_triggers" },
+    makeExecute: ({ sulcusMem, backendMode, namespace, nativeLoader, isAvailable }) =>
+      async (_id: string, params: any) => {
+        if (!isAvailable) {
+          throw new Error(`Sulcus unavailable: ${nativeLoader.error || "WASM not loaded"}`);
+        }
+        const res = await sulcusMem.evaluate_triggers(params.event, params.context_json ?? "{}");
+        return {
+          content: [{ type: "text", text: JSON.stringify({ result: res, backend: backendMode, namespace }, null, 2) }],
+          details: { result: res, backend: backendMode, namespace }
+        };
+      },
+  },
+};
+
+// ─── PLUGIN ──────────────────────────────────────────────────────────────────
+
+const sulcusPlugin = {
+  id: "memory-sulcus",
+  name: "Sulcus vMMU",
+  description: "Sulcus-backed vMMU memory for OpenClaw — thermodynamic decay, reactive triggers, local-first",
+  kind: "memory" as const,
+
+  register(api: any) {
+    // ── Configuration ──
+    const libDir = api.config?.libDir
+      ? resolve(api.config.libDir)
+      : resolve(process.env.HOME || "~", ".sulcus/lib");
+
+    const storeLibPath = api.config?.storeLibPath
+      ? resolve(api.config.storeLibPath)
+      : resolve(libDir, process.platform === "darwin" ? "libsulcus_store.dylib" : "libsulcus_store.so");
+
+    const vectorsLibPath = api.config?.vectorsLibPath
+      ? resolve(api.config.vectorsLibPath)
+      : resolve(libDir, process.platform === "darwin" ? "libsulcus_vectors.dylib" : "libsulcus_vectors.so");
+
+    const wasmDir = api.config?.wasmDir
+      ? resolve(api.config.wasmDir)
+      : resolve(__dirname, "wasm");
+
+    // Default namespace = agent name (prevents everything landing in "default")
+    const agentId = api.config?.agentId || api.pluginConfig?.agentId;
+    const namespace = api.config?.namespace === "default" && agentId
+      ? agentId
+      : (api.config?.namespace || agentId || "default");
+
+    // ── Load hooks config (config-driven dispatch) ──
+    const hooksConfig = loadHooksConfig(api.config);
+
+    // ── Load native dylibs ──
+    const nativeLoader = new NativeLibLoader(storeLibPath, vectorsLibPath);
+    nativeLoader.init(api.logger);
+
+    // ── Load WASM module ──
+    let sulcusMem: any = null;
+    let backendMode = "unavailable";
+
+    if (nativeLoader.loaded) {
+      const wasmJsPath = resolve(wasmDir, "sulcus_wasm.js");
+      if (existsSync(wasmJsPath)) {
+        try {
+          const { SulcusMem, on_init } = require(wasmJsPath);
+          // on_init sets up WASM internals (panic hooks etc.)
+          if (typeof on_init === "function") on_init();
+
+          const queryFn = nativeLoader.makeQueryFn();
+          const embedFn = nativeLoader.makeEmbedFn();
+          sulcusMem = SulcusMem.create(queryFn, embedFn);
+          backendMode = "wasm";
+          api.logger.info(`memory-sulcus: SulcusMem created via WASM (wasm: ${wasmJsPath})`);
+        } catch (e: any) {
+          api.logger.warn(`memory-sulcus: WASM load failed: ${e.message}`);
+          backendMode = "unavailable";
+        }
+      } else {
+        api.logger.warn(`memory-sulcus: WASM module not found at ${wasmJsPath}`);
       }
-    });
+    } else {
+      api.logger.warn(`memory-sulcus: native libs unavailable — ${nativeLoader.error}`);
+    }
+
+    const isAvailable = sulcusMem !== null;
+
+    // Update static awareness with runtime info
+    STATIC_AWARENESS = buildStaticAwareness(backendMode, namespace);
+
+    api.logger.info(`memory-sulcus: registered (backend: ${backendMode}, namespace: ${namespace}, available: ${isAvailable})`);
 
-    // agent_end: Do NOT auto-record raw conversation turns.
-    // The LLM has memory_store as a tool — it decides what's worth remembering.
-    api.on("agent_end", async (event: any) => {
-      api.logger.debug(`memory-sulcus: agent_end hook triggered for agent ${event.agentId} (no auto-record)`);
-    });
+    // ── Shared deps for tool executors ──
+    const toolDeps: ToolDeps = {
+      sulcusMem,
+      backendMode,
+      namespace,
+      nativeLoader,
+      storeLibPath,
+      vectorsLibPath,
+      wasmDir,
+      logger: api.logger,
+      isAvailable,
+    };
+
+    // ── Shared context for hook handlers ──
+    const handlerCtx: HookHandlerCtx = {
+      sulcusMem,
+      backendMode,
+      namespace,
+      logger: api.logger,
+      nativeError: nativeLoader.error,
+      storeLibPath,
+      vectorsLibPath,
+      wasmDir,
+    };
+
+    // ── Config-driven hook registration ──
+    for (const [hookName, hookConfig] of Object.entries(hooksConfig.hooks)) {
+      if (!hookConfig.enabled) continue;
+      const handler = hookHandlers[hookConfig.action];
+      if (handler) {
+        api.on(hookName, (event: any) => handler(event, hookConfig, handlerCtx));
+      } else {
+        api.logger.warn(`memory-sulcus: unknown hook action "${hookConfig.action}" for hook "${hookName}"`);
+      }
+    }
+
+    // ── Config-driven tool registration ──
+    for (const [toolName, toolConfig] of Object.entries(hooksConfig.tools)) {
+      if (!toolConfig.enabled) continue;
+      const toolDef = toolDefinitions[toolName];
+      if (toolDef) {
+        const schema = {
+          ...toolDef.schema,
+          async execute(id: string, params: any) {
+            return toolDef.makeExecute(toolDeps)(id, params);
+          },
+        };
+        api.registerTool(schema, toolDef.options);
+      } else {
+        api.logger.warn(`memory-sulcus: unknown tool "${toolName}" in config — skipping`);
+      }
+    }
 
     // No service registration needed — no background process to manage
   }

package/openclaw.plugin.json

@@ -108,6 +108,14 @@
         "type": "number",
         "description": "Max memories to auto-capture per agent turn",
         "default": 3
+      },
+      "hooks": {
+        "type": "object",
+        "description": "Hook→action mapping overrides. Merged with defaults from hooks.defaults.json. User values win. Example: { \"before_agent_start\": { \"enabled\": true, \"limit\": 10 } }"
+      },
+      "tools": {
+        "type": "object",
+        "description": "Tool enable/disable flags. Merged with defaults from hooks.defaults.json. Example: { \"consolidate\": { \"enabled\": true }, \"export_markdown\": { \"enabled\": true } }"
       }
     }
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@digitalforgestudios/openclaw-sulcus",
-  "version": "3.1.1",
+  "version": "3.2.0",
   "description": "Sulcus — reactive, thermodynamic memory plugin for OpenClaw. Opt-in persistent memory with heat-based decay, semantic search, and cross-agent sync. Auto-recall and auto-capture disabled by default.",
   "keywords": [
     "openclaw",
@@ -41,6 +41,7 @@
     "index.ts",
     "wasm/",
     "openclaw.plugin.json",
+    "hooks.defaults.json",
     "README.md"
   ],
   "dependencies": {