refactor(openclaw): make skipRetainSessionPatterns configurable

Replace hardcoded includes() checks with configurable glob patterns via
new skipRetainSessionPatterns config field. Bare tokens like 'heartbeat'
auto-wrap as '**:heartbeat**'. Adds PluginConfig type, 4 unit tests,
and documentation in openclaw integration docs.

Per PR #1410 reviewer feedback.

Author: vernmic

hindsight-docs/docs-integrations/openclaw.md

@@ -141,6 +141,7 @@ Optional settings in `~/.openclaw/openclaw.json`:
 - `recallRoles` - Which message roles to include when composing the contextual recall query (default: `["user", "assistant"]`).
 - `retainEveryNTurns` - Retain every Nth turn (default: `1` = every turn). Values > 1 enable chunked retention.
 - `retainOverlapTurns` - Extra prior turns included when chunked retention fires (default: `0`).
+- `skipRetainSessionPatterns` - Glob patterns to skip retain from machine-driven sessions. Bare tokens like `"heartbeat"` are auto-wrapped as `**:heartbeat**`. Defaults: `["heartbeat", "cron", "subagent", "autonomic"]`.
 - `debug` - Enable debug logging (default: `false`).
 
 ### Memory Isolation

hindsight-integrations/openclaw/src/index.ts

@@ -1407,6 +1407,14 @@ function getPluginConfig(api: MoltbotPluginAPI): PluginConfig {
     statelessSessionPatterns: Array.isArray(config.statelessSessionPatterns)
       ? config.statelessSessionPatterns
       : [],
+    skipRetainSessionPatterns: (() => {
+      const raw = Array.isArray(config.skipRetainSessionPatterns)
+        ? config.skipRetainSessionPatterns
+        : ["heartbeat", "cron", "subagent", "autonomic"];
+      // Convert bare tokens to glob patterns: "heartbeat" -> "**:heartbeat**"
+      // Pass through patterns that already contain glob wildcards
+      return raw.map((p: string) => (p.includes("*") ? p : `**:${p}**`));
+    })(),
     skipStatelessSessions: config.skipStatelessSessions !== false,
     debug: config.debug ?? false,
   };
@@ -2218,6 +2226,23 @@ ${memoriesFormatted}
           return;
         }
 
+        // Defense-in-depth: skip retain for operational session patterns
+        // These sessions are machine-driven and produce low-value or duplicative retains
+        // Patterns are configurable via skipRetainSessionPatterns; defaults match common operational keys
+        const skipRetainPatterns = compileSessionPatterns(
+          pluginConfig.skipRetainSessionPatterns ?? []
+        );
+        if (
+          agentEndSessionKey &&
+          skipRetainPatterns.length > 0 &&
+          matchesSessionPattern(agentEndSessionKey, skipRetainPatterns)
+        ) {
+          debug(
+            `[Hindsight] Skipping retain - operational session pattern matched: ${agentEndSessionKey}`
+          );
+          return;
+        }
+
         if (
           !Array.isArray(event.context?.sessionEntry?.messages ?? event.messages) ||
           (event.context?.sessionEntry?.messages ?? event.messages ?? []).length === 0
@@ -2231,22 +2256,6 @@ ${memoriesFormatted}
           return;
         }
 
-        // Defense-in-depth: skip retain for operational session patterns
-        // These sessions are machine-driven and produce low-value or duplicative retains
-        if (
-          agentEndSessionKey && (
-            agentEndSessionKey.includes(":heartbeat") ||
-            agentEndSessionKey.includes(":cron:") ||
-            agentEndSessionKey.includes(":subagent") ||
-            agentEndSessionKey.includes(":autonomic:")
-          )
-        ) {
-          debug(
-            `[Hindsight] Skipping retain - operational session pattern matched: ${agentEndSessionKey}`
-          );
-          return;
-        }
-
         // Chunked retention: skip non-Nth turns and use a sliding window when firing
         const retainEveryN = pluginConfig.retainEveryNTurns ?? 1;
         const allMessages = event.context?.sessionEntry?.messages ?? event.messages ?? [];

hindsight-integrations/openclaw/src/session-patterns.test.ts

@@ -85,3 +85,44 @@ describe("matchesSessionPattern", () => {
     expect(matchesSessionPattern("agent:main:sess-abc", patterns)).toBe(false);
   });
 });
+
+// ---------------------------------------------------------------------------
+// skipRetainSessionPatterns bare-token wrapping
+// ---------------------------------------------------------------------------
+
+describe("skipRetainSessionPatterns bare-token wrapping", () => {
+  // Simulates the wrapping logic from getPluginConfig:
+  // bare tokens like "heartbeat" become "**:heartbeat**",
+  // patterns already containing "*" pass through unchanged.
+  function wrapTokens(raw: string[]): string[] {
+    return raw.map((p) => (p.includes("*") ? p : `**:${p}**`));
+  }
+
+  it("wraps bare tokens as **:token** glob patterns", () => {
+    const wrapped = wrapTokens(["heartbeat", "cron", "subagent", "autonomic"]);
+    expect(wrapped).toEqual(["**:heartbeat**", "**:cron**", "**:subagent**", "**:autonomic**"]);
+  });
+
+  it("passes through patterns that already contain wildcards", () => {
+    const wrapped = wrapTokens(["agent:*:cron:**", "**:heartbeat**"]);
+    expect(wrapped).toEqual(["agent:*:cron:**", "**:heartbeat**"]);
+  });
+
+  it("default patterns match operational session keys", () => {
+    const patterns = compileSessionPatterns(
+      wrapTokens(["heartbeat", "cron", "subagent", "autonomic"])
+    );
+    expect(matchesSessionPattern("agent:main:heartbeat:abc123", patterns)).toBe(true);
+    expect(matchesSessionPattern("agent:worker:cron:nightly:cleanup", patterns)).toBe(true);
+    expect(matchesSessionPattern("agent:main:subagent:worker:456", patterns)).toBe(true);
+    expect(matchesSessionPattern("agent:main:autonomic:def", patterns)).toBe(true);
+  });
+
+  it("default patterns do not match user sessions", () => {
+    const patterns = compileSessionPatterns(
+      wrapTokens(["heartbeat", "cron", "subagent", "autonomic"])
+    );
+    expect(matchesSessionPattern("agent:main:sess-abc123", patterns)).toBe(false);
+    expect(matchesSessionPattern("telegram:123456:agent:main", patterns)).toBe(false);
+  });
+});

hindsight-integrations/openclaw/src/types.ts

@@ -103,6 +103,7 @@ export interface PluginConfig {
   recallInjectionPosition?: "prepend" | "append" | "user"; // Where to inject recalled memories. 'prepend' = start of system prompt (default), 'append' = end of system prompt (preserves prompt cache), 'user' = before user message.
   ignoreSessionPatterns?: string[]; // Session key glob patterns to skip entirely (no recall, no retain). E.g. ["agent:main:**", "agent:*:cron:**"]
   statelessSessionPatterns?: string[]; // Session key glob patterns for read-only sessions (recall allowed, retain skipped). E.g. ["agent:*:subagent:**"]
+  skipRetainSessionPatterns?: string[]; // Glob patterns to skip retain from machine-driven sessions. Defaults: ["heartbeat", "cron", "subagent", "autonomic"].
   skipStatelessSessions?: boolean; // When true (default), stateless sessions also skip recall. When false, they recall but never retain.
   debug?: boolean; // Enable debug logging (default: false)
   logLevel?: "off" | "error" | "warning" | "info" | "debug"; // Console log verbosity (default: 'info').

skills/hindsight-docs/references/developer/configuration.md

@@ -174,7 +174,6 @@ To switch between backends:
 | `HINDSIGHT_API_LLM_GROQ_SERVICE_TIER` | Groq service tier: `on_demand`, `flex`, `auto` | `auto` |
 | `HINDSIGHT_API_LLM_OPENAI_SERVICE_TIER` | OpenAI service tier: `flex` for 50% cost savings (OpenAI Flex Processing) | None (default) |
 | `HINDSIGHT_API_LLM_EXTRA_BODY` | JSON dict merged into `extra_body` for all OpenAI-compatible API calls. Useful for custom model servers (e.g., vLLM `chat_template_kwargs`). | `null` |
-| `HINDSIGHT_API_LLM_DEFAULT_HEADERS` | JSON dict passed as `default_headers` to provider SDK clients. Used by operators routing through proxies / request-tracing middleware (e.g. Cloudflare AI Gateway, Helicone, corporate proxies). Currently wired into the Anthropic provider; other providers can opt in. | `null` |
 | `HINDSIGHT_API_LLM_GEMINI_SAFETY_SETTINGS` | JSON-encoded list of `{category, threshold}` dicts for Gemini/VertexAI content safety filtering | `null` |
 
 **Provider Examples**