@bamdra/bamdra-memory-vector 0.1.9 → 0.1.11

package/README.md

@@ -1,89 +1,105 @@
 # bamdra-memory-vector
 
-`bamdra-memory-vector` is the semantic retrieval plugin for the Bamdra OpenClaw suite.
+![Bamdra Animated Logo](./docs/assets/bamdra-logo-animated.svg)
 
-It adds lightweight vector-style recall on top of `bamdra-openclaw-memory` without turning the whole stack into a heavy external vector-database deployment.
+The local knowledge and semantic recall layer for the Bamdra suite.
 
-## What It Does
+It can run independently, and it becomes most powerful when paired with `bamdra-openclaw-memory`.
 
-- writes Markdown-readable memory artifacts to local storage
-- builds a lightweight local semantic index
-- supports scoped retrieval for the current user
-- returns top-k semantic matches for recall-heavy prompts
-- keeps private user memory and shared knowledge separated
+Install directly:
 
-## Open Source Contents
+```bash
+openclaw plugins install @bamdra/bamdra-memory-vector
+```
+
+Release package:
 
-This repository already includes the real source code for the current open-source version.
+- GitHub Releases: https://github.com/bamdra/bamdra-memory-vector/releases
+- You can also build a local release bundle with `pnpm package:release`
 
-- source entrypoint:
-  [src/index.ts](/Users/wood/workspace/macmini-openclaw/openclaw-enhanced/bamdra-memory-vector/src/index.ts)
-- plugin manifest:
-  [openclaw.plugin.json](/Users/wood/workspace/macmini-openclaw/openclaw-enhanced/bamdra-memory-vector/openclaw.plugin.json)
-- package metadata:
-  [package.json](/Users/wood/workspace/macmini-openclaw/openclaw-enhanced/bamdra-memory-vector/package.json)
+[中文文档](./README.zh-CN.md)
 
-The repository currently looks small because the first public version is intentionally a compact, single-entry plugin.
+## What it does
 
-## Current Runtime Model
+`bamdra-memory-vector` turns local Markdown into a maintainable knowledge base.
 
-- private Markdown root:
-  `~/.openclaw/memory/vector/markdown/private/`
-- shared Markdown root:
-  `~/.openclaw/memory/vector/markdown/shared/`
-- local index:
-  `~/.openclaw/memory/vector/index.json`
+It indexes:
 
-`markdownRoot` is still supported as a legacy base path, but the recommended production setup is to set `privateMarkdownRoot` and `sharedMarkdownRoot` explicitly.
+- `knowledge/`
+- `docs/`
+- `notes/`
+- `ideas/`
 
-## Bundled Skill
+`ideas/` is a generic example name. If your vault uses a different folder such as `06_Interest/`, point the Markdown root at that structure or keep both names as valid knowledge buckets.
 
-This package now ships its own standalone operator skill:
+and helps OpenClaw search that local knowledge before falling back to the web.
 
-- `bamdra-memory-vector-operator`
+## Why it matters
 
-When OpenClaw bootstraps the installed plugin, that skill can be materialized into `~/.openclaw/skills/` and attached automatically.
+The weakest part of many memory systems is the knowledge layer:
 
-## Best Practice: Obsidian-Friendly Layout
+- knowledge becomes opaque
+- humans stop editing it
+- web search gets used too often
+- latency and token cost go up
 
-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`.
+This plugin closes that gap by keeping the knowledge base local, readable, and editable.
 
-Recommended example:
+## Best-practice layout
+
+```text
+private/
+  knowledge/
+  docs/
+  notes/
+  ideas/
+  06_Interest/
+
+shared/
+  knowledge/
+  docs/
+  notes/
+  ideas/
+  06_Interest/
+```
+
+## Best-practice storage
+
+Keep the index local, but point Markdown roots at a synced editor-friendly folder.
 
 ```json
 {
   "enabled": true,
   "privateMarkdownRoot": "~/Documents/Obsidian/MyVault/openclaw/private",
   "sharedMarkdownRoot": "~/Documents/Obsidian/MyVault/openclaw/shared",
-  "indexPath": "~/.openclaw/memory/vector/index.json",
-  "dimensions": 64
+  "indexPath": "~/.openclaw/memory/vector/index.json"
 }
 ```
 
-This gives you:
+That works especially well with:
 
-- 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
+- Obsidian
+- iCloud Drive
+- Git-synced repositories
+- Syncthing workspaces
 
-This first version exposes a lightweight local vector-style index interface and keeps the integration surface ready for later LanceDB-backed evolution.
+## Architecture
 
-## Product Positioning
+![Bamdra Suite Architecture](./docs/assets/architecture-technical-en.svg)
 
-`bamdra-memory-vector` is not meant to replace `bamdra-openclaw-memory`.
+## What it unlocks
 
-- `bamdra-openclaw-memory` is continuity-first
-- `bamdra-memory-vector` is recall enhancement
+With `bamdra-openclaw-memory`:
 
-Together they provide:
+- old work can be found through fuzzy recall
+- local docs can enter the answer path without prompt bloat
 
-- durable continuity across long sessions
-- Markdown-readable memory artifacts
-- lightweight semantic recall without extra infrastructure
+With `bamdra-user-bind`:
 
-## Build
+- private knowledge stays aligned with the correct user boundary
 
-```bash
-pnpm run bundle
-```
+## Repository
+
+- [GitHub organization](https://github.com/bamdra)
+- [Repository](https://github.com/bamdra/bamdra-memory-vector)
+- [Releases](https://github.com/bamdra/bamdra-memory-vector/releases)

package/README.zh-CN.md

@@ -1,87 +1,105 @@
 # bamdra-memory-vector
 
-`bamdra-memory-vector` 是 Bamdra OpenClaw 套件中的语义召回插件，而且它也可以独立运行。
+![Bamdra Animated Logo](./docs/assets/bamdra-logo-animated.svg)
 
-## 它做什么
+Bamdra 套件中的本地知识库与语义召回层。
+
+它可以独立运行，和 `bamdra-openclaw-memory` 配合时效果最好。
+
+单独安装：
+
+```bash
+openclaw plugins install @bamdra/bamdra-memory-vector
+```
+
+发布包下载：
 
-- 把记忆内容以 Markdown 可读形式写入本地
-- 建立轻量的本地语义索引
-- 按当前用户边界限制检索范围
-- 为长程记忆回捞提供 Top-K 语义召回
-- 保持私有记忆与共享知识分离
+- GitHub Releases: https://github.com/bamdra/bamdra-memory-vector/releases
+- 本地也可以执行 `pnpm package:release` 生成独立发布包
 
-## 开源内容说明
+[English README](./README.md)
 
-当前开源版的实际源码已经包含在这个仓库里。
+## 它做什么
+
+`bamdra-memory-vector` 会把本地 Markdown 变成真正可维护的知识库。
 
-- 源码入口：
-  [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)
+它会索引：
 
-仓库目前看起来比较轻，是因为首个公开版本刻意保持为紧凑、单入口插件。
+- `knowledge/`
+- `docs/`
+- `notes/`
+- `ideas/`
 
-## 当前运行模型
+其中 `ideas/` 只是通用示例名。如果你的 Obsidian 实际目录叫 `06_Interest/`，也完全可以按那个结构来放，插件同样可以把它当成灵感知识桶。
 
-- 私有 Markdown 根目录：
-  `~/.openclaw/memory/vector/markdown/private/`
-- 共享 Markdown 根目录：
-  `~/.openclaw/memory/vector/markdown/shared/`
-- 本地索引：
-  `~/.openclaw/memory/vector/index.json`
+并尽量让 OpenClaw 在上网之前先查本地知识。
 
-这一版提供的是轻量本地向量式索引接口，同时为后续 LanceDB 演进保留接入面。
+## 为什么重要
 
-`markdownRoot` 仍然保留兼容，但更推荐在正式环境里显式设置 `privateMarkdownRoot` 和 `sharedMarkdownRoot`。
+很多记忆系统最弱的一层，其实就是知识库层：
 
-## 随包 Skill
+- 知识越来越黑盒
+- 人不再愿意维护
+- web search 被过度使用
+- 延迟和 token 成本不断上升
 
-这个包现在会附带独立的 operator skill：
+这个插件补上的，正是这块短板。它让知识继续保持本地、可读、可改。
 
-- `bamdra-memory-vector-operator`
+## 最佳实践目录
 
-安装到 OpenClaw 后，bootstrap 可以把它复制到 `~/.openclaw/skills/` 并自动挂到 agent。
+```text
+private/
+  knowledge/
+  docs/
+  notes/
+  ideas/
+  06_Interest/
 
-## 最佳实践：兼容 Obsidian 的双库布局
+shared/
+  knowledge/
+  docs/
+  notes/
+  ideas/
+  06_Interest/
+```
 
-插件现在支持把私有记忆和共享知识分别落到两个 Markdown 根目录。这意味着你可以把 Markdown 指向 Obsidian 仓库、iCloud Drive、Git 同步目录或者 Syncthing 目录，而把本地索引仍然保留在 `~/.openclaw` 下面。
+## 最佳实践存储方式
 
-推荐配置示例：
+索引留在本地，Markdown 根目录指向一个会同步、会编辑的目录。
 
 ```json
 {
   "enabled": true,
   "privateMarkdownRoot": "~/Documents/Obsidian/MyVault/openclaw/private",
   "sharedMarkdownRoot": "~/Documents/Obsidian/MyVault/openclaw/shared",
-  "indexPath": "~/.openclaw/memory/vector/index.json",
-  "dimensions": 64
+  "indexPath": "~/.openclaw/memory/vector/index.json"
 }
 ```
 
-这样做的好处是：
+这尤其适合：
 
-- 私有记忆和共享知识库天然分开
-- Markdown 文件可以在任何同步设备上直接编辑
-- OpenClaw 继续使用本地索引，不依赖远端向量服务
-- 更适合把 Obsidian 作为长期知识库编辑入口
+- Obsidian
+- iCloud Drive
+- Git 同步仓库
+- Syncthing 工作区
 
-## 产品定位
+## 架构图
 
-`bamdra-memory-vector` 不是用来替代 `bamdra-openclaw-memory` 的。
+![Bamdra 套件架构图](./docs/assets/architecture-technical-zh.svg)
 
-- `bamdra-openclaw-memory` 更强调连续性
-- `bamdra-memory-vector` 更强调召回增强
+## 它能解锁什么
 
-两者组合后的价值是：
+与 `bamdra-openclaw-memory` 组合时：
 
-- 更强的长会话连续性
-- Markdown 可读、可维护的记忆载体
-- 不依赖重型基础设施的轻量语义召回
+- 旧工作可以通过模糊召回被重新找回
+- 本地文档能进入答案链路，而不是靠 prompt 硬塞
 
-## 构建
+与 `bamdra-user-bind` 组合时：
 
-```bash
-pnpm run bundle
-```
+- 私有知识会继续对齐到正确用户边界
+
+## 仓库地址
+
+- [GitHub 首页](https://github.com/bamdra)
+- [仓库地址](https://github.com/bamdra/bamdra-memory-vector)
+- [Releases](https://github.com/bamdra/bamdra-memory-vector/releases)

package/dist/index.js

@@ -41,7 +41,7 @@ var PLUGIN_ID = "bamdra-memory-vector";
 var SKILL_ID = "bamdra-memory-vector-operator";
 var SEARCH_TOOL_NAME = "bamdra_memory_vector_search";
 var REINDEX_TOOL_NAME = "bamdra_memory_vector_reindex";
-var DEFAULT_LIBRARY_DIRS = ["knowledge", "docs", "notes", "ideas"];
+var DEFAULT_LIBRARY_DIRS = ["knowledge", "docs", "notes", "ideas", "06_Interest"];
 var RUNTIME_DIR = "_runtime";
 var SUPPORTED_TEXT_EXTENSIONS = /* @__PURE__ */ new Set([
   ".md",
@@ -164,7 +164,7 @@ function register(api) {
   exposeVectorApi(runtime);
   api.registerTool?.({
     name: SEARCH_TOOL_NAME,
-    description: "Search the current user's vector memory and knowledge index",
+    description: "Search the current user's local vector-backed knowledge and memory index before falling back to web lookup",
     parameters: {
       type: "object",
       additionalProperties: false,

package/openclaw.plugin.json

@@ -3,7 +3,7 @@
   "type": "tool",
   "name": "Bamdra Memory Vector",
   "description": "Local vector-style semantic retrieval enhancement for Bamdra memory.",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "main": "./dist/index.js",
   "skills": ["./skills"],
   "configSchema": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bamdra/bamdra-memory-vector",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "Lightweight local semantic retrieval enhancement for the Bamdra OpenClaw memory suite.",
   "license": "MIT",
   "homepage": "https://www.bamdra.com",
@@ -34,7 +34,8 @@
   },
   "scripts": {
     "bundle": "node ../bamdra-openclaw-memory/scripts/run-local-bin.mjs tsup",
-    "prepublishOnly": "pnpm run bundle"
+    "prepublishOnly": "pnpm run bundle",
+    "package:release": "node ./scripts/package-release.mjs"
   },
   "openclaw": {
     "id": "bamdra-memory-vector",

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

@@ -25,6 +25,7 @@ It complements topic memory. Use it when the user remembers something fuzzily, w
 - do not flood the prompt with low-signal chunks
 - prefer a few strong recalls over many weak ones
 - when the question plausibly targets local docs, notes, ideas, or knowledge files, check local vector-backed knowledge before using web search
+- for repository docs, changelogs, READMEs, SOPs, or user-maintained Markdown libraries, local recall should be the default first step, not a fallback
 
 ## Markdown Knowledge Model
 
@@ -57,3 +58,4 @@ Shared examples:
 - 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
+- if local recall returns relevant results, answer from it first and only suggest web search when the user explicitly asks for public latest information beyond the local library