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

package/index.ts

@@ -17,88 +17,30 @@ import { RecallEngine } from "./src/recall/engine";
 import { captureMessages } from "./src/capture";
 import { DEFAULTS } from "./src/types";
 import { ViewerServer } from "./src/viewer/server";
-
-/**
- * Install the MemOS skill into the workspace skills directory.
- * The skill teaches the agent WHEN and HOW to use memory tools.
- */
-function ensureSkillInstalled(workspaceDir: string, log: { info: (s: string) => void }): void {
-  const skillDir = path.join(workspaceDir, "skills", "memos-local");
-  const skillMd = path.join(skillDir, "SKILL.md");
-
-  // Read bundled skill content from plugin source
-  const bundledSkill = path.join(__dirname, "skill", "SKILL.md");
-  let skillContent: string;
-  try {
-    skillContent = fs.readFileSync(bundledSkill, "utf-8");
-  } catch {
-    log.info("memos-local: bundled SKILL.md not found, using inline fallback");
-    skillContent = [
-      "---",
-      "name: memos-local",
-      'description: "Long-term conversation memory (MemOS). Use when: user asks about their identity, name, preferences, past conversations, or references something from a previous session."',
-      'metadata: { "openclaw": { "emoji": "🧠" } }',
-      "---",
-      "",
-      "# MemOS Local Memory Skill",
-      "",
-      "You have memory tools: memory_search, memory_timeline, memory_get.",
-      "Call memory_search BEFORE saying 'I don't know' about user identity/preferences.",
-      "For identity questions: memory_search(query=\"名字 身份\", role=\"user\")",
-      "If insufficient: call memory_timeline with hit ref, or try different query.",
-      "Budget: max 2 search + 2 timeline. Only then say 'insufficient evidence'.",
-      "NEVER ignore results. If USER said '我是唐波', that IS their name.",
-    ].join("\n");
-  }
-
-  try {
-    let needsWrite = true;
-    if (fs.existsSync(skillMd)) {
-      const existing = fs.readFileSync(skillMd, "utf-8");
-      if (existing === skillContent) needsWrite = false;
-    }
-
-    if (needsWrite) {
-      fs.mkdirSync(skillDir, { recursive: true });
-      fs.writeFileSync(skillMd, skillContent, "utf-8");
-      log.info("memos-local: installed/updated MemOS skill in workspace");
-    }
-  } catch {
-    // Non-fatal
-  }
-
-  // Always clean up old AGENTS.md protocol block if present
-  cleanupAgentsMdProtocol(workspaceDir);
-}
-
-function cleanupAgentsMdProtocol(workspaceDir: string): void {
-  const agentsPath = path.join(workspaceDir, "AGENTS.md");
-  try {
-    if (!fs.existsSync(agentsPath)) return;
-    let content = fs.readFileSync(agentsPath, "utf-8");
-
-    const markers = ["## MemOS Memory Protocol", "### MemOS Memory Rules"];
-    let changed = false;
-    for (const marker of markers) {
-      const idx = content.indexOf(marker);
-      if (idx === -1) continue;
-      const nextH2 = content.slice(idx + marker.length).match(/\n## (?!MemOS|Red Lines)/);
-      const blockEnd = nextH2 ? idx + marker.length + nextH2.index! : content.length;
-
-      // If marker is inside a "## Red Lines" section, remove the whole Red Lines block
-      const redLinesIdx = content.lastIndexOf("## Red Lines", idx);
-      const blockStart = (redLinesIdx !== -1 && redLinesIdx >= idx - 50) ? redLinesIdx : idx;
-
-      const before = content.slice(0, blockStart).trimEnd();
-      const after = content.slice(blockEnd).trimStart();
-      content = [before, after].filter(Boolean).join("\n\n");
-      if (content && !content.endsWith("\n")) content += "\n";
-      changed = true;
-    }
-    if (changed) fs.writeFileSync(agentsPath, content, "utf-8");
-  } catch {
-    // Non-fatal
+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 = {
@@ -138,10 +80,60 @@ const memosLocalPlugin = {
     const evidenceTag = ctx.config.capture?.evidenceWrapperTag ?? DEFAULTS.evidenceWrapperTag;
 
     const workspaceDir = api.resolvePath("~/.openclaw/workspace");
-    ensureSkillInstalled(workspaceDir, { info: (msg) => api.logger.info(msg) });
+    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(
@@ -149,32 +141,27 @@ const memosLocalPlugin = {
         name: "memory_search",
         label: "Memory Search",
         description:
-          "Search stored conversation memories. You have a long-term memory system — use it proactively!\n\n" +
-          "MANDATORY call scenarios:\n" +
-          "1. FIRST message of any new conversation — search to recall user context\n" +
-          "2. BEFORE asking the user for information — past conversations may already have the answer\n" +
-          "3. When the current topic might overlap with a past conversation\n\n" +
-          "Think of this as checking your notes before asking the user to repeat themselves.\n" +
-          "Each hit includes ref fields — use memory_get or task_summary to read details.\n" +
-          "Use role='user' to find what the USER actually said.\n" +
-          "Default: top 6 results, minScore 0.45.",
+          "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, role } = 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;
           };
 
-          ctx.log.debug(`memory_search query="${query}" maxResults=${maxResults ?? 6} minScore=${minScore ?? 0.45} role=${role ?? "all"}`);
-          const result = await engine.search({ query, maxResults, minScore, role });
-          ctx.log.debug(`memory_search returned ${result.hits.length} hits`);
+          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 {
@@ -183,8 +170,49 @@ const memosLocalPlugin = {
             };
           }
 
-          const lines = result.hits.map((h, i) => {
-            const parts = [`${i + 1}. [${h.source.role}] ${h.summary}`, `   id="${h.ref.chunkId}"`];
+          // 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") {
@@ -194,22 +222,35 @@ const memosLocalPlugin = {
             return parts.join("\n");
           });
 
-          const tips: string[] = [];
-          tips.push("NEXT STEPS:");
-          tips.push("1. Call memory_get(chunkId) to read the full original text of any hit.");
-          tips.push("2. If a hit has task_id, call task_summary(taskId) to get the complete task context.");
-          tips.push("3. Call memory_timeline with ref fields to read surrounding conversation.");
-          tips.push("4. Do NOT say 'I don't know' until you have tried at least one follow-up call.");
+          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:\n\n${lines.join("\n\n")}\n\n${tips.join("\n")}`,
+                text: `Found ${filteredHits.length} relevant memories:\n\n${lines.join("\n\n")}${tipsText}`,
               },
             ],
             details: {
-              hits: result.hits.map((h) => {
+              hits: filteredHits.map((h) => {
                 let effectiveTaskId = h.taskId;
                 if (effectiveTaskId) {
                   const t = store.getTask(effectiveTaskId);
@@ -217,8 +258,8 @@ const memosLocalPlugin = {
                 }
                 return {
                   chunkId: h.ref.chunkId,
-                  summary: h.summary,
                   taskId: effectiveTaskId,
+                  skillId: h.skillId,
                   role: h.source.role,
                   score: h.score,
                 };
@@ -226,7 +267,7 @@ const memosLocalPlugin = {
               meta: result.meta,
             },
           };
-        },
+        }),
       },
       { name: "memory_search" },
     );
@@ -238,29 +279,29 @@ const memosLocalPlugin = {
         name: "memory_timeline",
         label: "Memory Timeline",
         description:
-          "Expand context around a search hit. MUST use this after memory_search when " +
-          "the returned excerpts don't fully answer the question. Pass the ref fields " +
-          "(sessionKey, chunkId, turnId, seq) from any search hit to read surrounding messages.",
+          "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) {
+        execute: trackTool("memory_timeline", async (_toolCallId: any, params: any) => {
           ctx.log.debug(`memory_timeline called`);
-          const { sessionKey, chunkId, turnId, seq, window: win } = params as {
-            sessionKey: string;
+          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) => {
@@ -285,55 +326,13 @@ 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 ───
-
-    api.registerTool(
-      {
-        name: "memory_get",
-        label: "Memory Get",
-        description:
-          "Get full original text of a memory chunk. Use to verify exact details from a search hit.",
-        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})` }),
-          ),
-        }),
-        async execute(_toolCallId, params) {
-          ctx.log.debug(`memory_get called`);
-          const { chunkId, maxChars } = params as { chunkId: string; maxChars?: number };
-          const limit = Math.min(maxChars ?? DEFAULTS.getMaxCharsDefault, DEFAULTS.getMaxCharsMax);
-
-          const chunk = store.getChunk(chunkId);
-          if (!chunk) {
-            return {
-              content: [{ type: "text", text: `Chunk not found: ${chunkId}` }],
-              details: { error: "not_found" },
-            };
-          }
-
-          const content = chunk.content.length > limit
-            ? chunk.content.slice(0, limit) + "…"
-            : chunk.content;
-
-          const who = chunk.role === "user" ? "USER said" : chunk.role === "assistant" ? "ASSISTANT replied" : chunk.role === "tool" ? "TOOL returned" : chunk.role.toUpperCase();
-
-          return {
-            content: [{ type: "text", text: `[${who}] (session: ${chunk.sessionKey})\n\n${content}` }],
-            details: {
-              ref: { sessionKey: chunk.sessionKey, chunkId: chunk.id, turnId: chunk.turnId, seq: chunk.seq },
-              source: { ts: chunk.createdAt, role: chunk.role, sessionKey: chunk.sessionKey },
-            },
-          };
-        },
-      },
-      { name: "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 ───
 
@@ -348,7 +347,7 @@ const memosLocalPlugin = {
         parameters: Type.Object({
           taskId: Type.String({ description: "The task_id from a memory_search hit" }),
         }),
-        async execute(_toolCallId, params) {
+        execute: trackTool("task_summary", async (_toolCallId: any, params: any) => {
           const { taskId } = params as { taskId: string };
           ctx.log.debug(`task_summary called for task=${taskId}`);
 
@@ -385,10 +384,19 @@ const memosLocalPlugin = {
             };
           }
 
+          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: `## Task: ${task.title}\n\nStatus: ${task.status}\nChunks: ${store.getChunksByTask(taskId).length}\n\n${task.summary}`,
+              text: `## Task: ${task.title}\n\nStatus: ${task.status}\nChunks: ${store.getChunksByTask(taskId).length}\n\n${task.summary}${skillSection}`,
             }],
             details: {
               taskId: task.id,
@@ -396,13 +404,113 @@ const memosLocalPlugin = {
               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: "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 ───
 
     const viewerPort = (pluginCfg as any).viewerPort ?? 18799;
@@ -416,7 +524,7 @@ const memosLocalPlugin = {
           "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 {
@@ -438,21 +546,171 @@ const memosLocalPlugin = {
             ],
             details: { viewerUrl: url },
           };
-        },
+        }),
       },
       { name: "memory_viewer" },
     );
 
-    // No prompt injection — retrieval strategy is provided via the MemOS Skill
+    // ─── 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;
@@ -463,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) {