feat: Sync memos-local-openclaw from native_memos (#1279)

…emos, v1.0.3

- Version: 1.0.3
- Sync memos-local-openclaw from native_memos
- Includes: update-check, accuracy tests, test-agent-isolation,
viewer/server & html updates, ingest/recall/storage improvements,
better-sqlite3 Node 25+ compatibility

Made-with: Cursor

## 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)
- [x] 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

- [x] I have performed a self-review of my own code | 我已自行检查了自己的代码
- [x] I have commented my code in hard-to-understand areas |
我已在难以理解的地方对代码进行了注释
- [x] I have added tests that prove my fix is effective or that my
feature works | 我已添加测试以证明我的修复有效或功能正常
- [x] 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（如果适用）
- [x] I have linked the issue to this PR (if applicable) | 我已将 issue
链接到此 PR（如果适用）
- [x] 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: CarltonXiang

apps/memos-local-openclaw/.gitignore

@@ -13,6 +13,7 @@ Thumbs.db
 
 # Generated / non-essential
 package-lock.json
+.installed-version
 www/
 docs/
 ppt/

apps/memos-local-openclaw/index.ts

@@ -4,6 +4,9 @@
   "description": "Full-write local conversation memory with hybrid search (RRF + MMR + recency). Provides memory_search, memory_get, task_summary, memory_timeline, memory_viewer for layered retrieval.",
   "kind": "memory",
   "version": "0.1.11",
+  "skills": [
+    "skill/memos-memory-guide"
+  ],
   "homepage": "https://github.com/MemTensor/MemOS/tree/main/apps/memos-local-openclaw",
   "configSchema": {
     "type": "object",

apps/memos-local-openclaw/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "@memtensor/memos-local-openclaw-plugin",
-  "version": "1.0.0",
-  "description": "MemOS Local memory plugin for OpenClaw — full-write, hybrid-recall, progressive retrieval",
+  "version": "1.0.3",
+  "description": "MemOS Local memory plugin for OpenClaw \u2014 full-write, hybrid-recall, progressive retrieval",
   "type": "module",
   "main": "index.ts",
   "types": "dist/index.d.ts",
@@ -21,6 +21,9 @@
     "extensions": [
       "./index.ts"
     ],
+    "skills": [
+      "skill/memos-memory-guide"
+    ],
     "installDependencies": true
   },
   "scripts": {
@@ -29,6 +32,7 @@
     "lint": "eslint src --ext .ts",
     "test": "vitest run",
     "test:watch": "vitest",
+    "test:accuracy": "tsx scripts/run-accuracy-test.ts",
     "postinstall": "node scripts/postinstall.cjs",
     "prepublishOnly": "npm run build"
   },
@@ -49,14 +53,16 @@
     "better-sqlite3": "^12.6.2",
     "posthog-node": "^5.28.0",
     "puppeteer": "^24.38.0",
+    "semver": "^7.7.4",
     "uuid": "^10.0.0"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.12",
     "@types/node": "^22.10.0",
+    "@types/semver": "^7.7.1",
     "@types/uuid": "^10.0.0",
     "tsx": "^4.21.0",
     "typescript": "^5.7.0",
     "vitest": "^2.1.0"
   }
-}
+}

apps/memos-local-openclaw/package.json

@@ -33,6 +33,78 @@ ${CYAN}${BOLD}┌─────────────────────
 log(`Plugin dir: ${DIM}${pluginDir}${RESET}`);
 log(`Node: ${process.version}  Platform: ${process.platform}-${process.arch}`);
 
+/* ═══════════════════════════════════════════════════════════
+ *  Pre-phase: Clean stale build artifacts on upgrade
+ *  When openclaw re-installs a new version over an existing
+ *  extensions dir, old dist/node_modules can conflict.
+ *  We nuke them so npm install gets a clean slate, but
+ *  preserve user data (.env, data/).
+ * ═══════════════════════════════════════════════════════════ */
+
+function cleanStaleArtifacts() {
+  const isExtensionsDir = pluginDir.includes(path.join(".openclaw", "extensions"));
+  if (!isExtensionsDir) return;
+
+  const pkgPath = path.join(pluginDir, "package.json");
+  if (!fs.existsSync(pkgPath)) return;
+
+  let installedVer = "unknown";
+  try {
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+    installedVer = pkg.version || "unknown";
+  } catch { /* ignore */ }
+
+  const markerPath = path.join(pluginDir, ".installed-version");
+  let prevVer = "";
+  try { prevVer = fs.readFileSync(markerPath, "utf-8").trim(); } catch { /* first install */ }
+
+  if (prevVer === installedVer) {
+    log(`Version unchanged (${installedVer}), skipping artifact cleanup.`);
+    return;
+  }
+
+  if (prevVer) {
+    log(`Upgrade detected: ${DIM}${prevVer}${RESET} → ${GREEN}${installedVer}${RESET}`);
+  } else {
+    log(`Fresh install: ${GREEN}${installedVer}${RESET}`);
+  }
+
+  const dirsToClean = ["dist", "node_modules"];
+  let cleaned = 0;
+  for (const dir of dirsToClean) {
+    const full = path.join(pluginDir, dir);
+    if (fs.existsSync(full)) {
+      try {
+        fs.rmSync(full, { recursive: true, force: true });
+        ok(`Cleaned stale ${dir}/`);
+        cleaned++;
+      } catch (e) {
+        warn(`Could not remove ${dir}/: ${e.message}`);
+      }
+    }
+  }
+
+  const filesToClean = ["package-lock.json"];
+  for (const f of filesToClean) {
+    const full = path.join(pluginDir, f);
+    if (fs.existsSync(full)) {
+      try { fs.unlinkSync(full); ok(`Removed stale ${f}`); cleaned++; } catch { /* ignore */ }
+    }
+  }
+
+  try { fs.writeFileSync(markerPath, installedVer + "\n", "utf-8"); } catch { /* ignore */ }
+
+  if (cleaned > 0) {
+    ok(`Cleaned ${cleaned} stale artifact(s). Fresh install will follow.`);
+  }
+}
+
+try {
+  cleanStaleArtifacts();
+} catch (e) {
+  warn(`Artifact cleanup error: ${e.message}`);
+}
+
 /* ═══════════════════════════════════════════════════════════
  *  Phase 0: Ensure all dependencies are installed
  * ═══════════════════════════════════════════════════════════ */
@@ -102,6 +174,7 @@ function cleanupLegacy() {
   if (!fs.existsSync(extDir)) { log("No extensions directory found, skipping."); return; }
 
   const legacyDirs = [
+    path.join(extDir, "memos-local"),
     path.join(extDir, "memos-lite"),
     path.join(extDir, "memos-lite-openclaw-plugin"),
     path.join(extDir, "node_modules", "@memtensor", "memos-lite-openclaw-plugin"),
@@ -127,7 +200,7 @@ function cleanupLegacy() {
       const cfg = JSON.parse(raw);
       const entries = cfg?.plugins?.entries;
       if (entries) {
-        const oldKeys = ["memos-lite", "memos-lite-openclaw-plugin"];
+        const oldKeys = ["memos-local", "memos-lite", "memos-lite-openclaw-plugin"];
         let cfgChanged = false;
 
         for (const oldKey of oldKeys) {
@@ -146,17 +219,29 @@ function cleanupLegacy() {
         const newEntry = entries["memos-local-openclaw-plugin"];
         if (newEntry && typeof newEntry.source === "string") {
           const oldSource = newEntry.source;
-          if (oldSource.includes("memos-lite")) {
+          if (oldSource.includes("memos-lite") || (oldSource.includes("memos-local") && !oldSource.includes("memos-local-openclaw-plugin"))) {
             newEntry.source = oldSource
               .replace(/memos-lite-openclaw-plugin/g, "memos-local-openclaw-plugin")
-              .replace(/memos-lite/g, "memos-local");
+              .replace(/memos-lite/g, "memos-local-openclaw-plugin")
+              .replace(/\/memos-local\//g, "/memos-local-openclaw-plugin/")
+              .replace(/\/memos-local$/g, "/memos-local-openclaw-plugin");
             if (newEntry.source !== oldSource) {
               log(`Updated source path: ${DIM}${oldSource}${RESET} → ${GREEN}${newEntry.source}${RESET}`);
               cfgChanged = true;
             }
           }
         }
 
+        const slots = cfg?.plugins?.slots;
+        if (slots && typeof slots.memory === "string") {
+          const oldSlotNames = ["memos-local", "memos-lite", "memos-lite-openclaw-plugin"];
+          if (oldSlotNames.includes(slots.memory)) {
+            log(`Migrated plugins.slots.memory: ${DIM}${slots.memory}${RESET} → ${GREEN}memos-local-openclaw-plugin${RESET}`);
+            slots.memory = "memos-local-openclaw-plugin";
+            cfgChanged = true;
+          }
+        }
+
         if (cfgChanged) {
           const backup = cfgPath + ".bak-" + Date.now();
           fs.copyFileSync(cfgPath, backup);
@@ -185,10 +270,77 @@ try {
 }
 
 /* ═══════════════════════════════════════════════════════════
- *  Phase 2: Verify better-sqlite3 native module
+ *  Phase 2: Install bundled skill (memos-memory-guide)
+ * ═══════════════════════════════════════════════════════════ */
+
+function installBundledSkill() {
+  phase(2, "安装记忆技能 / Install memory skill");
+
+  const home = process.env.HOME || process.env.USERPROFILE || "";
+  if (!home) { warn("Cannot determine HOME directory, skipping skill install."); return; }
+
+  const skillSrc = path.join(pluginDir, "skill", "memos-memory-guide", "SKILL.md");
+  if (!fs.existsSync(skillSrc)) {
+    warn("Bundled SKILL.md not found, skipping skill install.");
+    return;
+  }
+
+  let pluginVersion = "0.0.0";
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(pluginDir, "package.json"), "utf-8"));
+    pluginVersion = pkg.version || pluginVersion;
+  } catch { /* ignore */ }
+
+  const skillContent = fs.readFileSync(skillSrc, "utf-8");
+  const targets = [
+    path.join(home, ".openclaw", "workspace", "skills", "memos-memory-guide"),
+    path.join(home, ".openclaw", "skills", "memos-memory-guide"),
+  ];
+
+  const meta = JSON.stringify({ ownerId: "memos-local-openclaw-plugin", slug: "memos-memory-guide", version: pluginVersion, publishedAt: Date.now() });
+  const origin = JSON.stringify({ version: 1, registry: "memos-local-openclaw-plugin", slug: "memos-memory-guide", installedVersion: pluginVersion, installedAt: Date.now() });
+
+  for (const dest of targets) {
+    try {
+      fs.mkdirSync(dest, { recursive: true });
+      fs.writeFileSync(path.join(dest, "SKILL.md"), skillContent, "utf-8");
+      fs.writeFileSync(path.join(dest, "_meta.json"), meta, "utf-8");
+      const clawHubDir = path.join(dest, ".clawhub");
+      fs.mkdirSync(clawHubDir, { recursive: true });
+      fs.writeFileSync(path.join(clawHubDir, "origin.json"), origin, "utf-8");
+      ok(`Skill installed → ${DIM}${dest}${RESET}`);
+    } catch (e) {
+      warn(`Could not install skill to ${dest}: ${e.message}`);
+    }
+  }
+
+  // Register in skills-lock.json so OpenClaw Dashboard can discover it
+  const lockPath = path.join(home, ".openclaw", "workspace", "skills-lock.json");
+  try {
+    let lockData = { version: 1, skills: {} };
+    if (fs.existsSync(lockPath)) {
+      lockData = JSON.parse(fs.readFileSync(lockPath, "utf-8"));
+    }
+    if (!lockData.skills) lockData.skills = {};
+    lockData.skills["memos-memory-guide"] = { source: "memos-local-openclaw-plugin", sourceType: "plugin", computedHash: "" };
+    fs.writeFileSync(lockPath, JSON.stringify(lockData, null, 2) + "\n", "utf-8");
+    ok("Registered in skills-lock.json");
+  } catch (e) {
+    warn(`Could not update skills-lock.json: ${e.message}`);
+  }
+}
+
+try {
+  installBundledSkill();
+} catch (e) {
+  warn(`Skill install error: ${e.message}`);
+}
+
+/* ═══════════════════════════════════════════════════════════
+ *  Phase 3: Verify better-sqlite3 native module
  * ═══════════════════════════════════════════════════════════ */
 
-phase(2, "检查 better-sqlite3 原生模块 / Check native module");
+phase(3, "检查 better-sqlite3 原生模块 / Check native module");
 
 const sqliteModulePath = path.join(pluginDir, "node_modules", "better-sqlite3");