memory-search-plugin 0.10.0 → 1.1.0

package/index.ts

@@ -1,210 +1,111 @@
-/**
- * memory-gateway 插件
- *
- * 替换 OpenClaw 默认的 memory-core 插件（通过 memory slot）
- * - memory_search → 路由到外部 Memory Gateway Search API
- * - memory_get    → 路径分流：MEMORY 路径走 Gateway，其他路径走原始实现
- *
- * 基于：
- * - OpenClaw_记忆隐私分阶段改造技术方案_V1.md（第 5.1 / 6.1 / 7.2 节）
- * - 存储方案设计-V2-虾生态2.md（第 4 节可见性规则）
- * - 三种场景-存储与查询方案.md（三场景可见性 + 存储 payload 格式）
- *
- * 场景可见性：
- *   private_own:  owner + peer(全部) + group(并集) + knowledge(用户ACL)
- *   private_other: peer(仅自己) + group(交集) + knowledge(用户ACL)
- *   group:         group(仅当前群) + knowledge(群ACL)
- *   knowledge:     knowledge(用户ACL)
- *   admin:         全部
- *
- * 原理：
- * memory-core 只注册了 memory_search 和 memory_get 两个工具。
- * append / insert / replace 等文件编辑工具不属于 memory slot，替换后不受影响。
- * 原始的 memory_get 实现可以通过 api.runtime.tools.createMemoryGetTool() 获取，
- * 用于非 MEMORY 路径的 passthrough。
- */
+import { resolveIdentity } from "./identity";
+import {
+  createGatewayClient,
+  type GatewayClient,
+  type GatewayClientConfig,
+} from "./gateway-client";
 
-import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
-import { createGatewayClient } from "./gateway-client";
-import { resolveIdentityFromParams, resolveIdentity, extractAgentId } from "./identity";
-import type { IdentityParams } from "./identity";
-import type { MemorySearchResult } from "./gateway-client";
-
-// ── Prompt Section ──────────────────────────────────────
-// 告诉 LLM 如何使用 memory 工具（和 memory-core 的逻辑一致）
+// ── Prompt Section ──
 
 const buildPromptSection = ({
   availableTools,
-  citationsMode,
 }: {
   availableTools: Set<string>;
-  citationsMode: string;
 }) => {
-  const hasMemorySearch = availableTools.has("memory_search");
-  const hasMemoryGet = availableTools.has("memory_get");
-  if (!hasMemorySearch && !hasMemoryGet) return [];
-
-  let toolGuidance: string;
-  if (hasMemorySearch && hasMemoryGet) {
-    toolGuidance =
-      "Before answering anything about prior work, decisions, dates, people, preferences, or todos: " +
-      "run memory_search for semantic search on MEMORY.md + memory/*.md; then use memory_get for keyword retrieval on only the needed content. " +
-      "If low confidence after search, say you checked.";
-  } else if (hasMemorySearch) {
-    toolGuidance =
-      "Before answering anything about prior work, decisions, dates, people, preferences, or todos: " +
-      "run memory_search on MEMORY.md + memory/*.md and answer from the matching results. " +
-      "If low confidence after search, say you checked.";
-  } else {
-    toolGuidance =
-      "Before answering anything about prior work, decisions, dates, people, preferences, or todos " +
-      "that already point to a specific memory file or note: " +
-      "run memory_get to pull only the needed lines. " +
-      "If low confidence after reading them, say you checked.";
-  }
-
-  const lines = ["## Memory Recall", toolGuidance];
-
-  lines.push(
+  const hasSearch = availableTools.has("memory_search");
+  const hasGet = availableTools.has("memory_get");
+  if (!hasSearch && !hasGet) return [];
+
+  const lines = [
+    "## Memory Recall",
+    "Before answering anything about prior work, decisions, dates, people, preferences, or todos: " +
+      "run memory_search for semantic search. " +
+      "If low confidence after search, say you checked.",
+    "",
     "**Context extraction:** When calling memory_search or memory_get, " +
-    "you MUST fill in the agent_id, sender_id, conversation_type, and group_id parameters " +
-    "by extracting them from the UntrustedContext section in this conversation. " +
-    "Look for lines like `agent_id: xxx`, `sender_id: xxx`, `conversation_type: xxx`, `group_id: xxx`. " +
-    "If a field is not present, omit it."
-  );
+      "you MUST extract the following from the UntrustedContext section and pass as parameters: " +
+      "`owner_id`, `sender_id`, `agent_id`, `conversation_type`, `group_id`. " +
+      "Look for lines like `owner_id: xxx`, `sender_id: xxx`, etc. " +
+      "If a field is not present, omit it. " +
+      "Do NOT invent or guess values — only use what is explicitly stated in UntrustedContext.",
+    "",
+  ];
 
-  if (citationsMode === "off") {
-    lines.push(
-      "Citations are disabled: do not mention file paths or line numbers in replies unless the user explicitly asks."
-    );
-  } else {
-    lines.push(
-      "Citations: include Source: <path#line> when it helps the user verify memory snippets."
-    );
-  }
-
-  lines.push("");
   return lines;
 };
 
-// ── 路径判断 ────────────────────────────────────────────
-
-/**
- * 判断是否是 MEMORY 路径
- * V1 方案第一阶段接管的路径：MEMORY.md 和 memory/**\/*.md
- */
-function isMemoryPath(path: string): boolean {
-  const normalized = path.replace(/\\/g, "/").replace(/^\.\//, "");
-  return (
-    normalized === "MEMORY.md" ||
-    normalized.startsWith("memory/") ||
-    normalized.endsWith("/MEMORY.md") ||
-    normalized.includes("/memory/")
-  );
-}
-
-// ── 结果格式化 ──────────────────────────────────────────
+// ── Plugin Entry ──
 
-/**
- * 将 Gateway 搜索结果格式化为 LLM 友好的文本
- * 包含 memory_type、来源文件和相似度信息，方便 LLM 做 citation
- * 字段对应 V2 存储方案的 payload 结构
- *
- * 注意：后端返回的相似度字段是 score（不是 similarity）
- */
-function formatSearchResults(results: MemorySearchResult[]): string {
-  if (results.length === 0) {
-    return "No relevant memories found.";
-  }
-
-  return results
-    .map((r, i) => {
-      // 构建来源描述：memory_type + 归属对象
-      let sourceDesc = r.memory_type;
-      if (r.memory_type === "peer" && r.peer_id) {
-        sourceDesc = `peer/${r.peer_id}`;
-      } else if (r.memory_type === "group" && r.group_id) {
-        sourceDesc = `group/${r.group_id}`;
-      } else if (r.memory_type === "knowledge" && r.kb_id) {
-        sourceDesc = `knowledge/${r.kb_id}`;
-      }
-
-      const filePart = r.source_file ? ` | ${r.source_file}` : "";
-      const header = `[${i + 1}] (${sourceDesc}, score: ${r.score.toFixed(2)}${filePart})`;
-      return `${header}\n${r.content}`;
-    })
-    .join("\n\n");
-}
-
-// ── 插件定义 ────────────────────────────────────────────
-
-export default definePluginEntry({
+export default {
   id: "memory-search-plugin",
-  name: "Memory Search Plugin",
-  description: "Routes memory to external Memory Search Gateway with ACL",
-  kind: "memory" as const,
 
   register(api: any) {
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-    // 0. 从 openclaw.json pluginConfig 读取 Gateway 配置
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-    const gatewayUrl = (api.pluginConfig?.gatewayUrl as string | undefined) || "http://localhost:18790";
-    const gatewayToken = (api.pluginConfig?.gatewayToken as string | undefined) || "";
-    const ocToken = process.env.OPENCLAW_GATEWAY_TOKEN || "";
-    const releaseName = ocToken.startsWith("oc-") ? ocToken.slice(3) : "";
-    console.log("[memory-search-plugin] gatewayUrl:", gatewayUrl, "releaseName:", releaseName);
-
-    const gateway = createGatewayClient({ gatewayUrl, gatewayToken });
-
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-    // 1. 注册 prompt section（和 memory-core 一致）
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-    api.registerMemoryPromptSection(buildPromptSection);
-
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-    // 2. 注册 memory_search → 调 Gateway Search API
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    const config: GatewayClientConfig = {
+      gatewayUrl:
+        api.getConfig?.("MEMORY_GATEWAY_URL") ||
+        process.env.MEMORY_GATEWAY_URL ||
+        "",
+      gatewayToken:
+        api.getConfig?.("MEMORY_GATEWAY_TOKEN") ||
+        process.env.MEMORY_GATEWAY_TOKEN ||
+        "",
+    };
+
+    if (!config.gatewayUrl) {
+      console.warn("[memory-search-plugin] MEMORY_GATEWAY_URL not set, plugin disabled");
+      return;
+    }
+
+    const gateway: GatewayClient = createGatewayClient(config);
+
+    // ── Prompt Section ──
+    api.registerPromptSection?.({
+      id: "memory-recall",
+      position: "top",
+      build: buildPromptSection,
+    });
+
+    // ── memory_search (vector search on memory_pipeline_facts) ──
     api.registerTool(
       (ctx: any) => {
-        // fallback: 如果 sessionKey 仍可用，保留兼容
-        const fallbackIdentity = ctx.sessionKey ? resolveIdentity(ctx.sessionKey) : null;
-        const fallbackAgentId = ctx.sessionKey ? extractAgentId(ctx.sessionKey) : null;
-
         return {
           name: "memory_search",
           description:
-            "Semantically search MEMORY.md and memory/**/*.md for relevant memories. " +
-            "You MUST extract agent_id, sender_id, conversation_type, group_id from the UntrustedContext in this conversation and pass them as parameters.",
+            "Semantically search memories. " +
+            "Extract owner_id, sender_id, agent_id, conversation_type, group_id from UntrustedContext.",
           parameters: {
             type: "object" as const,
             properties: {
-              query: {
+              query: { type: "string" as const, description: "The search query" },
+              owner_id: {
                 type: "string" as const,
-                description: "The search query",
+                description:
+                  "The owner_id from UntrustedContext (agent owner's user_id, always present)",
               },
-              agent_id: {
+              sender_id: {
                 type: "string" as const,
-                description: "The agent_id from UntrustedContext (e.g. 'main' or 'lobster_xxx')",
+                description: "The sender_id from UntrustedContext (current message sender)",
               },
-              sender_id: {
+              agent_id: {
                 type: "string" as const,
-                description: "The sender_id from UntrustedContext",
+                description: "The agent_id from UntrustedContext",
               },
               conversation_type: {
                 type: "string" as const,
-                description: "The conversation_type from UntrustedContext: 'direct' or 'group'",
+                description:
+                  "The conversation_type from UntrustedContext: 'direct' or 'group'",
               },
               group_id: {
                 type: "string" as const,
-                description: "The group_id from UntrustedContext (only present in group chats)",
+                description: "The group_id from UntrustedContext (only in group chats)",
               },
               maxResults: {
                 type: "number" as const,
-                description: "Maximum number of results to return",
+                description: "Max results (default 20)",
               },
               minScore: {
                 type: "number" as const,
-                description: "Minimum similarity score threshold",
+                description: "Min similarity score 0-1 (default 0.3)",
               },
             },
             required: ["query"],
@@ -214,8 +115,9 @@ export default definePluginEntry({
             toolCallId: string,
             params: {
               query?: string;
-              agent_id?: string;
+              owner_id?: string;
               sender_id?: string;
+              agent_id?: string;
               conversation_type?: string;
               group_id?: string;
               maxResults?: number;
@@ -229,65 +131,49 @@ export default definePluginEntry({
               };
             }
 
-            // 优先用 LLM 传参，fallback 到 sessionKey 解析
-            const agentId = params.agent_id?.trim() || fallbackAgentId || "main";
-            const identity = (params.sender_id || params.conversation_type || params.group_id)
-              ? resolveIdentityFromParams({
-                  sender_id: params.sender_id,
-                  conversation_type: params.conversation_type,
-                  group_id: params.group_id,
-                })
-              : (fallbackIdentity || resolveIdentityFromParams({}));
+            const identity = resolveIdentity({
+              sender_id: params.sender_id,
+              owner_id: params.owner_id,
+              conversation_type: params.conversation_type,
+              group_id: params.group_id,
+            });
+            const agentId = params.agent_id?.trim() || "main";
 
             console.log(
-              `[memory-search-plugin] search: agent_id=${agentId} scene=${identity.scene} ` +
-              `user_id=${identity.user_id} group_id=${identity.group_id} ` +
-              `release_name=${releaseName} ` +
-              `(source=${params.sender_id ? "llm_params" : "fallback"})`
+              `[memory-search] search: agent=${agentId} scene=${identity.scene} ` +
+                `sender=${identity.sender_id} owner=${identity.owner_id} group=${identity.group_id}`
             );
 
             try {
               const data = await gateway.callGatewaySearch({
+                owner_id: identity.owner_id,
+                sender_id: identity.sender_id,
                 agent_id: agentId,
-                user_id: identity.user_id,
                 query,
                 scene: identity.scene,
                 group_id: identity.group_id,
-                release_name: releaseName || undefined,
                 limit: params.maxResults || 20,
                 threshold: params.minScore || 0.3,
               });
 
-              const text = formatSearchResults(data.results);
-
-              return {
-                content: [{ type: "text" as const, text }],
-                details: {
-                  results: data.results,
-                  total: data.total,
-                  scene: data.scene,
-                  steps: data.steps,
-                },
-              };
+              const text =
+                data.results.length === 0
+                  ? "No relevant memories found."
+                  : data.results
+                      .map((r, i) => {
+                        const tag =
+                          r.memory_type === "group" && r.group_id
+                            ? `group/${r.group_id}`
+                            : r.memory_type === "knowledge" && r.kb_id
+                              ? `knowledge/${r.kb_id}`
+                              : r.memory_type;
+                        return `[${i + 1}] (${tag}, score: ${r.score.toFixed(2)})\n${r.content}`;
+                      })
+                      .join("\n\n");
+
+              return { content: [{ type: "text" as const, text }] };
             } catch (err: any) {
-              console.error("[memory-search-plugin] search failed:", err.message);
-
-              try {
-                const fallbackTool =
-                  api.runtime?.tools?.createMemorySearchTool({
-                    config: ctx.config,
-                    agentSessionKey: ctx.sessionKey,
-                  });
-                if (fallbackTool) {
-                  console.warn(
-                    "[memory-search-plugin] falling back to local memory_search"
-                  );
-                  return await fallbackTool.execute(toolCallId, { query, maxResults: params.maxResults, minScore: params.minScore });
-                }
-              } catch {
-                // 降级也失败
-              }
-
+              console.error("[memory-search] search failed:", err.message);
               return {
                 content: [
                   {
@@ -303,162 +189,120 @@ export default definePluginEntry({
       { names: ["memory_search"] }
     );
 
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-    // 3. 注册 memory_get → 路径分流
-    //    MEMORY 路径 → Gateway
-    //    其他路径   → 原始实现（passthrough）
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    // ── memory_get (keyword search on memory_chat_logs) ──
     api.registerTool(
       (ctx: any) => {
-        const fallbackIdentity = ctx.sessionKey ? resolveIdentity(ctx.sessionKey) : null;
-        const fallbackAgentId = ctx.sessionKey ? extractAgentId(ctx.sessionKey) : null;
-
         return {
           name: "memory_get",
           description:
-            "Read a memory file or workspace file. " +
-            "Supports reading MEMORY.md, memory/**/*.md, and other workspace files. " +
-            "You MUST extract agent_id, sender_id, conversation_type, group_id from the UntrustedContext in this conversation and pass them as parameters.",
+            "Search raw chat messages by keyword. " +
+            "Queries the original message log, not the extracted facts. " +
+            "Extract owner_id, sender_id, agent_id, conversation_type, group_id from UntrustedContext.",
           parameters: {
             type: "object" as const,
             properties: {
-              path: {
+              keyword: {
                 type: "string" as const,
-                description:
-                  "Relative path to the file (e.g. MEMORY.md, memory/notes.md, SOUL.md)",
+                description: "Keyword to search in chat messages",
               },
-              agent_id: {
+              owner_id: {
                 type: "string" as const,
-                description: "The agent_id from UntrustedContext (e.g. 'main' or 'lobster_xxx')",
+                description: "The owner_id from UntrustedContext",
               },
               sender_id: {
                 type: "string" as const,
                 description: "The sender_id from UntrustedContext",
               },
+              agent_id: {
+                type: "string" as const,
+                description: "The agent_id from UntrustedContext",
+              },
               conversation_type: {
                 type: "string" as const,
-                description: "The conversation_type from UntrustedContext: 'direct' or 'group'",
+                description:
+                  "The conversation_type from UntrustedContext: 'direct' or 'group'",
               },
               group_id: {
                 type: "string" as const,
-                description: "The group_id from UntrustedContext (only present in group chats)",
-              },
-              from: {
-                type: "number" as const,
-                description: "Starting line number (1-indexed)",
+                description: "The group_id from UntrustedContext (only in group chats)",
               },
-              lines: {
+              limit: {
                 type: "number" as const,
-                description: "Number of lines to read",
+                description: "Max messages to return (default 20)",
               },
             },
-            required: ["path"],
+            required: ["keyword"],
           },
 
           async execute(
             toolCallId: string,
             params: {
-              path?: string;
-              agent_id?: string;
+              keyword?: string;
+              owner_id?: string;
               sender_id?: string;
+              agent_id?: string;
               conversation_type?: string;
               group_id?: string;
-              from?: number;
-              lines?: number;
+              limit?: number;
             }
           ) {
-            const path = params.path || "";
-            if (!path) {
+            const keyword = params.keyword || "";
+            if (!keyword) {
               return {
-                content: [{ type: "text" as const, text: "No path provided." }],
+                content: [{ type: "text" as const, text: "No keyword provided." }],
               };
             }
 
-            // 懒加载原始 memory_get 实现，用于非 MEMORY 路径的 passthrough
-            let originalGetTool: any = null;
-            try {
-              originalGetTool = api.runtime?.tools?.createMemoryGetTool({
-                config: ctx.config,
-                agentSessionKey: ctx.sessionKey,
-              });
-            } catch {
-              // memory-core 被替换后 api.runtime.tools 不可用，忽略
-            }
-
-            // ── 路径分流 ──
-            if (isMemoryPath(path)) {
-              const agentId = params.agent_id?.trim() || fallbackAgentId || "main";
-              const identity = (params.sender_id || params.conversation_type || params.group_id)
-                ? resolveIdentityFromParams({
-                    sender_id: params.sender_id,
-                    conversation_type: params.conversation_type,
-                    group_id: params.group_id,
-                  })
-                : (fallbackIdentity || resolveIdentityFromParams({}));
-
-              console.log(
-                `[memory-search-plugin] get: path=${path} agent_id=${agentId} scene=${identity.scene} ` +
-                `user_id=${identity.user_id} release_name=${releaseName} (source=${params.sender_id ? "llm_params" : "fallback"})`
-              );
-
-              try {
-                const data = await gateway.callGatewayGet({
-                  agent_id: agentId,
-                  user_id: identity.user_id,
-                  path,
-                  scene: identity.scene,
-                  group_id: identity.group_id,
-                  release_name: releaseName || undefined,
-                  from: params.from,
-                  lines: params.lines,
-                });
-
-                return {
-                  content: [{ type: "text" as const, text: data.text }],
-                  details: { path: data.path, text: data.text },
-                };
-              } catch (err: any) {
-                console.error("[memory-search-plugin] get failed:", err.message);
+            const identity = resolveIdentity({
+              sender_id: params.sender_id,
+              owner_id: params.owner_id,
+              conversation_type: params.conversation_type,
+              group_id: params.group_id,
+            });
+            const agentId = params.agent_id?.trim() || "main";
 
-                if (err.message?.includes('403')) {
-                  return {
-                    content: [
-                      {
-                        type: "text" as const,
-                        text: `Access denied: ${path}`,
-                      },
-                    ],
-                  };
-                }
+            console.log(
+              `[memory-search] get: keyword="${keyword}" agent=${agentId} scene=${identity.scene} ` +
+                `owner=${identity.owner_id} group=${identity.group_id}`
+            );
 
-                if (originalGetTool) {
-                  console.warn(
-                    "[memory-search-plugin] falling back to local memory_get for:",
-                    path
-                  );
-                  return await originalGetTool.execute(toolCallId, { path, from: params.from, lines: params.lines });
-                }
+            try {
+              const data = await gateway.callGatewayGet({
+                owner_id: identity.owner_id,
+                sender_id: identity.sender_id,
+                agent_id: agentId,
+                keyword,
+                scene: identity.scene,
+                group_id: identity.group_id,
+                limit: params.limit || 20,
+              });
 
+              if (data.messages.length === 0) {
                 return {
                   content: [
-                    {
-                      type: "text" as const,
-                      text: `Failed to read ${path}: Gateway unavailable.`,
-                    },
+                    { type: "text" as const, text: "No matching messages found." },
                   ],
-                  details: { path, text: "", error: err.message },
                 };
               }
-            } else {
-              if (originalGetTool) {
-                return await originalGetTool.execute(toolCallId, { path, from: params.from, lines: params.lines });
-              }
 
+              const text = data.messages
+                .map((m) => {
+                  const tag =
+                    m.message_type === "group" && m.group_id
+                      ? `group/${m.group_id}`
+                      : m.message_type;
+                  return `[${tag}] ${m.formatted_text}`;
+                })
+                .join("\n");
+
+              return { content: [{ type: "text" as const, text }] };
+            } catch (err: any) {
+              console.error("[memory-search] get failed:", err.message);
               return {
                 content: [
                   {
                     type: "text" as const,
-                    text: `Cannot read ${path}: memory_get backend not available.`,
+                    text: "Message search temporarily unavailable.",
                   },
                 ],
               };
@@ -468,19 +312,5 @@ export default definePluginEntry({
       },
       { names: ["memory_get"] }
     );
-
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-    // 4. 保留 CLI 命令（和 memory-core 一致）
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-    api.registerCli(
-      ({ program }: any) => {
-        try {
-          api.runtime?.tools?.registerMemoryCli(program);
-        } catch {
-          // memory-core 被替换后 api.runtime.tools 不可用，忽略
-        }
-      },
-      { commands: ["memory"] }
-    );
   },
-});
+};

package/openclaw.plugin.json

@@ -1,22 +1,19 @@
 {
   "id": "memory-search-plugin",
   "name": "Memory Search Plugin",
-  "description": "Routes memory_search to external Memory Search Gateway with ACL, memory_get with path routing",
-  "kind": "memory",
-  "version": "0.8.0",
-  "configSchema": {
-    "type": "object",
-    "additionalProperties": false,
-    "properties": {
-      "gatewayUrl": {
-        "type": "string",
-        "description": "Memory Search Gateway API 地址，如 http://your-host:8888"
-      },
-      "gatewayToken": {
-        "type": "string",
-        "description": "Bearer Token，留空则不认证"
-      }
+  "version": "1.1.0",
+  "description": "Memory search and retrieval with owner_id-based isolation (no release_name)",
+  "main": "index.ts",
+  "config": {
+    "MEMORY_GATEWAY_URL": {
+      "type": "string",
+      "description": "URL of the claw-memory gateway service",
+      "required": true
     },
-    "required": ["gatewayUrl"]
+    "MEMORY_GATEWAY_TOKEN": {
+      "type": "string",
+      "description": "Auth token for gateway",
+      "required": false
+    }
   }
 }