@memtensor/memos-local-openclaw-plugin 0.1.3 → 0.1.5

package/index.ts

@@ -7,6 +7,8 @@
 
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
 import { Type } from "@sinclair/typebox";
+import * as fs from "fs";
+import * as path from "path";
 import { buildContext } from "./src/config";
 import { SqliteStore } from "./src/storage/sqlite";
 import { Embedder } from "./src/embedding";
@@ -15,31 +17,40 @@ import { RecallEngine } from "./src/recall/engine";
 import { captureMessages } from "./src/capture";
 import { DEFAULTS } from "./src/types";
 import { ViewerServer } from "./src/viewer/server";
+import { SkillEvolver } from "./src/skill/evolver";
+import { SkillInstaller } from "./src/skill/installer";
+import { Summarizer } from "./src/ingest/providers";
+import { MEMORY_GUIDE_SKILL_MD } from "./src/skill/bundled-memory-guide";
+
+
+/** Remove near-duplicate hits based on summary word overlap (>70%). Keeps first (highest-scored) hit. */
+function deduplicateHits<T extends { summary: string }>(hits: T[]): T[] {
+  const kept: T[] = [];
+  for (const hit of hits) {
+    const dominated = kept.some((k) => {
+      const a = k.summary.toLowerCase();
+      const b = hit.summary.toLowerCase();
+      if (a === b) return true;
+      const wordsA = new Set(a.split(/\s+/).filter(w => w.length > 1));
+      const wordsB = new Set(b.split(/\s+/).filter(w => w.length > 1));
+      if (wordsA.size === 0 || wordsB.size === 0) return false;
+      let overlap = 0;
+      for (const w of wordsB) { if (wordsA.has(w)) overlap++; }
+      return overlap / Math.min(wordsA.size, wordsB.size) > 0.7;
+    });
+    if (!dominated) kept.push(hit);
+  }
+  return kept;
+}
 
 const pluginConfigSchema = {
   type: "object" as const,
   additionalProperties: true,
   properties: {
-    embedding: {
-      type: "object" as const,
-      properties: {
-        provider: { type: "string" as const },
-        endpoint: { type: "string" as const },
-        apiKey: { type: "string" as const },
-        model: { type: "string" as const },
-      },
+    viewerPort: {
+      type: "number" as const,
+      description: "Memory Viewer HTTP port (default 18799)",
     },
-    summarizer: {
-      type: "object" as const,
-      properties: {
-        provider: { type: "string" as const },
-        endpoint: { type: "string" as const },
-        apiKey: { type: "string" as const },
-        model: { type: "string" as const },
-        temperature: { type: "number" as const },
-      },
-    },
-    viewerPort: { type: "number" as const },
   },
 };
 
@@ -48,7 +59,7 @@ const memosLocalPlugin = {
   name: "MemOS Local Memory",
   description:
     "Full-write local conversation memory with hybrid search (RRF + MMR + recency). " +
-    "Provides memory_search, memory_timeline, memory_get for progressive recall.",
+    "Provides memory_search, memory_get, task_summary, memory_timeline, memory_viewer for layered retrieval.",
   kind: "memory" as const,
   configSchema: pluginConfigSchema,
 
@@ -68,8 +79,61 @@ const memosLocalPlugin = {
     const engine = new RecallEngine(store, embedder, ctx);
     const evidenceTag = ctx.config.capture?.evidenceWrapperTag ?? DEFAULTS.evidenceWrapperTag;
 
+    const workspaceDir = api.resolvePath("~/.openclaw/workspace");
+    const skillCtx = { ...ctx, workspaceDir };
+    const skillEvolver = new SkillEvolver(store, engine, skillCtx);
+    const skillInstaller = new SkillInstaller(store, skillCtx);
+
+    // Install bundled memory-guide skill so OpenClaw loads it (write from embedded content so it works regardless of deploy layout)
+    const workspaceSkillsDir = path.join(workspaceDir, "skills");
+    const memosGuideDest = path.join(workspaceSkillsDir, "memos-memory-guide");
+    fs.mkdirSync(memosGuideDest, { recursive: true });
+    fs.writeFileSync(path.join(memosGuideDest, "SKILL.md"), MEMORY_GUIDE_SKILL_MD, "utf-8");
+    ctx.log.info(`memos-local: installed bundled skill memos-memory-guide → ${memosGuideDest}`);
+
+    // Also ensure managed skills dir has it so dashboard/other loaders can see it
+    const managedSkillsDir = path.join(stateDir, "skills");
+    const managedMemosGuide = path.join(managedSkillsDir, "memos-memory-guide");
+    try {
+      fs.mkdirSync(managedMemosGuide, { recursive: true });
+      fs.writeFileSync(path.join(managedMemosGuide, "SKILL.md"), MEMORY_GUIDE_SKILL_MD, "utf-8");
+      ctx.log.info(`memos-local: installed bundled skill memos-memory-guide → ${managedMemosGuide} (managed)`);
+    } catch (e) {
+      ctx.log.warn(`memos-local: could not write to managed skills dir: ${e}`);
+    }
+
+    worker.getTaskProcessor().onTaskCompleted((task) => {
+      skillEvolver.onTaskCompleted(task).catch((err) => {
+        ctx.log.warn(`SkillEvolver async error: ${err}`);
+      });
+    });
+
+    const summarizer = new Summarizer(ctx.config.summarizer, ctx.log);
+
     api.logger.info(`memos-local: initialized (db: ${ctx.config.storage!.dbPath})`);
 
+    const trackTool = (toolName: string, fn: (...args: any[]) => Promise<any>) =>
+      async (...args: any[]) => {
+        const t0 = performance.now();
+        let ok = true;
+        let result: any;
+        const inputParams = args.length > 1 ? args[1] : args[0];
+        try {
+          result = await fn(...args);
+          return result;
+        } catch (e) {
+          ok = false;
+          throw e;
+        } finally {
+          const dur = performance.now() - t0;
+          store.recordToolCall(toolName, dur, ok);
+          try {
+            const outputText = result?.content?.[0]?.text ?? JSON.stringify(result ?? "");
+            store.recordApiLog(toolName, inputParams, outputText, dur, ok);
+          } catch (_) { /* best-effort */ }
+        }
+      };
+
     // ─── Tool: memory_search ───
 
     api.registerTool(
@@ -77,21 +141,27 @@ const memosLocalPlugin = {
         name: "memory_search",
         label: "Memory Search",
         description:
-          "Search stored conversation memories. Returns summary, original_excerpt (evidence), score, and ref. " +
-          "Default: top 6, minScore 0.45. Increase maxResults to 12/20 or lower minScore to 0.35 if needed.",
+          "Search long-term conversation memory for past conversations, user preferences, decisions, and experiences. " +
+          "Relevant memories are automatically injected at the start of each turn, but call this tool when you need " +
+          "to search with a different query, narrow by role, or the auto-recalled context is insufficient.\n\n" +
+          "Use role='user' to find what the user actually said.",
         parameters: Type.Object({
           query: Type.String({ description: "Natural language search query" }),
-          maxResults: Type.Optional(Type.Number({ description: "Max results (default 6, max 20)" })),
+          maxResults: Type.Optional(Type.Number({ description: "Max results (default 20, max 20)" })),
           minScore: Type.Optional(Type.Number({ description: "Min score 0-1 (default 0.45, floor 0.35)" })),
+          role: Type.Optional(Type.String({ description: "Filter by role: 'user', 'assistant', or 'tool'. Use 'user' to find what the user said." })),
         }),
-        async execute(_toolCallId, params) {
-          const { query, maxResults, minScore } = params as {
+        execute: trackTool("memory_search", async (_toolCallId: any, params: any) => {
+          const { query, minScore, role } = params as {
             query: string;
             maxResults?: number;
             minScore?: number;
+            role?: string;
           };
 
-          const result = await engine.search({ query, maxResults, minScore });
+          ctx.log.debug(`memory_search query="${query}" minScore=${minScore ?? 0.45} role=${role ?? "all"}`);
+          const result = await engine.search({ query, maxResults: 20, minScore, role });
+          ctx.log.debug(`memory_search raw candidates: ${result.hits.length}`);
 
           if (result.hits.length === 0) {
             return {
@@ -100,35 +170,104 @@ const memosLocalPlugin = {
             };
           }
 
-          const roleLabel = (r: string) => r === "user" ? "[USER said]" : r === "assistant" ? "[ASSISTANT replied]" : r === "tool" ? "[TOOL returned]" : `[${r.toUpperCase()}]`;
+          // LLM relevance + sufficiency filtering
+          let filteredHits = result.hits;
+          let sufficient = false;
+
+          const candidates = result.hits.map((h, i) => ({
+            index: i + 1,
+            summary: h.summary,
+            role: h.source.role,
+          }));
+
+          const filterResult = await summarizer.filterRelevant(query, candidates);
+          if (filterResult !== null) {
+            sufficient = filterResult.sufficient;
+            if (filterResult.relevant.length > 0) {
+              const indexSet = new Set(filterResult.relevant);
+              filteredHits = result.hits.filter((_, i) => indexSet.has(i + 1));
+              ctx.log.debug(`memory_search LLM filter: ${result.hits.length} → ${filteredHits.length} hits, sufficient=${sufficient}`);
+            } else {
+              return {
+                content: [{ type: "text", text: "No relevant memories found for this query." }],
+                details: { meta: result.meta },
+              };
+            }
+          }
+
+          if (filteredHits.length === 0) {
+            return {
+              content: [{ type: "text", text: "No relevant memories found for this query." }],
+              details: { meta: result.meta },
+            };
+          }
+
+          const beforeDedup = filteredHits.length;
+          filteredHits = deduplicateHits(filteredHits);
+          ctx.log.debug(`memory_search dedup: ${beforeDedup} → ${filteredHits.length}`);
+
+          const lines = filteredHits.map((h, i) => {
+            const excerpt = h.original_excerpt.length > 300
+              ? h.original_excerpt.slice(0, 297) + "..."
+              : h.original_excerpt;
+            const parts = [`${i + 1}. [${h.source.role}]`];
+            if (excerpt) parts.push(`   ${excerpt}`);
+            parts.push(`   chunkId="${h.ref.chunkId}"`);
+            if (h.taskId) {
+              const task = store.getTask(h.taskId);
+              if (task && task.status !== "skipped") {
+                parts.push(`   task_id="${h.taskId}"`);
+              }
+            }
+            return parts.join("\n");
+          });
 
-          const text = result.hits
-            .map(
-              (h, i) =>
-                `${i + 1}. ${roleLabel(h.source.role)} [score=${h.score}] ${h.summary}\n   Evidence: ${h.original_excerpt.slice(0, 200)}`,
-            )
-            .join("\n\n");
+          let tipsText = "";
+          if (!sufficient) {
+            const hasTask = filteredHits.some((h) => {
+              if (!h.taskId) return false;
+              const t = store.getTask(h.taskId);
+              return t && t.status !== "skipped";
+            });
+
+            const tips: string[] = [];
+            if (hasTask) {
+              tips.push("→ call task_summary(taskId) for full task context");
+              tips.push("→ call skill_get(taskId=...) if the task has a proven experience guide");
+            }
+            tips.push("→ call memory_timeline(chunkId) to expand surrounding conversation");
+
+            if (tips.length > 0) {
+              tipsText = "\n\nThese memories may not be enough. You can fetch more context:\n" + tips.join("\n");
+            }
+          }
 
           return {
             content: [
               {
                 type: "text",
-                text: `Found ${result.hits.length} memories (minScore=${result.meta.usedMinScore}):\n\n${text}`,
+                text: `Found ${filteredHits.length} relevant memories:\n\n${lines.join("\n\n")}${tipsText}`,
               },
             ],
             details: {
-              hits: result.hits.map((h) => ({
-                role: h.source.role,
-                summary: h.summary,
-                original_excerpt: h.original_excerpt,
-                ref: h.ref,
-                score: h.score,
-                source: h.source,
-              })),
+              hits: filteredHits.map((h) => {
+                let effectiveTaskId = h.taskId;
+                if (effectiveTaskId) {
+                  const t = store.getTask(effectiveTaskId);
+                  if (t && t.status === "skipped") effectiveTaskId = null;
+                }
+                return {
+                  chunkId: h.ref.chunkId,
+                  taskId: effectiveTaskId,
+                  skillId: h.skillId,
+                  role: h.source.role,
+                  score: h.score,
+                };
+              }),
               meta: result.meta,
             },
           };
-        },
+        }),
       },
       { name: "memory_search" },
     );
@@ -140,26 +279,29 @@ const memosLocalPlugin = {
         name: "memory_timeline",
         label: "Memory Timeline",
         description:
-          "Get neighboring context around a memory ref. Use after memory_search to expand context.",
+          "Expand context around a memory search hit. Pass the chunkId from a search result " +
+          "to read the surrounding conversation messages.",
         parameters: Type.Object({
-          sessionKey: Type.String({ description: "From search hit ref.sessionKey" }),
-          chunkId: Type.String({ description: "From search hit ref.chunkId" }),
-          turnId: Type.String({ description: "From search hit ref.turnId" }),
-          seq: Type.Number({ description: "From search hit ref.seq" }),
+          chunkId: Type.String({ description: "The chunkId from a memory_search hit" }),
           window: Type.Optional(Type.Number({ description: "Context window ±N (default 2)" })),
         }),
-        async execute(_toolCallId, params) {
-          const { sessionKey, chunkId, turnId, seq, window: win } = params as {
-            sessionKey: string;
+        execute: trackTool("memory_timeline", async (_toolCallId: any, params: any) => {
+          ctx.log.debug(`memory_timeline called`);
+          const { chunkId, window: win } = params as {
             chunkId: string;
-            turnId: string;
-            seq: number;
             window?: number;
           };
 
-          const w = win ?? DEFAULTS.timelineWindowDefault;
-          const neighbors = store.getNeighborChunks(sessionKey, turnId, seq, w);
           const anchorChunk = store.getChunk(chunkId);
+          if (!anchorChunk) {
+            return {
+              content: [{ type: "text", text: `Chunk not found: ${chunkId}` }],
+              details: { error: "not_found" },
+            };
+          }
+
+          const w = win ?? DEFAULTS.timelineWindowDefault;
+          const neighbors = store.getNeighborChunks(anchorChunk.sessionKey, anchorChunk.turnId, anchorChunk.seq, w);
           const anchorTs = anchorChunk?.createdAt ?? 0;
 
           const entries = neighbors.map((chunk) => {
@@ -184,53 +326,189 @@ const memosLocalPlugin = {
             content: [{ type: "text", text: `Timeline (${entries.length} entries):\n\n${text}` }],
             details: { entries, anchorRef: { sessionKey, chunkId, turnId, seq } },
           };
-        },
+        }),
       },
       { name: "memory_timeline" },
     );
 
-    // ─── Tool: memory_get ───
+    // memory_get removed — search results are pre-filtered by LLM for relevance;
+    // agents use task_summary for broader context and skill_get for experience guides.
+
+    // ─── Tool: task_summary ───
 
     api.registerTool(
       {
-        name: "memory_get",
-        label: "Memory Get",
+        name: "task_summary",
+        label: "Task Summary",
         description:
-          "Get full original text of a memory chunk. Use to verify exact details from a search hit.",
+          "Get the detailed summary of a complete task. Use this when memory_search returns a hit " +
+          "with a task_id and you need the full context of that task. The summary preserves all " +
+          "critical information: URLs, file paths, commands, error codes, step-by-step instructions.",
         parameters: Type.Object({
-          chunkId: Type.String({ description: "From search hit ref.chunkId" }),
-          maxChars: Type.Optional(
-            Type.Number({ description: `Max chars (default ${DEFAULTS.getMaxCharsDefault}, max ${DEFAULTS.getMaxCharsMax})` }),
-          ),
+          taskId: Type.String({ description: "The task_id from a memory_search hit" }),
         }),
-        async execute(_toolCallId, params) {
-          const { chunkId, maxChars } = params as { chunkId: string; maxChars?: number };
-          const limit = Math.min(maxChars ?? DEFAULTS.getMaxCharsDefault, DEFAULTS.getMaxCharsMax);
+        execute: trackTool("task_summary", async (_toolCallId: any, params: any) => {
+          const { taskId } = params as { taskId: string };
+          ctx.log.debug(`task_summary called for task=${taskId}`);
 
-          const chunk = store.getChunk(chunkId);
-          if (!chunk) {
+          const task = store.getTask(taskId);
+          if (!task) {
             return {
-              content: [{ type: "text", text: `Chunk not found: ${chunkId}` }],
+              content: [{ type: "text", text: `Task not found: ${taskId}` }],
               details: { error: "not_found" },
             };
           }
 
-          const content = chunk.content.length > limit
-            ? chunk.content.slice(0, limit) + "…"
-            : chunk.content;
+          if (task.status === "skipped") {
+            return {
+              content: [{ type: "text", text: `Task "${task.title}" was too brief to generate a summary. Reason: ${task.summary || "conversation too short"}. Use memory_get to read individual chunks instead.` }],
+              details: { taskId, status: task.status },
+            };
+          }
 
-          const who = chunk.role === "user" ? "USER said" : chunk.role === "assistant" ? "ASSISTANT replied" : chunk.role === "tool" ? "TOOL returned" : chunk.role.toUpperCase();
+          if (!task.summary) {
+            const chunks = store.getChunksByTask(taskId);
+            if (chunks.length === 0) {
+              return {
+                content: [{ type: "text", text: `Task ${taskId} has no content yet.` }],
+                details: { taskId, status: task.status },
+              };
+            }
+            return {
+              content: [{
+                type: "text",
+                text: `Task "${task.title}" is still active (summary not yet generated). ` +
+                  `It contains ${chunks.length} memory chunks. Use memory_get to read individual chunks.`,
+              }],
+              details: { taskId, status: task.status, chunkCount: chunks.length },
+            };
+          }
+
+          const relatedSkills = store.getSkillsByTask(taskId);
+          let skillSection = "";
+          if (relatedSkills.length > 0) {
+            const skillLines = relatedSkills.map(rs =>
+              `- 🔧 ${rs.skill.name} (${rs.relation}, v${rs.versionAt}) — call skill_get(skillId="${rs.skill.id}") or skill_get(taskId="${taskId}") to get the full guide`
+            );
+            skillSection = `\n\n### Related Skills\n${skillLines.join("\n")}`;
+          }
 
           return {
-            content: [{ type: "text", text: `[${who}] (session: ${chunk.sessionKey})\n\n${content}` }],
+            content: [{
+              type: "text",
+              text: `## Task: ${task.title}\n\nStatus: ${task.status}\nChunks: ${store.getChunksByTask(taskId).length}\n\n${task.summary}${skillSection}`,
+            }],
             details: {
-              ref: { sessionKey: chunk.sessionKey, chunkId: chunk.id, turnId: chunk.turnId, seq: chunk.seq },
-              source: { ts: chunk.createdAt, role: chunk.role, sessionKey: chunk.sessionKey },
+              taskId: task.id,
+              title: task.title,
+              status: task.status,
+              startedAt: task.startedAt,
+              endedAt: task.endedAt,
+              relatedSkills: relatedSkills.map(rs => ({ skillId: rs.skill.id, name: rs.skill.name, relation: rs.relation })),
             },
           };
-        },
+        }),
       },
-      { name: "memory_get" },
+      { name: "task_summary" },
+    );
+
+    // ─── Tool: skill_get ───
+
+    api.registerTool(
+      {
+        name: "skill_get",
+        label: "Get Skill",
+        description:
+          "Retrieve a proven skill (experience guide) by skillId or taskId. " +
+          "Pass either one — if you have a task_id from memory_search, pass taskId and the system " +
+          "will find the associated skill automatically.",
+        parameters: Type.Object({
+          skillId: Type.Optional(Type.String({ description: "Direct skill ID" })),
+          taskId: Type.Optional(Type.String({ description: "Task ID — will look up the skill linked to this task" })),
+        }),
+        execute: trackTool("skill_get", async (_toolCallId: any, params: any) => {
+          const { skillId: directSkillId, taskId } = params as { skillId?: string; taskId?: string };
+
+          let resolvedSkillId = directSkillId;
+          if (!resolvedSkillId && taskId) {
+            const linked = store.getSkillsByTask(taskId);
+            if (linked.length > 0) {
+              resolvedSkillId = linked[0].skill.id;
+            } else {
+              return {
+                content: [{ type: "text", text: `No skill associated with task ${taskId}.` }],
+                details: { error: "no_skill_for_task", taskId },
+              };
+            }
+          }
+
+          if (!resolvedSkillId) {
+            return {
+              content: [{ type: "text", text: "Provide either skillId or taskId." }],
+              details: { error: "missing_params" },
+            };
+          }
+
+          ctx.log.debug(`skill_get resolved skill=${resolvedSkillId} (from ${directSkillId ? "skillId" : "taskId=" + taskId})`);
+
+          const skill = store.getSkill(resolvedSkillId);
+          if (!skill) {
+            return {
+              content: [{ type: "text", text: `Skill not found: ${resolvedSkillId}` }],
+              details: { error: "not_found" },
+            };
+          }
+
+          const sv = store.getLatestSkillVersion(resolvedSkillId);
+          if (!sv) {
+            return {
+              content: [{ type: "text", text: `Skill "${skill.name}" has no content versions.` }],
+              details: { skillId: resolvedSkillId, name: skill.name, error: "no_version" },
+            };
+          }
+
+          return {
+            content: [{
+              type: "text",
+              text: `## Skill: ${skill.name} (v${skill.version})\n\n${sv.content}\n\n---\nTo install this skill for persistent use: call skill_install(skillId="${resolvedSkillId}")`,
+            }],
+            details: {
+              skillId: skill.id,
+              name: skill.name,
+              version: skill.version,
+              status: skill.status,
+              installed: skill.installed,
+            },
+          };
+        }),
+      },
+      { name: "skill_get" },
+    );
+
+    // ─── Tool: skill_install ───
+
+    api.registerTool(
+      {
+        name: "skill_install",
+        label: "Install Skill",
+        description:
+          "Install a learned skill into the agent workspace so it becomes permanently available. " +
+          "After installation, the skill will be loaded automatically in future sessions.",
+        parameters: Type.Object({
+          skillId: Type.String({ description: "The skill_id to install" }),
+        }),
+        execute: trackTool("skill_install", async (_toolCallId: any, params: any) => {
+          const { skillId } = params as { skillId: string };
+          ctx.log.debug(`skill_install called for skill=${skillId}`);
+
+          const result = skillInstaller.install(skillId);
+          return {
+            content: [{ type: "text", text: result.message }],
+            details: result,
+          };
+        }),
+      },
+      { name: "skill_install" },
     );
 
     // ─── Tool: memory_viewer ───
@@ -242,9 +520,12 @@ const memosLocalPlugin = {
         name: "memory_viewer",
         label: "Open Memory Viewer",
         description:
-          "Open the MemOS Memory Viewer web dashboard. Returns the URL the user can open in their browser to visually browse, search, and manage all stored memories.",
+          "Show the MemOS Memory Viewer URL. Call this when the user asks how to view, browse, manage, " +
+          "or access their stored memories, or asks where the memory dashboard is. " +
+          "Returns the URL the user can open in their browser.",
         parameters: Type.Object({}),
-        async execute() {
+        execute: trackTool("memory_viewer", async () => {
+          ctx.log.debug(`memory_viewer called`);
           const url = `http://127.0.0.1:${viewerPort}`;
           return {
             content: [
@@ -265,19 +546,171 @@ const memosLocalPlugin = {
             ],
             details: { viewerUrl: url },
           };
-        },
+        }),
       },
       { name: "memory_viewer" },
     );
 
+    // ─── Auto-recall: inject relevant memories before agent starts ───
+
+    api.on("before_agent_start", async (event: { prompt?: string; messages?: unknown[] }) => {
+      if (!event.prompt || event.prompt.length < 3) return;
+
+      const recallT0 = performance.now();
+      let recallQuery = "";
+
+      try {
+        const rawPrompt = event.prompt;
+        ctx.log.debug(`auto-recall: rawPrompt="${rawPrompt.slice(0, 300)}"`);
+
+        let query = rawPrompt;
+        const lastDoubleNewline = rawPrompt.lastIndexOf("\n\n");
+        if (lastDoubleNewline > 0 && lastDoubleNewline < rawPrompt.length - 3) {
+          const tail = rawPrompt.slice(lastDoubleNewline + 2).trim();
+          if (tail.length >= 2) query = tail;
+        }
+        query = query.replace(/^\[.*?\]\s*/, "");
+        query = query.replace(/<[^>]+>/g, "").trim();
+        recallQuery = query;
+
+        if (query.length < 2) {
+          ctx.log.debug("auto-recall: extracted query too short, skipping");
+          return;
+        }
+        ctx.log.debug(`auto-recall: query="${query.slice(0, 80)}"`);
+
+        const result = await engine.search({ query, maxResults: 20, minScore: 0.45 });
+        if (result.hits.length === 0) {
+          ctx.log.debug("auto-recall: no candidates found");
+          const dur = performance.now() - recallT0;
+          store.recordToolCall("memory_search", dur, true);
+          store.recordApiLog("memory_search", { query }, "no hits", dur, true);
+          const noRecallHint =
+            "## Memory system\n\nNo memories were automatically recalled for this turn (e.g. the user's message was long, vague, or no matching history). " +
+            "You may still have relevant past context — call the **memory_search** tool with a **short, focused query** you generate yourself " +
+            "(e.g. key topics, names, or a rephrased question) to search the user's conversation history.";
+          return { systemPrompt: noRecallHint };
+        }
+
+        const candidates = result.hits.map((h, i) => ({
+          index: i + 1,
+          summary: h.summary,
+          role: h.source.role,
+        }));
+
+        let filteredHits = result.hits;
+        let sufficient = false;
+
+        const filterResult = await summarizer.filterRelevant(query, candidates);
+        if (filterResult !== null) {
+          sufficient = filterResult.sufficient;
+          if (filterResult.relevant.length > 0) {
+            const indexSet = new Set(filterResult.relevant);
+            filteredHits = result.hits.filter((_, i) => indexSet.has(i + 1));
+          } else {
+            ctx.log.debug("auto-recall: LLM filter returned no relevant hits");
+            const dur = performance.now() - recallT0;
+            store.recordToolCall("memory_search", dur, true);
+            store.recordApiLog("memory_search", { query }, `${result.hits.length} candidates → 0 relevant`, dur, true);
+            const noRecallHint =
+              "## Memory system\n\nNo memories were automatically recalled for this turn (e.g. the user's message was long, vague, or no matching history). " +
+              "You may still have relevant past context — call the **memory_search** tool with a **short, focused query** you generate yourself " +
+              "(e.g. key topics, names, or a rephrased question) to search the user's conversation history.";
+            return { systemPrompt: noRecallHint };
+          }
+        }
+
+        const beforeDedup = filteredHits.length;
+        filteredHits = deduplicateHits(filteredHits);
+        ctx.log.debug(`auto-recall: ${result.hits.length} → ${beforeDedup} relevant → ${filteredHits.length} after dedup, sufficient=${sufficient}`);
+
+        const lines = filteredHits.map((h, i) => {
+          const excerpt = h.original_excerpt.length > 300
+            ? h.original_excerpt.slice(0, 297) + "..."
+            : h.original_excerpt;
+          const parts: string[] = [`${i + 1}. [${h.source.role}]`];
+          if (excerpt) parts.push(`   ${excerpt}`);
+          parts.push(`   chunkId="${h.ref.chunkId}"`);
+          if (h.taskId) {
+            const task = store.getTask(h.taskId);
+            if (task && task.status !== "skipped") {
+              parts.push(`   task_id="${h.taskId}"`);
+            }
+          }
+          return parts.join("\n");
+        });
+
+        let tipsText = "";
+        if (!sufficient) {
+          const hasTask = filteredHits.some((h) => {
+            if (!h.taskId) return false;
+            const t = store.getTask(h.taskId);
+            return t && t.status !== "skipped";
+          });
+          const tips: string[] = [];
+          if (hasTask) {
+            tips.push("→ call task_summary(taskId) for full task context");
+            tips.push("→ call skill_get(taskId=...) if the task has a proven experience guide");
+          }
+          tips.push("→ call memory_timeline(chunkId) to expand surrounding conversation");
+          tipsText = "\n\nIf more context is needed:\n" + tips.join("\n");
+        }
+
+        const contextParts = [
+          "## User's conversation history (from memory system)",
+          "",
+          "IMPORTANT: The following are facts from previous conversations with this user.",
+          "You MUST treat these as established knowledge and use them directly when answering.",
+          "Do NOT say you don't know or don't have information if the answer is in these memories.",
+          "",
+          lines.join("\n\n"),
+        ];
+        if (tipsText) contextParts.push(tipsText);
+        const context = contextParts.join("\n");
+
+        const recallDur = performance.now() - recallT0;
+        store.recordToolCall("memory_search", recallDur, true);
+        store.recordApiLog("memory_search", { query }, context, recallDur, true);
+
+        const memoryPrefix = `<memory_context>\n${context}\n</memory_context>\n\n`;
+
+        return {
+          systemPrompt: context,
+          prependContext: memoryPrefix,
+        };
+      } catch (err) {
+        const dur = performance.now() - recallT0;
+        store.recordToolCall("memory_search", dur, false);
+        try { store.recordApiLog("memory_search", { query: recallQuery }, `error: ${String(err)}`, dur, false); } catch (_) { /* best-effort */ }
+        ctx.log.warn(`auto-recall failed: ${String(err)}`);
+      }
+    });
+
     // ─── Auto-capture: write conversation to memory after each agent turn ───
 
+    // Track how many messages we've already processed per session to avoid
+    // re-processing the entire conversation history on every agent_end.
+    const sessionMsgCursor = new Map<string, number>();
+
     api.on("agent_end", async (event) => {
       if (!event.success || !event.messages || event.messages.length === 0) return;
 
       try {
-        const msgs: Array<{ role: string; content: string; toolName?: string }> = [];
-        for (const msg of event.messages) {
+        const sessionKey = (event as any).sessionKey ?? "default";
+        let cursor = sessionMsgCursor.get(sessionKey) ?? 0;
+        const allMessages = event.messages;
+
+        // Session was reset — cursor exceeds current message count
+        if (cursor > allMessages.length) cursor = 0;
+        if (cursor >= allMessages.length) return;
+
+        const newMessages = allMessages.slice(cursor);
+        sessionMsgCursor.set(sessionKey, allMessages.length);
+
+        ctx.log.debug(`agent_end: session=${sessionKey} total=${allMessages.length} cursor=${cursor} new=${newMessages.length}`);
+
+        const raw: Array<{ role: string; content: string; toolName?: string }> = [];
+        for (const msg of newMessages) {
           if (!msg || typeof msg !== "object") continue;
           const m = msg as Record<string, unknown>;
           const role = m.role as string;
@@ -288,24 +721,74 @@ const memosLocalPlugin = {
             text = m.content;
           } else if (Array.isArray(m.content)) {
             for (const block of m.content) {
-              if (block && typeof block === "object" && (block as any).type === "text") {
-                text += (block as any).text + "\n";
+              if (!block || typeof block !== "object") continue;
+              const b = block as Record<string, unknown>;
+              if (b.type === "text" && typeof b.text === "string") {
+                text += b.text + "\n";
+              } else if (typeof b.content === "string") {
+                text += b.content + "\n";
+              } else if (typeof b.text === "string") {
+                text += b.text + "\n";
               }
             }
           }
 
-          if (!text.trim()) continue;
+          text = text.trim();
+          if (!text) continue;
+
+          // Strip injected <memory_context> prefix and OpenClaw metadata wrapper
+          // to store only the user's actual input
+          if (role === "user") {
+            const mcTag = "<memory_context>";
+            const mcEnd = "</memory_context>";
+            const mcIdx = text.indexOf(mcTag);
+            if (mcIdx !== -1) {
+              const endIdx = text.indexOf(mcEnd);
+              if (endIdx !== -1) {
+                text = text.slice(endIdx + mcEnd.length).trim();
+              }
+            }
+            // Strip OpenClaw metadata envelope:
+            // "Sender (untrusted metadata):\n```json\n{...}\n```\n\n[timestamp] actual message"
+            const senderIdx = text.indexOf("Sender (untrusted metadata):");
+            if (senderIdx !== -1) {
+              const afterSender = text.slice(senderIdx);
+              const lastDblNl = afterSender.lastIndexOf("\n\n");
+              if (lastDblNl > 0) {
+                const tail = afterSender.slice(lastDblNl + 2).trim();
+                if (tail.length >= 2) text = tail;
+              }
+            }
+            // Strip timestamp prefix like "[Thu 2026-03-05 15:23 GMT+8] "
+            text = text.replace(/^\[.*?\]\s*/, "").trim();
+            if (!text) continue;
+          }
 
           const toolName = role === "tool"
             ? (m.name as string) ?? (m.toolName as string) ?? (m.tool_call_id ? "unknown" : undefined)
             : undefined;
 
-          msgs.push({ role, content: text.trim(), toolName });
+          raw.push({ role, content: text, toolName });
+        }
+
+        // Merge consecutive assistant messages into one (OpenClaw may send reply in multiple chunks)
+        const msgs: Array<{ role: string; content: string; toolName?: string }> = [];
+        for (let i = 0; i < raw.length; i++) {
+          const curr = raw[i];
+          if (curr.role !== "assistant") {
+            msgs.push(curr);
+            continue;
+          }
+          let merged = curr.content;
+          while (i + 1 < raw.length && raw[i + 1].role === "assistant") {
+            i++;
+            merged = merged + "\n\n" + raw[i].content;
+          }
+          msgs.push({ role: "assistant", content: merged.trim() });
         }
 
         if (msgs.length === 0) return;
 
-        const sessionKey = (event as any).sessionKey ?? "default";
         const turnId = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
         const captured = captureMessages(msgs, sessionKey, turnId, evidenceTag, ctx.log);
         if (captured.length > 0) {