@restregular/dsh-memory 0.3.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,103 +1,82 @@
1
1
  # @restregular/dsh-memory
2
2
 
3
- DeepSeek Harness 的本地长期记忆插件(核心包):JSONL 存储 + 本地向量检索 + 四个模型工具 + 自动召回注入。
3
+ DeepSeek Harness 的本地长期记忆插件 —— **单包单入口**:JSONL 存储 + 本地向量检索(BGE-M3)+ 四个模型工具 + 自动召回注入 + 设置页管理面板。
4
4
 
5
5
  ## 安装
6
6
 
7
- 装进任意 DSH profile(例如桌面端 `~/.dsh/profiles/desktop`,Web 端 `~/.dsh/profiles/web`):
7
+ 装进任意 DSH profile(桌面端 `~/.dsh/profiles/desktop`,Web 端 `~/.dsh/profiles/web`):
8
8
 
9
9
  ```bash
10
10
  pnpm add @restregular/dsh-memory
11
11
  ```
12
12
 
13
- 本包同时提供三个 loader entry,装好后自动生效(bundle patch 已随包分发):
13
+ 本包只有**一条 Loader entry**,装好后自动生效(bundle patch 随包分发),面板与记忆工具同属这一条:
14
14
 
15
- | entry id | 作用 |
15
+ | 部分 | 作用 |
16
16
  | --- | --- |
17
- | `dsh-memory-local` | 提供 `memory` 服务:存储、检索、向量回填 |
18
- | `dsh-tool-memory` | 注册 `memory_save` / `memory_search` / `memory_list` / `memory_forget` 四个工具 |
19
- | `dsh-memory-inject` | 在 `agent/pre-step` 注入召回块(可选,可关) |
17
+ | provider | 提供 `memory` 服务:JSONL 存储、双通道检索、向量回填、向量后端生命周期 |
18
+ | tools | 注册 `memory_save` / `memory_search` / `memory_list` / `memory_forget` |
19
+ | inject | 在 `agent/pre-step` 注入召回块(可在配置里关) |
20
+ | panel | 设置页「记忆」区块 + `/memory/api` 管理接口 |
20
21
 
21
- > 管理面板是独立包:**@restregular/dsh-memory-panel**(设置页里查看/编辑/删除记忆,并手动启停向量服务)。
22
+ > 为什么合并成一个包:宿主的 `dsh-client-modules` 只在「某条活 Loader entry 能解析到包名」时为该包提供 client bundle,而且要求**一个包名只有一个解析源**。把 provider/工具/注入/面板拆成多条 entry,会让同一个包名被多个来源命中 → 客户端图组合失败(桌面端 fail-loud)。一个包一条 entry 是它唯一稳定的形态。
22
23
 
23
24
  ## 配置
24
25
 
25
- patch 里给 `dsh-memory-local` 传配置即可(默认值通常够用):
26
+ 给 `dsh-memory` 传配置即可(默认值通常够用)。provider 的配置在顶层,工具/注入/面板各占一个小节:
26
27
 
27
28
  ```yaml
28
- - id: dsh-memory-local
29
+ - id: dsh-memory
30
+ name: '@restregular/dsh-memory'
29
31
  config:
30
- storeDir: '~/.dsh/memory-store' # 默认 <home>/.dsh/memory-store
32
+ storeDir: '~/.dsh/memory-store'
31
33
  scopes: { global: true, project: true }
32
34
  retrieval:
33
35
  topK: 5
36
+ recallN: 30
34
37
  vector:
35
38
  enabled: true
36
39
  endpoint: 'http://127.0.0.1:8078/v1/embeddings'
37
40
  model: bge-m3
38
41
  dims: 1024
39
- timeoutMs: 300 # 交互检索预算(要紧)
42
+ timeoutMs: 300 # 交互检索预算(要紧)
40
43
  writeTimeoutMs: 10000 # 保存时嵌整条记录
41
44
  backfillTimeoutMs: 30000 # 批量回填
42
- backfillMaxChars: 8000
43
- llm: { enabled: false } # LLM 重排(可选)
45
+ llm: { enabled: false } # LLM 重排(可选)
44
46
  limits: { maxRecordsPerScope: 2000, maxRecordChars: 4000 }
45
- secrets: { enabled: true, mode: refuse } # 拒绝写入疑似凭据
47
+ secrets: { enabled: true, mode: refuse }
48
+ tools: { defaultScope: project } # 或 global;projectScope 默认 project:<cwd>
49
+ inject: { enabled: true, tokenBudget: 500, topK: 5 }
50
+ panel: { route: '/memory/api' }
46
51
  ```
47
52
 
48
- ### 向量检索(可选,默认不启用)
53
+ > 原来靠「多条 entry 各自一个 config 块」表达的独立开关,现在是小节里的字段:不想要自动召回就 `inject.enabled: false`,不需要模型工具就 `tools.enabled: false`。
49
54
 
50
- **不配任何东西也能用**:检索自动降级为纯词法匹配(IDF + CJK bigram),保存/搜索/注入全部正常。向量检索是**按配置启用**的——写了 `endpoint`、配了 `spawn`、或面板里装了本地后端,才会去碰网络;否则一个请求都不发(不会白试、不会刷错误日志)。
55
+ ### 向量检索(可选,默认不启用)
51
56
 
52
- 三条启用路径,任选一条:
57
+ **不配任何东西也能用**:检索自动降级为纯词法匹配(IDF + CJK bigram)。向量检索是**按配置启用**的——写了 `endpoint`、配了 `spawn`、或面板里装了本地后端,才会去碰网络。
53
58
 
54
- **① 面板一键装(推荐给不想折腾的人)**:设置页「记忆」→「向量服务」卡片 → 点 **下载并配置**。插件会下载 llama.cpp CPU 版运行时 + bge-m3 量化模型(约 440MB)到 `retrieval.vector.autoInstall.dir`(默认:显式配了 `storeDir` 时用它上一级目录,否则 `~/.dsh/memory-vector`),解压后就地托管启动,下次开机自动拉起、退出自动关闭。
59
+ 三条启用路径,任选一条:
55
60
 
56
- **② 云端 / 自建 OpenAI 兼容服务**(不用下模型):
61
+ 1. **面板一键装**:设置页「记忆」→「向量服务」→ **下载并配置**(llama.cpp CPU 运行时 + bge-m3 量化模型,约 440MB,装在 `retrieval.vector.autoInstall.dir`,默认 `~/.dsh/memory-vector`)。
62
+ 2. **云端 / 自建 OpenAI 兼容服务**:写 `endpoint` + `model` + `dims` 即可(只调用,不启停)。
63
+ 3. **自己管进程**:配 `retrieval.vector.spawn`(exe / model / cwd / logFile),由插件托管启动与关闭。
57
64
 
58
- ```yaml
59
- vector:
60
- enabled: true
61
- endpoint: 'https://api.example.com/v1/embeddings'
62
- model: 'bge-m3' # 服务端要求的模型名
63
- dims: 1024 # 必须与服务端输出维度一致
64
- ```
65
-
66
- **③ 自己管进程(手填路径)**:
67
-
68
- ```yaml
69
- vector:
70
- spawn: # 让插件托管 llama-server 进程(opt-in)
71
- enabled: true
72
- exe: '/path/to/llama-server.exe'
73
- model: '/path/to/bge-m3-Q4_K_M.gguf'
74
- cwd: '/path/to/llamacpp' # 该目录须含 llama-server-impl.dll
75
- logFile: '/path/to/llama-server.log'
76
- threads: 6
77
- ```
78
-
79
- - 路径 ①③ 都由插件托管进程:应用启动后台拉起、应用退出自动关闭;已在跑的实例(有 PID 文件)会被接管,没有 PID 文件的外部实例不接管。路径 ② 只调用、不启停(面板会标成「外部服务」)。
80
- - 若 `autoInstall.dir`(或 `storeDir` 上一级)里已经存在 `llamacpp/` + `models/`,插件会**直接采用**,面板只显示状态,不需要重新下载。
81
- - 面板的开关只在"进程确实由本应用托管"时出现;未配置给下载按钮,外部服务只显示连通性,配置里关掉了就只解释原因——不会出现一个永远灰着的开关。
82
-
83
- ### 维护与卸载
65
+ ## 安全
84
66
 
85
- 面板底部有一个「维护」区,不可撤销的操作都走**两步确认**(第一次点击只是把按钮换成"确认…"):
67
+ - `/memory/api` 的**每个**路由都先过一道围栏(`refuseRequest`):宿主 `connection.requestRejection`(Host/Origin 检查 + 浏览器登录)可用时以它为准,围栏抛错一律 403(失败关闭);旧宿主没有该服务时退化为"只认 loopback 权威 + 同源"。原因:注册在裸 webServer 上的路由不在宿主 `/api` 围栏与浏览器登录之后,而这里的接口能读、改、删、清空全部记忆。
68
+ - 记忆内容在写入前过凭据扫描(`secrets.mode: refuse | redact`),默认拒绝写入疑似密钥。
69
+ - 清空记忆需要两步确认,且接口要求显式 `confirm: "delete"`。
86
70
 
87
- | 动作 | 做什么 | 安全边界 |
88
- | --- | --- | --- |
89
- | **卸载向量服务** | 删掉插件下载的 llama.cpp 运行时 + 模型 + 日志(约 480 MB) | 只删 `retrieval.vector.autoInstall.dir`(默认 storeDir 上一级)里的东西;**绝不碰记忆数据目录**;若 `spawn.exe` 指向该根目录之外(也就是你自己装的 llama.cpp),直接拒绝并说明原因 |
90
- | **清空记忆数据** | 删除所有作用域的全部记录(走 store,JSONL 与 `.vec` 边车保持一致,不会删出半个库) | 两步确认,且接口要求显式 `confirm: "delete"`,缺了不执行 |
71
+ ## 维护与卸载
91
72
 
92
- **卸载插件本身**:在 DSH 的「插件 / 插件市场」里移除本包和 `@restregular/dsh-memory-panel`。
73
+ 面板「维护」区(两步确认):**卸载向量服务**(删运行时 + 模型 + 日志,绝不碰记忆数据)、**清空记忆数据**(走 store,JSONL 与 `.vec` 边车保持一致)。
93
74
 
94
- > ⚠️ DSH 卸载插件只是在 profile 里 `pnpm remove` 并去掉 bundles 条目:它**不会**给插件任何提问机会,也**不会**自动删除向量服务文件或记忆数据。所以"要不要留向量服务""要不要留记忆数据"这两件事要在卸载**之前**到面板「维护」区处理——插件卸载后那个面板也就没了。
95
- >
96
- > 手动清理路径:向量服务在 `retrieval.vector.autoInstall.dir`(默认 `~/.dsh/memory-vector`;显式配了 `storeDir` 时是它的上一级目录),记忆数据在 `storeDir`。
75
+ DSH 卸载插件只是 `pnpm remove` + 去掉 bundles 条目,不会自动删除向量服务文件或记忆数据 —— 要清就在卸载前到面板处理。
97
76
 
98
77
  ## 说明
99
78
 
100
- - 存储为每作用域一个 JSONL + `.vec` 向量边车(含模型/维度身份头,不匹配自动重建)。
101
- - 记忆分 `global` 与 `project:<cwd>` 两类作用域。
102
- - 只在插件自己的生命周期内工作:任何异常都被吞掉并记日志,绝不让 DSH 启动失败。
79
+ - 存储:每作用域一个 JSONL + `.vec` 向量边车(含模型/维度身份头,不匹配自动重建)。
80
+ - 作用域:`global` 与 `project:<cwd>`。
81
+ - 任何异常都被吞掉并记日志,绝不让 DSH 启动失败。
103
82
  - License: MIT
package/cordis.patch.yml CHANGED
@@ -1,10 +1,8 @@
1
- # @restregular/dsh-memory bundle patch: local memory provider + model-facing tools + recall injection.
2
- # 三个 entry 共用本包,但本包不声明 dsh.client —— 声明了客户端 bundle 的包只允许一个活跃
3
- # entry(dsh-client-modules: "resolves from multiple active Loader sources")。
1
+ # @restregular/dsh-memory bundle patch: 单包单入口 —— provider + 模型工具 + 召回注入 + 面板(服务端与客户端同包)。
2
+ #
3
+ # 只有一行,而且必须是包名:宿主的 client-modules 只为「能解析到包名的活 entry」
4
+ # 提供 client bundle(见 dsh-client-modules reconcilePackage)。纯 insert、不带
5
+ # config,是为了让这一行可被宿主热挂载(带 config 只能重启生效)。
4
6
  - insert:
5
- - id: dsh-memory-local
7
+ - id: dsh-memory
6
8
  name: '@restregular/dsh-memory'
7
- - id: dsh-tool-memory
8
- name: '@restregular/dsh-memory/tools'
9
- - id: dsh-memory-inject
10
- name: '@restregular/dsh-memory/inject'
package/icon.svg ADDED
@@ -0,0 +1 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M12 8V4H8"/><rect x="4" y="8" width="16" height="12" rx="2"/><path d="M2 14h2"/><path d="M20 14h2"/><path d="M15 13v2"/><path d="M9 13v2"/></svg>