memory-search-plugin 0.2.0

package/gateway-client.ts

@@ -0,0 +1,113 @@
+/**
+ * Memory Search Gateway HTTP 调用封装
+ *
+ * 封装与外部 Memory Search Gateway 服务的通信。
+ * 请求/响应格式与后端 app/models.py 完全对齐。
+ * Gateway 地址从 openclaw.json plugins.entries.memory-search-plugin.config.gatewayUrl 获取。
+ */
+
+import type { Scene } from "./identity";
+
+// ── 类型定义（与后端 app/models.py 对齐）──────────────
+
+export type MemoryType = "owner" | "peer" | "group" | "knowledge";
+
+export interface MemorySearchRequest {
+  agent_id: string;
+  user_id: string;
+  query: string;
+  scene: Scene;
+  group_id?: string | null;
+  limit?: number;       // 1-100, default 20
+  threshold?: number;   // 0.0-1.0, default 0.3
+}
+
+export interface MemorySearchResult {
+  id: string;
+  content: string;
+  score: number;
+  memory_type: MemoryType;
+  source_file?: string;
+  created_at?: string;
+  agent_id?: string;
+  peer_id?: string;
+  group_id?: string;
+  kb_id?: string;
+}
+
+export interface MemorySearchResponse {
+  results: MemorySearchResult[];
+  total: number;
+  scene: Scene;
+  steps: string[];
+}
+
+export interface MemoryGetRequest {
+  agent_id: string;
+  user_id: string;
+  path: string;
+  scene?: Scene;
+  group_id?: string | null;
+  from?: number;
+  lines?: number;
+}
+
+export interface MemoryGetResponse {
+  text: string;
+  path: string;
+}
+
+// ── Gateway Client ─────────────────────────────────────
+
+export interface GatewayClientConfig {
+  gatewayUrl: string;
+  gatewayToken?: string;
+}
+
+export interface GatewayClient {
+  callGatewaySearch(options: MemorySearchRequest): Promise<MemorySearchResponse>;
+  callGatewayGet(options: MemoryGetRequest): Promise<MemoryGetResponse>;
+}
+
+export function createGatewayClient(config: GatewayClientConfig): GatewayClient {
+  const baseUrl = config.gatewayUrl.replace(/\/+$/, "");
+  const token = config.gatewayToken || "";
+
+  const authHeaders = token
+    ? { Authorization: `Bearer ${token}` }
+    : {};
+
+  return {
+    async callGatewaySearch(options) {
+      const url = `${baseUrl}/api/memory/search`;
+      const response = await fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", ...authHeaders },
+        body: JSON.stringify(options),
+      });
+      if (!response.ok) {
+        const errorBody = await response.text().catch(() => "");
+        throw new Error(
+          `Gateway search failed: ${response.status} ${response.statusText} ${errorBody}`
+        );
+      }
+      return response.json() as Promise<MemorySearchResponse>;
+    },
+
+    async callGatewayGet(options) {
+      const url = `${baseUrl}/api/memory/get`;
+      const response = await fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", ...authHeaders },
+        body: JSON.stringify(options),
+      });
+      if (!response.ok) {
+        const errorBody = await response.text().catch(() => "");
+        throw new Error(
+          `Gateway get failed: ${response.status} ${response.statusText} ${errorBody}`
+        );
+      }
+      return response.json() as Promise<MemoryGetResponse>;
+    },
+  };
+}

package/identity.ts

@@ -0,0 +1,106 @@
+/**
+ * 身份解析模块
+ *
+ * 从 sessionKey 中解析出当前会话的身份类型和场景。
+ * sessionKey 格式参考 V1.4 文档和 memory-privacy/identity.ts
+ *
+ * 输出：
+ *   - scene:    对应后端 SearchRequest.scene（private_own / private_other / group）
+ *   - user_id:  当前对话用户的 ID
+ *   - group_id: 群聊时的群 ID（仅 group 场景）
+ */
+
+/** 后端 models.py 定义的五种场景 */
+export type Scene =
+  | "private_own"
+  | "private_other"
+  | "group"
+  | "knowledge"
+  | "admin";
+
+/** 解析后的身份信息，与后端 SearchRequest 的 user_id / scene / group_id 对齐 */
+export interface ResolvedIdentity {
+  scene: Scene;
+  user_id: string;
+  group_id: string | null;
+}
+
+/**
+ * 从 sessionKey 解析身份 + 场景
+ *
+ * sessionKey 末段格式:
+ *   owner/peer: user_{userId}_lobster_{lobsterId}_release_{version}
+ *   group:      user_{userId}_lobster_{lobsterId}_group_{groupId}_release_{version}
+ *
+ * 场景映射:
+ *   owner（私聊自己的 agent）→ scene = "private_own"
+ *   peer （私聊别人的 agent）→ scene = "private_other"
+ *   group（群聊中 agent 回复）→ scene = "group"
+ */
+export function resolveIdentity(sessionKey: string | undefined): ResolvedIdentity {
+  // ── 测试模式：环境变量覆盖 ──────────────────────────
+  // 设置 MEMORY_GATEWAY_TEST_SCENE 即可跳过 sessionKey 解析，
+  // 方便在没有真实 IM 会话时测试插件。
+  const testScene = process.env.MEMORY_GATEWAY_TEST_SCENE as Scene | undefined;
+  if (testScene) {
+    const result: ResolvedIdentity = {
+      scene: testScene,
+      user_id: process.env.MEMORY_GATEWAY_TEST_USER_ID || "owner_A",
+      group_id: process.env.MEMORY_GATEWAY_TEST_GROUP_ID || null,
+    };
+    console.log("[memory-search-plugin] TEST MODE identity:", JSON.stringify(result));
+    return result;
+  }
+
+  // ── 正常模式：从 sessionKey 解析 ──────────────────────
+  const sk = sessionKey ?? "";
+  const sessionPart = sk.split(":").pop() || "";
+
+  // 1. 群聊: 包含 _group_
+  const groupMatch = sessionPart.match(
+    /user_(.+?)_lobster_(.+?)_group_(.+?)_release_(.+)$/
+  );
+  if (groupMatch) {
+    return {
+      scene: "group",
+      user_id: groupMatch[1],
+      group_id: groupMatch[3],
+    };
+  }
+
+  // 2. 私聊 (owner 或 peer)
+  const peerMatch = sessionPart.match(
+    /user_(.+?)_lobster_(.+?)_release_(.+)$/
+  );
+  if (peerMatch) {
+    const userId = peerMatch[1];
+    if (isOwner(userId)) {
+      return { scene: "private_own", user_id: userId, group_id: null };
+    }
+    return { scene: "private_other", user_id: userId, group_id: null };
+  }
+
+  // 3. 兜底: 安全起见当作 peer（private_other）
+  return { scene: "private_other", user_id: "unknown", group_id: null };
+}
+
+/**
+ * 判断是否是 owner
+ * 通过环境变量 OPENCLAW_GATEWAY_TOKEN 判断
+ * token 格式: oc-user-{ownerUserId}
+ */
+function isOwner(userId: string): boolean {
+  const token = process.env.OPENCLAW_GATEWAY_TOKEN || "";
+  if (!token) return false;
+  const ownerUserId = token.split("-").pop() || "";
+  return ownerUserId !== "" && ownerUserId === userId;
+}
+
+/**
+ * 从 sessionKey 提取 agent_id
+ * sessionKey 格式: agent:{agentId}:palz:...
+ */
+export function extractAgentId(sessionKey: string | undefined): string {
+  const parts = (sessionKey || "").split(":");
+  return parts.length >= 2 ? parts[1] : "main";
+}

package/index.ts

@@ -0,0 +1,390 @@
+/**
+ * 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 { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+import { createGatewayClient } from "./gateway-client";
+import { resolveIdentity, extractAgentId } from "./identity";
+import type { MemorySearchResult } from "./gateway-client";
+
+// ── Prompt Section ──────────────────────────────────────
+// 告诉 LLM 如何使用 memory 工具（和 memory-core 的逻辑一致）
+
+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 on MEMORY.md + memory/*.md; then use memory_get to pull only the needed lines. " +
+      "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];
+
+  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/")
+  );
+}
+
+// ── 结果格式化 ──────────────────────────────────────────
+
+/**
+ * 将 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({
+  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) || "";
+    console.log("[memory-search-plugin] gatewayUrl:", gatewayUrl);
+
+    const gateway = createGatewayClient({ gatewayUrl, gatewayToken });
+
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    // 1. 注册 prompt section（和 memory-core 一致）
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    api.registerMemoryPromptSection(buildPromptSection);
+
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    // 2. 注册 memory_search → 调 Gateway Search API
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    api.registerTool(
+      (ctx: any) => {
+        const identity = resolveIdentity(ctx.sessionKey);
+        const agentId = extractAgentId(ctx.sessionKey);
+
+        return {
+          name: "memory_search",
+          description:
+            "Semantically search MEMORY.md and memory/**/*.md for relevant memories.",
+          parameters: {
+            type: "object" as const,
+            properties: {
+              query: {
+                type: "string" as const,
+                description: "The search query",
+              },
+              maxResults: {
+                type: "number" as const,
+                description: "Maximum number of results to return",
+              },
+              minScore: {
+                type: "number" as const,
+                description: "Minimum similarity score threshold",
+              },
+            },
+            required: ["query"],
+          },
+
+          async execute(
+            toolCallId: string,
+            params: { query?: string; maxResults?: number; minScore?: number }
+          ) {
+            const query = params.query || "";
+            if (!query) {
+              return {
+                content: [{ type: "text" as const, text: "No query provided." }],
+              };
+            }
+
+            try {
+              // 按后端 SearchRequest 格式发送请求
+              const data = await gateway.callGatewaySearch({
+                agent_id: agentId,
+                user_id: identity.user_id,
+                query,
+                scene: identity.scene,
+                group_id: identity.group_id,
+                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,
+                },
+              };
+            } catch (err: any) {
+              console.error("[memory-search-plugin] search failed:", err.message);
+
+              // ── 降级：尝试用原始的 memory_search ──
+              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, params);
+                }
+              } catch {
+                // 降级也失败，返回错误信息
+              }
+
+              return {
+                content: [
+                  {
+                    type: "text" as const,
+                    text: "Memory search temporarily unavailable.",
+                  },
+                ],
+              };
+            }
+          },
+        };
+      },
+      { names: ["memory_search"] }
+    );
+
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    // 3. 注册 memory_get → 路径分流
+    //    MEMORY 路径 → Gateway
+    //    其他路径   → 原始实现（passthrough）
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    api.registerTool(
+      (ctx: any) => {
+        const identity = resolveIdentity(ctx.sessionKey);
+        const agentId = extractAgentId(ctx.sessionKey);
+
+        // 获取原始 memory_get 实现，用于非 MEMORY 路径的 passthrough
+        const originalGetTool = api.runtime.tools.createMemoryGetTool({
+          config: ctx.config,
+          agentSessionKey: ctx.sessionKey,
+        });
+
+        return {
+          name: "memory_get",
+          description:
+            "Read a memory file or workspace file. " +
+            "Supports reading MEMORY.md, memory/**/*.md, and other workspace files.",
+          parameters: {
+            type: "object" as const,
+            properties: {
+              path: {
+                type: "string" as const,
+                description:
+                  "Relative path to the file (e.g. MEMORY.md, memory/notes.md, SOUL.md)",
+              },
+              from: {
+                type: "number" as const,
+                description: "Starting line number (1-indexed)",
+              },
+              lines: {
+                type: "number" as const,
+                description: "Number of lines to read",
+              },
+            },
+            required: ["path"],
+          },
+
+          async execute(
+            toolCallId: string,
+            params: { path?: string; from?: number; lines?: number }
+          ) {
+            const path = params.path || "";
+            if (!path) {
+              return {
+                content: [{ type: "text" as const, text: "No path provided." }],
+              };
+            }
+
+            // ── 路径分流 ──
+            if (isMemoryPath(path)) {
+              // MEMORY 路径 → 调 Gateway（带 ACL）
+              try {
+                // 按后端 GetRequest 格式发送请求
+                const data = await gateway.callGatewayGet({
+                  agent_id: agentId,
+                  user_id: identity.user_id,
+                  path,
+                  scene: identity.scene,
+                  group_id: identity.group_id,
+                  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);
+
+                // 403 明确拒绝 → 不降级，直接返回拒绝
+                if (err.message?.includes('403')) {
+                  return {
+                    content: [
+                      {
+                        type: "text" as const,
+                        text: `Access denied: ${path}`,
+                      },
+                    ],
+                  };
+                }
+
+                // 其他错误（网络不通等）→ 降级到本地文件读取
+                if (originalGetTool) {
+                  console.warn(
+                    "[memory-search-plugin] falling back to local memory_get for:",
+                    path
+                  );
+                  return await originalGetTool.execute(toolCallId, params);
+                }
+
+                return {
+                  content: [
+                    {
+                      type: "text" as const,
+                      text: `Failed to read ${path}: Gateway unavailable.`,
+                    },
+                  ],
+                  details: { path, text: "", error: err.message },
+                };
+              }
+            } else {
+              // 非 MEMORY 路径 → passthrough 给原始实现
+              // 这样 SOUL.md、rules.md 等文件的读取行为完全不变
+              if (originalGetTool) {
+                return await originalGetTool.execute(toolCallId, params);
+              }
+
+              return {
+                content: [
+                  {
+                    type: "text" as const,
+                    text: `Cannot read ${path}: memory_get backend not available.`,
+                  },
+                ],
+              };
+            }
+          },
+        };
+      },
+      { names: ["memory_get"] }
+    );
+
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    // 4. 保留 CLI 命令（和 memory-core 一致）
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    api.registerCli(
+      ({ program }: any) => {
+        api.runtime.tools.registerMemoryCli(program);
+      },
+      { commands: ["memory"] }
+    );
+  },
+});

package/openclaw.plugin.json

@@ -0,0 +1,22 @@
+{
+  "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.1.0",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "gatewayUrl": {
+        "type": "string",
+        "description": "Memory Search Gateway API 地址，如 http://172.22.39.89:8888"
+      },
+      "gatewayToken": {
+        "type": "string",
+        "description": "Bearer Token，留空则不认证"
+      }
+    },
+    "required": ["gatewayUrl"]
+  }
+}

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "memory-search-plugin",
+  "version": "0.2.0",
+  "type": "module",
+  "main": "index.ts",
+  "files": [
+    "*.ts",
+    "openclaw.plugin.json",
+    "!*.test.ts"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ]
+  }
+}