@clawmem-ai/clawmem 0.1.12 → 0.1.14

package/src/service.ts

@@ -1,6 +1,7 @@
 // Thin orchestrator: wires conversation mirroring, memory store, and plugin lifecycle.
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
 import { hasDefaultRepo, isAgentConfigured, resolveAgentRoute, resolvePluginConfig } from "./config.js";
+import { filterDirectCollaborators, listRepoAccessTeams, resolveOrgInvitationRole } from "./collaboration.js";
 import { ConversationMirror } from "./conversation.js";
 import { GitHubIssueClient } from "./github-client.js";
 import { KeyedAsyncQueue } from "./keyed-async-queue.js";
@@ -13,15 +14,19 @@ import { buildAgentBootstrapRegistration, inferAgentIdFromTranscriptPath, normal
 type TurnPayload = { sessionId?: string; sessionKey?: string; agentId?: string; messages: unknown[] };
 type FinalizePayload = { sessionId?: string; sessionKey?: string; sessionFile?: string; agentId?: string; reason?: string; messages?: unknown[] };
 type CollaborationPermission = "read" | "write" | "admin";
-type CollaborationOrgRole = "member" | "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;
   private readonly queue = new KeyedAsyncQueue();
   private readonly stateQueue = new KeyedAsyncQueue();
   private readonly pending = new Set<Promise<unknown>>();
   private readonly syncTimers = new Map<string, ReturnType<typeof setTimeout>>();
+  private readonly maintenanceTimers = new Map<string, ReturnType<typeof setTimeout>>();
   private statePath = "";
   private state: PluginState = { version: 2, sessions: {} };
   private unsubTranscript?: () => void;
@@ -33,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" }));
@@ -52,16 +62,19 @@ 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 () => {
         this.unsubTranscript?.();
         for (const t of this.syncTimers.values()) clearTimeout(t);
         this.syncTimers.clear();
+        for (const t of this.maintenanceTimers.values()) clearTimeout(t);
+        this.maintenanceTimers.clear();
         await Promise.allSettled([...this.pending]);
       },
     });
@@ -224,7 +237,7 @@ class ClawMemService {
 
     this.api.registerTool({
       name: "memory_recall",
-      description: "Search ClawMem active memories for relevant prior facts, decisions, conventions, and lessons.",
+      description: "Search ClawMem active memories for relevant prior facts, decisions, conventions, and lessons. Use this before answering questions about prior conversations, earlier assistant responses, user preferences, or historical project context.",
       required: true,
       parameters: {
         type: "object",
@@ -287,12 +300,13 @@ class ClawMemService {
 
     this.api.registerTool({
       name: "memory_store",
-      description: "Store a durable ClawMem memory immediately instead of waiting for session finalization.",
+      description: "Store one atomic durable ClawMem memory immediately instead of waiting for session finalization. Keep each write to a single fact, preference, decision, or timeline update.",
       required: true,
       parameters: {
         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: {
@@ -309,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);
@@ -316,7 +331,12 @@ class ClawMemService {
         if ("error" in resolved) return toolText(resolved.error);
         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({ detail, ...(kind ? { kind } : {}), ...(topics && topics.length > 0 ? { topics } : {}) });
+        const result = await resolved.mem.store({
+          ...(title ? { title } : {}),
+          detail,
+          ...(kind ? { kind } : {}),
+          ...(topics && topics.length > 0 ? { topics } : {}),
+        });
         if (!result.created) return toolText(`Memory already exists in ${resolved.route.repo}.\n${renderMemoryBlock(result.memory)}`);
         return toolText(`Stored memory in ${resolved.route.repo}.\n${renderMemoryBlock(result.memory)}`);
       },
@@ -331,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: {
@@ -349,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)}`);
         }
@@ -1006,7 +1028,7 @@ class ClawMemService {
         properties: {
           org: { type: "string", minLength: 1, description: "Organization login." },
           inviteeLogin: { type: "string", minLength: 1, description: "Username to invite." },
-          role: { type: "string", enum: ["member", "admin"], description: "Org role for the invitation. Defaults to member." },
+          role: { type: "string", enum: ["member", "owner"], description: "Org role for the invitation. Defaults to member." },
           teamIds: {
             type: "array",
             description: "Optional numeric team ids to pre-assign on acceptance.",
@@ -1027,7 +1049,8 @@ class ClawMemService {
         const org = typeof p.org === "string" ? p.org.trim() : "";
         const inviteeLogin = typeof p.inviteeLogin === "string" ? p.inviteeLogin.trim() : "";
         if (!org || !inviteeLogin) return toolText("org and inviteeLogin are required.");
-        const role: CollaborationOrgRole = p.role === "admin" ? "admin" : "member";
+        const role = resolveOrgInvitationRole(p.role, "member");
+        if ("error" in role) return toolText(role.error);
         const teamIds = Array.isArray(p.teamIds)
           ? p.teamIds.filter((value): value is number => typeof value === "number" && Number.isInteger(value) && value > 0)
           : undefined;
@@ -1039,7 +1062,7 @@ class ClawMemService {
         try {
           const invitation = await resolved.client.createOrgInvitation(org, {
             inviteeLogin,
-            role,
+            role: role.role,
             ...(teamIds && teamIds.length > 0 ? { teamIds } : {}),
             ...(expiresInDays ? { expiresInDays } : {}),
           });
@@ -1228,9 +1251,9 @@ class ClawMemService {
           }
 
           try {
-            const collaborators = await target.client.listRepoCollaborators(target.owner, target.repo);
+            const collaborators = filterDirectCollaborators(await target.client.listRepoCollaborators(target.owner, target.repo), target.owner);
             lines.push("");
-            lines.push("Direct collaborators:");
+            lines.push("Explicit collaborators (excluding owner):");
             if (collaborators.length === 0) lines.push("- None visible");
             else lines.push(...collaborators.map((collaborator) => `- ${renderCollaboratorLine(collaborator)}`));
           } catch (error) {
@@ -1247,14 +1270,17 @@ class ClawMemService {
             notes.push(`Repo invitation lookup failed: ${String(error)}`);
           }
 
-          try {
-            const teams = await target.client.listRepoTeams(target.owner, target.repo);
-            lines.push("");
-            lines.push("Teams with repo access:");
-            if (teams.length === 0) lines.push("- None visible");
-            else lines.push(...teams.map((team) => `- ${renderTeamLine(team)}`));
-          } catch (error) {
-            notes.push(`Repo team grant lookup failed: ${String(error)}`);
+          if (orgName) {
+            try {
+              const teamAccess = await listRepoAccessTeams(target.client, orgName, target.fullName);
+              lines.push("");
+              lines.push("Teams with repo access:");
+              if (teamAccess.teams.length === 0) lines.push("- None visible");
+              else lines.push(...teamAccess.teams.map((team) => `- ${renderTeamLine(team)}`));
+              notes.push(...teamAccess.notes);
+            } catch (error) {
+              notes.push(`Repo team grant lookup failed: ${String(error)}`);
+            }
           }
 
           try {
@@ -1280,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;
-    await this.runRequestMaintenance(routeAgentId);
+    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.memoryRecallLimit);
+      const memories = await mem.search(prompt, this.config.memoryAutoRecallLimit);
       if (memories.length === 0) return;
-      const text = memories.map((m) => `- ${m.detail}`).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)}`); }
   }
 
@@ -1357,6 +1397,7 @@ class ClawMemService {
   private async finalize(p: FinalizePayload): Promise<void> {
     if (!p.sessionId) return;
     const agentId = normalizeAgentId(p.agentId);
+    const scopeKey = sessionScopeKey(p.sessionId, agentId);
     if (!(await this.ensureDefaultRepoConfigured(agentId))) return;
     const { conv } = this.getServices(agentId);
     const s = this.getOrCreate(p.sessionId, agentId);
@@ -1375,6 +1416,7 @@ class ClawMemService {
     s.summaryStatus = "pending";
     if (allOk) s.finalizedAt = new Date().toISOString();
     await this.persistState();
+    this.scheduleSessionMaintenance(scopeKey, agentId, { reason: p.reason ?? "finalize" });
   }
 
   // --- Infrastructure ---
@@ -1531,55 +1573,109 @@ class ClawMemService {
       },
     });
   }
-  private async runRequestMaintenance(agentId: string): Promise<void> {
+  private scheduleRecentSessionMaintenance(agentId: string): void {
     const sessions = Object.values(this.state.sessions)
       .filter((session) => normalizeAgentId(session.agentId) === agentId)
       .sort((a, b) => Date.parse(b.updatedAt ?? b.createdAt ?? "") - Date.parse(a.updatedAt ?? a.createdAt ?? ""))
       .slice(0, 8);
-    if (sessions.length === 0) return;
+    for (const session of sessions) {
+      if (!this.sessionNeedsMaintenance(session)) continue;
+      this.scheduleSessionMaintenance(sessionScopeKey(session.sessionId, session.agentId), agentId, {
+        reason: "request-start-fallback",
+        delayMs: 0,
+      });
+      break;
+    }
+  }
+
+  private scheduleSessionMaintenance(
+    scopeKey: string,
+    agentId: string,
+    options: { delayMs?: number; attempt?: number; reason?: string } = {},
+  ): void {
+    const prev = this.maintenanceTimers.get(scopeKey);
+    if (prev) clearTimeout(prev);
+    const delayMs = Math.max(0, options.delayMs ?? 0);
+    const attempt = Math.max(0, options.attempt ?? 0);
+    const reason = options.reason ?? "scheduled";
+    const timer = setTimeout(() => {
+      this.maintenanceTimers.delete(scopeKey);
+      void this.track(this.enqueueSession(scopeKey, () => this.runSessionMaintenance(scopeKey, agentId, attempt, reason)))
+        .catch((error) => this.warn(`background maintenance for ${scopeKey}`, error));
+    }, delayMs);
+    timer.unref?.();
+    this.maintenanceTimers.set(scopeKey, timer);
+  }
+
+  private async runSessionMaintenance(scopeKey: string, agentId: string, attempt: number, reason: string): Promise<void> {
+    const session = this.state.sessions[scopeKey];
+    if (!session || !this.sessionNeedsMaintenance(session)) return;
+    if (!(await this.ensureDefaultRepoConfigured(agentId))) return;
     const { conv, mem } = this.getServices(agentId);
+    const snap = await conv.loadSnapshot(session, []);
+    if (!conv.shouldMirror(session.sessionId, snap.messages) || snap.messages.length === 0) return;
     let changed = false;
-    let workDone = 0;
-    for (const session of sessions) {
-      if (workDone >= 3) break;
-      const snap = await conv.loadSnapshot(session, []);
-      if (!conv.shouldMirror(session.sessionId, snap.messages) || snap.messages.length === 0) continue;
-      if (!session.issueNumber) {
-        await conv.ensureIssue(session, snap);
-        changed = true;
-      }
-      if (session.summaryStatus === "pending") {
-        try {
-          const result = await conv.generateSummaryAndTitle(session, snap);
-          await conv.syncLabels(session, snap, true);
-          await conv.syncBody(session, snap, result.summary, true, result.title);
-          session.summaryStatus = "complete";
-          if (result.title?.trim()) {
-            session.issueTitle = result.title.trim();
-            session.titleSource = "llm";
-          }
-          this.maybeAutoNameRepo(agentId, result.summary, result.title);
-          changed = true;
-          workDone++;
-        } catch (error) {
-          this.warn(`request-scoped summary sync for ${session.sessionId}`, error);
+    let retryNeeded = false;
+    if (!session.issueNumber) {
+      await conv.ensureIssue(session, snap);
+      changed = true;
+    }
+    if (session.summaryStatus === "pending") {
+      try {
+        const result = await conv.generateSummaryAndTitle(session, snap);
+        await conv.syncLabels(session, snap, true);
+        await conv.syncBody(session, snap, result.summary, true, result.title);
+        session.summaryStatus = "complete";
+        if (result.title?.trim()) {
+          session.issueTitle = result.title.trim();
+          session.titleSource = "llm";
         }
+        this.maybeAutoNameRepo(agentId, result.summary, result.title);
+        changed = true;
+      } catch (error) {
+        retryNeeded = true;
+        this.warn(`background summary sync for ${session.sessionId}`, error);
       }
-      if (session.titleSource !== "llm" && snap.messages.length >= 2) {
+    }
+    if (session.titleSource !== "llm" && snap.messages.length >= 2) {
+      try {
         await conv.syncTitle(session, snap);
         changed = true;
-        workDone++;
+      } catch (error) {
+        retryNeeded = true;
+        this.warn(`background title sync for ${session.sessionId}`, error);
       }
-      if (snap.messages.length >= 2 && snap.messages.length > (session.lastMemorySyncCount ?? 0)) {
-        const ok = await mem.syncFromConversation(session, snap);
-        if (ok) {
-          session.lastMemorySyncCount = snap.messages.length;
-          changed = true;
-        }
-        workDone++;
+    }
+    if (snap.messages.length >= 2 && snap.messages.length > (session.lastMemorySyncCount ?? 0)) {
+      const ok = await mem.syncFromConversation(session, snap);
+      if (ok) {
+        session.lastMemorySyncCount = snap.messages.length;
+        changed = true;
+      } else {
+        retryNeeded = true;
       }
     }
     if (changed) await this.persistState();
+    if (!retryNeeded || !this.sessionNeedsMaintenance(session)) return;
+    if (attempt < SESSION_MAINTENANCE_RETRY_DELAYS_MS.length) {
+      const delayMs = SESSION_MAINTENANCE_RETRY_DELAYS_MS[attempt];
+      this.api.logger.warn?.(
+        `clawmem: background maintenance incomplete for ${session.sessionId}; retrying in ${Math.round(delayMs / 1000)}s (${reason})`,
+      );
+      this.scheduleSessionMaintenance(scopeKey, agentId, { delayMs, attempt: attempt + 1, reason: "retry" });
+      return;
+    }
+    this.api.logger.warn?.(
+      `clawmem: background maintenance remains pending for ${session.sessionId}; it will be retried opportunistically on future requests`,
+    );
+  }
+
+  private sessionNeedsMaintenance(session: SessionMirrorState): boolean {
+    if (session.summaryStatus === "pending") return true;
+    const hasMeaningfulTranscript = Math.max(session.lastMirroredCount, session.turnCount) >= 2;
+    if (!hasMeaningfulTranscript) return false;
+    if (session.titleSource !== "llm") return true;
+    return (session.lastMemorySyncCount ?? 0) < session.lastMirroredCount;
   }
 
   private getServices(agentId?: string, repo?: string): { route: ClawMemResolvedRoute; conv: ConversationMirror; mem: MemoryStore; client: GitHubIssueClient } {
@@ -1706,11 +1802,30 @@ function shouldFallbackToAnonymousBootstrap(error: unknown): boolean {
 function toolText(text: string): { content: Array<{ type: "text"; text: string }> } {
   return { content: [{ type: "text", text }] };
 }
-function renderMemoryLine(memory: { memoryId: string; title?: string; detail: string; kind?: string; topics?: string[]; status: "active" | "stale" }): string {
-  const schema = [memory.kind ? `kind:${memory.kind}` : "", ...(memory.topics ?? []).map((topic) => `topic:${topic}`)].filter(Boolean).join(", ");
+function renderMemoryLine(memory: {
+  memoryId: string;
+  title?: string;
+  detail: string;
+  kind?: string;
+  topics?: string[];
+  status: "active" | "stale";
+}): string {
+  const schema = [
+    memory.kind ? `kind:${memory.kind}` : "",
+    ...(memory.topics ?? []).map((topic) => `topic:${topic}`),
+  ].filter(Boolean).join(", ");
   return `[${memory.memoryId}] ${memory.title || "Memory"}${schema ? ` (${schema})` : ""}${memory.status === "stale" ? " [stale]" : ""}: ${memory.detail}`;
 }
-function renderMemoryBlock(memory: { memoryId: string; issueNumber?: number; title?: string; detail: string; kind?: string; topics?: string[]; status: "active" | "stale"; date?: string }): string {
+function renderMemoryBlock(memory: {
+  memoryId: string;
+  issueNumber?: number;
+  title?: string;
+  detail: string;
+  kind?: string;
+  topics?: string[];
+  status: "active" | "stale";
+  date?: string;
+}): string {
   const lines = [
     `Memory ID: ${memory.memoryId}`,
     ...(typeof memory.issueNumber === "number" ? [`Issue Number: ${memory.issueNumber}`] : []),
@@ -1724,6 +1839,170 @@ function renderMemoryBlock(memory: { memoryId: string; issueNumber?: number; tit
   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

@@ -15,6 +15,7 @@ export type ClawMemPluginConfig = {
   authScheme: "token" | "bearer";
   agents: Record<string, ClawMemAgentConfig>;
   memoryRecallLimit: number;
+  memoryAutoRecallLimit: number;
   turnCommentDelayMs: number;
   summaryWaitTimeoutMs: number;
 };
@@ -43,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";