@clawmem-ai/clawmem 0.1.14 → 0.1.16

package/README.md

@@ -136,9 +136,12 @@ Full config with all options:
             }
           },
           turnCommentDelayMs: 1000,
+          digestWaitTimeoutMs: 30000,
           summaryWaitTimeoutMs: 120000,
+          memoryExtractWaitTimeoutMs: 45000,
+          memoryReconcileWaitTimeoutMs: 45000,
           memoryRecallLimit: 5,
-          memoryAutoRecallLimit: 5
+          memoryAutoRecallLimit: 3
         }
       }
     }
@@ -151,10 +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: ...`.
-- Memory search and auto-injection only return open `type:memory` issues. Closed memory issues are treated as stale.
-- `memory_recall` now prefers the backend `/api/v3/search/issues` endpoint scoped to the current repo plus `label:"type:memory"`, with a simple local lexical fallback when backend search is unavailable or returns no matches.
-- Durable memories are extracted best-effort during later request-scoped maintenance, not by background subagent work after a request has already ended.
+- 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 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.14",
+  "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",
@@ -127,7 +154,7 @@
     },
     "memoryAutoRecallLimit": {
       "label": "Auto Recall Limit",
-      "help": "Maximum number of active memories injected into context before an agent starts."
+      "help": "Maximum number of active memories automatically injected before each turn."
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawmem-ai/clawmem",
-  "version": "0.1.14",
+  "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,20 +25,23 @@ 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
-- Best-effort durable memory extraction during later request-scoped maintenance
-- Automatic recall of relevant active memories at session start
+- 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 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`
 
-Automatic recall is only a bootstrap. You still need to retrieve before answering when memory may matter, and save after learning something durable.
-
 ## Mandatory turn loop
 
 On every user turn, run this loop:
 
 1. Before answering, ask: could ClawMem improve this answer?
    - Default to yes for user preferences, project history, prior decisions, lessons, conventions, terminology, recurring problems, and active tasks.
-   - Before explicit memory work, choose the right repo. If unclear, inspect `memory_repos` and fall back to the agent's `defaultRepo`.
-   - Start with `memory_recall`.
+   - Auto-recall may already inject useful context from the current agent's `defaultRepo`, but it is only a hint. Do not treat missing auto-recall context as proof that no relevant memory exists.
+   - If the injected context already answers the question, you do not need to immediately call `memory_recall` again.
+   - Auto-recall does not currently fan out across every accessible repo. Shared organization memory, team memory, and project memory outside the current `defaultRepo` will not be recalled automatically.
+   - Before explicit memory work, choose the right repo. If unclear, inspect `memory_repos` and fall back to the agent's `defaultRepo`. If the likely memory lives outside the default repo, use explicit repo selection instead of relying on auto-recall.
+   - Use `memory_recall` when injected context is missing, weak, cross-repo, high-stakes, or when you need an explicit retrieval trace.
+   - Write `memory_recall.query` as a short natural-language intent. Do not paste long code blocks, full logs, tool chatter, or system prompt text unless the exact wording is necessary.
    - When the question spans more than one angle, run more than one recall query across keywords, topics, synonyms, and likely project phrasing.
    - If `memory_recall` is weak or empty and the answer depends on whether a memory exists, cross-check with `memory_list`.
    - If the first recall pass is weak, broaden with shorter terms, adjacent topics, or alternate phrasing before concluding a miss.
@@ -46,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.
@@ -55,11 +59,11 @@ On every user turn, run this loop:
    - For new memories, write the memory title and body in the user's current language by default.
    - Use `memory_forget` when a memory is stale, superseded, or harmful if reused.
 3. Keep the user posted.
-   - If a retrieved memory materially shaped the answer, including automatic session-start recall, briefly surface that fact in the user's current language.
+   - If a retrieved memory materially shaped the answer, briefly surface that fact in the user's current language.
    - 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 retrieving and saving. A missed search or missed memory is worse than an extra search.
+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
 
@@ -69,6 +73,7 @@ Bias toward retrieving and saving. A missed search or missed memory is worse tha
 - Private personal memory usually belongs in the agent's `defaultRepo`.
 - Project memory belongs in the relevant project repo.
 - Shared or team knowledge belongs in the shared repo for that group.
+- Shared or team knowledge in another repo is not part of default auto-recall today. To use it, select that repo explicitly with `memory_recall`, `memory_list`, or `memory_get`.
 - Memory titles and bodies default to the user's current language for new memories.
 - Prefer a short standalone title plus a fuller `detail` body instead of stuffing the whole memory into the title.
 - If you omit `title`, the plugin may derive it from `detail`, but providing an explicit title is preferred for readability in the Console.

package/src/config.test.ts

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

package/src/config.ts

@@ -46,9 +46,12 @@ export function resolvePluginConfig(api: OpenClawPluginApi): ClawMemPluginConfig
     authScheme: raw.authScheme === "bearer" ? "bearer" : "token",
     agents,
     memoryRecallLimit: clamp(num(raw.memoryRecallLimit, 5), 1, 20),
-    memoryAutoRecallLimit: clamp(num(raw.memoryAutoRecallLimit, 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 {