@clawmem-ai/clawmem 0.1.13 → 0.1.14

package/README.md

@@ -162,4 +162,4 @@ Full config with all options:
 - `memory_update` updates one existing memory issue in place; use it for evolving canonical facts or active tasks instead of creating a duplicate node.
 - Conversation lifecycle is stored in native issue state (`open` while live, `closed` after finalize); memory lifecycle uses native issue state too (`open` active, `closed` stale).
 - Memory extraction now prefers one atomic fact per memory item instead of bundling whole sessions into a single node.
-- Memory issue bodies store the durable detail plus flat metadata such as `memory_hash` and logical `date`; labels are reserved for schema and routing.
+- Memory issue bodies store the durable detail in a YAML `detail` field plus flat metadata such as `memory_hash` and logical `date`; this matches the current Console parser in `agent-git-service/web`.

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "clawmem",
   "name": "ClawMem",
-  "version": "0.1.13",
+  "version": "0.1.14",
   "description": "Mirror OpenClaw sessions into GitHub-compatible issues and comments.",
   "kind": "memory",
   "skills": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawmem-ai/clawmem",
-  "version": "0.1.13",
+  "version": "0.1.14",
   "description": "Mirror OpenClaw sessions into GitHub-compatible issues and comments.",
   "type": "module",
   "license": "MIT",

package/skills/clawmem/SKILL.md

@@ -50,6 +50,8 @@ On every user turn, run this loop:
    - 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.
    - Use `memory_store` when this is a genuinely new memory.
+   - When using `memory_store`, pass both `title` and `detail` when you can. Keep the title concise and human-readable, and keep `detail` as the full durable fact.
+   - When using `memory_update`, pass `title` as well if the existing title is too short, outdated, or less precise than the current canonical fact.
    - 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.
@@ -68,6 +70,8 @@ Bias toward retrieving and saving. A missed search or missed memory is worse tha
 - Project memory belongs in the relevant project repo.
 - Shared or team knowledge belongs in the shared repo for that group.
 - 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.
 - When updating an existing memory, keep that node in its current language unless the user explicitly asks to rewrite it.
 - Keep schema labels and machine-oriented fields stable. Do not translate `type:*`, `kind:*`, `topic:*`, or other structural identifiers.
 - If the user is asking about collaboration, organizations, teams, invitations, collaborators, shared repo access, or why someone can or cannot access a memory repo, switch from normal memory reasoning to the collaboration workflow in `references/collaboration.md`.

package/skills/clawmem/references/manual-ops.md

@@ -76,6 +76,7 @@ Do not export `GH_HOST` or `GH_ENTERPRISE_TOKEN` globally for unrelated github.c
 Use the tool path first. If raw issue control is required:
 
 - For new memories, write the issue title and body in the user's current language.
+- Prefer a concise standalone title and keep the full durable fact in the body.
 - When manually updating an existing memory, preserve that memory's current language unless the user explicitly asks for a rewrite.
 - Keep labels and schema markers such as `type:*`, `kind:*`, and `topic:*` in their fixed machine-readable form.
 

package/skills/clawmem/references/schema.md

@@ -61,6 +61,8 @@ If you create a curated memory manually, include:
 ## Storage language
 
 - For new memory nodes, write the human-readable title and body in the user's current language by default.
+- When using plugin tools, prefer passing an explicit short `title` plus a fuller `detail` body.
+- Do not treat the title as the only durable content. The body detail should still contain the full reusable fact.
 - When updating an existing memory node, preserve that node's current language unless the user explicitly asks for a rewrite.
 - Do not translate schema or routing markers such as `type:*`, `kind:*`, `topic:*`, or other machine-oriented field names.
 

package/src/memory.test.ts

@@ -177,12 +177,36 @@ async function testStructuredStoreAndSchema(): Promise<void> {
   assert(created[0]?.labels.includes("topic:rate-limit"), "expected created labels to include normalized topic");
   assert(!created[0]?.labels.some((label) => label.startsWith("session:")), "expected manual memory_store writes to omit synthetic session labels");
   assert(!created[0]?.labels.some((label) => label.startsWith("date:")), "expected new memory labels to omit date labels");
+  assert(created[0]?.body.includes("memory_hash:"), "expected new memory body to retain metadata fields");
+  assert(created[0]?.body.includes("detail: Redis Lua scripts are required for atomic rate limiting."), "expected new memory body to store detail in YAML");
   assert(created[0]?.body.includes(`date: ${result.memory.date}`), "expected new memory body to retain logical date metadata");
   assert(ensured[0]?.includes("kind:lesson"), "expected ensureLabels to include kind label");
   assert(schema.kinds.includes("lesson"), "expected schema to expose existing kind labels");
   assert(schema.topics.includes("redis"), "expected schema to expose existing topic labels");
 }
 
+async function testStoreKeepsFullAutoTitleAndSupportsExplicitTitle(): Promise<void> {
+  const created: Array<{ title: string; body: string; labels: string[] }> = [];
+  const client = {
+    listIssues: async () => [] as IssueRecord[],
+    listLabels: async () => [] as LabelRecord[],
+    ensureLabels: async () => {},
+    createIssue: async (payload: { title: string; body: string; labels: string[] }) => {
+      created.push(payload);
+      return { number: created.length + 100, title: payload.title };
+    },
+  };
+  const store = new MemoryStore(client as never, {} as never, testConfig());
+  const longDetail = "Tech Decision #001: Frontend = React Native, Backend = FastAPI, Database = PostgreSQL, and analytics events must stay append-only for auditability.";
+  const auto = await store.store({ detail: longDetail });
+  const explicit = await store.store({ title: "Architecture Decision #001", detail: "Use React Native + FastAPI for the first mobile stack." });
+
+  assert(auto.memory.title === `Memory: ${longDetail}`, "expected auto-generated memory title to keep the full detail without truncation");
+  assert(explicit.memory.title === "Memory: Architecture Decision #001", "expected explicit memory title to be preserved");
+  assert(created[0]?.title === `Memory: ${longDetail}`, "expected created issue title to keep the full auto title");
+  assert(created[1]?.title === "Memory: Architecture Decision #001", "expected created issue title to use the explicit title");
+}
+
 async function testGetAndListMemories(): Promise<void> {
   const issues = [
     issueFromMemory(memory({
@@ -312,10 +336,52 @@ async function testUpdateMemoryInPlace(): Promise<void> {
   assert(JSON.stringify(updated?.topics) === JSON.stringify(["preferences", "sports"]), "expected topics to be replaced");
   assert(updatedIssues.length === 1, "expected a single issue update");
   assert(updatedIssues[0]?.title !== "Memory: xiangz preferences", "expected title to refresh from updated detail");
+  assert(updatedIssues[0]?.body?.includes("memory_hash:"), "expected updated body to retain metadata");
+  assert(updatedIssues[0]?.body?.includes("detail:"), "expected updated body to store a detail field in YAML");
+  assert(updatedIssues[0]?.body?.includes("recently follows tennis"), "expected updated body to contain the updated detail text");
   assert(ensured[0]?.includes("topic:sports"), "expected new topic label to be ensured");
   assert(syncedLabels[0]?.labels.includes("kind:core-fact"), "expected existing kind label to be preserved");
 }
 
+async function testUpdateSupportsExplicitRetitle(): Promise<void> {
+  const issues: IssueRecord[] = [
+    issueFromMemory(memory({
+      issueNumber: 20,
+      title: "Memory: old short title",
+      detail: "We use append-only audit events for billing changes.",
+      kind: "convention",
+    })),
+  ];
+  const updatedIssues: Array<{ number: number; title?: string; body?: string }> = [];
+  const client = {
+    listIssues: async (params?: { labels?: string[]; state?: "open" | "closed" | "all" }) => {
+      const labels = params?.labels ?? [];
+      const state = params?.state ?? "open";
+      return issues.filter((issue) => {
+        const issueLabels = issue.labels ?? [];
+        if (!labels.every((label) => issueLabels.includes(label))) return false;
+        if (state === "all") return true;
+        return (issue.state ?? "open") === state;
+      });
+    },
+    ensureLabels: async () => {},
+    updateIssue: async (number: number, patch: { title?: string; body?: string }) => {
+      updatedIssues.push({ number, ...patch });
+      const issue = issues.find((entry) => entry.number === number);
+      if (!issue) throw new Error("issue missing");
+      if (patch.title) issue.title = patch.title;
+      if (patch.body) issue.body = patch.body;
+      return issue;
+    },
+    syncManagedLabels: async () => {},
+  };
+  const store = new MemoryStore(client as never, {} as never, testConfig());
+  const updated = await store.update("20", { title: "Billing Audit Convention" });
+
+  assert(updated?.title === "Memory: Billing Audit Convention", "expected memory_update to support explicit retitle");
+  assert(updatedIssues[0]?.title === "Memory: Billing Audit Convention", "expected issue title patch to use the explicit retitle");
+}
+
 async function testForgetClosesMemoryIssue(): Promise<void> {
   const issues: IssueRecord[] = [
     issueFromMemory(memory({
@@ -367,9 +433,11 @@ async function main(): Promise<void> {
   await testBackendSearchFallsBackToLocalLexical();
   testCjkScoring();
   await testStructuredStoreAndSchema();
+  await testStoreKeepsFullAutoTitleAndSupportsExplicitTitle();
   await testGetAndListMemories();
   await testLegacyMemoriesWithoutSessionOrDate();
   await testUpdateMemoryInPlace();
+  await testUpdateSupportsExplicitRetitle();
   await testForgetClosesMemoryIssue();
   console.log("memory tests passed");
 }

package/src/memory.ts

@@ -84,8 +84,8 @@ export class MemoryStore {
 
     const date = localDate();
     const labels = memLabels(normalized.kind, normalized.topics);
-    const title = `${MEMORY_TITLE_PREFIX}${trunc(detail, 72)}`;
-    const body = stringifyFlatYaml([["memory_hash", hash], ["date", date], ["detail", detail]]);
+    const title = renderMemoryTitle(normalized);
+    const body = renderMemoryBody(detail, hash, date);
     await this.client.ensureLabels(labels);
     const issue = await this.client.createIssue({ title, body, labels });
     return {
@@ -104,10 +104,15 @@ export class MemoryStore {
     };
   }
 
-  async update(memoryId: string, patch: { detail?: string; kind?: string; topics?: string[] }): Promise<ParsedMemoryIssue | null> {
+  async update(memoryId: string, patch: { title?: string; detail?: string; kind?: string; topics?: string[] }): Promise<ParsedMemoryIssue | null> {
     const current = await this.get(memoryId, "all");
     if (!current) return null;
     const nextDetail = typeof patch.detail === "string" && patch.detail.trim() ? norm(patch.detail) : current.detail;
+    const nextTitle = typeof patch.title === "string" && patch.title.trim()
+      ? renderMemoryTitle({ title: patch.title.trim(), detail: nextDetail })
+      : patch.detail !== undefined
+        ? renderMemoryTitle({ detail: nextDetail })
+        : current.title || renderMemoryTitle({ detail: nextDetail });
     const nextKind = patch.kind !== undefined ? normalizeLabelValue(patch.kind, "kind:") : current.kind;
     const nextTopics = patch.topics !== undefined
       ? uniqueNormalized(patch.topics.map((topic) => normalizeLabelValue(topic, "topic:")).filter(Boolean) as string[])
@@ -118,8 +123,7 @@ export class MemoryStore {
       return (memory.memoryHash || sha256(norm(memory.detail))) === nextHash;
     });
     if (duplicate) throw new Error(`another active memory already stores this detail as [${duplicate.memoryId}]`);
-    const nextTitle = `${MEMORY_TITLE_PREFIX}${trunc(nextDetail, 72)}`;
-    const nextBody = stringifyFlatYaml([["memory_hash", nextHash], ["date", current.date], ["detail", nextDetail]]);
+    const nextBody = renderMemoryBody(nextDetail, nextHash, current.date);
     const nextLabels = memLabels(nextKind, nextTopics);
     await this.client.ensureLabels(nextLabels);
     await this.client.updateIssue(current.issueNumber, { title: nextTitle, body: nextBody });
@@ -201,16 +205,16 @@ export class MemoryStore {
     const kind = labelVal(labels, "kind:");
     const topics = labels.filter((l) => l.startsWith("topic:")).map((l) => l.slice(6).trim()).filter(Boolean);
     const rawBody = (issue.body ?? "").trim();
-    const body = rawBody ? parseFlatYaml(rawBody) : {};
-    const detail = body.detail?.trim() || rawBody;
+    const parsed = parseStoredMemoryBody(rawBody);
+    const detail = parsed.detail?.trim() || rawBody;
     const status = issue.state === "closed" || labels.includes(LABEL_MEMORY_STALE) ? "stale" : "active";
     if (!detail) return null;
     return {
       issueNumber: issue.number,
       title: issue.title?.trim() || "",
-      memoryId: body.memory_id?.trim() || String(issue.number),
-      memoryHash: body.memory_hash?.trim() || undefined,
-      date: body.date?.trim() || "1970-01-01",
+      memoryId: parsed.meta.memory_id?.trim() || String(issue.number),
+      memoryHash: parsed.meta.memory_hash?.trim() || undefined,
+      date: parsed.meta.date?.trim() || "1970-01-01",
       detail,
       ...(kind ? { kind } : {}),
       ...(topics.length > 0 ? { topics } : {}),
@@ -236,8 +240,8 @@ export class MemoryStore {
       }
       const labels = memLabels(draft.kind, draft.topics);
       const date = localDate();
-      const title = `${MEMORY_TITLE_PREFIX}${trunc(detail, 72)}`;
-      const body = stringifyFlatYaml([["memory_hash", hash], ["date", date], ["detail", detail]]);
+      const title = renderMemoryTitle(draft);
+      const body = renderMemoryBody(detail, hash, date);
       await this.client.ensureLabels(labels);
       const issue = await this.client.createIssue({ title, body, labels });
       activeByHash.set(hash, {
@@ -280,9 +284,10 @@ export class MemoryStore {
     const sessionKey = subKey(session, "memory");
     const message = [
       "Extract durable memories from the conversation below.",
-      'Return JSON only in the form {"save":[{"detail":"...","kind":"...","topics":["..."]}],"stale":["memory-id"]}.',
+      'Return JSON only in the form {"save":[{"title":"...","detail":"...","kind":"...","topics":["..."]}],"stale":["memory-id"]}.',
       "Each save item must contain one durable fact. If a turn contains several independent facts, save them separately instead of bundling them into one summary memory.",
       "Use save for stable, reusable facts, preferences, decisions, constraints, workflows, and ongoing context worth remembering later.",
+      "Title is optional. If you provide one, make it concise and human-readable.",
       "Use stale for existing memory IDs only when the conversation clearly supersedes or invalidates them.",
       "Infer kind and topics when they would help future retrieval. Reuse existing kinds and topics when possible.",
       "If no existing kind fits, you may propose a new short kind label. Keep kinds concise and reusable.",
@@ -300,7 +305,7 @@ export class MemoryStore {
         deliver: false,
         lane: "clawmem-memory",
         idempotencyKey: sha256(`${session.sessionId}:${snapshot.messages.length}:memory-decision`),
-        extraSystemPrompt: "You extract durable memory updates from OpenClaw conversations. Output JSON only with save objects containing detail, optional kind, and optional topics, plus stale string ids. Keep each save item to one durable fact.",
+        extraSystemPrompt: "You extract durable memory updates from OpenClaw conversations. Output JSON only with save objects containing detail, optional title, optional kind, and optional topics, plus stale string ids. Keep each save item to one durable fact.",
       });
       const wait = await subagent.waitForRun({ runId: run.runId, timeoutMs: this.config.summaryWaitTimeoutMs });
       if (wait.status === "timeout") throw new Error("memory decision subagent timed out");
@@ -341,6 +346,35 @@ function memLabels(kind?: string, topics?: string[]): string[] {
   ];
 }
 
+function renderMemoryTitle(draft: Pick<MemoryDraft, "detail" | "title">): string {
+  const raw = typeof draft.title === "string" && draft.title.trim() ? draft.title : draft.detail;
+  const normalized = norm(raw);
+  return normalized.startsWith(MEMORY_TITLE_PREFIX) ? normalized : `${MEMORY_TITLE_PREFIX}${normalized}`;
+}
+
+function renderMemoryBody(detail: string, memoryHash: string, date: string): string {
+  return stringifyFlatYaml([["memory_hash", memoryHash], ["date", date], ["detail", norm(detail)]]);
+}
+
+function parseStoredMemoryBody(rawBody: string): { detail: string; meta: Record<string, string> } {
+  const trimmed = rawBody.trim();
+  if (!trimmed) return { detail: "", meta: {} };
+
+  const legacyYaml = parseFlatYaml(trimmed);
+  if (legacyYaml.detail?.trim()) {
+    return { detail: legacyYaml.detail.trim(), meta: legacyYaml };
+  }
+
+  const hiddenMeta = /(?:^|\n)<!--\s*clawmem-meta\s*\n([\s\S]*?)\n-->\s*$/.exec(trimmed);
+  if (!hiddenMeta) {
+    return { detail: trimmed, meta: {} };
+  }
+
+  const meta = parseFlatYaml(hiddenMeta[1] ?? "");
+  const detail = trimmed.slice(0, hiddenMeta.index).trim() || meta.detail?.trim() || "";
+  return { detail, meta };
+}
+
 function norm(v: string): string { return v.replace(/\s+/g, " ").trim(); }
 function trunc(v: string, max: number): string { const s = norm(v); return s.length <= max ? s : `${s.slice(0, max - 1).trimEnd()}…`; }
 function normalizeSearch(v: string): string {
@@ -429,9 +463,11 @@ export function scoreMemoryMatch(memory: ParsedMemoryIssue, rawQuery: string): n
 function normalizeDraft(input: MemoryDraft): MemoryDraft {
   const detail = norm(input.detail);
   if (!detail) throw new Error("memory detail is empty");
+  const title = typeof input.title === "string" && input.title.trim() ? norm(input.title) : undefined;
   const kind = normalizeLabelValue(input.kind, "kind:");
   const topics = uniqueNormalized((input.topics ?? []).map((topic) => normalizeLabelValue(topic, "topic:")).filter(Boolean) as string[]);
   return {
+    ...(title ? { title } : {}),
     detail,
     ...(kind ? { kind } : {}),
     ...(topics.length > 0 ? { topics } : {}),
@@ -490,12 +526,13 @@ function parseSaveItem(value: unknown): MemoryDraft | null {
   }
   if (!value || typeof value !== "object" || Array.isArray(value)) return null;
   const record = value as Record<string, unknown>;
+  const title = typeof record.title === "string" ? record.title : undefined;
   const detail = typeof record.detail === "string" ? norm(record.detail) : "";
   if (!detail) return null;
   const kind = typeof record.kind === "string" ? record.kind : undefined;
   const topics = Array.isArray(record.topics) ? record.topics.filter((v): v is string => typeof v === "string") : undefined;
   try {
-    return normalizeDraft({ detail, ...(kind ? { kind } : {}), ...(topics ? { topics } : {}) });
+    return normalizeDraft({ ...(title ? { title } : {}), detail, ...(kind ? { kind } : {}), ...(topics ? { topics } : {}) });
   } catch {
     return null;
   }

package/src/service.test.ts

@@ -0,0 +1,141 @@
+import {
+  buildLegacyRelevantMemoriesContext,
+  buildRelevantMemoriesSystemContext,
+  extractPromptTextForRecall,
+  resolveOpenClawHostVersion,
+  resolvePromptHookMode,
+} from "./service.js";
+
+function assert(condition: unknown, message: string): void {
+  if (!condition) throw new Error(message);
+}
+
+function testExtractPromptFromString(): void {
+  assert(extractPromptTextForRecall("  help me fix redis  ") === "help me fix redis", "expected direct string prompts to be trimmed");
+}
+
+function testExtractPromptFromPromptField(): void {
+  assert(
+    extractPromptTextForRecall({ prompt: "Summarize the release notes." }) === "Summarize the release notes.",
+    "expected prompt field to be used when present",
+  );
+}
+
+function testExtractPromptFromLatestUserMessage(): void {
+  const prompt = extractPromptTextForRecall({
+    messages: [
+      { role: "assistant", text: "How can I help?" },
+      { role: "user", text: "Please fix the login bug." },
+    ],
+  });
+  assert(prompt === "Please fix the login bug.", "expected the latest user message to drive recall");
+}
+
+function testExtractPromptFromStructuredContent(): void {
+  const prompt = extractPromptTextForRecall({
+    messages: [
+      {
+        role: "user",
+        content: [
+          { type: "text", text: "Check the deployment logs" },
+          { type: "text", text: "and verify nginx." },
+        ],
+      },
+    ],
+  });
+  assert(prompt === "Check the deployment logs\nand verify nginx.", "expected structured text content to be flattened");
+}
+
+function testBuildRelevantMemoriesSystemContext(): void {
+  const context = buildRelevantMemoriesSystemContext([
+    { detail: "OpenClaw main agent identity uses Gandalf." },
+    { detail: "Shared memories can break if the repo path changes." },
+  ]);
+
+  assert(context.includes("ClawMem relevant memories:"), "expected a human-readable heading");
+  assert(context.includes("- OpenClaw main agent identity uses Gandalf."), "expected memories to be listed as bullets");
+  assert(!context.includes("<relevant-memories>"), "expected the legacy XML wrapper to be removed");
+}
+
+function testBuildLegacyRelevantMemoriesContext(): void {
+  const context = buildLegacyRelevantMemoriesContext([
+    { detail: "Use the shared repo for team memory." },
+  ]);
+
+  assert(context.includes("Relevant ClawMem memories for this request:"), "expected a legacy-safe heading");
+  assert(context.includes("- Use the shared repo for team memory."), "expected memories to stay readable");
+  assert(!context.includes("<relevant-memories>"), "expected legacy context to avoid XML wrappers too");
+}
+
+function testResolveHostVersionFromRuntime(): void {
+  const version = resolveOpenClawHostVersion({ runtime: { version: "2026.3.28" } } as never);
+  assert(version === "2026.3.28", "expected runtime.version to take precedence");
+}
+
+function testResolveHostVersionFromEnvFallback(): void {
+  const previous = {
+    OPENCLAW_VERSION: process.env.OPENCLAW_VERSION,
+    OPENCLAW_SERVICE_VERSION: process.env.OPENCLAW_SERVICE_VERSION,
+    npm_package_version: process.env.npm_package_version,
+  };
+  try {
+    delete process.env.OPENCLAW_VERSION;
+    process.env.OPENCLAW_SERVICE_VERSION = "2026.3.6";
+    delete process.env.npm_package_version;
+    const version = resolveOpenClawHostVersion({ runtime: {} } as never);
+    assert(version === "2026.3.6", "expected OPENCLAW_SERVICE_VERSION fallback");
+  } finally {
+    process.env.OPENCLAW_VERSION = previous.OPENCLAW_VERSION;
+    process.env.OPENCLAW_SERVICE_VERSION = previous.OPENCLAW_SERVICE_VERSION;
+    process.env.npm_package_version = previous.npm_package_version;
+  }
+}
+
+function testIgnoresNpmPackageVersionFallback(): void {
+  const previous = {
+    OPENCLAW_VERSION: process.env.OPENCLAW_VERSION,
+    OPENCLAW_SERVICE_VERSION: process.env.OPENCLAW_SERVICE_VERSION,
+    npm_package_version: process.env.npm_package_version,
+  };
+  try {
+    delete process.env.OPENCLAW_VERSION;
+    delete process.env.OPENCLAW_SERVICE_VERSION;
+    process.env.npm_package_version = "2026.3.99";
+    const version = resolveOpenClawHostVersion({ runtime: {} } as never);
+    assert(version === undefined, "expected npm_package_version to be ignored for host detection");
+  } finally {
+    process.env.OPENCLAW_VERSION = previous.OPENCLAW_VERSION;
+    process.env.OPENCLAW_SERVICE_VERSION = previous.OPENCLAW_SERVICE_VERSION;
+    process.env.npm_package_version = previous.npm_package_version;
+  }
+}
+
+function testResolvePromptHookModeModern(): void {
+  const mode = resolvePromptHookMode({ runtime: { version: "2026.3.28" } } as never);
+  assert(mode === "modern", "expected modern hook mode for OpenClaw 2026.3.28");
+}
+
+function testResolvePromptHookModeLegacy(): void {
+  const mode = resolvePromptHookMode({ runtime: { version: "2026.3.6" } } as never);
+  assert(mode === "legacy", "expected legacy hook mode before 2026.3.7");
+}
+
+function testResolvePromptHookModeLegacyForUnknownVersion(): void {
+  const mode = resolvePromptHookMode({ runtime: {} } as never);
+  assert(mode === "legacy", "expected unknown host versions to fall back to legacy mode");
+}
+
+testExtractPromptFromString();
+testExtractPromptFromPromptField();
+testExtractPromptFromLatestUserMessage();
+testExtractPromptFromStructuredContent();
+testBuildRelevantMemoriesSystemContext();
+testBuildLegacyRelevantMemoriesContext();
+testResolveHostVersionFromRuntime();
+testResolveHostVersionFromEnvFallback();
+testIgnoresNpmPackageVersionFallback();
+testResolvePromptHookModeModern();
+testResolvePromptHookModeLegacy();
+testResolvePromptHookModeLegacyForUnknownVersion();
+
+console.log("service tests passed");

package/src/service.ts

@@ -17,6 +17,8 @@ type CollaborationPermission = "read" | "write" | "admin";
 type CollaborationTeamRole = "member" | "maintainer";
 
 const SESSION_MAINTENANCE_RETRY_DELAYS_MS = [5000, 30000, 120000] as const;
+const MODERN_PROMPT_HOOK_MIN_HOST_VERSION = "2026.3.7";
+type PromptHookMode = "modern" | "legacy";
 
 class ClawMemService {
   private readonly config: ClawMemPluginConfig;
@@ -36,7 +38,12 @@ class ClawMemService {
   }
 
   register(): void {
-    this.api.on("before_agent_start", async (ev, ctx) => this.handleBeforeAgentStart(ev.prompt, ctx.agentId));
+    const promptHookMode = resolvePromptHookMode(this.api);
+    if (promptHookMode === "modern") {
+      this.api.on("before_prompt_build", async (ev, ctx) => this.handleBeforePromptBuild(ev, ctx.agentId));
+    } else {
+      this.api.on("before_agent_start", async (ev, ctx) => this.handleBeforeAgentStart(ev, ctx.agentId));
+    }
     this.api.on("agent_end", (ev, ctx) => this.scheduleTurn({ sessionId: ctx.sessionId, sessionKey: ctx.sessionKey, agentId: ctx.agentId, messages: ev.messages }));
     this.api.on("before_reset", (ev, ctx) => this.enqueueFinalize({ sessionId: ctx.sessionId, sessionKey: ctx.sessionKey, sessionFile: ev.sessionFile, agentId: ctx.agentId, reason: ev.reason, messages: ev.messages }));
     this.api.on("session_end", (ev, ctx) => this.enqueueFinalize({ sessionId: ev.sessionId ?? ctx.sessionId, sessionKey: ev.sessionKey ?? ctx.sessionKey, agentId: ctx.agentId, reason: "session_end" }));
@@ -55,10 +62,11 @@ class ClawMemService {
           const route = resolveAgentRoute(this.config, agentId);
           return isAgentConfigured(route) && hasDefaultRepo(route);
         }).length;
+        const hostVersion = resolveOpenClawHostVersion(this.api);
         this.api.logger.info?.(
           configuredCount > 0
-            ? `clawmem: ready with ${configuredCount} configured agent route(s); missing routes will provision on first use via ${this.config.baseUrl}`
-            : `clawmem: ready; agent routes will provision on first use via ${this.config.baseUrl}`,
+            ? `clawmem: ready with ${configuredCount} configured agent route(s); prompt hook mode=${promptHookMode}${hostVersion ? ` for OpenClaw ${hostVersion}` : ""}; missing routes will provision on first use via ${this.config.baseUrl}`
+            : `clawmem: ready; prompt hook mode=${promptHookMode}${hostVersion ? ` for OpenClaw ${hostVersion}` : ""}; agent routes will provision on first use via ${this.config.baseUrl}`,
         );
       },
       stop: async () => {
@@ -298,6 +306,7 @@ class ClawMemService {
         type: "object",
         additionalProperties: false,
         properties: {
+          title: { type: "string", minLength: 1, description: "Optional human-readable memory title. Defaults to the full detail text when omitted." },
           detail: { type: "string", minLength: 1, description: "The durable fact, lesson, decision, or preference to remember." },
           kind: { type: "string", minLength: 1, description: "Optional schema kind, for example lesson, convention, skill, or task." },
           topics: {
@@ -314,6 +323,7 @@ class ClawMemService {
       },
       execute: async (_id: string, params: unknown) => {
         const p = asRecord(params);
+        const title = typeof p.title === "string" ? p.title.trim() : "";
         const detail = typeof p.detail === "string" ? p.detail.trim() : "";
         if (!detail) return toolText("Detail is empty.");
         const agentId = this.resolveToolAgentId(p.agentId);
@@ -322,6 +332,7 @@ class ClawMemService {
         const kind = typeof p.kind === "string" && p.kind.trim() ? p.kind.trim() : undefined;
         const topics = Array.isArray(p.topics) ? p.topics.filter((topic): topic is string => typeof topic === "string" && topic.trim().length > 0) : undefined;
         const result = await resolved.mem.store({
+          ...(title ? { title } : {}),
           detail,
           ...(kind ? { kind } : {}),
           ...(topics && topics.length > 0 ? { topics } : {}),
@@ -340,6 +351,7 @@ class ClawMemService {
         additionalProperties: false,
         properties: {
           memoryId: { type: "string", minLength: 1, description: "The memory id or issue number to update." },
+          title: { type: "string", minLength: 1, description: "Optional replacement title for the same memory record." },
           detail: { type: "string", minLength: 1, description: "Optional replacement detail text for the same memory record." },
           kind: { type: "string", minLength: 1, description: "Optional replacement kind label." },
           topics: {
@@ -358,16 +370,17 @@ class ClawMemService {
         const p = asRecord(params);
         const memoryId = typeof p.memoryId === "string" ? p.memoryId.trim() : "";
         if (!memoryId) return toolText("memoryId is empty.");
+        const title = typeof p.title === "string" && p.title.trim() ? p.title.trim() : undefined;
         const detail = typeof p.detail === "string" && p.detail.trim() ? p.detail.trim() : undefined;
         const kind = typeof p.kind === "string" && p.kind.trim() ? p.kind.trim() : undefined;
         const topics = Array.isArray(p.topics) ? p.topics.filter((topic): topic is string => typeof topic === "string" && topic.trim().length > 0) : undefined;
-        if (!detail && kind === undefined && topics === undefined) return toolText("Provide at least one of detail, kind, or topics.");
+        if (title === undefined && !detail && kind === undefined && topics === undefined) return toolText("Provide at least one of title, detail, kind, or topics.");
         const agentId = this.resolveToolAgentId(p.agentId);
         const resolved = await this.requireToolRoute(agentId, p.repo);
         if ("error" in resolved) return toolText(resolved.error);
         let updated;
         try {
-          updated = await resolved.mem.update(memoryId, { ...(detail ? { detail } : {}), ...(kind !== undefined ? { kind } : {}), ...(topics !== undefined ? { topics } : {}) });
+          updated = await resolved.mem.update(memoryId, { ...(title ? { title } : {}), ...(detail ? { detail } : {}), ...(kind !== undefined ? { kind } : {}), ...(topics !== undefined ? { topics } : {}) });
         } catch (error) {
           return toolText(`Unable to update memory "${memoryId}": ${String(error)}`);
         }
@@ -1293,17 +1306,31 @@ class ClawMemService {
     });
   }
 
-  private async handleBeforeAgentStart(prompt: unknown, agentId?: string): Promise<{ prependContext: string } | void> {
+  private async handleBeforePromptBuild(event: unknown, agentId?: string): Promise<{ prependSystemContext: string } | void> {
+    const routeAgentId = normalizeAgentId(agentId);
+    if (!(await this.ensureDefaultRepoConfigured(routeAgentId))) return;
+    this.scheduleRecentSessionMaintenance(routeAgentId);
+    const prompt = extractPromptTextForRecall(event);
+    if (typeof prompt !== "string" || prompt.trim().length < 5) return;
+    try {
+      const { mem } = this.getServices(routeAgentId);
+      const memories = await mem.search(prompt, this.config.memoryAutoRecallLimit);
+      if (memories.length === 0) return;
+      return { prependSystemContext: buildRelevantMemoriesSystemContext(memories) };
+    } catch (error) { this.api.logger.warn(`clawmem: memory recall failed: ${String(error)}`); }
+  }
+
+  private async handleBeforeAgentStart(event: unknown, agentId?: string): Promise<{ prependContext: string } | void> {
     const routeAgentId = normalizeAgentId(agentId);
     if (!(await this.ensureDefaultRepoConfigured(routeAgentId))) return;
     this.scheduleRecentSessionMaintenance(routeAgentId);
+    const prompt = extractPromptTextForRecall(event);
     if (typeof prompt !== "string" || prompt.trim().length < 5) return;
     try {
       const { mem } = this.getServices(routeAgentId);
       const memories = await mem.search(prompt, this.config.memoryAutoRecallLimit);
       if (memories.length === 0) return;
-      const text = memories.map((m) => `- ${formatInjectedMemory(m)}`).join("\n");
-      return { prependContext: `<relevant-memories>\nThe following active memories may be relevant to this conversation:\n${text}\n</relevant-memories>` };
+      return { prependContext: buildLegacyRelevantMemoriesContext(memories) };
     } catch (error) { this.api.logger.warn(`clawmem: memory recall failed: ${String(error)}`); }
   }
 
@@ -1812,12 +1839,170 @@ function renderMemoryBlock(memory: {
   return lines.join("\n");
 }
 
+export function buildRelevantMemoriesSystemContext(memories: Array<{ detail: string }>): string {
+  return [
+    "ClawMem relevant memories:",
+    "Use these as background context only when they help with the current request.",
+    ...memories.map((memory) => `- ${formatInjectedMemory(memory)}`),
+  ].join("\n");
+}
+
+export function buildLegacyRelevantMemoriesContext(memories: Array<{ detail: string }>): string {
+  return [
+    "Relevant ClawMem memories for this request:",
+    ...memories.map((memory) => `- ${formatInjectedMemory(memory)}`),
+  ].join("\n");
+}
+
 function formatInjectedMemory(memory: {
   detail: string;
 }): string {
   return memory.detail;
 }
 
+export function extractPromptTextForRecall(event: unknown): string | undefined {
+  const direct = normalizePromptText(event);
+  if (direct) return direct;
+
+  const record = asRecord(event);
+  for (const candidate of [record.prompt, record.userPrompt, record.input, record.query, record.text]) {
+    const text = normalizePromptText(candidate);
+    if (text) return text;
+  }
+
+  return extractPromptTextFromMessages(record.messages) ?? extractPromptTextFromMessages(record.conversation);
+}
+
+function extractPromptTextFromMessages(value: unknown): string | undefined {
+  if (!Array.isArray(value)) return undefined;
+  let fallback: string | undefined;
+  for (let index = value.length - 1; index >= 0; index--) {
+    const message = value[index];
+    const record = asRecord(message);
+    const role = typeof record.role === "string" ? record.role.trim().toLowerCase() : "";
+    const text = normalizePromptText(record.text)
+      ?? normalizePromptText(record.prompt)
+      ?? normalizePromptText(record.content)
+      ?? normalizePromptText(record.message);
+    if (!text) continue;
+    if (!fallback) fallback = text;
+    if (!role || role === "user") return text;
+  }
+  return fallback;
+}
+
+function normalizePromptText(value: unknown): string | undefined {
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    return trimmed || undefined;
+  }
+  if (Array.isArray(value)) {
+    const parts = value
+      .map((entry) => {
+        if (typeof entry === "string") return entry.trim();
+        const record = asRecord(entry);
+        if (record.type === "text" && typeof record.text === "string") return record.text.trim();
+        if (typeof record.text === "string") return record.text.trim();
+        return "";
+      })
+      .filter(Boolean);
+    return parts.length > 0 ? parts.join("\n") : undefined;
+  }
+  return undefined;
+}
+
+export function resolvePromptHookMode(api: Pick<OpenClawPluginApi, "runtime">): PromptHookMode {
+  const hostVersion = resolveOpenClawHostVersion(api);
+  if (!hostVersion) return "legacy";
+  const comparison = compareOpenClawVersions(hostVersion, MODERN_PROMPT_HOOK_MIN_HOST_VERSION);
+  if (comparison === null) return "legacy";
+  return comparison >= 0 ? "modern" : "legacy";
+}
+
+export function resolveOpenClawHostVersion(api: Pick<OpenClawPluginApi, "runtime">): string | undefined {
+  const runtimeVersion = typeof api.runtime?.version === "string" ? api.runtime.version.trim() : "";
+  if (isUsableOpenClawVersion(runtimeVersion)) return runtimeVersion;
+  for (const candidate of [
+    process.env.OPENCLAW_VERSION,
+    process.env.OPENCLAW_SERVICE_VERSION,
+  ]) {
+    const trimmed = candidate?.trim();
+    if (isUsableOpenClawVersion(trimmed)) return trimmed;
+  }
+  return undefined;
+}
+
+function isUsableOpenClawVersion(version: string | undefined): version is string {
+  return Boolean(version && version !== "0.0.0" && version !== "unknown");
+}
+
+function compareOpenClawVersions(left: string, right: string): number | null {
+  const leftSemver = parseComparableSemver(left);
+  const rightSemver = parseComparableSemver(right);
+  if (!leftSemver || !rightSemver) return null;
+  if (leftSemver.major !== rightSemver.major) return leftSemver.major < rightSemver.major ? -1 : 1;
+  if (leftSemver.minor !== rightSemver.minor) return leftSemver.minor < rightSemver.minor ? -1 : 1;
+  if (leftSemver.patch !== rightSemver.patch) return leftSemver.patch < rightSemver.patch ? -1 : 1;
+  return comparePrereleaseIdentifiers(leftSemver.prerelease, rightSemver.prerelease);
+}
+
+type ComparableSemver = {
+  major: number;
+  minor: number;
+  patch: number;
+  prerelease: string[] | null;
+};
+
+function parseComparableSemver(version: string | undefined): ComparableSemver | null {
+  if (!version) return null;
+  const normalized = normalizeLegacyDotBetaVersion(version);
+  const match = /^v?([0-9]+)\.([0-9]+)\.([0-9]+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(normalized);
+  if (!match) return null;
+  const [, major, minor, patch, prereleaseRaw] = match;
+  if (!major || !minor || !patch) return null;
+  return {
+    major: Number.parseInt(major, 10),
+    minor: Number.parseInt(minor, 10),
+    patch: Number.parseInt(patch, 10),
+    prerelease: prereleaseRaw ? prereleaseRaw.split(".").filter(Boolean) : null,
+  };
+}
+
+function normalizeLegacyDotBetaVersion(version: string): string {
+  const trimmed = version.trim();
+  const dotBetaMatch = /^([vV]?[0-9]+\.[0-9]+\.[0-9]+)\.beta(?:\.([0-9A-Za-z.-]+))?$/.exec(trimmed);
+  if (!dotBetaMatch) return trimmed;
+  const base = dotBetaMatch[1];
+  const suffix = dotBetaMatch[2];
+  return suffix ? `${base}-beta.${suffix}` : `${base}-beta`;
+}
+
+function comparePrereleaseIdentifiers(a: string[] | null, b: string[] | null): number {
+  if (!a?.length && !b?.length) return 0;
+  if (!a?.length) return 1;
+  if (!b?.length) return -1;
+  const max = Math.max(a.length, b.length);
+  for (let index = 0; index < max; index += 1) {
+    const left = a[index];
+    const right = b[index];
+    if (left == null && right == null) return 0;
+    if (left == null) return -1;
+    if (right == null) return 1;
+    if (left === right) continue;
+    const leftNumeric = /^[0-9]+$/.test(left);
+    const rightNumeric = /^[0-9]+$/.test(right);
+    if (leftNumeric && rightNumeric) {
+      const leftNumber = Number.parseInt(left, 10);
+      const rightNumber = Number.parseInt(right, 10);
+      return leftNumber < rightNumber ? -1 : 1;
+    }
+    if (leftNumeric && !rightNumeric) return -1;
+    if (!leftNumeric && rightNumeric) return 1;
+    return left < right ? -1 : 1;
+  }
+  return 0;
+}
+
 function renderOrgLine(org: { login?: string; name?: string; default_repository_permission?: string; description?: string }): string {
   const login = org.login?.trim() || "unknown-org";
   const name = org.name?.trim() ? ` (${org.name.trim()})` : "";

package/src/types.ts

@@ -44,7 +44,7 @@ export type SessionMirrorState = {
 export type PluginState = { version: 2; sessions: Record<string, SessionMirrorState>; migrations?: Record<string, string> };
 export type NormalizedMessage = { role: string; text: string; toolName?: string; timestamp?: string; stopReason?: string };
 export type TranscriptSnapshot = { sessionId?: string; messages: NormalizedMessage[] };
-export type MemoryDraft = { detail: string; kind?: string; topics?: string[] };
+export type MemoryDraft = { title?: string; detail: string; kind?: string; topics?: string[] };
 export type MemorySchema = { kinds: string[]; topics: string[] };
 export type MemoryListOptions = {
   status?: "active" | "stale" | "all";