@clawmem-ai/clawmem 0.1.15 → 0.1.16

package/README.md

@@ -136,7 +136,10 @@ Full config with all options:
             }
           },
           turnCommentDelayMs: 1000,
+          digestWaitTimeoutMs: 30000,
           summaryWaitTimeoutMs: 120000,
+          memoryExtractWaitTimeoutMs: 45000,
+          memoryReconcileWaitTimeoutMs: 45000,
           memoryRecallLimit: 5,
           memoryAutoRecallLimit: 3
         }
@@ -151,11 +154,12 @@ Full config with all options:
 ## Notes
 
 - Conversation comments exclude tool calls, tool results, system messages, and heartbeat noise.
-- Summary failures do not block finalization; the `summary` field is written as `failed: ...`.
+- Finalization now uses a staged pipeline: rolling digest updates during the session, then a final issue summary/title after finalize, plus a separate extract/reconcile memory pipeline.
+- Summary failures do not block finalization; the conversation issue remains finalized with `summary: pending`, and ClawMem retries the final summary through background recovery scheduling.
 - Memory search and auto-recall only return open `type:memory` issues. Closed memory issues are treated as stale.
 - ClawMem automatically injects a small set of relevant memories before each turn using the agent's default repo and the backend recall API. Auto-recall is best-effort and quietly skips injection when backend recall is unavailable.
 - `memory_recall` uses the backend `/api/v3/search/issues` endpoint scoped to the current repo plus `label:"type:memory"`. When backend recall is unavailable, use `memory_list` or `memory_get` to inspect memories explicitly.
-- Durable memories are extracted best-effort during later request-scoped maintenance, not by background subagent work after a request has already ended.
+- Durable memories are captured in two stages after each mirrored turn: extract atomic candidates from new conversation deltas, then reconcile them against existing memories before writing durable updates. If either stage fails, ClawMem retries it through background recovery scheduling rather than the request-start path.
 - The plugin exposes `memory_repos`, `memory_repo_create`, `memory_list`, `memory_get`, `memory_labels`, `memory_recall`, `memory_store`, `memory_update`, and `memory_forget` for mid-session use.
 - Route resolution is now: agent identity supplies credentials, `defaultRepo` is the fallback memory space, and explicit tool calls may override repo per operation.
 - `memory_store` accepts optional schema hints such as kind and topics; the plugin normalizes them into managed `kind:*` and `topic:*` labels.

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "clawmem",
   "name": "ClawMem",
-  "version": "0.1.15",
+  "version": "0.1.16",
   "description": "Mirror OpenClaw sessions into GitHub-compatible issues and comments.",
   "kind": "memory",
   "skills": [
@@ -67,11 +67,26 @@
         "minimum": 0,
         "maximum": 60000
       },
+      "digestWaitTimeoutMs": {
+        "type": "integer",
+        "minimum": 1000,
+        "maximum": 600000
+      },
       "summaryWaitTimeoutMs": {
         "type": "integer",
         "minimum": 1000,
         "maximum": 600000
       },
+      "memoryExtractWaitTimeoutMs": {
+        "type": "integer",
+        "minimum": 1000,
+        "maximum": 600000
+      },
+      "memoryReconcileWaitTimeoutMs": {
+        "type": "integer",
+        "minimum": 1000,
+        "maximum": 600000
+      },
       "memoryRecallLimit": {
         "type": "integer",
         "minimum": 1,
@@ -117,9 +132,21 @@
       "label": "Turn Sync Delay (ms)",
       "help": "Small delay so transcript writes settle before a turn comment is mirrored."
     },
+    "digestWaitTimeoutMs": {
+      "label": "Digest Wait Timeout (ms)",
+      "help": "How long clawmem waits for the rolling conversation digest subagent before retrying later."
+    },
     "summaryWaitTimeoutMs": {
       "label": "Summary Wait Timeout (ms)",
-      "help": "How long clawmem waits for the OpenClaw subagent summarizer before writing a failed summary."
+      "help": "How long clawmem waits for the final conversation summary subagent during session finalization."
+    },
+    "memoryExtractWaitTimeoutMs": {
+      "label": "Memory Extract Timeout (ms)",
+      "help": "How long clawmem waits while extracting atomic memory candidates from new conversation deltas."
+    },
+    "memoryReconcileWaitTimeoutMs": {
+      "label": "Memory Reconcile Timeout (ms)",
+      "help": "How long clawmem waits while reconciling extracted memory candidates against existing memories."
     },
     "memoryRecallLimit": {
       "label": "Memory Recall Limit",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawmem-ai/clawmem",
-  "version": "0.1.15",
+  "version": "0.1.16",
   "description": "Mirror OpenClaw sessions into GitHub-compatible issues and comments.",
   "type": "module",
   "license": "MIT",
@@ -23,6 +23,9 @@
     "access": "public"
   },
   "openclaw": {
+    "hooks": [
+      "./index.ts"
+    ],
     "extensions": [
       "./index.ts"
     ]

package/skills/clawmem/SKILL.md

@@ -25,8 +25,9 @@ Memory hygiene matters: lock important insights deliberately, update canonical f
 The ClawMem plugin automatically handles:
 - Per-agent provisioning of credentials plus a default memory repo
 - Session mirroring into `type:conversation` issues
+- Rolling conversation digests during the session plus a final issue summary/title after finalize
 - Best-effort automatic memory recall before each turn, scoped to the current agent's `defaultRepo`
-- Best-effort durable memory extraction during later request-scoped maintenance
+- Best-effort durable memory extraction after mirrored turns, with background recovery retries if extract/reconcile work fails
 - Mid-session memory tools: `memory_repos`, `memory_repo_create`, `memory_list`, `memory_get`, `memory_labels`, `memory_recall`, `memory_store`, `memory_update`, and `memory_forget`
 
 ## Mandatory turn loop
@@ -48,6 +49,7 @@ On every user turn, run this loop:
    - Never treat a `memory_recall` miss by itself as proof that no relevant memory exists.
 2. After answering, ask: did this turn create durable knowledge?
    - Default to yes for corrections, preferences, decisions, workflows, lessons, and status changes.
+   - Auto-extraction is asynchronous and best-effort. If a fact must be durable immediately, or the next turn will depend on it, write it explicitly with `memory_store` or `memory_update` instead of waiting for background capture.
    - Prefer one durable fact per memory. If a turn contains several independent facts, save them separately instead of bundling them into one summary memory.
    - Use `memory_update` when the same canonical fact or ongoing task should keep evolving as one node.
    - When updating an existing memory, preserve that node's current language unless the user explicitly asks for a rewrite.
@@ -61,7 +63,7 @@ On every user turn, run this loop:
    - Include the memory id and title only when they help with debugging, traceability, or an explicit user request.
    - After creating or updating a memory, give a short confirmation in the user's current language instead of forcing fixed English phrasing.
 
-Bias toward saving, and use explicit retrieval whenever auto-recall is absent, weak, cross-repo, or too ambiguous to trust on its own.
+Bias toward saving, and use explicit retrieval whenever auto-recall is absent, weak, cross-repo, or too ambiguous to trust on its own. Do not assume a just-finished turn has already been captured as durable memory unless you explicitly wrote it or later verified it.
 
 ## Retrieval and storage rules
 

package/src/config.test.ts

@@ -29,7 +29,10 @@ function baseConfig(): ClawMemPluginConfig {
     memoryRecallLimit: 5,
     memoryAutoRecallLimit: 3,
     turnCommentDelayMs: 1000,
+    digestWaitTimeoutMs: 30000,
     summaryWaitTimeoutMs: 120000,
+    memoryExtractWaitTimeoutMs: 45000,
+    memoryReconcileWaitTimeoutMs: 45000,
   };
 }
 

package/src/config.ts

@@ -48,7 +48,10 @@ export function resolvePluginConfig(api: OpenClawPluginApi): ClawMemPluginConfig
     memoryRecallLimit: clamp(num(raw.memoryRecallLimit, 5), 1, 20),
     memoryAutoRecallLimit: clamp(num(raw.memoryAutoRecallLimit, 3), 1, 20),
     turnCommentDelayMs: num(raw.turnCommentDelayMs, 1000),
+    digestWaitTimeoutMs: clamp(num(raw.digestWaitTimeoutMs, 30000), 1000, 600000),
     summaryWaitTimeoutMs: clamp(num(raw.summaryWaitTimeoutMs, 120000), 1000, 600000),
+    memoryExtractWaitTimeoutMs: clamp(num(raw.memoryExtractWaitTimeoutMs, 45000), 1000, 600000),
+    memoryReconcileWaitTimeoutMs: clamp(num(raw.memoryReconcileWaitTimeoutMs, 45000), 1000, 600000),
   };
 }
 

package/src/conversation.ts

@@ -4,9 +4,10 @@ import path from "node:path";
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
 import { AGENT_LABEL_PREFIX, DEFAULT_LABELS, SESSION_TITLE_PREFIX, extractLabelNames } from "./config.js";
 import type { GitHubIssueClient } from "./github-client.js";
+import { parseCandidates } from "./memory.js";
 import { normalizeMessages, readTranscriptSnapshot } from "./transcript.js";
-import type { ClawMemPluginConfig, NormalizedMessage, SessionMirrorState, TranscriptSnapshot } from "./types.js";
-import { fmtTranscript, localDate, localDateTime, sha256, subKey } from "./utils.js";
+import type { ClawMemPluginConfig, MemoryCandidate, NormalizedMessage, SessionMirrorState, TranscriptSnapshot } from "./types.js";
+import { fmtTranscript, fmtTranscriptFrom, localDate, localDateTime, sha256, sliceTranscriptDelta, subKey } from "./utils.js";
 import { parseFlatYaml, stringifyFlatYaml } from "./yaml.js";
 
 export class ConversationMirror {
@@ -18,6 +19,10 @@ export class ConversationMirror {
     if (first.includes("generate a short 1-2 word filename slug") && first.includes("Reply with ONLY the slug")) return false;
     if (first.includes("Summarize the following conversation.") && first.includes('Return valid JSON only in the form {"summary":"..."}')) return false;
     if (first.includes("Extract durable memories from the conversation below.") && first.includes('Return JSON only in the form {"save":')) return false;
+    if (first.includes("Maintain a rolling digest of the conversation below.") && first.includes('Return valid JSON only in the form {"digest":"...","title":"..."}')) return false;
+    if (first.includes("Write the final issue summary for the conversation below.") && first.includes('Return valid JSON only in the form {"summary":"...","title":"..."}')) return false;
+    if (first.includes("Extract atomic durable memory candidates from the conversation delta below.")) return false;
+    if (first.includes("Reconcile extracted durable memory candidates against existing memories.")) return false;
     return true;
   }
 
@@ -90,6 +95,173 @@ export class ConversationMirror {
     return count;
   }
 
+  async generateRollingDigest(
+    session: SessionMirrorState,
+    snapshot: TranscriptSnapshot,
+    fromCursor: number,
+    previousDigest?: string,
+  ): Promise<{ digest: string; title?: string }> {
+    const { anchorStart, deltaStart, anchorMessages, deltaMessages } = sliceTranscriptDelta(snapshot.messages, fromCursor, 2);
+    if (deltaMessages.length === 0) {
+      return { digest: previousDigest?.trim() || "" };
+    }
+    const subagent = this.api.runtime.subagent;
+    const sessionKey = subKey(session, "digest");
+    const message = [
+      "Maintain a rolling digest of the conversation below.",
+      'Return valid JSON only in the form {"digest":"...","title":"..."}',
+      "Update the digest so it accurately represents the conversation so far in 4-8 concise factual sentences.",
+      "Focus on decisions, constraints, preferences, open workstreams, and concrete outcomes worth carrying forward.",
+      "Use the anchor messages only for context resolution. The new messages are the only part that must be incorporated now.",
+      "Title is optional. If provided, keep it under 50 characters and accurately describe the overall conversation.",
+      "",
+      "<previous-digest>",
+      previousDigest?.trim() || "None.",
+      "</previous-digest>",
+      "",
+      "<anchor-messages>",
+      anchorMessages.length > 0 ? fmtTranscriptFrom(anchorMessages, anchorStart) : "None.",
+      "</anchor-messages>",
+      "",
+      "<new-messages>",
+      fmtTranscriptFrom(deltaMessages, deltaStart),
+      "</new-messages>",
+    ].join("\n");
+    try {
+      const run = await subagent.run({
+        sessionKey,
+        message,
+        deliver: false,
+        lane: "clawmem-digest",
+        idempotencyKey: sha256(`${session.sessionId}:${fromCursor}:${snapshot.messages.length}:digest-v1`),
+        extraSystemPrompt: "You maintain rolling conversation digests for ClawMem. Output JSON only with string fields digest and optional title.",
+      });
+      const wait = await subagent.waitForRun({ runId: run.runId, timeoutMs: this.config.digestWaitTimeoutMs });
+      if (wait.status === "timeout") throw new Error("digest subagent timed out");
+      if (wait.status === "error") throw new Error(wait.error || "digest subagent failed");
+      const msgs = normalizeMessages((await subagent.getSessionMessages({ sessionKey, limit: 50 })).messages);
+      const text = [...msgs].reverse().find((e) => e.role === "assistant" && e.text.trim())?.text;
+      if (!text) throw new Error("digest subagent returned no assistant text");
+      return parseDigestAndTitle(text);
+    } finally {
+      subagent.deleteSession({ sessionKey, deleteTranscript: true }).catch(() => {});
+    }
+  }
+
+  async deriveDelta(
+    session: SessionMirrorState,
+    snapshot: TranscriptSnapshot,
+    fromCursor: number,
+    previousDigest?: string,
+  ): Promise<{ digest: string; title?: string; candidates: MemoryCandidate[] }> {
+    const { anchorStart, deltaStart, anchorMessages, deltaMessages } = sliceTranscriptDelta(snapshot.messages, fromCursor, 2);
+    if (deltaMessages.length === 0) {
+      return { digest: previousDigest?.trim() || "", candidates: [] };
+    }
+    const subagent = this.api.runtime.subagent;
+    const sessionKey = subKey(session, "derive-delta");
+    const message = [
+      "Maintain a rolling digest and extract atomic durable memory candidates from the conversation delta below.",
+      'Return valid JSON only in the form {"digest":"...","title":"...","candidates":[{"title":"...","detail":"...","kind":"...","topics":["..."],"evidence":"..."}]}.',
+      "Update the digest so it accurately represents the conversation so far in 4-8 concise factual sentences.",
+      "Focus the digest on decisions, constraints, preferences, open workstreams, and concrete outcomes worth carrying forward.",
+      "Extract only durable facts, preferences, decisions, constraints, workflows, and ongoing context worth remembering later.",
+      "Use the anchor messages only for context resolution. The new messages are the only source that may add new candidates now.",
+      "Each candidate must represent one durable fact. Split independent facts into separate candidates.",
+      "Do not extract temporary requests, tool chatter, startup boilerplate, or summaries about internal helper sessions.",
+      "Kind and topics are optional. Keep them short, reusable, and low-cardinality.",
+      "Evidence is optional. If present, keep it short and quote-free.",
+      "Title is optional. If provided, keep it under 50 characters and accurately describe the overall conversation.",
+      "Prefer an empty candidates array when nothing durable was added.",
+      "",
+      "<previous-digest>",
+      previousDigest?.trim() || "None.",
+      "</previous-digest>",
+      "",
+      "<anchor-messages>",
+      anchorMessages.length > 0 ? fmtTranscriptFrom(anchorMessages, anchorStart) : "None.",
+      "</anchor-messages>",
+      "",
+      "<new-messages>",
+      fmtTranscriptFrom(deltaMessages, deltaStart),
+      "</new-messages>",
+    ].join("\n");
+    try {
+      const run = await subagent.run({
+        sessionKey,
+        message,
+        deliver: false,
+        lane: "clawmem-derive-delta",
+        idempotencyKey: sha256(`${session.sessionId}:${fromCursor}:${snapshot.messages.length}:derive-delta-v1`),
+        extraSystemPrompt: "You maintain rolling conversation digests and extract atomic durable memory candidates for ClawMem. Output JSON only with digest, optional title, and candidates.",
+      });
+      const wait = await subagent.waitForRun({
+        runId: run.runId,
+        timeoutMs: Math.max(this.config.digestWaitTimeoutMs, this.config.memoryExtractWaitTimeoutMs),
+      });
+      if (wait.status === "timeout") throw new Error("derive delta subagent timed out");
+      if (wait.status === "error") throw new Error(wait.error || "derive delta subagent failed");
+      const msgs = normalizeMessages((await subagent.getSessionMessages({ sessionKey, limit: 50 })).messages);
+      const text = [...msgs].reverse().find((e) => e.role === "assistant" && e.text.trim())?.text;
+      if (!text) throw new Error("derive delta subagent returned no assistant text");
+      return parseDerivedDelta(text);
+    } finally {
+      subagent.deleteSession({ sessionKey, deleteTranscript: true }).catch(() => {});
+    }
+  }
+
+  async generateFinalSummaryFromDigest(
+    session: SessionMirrorState,
+    snapshot: TranscriptSnapshot,
+    digestText: string,
+  ): Promise<{ summary: string; title?: string }> {
+    if (!digestText.trim() && snapshot.messages.length === 0) throw new Error("no conversation content to summarize");
+    const tailStart = Math.max(0, snapshot.messages.length - 6);
+    const tailMessages = snapshot.messages.slice(tailStart);
+    const subagent = this.api.runtime.subagent;
+    const sessionKey = subKey(session, "summary-final");
+    const message = [
+      "Write the final issue summary for the conversation below.",
+      'Return valid JSON only in the form {"summary":"...","title":"..."}',
+      "The summary should be concise, factual, and written in 2-4 sentences.",
+      "Use the rolling digest as the primary source of truth, and use the recent tail only to preserve freshness and wording accuracy.",
+      "Do not include markdown, bullet points, or analysis.",
+      "",
+      "Title rules:",
+      "- Under 50 characters, accurately describe the main topic or task.",
+      "- Should let someone immediately know what the conversation is about.",
+      "- Must be in the same language as the majority of the conversation content.",
+      "- Good: precise, descriptive, specific. Bad: vague, overly creative, generic.",
+      "",
+      "<rolling-digest>",
+      digestText.trim() || "None.",
+      "</rolling-digest>",
+      "",
+      "<recent-tail>",
+      tailMessages.length > 0 ? fmtTranscriptFrom(tailMessages, tailStart) : "None.",
+      "</recent-tail>",
+    ].join("\n");
+    try {
+      const run = await subagent.run({
+        sessionKey,
+        message,
+        deliver: false,
+        lane: "clawmem-summary",
+        idempotencyKey: sha256(`${session.sessionId}:${snapshot.messages.length}:summary-final-v1`),
+        extraSystemPrompt: "You write final conversation issue summaries for ClawMem. Output JSON only with string fields summary and title.",
+      });
+      const wait = await subagent.waitForRun({ runId: run.runId, timeoutMs: this.config.summaryWaitTimeoutMs });
+      if (wait.status === "timeout") throw new Error("summary subagent timed out");
+      if (wait.status === "error") throw new Error(wait.error || "summary subagent failed");
+      const msgs = normalizeMessages((await subagent.getSessionMessages({ sessionKey, limit: 50 })).messages);
+      const text = [...msgs].reverse().find((e) => e.role === "assistant" && e.text.trim())?.text;
+      if (!text) throw new Error("summary subagent returned no assistant text");
+      return parseSummaryAndTitle(text);
+    } finally {
+      subagent.deleteSession({ sessionKey, deleteTranscript: true }).catch(() => {});
+    }
+  }
+
   async generateSummaryAndTitle(session: SessionMirrorState, snapshot: TranscriptSnapshot): Promise<{ summary: string; title?: string }> {
     if (snapshot.messages.length === 0) throw new Error("no conversation messages to summarize");
     const subagent = this.api.runtime.subagent;
@@ -367,6 +539,49 @@ function parseSummaryAndTitle(raw: string): { summary: string; title?: string }
   return { summary: t };
 }
 
+function parseDigestAndTitle(raw: string): { digest: string; title?: string } {
+  const tryParse = (s: string): { digest: string; title?: string } | null => {
+    try {
+      const p = JSON.parse(s) as { digest?: unknown; title?: unknown };
+      const digest = typeof p?.digest === "string" && p.digest.trim() ? p.digest.trim() : null;
+      if (!digest) return null;
+      const title = typeof p?.title === "string" && p.title.trim() ? p.title.trim() : undefined;
+      return { digest, title };
+    } catch {
+      const i = s.indexOf("{"), j = s.lastIndexOf("}");
+      if (i >= 0 && j > i) {
+        try {
+          const p = JSON.parse(s.slice(i, j + 1)) as { digest?: unknown; title?: unknown };
+          const digest = typeof p?.digest === "string" && p.digest.trim() ? p.digest.trim() : null;
+          if (!digest) return null;
+          const title = typeof p?.title === "string" && p.title.trim() ? p.title.trim() : undefined;
+          return { digest, title };
+        } catch { return null; }
+      }
+      return null;
+    }
+  };
+  const t = raw.trim();
+  const direct = tryParse(t);
+  if (direct) return direct;
+  const f = /^```(?:json)?\s*([\s\S]*?)```$/i.exec(t);
+  if (f?.[1]) {
+    const nested = tryParse(f[1].trim());
+    if (nested) return nested;
+  }
+  return { digest: t };
+}
+
+function parseDerivedDelta(raw: string): { digest: string; title?: string; candidates: MemoryCandidate[] } {
+  const parsedDigest = parseDigestAndTitle(raw);
+  const candidates = parseCandidates(raw);
+  return {
+    digest: parsedDigest.digest,
+    ...(parsedDigest.title ? { title: parsedDigest.title } : {}),
+    candidates,
+  };
+}
+
 function parseTitle(raw: string): string | undefined {
   const tryParse = (s: string): string | undefined => {
     try {

package/src/memory.test.ts

@@ -1,4 +1,4 @@
-import { MemoryStore, scoreMemoryMatch } from "./memory.js";
+import { MemoryStore, mergeMemoryCandidates, scoreMemoryMatch } from "./memory.js";
 import type { ParsedMemoryIssue } from "./types.js";
 import { stringifyFlatYaml } from "./yaml.js";
 
@@ -46,7 +46,10 @@ function testConfig(): never {
     memoryRecallLimit: 5,
     memoryAutoRecallLimit: 3,
     turnCommentDelayMs: 1000,
+    digestWaitTimeoutMs: 30000,
     summaryWaitTimeoutMs: 120000,
+    memoryExtractWaitTimeoutMs: 45000,
+    memoryReconcileWaitTimeoutMs: 45000,
   } as never;
 }
 
@@ -173,6 +176,32 @@ function testCjkScoring(): void {
   assert(billingScore > 0, "expected Chinese query to produce a positive match score");
 }
 
+function testMergeMemoryCandidates(): void {
+  const merged = mergeMemoryCandidates(
+    [
+      {
+        candidateId: "abc",
+        detail: "Redis Lua scripts keep rate limiting atomic.",
+        topics: ["redis"],
+      },
+    ],
+    [
+      {
+        candidateId: "abc",
+        detail: "Redis Lua scripts keep rate limiting atomic.",
+        kind: "lesson",
+        topics: ["rate-limit"],
+        evidence: "User confirmed the production path uses Lua.",
+      },
+    ],
+  );
+
+  assert(merged.length === 1, "expected duplicate candidates to merge by candidateId");
+  assert(merged[0]?.kind === "lesson", "expected merged candidates to preserve new schema hints");
+  assert(JSON.stringify(merged[0]?.topics) === JSON.stringify(["rate-limit", "redis"]), "expected merged candidates to union topics");
+  assert(merged[0]?.evidence === "User confirmed the production path uses Lua.", "expected merged candidates to preserve evidence");
+}
+
 async function testStructuredStoreAndSchema(): Promise<void> {
   const created: Array<{ title: string; body: string; labels: string[] }> = [];
   const ensured: string[][] = [];
@@ -456,8 +485,9 @@ async function main(): Promise<void> {
   await testBackendSearchPreferredForRecall();
   await testBackendSearchReturnsEmptyWithoutLexicalFallback();
   await testBackendSearchPropagatesErrors();
-  testCjkScoring();
-  await testStructuredStoreAndSchema();
+testCjkScoring();
+testMergeMemoryCandidates();
+await testStructuredStoreAndSchema();
   await testStoreKeepsFullAutoTitleAndSupportsExplicitTitle();
   await testGetAndListMemories();
   await testLegacyMemoriesWithoutSessionOrDate();