clawmem 0.1.0

package/src/openclaw/engine.ts

@@ -0,0 +1,283 @@
+/**
+ * ClawMem ContextEngine — OpenClaw integration
+ *
+ * Implements the ContextEngine interface for OpenClaw's plugin system.
+ * Phase 1: thin shim that shells out to `clawmem hook <name>` for lifecycle operations.
+ *
+ * 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)
+ * - 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";
+
+// =============================================================================
+// Types (matching OpenClaw's ContextEngine interface without importing it)
+// =============================================================================
+
+type ContextEngineInfo = {
+  id: string;
+  name: string;
+  version?: string;
+  ownsCompaction?: boolean;
+};
+
+type AssembleResult = {
+  messages: unknown[];
+  estimatedTokens: number;
+  systemPromptAddition?: string;
+};
+
+type CompactResult = {
+  ok: boolean;
+  compacted: boolean;
+  reason?: string;
+  result?: {
+    summary?: string;
+    firstKeptEntryId?: string;
+    tokensBefore: number;
+    tokensAfter?: number;
+    details?: unknown;
+  };
+};
+
+type IngestResult = { ingested: boolean };
+type IngestBatchResult = { ingestedCount: number };
+type BootstrapResult = {
+  bootstrapped: boolean;
+  importedMessages?: number;
+  reason?: string;
+};
+
+type SubagentSpawnPreparation = { rollback: () => void | Promise<void> };
+type SubagentEndReason = "deleted" | "completed" | "swept" | "released";
+
+// =============================================================================
+// Logger interface
+// =============================================================================
+
+type Logger = {
+  debug?: (msg: string) => void;
+  info: (msg: string) => void;
+  warn: (msg: string) => void;
+  error: (msg: string) => void;
+};
+
+// =============================================================================
+// ClawMem ContextEngine
+// =============================================================================
+
+export class ClawMemContextEngine {
+  readonly info: ContextEngineInfo = {
+    id: "clawmem",
+    name: "ClawMem Memory System",
+    version: "0.2.0",
+    ownsCompaction: false, // Delegate compaction to legacy engine
+  };
+
+  private bootstrappedSessions = new Set<string>();
+
+  constructor(
+    private readonly cfg: ClawMemConfig,
+    private readonly logger: Logger,
+  ) {}
+
+  // ---------------------------------------------------------------------------
+  // bootstrap — register session, no context injection (P1 finding: bootstrap
+  // return type has no prompt injection field)
+  // ---------------------------------------------------------------------------
+
+  async bootstrap(params: {
+    sessionId: string;
+    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.
+    const result = await execHook(this.cfg, "session-bootstrap", {
+      session_id: params.sessionId,
+      transcript_path: params.sessionFile,
+    });
+
+    if (result.exitCode !== 0) {
+      this.logger.warn(`clawmem: bootstrap hook failed: ${result.stderr}`);
+    }
+
+    return { bootstrapped: true };
+  }
+
+  // ---------------------------------------------------------------------------
+  // ingest — no-op (ClawMem captures at turn boundaries via afterTurn)
+  // ---------------------------------------------------------------------------
+
+  async ingest(_params: {
+    sessionId: string;
+    sessionKey?: string;
+    message: unknown;
+    isHeartbeat?: boolean;
+  }): Promise<IngestResult> {
+    return { ingested: false };
+  }
+
+  // ---------------------------------------------------------------------------
+  // ingestBatch — no-op
+  // ---------------------------------------------------------------------------
+
+  async ingestBatch?(_params: {
+    sessionId: string;
+    sessionKey?: string;
+    messages: unknown[];
+    isHeartbeat?: boolean;
+  }): Promise<IngestBatchResult> {
+    return { ingestedCount: 0 };
+  }
+
+  // ---------------------------------------------------------------------------
+  // assemble — minimal pass-through (P1 finding: assemble() lacks the user
+  // prompt, so retrieval must happen in before_prompt_build hook instead)
+  // ---------------------------------------------------------------------------
+
+  async assemble(params: {
+    sessionId: string;
+    sessionKey?: string;
+    messages: unknown[];
+    tokenBudget?: number;
+  }): Promise<AssembleResult> {
+    // Pass-through: retrieval already injected via before_prompt_build hook
+    return {
+      messages: params.messages,
+      estimatedTokens: 0, // Caller handles estimation
+    };
+  }
+
+  // ---------------------------------------------------------------------------
+  // afterTurn — run extraction hooks (decision-extractor, handoff-generator,
+  // feedback-loop) in parallel. These process the completed turn and persist
+  // decisions, handoff notes, and confidence boosts.
+  // ---------------------------------------------------------------------------
+
+  async afterTurn(params: {
+    sessionId: string;
+    sessionKey?: string;
+    sessionFile: string;
+    messages: unknown[];
+    prePromptMessageCount: number;
+    autoCompactionSummary?: string;
+    isHeartbeat?: boolean;
+    tokenBudget?: number;
+  }): Promise<void> {
+    // Skip extraction for heartbeat turns
+    if (params.isHeartbeat) return;
+
+    // Skip if too few messages (no meaningful content to extract)
+    const newMessages = params.messages.length - params.prePromptMessageCount;
+    if (newMessages < 2) return;
+
+    const hookInput = {
+      session_id: params.sessionId,
+      transcript_path: params.sessionFile,
+    };
+
+    // Fire all three Stop hooks in parallel (independent operations)
+    const [decisionResult, handoffResult, feedbackResult] = await Promise.allSettled([
+      execHook(this.cfg, "decision-extractor", hookInput),
+      execHook(this.cfg, "handoff-generator", hookInput),
+      execHook(this.cfg, "feedback-loop", hookInput),
+    ]);
+
+    // Log failures but don't throw (fail-open)
+    for (const [name, result] of [
+      ["decision-extractor", decisionResult],
+      ["handoff-generator", handoffResult],
+      ["feedback-loop", feedbackResult],
+    ] as const) {
+      if (result.status === "rejected") {
+        this.logger.warn(`clawmem: afterTurn ${name} failed: ${result.reason}`);
+      } else if (result.value.exitCode !== 0) {
+        this.logger.warn(`clawmem: afterTurn ${name} error: ${result.value.stderr}`);
+      }
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // 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.
+  // ---------------------------------------------------------------------------
+
+  async compact(params: {
+    sessionId: string;
+    sessionKey?: string;
+    sessionFile: string;
+    tokenBudget?: number;
+    force?: boolean;
+    currentTokenCount?: number;
+    compactionTarget?: "budget" | "threshold";
+    customInstructions?: string;
+  }): Promise<CompactResult> {
+    // Run precompact-extract to preserve state before compaction
+    const extractResult = await execHook(this.cfg, "precompact-extract", {
+      session_id: params.sessionId,
+      transcript_path: params.sessionFile,
+    });
+
+    if (extractResult.exitCode !== 0) {
+      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",
+    };
+  }
+
+  // ---------------------------------------------------------------------------
+  // prepareSubagentSpawn — placeholder for future per-subagent memory scoping
+  // ---------------------------------------------------------------------------
+
+  async prepareSubagentSpawn?(_params: {
+    parentSessionKey: string;
+    childSessionKey: string;
+    ttlMs?: number;
+  }): Promise<SubagentSpawnPreparation | undefined> {
+    return undefined;
+  }
+
+  // ---------------------------------------------------------------------------
+  // onSubagentEnded — placeholder
+  // ---------------------------------------------------------------------------
+
+  async onSubagentEnded?(_params: {
+    childSessionKey: string;
+    reason: SubagentEndReason;
+  }): Promise<void> {
+    // No-op for now
+  }
+
+  // ---------------------------------------------------------------------------
+  // dispose — cleanup
+  // ---------------------------------------------------------------------------
+
+  async dispose(): Promise<void> {
+    this.bootstrappedSessions.clear();
+  }
+
+  // ---------------------------------------------------------------------------
+  // Helper: check if session has been bootstrapped (used by prompt hook)
+  // ---------------------------------------------------------------------------
+
+  isBootstrapped(sessionId: string): boolean {
+    return this.bootstrappedSessions.has(sessionId);
+  }
+}

package/src/openclaw/index.ts

@@ -0,0 +1,221 @@
+/**
+ * ClawMem OpenClaw Plugin — Entry Point
+ *
+ * Registers ClawMem as an OpenClaw ContextEngine plugin with:
+ * 1. ContextEngine (engine.ts) — lifecycle: afterTurn, compact, bootstrap
+ * 2. Plugin hooks — before_prompt_build (retrieval), session_start/end, before_reset
+ * 3. Agent tools — clawmem_search, clawmem_get, clawmem_session_log, clawmem_timeline, clawmem_similar
+ * 4. Service — starts clawmem serve (REST API) for tool HTTP calls
+ *
+ * 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
+ * - assemble() is minimal pass-through (retrieval already injected via hook)
+ */
+
+import { ClawMemContextEngine } from "./engine.js";
+import { resolveClawMemBin, execHook, parseHookOutput, extractContext } from "./shell.js";
+import type { ClawMemConfig } from "./shell.js";
+import { createTools } from "./tools.js";
+
+// =============================================================================
+// Plugin Definition
+// =============================================================================
+
+const PROFILE_BUDGETS: Record<string, number> = {
+  speed: 400,
+  balanced: 800,
+  deep: 1200,
+};
+
+const clawmemPlugin = {
+  id: "clawmem",
+  name: "ClawMem",
+  description: "On-device hybrid memory system with composite scoring, graph traversal, and lifecycle management",
+  version: "0.2.0",
+  kind: "context-engine" as const,
+
+  register(api: any) {
+    // ----- Resolve config -----
+    const pluginCfg = (api.pluginConfig || {}) as Record<string, unknown>;
+    const profile = (pluginCfg.profile as string) || "balanced";
+    const tokenBudget = (pluginCfg.tokenBudget as number) || PROFILE_BUDGETS[profile] || 800;
+
+    const cfg: ClawMemConfig = {
+      clawmemBin: resolveClawMemBin(pluginCfg.clawmemBin as string | undefined),
+      tokenBudget,
+      profile,
+      enableTools: pluginCfg.enableTools !== false,
+      servePort: (pluginCfg.servePort as number) || 7438,
+      env: {
+        ...(pluginCfg.gpuEmbed ? { CLAWMEM_EMBED_URL: pluginCfg.gpuEmbed as string } : {}),
+        ...(pluginCfg.gpuLlm ? { CLAWMEM_LLM_URL: pluginCfg.gpuLlm as string } : {}),
+        ...(pluginCfg.gpuRerank ? { CLAWMEM_RERANK_URL: pluginCfg.gpuRerank as string } : {}),
+        CLAWMEM_PROFILE: profile,
+      },
+    };
+
+    const logger = api.logger;
+    logger.info(`clawmem: plugin registered (bin: ${cfg.clawmemBin}, profile: ${profile}, budget: ${tokenBudget})`);
+
+    // ----- Register ContextEngine -----
+    const engine = new ClawMemContextEngine(cfg, logger);
+    api.registerContextEngine("clawmem", () => engine);
+
+    // ----- Track first-turn per session -----
+    const surfacedSessions = new Set<string>();
+
+    // ----- Plugin Hook: before_prompt_build -----
+    // This is WHERE retrieval happens (P1 finding: assemble() lacks the user prompt)
+    api.on("before_prompt_build", async (
+      event: { prompt: string; messages?: unknown[] },
+      ctx: { sessionId?: string; sessionKey?: string }
+    ) => {
+      if (!event.prompt || event.prompt.length < 5) return;
+
+      const sessionId = ctx.sessionId || "unknown";
+      const isFirstTurn = !surfacedSessions.has(sessionId);
+
+      let context = "";
+
+      // On first turn: run session-bootstrap for profile + handoff + decisions + stale
+      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}`);
+        }
+      }
+
+      // Every turn: run context-surfacing for prompt-aware retrieval
+      const surfacingResult = await execHook(cfg, "context-surfacing", {
+        session_id: sessionId,
+        prompt: event.prompt,
+      });
+
+      if (surfacingResult.exitCode === 0) {
+        const parsed = parseHookOutput(surfacingResult.stdout);
+        const surfacedContext = extractContext(parsed);
+        if (surfacedContext) {
+          context += surfacedContext;
+        }
+      } else {
+        logger.warn(`clawmem: context-surfacing failed: ${surfacingResult.stderr}`);
+      }
+
+      if (!context.trim()) return;
+
+      return { prependContext: context.trim() };
+    }, { priority: 10 }); // Run early to prepend context before other hooks
+
+    // ----- Plugin Hook: session_start -----
+    api.on("session_start", async (
+      event: { sessionId: string; sessionKey?: string },
+      _ctx: unknown
+    ) => {
+      logger.info?.(`clawmem: session started ${event.sessionId}`);
+    });
+
+    // ----- Plugin Hook: session_end -----
+    api.on("session_end", async (
+      event: { sessionId: string; sessionKey?: string; messageCount: number },
+      _ctx: unknown
+    ) => {
+      // Cleanup tracked state
+      surfacedSessions.delete(event.sessionId);
+      logger.info?.(`clawmem: session ended ${event.sessionId} (${event.messageCount} messages)`);
+    });
+
+    // ----- Plugin Hook: before_reset -----
+    // Safety net for /new and /reset — ensure extraction runs before session clears
+    api.on("before_reset", async (
+      event: { sessionFile?: string; messages?: unknown[]; reason?: string },
+      ctx: { sessionId?: string; sessionKey?: string }
+    ) => {
+      if (!event.sessionFile || !ctx.sessionId) return;
+
+      // Run extraction hooks before reset clears the session
+      const hookInput = {
+        session_id: ctx.sessionId,
+        transcript_path: event.sessionFile,
+      };
+
+      await Promise.allSettled([
+        execHook(cfg, "decision-extractor", hookInput),
+        execHook(cfg, "handoff-generator", hookInput),
+        execHook(cfg, "feedback-loop", hookInput),
+      ]);
+
+      surfacedSessions.delete(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,
+      });
+    });
+
+    // ----- Register Tools -----
+    if (cfg.enableTools) {
+      const tools = createTools(cfg, logger);
+      for (const tool of tools) {
+        api.registerTool(
+          {
+            name: tool.name,
+            label: tool.label,
+            description: tool.description,
+            parameters: tool.parameters,
+            async execute(toolCallId: string, params: Record<string, unknown>) {
+              return tool.execute(toolCallId, params);
+            },
+          },
+          { name: tool.name }
+        );
+      }
+      logger.info(`clawmem: registered ${tools.length} agent tools`);
+    }
+
+    // ----- Register Service (REST API) -----
+    let serveChild: import("node:child_process").ChildProcess | null = null;
+
+    api.registerService({
+      id: "clawmem-api",
+      async start(svcCtx: { logger: typeof logger }) {
+        const { spawnBackground } = await import("./shell.js");
+        serveChild = spawnBackground(cfg, ["serve", "--port", String(cfg.servePort)], svcCtx.logger);
+        svcCtx.logger.info(`clawmem: REST API spawned (pid=${serveChild.pid})`);
+      },
+      stop() {
+        if (serveChild && !serveChild.killed) {
+          serveChild.kill("SIGTERM");
+          logger.info("clawmem: REST API service stopped");
+        }
+        serveChild = null;
+      },
+    });
+  },
+};
+
+export default clawmemPlugin;

package/src/openclaw/plugin.json

@@ -0,0 +1,83 @@
+{
+  "id": "clawmem",
+  "kind": "context-engine",
+  "uiHints": {
+    "clawmemBin": {
+      "label": "ClawMem Binary Path",
+      "placeholder": "/usr/local/bin/clawmem",
+      "help": "Path to clawmem binary. Auto-detected from PATH if not set."
+    },
+    "tokenBudget": {
+      "label": "Context Token Budget",
+      "placeholder": "800",
+      "help": "Max tokens for context surfacing injection (default: 800)"
+    },
+    "profile": {
+      "label": "Retrieval Profile",
+      "help": "speed (400 tokens) | balanced (800) | deep (1200)"
+    },
+    "enableTools": {
+      "label": "Register Agent Tools",
+      "help": "Register ClawMem retrieval tools for agent-initiated queries"
+    },
+    "servePort": {
+      "label": "REST API Port",
+      "placeholder": "7438",
+      "help": "Port for ClawMem HTTP REST API (used by tools)",
+      "advanced": true
+    },
+    "gpuEmbed": {
+      "label": "Embedding Endpoint",
+      "placeholder": "http://localhost:8088",
+      "help": "URL for granite-embed embedding service",
+      "advanced": true
+    },
+    "gpuLlm": {
+      "label": "LLM Endpoint",
+      "placeholder": "http://localhost:8089",
+      "help": "URL for ClawMem LLM (query expansion, extraction)",
+      "advanced": true
+    },
+    "gpuRerank": {
+      "label": "Reranker Endpoint",
+      "placeholder": "http://localhost:8090",
+      "help": "URL for reranking service",
+      "advanced": true
+    }
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "clawmemBin": {
+        "type": "string"
+      },
+      "tokenBudget": {
+        "type": "number",
+        "minimum": 100,
+        "maximum": 4000
+      },
+      "profile": {
+        "type": "string",
+        "enum": ["speed", "balanced", "deep"]
+      },
+      "enableTools": {
+        "type": "boolean"
+      },
+      "servePort": {
+        "type": "number",
+        "minimum": 1024,
+        "maximum": 65535
+      },
+      "gpuEmbed": {
+        "type": "string"
+      },
+      "gpuLlm": {
+        "type": "string"
+      },
+      "gpuRerank": {
+        "type": "string"
+      }
+    }
+  }
+}