@clawmem-ai/clawmem 0.1.15 → 0.1.17

package/src/memory.ts

@@ -1,16 +1,11 @@
-// Memory CRUD, sha256 dedup, and AI-driven memory extraction.
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
+// Memory CRUD, recall search helpers, and candidate parsing.
 import { LABEL_MEMORY_STALE, MEMORY_TITLE_PREFIX, extractLabelNames, labelVal } from "./config.js";
 import type { GitHubIssueClient } from "./github-client.js";
-import { normalizeMessages } from "./transcript.js";
-import type { ClawMemPluginConfig, MemoryDraft, MemoryListOptions, MemorySchema, ParsedMemoryIssue, SessionMirrorState, TranscriptSnapshot } from "./types.js";
-import { fmtTranscript, localDate, sha256, subKey } from "./utils.js";
+import type { MemoryCandidate, MemoryDraft, MemoryListOptions, MemorySchema, ParsedMemoryIssue } from "./types.js";
+import { localDate, sha256 } from "./utils.js";
 import { parseFlatYaml, stringifyFlatYaml } from "./yaml.js";
 import { sanitizeRecallQueryInput } from "./recall-sanitize.js";
 
-type MemoryDecision = { save: MemoryDraft[]; stale: string[] };
-type SearchIndex = { title: string; detail: string; kind?: string; topics: string[] };
-
 const MAX_BACKEND_QUERY_CHARS = 1500;
 
 const RECALL_INJECTED_BLOCKS = [
@@ -22,7 +17,7 @@ const RECALL_INJECTED_BLOCKS = [
 const URL_RE = /https?:\/\/\S+/gi;
 
 export class MemoryStore {
-  constructor(private readonly client: GitHubIssueClient, private readonly api: OpenClawPluginApi, private readonly config: ClawMemPluginConfig) {}
+  constructor(private readonly client: GitHubIssueClient) {}
 
   async search(query: string, limit: number): Promise<ParsedMemoryIssue[]> {
     const q = normalizeSearch(query);
@@ -48,17 +43,13 @@ export class MemoryStore {
       }
       if (batch.length < 100) break;
     }
-    for (const memory of await this.listByStatus("all")) {
-      if (memory.kind) kinds.add(memory.kind);
-      for (const topic of memory.topics ?? []) topics.add(topic);
-    }
     return { kinds: [...kinds].sort(), topics: [...topics].sort() };
   }
 
   async get(memoryId: string, status: "active" | "stale" | "all" = "all"): Promise<ParsedMemoryIssue | null> {
     const id = memoryId.trim();
     if (!id) throw new Error("memoryId is empty");
-    return (await this.listByStatus(status)).find((m) => m.memoryId === id || String(m.issueNumber) === id) ?? null;
+    return this.findByRef(id, status);
   }
 
   async listMemories(options: MemoryListOptions = {}): Promise<ParsedMemoryIssue[]> {
@@ -66,22 +57,28 @@ export class MemoryStore {
     const kind = normalizeOptionalLabelValue(options.kind, "kind:");
     const topic = normalizeOptionalLabelValue(options.topic, "topic:");
     const limit = Math.min(200, Math.max(1, options.limit ?? 20));
-    return (await this.listByStatus(status))
-      .filter((memory) => {
-        if (kind && memory.kind !== kind) return false;
-        if (topic && !(memory.topics ?? []).includes(topic)) return false;
-        return true;
-      })
-      .sort((a, b) => b.issueNumber - a.issueNumber)
-      .slice(0, limit);
+    const labels = ["type:memory", ...(kind ? [`kind:${kind}`] : []), ...(topic ? [`topic:${topic}`] : [])];
+    const state = status === "active" ? "open" : "all";
+    const out: ParsedMemoryIssue[] = [];
+    for (let page = 1; page <= 20 && out.length < limit; page++) {
+      const batch = await this.client.listIssues({ labels, state, page, perPage: Math.min(100, limit) });
+      for (const issue of batch) {
+        const memory = this.parseIssue(issue);
+        if (!memory) continue;
+        if (status !== "all" && memory.status !== status) continue;
+        out.push(memory);
+        if (out.length >= limit) break;
+      }
+      if (batch.length < Math.min(100, limit)) break;
+    }
+    return out.sort((a, b) => b.issueNumber - a.issueNumber).slice(0, limit);
   }
 
   async store(draft: MemoryDraft): Promise<{ created: boolean; memory: ParsedMemoryIssue }> {
     const normalized = normalizeDraft(draft);
     const detail = norm(normalized.detail);
-    const allActive = await this.listByStatus("active");
     const hash = sha256(detail);
-    const existing = allActive.find((m) => (m.memoryHash || sha256(norm(m.detail))) === hash);
+    const existing = await this.findActiveByHash(hash);
     if (existing) {
       const memory = await this.mergeSchema(existing, normalized);
       return { created: false, memory };
@@ -123,11 +120,12 @@ export class MemoryStore {
       ? uniqueNormalized(patch.topics.map((topic) => normalizeLabelValue(topic, "topic:")).filter(Boolean) as string[])
       : uniqueNormalized(current.topics ?? []);
     const nextHash = sha256(nextDetail);
-    const duplicate = (await this.listByStatus("active")).find((memory) => {
-      if (memory.issueNumber === current.issueNumber) return false;
-      return (memory.memoryHash || sha256(norm(memory.detail))) === nextHash;
-    });
-    if (duplicate) throw new Error(`another active memory already stores this detail as [${duplicate.memoryId}]`);
+    const duplicate = await this.findActiveByHash(nextHash);
+    if (duplicate?.issueNumber === current.issueNumber) {
+      // Updating schema/title without changing the underlying detail is always safe.
+    } else if (duplicate) {
+      throw new Error(`another active memory already stores this detail as [${duplicate.memoryId}]`);
+    }
     const nextBody = renderMemoryBody(nextDetail, nextHash, current.date);
     const nextLabels = memLabels(nextKind, nextTopics);
     await this.client.ensureLabels(nextLabels);
@@ -153,36 +151,6 @@ export class MemoryStore {
     return { ...mem, status: "stale" };
   }
 
-  async syncFromConversation(session: SessionMirrorState, snapshot: TranscriptSnapshot): Promise<boolean> {
-    try {
-      const decision = await this.generateDecision(session, snapshot);
-      const { savedCount, staledCount } = await this.applyDecision(decision);
-      if (savedCount > 0 || staledCount > 0)
-        this.api.logger.info?.(`clawmem: synced memories for ${session.sessionId} (saved=${savedCount}, stale=${staledCount})`);
-      return true;
-    } catch (error) {
-      this.api.logger.warn(`clawmem: memory capture failed: ${String(error)}`);
-      return false;
-    }
-  }
-
-  private async listByStatus(status: "active" | "stale" | "all"): Promise<ParsedMemoryIssue[]> {
-    const labels = ["type:memory"];
-    const state = status === "active" ? "open" : "all";
-    const out: ParsedMemoryIssue[] = [];
-    for (let page = 1; page <= 20; page++) {
-      const batch = await this.client.listIssues({ labels, state, page, perPage: 100 });
-      for (const issue of batch) {
-        const parsed = this.parseIssue(issue);
-        if (!parsed) continue;
-        if (status !== "all" && parsed.status !== status) continue;
-        out.push(parsed);
-      }
-      if (batch.length < 100) break;
-    }
-    return out;
-  }
-
   private async searchViaBackend(query: string, limit: number): Promise<ParsedMemoryIssue[]> {
     const repo = this.client.repo();
     if (!repo) throw new Error("ClawMem memory recall requires a configured repo.");
@@ -194,6 +162,46 @@ export class MemoryStore {
       .slice(0, limit);
   }
 
+  private async findActiveByHash(hash: string): Promise<ParsedMemoryIssue | null> {
+    const repo = this.client.repo?.();
+    if (!repo) return null;
+    const query = buildMemoryHashSearchQuery(hash, repo);
+    const batch = await this.client.searchIssues(query, { perPage: 10 });
+    return batch
+      .map((issue) => this.parseIssue(issue))
+      .find((memory): memory is ParsedMemoryIssue =>
+        memory !== null && memory.status === "active" && (memory.memoryHash || sha256(norm(memory.detail))) === hash,
+      ) ?? null;
+  }
+
+  private async findByRef(id: string, status: "active" | "stale" | "all"): Promise<ParsedMemoryIssue | null> {
+    const trimmed = id.trim();
+    if (!trimmed) return null;
+    if (/^\d+$/.test(trimmed)) {
+      try {
+        const issue = await this.client.getIssue(Number(trimmed));
+        const parsed = this.parseIssue(issue);
+        if (!parsed) return null;
+        if (status !== "all" && parsed.status !== status) return null;
+        return parsed;
+      } catch {
+        // Fall through to memory-id search for nonstandard repos that expose custom memory ids.
+      }
+    }
+    const repo = this.client.repo?.();
+    if (!repo) return null;
+    const batch = await this.client.searchIssues(buildMemoryRefSearchQuery(trimmed, repo, status), { perPage: 10 });
+    return batch
+      .map((issue) => this.parseIssue(issue))
+      .find((memory): memory is ParsedMemoryIssue =>
+        memory !== null && (status === "all" || memory.status === status) && (memory.memoryId === trimmed || String(memory.issueNumber) === trimmed),
+      ) ?? null;
+  }
+
+  private async findActiveByRef(id: string): Promise<ParsedMemoryIssue | null> {
+    return this.findByRef(id, "active");
+  }
+
   private parseIssue(issue: { number: number; title?: string; body?: string; state?: string; labels?: Array<{ name?: string } | string> }): ParsedMemoryIssue | null {
     const labels = extractLabelNames(issue.labels);
     if (!labels.includes("type:memory")) return null;
@@ -217,103 +225,6 @@ export class MemoryStore {
     };
   }
 
-  private async applyDecision(decision: MemoryDecision): Promise<{ savedCount: number; staledCount: number }> {
-    const allActive = await this.listByStatus("active");
-    const activeById = new Map(allActive.map((m) => [m.memoryId, m]));
-    const activeByHash = new Map(allActive.map((m) => [m.memoryHash || sha256(norm(m.detail)), m]));
-    let savedCount = 0;
-    for (const raw of decision.save) {
-      const draft = normalizeDraft(raw);
-      const detail = norm(draft.detail);
-      if (!detail) continue;
-      const hash = sha256(detail);
-      const existing = activeByHash.get(hash);
-      if (existing) {
-        const merged = await this.mergeSchema(existing, draft);
-        activeByHash.set(hash, merged);
-        continue;
-      }
-      const labels = memLabels(draft.kind, draft.topics);
-      const date = localDate();
-      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, {
-        issueNumber: issue.number,
-        title,
-        memoryId: String(issue.number),
-        memoryHash: hash,
-        date,
-        detail,
-        ...(draft.kind ? { kind: draft.kind } : {}),
-        ...(draft.topics && draft.topics.length > 0 ? { topics: draft.topics } : {}),
-        status: "active",
-      });
-      savedCount++;
-    }
-    let staledCount = 0;
-    for (const id of [...new Set(decision.stale.map((s) => s.trim()).filter(Boolean))]) {
-      const mem = activeById.get(id);
-      if (!mem) continue;
-      await this.client.syncManagedLabels(mem.issueNumber, memLabels(mem.kind, mem.topics));
-      await this.client.updateIssue(mem.issueNumber, { state: "closed" });
-      staledCount++;
-    }
-    return { savedCount, staledCount };
-  }
-
-  private async generateDecision(session: SessionMirrorState, snapshot: TranscriptSnapshot): Promise<MemoryDecision> {
-    if (snapshot.messages.length === 0) return { save: [], stale: [] };
-    const recent = (await this.listByStatus("active")).sort((a, b) => b.issueNumber - a.issueNumber).slice(0, 20);
-    const existingBlock = recent.length === 0 ? "None." : recent.map((m) => {
-      const schema = [m.kind ? `kind=${m.kind}` : "", ...(m.topics ?? []).map((topic) => `topic=${topic}`)].filter(Boolean).join(", ");
-      return `[${m.memoryId}] ${schema ? `${schema} | ` : ""}${m.detail}`;
-    }).join("\n");
-    const schema = await this.listSchema();
-    const schemaBlock = [
-      `Existing kinds: ${schema.kinds.length > 0 ? schema.kinds.join(", ") : "None."}`,
-      `Existing topics: ${schema.topics.length > 0 ? schema.topics.join(", ") : "None."}`,
-    ].join("\n");
-    const subagent = this.api.runtime.subagent;
-    const sessionKey = subKey(session, "memory");
-    const message = [
-      "Extract durable memories from the conversation below.",
-      '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.",
-      "Topics should be short reusable tags, not sentences. Prefer 0-3 topics per memory.",
-      "Do not save temporary requests, startup boilerplate, tool chatter, summaries about internal helper sessions, or one-off operational details.",
-      "Prefer empty arrays when nothing durable should be remembered.",
-      "", "<existing-schema>", schemaBlock, "</existing-schema>",
-      "", "<existing-active-memories>", existingBlock, "</existing-active-memories>",
-      "", "<conversation>", fmtTranscript(snapshot.messages), "</conversation>",
-    ].join("\n");
-    try {
-      const run = await subagent.run({
-        sessionKey,
-        message,
-        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 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");
-      if (wait.status === "error") throw new Error(wait.error || "memory decision 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("memory decision subagent returned no assistant text");
-      return parseDecision(text);
-    } finally {
-      subagent.deleteSession({ sessionKey, deleteTranscript: true }).catch(() => {});
-    }
-  }
-
   private async mergeSchema(memory: ParsedMemoryIssue, draft: MemoryDraft): Promise<ParsedMemoryIssue> {
     const normalized = normalizeDraft(draft);
     const nextKind = normalized.kind ?? memory.kind;
@@ -376,46 +287,23 @@ function normalizeSearch(v: string): string {
   return v.normalize("NFKC").toLowerCase().replace(/\s+/g, " ").trim();
 }
 
-function buildSearchIndex(memory: ParsedMemoryIssue): SearchIndex {
-  return {
-    title: normalizeSearch(memory.title),
-    detail: normalizeSearch(memory.detail),
-    ...(memory.kind ? { kind: normalizeSearch(memory.kind) } : {}),
-    topics: (memory.topics ?? []).map(normalizeSearch).filter(Boolean),
-  };
-}
-
-function searchTokens(v: string): string[] {
-  const seen = new Set<string>();
-  for (const token of v.split(/[^0-9\p{L}]+/u)) {
-    if (token.length > 1) seen.add(token);
-  }
-  for (const chunk of v.match(/[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}]{2,}/gu) ?? []) {
-    for (let i = 0; i < chunk.length; i++) {
-      seen.add(chunk[i]!);
-      if (i + 1 < chunk.length) seen.add(chunk.slice(i, i + 2));
-    }
-  }
-  return [...seen];
-}
-
-function charBigrams(v: string): Set<string> {
-  const compact = v.replace(/\s+/g, "");
-  if (compact.length < 2) return new Set(compact ? [compact] : []);
-  const out = new Set<string>();
-  for (let i = 0; i < compact.length - 1; i++) out.add(compact.slice(i, i + 2));
-  return out;
+function buildMemorySearchQuery(query: string, repo: string): string {
+  const parts = [buildRecallSearchText(query), `repo:${repo}`, "is:issue", "state:open", 'label:"type:memory"'].filter(Boolean);
+  return parts.join(" ");
 }
 
-function overlapRatio(left: Set<string>, right: Set<string>): number {
-  if (left.size === 0 || right.size === 0) return 0;
-  let hits = 0;
-  for (const token of left) if (right.has(token)) hits++;
-  return hits / Math.max(left.size, right.size);
+function buildMemoryHashSearchQuery(hash: string, repo: string): string {
+  const needle = hash.trim();
+  if (!needle) return "";
+  return [`"${needle}"`, `repo:${repo}`, "is:issue", "state:open", 'label:"type:memory"'].join(" ");
 }
 
-function buildMemorySearchQuery(query: string, repo: string): string {
-  const parts = [buildRecallSearchText(query), `repo:${repo}`, "is:issue", "state:open", 'label:"type:memory"'].filter(Boolean);
+function buildMemoryRefSearchQuery(memoryId: string, repo: string, status: "active" | "stale" | "all"): string {
+  const needle = memoryId.trim();
+  if (!needle) return "";
+  const parts = [`"${needle}"`, `repo:${repo}`, "is:issue", 'label:"type:memory"'];
+  if (status === "active") parts.push("state:open");
+  if (status === "stale") parts.push("state:closed");
   return parts.join(" ");
 }
 
@@ -436,42 +324,6 @@ function truncateRecallQuery(text: string, maxLen: number): string {
   return compact.length <= maxLen ? compact : compact.slice(0, maxLen).trimEnd();
 }
 
-export function scoreMemoryMatch(memory: ParsedMemoryIssue, rawQuery: string): number {
-  const query = normalizeSearch(rawQuery);
-  if (!query) return 0;
-  const idx = buildSearchIndex(memory);
-  const tokens = searchTokens(query);
-  const queryTokenSet = new Set(tokens);
-  const titleTokenSet = new Set(searchTokens(idx.title));
-  const detailTokenSet = new Set(searchTokens(idx.detail));
-  const kindTokenSet = new Set(searchTokens(idx.kind ?? ""));
-  const topicTokenSet = new Set(idx.topics.flatMap(searchTokens));
-  let score = 0;
-
-  if (idx.title.includes(query)) score += 18;
-  if (idx.detail.includes(query)) score += 12;
-  if (idx.kind?.includes(query)) score += 8;
-  for (const topic of idx.topics) if (topic.includes(query)) score += 10;
-
-  for (const token of tokens) {
-    if (idx.title.includes(token)) score += 4;
-    if (idx.detail.includes(token)) score += 2;
-    if (idx.kind?.includes(token)) score += 3;
-    if (idx.topics.some((topic) => topic.includes(token))) score += 3;
-  }
-
-  score += overlapRatio(queryTokenSet, titleTokenSet) * 10;
-  score += overlapRatio(queryTokenSet, detailTokenSet) * 6;
-  score += overlapRatio(queryTokenSet, kindTokenSet) * 6;
-  score += overlapRatio(queryTokenSet, topicTokenSet) * 8;
-
-  const queryBigrams = charBigrams(query);
-  score += overlapRatio(queryBigrams, charBigrams(idx.title)) * 6;
-  score += overlapRatio(queryBigrams, charBigrams(idx.detail)) * 3;
-
-  return score;
-}
-
 function normalizeDraft(input: MemoryDraft): MemoryDraft {
   const detail = norm(input.detail);
   if (!detail) throw new Error("memory detail is empty");
@@ -510,42 +362,83 @@ function uniqueNormalized(values: string[]): string[] {
   return [...new Set(values.map((value) => value.trim()).filter(Boolean))].sort();
 }
 
-function parseDecision(raw: string): MemoryDecision {
-  const tryParse = (s: string): MemoryDecision | null => {
+export function parseCandidates(raw: string): MemoryCandidate[] {
+  const tryParse = (s: string): MemoryCandidate[] | null => {
     try {
-      const p = JSON.parse(s) as Record<string, unknown>;
-      return {
-        save: Array.isArray(p.save) ? p.save.map(parseSaveItem).filter((v): v is MemoryDraft => Boolean(v)) : [],
-        stale: Array.isArray(p.stale) ? p.stale.filter((v): v is string => typeof v === "string") : [],
-      };
+      const payload = JSON.parse(s) as Record<string, unknown>;
+      const candidates = Array.isArray(payload.candidates)
+        ? payload.candidates.map(parseCandidateItem).filter((candidate): candidate is MemoryCandidate => Boolean(candidate))
+        : [];
+      return mergeMemoryCandidates([], candidates);
     } catch {
       return null;
     }
   };
-  const t = raw.trim();
-  return tryParse(t) ?? (() => {
-    const f = /^```(?:json)?\s*([\s\S]*?)```$/i.exec(t);
-    const nested = f?.[1] ? tryParse(f[1].trim()) : null;
+  const trimmed = raw.trim();
+  const direct = tryParse(trimmed);
+  if (direct) return direct;
+  const fenced = /^```(?:json)?\s*([\s\S]*?)```$/i.exec(trimmed);
+  if (fenced?.[1]) {
+    const nested = tryParse(fenced[1].trim());
     if (nested) return nested;
-    throw new Error("memory decision subagent returned invalid JSON");
-  })();
+  }
+  throw new Error("finalize memory candidates returned invalid JSON");
 }
 
-function parseSaveItem(value: unknown): MemoryDraft | null {
+function parseCandidateItem(value: unknown): MemoryCandidate | null {
   if (typeof value === "string") {
     const detail = norm(value);
-    return detail ? { detail } : null;
+    return detail ? { candidateId: sha256(detail), detail } : 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 title = typeof record.title === "string" ? record.title : undefined;
   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;
+  const topics = Array.isArray(record.topics) ? record.topics.filter((topic): topic is string => typeof topic === "string") : undefined;
+  const evidence = typeof record.evidence === "string" ? norm(record.evidence) : undefined;
   try {
-    return normalizeDraft({ ...(title ? { title } : {}), detail, ...(kind ? { kind } : {}), ...(topics ? { topics } : {}) });
+    const draft = normalizeDraft({
+      ...(title ? { title } : {}),
+      detail,
+      ...(kind ? { kind } : {}),
+      ...(topics ? { topics } : {}),
+    });
+    return {
+      candidateId: sha256(draft.detail),
+      detail: draft.detail,
+      ...(draft.title ? { title: draft.title } : {}),
+      ...(draft.kind ? { kind: draft.kind } : {}),
+      ...(draft.topics ? { topics: draft.topics } : {}),
+      ...(evidence ? { evidence } : {}),
+    };
   } catch {
     return null;
   }
 }
+
+export function mergeMemoryCandidates(base: MemoryCandidate[], next: MemoryCandidate[]): MemoryCandidate[] {
+  const out = new Map<string, MemoryCandidate>();
+  for (const candidate of [...base, ...next]) {
+    const existing = out.get(candidate.candidateId);
+    if (!existing) {
+      out.set(candidate.candidateId, {
+        ...candidate,
+        ...(candidate.topics ? { topics: uniqueNormalized(candidate.topics) } : {}),
+      });
+      continue;
+    }
+    out.set(candidate.candidateId, {
+      candidateId: candidate.candidateId,
+      detail: candidate.detail || existing.detail,
+      ...(candidate.title || existing.title ? { title: candidate.title || existing.title } : {}),
+      ...(candidate.kind || existing.kind ? { kind: candidate.kind || existing.kind } : {}),
+      ...((candidate.topics || existing.topics)
+        ? { topics: uniqueNormalized([...(existing.topics ?? []), ...(candidate.topics ?? [])]) }
+        : {}),
+      ...(candidate.evidence || existing.evidence ? { evidence: candidate.evidence || existing.evidence } : {}),
+    });
+  }
+  return [...out.values()];
+}

package/src/runtime-env.ts

@@ -0,0 +1,12 @@
+export function getOpenClawAgentIdFromEnv(): string | undefined {
+  const value = process.env.OPENCLAW_AGENT_ID;
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+export function getOpenClawHostVersionFromEnv(): string | undefined {
+  for (const candidate of [process.env.OPENCLAW_VERSION, process.env.OPENCLAW_SERVICE_VERSION]) {
+    const trimmed = candidate?.trim();
+    if (trimmed) return trimmed;
+  }
+  return undefined;
+}

package/src/service.test.ts

@@ -1,5 +1,7 @@
 import {
+  buildClawMemPromptSection,
   buildAutoRecallContext,
+  createClawMemPlugin,
   extractPromptTextForRecall,
   resolveOpenClawHostVersion,
   resolvePromptHookMode,
@@ -75,6 +77,118 @@ function testBuildAutoRecallContext(): void {
   assert(context.includes("- [11] OpenClaw main agent identity uses Gandalf."), "expected memories to be listed as bullets");
 }
 
+function testBuildClawMemPromptSection(): void {
+  const lines = buildClawMemPromptSection({
+    availableTools: new Set([
+      "memory_recall",
+      "memory_list",
+      "memory_get",
+      "memory_repos",
+      "memory_labels",
+      "memory_store",
+      "memory_update",
+      "memory_forget",
+    ]),
+  });
+  const prompt = lines.join("\n");
+
+  assert(lines[0] === "## ClawMem", "expected a stable heading for always-on ClawMem guidance");
+  assert(prompt.includes("active long-term memory system"), "expected the prompt to frame ClawMem as the active memory system");
+  assert(prompt.includes("`memory_recall`, `memory_list`, and `memory_get`"), "expected explicit retrieval guidance");
+  assert(prompt.includes("`memory_store` and `memory_update`"), "expected explicit save guidance");
+  assert(prompt.includes("`memory_forget`"), "expected explicit stale-memory guidance");
+  assert(prompt.includes("Store one durable fact per memory."), "expected one-fact-per-memory guidance");
+  assert(prompt.includes("Skip temporary requests, tool chatter"), "expected anti-noise write guardrails");
+  assert(prompt.includes("explicit short `title` plus a fuller `detail`"), "expected explicit title guidance");
+  assert(prompt.includes("user's current language"), "expected language guidance for new memories");
+  assert(prompt.includes("`memory_labels`"), "expected schema reuse guidance to mention memory_labels");
+  assert(prompt.includes("translated or near-duplicate variant"), "expected anti-duplication schema guidance");
+}
+
+function createFakePluginApi(options?: {
+  slot?: string;
+  exposeCapability?: boolean;
+}) {
+  let registeredCapability: { promptBuilder?: typeof buildClawMemPromptSection } | undefined;
+  let registeredPromptSection: typeof buildClawMemPromptSection | undefined;
+  const api = {
+    id: "clawmem",
+    name: "ClawMem",
+    source: "test",
+    registrationMode: "test",
+    config: {},
+    pluginConfig: {},
+    logger: {
+      info: () => {},
+      warn: () => {},
+    },
+    runtime: {
+      version: "2026.4.9",
+      config: {
+        loadConfig: () => ({
+          plugins: {
+            slots: {
+              memory: options?.slot ?? "clawmem",
+            },
+          },
+        }),
+      },
+      events: {
+        onSessionTranscriptUpdate: () => () => {},
+      },
+      subagent: {},
+    },
+    on: () => {},
+    registerTool: () => {},
+    registerService: () => {},
+    ...(options?.exposeCapability === false
+      ? {}
+      : {
+          registerMemoryCapability: (capability: { promptBuilder?: typeof buildClawMemPromptSection }) => {
+            registeredCapability = capability;
+          },
+        }),
+    registerMemoryPromptSection: (builder: typeof buildClawMemPromptSection) => {
+      registeredPromptSection = builder;
+    },
+  };
+
+  return {
+    api,
+    getRegisteredCapability: () => registeredCapability,
+    getRegisteredPromptSection: () => registeredPromptSection,
+  };
+}
+
+function testRegistersAlwaysOnMemoryPromptCapability(): void {
+  const fake = createFakePluginApi();
+  createClawMemPlugin(fake.api as never);
+
+  const capability = fake.getRegisteredCapability();
+  assert(Boolean(capability?.promptBuilder), "expected ClawMem to register a memory prompt builder");
+  const prompt = capability?.promptBuilder?.({ availableTools: new Set(["memory_recall", "memory_store"]) }).join("\n") ?? "";
+  assert(prompt.includes("## ClawMem"), "expected the registered prompt builder to emit ClawMem guidance");
+}
+
+function testFallsBackToLegacyMemoryPromptSectionRegistration(): void {
+  const fake = createFakePluginApi({ exposeCapability: false });
+  createClawMemPlugin(fake.api as never);
+
+  assert(!fake.getRegisteredCapability(), "expected no memory capability registration when the host lacks that API");
+  const builder = fake.getRegisteredPromptSection();
+  assert(Boolean(builder), "expected fallback registration through registerMemoryPromptSection");
+  const prompt = builder?.({ availableTools: new Set(["memory_recall"]) }).join("\n") ?? "";
+  assert(prompt.includes("## ClawMem"), "expected the fallback builder to emit ClawMem guidance");
+}
+
+function testSkipsAlwaysOnPromptWhenClawMemIsNotSelectedMemoryPlugin(): void {
+  const fake = createFakePluginApi({ slot: "other-memory" });
+  createClawMemPlugin(fake.api as never);
+
+  assert(!fake.getRegisteredCapability(), "expected no memory prompt registration when ClawMem is not the selected memory plugin");
+  assert(!fake.getRegisteredPromptSection(), "expected no legacy prompt registration when ClawMem is not selected");
+}
+
 function testResolveHostVersionFromRuntime(): void {
   const version = resolveOpenClawHostVersion({ runtime: { version: "2026.3.28" } } as never);
   assert(version === "2026.3.28", "expected runtime.version to take precedence");
@@ -139,11 +253,15 @@ testExtractPromptFallsBackToLatestUserMessage();
 testExtractPromptFromPromptField();
 testExtractPromptFromStructuredContent();
 testBuildAutoRecallContext();
+testBuildClawMemPromptSection();
 testResolveHostVersionFromRuntime();
 testResolveHostVersionFromEnvFallback();
 testIgnoresNpmPackageVersionFallback();
 testResolvePromptHookModeModern();
 testResolvePromptHookModeLegacy();
 testResolvePromptHookModeLegacyForUnknownVersion();
+testRegistersAlwaysOnMemoryPromptCapability();
+testFallsBackToLegacyMemoryPromptSectionRegistration();
+testSkipsAlwaysOnPromptWhenClawMemIsNotSelectedMemoryPlugin();
 
 console.log("service tests passed");