clawmem 0.2.8 → 0.3.0

package/AGENTS.md

@@ -682,4 +682,5 @@ clawmem consolidate [--dry-run] # Find and archive duplicate low-confidence docu
 - Consolidation worker (`CLAWMEM_ENABLE_CONSOLIDATION=true`) backfills unenriched docs with A-MEM notes + links. Only runs if the MCP process stays alive long enough to tick (every 5min).
 - Beads integration: `syncBeadsIssues()` queries `bd` CLI (Dolt backend, v0.58.0+) for live issue data, creates markdown docs in `beads` collection, maps all dependency edge types into `memory_relations`, and triggers A-MEM enrichment for new docs. Watcher auto-triggers on `.beads/` directory changes; `beads_sync` MCP tool for manual sync. Requires `bd` binary on PATH or at `~/go/bin/bd`.
 - HTTP REST API: `clawmem serve [--port 7438]` — optional REST server on localhost. Search, retrieval, lifecycle, and graph traversal. `POST /retrieve` mirrors `memory_retrieve` with auto-routing (keyword/semantic/causal/timeline/hybrid). `POST /search` provides direct mode selection. Bearer token auth via `CLAWMEM_API_TOKEN` env var (disabled if unset).
-- OpenClaw ContextEngine plugin: `clawmem setup openclaw` — registers ClawMem as a native OpenClaw context engine. Uses `before_prompt_build` for retrieval (prompt-aware), `afterTurn()` for extraction, `compact()` for pre-compaction. Shares same vault as Claude Code hooks (dual-mode). SQLite busy_timeout=5000ms for concurrent access safety.
+- OpenClaw ContextEngine plugin: `clawmem setup openclaw` — registers ClawMem as a native OpenClaw context engine. Uses `before_prompt_build` for retrieval (prompt-aware), `afterTurn()` for extraction, `compact()` for pre-compaction + runtime delegation. Shares same vault as Claude Code hooks (dual-mode). SQLite busy_timeout=5000ms for concurrent access safety.
+- **OpenClaw v2026.3.28+ compaction fix (v0.3.0):** `compact()` now delegates to OpenClaw's runtime compactor via `delegateCompactionToRuntime()` from `openclaw/plugin-sdk/core`. Previous versions returned `compacted: false` expecting legacy fallback — that fallback no longer exists. Without this fix, sessions never compact. Bootstrap context is now cached in `bootstrap()` and consumed once in `before_prompt_build`, eliminating duplicate hook invocations.

package/CLAUDE.md

@@ -682,4 +682,5 @@ clawmem consolidate [--dry-run] # Find and archive duplicate low-confidence docu
 - Consolidation worker (`CLAWMEM_ENABLE_CONSOLIDATION=true`) backfills unenriched docs with A-MEM notes + links. Only runs if the MCP process stays alive long enough to tick (every 5min).
 - Beads integration: `syncBeadsIssues()` queries `bd` CLI (Dolt backend, v0.58.0+) for live issue data, creates markdown docs in `beads` collection, maps all dependency edge types into `memory_relations`, and triggers A-MEM enrichment for new docs. Watcher auto-triggers on `.beads/` directory changes; `beads_sync` MCP tool for manual sync. Requires `bd` binary on PATH or at `~/go/bin/bd`.
 - HTTP REST API: `clawmem serve [--port 7438]` — optional REST server on localhost. Search, retrieval, lifecycle, and graph traversal. `POST /retrieve` mirrors `memory_retrieve` with auto-routing (keyword/semantic/causal/timeline/hybrid). `POST /search` provides direct mode selection. Bearer token auth via `CLAWMEM_API_TOKEN` env var (disabled if unset).
-- OpenClaw ContextEngine plugin: `clawmem setup openclaw` — registers ClawMem as a native OpenClaw context engine. Uses `before_prompt_build` for retrieval (prompt-aware), `afterTurn()` for extraction, `compact()` for pre-compaction. Shares same vault as Claude Code hooks (dual-mode). SQLite busy_timeout=5000ms for concurrent access safety.
+- OpenClaw ContextEngine plugin: `clawmem setup openclaw` — registers ClawMem as a native OpenClaw context engine. Uses `before_prompt_build` for retrieval (prompt-aware), `afterTurn()` for extraction, `compact()` for pre-compaction + runtime delegation. Shares same vault as Claude Code hooks (dual-mode). SQLite busy_timeout=5000ms for concurrent access safety.
+- **OpenClaw v2026.3.28+ compaction fix (v0.3.0):** `compact()` now delegates to OpenClaw's runtime compactor via `delegateCompactionToRuntime()` from `openclaw/plugin-sdk/core`. Previous versions returned `compacted: false` expecting legacy fallback — that fallback no longer exists. Without this fix, sessions never compact. Bootstrap context is now cached in `bootstrap()` and consumed once in `before_prompt_build`, eliminating duplicate hook invocations.

package/SKILL.md

@@ -592,6 +592,10 @@ openclaw config set agents.defaults.memorySearch.extraPaths '["~/documents", "~/
 
 **Tradeoffs:** Redundant recall but 10-15% context window waste from duplicate facts.
 
+### Compaction (v0.3.0+, required for OpenClaw v2026.3.28+)
+
+`compact()` delegates to OpenClaw's runtime compactor via `delegateCompactionToRuntime()`. Previous versions returned `compacted: false` expecting legacy fallback — that fallback no longer exists. Without this fix, OpenClaw sessions never compact and context grows unbounded.
+
 ---
 
 ## Troubleshooting
@@ -701,7 +705,7 @@ clawmem consolidate [--dry-run] # Find and archive duplicate low-confidence docu
 - Consolidation worker (`CLAWMEM_ENABLE_CONSOLIDATION=true`) backfills unenriched docs. Only runs if MCP process stays alive long enough (every 5min).
 - Beads integration: `syncBeadsIssues()` queries `bd` CLI (Dolt backend, v0.58.0+), creates markdown docs, maps dependency edges into `memory_relations`. Watcher auto-triggers on `.beads/` changes; `beads_sync` MCP for manual sync.
 - HTTP REST API: `clawmem serve [--port 7438]` — optional REST server on localhost. Search, retrieval, lifecycle, and graph traversal. `POST /retrieve` mirrors `memory_retrieve` with auto-routing (keyword/semantic/causal/timeline/hybrid). `POST /search` provides direct mode selection. Bearer token auth via `CLAWMEM_API_TOKEN` env var (disabled if unset).
-- OpenClaw ContextEngine plugin: `clawmem setup openclaw` — registers as native OpenClaw context engine. Dual-mode: shares vault with Claude Code hooks. Uses `before_prompt_build` for retrieval, `afterTurn()` for extraction, `compact()` for pre-compaction.
+- OpenClaw ContextEngine plugin: `clawmem setup openclaw` — registers as native OpenClaw context engine. Dual-mode: shares vault with Claude Code hooks. Uses `before_prompt_build` for retrieval, `afterTurn()` for extraction, `compact()` for pre-compaction + runtime delegation (v0.3.0+, required for OpenClaw v2026.3.28+).
 
 ## Tool Selection (one-liner)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawmem",
-  "version": "0.2.8",
+  "version": "0.3.0",
   "description": "On-device context engine and memory for AI agents. Claude Code and OpenClaw. Hooks + MCP server + hybrid RAG search.",
   "type": "module",
   "bin": {

package/src/openclaw/engine.ts

@@ -7,13 +7,13 @@
  * Architecture (per GPT 5.4 High review):
  * - assemble(): minimal pass-through (real retrieval happens in before_prompt_build hook)
  * - afterTurn(): shells out to decision-extractor, handoff-generator, feedback-loop
- * - compact(): shells out to precompact-extract, then delegates to legacy compaction (ownsCompaction: false)
+ * - compact(): shells out to precompact-extract, then delegates to OpenClaw runtime compactor
  * - ingest(): no-op (ClawMem captures at turn boundaries, not per-message)
  * - bootstrap(): session registration only (context injection via before_prompt_build hook)
  */
 
 import type { ClawMemConfig } from "./shell.js";
-import { execHook, parseHookOutput } from "./shell.js";
+import { execHook, parseHookOutput, extractContext } from "./shell.js";
 
 // =============================================================================
 // Types (matching OpenClaw's ContextEngine interface without importing it)
@@ -76,10 +76,10 @@ export class ClawMemContextEngine {
     id: "clawmem",
     name: "ClawMem Memory System",
     version: "0.2.0",
-    ownsCompaction: false, // Delegate compaction to legacy engine
+    ownsCompaction: false, // Delegate compaction to OpenClaw runtime
   };
 
-  private bootstrappedSessions = new Set<string>();
+  private bootstrapContexts = new Map<string, string>();
 
   constructor(
     private readonly cfg: ClawMemConfig,
@@ -96,23 +96,37 @@ export class ClawMemContextEngine {
     sessionKey?: string;
     sessionFile: string;
   }): Promise<BootstrapResult> {
-    this.bootstrappedSessions.add(params.sessionId);
-
-    // Fire session-bootstrap hook for session registration + side effects
-    // (profile refresh, session_log entry). Context is NOT injected here —
-    // that happens in the before_prompt_build plugin hook.
+    // Fire session-bootstrap hook and cache returned context for first-turn
+    // injection via before_prompt_build. Running it here (once) avoids the
+    // duplicate invocation that previously existed in the prompt hook.
     const result = await execHook(this.cfg, "session-bootstrap", {
       session_id: params.sessionId,
       transcript_path: params.sessionFile,
     });
 
-    if (result.exitCode !== 0) {
+    if (result.exitCode === 0) {
+      const parsed = parseHookOutput(result.stdout);
+      const ctx = extractContext(parsed);
+      if (ctx) {
+        this.bootstrapContexts.set(params.sessionId, ctx);
+      }
+    } else {
       this.logger.warn(`clawmem: bootstrap hook failed: ${result.stderr}`);
     }
 
     return { bootstrapped: true };
   }
 
+  /**
+   * Consume cached bootstrap context for a session (one-shot).
+   * Returns the context string and removes it from cache.
+   */
+  takeBootstrapContext(sessionId: string): string | undefined {
+    const ctx = this.bootstrapContexts.get(sessionId);
+    if (ctx) this.bootstrapContexts.delete(sessionId);
+    return ctx;
+  }
+
   // ---------------------------------------------------------------------------
   // ingest — no-op (ClawMem captures at turn boundaries via afterTurn)
   // ---------------------------------------------------------------------------
@@ -207,10 +221,11 @@ export class ClawMemContextEngine {
   }
 
   // ---------------------------------------------------------------------------
-  // compact — run precompact-extract for state preservation, then return
-  // ownsCompaction: false so OpenClaw's legacy compaction still runs.
-  // P1 finding: compact() must still perform real compaction; precompact-extract
-  // is a side effect, not a compactor. We delegate real compaction to legacy.
+  // compact — run precompact-extract for state preservation, then delegate
+  // to OpenClaw's built-in runtime compactor. ownsCompaction=false means we
+  // don't own the algorithm — but v2026.3.30 requires engines to explicitly
+  // delegate via delegateCompactionToRuntime() instead of returning
+  // compacted:false and hoping for legacy fallback (which no longer exists).
   // ---------------------------------------------------------------------------
 
   async compact(params: {
@@ -222,6 +237,7 @@ export class ClawMemContextEngine {
     currentTokenCount?: number;
     compactionTarget?: "budget" | "threshold";
     customInstructions?: string;
+    runtimeContext?: Record<string, unknown>;
   }): Promise<CompactResult> {
     // Run precompact-extract to preserve state before compaction
     const extractResult = await execHook(this.cfg, "precompact-extract", {
@@ -233,13 +249,20 @@ export class ClawMemContextEngine {
       this.logger.warn(`clawmem: precompact-extract failed: ${extractResult.stderr}`);
     }
 
-    // Return not-compacted — let legacy engine handle actual compaction
-    // (ownsCompaction: false means OpenClaw will call legacy compact() after us)
-    return {
-      ok: true,
-      compacted: false,
-      reason: "clawmem-precompact-only",
-    };
+    // Delegate actual compaction to OpenClaw's built-in runtime compactor.
+    // Lazy import avoids requiring openclaw as a build dependency — the SDK
+    // path is resolved at runtime by OpenClaw's plugin loader alias system.
+    try {
+      const { delegateCompactionToRuntime } = await import("openclaw/plugin-sdk/core");
+      return await delegateCompactionToRuntime(params as any);
+    } catch (err) {
+      this.logger.warn(`clawmem: delegateCompactionToRuntime failed: ${String(err)}`);
+      return {
+        ok: false,
+        compacted: false,
+        reason: `delegation-failed: ${String(err)}`,
+      };
+    }
   }
 
   // ---------------------------------------------------------------------------
@@ -269,15 +292,14 @@ export class ClawMemContextEngine {
   // dispose — cleanup
   // ---------------------------------------------------------------------------
 
-  async dispose(): Promise<void> {
-    this.bootstrappedSessions.clear();
+  /**
+   * Clean up per-session state. Called from session_end and before_reset hooks.
+   */
+  clearSession(sessionId: string): void {
+    this.bootstrapContexts.delete(sessionId);
   }
 
-  // ---------------------------------------------------------------------------
-  // Helper: check if session has been bootstrapped (used by prompt hook)
-  // ---------------------------------------------------------------------------
-
-  isBootstrapped(sessionId: string): boolean {
-    return this.bootstrappedSessions.has(sessionId);
+  async dispose(): Promise<void> {
+    this.bootstrapContexts.clear();
   }
 }

package/src/openclaw/index.ts

@@ -10,7 +10,7 @@
  * Architecture per GPT 5.4 High review:
  * - Prompt-aware retrieval goes through before_prompt_build (has the user prompt)
  * - Post-turn extraction goes through ContextEngine.afterTurn() (has messages[])
- * - Compaction goes through ContextEngine.compact() → precompact-extract → delegate to legacy
+ * - Compaction goes through ContextEngine.compact() → precompact-extract → delegate to runtime
  * - assemble() is minimal pass-through (retrieval already injected via hook)
  */
 
@@ -109,24 +109,14 @@ const clawmemPlugin = {
 
       let context = "";
 
-      // On first turn: run session-bootstrap for profile + handoff + decisions + stale
+      // On first turn: consume cached bootstrap context from engine.bootstrap()
+      // (avoids duplicate session-bootstrap hook invocation)
       if (isFirstTurn) {
         surfacedSessions.add(sessionId);
 
-        const bootstrapResult = await execHook(cfg, "session-bootstrap", {
-          session_id: sessionId,
-        });
-
-        if (bootstrapResult.exitCode === 0) {
-          const parsed = parseHookOutput(bootstrapResult.stdout);
-          // Session-bootstrap outputs context directly to stdout (not via hookSpecificOutput)
-          // It uses the system_message field for SessionStart hooks
-          const bootstrapContext = (parsed?.systemMessage as string) || "";
-          if (bootstrapContext) {
-            context += bootstrapContext + "\n\n";
-          }
-        } else {
-          logger.warn(`clawmem: session-bootstrap failed: ${bootstrapResult.stderr}`);
+        const bootstrapContext = engine.takeBootstrapContext(sessionId);
+        if (bootstrapContext) {
+          context += bootstrapContext + "\n\n";
         }
       }
 
@@ -168,6 +158,7 @@ const clawmemPlugin = {
     ) => {
       // Cleanup tracked state
       surfacedSessions.delete(event.sessionId);
+      engine.clearSession(event.sessionId);
       logger.info?.(`clawmem: session ended ${event.sessionId} (${event.messageCount} messages)`);
     });
 
@@ -192,22 +183,12 @@ const clawmemPlugin = {
       ]);
 
       surfacedSessions.delete(ctx.sessionId);
+      engine.clearSession(ctx.sessionId);
     });
 
-    // ----- Plugin Hook: before_compaction -----
-    // Fire precompact-extract before compaction starts (additional safety — compact()
-    // also runs it, but before_compaction fires earlier in the pipeline)
-    api.on("before_compaction", async (
-      event: { sessionFile?: string; messageCount: number },
-      ctx: { sessionId?: string }
-    ) => {
-      if (!event.sessionFile || !ctx.sessionId) return;
-
-      await execHook(cfg, "precompact-extract", {
-        session_id: ctx.sessionId,
-        transcript_path: event.sessionFile,
-      });
-    });
+    // NOTE: before_compaction hook removed — precompact-extract now fires only
+    // in engine.compact() before delegating to the runtime compactor. This avoids
+    // the duplicate invocation that previously existed.
 
     // ----- Register Tools -----
     if (cfg.enableTools) {