Openclaw local plugin 20260408 (#1450)

## Description

Please include a summary of the change, the problem it solves, the
implementation approach, and relevant context. List any dependencies
required for this change.

Related Issue (Required):  Fixes #issue_number

## Type of change

Please delete options that are not relevant.

- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to not work as expected)
- [ ] Refactor (does not change functionality, e.g. code style
improvements, linting)
- [ ] Documentation update

## How Has This Been Tested?

Please describe the tests that you ran to verify your changes. Provide
instructions so we can reproduce. Please also list any relevant details
for your test configuration

- [ ] Unit Test
- [ ] Test Script Or Test Steps (please provide)
- [ ] Pipeline Automated API Test (please provide)

## Checklist

- [ ] I have performed a self-review of my own code | 我已自行检查了自己的代码
- [ ] I have commented my code in hard-to-understand areas |
我已在难以理解的地方对代码进行了注释
- [ ] I have added tests that prove my fix is effective or that my
feature works | 我已添加测试以证明我的修复有效或功能正常
- [ ] I have created related documentation issue/PR in
[MemOS-Docs](https://github.com/MemTensor/MemOS-Docs) (if applicable) |
我已在 [MemOS-Docs](https://github.com/MemTensor/MemOS-Docs) 中创建了相关的文档
issue/PR（如果适用）
- [ ] I have linked the issue to this PR (if applicable) | 我已将 issue
链接到此 PR（如果适用）
- [ ] I have mentioned the person who will review this PR | 我已提及将审查此 PR
的人

## Reviewer Checklist
- [ ] closes #xxxx (Replace xxxx with the GitHub issue number)
- [ ] Made sure Checks passed
- [ ] Tests have been provided

Author: hijzy

apps/memos-local-openclaw/index.ts

@@ -57,6 +57,43 @@ const NEW_SESSION_PROMPT_RE = /A new session was started via \/new or \/reset\./
 const INTERNAL_CONTEXT_RE = /OpenClaw runtime context \(internal\):[\s\S]*/i;
 const CONTINUE_PROMPT_RE = /^Continue where you left off\.[\s\S]*/i;
 
+const buildMemoryPromptSection = ({ availableTools, citationsMode }: {
+  availableTools: Set<string>;
+  citationsMode?: string;
+}) => {
+  const lines: string[] = [];
+  const hasMemorySearch = availableTools.has("memory_search");
+  const hasMemoryGet = availableTools.has("memory_get");
+
+  if (!hasMemorySearch && !hasMemoryGet) {
+    return lines;
+  }
+
+  lines.push("## Memory Recall");
+  lines.push(
+    "This workspace uses MemOS Local as the active memory slot. Prefer recalled memories and the memory tools before claiming prior context is unavailable.",
+  );
+
+  if (hasMemorySearch && hasMemoryGet) {
+    lines.push(
+      "Use `memory_search` to locate relevant memories, then `memory_get` or `memory_timeline` when you need the full source text or surrounding context.",
+    );
+  } else if (hasMemorySearch) {
+    lines.push("Use `memory_search` before answering questions about prior conversations, preferences, plans, or decisions.");
+  } else {
+    lines.push("Use `memory_get` or `memory_timeline` to inspect the referenced memory before answering.");
+  }
+
+  if (citationsMode === "off") {
+    lines.push("Citations are disabled, so avoid mentioning internal memory ids unless the user asks.");
+  } else {
+    lines.push("When it helps the user verify a memory-backed claim, mention the relevant memory identifier or tool result.");
+  }
+
+  lines.push("");
+  return lines;
+};
+
 function normalizeAutoRecallQuery(rawPrompt: string): string {
   let query = rawPrompt.trim();
 
@@ -123,6 +160,10 @@ const memosLocalPlugin = {
   configSchema: pluginConfigSchema,
 
   register(api: OpenClawPluginApi) {
+    api.registerMemoryCapability({
+      promptBuilder: buildMemoryPromptSection,
+    });
+
     const moduleDir = path.dirname(fileURLToPath(import.meta.url));
     const localRequire = createRequire(import.meta.url);
     const npmCmd = process.platform === "win32" ? "npm.cmd" : "npm";
@@ -2399,8 +2440,10 @@ Groups: ${groupNames.length > 0 ? groupNames.join(", ") : "(none)"}`,
 
     // Fallback: OpenClaw may load this plugin via deferred reload after
     // startPluginServices has already run, so service.start() never fires.
-    // Self-start the viewer after a grace period if it hasn't been started.
-    const SELF_START_DELAY_MS = 3000;
+    // Start on the next tick instead of waiting several seconds; the
+    // serviceStarted guard still prevents duplicate startup if the host calls
+    // service.start() immediately after registration.
+    const SELF_START_DELAY_MS = 0;
     setTimeout(() => {
       if (!serviceStarted) {
         api.logger.info("memos-local: service.start() not called by host, self-starting viewer...");

apps/memos-local-openclaw/install.sh

@@ -150,6 +150,17 @@ ensure_node22() {
   exit 1
 }
 
+resolve_openclaw_bin() {
+  if command -v openclaw >/dev/null 2>&1; then
+    command -v openclaw
+    return 0
+  fi
+
+  error "Global openclaw CLI not found, 未找到全局 openclaw 命令"
+  error "Install it first with: npm install -g openclaw@latest"
+  exit 1
+}
+
 print_banner() {
   echo -e "${BLUE}${BOLD}🧠 Memos Local OpenClaw Installer${NC}"
   echo -e "${BLUE}${DEFAULT_TAGLINE}${NC}"
@@ -208,6 +219,9 @@ if ! command -v node >/dev/null 2>&1; then
   exit 1
 fi
 
+OPENCLAW_BIN="$(resolve_openclaw_bin)"
+success "Using global OpenClaw CLI, 使用全局 OpenClaw CLI: ${OPENCLAW_BIN}"
+
 PACKAGE_SPEC="${PLUGIN_PACKAGE}@${PLUGIN_VERSION}"
 EXTENSION_DIR="${OPENCLAW_HOME}/extensions/${PLUGIN_ID}"
 OPENCLAW_CONFIG_PATH="${OPENCLAW_HOME}/openclaw.json"
@@ -302,7 +316,7 @@ NODE
 }
 
 info "Stop OpenClaw Gateway, 停止 OpenClaw Gateway..."
-npx openclaw gateway stop >/dev/null 2>&1 || true
+"${OPENCLAW_BIN}" gateway stop >/dev/null 2>&1 || true
 
 if command -v lsof >/dev/null 2>&1; then
   PIDS="$(lsof -i :"${PORT}" -t 2>/dev/null || true)"
@@ -388,21 +402,37 @@ fi
 update_openclaw_config
 
 info "Install OpenClaw Gateway service, 安装 OpenClaw Gateway 服务..."
-npx openclaw gateway install --port "${PORT}" --force 2>&1 || true
+"${OPENCLAW_BIN}" gateway install --port "${PORT}" --force 2>&1 || true
 
 success "Start OpenClaw Gateway service, 启动 OpenClaw Gateway 服务..."
-npx openclaw gateway start 2>&1
+"${OPENCLAW_BIN}" gateway start 2>&1
 
 info "Starting Memory Viewer, 正在启动记忆面板..."
-for i in 1 2 3 4 5; do
-  if command -v lsof >/dev/null 2>&1 && lsof -i :18799 -t >/dev/null 2>&1; then
+VIEWER_URL="http://127.0.0.1:18799"
+VIEWER_WAIT_SECONDS=30
+viewer_ready=0
+for ((i=1; i<=VIEWER_WAIT_SECONDS; i++)); do
+  if command -v curl >/dev/null 2>&1; then
+    if curl -fsS --max-time 2 "${VIEWER_URL}" >/dev/null 2>&1; then
+      viewer_ready=1
+      break
+    fi
+  elif command -v lsof >/dev/null 2>&1 && lsof -i :18799 -t >/dev/null 2>&1; then
+    viewer_ready=1
     break
   fi
   printf "."
   sleep 1
 done
 echo ""
 
+if [[ "${viewer_ready}" -eq 1 ]]; then
+  success "Memory Viewer is ready, 记忆面板已就绪: ${VIEWER_URL}"
+else
+  warn "Memory Viewer not ready after ${VIEWER_WAIT_SECONDS}s, 记忆面板在 ${VIEWER_WAIT_SECONDS} 秒后仍未就绪"
+  warn "Check gateway logs if http://127.0.0.1:18799 is still unavailable."
+fi
+
 echo ""
 success "=========================================="
 success "  Installation complete! 安装完成!"

apps/memos-local-openclaw/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memtensor/memos-local-openclaw-plugin",
-  "version": "1.0.8",
+  "version": "1.0.9-beta.1",
   "description": "MemOS Local memory plugin for OpenClaw — full-write, hybrid-recall, progressive retrieval",
   "type": "module",
   "main": "index.ts",

apps/memos-local-openclaw/tests/incremental-sharing.test.ts

@@ -19,9 +19,21 @@ function makeApi(stateDir: string, pluginConfig: Record<string, unknown> = {}) {
       return input === "~/.openclaw" ? stateDir : input;
     },
     logger: noopLog,
-    registerTool(def: any) {
+    registerTool(def: any, meta?: { name?: string }) {
+      if (typeof def === "function") {
+        const key = meta?.name ?? def({ agentId: "main", sessionKey: "default" }).name;
+        tools.set(key, {
+          name: key,
+          execute: (...args: any[]) => {
+            const runtimeCtx = args[2] ?? { agentId: "main", sessionKey: "default" };
+            return def(runtimeCtx).execute(...args);
+          },
+        });
+        return;
+      }
       tools.set(def.name, def);
     },
+    registerMemoryCapability() {},
     registerService(def: any) {
       service = def;
     },

apps/memos-local-openclaw/tests/integration.test.ts

@@ -30,9 +30,21 @@ function makePluginApi(stateDir: string, pluginConfig: Record<string, unknown> =
       return input === "~/.openclaw" ? stateDir : input;
     },
     logger: noopLog,
-    registerTool(def: any) {
+    registerTool(def: any, meta?: { name?: string }) {
+      if (typeof def === "function") {
+        const key = meta?.name ?? def({ agentId: "main", sessionKey: "default" }).name;
+        tools.set(key, {
+          name: key,
+          execute: (...args: any[]) => {
+            const runtimeCtx = args[2] ?? { agentId: "main", sessionKey: "default" };
+            return def(runtimeCtx).execute(...args);
+          },
+        });
+        return;
+      }
       tools.set(def.name, def);
     },
+    registerMemoryCapability() {},
     registerService(def: any) {
       service = def;
     },
@@ -837,9 +849,9 @@ describe("Integration: root plugin memory_search network scope", () => {
       expect(searchTool).toBeDefined();
 
       const result = await searchTool.execute("call-root-search", { query: "rollout checklist", scope: "all", maxResults: 5 }, { agentId: "main" });
-      expect(result.details.local.hits.length).toBeGreaterThan(0);
-      expect(result.details.hub.hits.length).toBeGreaterThan(0);
-      expect(result.details.hub.hits[0].remoteHitId).toBeTruthy();
+      expect((result.details.filtered ?? []).some((hit: any) => hit.origin !== "hub-remote")).toBe(true);
+      expect((result.details.filtered ?? []).some((hit: any) => hit.origin === "hub-remote")).toBe(true);
+      expect((result.details.hubCandidates ?? []).length).toBeGreaterThan(0);
     } finally {
       await teardownRootMemorySearchHarness(harness);
     }

apps/memos-local-openclaw/tests/plugin-impl-access.test.ts

@@ -21,9 +21,21 @@ function makeApi(stateDir: string, pluginConfig: Record<string, unknown> = {}) {
       info: () => {},
       warn: () => {},
     },
-    registerTool(def: any) {
+    registerTool(def: any, meta?: { name?: string }) {
+      if (typeof def === "function") {
+        const key = meta?.name ?? def({ agentId: "main", sessionKey: "default" }).name;
+        tools.set(key, {
+          name: key,
+          execute: (...args: any[]) => {
+            const runtimeCtx = args[2] ?? { agentId: "main", sessionKey: "default" };
+            return def(runtimeCtx).execute(...args);
+          },
+        });
+        return;
+      }
       tools.set(def.name, def);
     },
+    registerMemoryCapability() {},
     registerService(def: any) {
       service = def;
     },
@@ -219,7 +231,7 @@ describe("plugin-impl owner isolation", () => {
     const search = tools.get("memory_search");
     await waitFor(async () => {
       const result = await search.execute("call-search", { query: "alpha private marker", maxResults: 5, minScore: 0.1 }, { agentId: "alpha" });
-      return (result?.details?.hits?.length ?? 0) > 0;
+      return (result?.details?.filtered?.length ?? 0) > 0;
     });
   });
 
@@ -243,20 +255,20 @@ describe("plugin-impl owner isolation", () => {
     const beta = await search.execute("call-search", { query: "alpha private marker", maxResults: 5, minScore: 0.1 }, { agentId: "beta" });
     const publicHit = await search.execute("call-search", { query: "shared public marker", maxResults: 5, minScore: 0.1 }, { agentId: "beta" });
 
-    expect(alpha.details.hits.length).toBeGreaterThan(0);
-    const betaAlphaHits = (beta.details?.hits ?? []).filter((h: any) =>
+    expect(alpha.details.filtered.length).toBeGreaterThan(0);
+    const betaAlphaHits = (beta.details?.filtered ?? []).filter((h: any) =>
       h.original_excerpt?.includes("alpha") || h.summary?.includes("alpha"),
     );
     expect(betaAlphaHits).toHaveLength(0);
-    expect(publicHit.details.hits.length).toBeGreaterThan(0);
+    expect(publicHit.details.filtered.length).toBeGreaterThan(0);
   });
 
   it("memory_timeline should not leak another agent's private neighbors", async () => {
     const search = tools.get("memory_search");
     const timeline = tools.get("memory_timeline");
 
     const alpha = await search.execute("call-search", { query: "alpha private marker", maxResults: 5, minScore: 0.1 }, { agentId: "alpha" });
-    const chunkId = alpha.details.hits[0].chunkId;
+    const chunkId = alpha.details.filtered[0].chunkId;
     const betaTimeline = await timeline.execute("call-timeline", { chunkId }, { agentId: "beta" });
 
     expect(betaTimeline.details.entries).toEqual([]);
@@ -416,7 +428,7 @@ describe("plugin-impl owner isolation", () => {
     const getTool = tools.get("memory_get");
 
     const alpha = await search.execute("call-search", { query: "alpha private marker", maxResults: 5, minScore: 0.1 }, { agentId: "alpha" });
-    const chunkId = alpha.details.hits[0].chunkId;
+    const chunkId = alpha.details.filtered[0].chunkId;
     const betaGet = await getTool.execute("call-get", { chunkId }, { agentId: "beta" });
 
     expect(betaGet.details.error).toBe("not_found");

apps/memos-local-openclaw/tests/plugin-openclaw-wiring.test.ts

@@ -112,6 +112,7 @@ describe("plugin-impl OpenClaw wiring", () => {
       resolvePath: () => "/tmp/memos-openclaw-wiring",
       logger: { info() {}, warn() {} },
       registerTool: () => {},
+      registerMemoryCapability: () => {},
       registerService: () => {},
       on: () => {},
     } as any);

apps/memos-local-openclaw/tests/shutdown-lifecycle.test.ts

@@ -113,6 +113,7 @@ describe("shutdown lifecycle", () => {
       resolvePath: () => "/tmp/memos-service-stop",
       logger: noopLog,
       registerTool: () => {},
+      registerMemoryCapability: () => {},
       registerService: (service: any) => { registeredService = service; },
       on: () => {},
     } as any);

apps/memos-local-plugin/.env.example

@@ -0,0 +1,36 @@
+# ─── Embedding API ───
+# Use any OpenAI-compatible embedding service, or leave blank for local offline model (Xenova/all-MiniLM-L6-v2)
+EMBEDDING_PROVIDER=openai_compatible
+EMBEDDING_API_KEY=your-embedding-api-key
+EMBEDDING_ENDPOINT=https://your-embedding-api.com/v1
+EMBEDDING_MODEL=bge-m3
+
+# ─── Summarizer API ───
+# OpenAI-compatible LLM for one-sentence chunk summaries
+# Leave blank to use rule-based fallback (no LLM needed)
+SUMMARIZER_PROVIDER=openai_compatible
+SUMMARIZER_API_KEY=your-summarizer-api-key
+SUMMARIZER_ENDPOINT=https://api.openai.com/v1
+SUMMARIZER_MODEL=gpt-4o-mini
+SUMMARIZER_TEMPERATURE=0
+
+# ─── Memory Viewer ───
+# Port for the web-based Memory Viewer (default: 18799)
+# VIEWER_PORT=18799
+
+# ─── Tavily Search (optional) ───
+# API key for Tavily web search (get from https://app.tavily.com)
+# TAVILY_API_KEY=tvly-your-tavily-api-key
+
+# ─── Telemetry (opt-out) ───
+# Anonymous usage analytics to help improve the plugin.
+# No memory content, queries, or personal data is ever sent — only tool names, latencies, and version info.
+# Enabled by default. Set to false to opt-out.
+# TELEMETRY_ENABLED=false
+#
+# Telemetry backend credentials (for maintainers / CI only).
+# End users do NOT need to set these — they are bundled into the npm package at publish time.
+# If not set and telemetry.credentials.json is absent, telemetry is silently disabled.
+# MEMOS_ARMS_ENDPOINT=https://your-arms-endpoint.log.aliyuncs.com/rum/web/v2?workspace=...&service_id=...
+# MEMOS_ARMS_PID=your-arms-pid
+# MEMOS_ARMS_ENV=prod

apps/memos-local-plugin/.gitignore

@@ -0,0 +1,36 @@
+node_modules/
+dist/
+*.tsbuildinfo
+.env
+
+# Compiled output (root level only)
+/*.js
+/*.js.map
+/*.d.ts
+/*.d.ts.map
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# IDE
+.vscode/
+.idea/
+
+# Generated / non-essential
+package-lock.json
+.installed-version
+ppt/
+*.tgz
+
+# Prebuilt native binaries (included in npm package via `files`, not in git)
+prebuilds/
+
+# Telemetry credentials (generated by CI, not committed to git)
+telemetry.credentials.json
+
+# Database files
+*.sqlite
+*.sqlite-journal
+*.db
+/~/.openclaw/