openclaw-memory-alibaba-local 0.1.4 → 0.1.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-memory-alibaba-local",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "OpenClaw memory plugin: local LanceDB + DashScope-compatible embeddings",
   "type": "module",
   "license": "MIT",
@@ -20,8 +20,7 @@
     "*.ts",
     "web/**/*.ts",
     "openclaw.plugin.json",
-    "README.md",
-    "API.md"
+    "README.md"
   ],
   "dependencies": {
     "@lancedb/lancedb": "^0.27.1",

package/web/memory-admin-ops.ts

@@ -18,7 +18,7 @@ import {
   USER_MEMORY_CATEGORIES,
   isFullContextSourceCategory,
 } from "../categories.js";
-import type { AdminListFilters, MemoryDB } from "../db.js";
+import type { AdminListFilters, MemoryDashboardAggregate, MemoryDB, MemoryEntry } from "../db.js";
 
 const MANUAL_ADD_MAX_CHARS = 8000;
 
@@ -83,17 +83,37 @@ function tabToCategories(tab: string, cfg: MemoryConfig): MemoryCategory[] {
   return [...USER_MEMORY_CATEGORIES];
 }
 
-function parseOptionalTimeMs(iso: string | null | undefined): number | undefined {
-  if (!iso) {
+/** Epoch ms → ISO 8601 UTC（如 `2026-03-25T06:28:00.000Z`）。 */
+export function epochMsToIso8601(ms: number): string {
+  return new Date(ms).toISOString();
+}
+
+/**
+ * 管理 RPC 时间筛选：优先 **ISO 8601 字符串**；仍接受 **数字毫秒**（兼容旧客户端）。
+ */
+function parseOptionalTimeParam(value: unknown): number | undefined {
+  if (value == null || value === "") {
     return undefined;
   }
-  const t = Date.parse(String(iso));
-  if (Number.isNaN(t)) {
-    return undefined;
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return Math.floor(value);
   }
-  return t;
+  const t = Date.parse(String(value));
+  return Number.isNaN(t) ? undefined : t;
 }
 
+export type MemoryAdminListItemRpc = Omit<MemoryEntry, "createdAt"> & { createdAt: string };
+
+function memoryEntryToRpcPayload(e: MemoryEntry): MemoryAdminListItemRpc {
+  return { ...e, createdAt: epochMsToIso8601(e.createdAt) };
+}
+
+/** 大盘 RPC 出参：`timeFrom` / `timeTo` 为 ISO 8601，不再返回 `timeFromMs` / `timeToMs`。 */
+export type MemoryDashboardAggregateRpc = Omit<MemoryDashboardAggregate, "timeFromMs" | "timeToMs"> & {
+  timeFrom: string;
+  timeTo: string;
+};
+
 async function ensureDb(ctx: MemoryAdminOpsContext): Promise<AdminOpResult<null>> {
   try {
     await ctx.db.ensureReady();
@@ -132,10 +152,14 @@ export async function opMemoryAdminDashboard(
   if (!r.ok) {
     return r;
   }
-  const timeFromMs = parseOptionalTimeMs(params.timeFrom as string | undefined);
-  const timeToMs = parseOptionalTimeMs(params.timeTo as string | undefined);
+  const timeFromMs = parseOptionalTimeParam(params.timeFrom);
+  const timeToMs = parseOptionalTimeParam(params.timeTo);
   if (timeFromMs === undefined || timeToMs === undefined) {
-    return { ok: false, status: 400, body: { error: "timeFrom and timeTo are required (ISO 8601)" } };
+    return {
+      ok: false,
+      status: 400,
+      body: { error: "timeFrom and timeTo are required (ISO 8601 strings, e.g. 2026-03-25T06:28:00.000Z)" },
+    };
   }
   const agentId = String(params.agentId ?? "").trim();
   const sessionId = String(params.sessionId ?? "").trim();
@@ -144,7 +168,13 @@ export async function opMemoryAdminDashboard(
   }
   try {
     const agg = await ctx.db.getAdminDashboardAggregates(timeFromMs, timeToMs, agentId, sessionId);
-    return { ok: true, data: agg };
+    const { timeFromMs: fromMs, timeToMs: toMs, ...rest } = agg;
+    const data: MemoryDashboardAggregateRpc = {
+      ...rest,
+      timeFrom: epochMsToIso8601(fromMs),
+      timeTo: epochMsToIso8601(toMs),
+    };
+    return { ok: true, data };
   } catch (e) {
     return { ok: false, status: 400, body: { error: String(e) } };
   }
@@ -169,8 +199,8 @@ export async function opMemoryAdminList(
   if (baseCats.length === 0) {
     return { ok: true, data: { items: [], total: 0, page: 1, pageSize: 100 } };
   }
-  const timeFromMs = parseOptionalTimeMs(params.timeFrom as string | undefined);
-  const timeToMs = parseOptionalTimeMs(params.timeTo as string | undefined);
+  const timeFromMs = parseOptionalTimeParam(params.timeFrom);
+  const timeToMs = parseOptionalTimeParam(params.timeTo);
   const page = Math.max(1, parseInt(String(params.page || "1"), 10) || 1);
   const pageSize = Math.min(500, Math.max(1, parseInt(String(params.limit || "100"), 10) || 100));
 
@@ -205,7 +235,10 @@ export async function opMemoryAdminList(
       adminTab,
       sortDesc,
     });
-    return { ok: true, data: { items, total, page, pageSize } };
+    return {
+      ok: true,
+      data: { items: items.map(memoryEntryToRpcPayload), total, page, pageSize },
+    };
   } catch (e) {
     return { ok: false, status: 400, body: { error: String(e) } };
   }
@@ -296,7 +329,7 @@ export async function opMemoryAdminAdd(
     ok: true,
     data: {
       id: stored[0]!.id,
-      createdAt: stored[0]!.createdAt,
+      createdAt: epochMsToIso8601(stored[0]!.createdAt),
       chunkRows: stored.length,
     },
   };

package/web/memory-routes.ts

@@ -18,6 +18,7 @@ import {
   opMemoryAdminDelete,
   opMemoryAdminFacets,
   opMemoryAdminList,
+  type AdminOpResult,
   type MemoryAdminOpsContext,
   type MemoryAdminOpsOpts,
 } from "./memory-admin-ops.js";
@@ -83,7 +84,7 @@ function sendHtml(res: ServerResponse, html: string): void {
   res.end(html);
 }
 
-function applyAdminOpResult(respond: GatewayRequestHandlerOptions["respond"], result: import("./memory-admin-ops.js").AdminOpResult): void {
+function applyAdminOpResult(respond: GatewayRequestHandlerOptions["respond"], result: AdminOpResult): void {
   if (result.ok) {
     respond(true, result.data);
     return;
@@ -168,8 +169,49 @@ export function registerMemoryAdminGatewayMethods(
   logger.info("[openclaw-memory-alibaba-local] Memory admin Gateway methods: memory.admin.* (config, facets, dashboard, list, delete, add)");
 }
 
+async function readJsonBody(req: IncomingMessage, maxBytes = 2 * 1024 * 1024): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    let n = 0;
+    req.on("data", (chunk: Buffer) => {
+      n += chunk.length;
+      if (n > maxBytes) {
+        req.destroy();
+        reject(new Error("body too large"));
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+    req.on("error", reject);
+  });
+}
+
+async function dispatchMemoryAdminRpc(
+  ctx: MemoryAdminOpsContext,
+  method: string,
+  params: unknown,
+): Promise<AdminOpResult> {
+  switch (method) {
+    case "memory.admin.config":
+      return opMemoryAdminConfig(ctx);
+    case "memory.admin.facets":
+      return opMemoryAdminFacets(ctx);
+    case "memory.admin.dashboard":
+      return opMemoryAdminDashboard(ctx, (params as Record<string, unknown>) ?? {});
+    case "memory.admin.list":
+      return opMemoryAdminList(ctx, (params as Record<string, unknown>) ?? {});
+    case "memory.admin.delete":
+      return opMemoryAdminDelete(ctx, (params as Record<string, unknown>) ?? {});
+    case "memory.admin.add":
+      return opMemoryAdminAdd(ctx, (params as Record<string, unknown>) ?? {});
+    default:
+      return { ok: false, status: 404, body: { error: "unknown method", method } };
+  }
+}
+
 /**
- * HTTP: serves HTML at /plugins/memory; legacy /plugins/memory/api/* returns 410 with migration hint.
+ * HTTP: HTML at /plugins/memory；同源 HTTP POST /plugins/memory/api/v1/call 供非本机访问（仅需 gateway token，不经 WS operator scope）。
  */
 export function registerMemoryPanelRoutes(
   registerHttpRoute: RegisterHttpRoute,
@@ -178,9 +220,11 @@ export function registerMemoryPanelRoutes(
   logger: PluginLogger,
   opts?: MemoryPanelRoutesOpts | null,
 ): void {
-  void db;
-  void cfg;
-  void opts;
+  const ctxBase: MemoryAdminOpsContext = {
+    db,
+    cfg,
+    opts: opts ?? undefined,
+  };
   const requiredToken = resolveGatewayToken();
   const token = typeof requiredToken === "string" && requiredToken.length > 0 ? requiredToken : undefined;
 
@@ -204,9 +248,44 @@ export function registerMemoryPanelRoutes(
               return true;
             }
           }
-          sendJson(res, 410, {
-            error: "HTTP JSON API removed",
-            detail: "Use Gateway WebSocket RPC methods: memory.admin.config, memory.admin.facets, memory.admin.dashboard, memory.admin.list, memory.admin.delete, memory.admin.add",
+
+          if (p === "/plugins/memory/api/v1/call" && req.method === "POST") {
+            let raw: string;
+            try {
+              raw = await readJsonBody(req);
+            } catch {
+              sendJson(res, 400, { error: "invalid body" });
+              return true;
+            }
+            let body: { method?: string; params?: unknown };
+            try {
+              body = JSON.parse(raw || "{}") as { method?: string; params?: unknown };
+            } catch {
+              sendJson(res, 400, { error: "invalid json" });
+              return true;
+            }
+            const method = typeof body.method === "string" ? body.method.trim() : "";
+            if (!method) {
+              sendJson(res, 400, { error: "missing method" });
+              return true;
+            }
+            try {
+              const result = await dispatchMemoryAdminRpc(ctxBase, method, body.params ?? {});
+              if (result.ok) {
+                sendJson(res, 200, result.data as unknown);
+              } else {
+                sendJson(res, result.status, { ...result.body, status: result.status });
+              }
+            } catch (e) {
+              logger.warn(`memory api/v1/call ${method}: ${String(e)}`);
+              sendJson(res, 500, { error: String(e) });
+            }
+            return true;
+          }
+
+          sendJson(res, 404, {
+            error: "not found",
+            detail: "POST /plugins/memory/api/v1/call with JSON { method, params } (same as memory.admin.* WebSocket RPC)",
           });
           return true;
         }
@@ -221,5 +300,7 @@ export function registerMemoryPanelRoutes(
     },
   });
 
-  logger.info("[openclaw-memory-alibaba-local] Memory admin UI at /plugins/memory/ (data via WebSocket memory.admin.*)");
+  logger.info(
+    "[openclaw-memory-alibaba-local] Memory admin UI at /plugins/memory/ (WS memory.admin.* on loopback; HTTP POST .../api/v1/call for remote)",
+  );
 }

package/web/memory-ui.ts

@@ -1102,10 +1102,76 @@ function buildClientScript(): string {
     });
   }
 
+  /**
+   * 非本机 hostname（公网 IP / 域名）时 Gateway WebSocket 会剥离 operator.admin；同源 HTTP 仅需 gateway token（与观测插件一致）。
+   */
+  async function fetchMemoryApiHttp(method, params) {
+    var tok = getGatewayToken();
+    var headers = { "Content-Type": "application/json" };
+    if (tok) {
+      headers["Authorization"] = "Bearer " + tok;
+    }
+    var resp;
+    try {
+      resp = await fetch("/plugins/memory/api/v1/call", {
+        method: "POST",
+        headers: headers,
+        body: JSON.stringify({ method: method, params: params || {} })
+      });
+    } catch (e) {
+      return {
+        ok: false,
+        status: 0,
+        json: function () {
+          return Promise.resolve({ error: String(e) });
+        },
+        text: function () {
+          return Promise.resolve(String(e));
+        }
+      };
+    }
+    var j;
+    try {
+      j = await resp.json();
+    } catch (e2) {
+      j = { error: "invalid JSON response" };
+    }
+    if (resp.ok) {
+      return {
+        ok: true,
+        status: 200,
+        json: function () {
+          return Promise.resolve(j);
+        },
+        text: function () {
+          return Promise.resolve("");
+        }
+      };
+    }
+    var st = resp.status;
+    if (j && typeof j.status === "number" && Number.isFinite(j.status)) {
+      st = j.status;
+    }
+    return {
+      ok: false,
+      status: st,
+      json: function () {
+        return Promise.resolve(j);
+      },
+      text: function () {
+        return Promise.resolve(String((j && j.error) || resp.status));
+      }
+    };
+  }
+
   /** 与原先 fetch 类似的接口：ok / status / json() / text() */
   async function fetchMemoryApi(method, params) {
+    var p = params || {};
+    if (!isMemoryPanelLoopbackHost()) {
+      return fetchMemoryApiHttp(method, p);
+    }
     try {
-      var res = await gatewayRpc(method, params || {});
+      var res = await gatewayRpc(method, p);
       if (res.ok) {
         return {
           ok: true,
@@ -1118,6 +1184,12 @@ function buildClientScript(): string {
           }
         };
       }
+      if (res.unauthorized) {
+        var httpRes = await fetchMemoryApiHttp(method, p);
+        if (httpRes.ok) {
+          return httpRes;
+        }
+      }
       var st = res.payload && res.payload.status ? parseInt(String(res.payload.status), 10) : 0;
       if (!Number.isFinite(st) || st < 400) {
         st = res.unauthorized ? 403 : 502;

package/API.md

@@ -1,917 +0,0 @@
-# openclaw-memory-alibaba-local — 接口说明
-
-本文说明**记忆管理面板**与 **Agent 工具**相关接口。管理面板的**数据接口**已改为 **Gateway WebSocket RPC**（与 OpenClaw 网关协议一致）；仅 **HTML 壳**仍通过 HTTP 提供。
-
-- **网关根 URL**：以部署为准，例如 `http://127.0.0.1:12345`，下文记为 `{GATEWAY}`。
-- **WebSocket**：`ws://` 或 `wss://` + 与 HTTP 相同的 `host`（同端口）。
-- **HTML 壳**：`{GATEWAY}/plugins/memory`（前缀匹配）。
-
-**类型约定**
-
-| 文档中的类型 | 含义 |
-|--------------|------|
-| `string` / `number` / `boolean` | JSON 基本类型 |
-| `object` | JSON **对象**（键值对；与语言里的 Map 类似，但是标准 JSON） |
-| `T[]` / `array` | JSON **数组**；若元素为对象，文档在下方单独给出「数组元素结构」表 |
-| `—` | 不适用（如响应头说明） |
-
----
-
-## 一、Gateway WebSocket RPC（管理面板数据）
-
-### 1.1 连接与鉴权
-
-1. 浏览器建立 `WebSocket` 到 `{WS_GATEWAY}`（与页面同源：`location` 的 host + `ws:`/`wss:`）。
-2. 服务端先推送事件 `connect.challenge`（`payload.nonce`）。
-3. 客户端发送首帧请求（OpenClaw 协议）。**内嵌面板**按页面 hostname 选择 `client`（与网关 `isLocalClient`、是否清空 `scopes` 一致）：
-
-   - **回环**：`localhost` / `127.0.0.1` / `::1` → `id: "openclaw-control-ui"`，`mode: "ui"`。
-   - **非回环**（如局域网 IP、自定义域名）：`id: "openclaw-probe"`，`mode: "probe"`（避免 Control UI 在非本机 HTTP 下直接握手失败）。
-
-```json
-{
-  "type": "req",
-  "id": "<任意唯一字符串>",
-  "method": "connect",
-  "params": {
-    "minProtocol": 3,
-    "maxProtocol": 3,
-    "client": {
-      "id": "openclaw-control-ui",
-      "version": "memory-panel",
-      "platform": "<navigator.platform 或 web>",
-      "mode": "ui"
-    },
-    "role": "operator",
-    "scopes": ["operator.admin"],
-    "auth": { "token": "<与 openclaw.json gateway.auth.token 一致>" }
-  }
-}
-```
-
-4. 成功时收到 `type: "res"` 且 `ok: true`，`payload` 内含 `hello-ok` 等网关握手信息。浏览器连接会校验来源（`gateway.controlUi.allowedOrigins` 等），与官方 Control UI 一致。
-
-   **HTTP + `?token=` 时的 `openclaw.json`（`gateway.controlUi`）**：
-
-   | 访问方式 | 典型配置 |
-   |----------|----------|
-   | 本机 `http://127.0.0.1` / `localhost` + Control UI 客户端 | **`allowInsecureAuth: true`**（否则握手报错 *control ui requires device identity*） |
-   | 局域网 IP / 非回环 hostname + Probe 客户端 | 除 token 外通常需 **`dangerouslyDisableDeviceAuth: true`**，否则握手可成功但网关会**清空 `scopes`**，`memory.admin.*` 报 *missing scope*（面板 403/502） |
-   | 生产/跨机更稳妥 | **HTTPS** + 设备配对，或 SSH 转发到本机后用 `127.0.0.1` + `allowInsecureAuth` |
-
-   示例（本机开发常见）：
-
-```json
-"gateway": {
-  "controlUi": {
-    "allowInsecureAuth": true
-  }
-}
-```
-
-   局域网浏览器直连网关时（面板已用 probe 客户端）示例：
-
-```json
-"gateway": {
-  "controlUi": {
-    "dangerouslyDisableDeviceAuth": true
-  }
-}
-```
-
-5. 后续业务请求均为：
-
-```json
-{ "type": "req", "id": "<唯一>", "method": "<下表 method>", "params": { } }
-```
-
-成功：`{ "type": "res", "id": "…", "ok": true, "payload": <与原先 HTTP JSON 响应体相同> }`  
-失败：`ok: false`，`error.message` 为人类可读原因；部分失败同时带 `payload`（如 `{ "error": "…", "status": 400 }`）。
-
-### 1.2 管理方法一览
-
-| `method` | 说明 | `params`（JSON object） | 成功时 `payload` |
-|----------|------|---------------------------|------------------|
-| `memory.admin.config` | 面板配置 | 无必填字段 | 同原 `GET …/api/config` 响应 |
-| `memory.admin.facets` | 下拉去重值 | 可选 `tab`（保留字段，服务端可忽略） | 同原 `GET …/api/facets` |
-| `memory.admin.dashboard` | 大盘统计 | `timeFrom`, `timeTo`（ISO 8601）、`agentId`；可选 `sessionId` | 同原 `GET …/api/dashboard` |
-| `memory.admin.list` | 分页列表 | `tab`, `agentId`；可选 `sessionId`, `timeFrom`, `timeTo`, `category`, `page`, `limit`, `sortDesc`（布尔，默认 true） | 同原 `GET …/api/list` |
-| `memory.admin.delete` | 批量删除 | `items`: `{ agentId, id }[]` | 同原 `POST …/api/delete` |
-| `memory.admin.add` | 手工插入 | `agentId`, `text`, `category` | 同原 `POST …/api/add` |
-
-### 1.3 废弃的 HTTP JSON
-
-| 路径 | 行为 |
-|------|------|
-| `GET/POST {GATEWAY}/plugins/memory/api/*` | 若配置了 gateway token，仍校验 `?token=` 或 `Authorization: Bearer`；校验通过后返回 **`410 Gone`**，body 提示改用 WebSocket `memory.admin.*`。 |
-
----
-
-## 二、HTTP（仅 HTML 壳）
-
-### 2.1 `GET /plugins/memory`
-
-| 项目 | 说明 |
-|------|------|
-| **功能** | 返回记忆管理端单页 HTML（壳页面；数据由 `/api/*` 拉取） |
-| **URI** | `{GATEWAY}/plugins/memory` |
-
-**入参**
-
-| 参数 | 位置 | 类型 | 必须 | 合法值 / 说明 | 默认值 |
-|------|------|------|------|----------------|--------|
-| — | — | — | — | 无查询参数 | — |
-
-**出参**（成功 `200`）
-
-| 字段 / 项 | 类型 | 说明 |
-|-----------|------|------|
-| 响应体 | `string` | HTML 文档 |
-| 响应头 `Content-Type` | — | `text/html; charset=utf-8` |
-
----
-
-### 2.2 参考：`memory.admin.config`（原 `GET …/api/config`）
-
-| 项目 | 说明 |
-|------|------|
-| **功能** | 返回面板开关、Tab 类别、中文标签、列表筛选项等 |
-| **URI** | `{GATEWAY}/plugins/memory/api/config` |
-
-**入参**
-
-| 参数 | 位置 | 类型 | 必须 | 合法值 / 说明 | 默认值 |
-|------|------|------|------|----------------|--------|
-| — | — | — | — | 无 | — |
-
-**出参**（成功 `200`，`application/json`）
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `enableFullContextMemory` | `boolean` | 是否开启全文类记忆 |
-| `enableSelfImprovingMemory` | `boolean` | 是否开启自进化类记忆 |
-| `categoryLabelsZh` | `object` | 键：记忆类型代码 `string` → 值：中文展示名 `string`（动态键，无固定子字段表） |
-| `tabCategories` | `object` | 固定三键，见下表「`tabCategories` 对象结构」 |
-| `memoryTypeFilterOptions` | `object` | 固定三键，见下表「`memoryTypeFilterOptions` 对象结构」 |
-
-**`tabCategories` 对象结构**（键固定）
-
-| 键 | 类型 | 说明 |
-|----|------|------|
-| `user` | `string[]` | 用户 Tab 下的类型代码列表 |
-| `self` | `string[]` | 自进化 Tab；功能关闭时可能为 `[]` |
-| `full` | `string[]` | 全文 Tab；功能关闭时可能为 `[]` |
-
-**`memoryTypeFilterOptions` 对象结构**（键固定）
-
-| 键 | 类型 | 说明 |
-|----|------|------|
-| `user` | `object[]` | 筛选项列表，元素结构见下表 |
-| `self` | `object[]` | 同上 |
-| `full` | `object[]` | 同上 |
-
-**`memoryTypeFilterOptions.*` 数组元素（object）**
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `category` | `string` | 记忆类型代码 |
-| `labelZh` | `string` | 界面展示用中文 |
-
----
-
-### 2.3 参考：`memory.admin.facets`（原 `GET …/api/facets`）
-
-| 项目 | 说明 |
-|------|------|
-| **功能** | 返回库中出现过的去重 `agentId`、`sessionId`（供下拉框） |
-| **URI** | `{GATEWAY}/plugins/memory/api/facets` |
-
-**入参**
-
-| 参数 | 位置 | 类型 | 必须 | 合法值 / 说明 | 默认值 |
-|------|------|------|------|----------------|--------|
-| — | — | — | — | 无 | — |
-
-**出参**（成功 `200`，`application/json`）
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `agents` | `string[]` | 已排序的去重 Agent ID |
-| `sessions` | `string[]` | 已排序的去重会话 ID |
-
----
-
-### 2.4 参考：`memory.admin.dashboard`（原 `GET …/api/dashboard`）
-
-| 项目 | 说明 |
-|------|------|
-| **功能** | 指定时间范围 + Agent（可选会话）下的记忆大盘统计 |
-| **URI** | `{GATEWAY}/plugins/memory/api/dashboard` |
-
-**入参**
-
-| 参数 | 位置 | 类型 | 必须 | 合法值 / 说明 | 默认值 |
-|------|------|------|------|----------------|--------|
-| `timeFrom` | query | `string` | **是** | ISO 8601，须可被 `Date.parse` 解析 | 无 |
-| `timeTo` | query | `string` | **是** | 同上 | 无 |
-| `agentId` | query | `string` | **是** | 非空（trim 后） | 无 |
-| `sessionId` | query | `string` | 否 | 非空则仅统计该会话；空表示不限 | 空 |
-
-**出参**（成功 `200`，`application/json`）
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `total` | `number` | 满足条件的记忆条数 |
-| `timeFromMs` | `number` | 起始时间毫秒时间戳 |
-| `timeToMs` | `number` | 结束时间毫秒时间戳 |
-| `byKind` | `object` | 四大类条数，子结构见下表 |
-| `byCategory` | `object` | 键：类型代码 `string` → 值：条数 `number`（动态键） |
-| `byBucket` | `object[]` | 时间趋势桶，元素结构见下表 |
-| `topAgents` | `object[]` | 条数 Top Agent，**最多 10 条**，元素结构见下表 |
-| `topSessions` | `object[]` | 条数 Top 会话，**最多 10 条**，元素结构见下表 |
-| `importance` | `object` | 重要程度分档，子结构见下表 |
-| `uniqueAgents` | `number` | 去重 Agent 数 |
-| `uniqueSessions` | `number` | 去重会话数 |
-
-**`byKind` 对象结构**
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `user` | `number` | 用户记忆类（`user_memory_*`） |
-| `self` | `number` | 自进化类（`self_improving_*`） |
-| `full` | `number` | 全文相关（含 `full_context_memory` 与 `full_context_*`） |
-| `other` | `number` | 其余类型 |
-
-**`byBucket` 数组元素（object）**
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `key` | `string` | 桶标识（如月份 `YYYY-MM` 或序号） |
-| `label` | `string` | 展示用标签 |
-| `count` | `number` | 该桶内条数 |
-
-说明：跨度 ≤48 小时按**小时**桶；跨度大于 60 天按**本地自然月**桶；否则按**日**桶。
-
-**`topAgents` 数组元素（object）**
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `agentId` | `string` | Agent ID |
-| `count` | `number` | 条数 |
-
-**`topSessions` 数组元素（object）**
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `sessionId` | `string` | 会话 ID |
-| `count` | `number` | 条数 |
-
-**`importance` 对象结构**
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `low` | `number` | 重要度小于 0.34 的条数 |
-| `mid` | `number` | 重要度大于等于 0.34 且小于 0.67 |
-| `high` | `number` | 重要度不小于 0.67 |
-| `avg` | `number` | 有效重要度的平均值；无有效值时为 `0` |
-
-**失败** `400`：缺少/非法时间、缺少 `agentId`、或命中行数超过约 5 万等，body 多为 `{ "error": string }`。
-
----
-
-### 2.5 参考：`memory.admin.list`（原 `GET …/api/list`；RPC 中 `sortDesc` 为 **boolean**，`page`/`limit` 为 **number**）
-
-| 项目 | 说明 |
-|------|------|
-| **功能** | 分页列出记忆行（Tab 对应类别集合；全文 Tab 按 `batchId` 分组排序） |
-| **URI** | `{GATEWAY}/plugins/memory/api/list` |
-
-**入参**
-
-| 参数 | 位置 | 类型 | 必须 | 合法值 / 说明 | 默认值 |
-|------|------|------|------|----------------|--------|
-| `agentId` | query | `string` | **是** | 非空 | 无 |
-| `tab` | query | `string` | 否 | `user` \| `self` \| `full`，决定基础类别集合 | `user` |
-| `sessionId` | query | `string` | 否 | 仅该会话 | 空（不限） |
-| `timeFrom` | query | `string` | 否 | ISO 8601，过滤创建时间下限 | 不限 |
-| `timeTo` | query | `string` | 否 | ISO 8601，过滤创建时间上限 | 不限 |
-| `category` | query | `string` | 否 | 须属当前 Tab 类别且出现在该 Tab 的 `memoryTypeFilterOptions` 中 | 不按子类型过滤 |
-| `page` | query | `number` | 否 | 正整数页码 | `1` |
-| `limit` | query | `number` | 否 | 每页 1～500 | `100` |
-| `sortDesc` | query | `string` | 否 | 传 `"false"` 时部分 Tab 改为时间升序；否则降序 | 降序 |
-
-**出参**（成功 `200`，`application/json`）
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `items` | `object[]` | 当前页记忆行，元素结构见下表 |
-| `total` | `number` | 符合条件的总条数（分页前） |
-| `page` | `number` | 当前页码 |
-| `pageSize` | `number` | 本页条数（对应请求中的 `limit`） |
-
-**`items` 数组元素（object）**
-
-| 字段 | 类型 | 必填（于对象内） | 说明 |
-|------|------|------------------|------|
-| `id` | `string` | 是 | 行 UUID，删除时与 `agentId` 一起提交 |
-| `agentId` | `string` | 是 | Agent ID |
-| `sessionId` | `string` | 是 | 会话 ID，可能为空字符串 `""` |
-| `text` | `string` | 是 | 正文 |
-| `importance` | `number` | 是 | 重要程度 |
-| `category` | `string` | 是 | 类型代码 |
-| `createdAt` | `number` | 是 | 创建时间（毫秒时间戳） |
-| `isDeleted` | `number` | 是 | 列表一般为未删除数据，常见 `0` |
-| `batchId` | `string` | 否 | 全文快照批次 ID，用于成组展示 |
-| `seqInBatch` | `number` | 否 | 批次内顺序 |
-| `chunkIndex` | `number` | 否 | 多向量段时序号 |
-
-**失败** `400`：`agentId` 缺失、`category` 与 Tab 不匹配、匹配过多等。
-
-**特例**（功能关闭的 Tab）：`items` 为 `[]`，`total` 为 `0`，`page` 为 `1`，`pageSize` 为 `100`。
-
----
-
-### 2.6 参考：`memory.admin.delete`（原 `POST …/api/delete`）
-
-| 项目 | 说明 |
-|------|------|
-| **功能** | 按行 ID 批量硬删除 |
-| **URI** | `{GATEWAY}/plugins/memory/api/delete` |
-| **Content-Type** | `application/json`（请求） |
-| **Body 上限** | 约 64KB |
-
-**入参（Body JSON）**
-
-| 参数 | 位置 | 类型 | 必须 | 合法值 / 说明 | 默认值 |
-|------|------|------|------|----------------|--------|
-| `items` | body | `object[]` | **是** | 至少 1 个元素；元素结构见下表 | 无 |
-
-**`items` 数组元素（object）**
-
-| 字段 | 类型 | 必须 | 说明 |
-|------|------|------|------|
-| `agentId` | `string` | **是** | 非空 |
-| `id` | `string` | **是** | 行 UUID |
-
-**出参**（成功 `200`，`application/json`）
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `deleted` | `number` | 实际删除条数 |
-
-说明：缺 `agentId` 或 `id` 的项会被跳过；若有效项为 0，返回 `400`，`error` 为 `items required`。
-
----
-
-### 2.7 参考：`memory.admin.add`（原 `POST …/api/add`）
-
-| 项目 | 说明 |
-|------|------|
-| **功能** | 管理端手工写入一条逻辑记忆（可对应多段向量行） |
-| **URI** | `{GATEWAY}/plugins/memory/api/add` |
-| **Content-Type** | `application/json` |
-| **Body 上限** | 约 64KB |
-
-**入参（Body JSON）**
-
-| 参数 | 位置 | 类型 | 必须 | 合法值 / 说明 | 默认值 |
-|------|------|------|------|----------------|--------|
-| `agentId` | body | `string` | **是** | 非空（trim） | 无 |
-| `text` | body | `string` | **是** | trim 后非空；超长按约 8000 字符截断 | 无 |
-| `category` | body | `string` | **是** | 见附录 A 与 config 开关；本接口不使用 `full_context_memory` 字面量 | 无 |
-
-写入行的 `sessionId` 固定为 `manual_insert`。
-
-**出参**（成功 `200`，`application/json`）
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `id` | `string` | 首段向量行的 UUID |
-| `createdAt` | `number` | 首行创建时间（毫秒时间戳） |
-| `chunkRows` | `number` | 写入的向量行数（段数） |
-
-**失败**：`400` / `502` / `503` 等，body 多为 `{ "error": string }`（见源码与运行时文案）。
-
----
-
-### 2.8 HTTP 调用示例（curl；**`/api/*` 已返回 410**，仅作 HTML 与历史对照）
-
-**环境**：`http://127.0.0.1:12345`，已配置 `gateway.auth.token`；下列 curl 中 **`GET/POST …/plugins/memory/api/*` 现已为 `410 Gone`**，请改用 **WebSocket `memory.admin.*`**。库内数据变化后，实测 JSON 会与下文摘录不同。
-
-```bash
-export GATEWAY="http://127.0.0.1:12345"
-export TOKEN="你的 gateway.auth.token"
-```
-
-鉴权：**请求头** `Authorization: Bearer $TOKEN`，或 **Query** `?token=$TOKEN`。
-
-**实测状态码一览**
-
-| 请求 | HTTP |
-|------|------|
-| `GET …/plugins/memory` | `200` |
-| `GET …/api/config`（Bearer） | **`410`**（已废弃） |
-| `GET …/api/config?token=` | **`410`** |
-| `GET …/api/facets` | **`410`** |
-| `GET …/api/dashboard`（带 timeFrom/timeTo/agentId） | **`410`** |
-| `GET …/api/list` | **`410`** |
-| `POST …/api/delete`，body `{"items":[]}` | **`410`** |
-| `POST …/api/add`（示例 body） | **`410`** |
-| `POST …/api/delete`（删掉刚插入的 id） | **`410`** |
-| `GET …/api/config`，错误 Bearer | **`410`** 或 `401`（先鉴权再 410） |
-
----
-
-**1）`GET /plugins/memory`（无 token）**
-
-```bash
-curl -sS -D - -o /tmp/memory_panel.html "$GATEWAY/plugins/memory" | head -n 12
-```
-
-**响应头（实测前若干行）**
-
-```http
-HTTP/1.1 200 OK
-X-Content-Type-Options: nosniff
-Referrer-Policy: no-referrer
-Permissions-Policy: camera=(), microphone=(), geolocation=()
-Content-Type: text/html; charset=utf-8
-Cache-Control: no-store, no-cache, must-revalidate
-Pragma: no-cache
-```
-
-**响应体**：HTML 单页（实测整页约 65KB）。正文开头如下，余下为内联样式与脚本。
-
-```html
-<!DOCTYPE html>
-<html lang="zh-CN">
-<head>
-<meta charset="utf-8"/>
-<meta name="viewport" content="width=device-width, initial-scale=1"/>
-<title>RDSClaw 记忆管理</title>
-<style>
-/* 与 OpenClaw Observability 面板一致的浅色卡片 + 红色主色 */
-:root {
-  font-family: system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
-  color: #212121;
-  background: #f5f5f5;
-  --oc-accent: #d32f2f;
-  --oc-accent-hover: #b71c1c;
-  --oc-secondary: #7e57c2;
-  --oc-border: #e0e0e0;
-  --oc-muted: #757575;
-  --oc-card: #ffffff;
-  --oc-page: #f5f5f5;
-}
-* { box-sizing: border-box; }
-input[type="checkbox"] { accent-color: var(--oc-accent); }
-body {
-  margin: 0;
-  padding: 20px 20px 32px;
-```
-
----
-
-**2）`GET /plugins/memory/api/config`**
-
-```bash
-curl -sS -H "Authorization: Bearer $TOKEN" \
-  "$GATEWAY/plugins/memory/api/config"
-```
-
-**响应体 `200`（实测 JSON，已格式化）**
-
-```json
-{
-  "enableFullContextMemory": true,
-  "enableSelfImprovingMemory": true,
-  "categoryLabelsZh": {
-    "user_memory_fact": "用户事实",
-    "user_memory_preference": "用户偏好",
-    "user_memory_decision": "用户决策",
-    "full_context_memory": "全文记忆",
-    "full_context_user": "全文 · 用户消息",
-    "full_context_assistant": "全文 · AI助手消息",
-    "full_context_system": "全文 · 系统消息",
-    "full_context_tool": "全文 · 工具调用",
-    "full_context_tool_result": "全文 · 工具结果",
-    "full_context_others": "全文 · 其他消息",
-    "self_improving_learnings": "最佳实践",
-    "self_improving_errors": "错误经验",
-    "self_improving_feature_requests": "行为诉求"
-  },
-  "tabCategories": {
-    "user": [
-      "user_memory_fact",
-      "user_memory_preference",
-      "user_memory_decision"
-    ],
-    "self": [
-      "self_improving_learnings",
-      "self_improving_errors",
-      "self_improving_feature_requests"
-    ],
-    "full": [
-      "full_context_user",
-      "full_context_assistant",
-      "full_context_system",
-      "full_context_tool",
-      "full_context_tool_result",
-      "full_context_others"
-    ]
-  },
-  "memoryTypeFilterOptions": {
-    "user": [
-      { "category": "user_memory_fact", "labelZh": "用户事实" },
-      { "category": "user_memory_preference", "labelZh": "用户偏好" },
-      { "category": "user_memory_decision", "labelZh": "用户决策" }
-    ],
-    "self": [
-      { "category": "self_improving_learnings", "labelZh": "最佳实践" },
-      { "category": "self_improving_errors", "labelZh": "错误经验" },
-      { "category": "self_improving_feature_requests", "labelZh": "行为诉求" }
-    ],
-    "full": [
-      { "category": "full_context_user", "labelZh": "全文 · 用户消息" },
-      { "category": "full_context_assistant", "labelZh": "全文 · AI助手消息" },
-      { "category": "full_context_system", "labelZh": "全文 · 系统消息" },
-      { "category": "full_context_tool", "labelZh": "全文 · 工具调用" },
-      { "category": "full_context_tool_result", "labelZh": "全文 · 工具结果" },
-      { "category": "full_context_others", "labelZh": "全文 · 其他消息" }
-    ]
-  }
-}
-```
-
----
-
-**3）Query 传 token（与 Bearer 等价，实测 body 与上条一致）**
-
-```bash
-curl -sS "$GATEWAY/plugins/memory/api/config?token=$TOKEN"
-```
-
-**响应体**：与 **2）** 相同（实测与 Bearer 返回同一 JSON）。
-
----
-
-**4）`GET /plugins/memory/api/facets`**
-
-```bash
-curl -sS -H "Authorization: Bearer $TOKEN" \
-  "$GATEWAY/plugins/memory/api/facets"
-```
-
-**响应体 `200`（实测）**
-
-```json
-{
-  "agents": ["main"],
-  "sessions": [
-    "agent:main:main",
-    "session:67505b88-3019-4c5a-88e2-53fe10abc8da",
-    "session:7e4de4fd-153c-4d14-a558-898486323f32",
-    "session:8b8fcf30-df6c-4361-85e1-007cf3390f9f",
-    "session:97dab399-a12b-409d-a4a7-52ab04c16085",
-    "session:afca0e5d-0de8-48a2-885e-c6494d988849",
-    "session:ca4f769f-ab45-40b9-8e7c-6c16e830dd99",
-    "session:cfdce68f-9a35-4e80-aae4-90501f31538e",
-    "session:e2e-1774361036",
-    "session:e7693a60-62de-4783-ab6b-a532b8995594",
-    "session:mem-empty-1774359591"
-  ]
-}
-```
-
----
-
-**5）`GET /plugins/memory/api/dashboard`**
-
-```bash
-curl -sS -G -H "Authorization: Bearer $TOKEN" \
-  --data-urlencode "timeFrom=2025-01-01T00:00:00.000Z" \
-  --data-urlencode "timeTo=2026-12-31T23:59:59.999Z" \
-  --data-urlencode "agentId=main" \
-  "$GATEWAY/plugins/memory/api/dashboard"
-```
-
-**响应体 `200`（实测，已格式化）**
-
-```json
-{
-  "total": 1520,
-  "timeFromMs": 1735689600000,
-  "timeToMs": 1798761599999,
-  "byKind": { "user": 20, "self": 30, "full": 1470, "other": 0 },
-  "byCategory": {
-    "full_context_user": 135,
-    "full_context_tool_result": 1095,
-    "full_context_assistant": 240,
-    "user_memory_preference": 5,
-    "user_memory_fact": 15,
-    "self_improving_errors": 2,
-    "self_improving_learnings": 26,
-    "self_improving_feature_requests": 2
-  },
-  "byBucket": [
-    { "key": "2025-01", "label": "2025-01", "count": 0 },
-    { "key": "2025-02", "label": "2025-02", "count": 0 },
-    { "key": "2025-03", "label": "2025-03", "count": 0 },
-    { "key": "2025-04", "label": "2025-04", "count": 0 },
-    { "key": "2025-05", "label": "2025-05", "count": 0 },
-    { "key": "2025-06", "label": "2025-06", "count": 0 },
-    { "key": "2025-07", "label": "2025-07", "count": 0 },
-    { "key": "2025-08", "label": "2025-08", "count": 0 },
-    { "key": "2025-09", "label": "2025-09", "count": 0 },
-    { "key": "2025-10", "label": "2025-10", "count": 0 },
-    { "key": "2025-11", "label": "2025-11", "count": 0 },
-    { "key": "2025-12", "label": "2025-12", "count": 0 },
-    { "key": "2026-01", "label": "2026-01", "count": 0 },
-    { "key": "2026-02", "label": "2026-02", "count": 0 },
-    { "key": "2026-03", "label": "2026-03", "count": 1520 },
-    { "key": "2026-04", "label": "2026-04", "count": 0 },
-    { "key": "2026-05", "label": "2026-05", "count": 0 },
-    { "key": "2026-06", "label": "2026-06", "count": 0 },
-    { "key": "2026-07", "label": "2026-07", "count": 0 },
-    { "key": "2026-08", "label": "2026-08", "count": 0 },
-    { "key": "2026-09", "label": "2026-09", "count": 0 },
-    { "key": "2026-10", "label": "2026-10", "count": 0 },
-    { "key": "2026-11", "label": "2026-11", "count": 0 },
-    { "key": "2026-12", "label": "2026-12", "count": 0 },
-    { "key": "2027-01", "label": "2027-01", "count": 0 }
-  ],
-  "topAgents": [{ "agentId": "main", "count": 1520 }],
-  "topSessions": [
-    { "sessionId": "session:e7693a60-62de-4783-ab6b-a532b8995594", "count": 871 },
-    { "sessionId": "agent:main:main", "count": 305 },
-    { "sessionId": "session:8b8fcf30-df6c-4361-85e1-007cf3390f9f", "count": 113 },
-    { "sessionId": "session:67505b88-3019-4c5a-88e2-53fe10abc8da", "count": 104 },
-    { "sessionId": "session:7e4de4fd-153c-4d14-a558-898486323f32", "count": 29 },
-    { "sessionId": "session:mem-empty-1774359591", "count": 28 },
-    { "sessionId": "session:afca0e5d-0de8-48a2-885e-c6494d988849", "count": 28 },
-    { "sessionId": "session:cfdce68f-9a35-4e80-aae4-90501f31538e", "count": 21 },
-    { "sessionId": "session:97dab399-a12b-409d-a4a7-52ab04c16085", "count": 8 },
-    { "sessionId": "session:ca4f769f-ab45-40b9-8e7c-6c16e830dd99", "count": 7 }
-  ],
-  "importance": {
-    "low": 0,
-    "mid": 17,
-    "high": 1503,
-    "avg": 0.6994736842105452
-  },
-  "uniqueAgents": 1,
-  "uniqueSessions": 11
-}
-```
-
----
-
-**6）`GET /plugins/memory/api/list`**
-
-```bash
-curl -sS -G -H "Authorization: Bearer $TOKEN" \
-  --data-urlencode "agentId=main" \
-  --data-urlencode "tab=user" \
-  --data-urlencode "page=1" \
-  --data-urlencode "limit=2" \
-  "$GATEWAY/plugins/memory/api/list"
-```
-
-**响应体 `200`（实测）**
-
-```json
-{
-  "items": [
-    {
-      "id": "861dcc43-66be-4a55-8157-bad77fc60e17",
-      "agentId": "main",
-      "sessionId": "session:8b8fcf30-df6c-4361-85e1-007cf3390f9f",
-      "text": "用户偏好使用中文进行交流。",
-      "importance": 0.5,
-      "category": "user_memory_fact",
-      "createdAt": 1774378304727,
-      "isDeleted": 0,
-      "seqInBatch": 0,
-      "chunkIndex": 0
-    },
-    {
-      "id": "1231e4e7-6a81-4216-b4c9-f4755e3825d0",
-      "agentId": "main",
-      "sessionId": "session:8b8fcf30-df6c-4361-85e1-007cf3390f9f",
-      "text": "用户为 RDS 记忆插件增加了 BM25 支持。",
-      "importance": 0.7,
-      "category": "user_memory_fact",
-      "createdAt": 1774378281971,
-      "isDeleted": 0,
-      "seqInBatch": 0,
-      "chunkIndex": 0
-    }
-  ],
-  "total": 20,
-  "page": 1,
-  "pageSize": 2
-}
-```
-
----
-
-**7）`POST /plugins/memory/api/delete`（空 `items`）**
-
-```bash
-curl -sS -H "Authorization: Bearer $TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"items":[]}' \
-  "$GATEWAY/plugins/memory/api/delete"
-```
-
-**响应体 `400`（实测）**
-
-```json
-{ "error": "items required" }
-```
-
----
-
-**8）`POST /plugins/memory/api/add` → 再 `delete`（同一条 id）**
-
-```bash
-curl -sS -H "Authorization: Bearer $TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"agentId":"main","text":"API doc embedded real response sample","category":"user_memory_fact"}' \
-  "$GATEWAY/plugins/memory/api/add"
-```
-
-**`add` 响应体 `200`（实测；该行已在后续 delete 中删掉）**
-
-```json
-{
-  "id": "a8ae8460-40ea-4878-baf8-f6fb48e5f79e",
-  "createdAt": 1774412491204,
-  "chunkRows": 1
-}
-```
-
-```bash
-curl -sS -H "Authorization: Bearer $TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"items":[{"agentId":"main","id":"a8ae8460-40ea-4878-baf8-f6fb48e5f79e"}]}' \
-  "$GATEWAY/plugins/memory/api/delete"
-```
-
-**`delete` 响应体 `200`（实测）**
-
-```json
-{ "deleted": 1 }
-```
-
----
-
-**9）错误 token**
-
-```bash
-curl -sS -H "Authorization: Bearer wrong-token" \
-  "$GATEWAY/plugins/memory/api/config"
-```
-
-**响应体 `401`（实测）**
-
-```json
-{
-  "error": {
-    "message": "Unauthorized",
-    "type": "unauthorized"
-  }
-}
-```
-
----
-
-## 三、Agent 工具（非 HTTP）
-
-由网关注册为 **tool**；入参为工具调用 JSON，**不是**浏览器地址栏请求。
-
-### 2.1 `memory_recall`
-
-**入参**
-
-| 参数 | 位置 | 类型 | 必须 | 合法值 / 说明 | 默认值 |
-|------|------|------|------|----------------|--------|
-| `query` | tool 参数 | `string` | **是** | 检索语句 | 无 |
-| `limit` | tool 参数 | `number` | 否 | 正整数；实际上限受插件约束 | 约 `30` |
-
-**出参**（工具返回值，OpenClaw 惯例）
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `content` | `object[]` | 常为 `[{ "type": "text", "text": string }]`，给人/模型阅读 |
-| `details` | `object` | 机器可读；子结构见下表（依场景不同） |
-
-**`details` 常见形态**
-
-| 场景 | `details` 类型 | 字段说明 |
-|------|----------------|----------|
-| 未配置插件 | `object` | `error`：`string`，如 `"not_configured"` |
-| 无结果 | `object` | `count`：`number`，`0` |
-| 有结果 | `object` | `count`：`number`；`memories`：`object[]`，元素见下表 |
-
-**`details.memories` 数组元素（object）**
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `id` | `string` | 记忆行 ID |
-| `text` | `string` | 正文 |
-| `category` | `string` | 类型代码 |
-| `importance` | `number` | 重要程度 |
-| `score` | `number` | 相关度分数 |
-| `createdAt` | `number` | 毫秒时间戳 |
-
----
-
-### 2.2 `memory_store`
-
-**入参**
-
-| 参数 | 位置 | 类型 | 必须 | 合法值 / 说明 | 默认值 |
-|------|------|------|------|----------------|--------|
-| `text` | tool 参数 | `string` | **是** | 待存储正文 | 无 |
-| `importance` | tool 参数 | `number` | 否 | 建议 0～1 | `0.7` |
-| `category` | tool 参数 | `string` | 否 | 枚举随配置；默认用户事实类 | `user_memory_fact` |
-
-**出参**
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `content` | `object[]` | 文本摘要（`type: text`） |
-| `details` | `object` | 成功时见下表；失败时常含 `error`：`string` |
-
-**`details` 成功时（object）**
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `action` | `string` | `"created"` 或 `"updated"` |
-| `id` | `string` | 记忆行 ID |
-
----
-
-### 2.3 `memory_forget`
-
-**入参**
-
-| 参数 | 位置 | 类型 | 必须 | 合法值 / 说明 | 默认值 |
-|------|------|------|------|----------------|--------|
-| `memoryId` | tool 参数 | `string` | 否 | 行 UUID；与 `query` 二选一 | 无 |
-| `query` | tool 参数 | `string` | 否 | 检索语句；与 `memoryId` 二选一 | 无 |
-
-**出参**
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `content` | `object[]` | 文本说明 |
-| `details` | `object` | 依场景不同，见下表 |
-
-**`details` 常见形态**
-
-| 场景 | 字段 | 类型 | 说明 |
-|------|------|------|------|
-| 未配置 | `error` | `string` | 如 `not_configured` |
-| 缺参 | `error` | `string` | `missing_param` |
-| 按 ID 删除成功 | `action` | `string` | `deleted` |
-| 按 ID 删除成功 | `id` | `string` | 被删 ID |
-| 按 ID 未找到 | `action` | `string` | `not_found` |
-| 按 ID 未找到 | `id` | `string` | 请求的 ID |
-| 按 query 无匹配 | `found` | `number` | `0` |
-| 按 query 自动删除 | `action` | `string` | `deleted` |
-| 按 query 自动删除 | `rows` | `number` | 删除行数 |
-| 按 query 自动删除 | `id` | `string` | 代表行 ID |
-| 按 query 仅候选 | `action` | `string` | `candidates` |
-| 按 query 仅候选 | `candidates` | `object[]` | 元素含 `id`、`text`、`category`、`score` |
-
-**`details.candidates` 数组元素（object）**
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `id` | `string` | 记忆 ID |
-| `text` | `string` | 正文 |
-| `category` | `string` | 类型 |
-| `score` | `number` | 分数 |
-
----
-
-## 四、附录
-
-### A. `POST /api/add` 与工具可用的类型代码（随配置增减）
-
-| 场景 | 允许的 `category` 示例 |
-|------|-------------------------|
-| 始终 | `user_memory_fact`、`user_memory_preference`、`user_memory_decision` |
-| 全文开启 | `full_context_user`、`full_context_assistant`、`full_context_system`、`full_context_tool`、`full_context_tool_result`、`full_context_others` |
-| 自进化开启 | `self_improving_learnings`、`self_improving_errors`、`self_improving_feature_requests` |
-
-### B. 运维备注
-
-- Service id：`openclaw-memory-alibaba-local`；无额外对外 HTTP。
-- `autoRecall`、`autoCapture` 等为行为开关，无独立 URL。
-
----
-
-*若与实现不一致，以仓库当前源码为准。*