@synth-coder/memhub 0.2.1 → 0.2.3

package/docs/proposals/proposal-close-gates.md

@@ -1,58 +1,58 @@
-# Proposal: Close Remaining Quality Gates (Phase 2)
-
-## Context
-Current implementation already has broad functionality and passing test suites, but quality gates are still blocked by:
-
-1. ESLint configuration/type-aware parsing issues on test files
-2. TypeScript typecheck errors in server and storage/service imports
-3. Coverage gate failure on function coverage (<80%)
-4. Project path inconsistency (`workspace/workspace/memhub`)
-
-## Root Causes
-- ESLint `parserOptions.project` only pointed to `tsconfig.json`, while test files are not included there.
-- Some implementation details introduced strict-mode lint/type mismatches (`any` usage, fallthrough, readonly/no-unused issues).
-- Existing server tests focus on constants/contracts but not internal execution paths, leaving many functions uncovered.
-- Project was scaffolded under a nested directory.
-
-## Plan of Record
-
-### Step 1 — Fix static quality gates
-- Update ESLint type-aware project references to include test TS config.
-- Update `tsconfig.test.json` include set.
-- Fix strict lint/type issues in server/service/storage/utils modules.
-
-### Step 2 — Raise function coverage to >=80%
-- Add focused tests for MCP server runtime paths:
-  - JSON parsing failure path
-  - invalid request path
-  - method dispatch (`initialize`, `tools/list`, `tools/call`, unknown method)
-  - error handling (`ServiceError`, validation-like error, generic error)
-  - response/error serialization
-  - log filtering behavior
-- Preserve existing passing behavior and avoid over-mocking core service logic.
-
-### Step 3 — Validate full gate
-Run and require pass for:
-- `npm run lint`
-- `npm run typecheck`
-- `npm run test`
-- `npm run test:coverage` (global lines/functions/branches/statements >= 80)
-
-### Step 4 — Normalize repository location
-- Move project to `C:\Users\cloud_user\.openclaw\workspace\memhub` (if missing).
-- Verify scripts still run from new root.
-
-## Acceptance Criteria
-- No lint errors
-- No typecheck errors
-- All tests pass
-- Coverage thresholds all >= 80%
-- Repository available at normalized path
-
-## Risks and Mitigations
-- **Risk:** Private method tests become brittle.
-  - **Mitigation:** Test externally visible behavior and error contracts where possible; keep internals tests focused and minimal.
-- **Risk:** Path migration may break references.
-  - **Mitigation:** Move whole directory atomically and rerun full gate.
-- **Risk:** Coverage improvements skew test value.
-  - **Mitigation:** Prefer behavior-driven tests over shallow line-hitting.
+# Proposal: Close Remaining Quality Gates (Phase 2)
+
+## Context
+Current implementation already has broad functionality and passing test suites, but quality gates are still blocked by:
+
+1. ESLint configuration/type-aware parsing issues on test files
+2. TypeScript typecheck errors in server and storage/service imports
+3. Coverage gate failure on function coverage (<80%)
+4. Project path inconsistency (`workspace/workspace/memhub`)
+
+## Root Causes
+- ESLint `parserOptions.project` only pointed to `tsconfig.json`, while test files are not included there.
+- Some implementation details introduced strict-mode lint/type mismatches (`any` usage, fallthrough, readonly/no-unused issues).
+- Existing server tests focus on constants/contracts but not internal execution paths, leaving many functions uncovered.
+- Project was scaffolded under a nested directory.
+
+## Plan of Record
+
+### Step 1 — Fix static quality gates
+- Update ESLint type-aware project references to include test TS config.
+- Update `tsconfig.test.json` include set.
+- Fix strict lint/type issues in server/service/storage/utils modules.
+
+### Step 2 — Raise function coverage to >=80%
+- Add focused tests for MCP server runtime paths:
+  - JSON parsing failure path
+  - invalid request path
+  - method dispatch (`initialize`, `tools/list`, `tools/call`, unknown method)
+  - error handling (`ServiceError`, validation-like error, generic error)
+  - response/error serialization
+  - log filtering behavior
+- Preserve existing passing behavior and avoid over-mocking core service logic.
+
+### Step 3 — Validate full gate
+Run and require pass for:
+- `npm run lint`
+- `npm run typecheck`
+- `npm run test`
+- `npm run test:coverage` (global lines/functions/branches/statements >= 80)
+
+### Step 4 — Normalize repository location
+- Move project to `C:\Users\cloud_user\.openclaw\workspace\memhub` (if missing).
+- Verify scripts still run from new root.
+
+## Acceptance Criteria
+- No lint errors
+- No typecheck errors
+- All tests pass
+- Coverage thresholds all >= 80%
+- Repository available at normalized path
+
+## Risks and Mitigations
+- **Risk:** Private method tests become brittle.
+  - **Mitigation:** Test externally visible behavior and error contracts where possible; keep internals tests focused and minimal.
+- **Risk:** Path migration may break references.
+  - **Mitigation:** Move whole directory atomically and rerun full gate.
+- **Risk:** Coverage improvements skew test value.
+  - **Mitigation:** Prefer behavior-driven tests over shallow line-hitting.

package/docs/tool-calling-policy.md

@@ -1,107 +1,101 @@
-# Tool Calling Policy (STM-first)
-
-> 目标：让模型在每轮任务中稳定形成「先加载短期记忆，再产出，再回写记忆」的闭环。
-
-## 一、调用时序（强约束）
-
-1. **首轮调用 `memory_load`**（在响应用户前）
-   - 用于加载当前会话/任务相关短期记忆（STM）
-   - 若无命中，继续任务，不阻塞
-
-2. **末轮调用 `memory_update`**（在本轮输出结束前）
-   - 将本轮新增的关键上下文写回
-   - 重点写入：决策、约束变更、待办变化、关键结论
-
----
-
-## 二、STM 判据（3 轮复用原则）
-
-若信息在未来 **3 轮** 内很可能被再次引用，则纳入 STM：
-
-- 当前任务目标/范围
-- 新确认的约束条件
-- 待办项与状态变化（pending / done）
-- 临时变量、参数、文件路径、报错栈
-- 用户明确修正/改口（需求切换）
-
-不满足则不强行写入，避免噪音。
-
----
-
-## 三、建议工具定义（简化版）
-
-## `memory_load`
-**作用**：统一“看记忆”，用于当前轮开头加载上下文。
-
-**建议入参**：
-- `session_id`（可选，推荐）
-- `date`（可选，默认今天）
-- `limit`（可选，默认 20）
-- `tags`（可选）
-- `category`（可选）
-- `query`（可选）
-- `scope`（可选：`stm|all`，默认 `stm`）
-
-**建议返回**：
-- `items[]`（记忆条目）
-- `summary`（可选摘要）
-- `pending[]` / `done[]`（若可提取）
-
----
-
-## `memory_update`
-**作用**：统一“写记忆”，用于当前轮末尾回写。
-
-**建议入参**：
-- `session_id`（可选；无则自动生成并返回）
-- `date`（可选，默认今天）
-- `mode`：`append|upsert`（默认 `append`）
-- `entry_type`：`decision|preference|knowledge|todo|state_change`
-- `title`
-- `content`
-- `tags[]`
-- `category`
-- `importance`（1-5）
-
-**建议返回**：
-- `id`
-- `session_id`
-- `file_path`
-- `created|updated`
-
----
-
-## 四、并发与目录规范
-
-为支持多个 CLI 同时写入，建议目录如下：
-
-```text
-memories/
-  YYYY-MM-DD/
-    <session_uuid>/
-      2026-03-03T16-41-23.123Z-<slug>.md
-```
-
-说明：
-- 同一天按 `session_uuid` 分桶，避免并发冲突
-- 每条记录仍保留 YAML + Markdown 正文
-- `session_uuid` 可来自调用方；缺省由服务端生成
-
----
-
-## 五、触发更新条件
-
-在以下事件发生时，优先触发 `memory_update`：
-
-- 用户显式改需求（如“换个方案”）
-- 任务状态切换（分析 → 实现 / 实现 → 验证）
-- 新信息与既有 STM 冲突
-- 本轮产出形成可复用结论
-
----
-
-## 六、设计原则
-
-- **STM 保留细节，不做过度抽象**
-- **LTM 另层抽取，不与 STM 混存**
-- **先 load，后 update，形成闭环**
+# Tool Calling Policy (情境驱动)
+
+> 目标：让记忆调用像人类一样自然——回忆由情境触发，记忆在无意识中形成。
+
+## 一、核心理念：从"时序驱动"到"情境驱动"
+
+人类的记忆规律：
+- **回忆是触发的** — 不是按计划"现在是回忆时间"，而是看到相关线索才想起
+- **记忆是无意识的** — 重要的经历自然留下痕迹，不需要刻意"现在要记住"
+
+因此，MemHub 的工具调用不应是"首轮必调 load，末轮必调 update"的机械流程，而是根据情境自然触发。
+
+---
+
+## 二、触发式调用原则
+
+### `memory_load` 触发条件
+
+当出现以下情境时，调用 memory_load：
+
+- 用户提到过往经历（"之前"、"记得吗"、"像上次那样"）
+- 遇到似曾相识的任务场景
+- 需要参考用户偏好做决策
+- 当前信息可能与过往冲突（用户纠正了你的假设）
+- 不确定用户的既有偏好或约束
+
+**不触发的情况**：
+- 简单明确的操作（"读取文件X"、"列出目录Y"）
+- 一次性任务，无需参考历史
+- 当前上下文已足够
+
+### `memory_update` 触发条件
+
+当出现以下情境时，调用 memory_update：
+
+- 发现用户偏好（"我更喜欢..."、"不要用..."）
+- 做出了有理由的技术决策
+- 纠正了一个误解或错误假设
+- 用户显式要求记住（"下次记住..."）
+- 项目上下文发生重要变化（技术栈、约束、团队规范）
+
+**不触发的情况**：
+- 简单的读写操作
+- 临时性、一次性的信息
+- 信息在短期内不会被复用
+
+---
+
+## 三、工具参考
+
+### `memory_load`
+
+按情境加载相关记忆，用于辅助当前任务。
+
+**参数**：
+- `query` — 搜索关键词或问题
+- `tags` — 按标签过滤
+- `category` — 按类别过滤
+- `limit` — 返回数量限制
+
+**返回**：
+- `items[]` — 匹配的记忆条目
+
+### `memory_update`
+
+记录值得保留的信息，为未来对话提供上下文。
+
+**参数**：
+- `content` — 要记录的内容（必需）
+- `title` — 简短标题
+- `entryType` — 类型：`preference`（偏好）、`decision`（决策）、`context`（上下文）、`fact`（事实）
+- `tags` — 标签数组
+- `category` — 分类
+- `importance` — 重要程度 1-5
+
+**返回**：
+- `id` — 记录 ID
+- `created` — 是否新建
+
+---
+
+## 四、存储规范
+
+目录结构支持并发写入：
+
+```text
+memories/
+  YYYY-MM-DD/
+    <session_uuid>/
+      2026-03-03T16-41-23.123Z-<slug>.md
+```
+
+每条记录保留 YAML 元数据 + Markdown 正文。
+
+---
+
+## 五、设计原则
+
+- **情境触发，而非时序强制** — 像人类记忆一样自然
+- **有价值才记录** — 避免噪音，保留真正可复用的信息
+- **偏好和决策优先** — 这些是最值得跨会话保留的内容

package/docs/vector-search.md

@@ -0,0 +1,306 @@
+# 向量语义搜索
+
+MemHub 集成了基于向量的语义搜索功能，使用本地 ONNX 模型实现智能记忆检索。
+
+## 概述
+
+### 为什么需要向量搜索？
+
+传统的关键词匹配存在以下限制：
+
+- 无法理解语义相似性（"架构" vs "设计"）
+- 无法处理同义词（"偏好" vs "喜好"）
+- 无法进行模糊匹配（"React 组件" vs "Component"）
+
+向量语义搜索通过将文本转换为高维向量，计算语义相似度，提供更智能的检索体验。
+
+### 技术实现
+
+- **Embedding 模型**: Xenova/all-MiniLM-L6-v2
+- **向量维度**: 384
+- **距离度量**: Cosine distance
+- **向量数据库**: LanceDB
+- **模型缓存**: `~/.cache/huggingface/`
+
+## 架构设计
+
+### 1. 分层架构
+
+```
+┌─────────────────────────────────────┐
+│     Memory Service (业务层)         │
+│  - memoryLoad(query, tags, ...)     │
+└──────────────┬──────────────────────┘
+               │
+       ┌───────┴────────┐
+       │                │
+┌──────▼─────┐    ┌────▼────────┐
+│ Embedding  │    │   Vector    │
+│  Service   │    │   Index     │
+│ (ONNX)     │    │ (LanceDB)   │
+└────────────┘    └─────────────┘
+```
+
+### 2. 数据流
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant MemoryService
+    participant EmbeddingService
+    participant VectorIndex
+    participant MarkdownStorage
+    
+    User->>MemoryService: memory_load(query="架构设计")
+    MemoryService->>EmbeddingService: embed("架构设计")
+    EmbeddingService-->>MemoryService: [0.1, 0.2, ..., 0.384]
+    MemoryService->>VectorIndex: search(vector, limit=20)
+    VectorIndex-->>MemoryService: [{id, _distance}, ...]
+    MemoryService->>MarkdownStorage: read([id1, id2, ...])
+    MarkdownStorage-->>MemoryService: [Memory, ...]
+    MemoryService-->>User: MemoryLoadOutput
+```
+
+## 使用方式
+
+### 1. 基本用法
+
+```typescript
+// 语义搜索
+const result = await memoryService.memoryLoad({
+  query: "如何实现用户认证",
+  limit: 10
+});
+
+// 返回语义最相关的记忆
+console.log(result.items);
+```
+
+### 2. 混合搜索
+
+```typescript
+// 语义搜索 + 元数据过滤
+const result = await memoryService.memoryLoad({
+  query: "数据库优化",
+  tags: ["performance", "backend"],
+  category: "engineering",
+  limit: 10
+});
+```
+
+### 3. 会话隔离
+
+```typescript
+// 限定在特定会话中搜索
+const result = await memoryService.memoryLoad({
+  query: "项目进度",
+  sessionId: "550e8400-e29b-41d4-a716-446655440000",
+  scope: "stm"
+});
+```
+
+## 配置选项
+
+### 环境变量
+
+```bash
+# 启用/禁用向量搜索（默认: true）
+MEMHUB_VECTOR_SEARCH=true
+
+# 存储路径（默认: ./memories）
+MEMHUB_STORAGE_PATH=/path/to/memories
+```
+
+### 禁用向量搜索
+
+在测试环境或资源受限场景下，可以禁用向量搜索：
+
+```bash
+MEMHUB_VECTOR_SEARCH=false
+```
+
+禁用后：
+- `memory_load` 降级为纯元数据过滤
+- `memory_update` 不更新向量索引
+- 降低内存和磁盘占用
+
+## Embedding 服务
+
+### 模型特性
+
+- **名称**: Xenova/all-MiniLM-L6-v2
+- **大小**: ~23MB
+- **语言**: 英文为主，支持多语言
+- **性能**: 快速推理，适合实时搜索
+
+### 单例模式
+
+```typescript
+class EmbeddingService {
+  private static instance: EmbeddingService | null = null;
+  
+  static getInstance(): EmbeddingService {
+    if (!this.instance) {
+      this.instance = new EmbeddingService();
+    }
+    return this.instance;
+  }
+  
+  async embed(text: string): Promise<number[]> {
+    // 返回 384 维归一化向量
+  }
+}
+```
+
+### 懒加载
+
+模型在首次使用时加载：
+
+```typescript
+// 构造函数不加载模型
+const service = EmbeddingService.getInstance();
+
+// 首次调用 embed() 时加载模型
+const vector = await service.embed("some text");
+
+// 后续调用复用已加载的模型
+const vector2 = await service.embed("another text");
+```
+
+## Vector Index
+
+### LanceDB 特性
+
+- **嵌入式**: 无需独立服务，直接访问文件系统
+- **高性能**: 基于 Apache Arrow 列式存储
+- **ACID**: 支持事务和并发控制
+- **可重建**: 可随时从 Markdown 重建索引
+
+### 索引结构
+
+```sql
+CREATE TABLE memories (
+  id TEXT PRIMARY KEY,
+  vector FLOAT[384],
+  title TEXT,
+  category TEXT,
+  tags TEXT,  -- JSON string
+  importance INT,
+  createdAt TEXT,
+  updatedAt TEXT
+);
+```
+
+### 搜索算法
+
+1. **向量搜索**: 使用 COSINE 距离
+2. **Top-K**: 返回距离最小的 K 个结果
+3. **过滤**: 可结合 SQL WHERE 子句
+
+```typescript
+// 搜索示例
+const results = await table
+  .vectorSearch(queryVector)
+  .where("category = 'engineering'")
+  .limit(10)
+  .toArray();
+```
+
+## 重建索引
+
+如果向量索引损坏或需要重建：
+
+```typescript
+// 1. 删除现有索引
+rm -rf memories/.lancedb
+
+// 2. 重新启动服务，索引会在下次写入时自动重建
+// 或手动触发重建（TODO: 添加 CLI 命令）
+```
+
+## 性能优化
+
+### 1. 模型缓存
+
+模型下载后缓存在 `~/.cache/huggingface/`，避免重复下载。
+
+### 2. 向量缓存
+
+LanceDB 自动缓存热门向量，提升搜索速度。
+
+### 3. 批量处理
+
+对于大量记忆条目，建议批量更新：
+
+```typescript
+// TODO: 添加批量更新接口
+await memoryService.batchUpdate(memories);
+```
+
+### 4. 异步更新
+
+向量索引更新在后台异步执行，不阻塞主流程：
+
+```typescript
+// Markdown 写入完成立即返回
+// 向量索引在后台更新
+await memoryService.memoryUpdate(input);
+```
+
+## 错误处理
+
+### 降级策略
+
+```typescript
+try {
+  // 尝试向量搜索
+  const results = await vectorIndex.search(vector, limit);
+} catch (error) {
+  // 降级为文本搜索
+  console.warn('Vector search failed, falling back to text search');
+  const results = await markdownStorage.search(query, limit);
+}
+```
+
+### 日志记录
+
+```typescript
+// 成功
+console.log('Vector search completed', { query, results: results.length });
+
+// 失败
+console.error('Vector search failed', { error: error.message });
+```
+
+## 限制与注意事项
+
+### 1. 语言支持
+
+当前模型主要针对英文优化，中文效果可能不如英文。
+
+### 2. 模型大小
+
+模型约 23MB，首次使用时需要下载。
+
+### 3. 内存占用
+
+ONNX Runtime 需要额外内存（约 100-200MB）。
+
+### 4. 向量维度
+
+固定 384 维，无法更改。
+
+## 未来规划
+
+- [ ] 支持多语言模型（中文优化）
+- [ ] 添加模型管理 CLI 命令
+- [ ] 支持自定义 embedding 模型
+- [ ] 添加索引健康检查
+- [ ] 支持向量维度配置
+- [ ] 优化大批量索引构建
+
+## 参考资料
+
+- [LanceDB 文档](https://lancedb.github.io/lancedb/)
+- [Xenova Transformers](https://github.com/xenova/transformers.js)
+- [all-MiniLM-L6-v2 模型](https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2)