@bamdra/bamdra-memory-vector 0.1.8 → 0.1.10

package/README.md

@@ -1,89 +1,83 @@
 # bamdra-memory-vector
 
-`bamdra-memory-vector` is the semantic retrieval plugin for the Bamdra OpenClaw suite.
+The local knowledge and semantic recall layer for the Bamdra 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.
+It can run independently, and it becomes most powerful when paired with `bamdra-openclaw-memory`.
 
-## What It Does
+[中文文档](./README.zh-CN.md)
 
-- 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
+## What it does
 
-## Open Source Contents
+`bamdra-memory-vector` turns local Markdown into a maintainable knowledge base.
 
-This repository already includes the real source code for the current open-source version.
+It indexes:
 
-- 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)
+- `knowledge/`
+- `docs/`
+- `notes/`
+- `ideas/`
 
-The repository currently looks small because the first public version is intentionally a compact, single-entry plugin.
+and helps OpenClaw search that local knowledge before falling back to the web.
 
-## Current Runtime Model
+## Why it matters
 
-- private Markdown root:
-  `~/.openclaw/memory/vector/markdown/private/`
-- shared Markdown root:
-  `~/.openclaw/memory/vector/markdown/shared/`
-- local index:
-  `~/.openclaw/memory/vector/index.json`
+The weakest part of many memory systems is the knowledge layer:
 
-`markdownRoot` is still supported as a legacy base path, but the recommended production setup is to set `privateMarkdownRoot` and `sharedMarkdownRoot` explicitly.
+- knowledge becomes opaque
+- humans stop editing it
+- web search gets used too often
+- latency and token cost go up
 
-## Bundled Skill
+This plugin closes that gap by keeping the knowledge base local, readable, and editable.
 
-This package now ships its own standalone operator skill:
+## Best-practice layout
 
-- `bamdra-memory-vector-operator`
+```text
+private/
+  knowledge/
+  docs/
+  notes/
+  ideas/
 
-When OpenClaw bootstraps the installed plugin, that skill can be materialized into `~/.openclaw/skills/` and attached automatically.
-
-## Best Practice: Obsidian-Friendly Layout
+shared/
+  knowledge/
+  docs/
+  notes/
+  ideas/
+```
 
-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`.
+## Best-practice storage
 
-Recommended example:
+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.
+## What it unlocks
 
-## Product Positioning
+With `bamdra-openclaw-memory`:
 
-`bamdra-memory-vector` is not meant to replace `bamdra-openclaw-memory`.
+- old work can be found through fuzzy recall
+- local docs can enter the answer path without prompt bloat
 
-- `bamdra-openclaw-memory` is continuity-first
-- `bamdra-memory-vector` is recall enhancement
+With `bamdra-user-bind`:
 
-Together they provide:
+- private knowledge stays aligned with the correct user boundary
 
-- durable continuity across long sessions
-- Markdown-readable memory artifacts
-- lightweight semantic recall without extra infrastructure
+## Repository
 
-## Build
-
-```bash
-pnpm run bundle
-```
+- [GitHub organization](https://github.com/bamdra)
+- [Repository](https://github.com/bamdra/bamdra-memory-vector)

package/README.zh-CN.md

@@ -1,87 +1,83 @@
 # bamdra-memory-vector
 
-`bamdra-memory-vector` 是 Bamdra OpenClaw 套件中的语义召回插件，而且它也可以独立运行。
+Bamdra 套件中的本地知识库与语义召回层。
 
-## 它做什么
-
-- 把记忆内容以 Markdown 可读形式写入本地
-- 建立轻量的本地语义索引
-- 按当前用户边界限制检索范围
-- 为长程记忆回捞提供 Top-K 语义召回
-- 保持私有记忆与共享知识分离
+它可以独立运行，和 `bamdra-openclaw-memory` 配合时效果最好。
 
-## 开源内容说明
+[English README](./README.md)
 
-当前开源版的实际源码已经包含在这个仓库里。
+## 它做什么
 
-- 源码入口：
-  [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)
+`bamdra-memory-vector` 会把本地 Markdown 变成真正可维护的知识库。
 
-仓库目前看起来比较轻，是因为首个公开版本刻意保持为紧凑、单入口插件。
+它会索引：
 
-## 当前运行模型
+- `knowledge/`
+- `docs/`
+- `notes/`
+- `ideas/`
 
-- 私有 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/
 
-## 最佳实践：兼容 Obsidian 的双库布局
+shared/
+  knowledge/
+  docs/
+  notes/
+  ideas/
+```
 
-插件现在支持把私有记忆和共享知识分别落到两个 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-openclaw-memory` 组合时：
 
-- `bamdra-openclaw-memory` 更强调连续性
-- `bamdra-memory-vector` 更强调召回增强
+- 旧工作可以通过模糊召回被重新找回
+- 本地文档能进入答案链路，而不是靠 prompt 硬塞
 
-两者组合后的价值是：
+与 `bamdra-user-bind` 组合时：
 
-- 更强的长会话连续性
-- Markdown 可读、可维护的记忆载体
-- 不依赖重型基础设施的轻量语义召回
+- 私有知识会继续对齐到正确用户边界
 
-## 构建
+## 仓库地址
 
-```bash
-pnpm run bundle
-```
+- [GitHub 首页](https://github.com/bamdra)
+- [仓库地址](https://github.com/bamdra/bamdra-memory-vector)

package/dist/index.js

@@ -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.8",
+  "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.8",
+  "version": "0.1.10",
   "description": "Lightweight local semantic retrieval enhancement for the Bamdra OpenClaw memory suite.",
   "license": "MIT",
   "homepage": "https://www.bamdra.com",

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

@@ -24,12 +24,16 @@ It complements topic memory. Use it when the user remembers something fuzzily, w
 - keep cross-user boundaries intact
 - 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
 
 - 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
+- common human-managed directories include `knowledge/`, `docs/`, `notes/`, and `ideas/`
+- `_runtime/` is system-managed and should not be treated as the main editing area
 
 ## Shared vs Private
 
@@ -54,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