@restregular/dsh-memory 0.10.1 → 0.11.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/CHANGELOG.md +137 -0
- package/README.md +396 -483
- package/icon.svg +1 -1
- package/lib/client.js +8 -8
- package/lib/inject/digest.js +1 -1
- package/lib/inject/inject.js +1 -1
- package/lib/inject/policy.js +1 -1
- package/lib/inject/rules.js +2 -2
- package/locale/en.json +2 -2
- package/locale/zh.json +2 -2
- package/package.json +3 -2
package/README.md
CHANGED
|
@@ -1,483 +1,396 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
](https://www.npmjs.com/package/@restregular/dsh-memory)
|
|
12
|
+
[](https://www.npmjs.com/package/@restregular/dsh-memory)
|
|
13
|
+
[](https://github.com/RestRegular/dsh-memory/blob/main/LICENSE)
|
|
14
|
+
[](https://nodejs.org/)
|
|
15
|
+
|
|
16
|
+
[npm 包](https://www.npmjs.com/package/@restregular/dsh-memory) · [问题反馈](https://github.com/RestRegular/dsh-memory/issues) · [更新日志](https://github.com/RestRegular/dsh-memory/blob/main/CHANGELOG.md)
|
|
17
|
+
|
|
18
|
+
> **它解决的不是「存一段文本」,而是「让模型在该记的时候记住、该用的时候用上」。**
|
|
19
|
+
> 记忆默认只落在本机;没有向量服务也能工作——检索自动退化为词法,一个网络请求都不发。
|
|
20
|
+
|
|
21
|
+

|
|
22
|
+
|
|
23
|
+
## 它解决什么
|
|
24
|
+
|
|
25
|
+
| 常遇到的问题 | 记忆系统怎么做 |
|
|
26
|
+
| --- | --- |
|
|
27
|
+
| 新会话从零开始,换个窗口就问不出上次的结论 | 结论落成记忆;新会话第一步注入摘要,之后每轮按问题召回 |
|
|
28
|
+
| 同一个坑反复踩,上次查到的命令又要再查一遍 | 发布 / 部署 / 工具失败等行为会触发定向召回;查到的做法直接复用 |
|
|
29
|
+
| 写了规则没人执行,改过的规则旧会话不知道 | `kind: rule` 进系统提示常驻段;新增或编辑会补一条提醒 |
|
|
30
|
+
| 云端记忆不可控,敏感内容不敢写 | 全部本地 JSONL;写入前过凭据扫描;默认不发任何网络请求 |
|
|
31
|
+
|
|
32
|
+
它也不是「把聊天记录整段塞给模型」:每条记忆是一句自洽的话,按作用域、类型和重要度管理;
|
|
33
|
+
召回有 token 预算与去重,旧结论可以用 `supersedes` 标注修正,而不是悄悄覆盖。
|
|
34
|
+
|
|
35
|
+
## 功能
|
|
36
|
+
|
|
37
|
+
| 能力 | 说明 |
|
|
38
|
+
| --- | --- |
|
|
39
|
+
| **五个工具** | `memory_save` / `memory_search` / `memory_list` / `memory_get` / `memory_forget`。摘要每行带 8 位 id,`memory_get` 直接取全文 |
|
|
40
|
+
| **四种作用域** | 会话 / 项目 / `global` / 自定义名。默认写进当前会话,读默认合并会话 + 项目 + global;项目作用域可起别名 |
|
|
41
|
+
| **双通道检索** | 词法(IDF + 中文 bigram)**+** 向量(本机 llama-server 的 OpenAI 兼容 `/v1/embeddings`)。向量缺席自动降级,不报错、不阻塞 |
|
|
42
|
+
| **自动召回** | 每轮按用户问题召回;新会话第一步注入项目 / global 摘要;发布、部署、工具失败等行为按标签触发定向召回 |
|
|
43
|
+
| **印象形态** | 每轮只给每条记忆的短摘要;模型判断相关但需要细节时再 `memory_get` 取全文,省 token 也不丢信息 |
|
|
44
|
+
| **硬性规则** | `kind: rule` 进系统提示常驻段;旧会话会收到新增 / 编辑提醒;超预算有明确警告,不静默丢弃 |
|
|
45
|
+
| **可视化管理** | 记录浏览 / 搜索 / 新建 / 编辑 / 删除;记忆树展示作用域、类型与修正链;设置改完即存;导入导出 |
|
|
46
|
+
| **一键向量后端** | 面板里下载 llama.cpp 运行时与内置模型,按 CPU / 内存 / 显卡推荐;换模型自动重建向量 |
|
|
47
|
+
| **跨进程安全** | 每个作用域一把写锁,锁内重新读盘再合并;多个 DSH 实例或 MCP server 共用一个 store 不丢数据 |
|
|
48
|
+
|
|
49
|
+
## 界面
|
|
50
|
+
|
|
51
|
+
### 记忆树
|
|
52
|
+
|
|
53
|
+
按 **作用域 → 类型 → 记录** 三层展开,根节点显示总数。`supersedes` 是关系而不是层级,
|
|
54
|
+
所以不改树结构:金色虚线从修正版弯到旧版,悬停或选中任意一端,整条修正链一起点亮。
|
|
55
|
+
|
|
56
|
+

|
|
57
|
+
|
|
58
|
+
### 设置
|
|
59
|
+
|
|
60
|
+
召回、摘要、印象、策略、规则、自动召回逐项开关;每个开关都有可见 label、说明和当前状态。
|
|
61
|
+
修改立即写入 `settings.json`,不需要点保存。
|
|
62
|
+
|
|
63
|
+

|
|
64
|
+
|
|
65
|
+
### 向量服务
|
|
66
|
+
|
|
67
|
+
在本机托管 `llama-server`,下载运行时与模型,选错维度这种事由内置清单保证不发生;
|
|
68
|
+
按硬件推荐,也支持自定义 GGUF。
|
|
69
|
+
|
|
70
|
+

|
|
71
|
+
|
|
72
|
+
## 安装
|
|
73
|
+
|
|
74
|
+
```bash
|
|
75
|
+
pnpm add @restregular/dsh-memory
|
|
76
|
+
# 或
|
|
77
|
+
npm i @restregular/dsh-memory
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
装进任意 DSH profile(桌面端 `~/.dsh/profiles/desktop`,Web 端 `~/.dsh/profiles/web`)。
|
|
81
|
+
包自带 `cordis.patch.yml`,注册**唯一一条** entry:
|
|
82
|
+
|
|
83
|
+
```yaml
|
|
84
|
+
- insert:
|
|
85
|
+
- id: dsh-memory
|
|
86
|
+
name: '@restregular/dsh-memory'
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
**不写任何配置就能用**:检索退化为词法,一个网络请求都不发。需要语义检索时,
|
|
90
|
+
在面板「服务 → 向量服务」里一键装本机后端即可。
|
|
91
|
+
|
|
92
|
+
> 宿主只允许**一个包名、一个解析源**,所以本插件是「一个包 + 一条 entry + 面板与服务端同包」。
|
|
93
|
+
> 拆成两个包会触发 `resolves from multiple active Loader sources`,客户端图组合失败,
|
|
94
|
+
> 桌面端直接起不来。这段设计约束写在 `<details>` 里,不影响使用。
|
|
95
|
+
|
|
96
|
+
<details>
|
|
97
|
+
<summary>为什么是一个包(给想改结构的人)</summary>
|
|
98
|
+
|
|
99
|
+
宿主的 `dsh-client-modules` 只在「某条**活的** Loader entry 能解析到包名」时才为该包提供
|
|
100
|
+
client bundle,并且 `reconcilePackage` 要求一个包名只有一个解析源。因此稳定形态只有一种:
|
|
101
|
+
**一个包名、一条 entry、两侧都在**。入口 `lib/index.js` 组合四个半边,每个半边各自
|
|
102
|
+
try/catch——任何一半失败都只记一行日志,绝不让 DSH 启动失败。
|
|
103
|
+
|
|
104
|
+
| 半边 | 作用 |
|
|
105
|
+
| --- | --- |
|
|
106
|
+
| `lib/provider` | 提供 `memory` 服务:JSONL 存储、双通道检索、向量回填、向量后端生命周期与一键安装 |
|
|
107
|
+
| `lib/tools` | 注册五个模型工具 |
|
|
108
|
+
| `lib/inject` | `agent/pre-step` 召回、摘要、策略、规则与行为触发 |
|
|
109
|
+
| `lib/panel` | `/memory/api` 管理接口(含同源 / 登录围栏) |
|
|
110
|
+
| `lib/client.js` | 设置页「记忆系统」区块与左侧栏入口(注册 id == 包名) |
|
|
111
|
+
|
|
112
|
+
</details>
|
|
113
|
+
|
|
114
|
+
## 快速开始
|
|
115
|
+
|
|
116
|
+
### 1. 打开面板
|
|
117
|
+
|
|
118
|
+
设置页 →「记忆系统」;也可以在「设置 → 侧栏入口」打开左侧栏的「记忆系统」按钮。
|
|
119
|
+
面板分四个标签:**服务 / 记录 / 记忆树 / 设置**。
|
|
120
|
+
|
|
121
|
+
### 2. 存一条记忆
|
|
122
|
+
|
|
123
|
+
模型自己会调,也可以直接对 Agent 说「记住:……」。工具入参如下:
|
|
124
|
+
|
|
125
|
+
```jsonc
|
|
126
|
+
memory_save({
|
|
127
|
+
"content": "本仓库用 pnpm 11 安装依赖;PATH 上的 pnpm 10 会报 ERR_PNPM_UNEXPECTED_STORE。",
|
|
128
|
+
"kind": "procedure", // fact / decision / preference / procedure / note / rule
|
|
129
|
+
"tags": ["pnpm", "toolchain"],
|
|
130
|
+
"importance": 0.8, // 0~1
|
|
131
|
+
"path": "D:/repositories/dsh-memory" // 可选:写入 project:<该路径>
|
|
132
|
+
})
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
### 3. 检索、取全文、列出、忘记
|
|
136
|
+
|
|
137
|
+
```jsonc
|
|
138
|
+
memory_search({ "query": "pnpm 装依赖", "topK": 5 })
|
|
139
|
+
memory_get({ "ids": ["3f2a9c1d"] })
|
|
140
|
+
memory_list({ "limit": 20 })
|
|
141
|
+
memory_forget({ "id": "3f2a9c1d" }) // 按内容删:memory_forget({ query, scope })
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
`memory_search` 省略 `scope` 时合并**会话 + 项目 + global**(按来源标注、按 id 去重);
|
|
145
|
+
`scope: "all"` 查所有已发现的作用域,写入路径会明确拒绝 `all`。
|
|
146
|
+
|
|
147
|
+
### 4. 作用域怎么选
|
|
148
|
+
|
|
149
|
+
| 写法 | 含义 |
|
|
150
|
+
| --- | --- |
|
|
151
|
+
| 省略 / `session` | **当前会话**(子代理共享父会话;拿不到会话信息时回退当前项目) |
|
|
152
|
+
| `project` | 当前工作区(键是 `project:<cwd>`) |
|
|
153
|
+
| `path` + 可选 `scope` | 指定工作区目录;`scope` 成为这个项目作用域的显示名(别名) |
|
|
154
|
+
| `global` | 所有项目共享 |
|
|
155
|
+
| `handbook`、`项目笔记` … | 自定义作用域,首次 `memory_save` 自动创建 |
|
|
156
|
+
| `session:<id>` / `project:<path>` | 显式钉住某个会话 / 工作区 |
|
|
157
|
+
| `all` / `*` | **只在读取时可用**:跨所有已发现作用域 |
|
|
158
|
+
|
|
159
|
+
项目作用域的身份永远是 `project:<绝对路径>`,别名只影响显示与引用,不迁移数据。
|
|
160
|
+
同一路径重复用同一个名字是幂等的;换名字会覆盖原别名;另一个路径抢同一个名字会被拒绝
|
|
161
|
+
(`SCOPE_NAME_TAKEN`)。
|
|
162
|
+
|
|
163
|
+
### 5. 导入 / 导出
|
|
164
|
+
|
|
165
|
+
导出是纯文本 JSON:作用域、类型、内容、标签、重要度、时间戳,**不含向量**。
|
|
166
|
+
导入时逐条走保存路径,按当前模型重新嵌入,并按「作用域 + 内容」去重;一次最多 5000 条。
|
|
167
|
+
|
|
168
|
+
## 注入链路
|
|
169
|
+
|
|
170
|
+
| 层 | 触发 | 作用 |
|
|
171
|
+
| --- | --- | --- |
|
|
172
|
+
| `recall` | 每轮 `agent/pre-step` | 按本轮用户问题检索,按 topK / token 预算注入;默认只给每条 120 字摘要 + `memory_get` 指引 |
|
|
173
|
+
| `digest` | 会话第一步 | 注入项目 + global 概览:按重要度 × 新鲜度挑选;正文超预算时附可检索的标签索引 |
|
|
174
|
+
| `policy` | 系统提示常驻 | 什么时候查记忆、查到怎么复用、查不到时低风险推断 / 高风险先问用户 |
|
|
175
|
+
| `rules` | 系统提示常驻 | `kind: rule` 的硬性规则,限量与预算;`mandatory` / `pinned` 排在最前 |
|
|
176
|
+
| `turnEnd` | 每轮结束(默认关) | 下一轮开头提醒「有可复用结论先落盘」 |
|
|
177
|
+
| 行为召回 | 可见文本 / 任务 / 命令 / 工具失败 | 命中标签后,在**下一个** `agent/pre-step` 定向检索;工具失败优先用该工具自己的 description |
|
|
178
|
+
|
|
179
|
+
行为召回只检索 **global + 当前会话 + 当前工作区**,不把自定义作用域或 fork 父会话带进来。
|
|
180
|
+
匹配源包括可见 assistant 文本、todo、`command/run`、`goal/change`、`tool/call` 的
|
|
181
|
+
name / description / 参数,以及工具失败描述;**不读取隐藏思维链**。
|
|
182
|
+
|
|
183
|
+
### 规则会跟进旧会话
|
|
184
|
+
|
|
185
|
+
系统提示段每步都会重渲染,但那只是提示词文本变化,不会产生对话消息;常驻段还有 token 预算,
|
|
186
|
+
新规则可能被更重要的旧规则挤掉。`rules.delta`(默认开)会在每轮第一步比较「该会话上一轮开始时
|
|
187
|
+
的规则快照」与当前规则:新增、以及编辑过(同一 id 的行变了)的规则都补一条提醒,没变化不重复;
|
|
188
|
+
宿主重启用历史里的规则行做种子,不会整批重提醒。关掉它只停提醒,常驻段与检索照旧。
|
|
189
|
+
|
|
190
|
+
### 去重与修正
|
|
191
|
+
|
|
192
|
+
- 召回按 **sessionId + 记忆 id / 版本** 去重;只给过标签的记录,任务命中后可补正文;内容更新会重新评估。
|
|
193
|
+
- 被 `supersedes` 指向的旧记录不再进入摘要、规则段和自动召回;`memory_search` / `memory_get` 仍可查历史。
|
|
194
|
+
- compaction 后重置摘要与注入去重状态。
|
|
195
|
+
|
|
196
|
+
## 检索
|
|
197
|
+
|
|
198
|
+
- **词法通道**:IDF 加权 + 中文 bigram;记录标签也并入可检索文本,所以中文正文 + 英文标签也能被标签查询命中。
|
|
199
|
+
- **向量通道**:调用 `llama-server` 的 OpenAI 兼容 `/v1/embeddings`;可用面板一键安装,也可接自己的端点。
|
|
200
|
+
- **可选 LLM 重排**:`retrieval.llm.enabled`,默认关。
|
|
201
|
+
- **自动降级**:端点没配、进程没起、向量身份不匹配时,只走词法,不报错、不阻塞。
|
|
202
|
+
|
|
203
|
+
向量边车 `.vec` 的首行是身份头 `#<model>\t<dims>\t<pooling>`。任一对不上就整份丢弃并重新嵌入;
|
|
204
|
+
重建期间检索暂时只用词法。老边车只有 `model` + `dims` 两段,按兼容接受,下一次写向量时自动升级。
|
|
205
|
+
**换模型 = 向量作废重建**,面板会在切换前告诉你涉及多少条记忆。
|
|
206
|
+
|
|
207
|
+
`minScore` 默认 `0.5` 是按 BGE 的 CLS 噪声底定的;换模型后如果召回太少就调低、太杂就调高。
|
|
208
|
+
|
|
209
|
+
## 向量后端与硬件
|
|
210
|
+
|
|
211
|
+
- **内置 8 个模型**:BGE-M3(Q4_K_M / Q8_0)、Qwen3-Embedding 0.6B / 4B / 8B、Nomic Embed v1.5、BGE 中文 small / base / large。
|
|
212
|
+
- **维度与 pooling 自动配对**:每个模型自带 `dims` 与 `pooling`,选它就自动写入。维度写错会让向量通道静默失效,这是最容易踩的坑。
|
|
213
|
+
- **按本机推荐**:探测 CPU 核数 / 内存 / 磁盘剩余 / 显卡与显存;质量优先,能整块放进显存就用 GPU;CPU 上重罚 4B / 8B;显存 < 4GB 的核显不算可用显卡。
|
|
214
|
+
- **运行时风味**:`cpu` / `vulkan` / `cuda` / `metal` / `auto`。Vulkan 自包含;CUDA 会一并下载 cudart 伴随包;所选风味找不到时退回 CPU 并在面板说明。
|
|
215
|
+
- **自定义 GGUF**:填 URL + 维度即可装清单之外的模型;需要前缀的模型(Nomic 的 `search_query:` / `search_document:`)自动带上。
|
|
216
|
+
- **一次只保留一份**:已装运行时 + 模型时不能再装第二个;换模型先去「维护 → 卸载向量服务」,否则「现在跑的是哪个」说不清。
|
|
217
|
+
|
|
218
|
+
```yaml
|
|
219
|
+
retrieval:
|
|
220
|
+
vector:
|
|
221
|
+
preset: 'qwen3-embedding-0.6b' # 清单 id
|
|
222
|
+
variant: 'q8_0' # 量化档
|
|
223
|
+
flavor: 'auto' # auto / cpu / vulkan / cuda / metal
|
|
224
|
+
# customModel: { url: 'https://…/model.gguf', dims: 1024, pooling: 'auto' }
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
`spawn.enabled: true` 时,应用启动会后台拉起向量服务、退出时自动关闭;带 PID 文件的遗留实例会被接管,
|
|
228
|
+
没有 PID 文件的外部实例不接管。
|
|
229
|
+
|
|
230
|
+
## 配置
|
|
231
|
+
|
|
232
|
+
```yaml
|
|
233
|
+
- id: dsh-memory
|
|
234
|
+
name: '@restregular/dsh-memory'
|
|
235
|
+
config:
|
|
236
|
+
storeDir: '~/.dsh/memory-store' # 建议绝对路径;默认 .dsh-memory
|
|
237
|
+
scopes:
|
|
238
|
+
global: true
|
|
239
|
+
project: true
|
|
240
|
+
session: true
|
|
241
|
+
custom: { enabled: true, max: 200 } # 只统计自定义作用域
|
|
242
|
+
retrieval:
|
|
243
|
+
topK: 5
|
|
244
|
+
recallN: 30
|
|
245
|
+
vector:
|
|
246
|
+
enabled: true
|
|
247
|
+
endpoint: 'http://127.0.0.1:8078/v1/embeddings'
|
|
248
|
+
model: bge-m3
|
|
249
|
+
dims: 1024
|
|
250
|
+
timeoutMs: 300 # 交互检索预算,要紧
|
|
251
|
+
writeTimeoutMs: 10000 # 保存时嵌整条记录
|
|
252
|
+
backfillTimeoutMs: 30000
|
|
253
|
+
backfillMaxChars: 8000
|
|
254
|
+
spawn:
|
|
255
|
+
enabled: true
|
|
256
|
+
exe: '/path/to/llama-server.exe'
|
|
257
|
+
model: '/path/to/bge-m3-Q4_K_M.gguf'
|
|
258
|
+
cwd: '/path/to/llamacpp' # 目录里要有 llama-server-impl.dll
|
|
259
|
+
logFile: '/path/to/llama-server.log'
|
|
260
|
+
llm: { enabled: false }
|
|
261
|
+
limits: { maxRecordsPerScope: 2000, maxRecordChars: 4000 }
|
|
262
|
+
secrets: { enabled: true, mode: refuse } # refuse | redact
|
|
263
|
+
tools: { defaultScope: session } # session / project / global
|
|
264
|
+
inject:
|
|
265
|
+
enabled: true # 整个注入半边总开关
|
|
266
|
+
extraScopes: ['handbook'] # 可选:额外参与普通召回的 scope
|
|
267
|
+
recall: { enabled: true, topK: 5, tokenBudget: 500 }
|
|
268
|
+
impression: { enabled: true, chars: 120 }
|
|
269
|
+
digest: { enabled: true, topK: 8, tokenBudget: 800, hintBudget: 160, hintMaxItems: 6 }
|
|
270
|
+
policy: { enabled: true }
|
|
271
|
+
rules: { enabled: true, maxItems: 10, tokenBudget: 300, delta: true }
|
|
272
|
+
turnEnd: { enabled: false }
|
|
273
|
+
panel: { route: '/memory/api' }
|
|
274
|
+
```
|
|
275
|
+
|
|
276
|
+
面板改过的值写入 `<storeDir>/settings.json`,**优先级高于这里的配置**。
|
|
277
|
+
注入分层各自独立开关;`inject.enabled: false` 全关,但工具检索不受影响。
|
|
278
|
+
|
|
279
|
+
只有写了 `endpoint`、配了 `spawn`、或面板里装了本地后端,插件才会碰网络;否则一个请求都不发。
|
|
280
|
+
|
|
281
|
+
## 数据与文件布局
|
|
282
|
+
|
|
283
|
+
| 路径 | 内容 |
|
|
284
|
+
| --- | --- |
|
|
285
|
+
| `<storeDir>/global.jsonl` | global 作用域,一行一条 |
|
|
286
|
+
| `<storeDir>/projects/<sha1(scope)>.jsonl` | 其它作用域(会话 / 项目 / 自定义);文件名是 scope 键的 SHA-1,路径分隔符无法穿越 |
|
|
287
|
+
| `<storeDir>/projects/<sha1(scope)>.vec` | 向量边车;首行 `#<model>\t<dims>\t<pooling>`,后面每行 `id\t<base64 向量>` |
|
|
288
|
+
| `<storeDir>/settings.json` | 面板设置(覆盖配置文件里的默认值) |
|
|
289
|
+
| `<storeDir>/scopes.json` | 项目作用域别名(显示名 → `project:<路径>`) |
|
|
290
|
+
| `<storeDir>/*.lock` | 跨进程写锁;陈旧锁(持有者已死或 10s 未动)会被接管 |
|
|
291
|
+
| `<installRoot>/llamacpp/` | llama-server 运行时、依赖 dll、`llama-server.log` |
|
|
292
|
+
| `<installRoot>/models/` | 下载的 GGUF 模型 |
|
|
293
|
+
| `<installRoot>/selected-model.json` | 面板里选过哪一档 |
|
|
294
|
+
|
|
295
|
+
`storeDir` 默认 `.dsh-memory`(相对启动目录),**建议显式配一个绝对路径**。文件首次写入才创建;
|
|
296
|
+
作用域被删空后,它的 `.jsonl` 与 `.vec` 会在下一次落盘时一起移除(`global.jsonl` 例外:只清内容、留文件)。
|
|
297
|
+
|
|
298
|
+
scope 键有三种形态:`global`、`project:<cwd>`、`session:<会话 id>`,其余是自定义名
|
|
299
|
+
(小写折叠、内部空白折成一个空格、最长 64 字符,禁止 `:`、路径分隔符、控制字符、`..`
|
|
300
|
+
与保留名 `global/project/session/all`)。**没有任何数据迁移**:旧的 `project:<cwd>` 文件继续原样读写。
|
|
301
|
+
|
|
302
|
+
`installRoot` 默认 `~/.dsh/memory-vector`;显式配了 `storeDir` 时取它的父目录。
|
|
303
|
+
|
|
304
|
+
### 多进程共用
|
|
305
|
+
|
|
306
|
+
写入按 scope 走锁文件,每次「锁内重新读盘 + 合并本次增量」,不再用内存快照整份覆盖磁盘;
|
|
307
|
+
读路径每秒 stat 一次,别的进程刚写的记录不用重启就能看到。实测 4 个进程 × 20 条并发写同一个 scope 零丢失。
|
|
308
|
+
已知取舍:同内容去重仍是进程内判断,两个进程同时写**完全相同**的内容理论上会落两条。
|
|
309
|
+
|
|
310
|
+
## 安全
|
|
311
|
+
|
|
312
|
+
- `/memory/api` 的每条路由都先过 `refuseRequest`:宿主 `connection.requestRejection` 可用时以它为准
|
|
313
|
+
(Host / Origin 围栏 + 浏览器登录),围栏抛错一律 403(失败关闭);旧宿主没有该服务时退化为
|
|
314
|
+
「只认 loopback 权威 + 同源」。原因是注册在裸 `webServer` 上的路由不在宿主 `/api` 围栏之后,
|
|
315
|
+
而这里的接口能读、改、删、清空全部记忆。
|
|
316
|
+
- 记忆内容写入前过凭据扫描(`secrets.mode: refuse | redact`),默认拒绝。
|
|
317
|
+
- 清空记忆是两步确认 + 接口要求显式 `confirm: "delete"`。
|
|
318
|
+
- 数据默认只在本机:JSONL 不加密,向量端点默认 loopback;请自行保护 store 目录,导出文件也是明文。
|
|
319
|
+
|
|
320
|
+
## 卸载 / 迁移
|
|
321
|
+
|
|
322
|
+
```bash
|
|
323
|
+
pnpm remove @restregular/dsh-memory # 再从 profile 的 patch 里删掉那条 entry
|
|
324
|
+
```
|
|
325
|
+
|
|
326
|
+
卸载插件**不会**移除已配置的向量服务与记忆文件——它们不在 `node_modules` 里,而是在
|
|
327
|
+
`<storeDir>` 与 `<installRoot>`。要清掉,先打开面板「服务 → 维护」:
|
|
328
|
+
|
|
329
|
+
- **卸载向量服务**:删运行时与模型(两步确认,显示释放空间);记忆数据保留。
|
|
330
|
+
- **清空记忆数据**:删全部 JSONL 与向量边车(两步确认,不可恢复)。
|
|
331
|
+
|
|
332
|
+
插件被卸掉后面板就打不开了,所以这件事只能在卸载**之前**做。迁移时直接复制这两个目录即可;
|
|
333
|
+
只想带走记忆内容,用「设置 → 数据 → 导出」。
|
|
334
|
+
|
|
335
|
+
## 开发
|
|
336
|
+
|
|
337
|
+
```bash
|
|
338
|
+
npm test # node --experimental-strip-types --test source/*/test/*.test.ts
|
|
339
|
+
npm run build # source/ → packages/dsh-memory(含产物契约检查)
|
|
340
|
+
npm run verify # 构建到 .verify/,不落 packages/
|
|
341
|
+
```
|
|
342
|
+
|
|
343
|
+
构建用 Node 内置类型剥离,相对 `.ts` 说明符改写为 `.js`,每个产出文件 `node --check`。
|
|
344
|
+
产物契约检查覆盖会**静默失败**的几处:patch 恰好一行、`exports` 放行 `./client` 与 locale、
|
|
345
|
+
`__ModuleLoader__.load({ id })` 等于包名、四个半边的相对 import 都在、`icon.svg` 体积在宿主上限内。
|
|
346
|
+
|
|
347
|
+
> 发布:`node tools/publish-npm-packages.mjs --scope @restregular --version x.y.z`。
|
|
348
|
+
> npm token 不经过命令行,默认从 DevCred 读取,由 `devcred inject` 写进临时 `.npmrc`,发布后连目录删除。
|
|
349
|
+
> npm 的暂存发布会短暂出现版本不可下载、`latest` 未更新;先轮询确认,不要重复发布或 bump 版本。
|
|
350
|
+
|
|
351
|
+
## 常见问题
|
|
352
|
+
|
|
353
|
+
**向量服务起不来**
|
|
354
|
+
看 `<installRoot>/llamacpp/llama-server.log`。常见原因:端口被占、`cwd` 里缺 `llama-server-impl.dll`、
|
|
355
|
+
模型与运行时风味不匹配(比如 GPU 风味但没驱动)。
|
|
356
|
+
|
|
357
|
+
**检索很差 / 全是词法命中**
|
|
358
|
+
先看面板「当前模型」那行的维度是否与模型一致,再看 `.vec` 身份头。维度或 pooling 写错不会报错,
|
|
359
|
+
只会让向量通道悄悄失效。`minScore` 可能需要按模型微调。
|
|
360
|
+
|
|
361
|
+
**想换模型**
|
|
362
|
+
先「维护 → 卸载向量服务」再装;换完现有记忆会重新嵌入。
|
|
363
|
+
|
|
364
|
+
**面板里看不到「记忆系统」**
|
|
365
|
+
包名与 Loader entry 必须一一对应;确认 profile 的 patch 里只有一条 `@restregular/dsh-memory`,
|
|
366
|
+
以及依赖真的装上了。
|
|
367
|
+
|
|
368
|
+
**插件列表里还是包名,没有「记忆系统」**
|
|
369
|
+
先确认版本 ≥ 0.11.0 且包里有 `locale/` 目录;然后**重启一次 DSH 桌面端**。宿主的 Node 进程会缓存
|
|
370
|
+
`package.json` 的 `exports` 映射,原地更新不会让这份缓存失效;重启后恢复,之后的版本更新不再需要。
|
|
371
|
+
|
|
372
|
+
**记忆没有自动召回**
|
|
373
|
+
确认 `inject.recall` / `autoRecall` 已开、当前作用域在召回范围内(标签触发的自动召回只含 global + 当前会话 +
|
|
374
|
+
当前工作区,普通每轮召回按 `inject.extraScopes` 配置),并检查标签是否真的命中。用 `GET /memory/api/audit?session=<id>` 可以看到触发原因、
|
|
375
|
+
候选、去重与各通道预算。
|
|
376
|
+
|
|
377
|
+
**数据怎么备份**
|
|
378
|
+
复制整个 `<storeDir>`;或用面板导出 JSON。导入会按当前模型重新嵌入,不携带旧向量。
|
|
379
|
+
|
|
380
|
+
## 更新日志
|
|
381
|
+
|
|
382
|
+
- **0.11.0** —— 插件更名为「记忆系统」,重写 README 并更新截图;无 API / 配置 / 数据格式变更。
|
|
383
|
+
- **0.10.1** —— 深色模式开关跟随宿主 token,修复白点融进白轨道。
|
|
384
|
+
- **0.10.0** —— 多进程安全写入、向量身份加入 pooling、读路径能看到其它进程的新写入。
|
|
385
|
+
|
|
386
|
+
完整记录见 [CHANGELOG.md](https://github.com/RestRegular/dsh-memory/blob/main/CHANGELOG.md)。
|
|
387
|
+
|
|
388
|
+
## License
|
|
389
|
+
|
|
390
|
+
[MIT](https://github.com/RestRegular/dsh-memory/blob/main/LICENSE)
|
|
391
|
+
|
|
392
|
+
---
|
|
393
|
+
|
|
394
|
+
English: **Memory System** — local-first long-term memory for DeepSeek Harness. One npm package,
|
|
395
|
+
one loader entry: JSONL storage, local vector recall through llama-server, five model tools,
|
|
396
|
+
automatic recall, hard rules, and a visual management panel. Memory stays on your machine.
|