@bamdra/bamdra-memory-vector 0.1.0 → 0.1.2

package/README.md

@@ -1,6 +1,6 @@
 # bamdra-memory-vector
 
-`bamdra-memory-vector` is the optional semantic retrieval plugin for the Bamdra OpenClaw memory suite.
+`bamdra-memory-vector` is the semantic retrieval plugin for the Bamdra OpenClaw suite.
 
 It adds lightweight vector-style recall on top of `bamdra-openclaw-memory` without turning the whole stack into a heavy external vector-database deployment.
 
@@ -27,11 +27,46 @@ The repository currently looks small because the first public version is intenti
 
 ## Current Runtime Model
 
-- Markdown root:
-  `~/.openclaw/memory/vector/markdown/`
+- private Markdown root:
+  `~/.openclaw/memory/vector/markdown/private/`
+- shared Markdown root:
+  `~/.openclaw/memory/vector/markdown/shared/`
 - local index:
   `~/.openclaw/memory/vector/index.json`
 
+`markdownRoot` is still supported as a legacy base path, but the recommended production setup is to set `privateMarkdownRoot` and `sharedMarkdownRoot` explicitly.
+
+## Bundled Skill
+
+This package now ships its own standalone operator skill:
+
+- `bamdra-memory-vector-operator`
+
+When OpenClaw bootstraps the installed plugin, that skill can be materialized into `~/.openclaw/skills/` and attached automatically.
+
+## Best Practice: Obsidian-Friendly Layout
+
+The plugin now supports separate roots for private memory and shared knowledge. That makes it practical to point Markdown storage at an Obsidian vault, iCloud Drive folder, Git-synced repo, or Syncthing workspace while keeping the local vector index in `~/.openclaw`.
+
+Recommended example:
+
+```json
+{
+  "enabled": true,
+  "privateMarkdownRoot": "~/Documents/Obsidian/MyVault/openclaw/private",
+  "sharedMarkdownRoot": "~/Documents/Obsidian/MyVault/openclaw/shared",
+  "indexPath": "~/.openclaw/memory/vector/index.json",
+  "dimensions": 64
+}
+```
+
+This gives you:
+
+- a private vault area for user-specific memory
+- a shared vault area for team or household knowledge
+- Markdown files that can be edited on any synced device
+- a local index that OpenClaw can rebuild without exposing other users' data
+
 This first version exposes a lightweight local vector-style index interface and keeps the integration surface ready for later LanceDB-backed evolution.
 
 ## Product Positioning

package/README.zh-CN.md

@@ -0,0 +1,87 @@
+# bamdra-memory-vector
+
+`bamdra-memory-vector` 是 Bamdra OpenClaw 套件中的语义召回插件，而且它也可以独立运行。
+
+## 它做什么
+
+- 把记忆内容以 Markdown 可读形式写入本地
+- 建立轻量的本地语义索引
+- 按当前用户边界限制检索范围
+- 为长程记忆回捞提供 Top-K 语义召回
+- 保持私有记忆与共享知识分离
+
+## 开源内容说明
+
+当前开源版的实际源码已经包含在这个仓库里。
+
+- 源码入口：
+  [src/index.ts](/Users/wood/workspace/macmini-openclaw/openclaw-enhanced/bamdra-memory-vector/src/index.ts)
+- 插件清单：
+  [openclaw.plugin.json](/Users/wood/workspace/macmini-openclaw/openclaw-enhanced/bamdra-memory-vector/openclaw.plugin.json)
+- 包元数据：
+  [package.json](/Users/wood/workspace/macmini-openclaw/openclaw-enhanced/bamdra-memory-vector/package.json)
+
+仓库目前看起来比较轻，是因为首个公开版本刻意保持为紧凑、单入口插件。
+
+## 当前运行模型
+
+- 私有 Markdown 根目录：
+  `~/.openclaw/memory/vector/markdown/private/`
+- 共享 Markdown 根目录：
+  `~/.openclaw/memory/vector/markdown/shared/`
+- 本地索引：
+  `~/.openclaw/memory/vector/index.json`
+
+这一版提供的是轻量本地向量式索引接口，同时为后续 LanceDB 演进保留接入面。
+
+`markdownRoot` 仍然保留兼容，但更推荐在正式环境里显式设置 `privateMarkdownRoot` 和 `sharedMarkdownRoot`。
+
+## 随包 Skill
+
+这个包现在会附带独立的 operator skill：
+
+- `bamdra-memory-vector-operator`
+
+安装到 OpenClaw 后，bootstrap 可以把它复制到 `~/.openclaw/skills/` 并自动挂到 agent。
+
+## 最佳实践：兼容 Obsidian 的双库布局
+
+插件现在支持把私有记忆和共享知识分别落到两个 Markdown 根目录。这意味着你可以把 Markdown 指向 Obsidian 仓库、iCloud Drive、Git 同步目录或者 Syncthing 目录，而把本地索引仍然保留在 `~/.openclaw` 下面。
+
+推荐配置示例：
+
+```json
+{
+  "enabled": true,
+  "privateMarkdownRoot": "~/Documents/Obsidian/MyVault/openclaw/private",
+  "sharedMarkdownRoot": "~/Documents/Obsidian/MyVault/openclaw/shared",
+  "indexPath": "~/.openclaw/memory/vector/index.json",
+  "dimensions": 64
+}
+```
+
+这样做的好处是：
+
+- 私有记忆和共享知识库天然分开
+- Markdown 文件可以在任何同步设备上直接编辑
+- OpenClaw 继续使用本地索引，不依赖远端向量服务
+- 更适合把 Obsidian 作为长期知识库编辑入口
+
+## 产品定位
+
+`bamdra-memory-vector` 不是用来替代 `bamdra-openclaw-memory` 的。
+
+- `bamdra-openclaw-memory` 更强调连续性
+- `bamdra-memory-vector` 更强调召回增强
+
+两者组合后的价值是：
+
+- 更强的长会话连续性
+- Markdown 可读、可维护的记忆载体
+- 不依赖重型基础设施的轻量语义召回
+
+## 构建
+
+```bash
+pnpm run bundle
+```

package/dist/index.js

@@ -24,18 +24,29 @@ __export(index_exports, {
   register: () => register
 });
 module.exports = __toCommonJS(index_exports);
+
+// ../node_modules/.pnpm/tsup@8.5.1_typescript@5.9.3/node_modules/tsup/assets/cjs_shims.js
+var getImportMetaUrl = () => typeof document === "undefined" ? new URL(`file:${__filename}`).href : document.currentScript && document.currentScript.tagName.toUpperCase() === "SCRIPT" ? document.currentScript.src : new URL("main.js", document.baseURI).href;
+var importMetaUrl = /* @__PURE__ */ getImportMetaUrl();
+
+// src/index.ts
 var import_node_crypto = require("crypto");
 var import_node_fs = require("fs");
 var import_node_os = require("os");
 var import_node_path = require("path");
+var import_node_url = require("url");
 var GLOBAL_VECTOR_API_KEY = "__OPENCLAW_BAMDRA_MEMORY_VECTOR__";
+var PLUGIN_ID = "bamdra-memory-vector";
+var SKILL_ID = "bamdra-memory-vector-operator";
+var TOOL_NAME = "memory_vector_search";
 var LocalVectorIndex = class {
   config;
   records = /* @__PURE__ */ new Map();
   constructor(inputConfig) {
     this.config = normalizeConfig(inputConfig);
     (0, import_node_fs.mkdirSync)((0, import_node_path.dirname)(this.config.indexPath), { recursive: true });
-    (0, import_node_fs.mkdirSync)(this.config.markdownRoot, { recursive: true });
+    (0, import_node_fs.mkdirSync)(this.config.privateMarkdownRoot, { recursive: true });
+    (0, import_node_fs.mkdirSync)(this.config.sharedMarkdownRoot, { recursive: true });
     this.load();
   }
   upsert(args) {
@@ -54,7 +65,8 @@ ${args.text}`, this.config.dimensions),
       updatedAt: (/* @__PURE__ */ new Date()).toISOString()
     };
     this.records.set(id, record);
-    const markdownPath = (0, import_node_path.join)(this.config.markdownRoot, args.sourcePath);
+    const markdownRoot = args.userId == null ? this.config.sharedMarkdownRoot : this.config.privateMarkdownRoot;
+    const markdownPath = (0, import_node_path.join)(markdownRoot, args.sourcePath);
     (0, import_node_fs.mkdirSync)((0, import_node_path.dirname)(markdownPath), { recursive: true });
     (0, import_node_fs.writeFileSync)(markdownPath, `# ${args.title}
 
@@ -69,7 +81,7 @@ ${args.text}
       if (args.userId == null) {
         return record.userId == null;
       }
-      return record.userId === args.userId;
+      return record.userId === args.userId || record.userId == null;
     }).map((record) => ({
       id: record.id,
       userId: record.userId,
@@ -100,10 +112,16 @@ ${args.text}
   }
 };
 function register(api) {
+  queueMicrotask(() => {
+    try {
+      bootstrapOpenClawHost();
+    } catch {
+    }
+  });
   const runtime = new LocalVectorIndex(api.pluginConfig ?? api.config ?? api.plugin?.config);
   exposeVectorApi(runtime);
   api.registerTool?.({
-    name: "memory_vector_search",
+    name: TOOL_NAME,
     description: "Search the current user's vector memory index",
     parameters: {
       type: "object",
@@ -148,13 +166,118 @@ function exposeVectorApi(runtime) {
 }
 function normalizeConfig(input) {
   const root = (0, import_node_path.join)((0, import_node_os.homedir)(), ".openclaw", "memory", "vector");
+  const markdownRoot = input?.markdownRoot ?? (0, import_node_path.join)(root, "markdown");
   return {
     enabled: input?.enabled ?? true,
-    markdownRoot: input?.markdownRoot ?? (0, import_node_path.join)(root, "markdown"),
+    markdownRoot,
+    privateMarkdownRoot: input?.privateMarkdownRoot ?? (0, import_node_path.join)(markdownRoot, "private"),
+    sharedMarkdownRoot: input?.sharedMarkdownRoot ?? (0, import_node_path.join)(markdownRoot, "shared"),
     indexPath: input?.indexPath ?? (0, import_node_path.join)(root, "index.json"),
     dimensions: input?.dimensions ?? 64
   };
 }
+function bootstrapOpenClawHost() {
+  const currentFile = (0, import_node_url.fileURLToPath)(importMetaUrl);
+  const runtimeDir = (0, import_node_path.dirname)(currentFile);
+  const packageRoot = (0, import_node_path.resolve)(runtimeDir, "..");
+  const openclawHome = (0, import_node_path.resolve)((0, import_node_os.homedir)(), ".openclaw");
+  const configPath = (0, import_node_path.join)(openclawHome, "openclaw.json");
+  const extensionRoot = (0, import_node_path.join)(openclawHome, "extensions");
+  const globalSkillsDir = (0, import_node_path.join)(openclawHome, "skills");
+  const skillSource = (0, import_node_path.join)(packageRoot, "skills", SKILL_ID);
+  const skillTarget = (0, import_node_path.join)(globalSkillsDir, SKILL_ID);
+  if (!runtimeDir.startsWith(extensionRoot) || !(0, import_node_fs.existsSync)(configPath)) {
+    return;
+  }
+  if ((0, import_node_fs.existsSync)(skillSource) && !(0, import_node_fs.existsSync)(skillTarget)) {
+    (0, import_node_fs.mkdirSync)((0, import_node_path.dirname)(skillTarget), { recursive: true });
+    (0, import_node_fs.cpSync)(skillSource, skillTarget, { recursive: true });
+  }
+  const original = (0, import_node_fs.readFileSync)(configPath, "utf8");
+  const config = JSON.parse(original);
+  const changed = ensureHostConfig(config);
+  if (!changed) {
+    return;
+  }
+  (0, import_node_fs.writeFileSync)(configPath, `${JSON.stringify(config, null, 2)}
+`, "utf8");
+}
+function ensureHostConfig(config) {
+  let changed = false;
+  const plugins = ensureObject(config, "plugins");
+  const entries = ensureObject(plugins, "entries");
+  const load = ensureObject(plugins, "load");
+  const tools = ensureObject(config, "tools");
+  const skills = ensureObject(config, "skills");
+  const skillsLoad = ensureObject(skills, "load");
+  const agents = ensureObject(config, "agents");
+  const entry = ensureObject(entries, PLUGIN_ID);
+  const entryConfig = ensureObject(entry, "config");
+  changed = ensureArrayIncludes(plugins, "allow", PLUGIN_ID) || changed;
+  changed = ensureArrayIncludes(load, "paths", (0, import_node_path.join)((0, import_node_os.homedir)(), ".openclaw", "extensions")) || changed;
+  changed = ensureArrayIncludes(skillsLoad, "extraDirs", (0, import_node_path.join)((0, import_node_os.homedir)(), ".openclaw", "skills")) || changed;
+  changed = ensureArrayIncludes(tools, "allow", TOOL_NAME) || changed;
+  if (entry.enabled !== false) {
+    entry.enabled = false;
+    changed = true;
+  }
+  if (entryConfig.enabled !== false) {
+    entryConfig.enabled = false;
+    changed = true;
+  }
+  if (typeof entryConfig.privateMarkdownRoot !== "string" || entryConfig.privateMarkdownRoot.length === 0) {
+    entryConfig.privateMarkdownRoot = "~/.openclaw/memory/vector/markdown/private";
+    changed = true;
+  }
+  if (typeof entryConfig.sharedMarkdownRoot !== "string" || entryConfig.sharedMarkdownRoot.length === 0) {
+    entryConfig.sharedMarkdownRoot = "~/.openclaw/memory/vector/markdown/shared";
+    changed = true;
+  }
+  if (typeof entryConfig.indexPath !== "string" || entryConfig.indexPath.length === 0) {
+    entryConfig.indexPath = "~/.openclaw/memory/vector/index.json";
+    changed = true;
+  }
+  changed = ensureAgentSkills(agents, SKILL_ID) || changed;
+  return changed;
+}
+function ensureObject(parent, key) {
+  const current = parent[key];
+  if (current && typeof current === "object" && !Array.isArray(current)) {
+    return current;
+  }
+  const next = {};
+  parent[key] = next;
+  return next;
+}
+function ensureArrayIncludes(parent, key, value) {
+  const current = Array.isArray(parent[key]) ? [...parent[key]] : [];
+  if (current.includes(value)) {
+    if (!Array.isArray(parent[key])) {
+      parent[key] = current;
+    }
+    return false;
+  }
+  current.push(value);
+  parent[key] = current;
+  return true;
+}
+function ensureAgentSkills(agents, skillId) {
+  const list = Array.isArray(agents.list) ? agents.list : [];
+  let changed = false;
+  for (const item of list) {
+    if (!item || typeof item !== "object") {
+      continue;
+    }
+    const agent = item;
+    const current = Array.isArray(agent.skills) ? [...agent.skills] : [];
+    if (!current.includes(skillId)) {
+      current.push(skillId);
+      agent.skills = current;
+      changed = true;
+    }
+  }
+  return changed;
+}
 function embed(text, dimensions) {
   const vector = Array.from({ length: dimensions }, () => 0);
   const tokens = text.toLowerCase().split(/[^a-z0-9_\u4e00-\u9fff]+/i).filter(Boolean);

package/openclaw.plugin.json

@@ -5,6 +5,7 @@
   "description": "Local vector-style semantic retrieval enhancement for Bamdra memory.",
   "version": "0.1.0",
   "main": "./dist/index.js",
+  "skills": ["./skills"],
   "configSchema": {
     "type": "object",
     "additionalProperties": true

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bamdra/bamdra-memory-vector",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Lightweight local semantic retrieval enhancement for the Bamdra OpenClaw memory suite.",
   "license": "MIT",
   "homepage": "https://www.bamdra.com",
@@ -16,6 +16,7 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
+    "skills",
     "openclaw.plugin.json",
     "README.md",
     "LICENSE"

package/skills/bamdra-memory-vector-operator/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: bamdra-memory-vector-operator
+description: Use vector-enhanced Markdown recall to find semantically related private or shared knowledge without overfilling context.
+---
+
+# Bamdra Memory Vector Operator
+
+Treat `bamdra-memory-vector` as the semantic recall layer for memory and knowledge files.
+
+It complements topic memory. Use it when the user remembers something fuzzily, when keyword matching may fail, or when Markdown knowledge files are the likely source.
+
+## Good Triggers
+
+- “你还记得吗”
+- “之前提过那个”
+- “知识库里有没有”
+- “我好像写过一份相关说明”
+- the wording is approximate rather than exact
+
+## Retrieval Policy
+
+- prefer vector recall when the user is referencing older or fuzzily remembered content
+- use shared knowledge and private knowledge deliberately
+- keep cross-user boundaries intact
+- do not flood the prompt with low-signal chunks
+- prefer a few strong recalls over many weak ones
+
+## Markdown Knowledge Model
+
+- private Markdown is for one user's durable notes and memory fragments
+- shared Markdown is for team or reusable knowledge
+- both are editable by humans outside the runtime
+
+## Safety Rules
+
+- never treat another user's private Markdown as searchable context
+- do not reveal storage paths unless the user asks
+- if retrieval confidence is weak, answer cautiously instead of pretending certainty