dsh-cooper-memory 0.0.0-stage → 0.1.1

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 ADDED
@@ -0,0 +1,24 @@
1
+ # Changelog
2
+
3
+ ## 0.1.1 — 2026-11-19
4
+
5
+ 安全修复(**0.1.0 用户建议升级**):
6
+
7
+ - 移除 `lib/llm.mjs` 里写死的 `baseURL` / `model` / `apiKeyEnv` 兜底值。0.1.0 在 profile 没配 `baseURL` 时,会把使用者的 API key 发到作者私有的网关;现在缺任何一项直接报错,`memory_probe_llm` 返回 `stage: "config"`。
8
+ - 删除注释里泄露网关地址、模型 id、凭据 ref 的调试笔记。
9
+ - `~/.dsh/.credentials.yaml` 只解析点名的那个 ref,不再把整个文件里「`sk-` 开头 / 长度 > 20」的值全部读进内存。
10
+ - provider 由 `agent-default-model.provider` 决定,找不到时不再回落到文件里第一个 `baseURL`。
11
+
12
+ 修复:
13
+
14
+ - `web.mjs` 默认端口 7890 → 17890,与 README / DETAIL 一致。
15
+ - 蒸馏按钮改用 `runDistill(this)`,不再依赖 `window.event`。
16
+ - MCP `serverInfo.version` 从 `package.json` 读取,不再写死 0.1.0。
17
+
18
+ 测试:
19
+
20
+ - 新增 `test/`(14 个用例):配置解析、凭据最小化、只向配置的 base 发请求、MCP stdio 全链路、发布包泄露扫描。`npm test` 可跑。
21
+
22
+ ## 0.1.0 — 2026-11-19
23
+
24
+ 首个公开版本。
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 dsh-cooper-memory contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,108 @@
1
- # Temporary Holding Version
1
+ # dsh-cooper-memory
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ 给 DeepSeek Harness 用的**本地记忆 + 文件夹知识库**。数据存在一个 SQLite 文件里,不依赖 Docker、不依赖向量服务、不出网(LLM 蒸馏走你已配置的模型通道)。
4
+
5
+ ## 解决什么
6
+
7
+ | 需求 | 实现 |
8
+ |---|---|
9
+ | 跨会话长期记忆,保存确认过的个人信息、偏好与事实 | 记忆表 + `pending → active` 状态机,未确认不注入 |
10
+ | 文件夹上传保留原始目录结构 | 递归入库,`rel_path` 保留层级,目录树由路径派生 |
11
+ | 检索分块可编辑、比对、回滚 | 只追加的版本表 + 行级 diff + 回滚生成新版本 |
12
+
13
+ ## 安装
14
+
15
+ 在 DSH 的 **Plugins** 页安装 `dsh-cooper-memory` 并启用;也可以用插件管理器从本地目录安装。
16
+
17
+ 安装后 bundle 会插入一个 MCP 客户端行,DSH 里出现 `mcp__memory__*` 工具(共 17 个)。
18
+
19
+ > 需要 Node.js ≥ 22.5(用到内置的 `node:sqlite`),且 `node` 需在 PATH 中。
20
+
21
+ ## 工具(17 个)
22
+
23
+ **记忆**
24
+
25
+ - `memory_recall` — 召回(常驻资料/偏好 + 按问匹配事实)
26
+ - `memory_remember` — 写入(默认 pending)
27
+ - `memory_confirm` / `memory_reject` — 确认 / 拒绝(拒绝留抑制记录)
28
+ - `memory_list` / `memory_edit`
29
+ - `memory_extract` — 规则提取(扫会话日志)
30
+ - `memory_distill` — LLM 蒸馏(分批,比规则准)
31
+ - `memory_probe_llm` — 探测 LLM 是否可用
32
+
33
+ **知识库**
34
+
35
+ - `kb_ingest` / `kb_tree` / `kb_search`
36
+ - `kb_get` / `kb_edit` / `kb_history` / `kb_diff` / `kb_rollback`
37
+
38
+ ## 命令行
39
+
40
+ ```bash
41
+ dsh-cooper-memory search "关键词"
42
+ dsh-cooper-memory extract --limit 20 # 规则提取
43
+ dsh-cooper-memory distill --turns 60 # LLM 蒸馏
44
+ dsh-cooper-memory memories --status pending
45
+ dsh-cooper-memory ingest D:/docs --size 512
46
+ dsh-cooper-memory tree
47
+ ```
48
+
49
+ ## 浏览器界面
50
+
51
+ ```bash
52
+ dsh-cooper-memory-web # http://127.0.0.1:17890
53
+ ```
54
+
55
+ 左边目录树、中间检索、右边分块编辑 + 版本历史 + 比对 + 回滚,另有「待确认记忆」队列。
56
+
57
+ ## 数据位置
58
+
59
+ 默认 `~/.dsh-memory/mem.db`,可用环境变量覆盖:
60
+
61
+ | 变量 | 作用 | 默认 |
62
+ |---|---|---|
63
+ | `MEM_ROOT` | 数据目录 | `~/.dsh-memory` |
64
+ | `MEM_DB` | 数据库文件完整路径 | `$MEM_ROOT/mem.db` |
65
+ | `MEM_WEB_PORT` | 界面端口 | `17890` |
66
+
67
+ ## 配置 LLM(可选)
68
+
69
+ 不配也能用:规则提取、知识库、检索、版本管理全部离线可用。配了才启用 `memory_distill` / `memory_probe_llm`。
70
+
71
+ **包里没有内置的默认地址、默认模型或默认凭据名**,三项都必须来自你自己的机器:
72
+
73
+ | 项 | 来源(按优先级) |
74
+ |---|---|
75
+ | `baseURL` | `LLM_BASE_URL` / `DEEPSEEK_BASE_URL` → profile `cordis.patch.yml` 里 `agent-default-model.provider` 指向的那个 provider 的 `baseURL` |
76
+ | `model` | `LLM_MODEL` → profile `cordis.patch.yml` 里 `agent-default-model.model` |
77
+ | `key` | `LLM_KEY_ENV` 指定的环境变量或 `~/.dsh/.credentials.yaml` 里的同名 ref → 该 provider 的 `apiKeyEnv` → `DEEPSEEK_API_KEY` |
78
+
79
+ 缺任何一项,`memory_probe_llm` 会返回 `stage: "config"` 并列出缺什么,`memory_distill` 会直接报错——不会退回到某个写死的地址去发请求。凭据文件只解析上面点名的那个 ref,其余条目不会进内存。
80
+
81
+ ## 导入工作流
82
+
83
+ 在灵枢(dsh-memory)里积累的记忆可以一次性导入:
84
+
85
+ ```bash
86
+ dsh-cooper-memory import-lingshu --dry # 先看统计
87
+ dsh-cooper-memory import-lingshu # 真正写入
88
+ ```
89
+
90
+ 只导入 `knowledge` 与 `contextual` 层;`structural`(审核裁决记录)会跳过。
91
+
92
+ ## 隐私边界
93
+
94
+ - 除了 `memory_distill` / `memory_probe_llm`,其余功能完全离线,进程不发起任何外部请求
95
+ - 蒸馏会把最近的用户发言原样发到你配置的 `baseURL`,**不做密钥打码**;别在会进记忆的对话里贴 key
96
+ - 出口只有 `baseURL + /chat/completions` 一个,没有遥测、没有回传
97
+ - 记忆与知识库以明文存在 `~/.dsh-memory/mem.db`,没有加密;SQLite 里不保存 API key
98
+
99
+ ## 已知限制
100
+
101
+ - **不做向量检索**:只有 FTS5 trigram + 中文二元组,靠措辞重合召回
102
+ - **不解析 PDF/DOCX**:只吃 md / txt / csv / json / yaml
103
+ - **提取精度约 60~85%**:所以结果一律进 pending 队列,人工确认后才生效
104
+ - **单机单库**:没有多租户、没有同步
105
+
106
+ ## 许可
107
+
108
+ MIT
package/cli.mjs ADDED
@@ -0,0 +1,177 @@
1
+ #!/usr/bin/env node
2
+ // cli.mjs —— 命令行入口(人用 / 脚本用),所有输出为 JSON 或纯文本
3
+ import { openDb } from './lib/db.mjs';
4
+ import {
5
+ ingestFolder, searchChunks, getChunk, editChunk, chunkHistory,
6
+ chunkVersionText, rollbackChunk, diffTexts, tree,
7
+ remember, confirmMemory, rejectMemory, editMemory, listMemories, recall,
8
+ } from './lib/core.mjs';
9
+ import { runAutoExtract, recentTurns, llmDistill } from './lib/extract.mjs';
10
+ import { probe as llmProbe } from './lib/llm.mjs';
11
+ import { importLingshu } from './lib/import-lingshu.mjs';
12
+
13
+ const argv = process.argv.slice(2);
14
+ const cmd = argv[0];
15
+ const rest = argv.slice(1);
16
+
17
+ function flag(name, def = null) {
18
+ const i = rest.indexOf('--' + name);
19
+ if (i < 0) return def;
20
+ return rest[i + 1];
21
+ }
22
+ const has = (name) => rest.includes('--' + name);
23
+ const positional = rest.filter((a, i) => !a.startsWith('--') && !(i > 0 && rest[i - 1].startsWith('--')));
24
+
25
+ function out(obj) {
26
+ process.stdout.write(JSON.stringify(obj, null, 2) + '\n');
27
+ }
28
+
29
+ const db = openDb();
30
+
31
+ try {
32
+ switch (cmd) {
33
+ case 'ingest': {
34
+ const dir = positional[0];
35
+ if (!dir) throw new Error('用法: cli.mjs ingest <目录> [--size 512] [--overlap 80] [--strategy auto]');
36
+ const stats = ingestFolder(db, dir, {
37
+ chunk_size: Number(flag('size', 512)),
38
+ chunk_overlap: Number(flag('overlap', 80)),
39
+ strategy: flag('strategy', 'auto'),
40
+ max_files: Number(flag('max', 5000)),
41
+ });
42
+ out(stats);
43
+ break;
44
+ }
45
+ case 'tree':
46
+ process.stdout.write(tree(db) + '\n');
47
+ break;
48
+ case 'search': {
49
+ const q = positional[0];
50
+ if (!q) throw new Error('用法: cli.mjs search <query> [--variants "a|b"] [--limit 8]');
51
+ const variants = (flag('variants', '') || '').split('|').map((s) => s.trim()).filter(Boolean);
52
+ const r = searchChunks(db, { query: q, variants, limit: Number(flag('limit', 8)) });
53
+ out({
54
+ usedQueries: r.usedQueries, fused: r.fused,
55
+ results: r.results.map((x) => ({
56
+ id: x.id, path: x.rel_path, ordinal: x.ordinal, score: Number(x.score.toFixed(4)),
57
+ heading: x.heading, text: x.text.slice(0, 160),
58
+ })),
59
+ });
60
+ break;
61
+ }
62
+ case 'get': {
63
+ const id = Number(positional[0]);
64
+ const c = getChunk(db, id);
65
+ if (!c) throw new Error('未找到');
66
+ out(c);
67
+ break;
68
+ }
69
+ case 'edit': {
70
+ const id = Number(positional[0]);
71
+ const text = positional[1];
72
+ if (!text) throw new Error('用法: cli.mjs edit <chunkId> <新文本> [--note "..."] [--base N]');
73
+ out(editChunk(db, id, text, {
74
+ note: flag('note', ''),
75
+ baseVersion: flag('base') ? Number(flag('base')) : null,
76
+ }));
77
+ break;
78
+ }
79
+ case 'history': {
80
+ out(chunkHistory(db, Number(positional[0])));
81
+ break;
82
+ }
83
+ case 'diff': {
84
+ const id = Number(positional[0]);
85
+ const a = Number(flag('from', 1));
86
+ const b = Number(flag('to'));
87
+ const va = chunkVersionText(db, id, a);
88
+ const vb = b ? chunkVersionText(db, id, b) : getChunk(db, id);
89
+ if (!va || !vb) throw new Error('版本不存在');
90
+ out({ chunkId: id, from: a, to: b, diff: diffTexts(va.text, vb.text) });
91
+ break;
92
+ }
93
+ case 'rollback': {
94
+ out(rollbackChunk(db, Number(positional[0]), Number(positional[1])));
95
+ break;
96
+ }
97
+ case 'remember': {
98
+ out(remember(db, {
99
+ kind: flag('kind', 'fact'),
100
+ text: positional[0] || flag('text', ''),
101
+ subject: flag('subject', ''),
102
+ status: flag('status', 'pending'),
103
+ confidence: Number(flag('conf', 0.6)),
104
+ source: flag('source', 'cli'),
105
+ tags: flag('tags', ''),
106
+ supersedes: flag('supersedes', null),
107
+ }));
108
+ break;
109
+ }
110
+ case 'extract': {
111
+ const r = runAutoExtract(db, {
112
+ sessionsDir: flag('sessions', undefined),
113
+ limit: Number(flag('limit', 30)),
114
+ dryRun: has('dry'),
115
+ maxFiles: Number(flag('maxfiles', 50)),
116
+ });
117
+ out(r);
118
+ break;
119
+ }
120
+ case 'probe-llm': out(await llmProbe()); break;
121
+ case 'import-lingshu': {
122
+ out(importLingshu(db, {
123
+ dryRun: has('dry'),
124
+ limit: Number(flag('limit', 5000)),
125
+ dir: flag('dir', undefined) || undefined,
126
+ }));
127
+ break;
128
+ }
129
+ case 'distill': {
130
+ const turns = recentTurns(flag('sessions', undefined), Number(flag('turns', 60)));
131
+ const r = await llmDistill(db, {
132
+ turns,
133
+ limit: Number(flag('limit', 30)),
134
+ dryRun: has('dry'),
135
+ });
136
+ out(r);
137
+ break;
138
+ }
139
+ case 'confirm': out(confirmMemory(db, Number(positional[0]))); break;
140
+ case 'reject': out(rejectMemory(db, Number(positional[0]), { note: flag('note', '') })); break;
141
+ case 'mem-edit': out(editMemory(db, Number(positional[0]), positional[1], { note: flag('note', '') })); break;
142
+ case 'memories': out(listMemories(db, { status: flag('status'), kind: flag('kind'), limit: Number(flag('limit', 100)) })); break;
143
+ case 'recall': {
144
+ const r = recall(db, positional[0] || '', { budgetChars: Number(flag('budget', 1200)) });
145
+ out(r);
146
+ break;
147
+ }
148
+ case 'stats': {
149
+ const docs = db.prepare('SELECT COUNT(*) n FROM documents').get().n;
150
+ const chunks = db.prepare('SELECT COUNT(*) n FROM chunks').get().n;
151
+ const vers = db.prepare('SELECT COUNT(*) n FROM chunk_versions').get().n;
152
+ const mems = db.prepare('SELECT status, COUNT(*) n FROM memories GROUP BY status').all();
153
+ const tiers = db.prepare('SELECT tier, COUNT(*) n FROM chunks GROUP BY tier').all();
154
+ out({ docs, chunks, versions: vers, memories: mems, tiers });
155
+ break;
156
+ }
157
+ default:
158
+ process.stdout.write(`用法:
159
+ ingest <目录> 入库并分块
160
+ tree 目录树
161
+ search <query> 检索
162
+ get <chunkId> 读分块
163
+ edit <chunkId> <文本> 编辑分块(生成新版本)
164
+ history <chunkId> 版本历史
165
+ diff <chunkId> --from 1 --to 2 版本比对
166
+ rollback <chunkId> <版本> 回滚
167
+ remember --kind fact --text "..." 写记忆
168
+ confirm <id> / reject <id>
169
+ memories [--status pending]
170
+ recall <query>
171
+ stats
172
+ `);
173
+ }
174
+ } catch (e) {
175
+ process.stderr.write('ERROR: ' + (e.message || e) + '\n');
176
+ process.exit(1);
177
+ }
@@ -0,0 +1,12 @@
1
+ - insert:
2
+ - id: dsh-cooper-memory
3
+ name: '@deepseek-ai/dsh-mcp-client'
4
+ config:
5
+ serverName: memory
6
+ transport: stdio
7
+ command: node
8
+ args:
9
+ - 'node_modules/dsh-cooper-memory/mcp.mjs'
10
+ env:
11
+ NODE_NO_WARNINGS: '1'
12
+ failOnStartupError: true
package/docs/DETAIL.md ADDED
@@ -0,0 +1,83 @@
1
+ # 本地记忆 / Local memory
2
+
3
+ ## 它做什么
4
+
5
+ DSH 本身没有跨会话记忆:每个新会话从零开始。这个插件在本地维护一个 SQLite 文件,把三件事落在同一处:
6
+
7
+ 1. **长期记忆** —— 用户的偏好、身份、环境事实、待办事项
8
+ 2. **文件夹知识库** —— 任意目录递归入库,保留原始层级
9
+ 3. **可编辑的检索分块** —— 每次修改留版本,可逐行比对、可回滚
10
+
11
+ 全部离线,不需要 Docker,不需要向量数据库。
12
+
13
+ ## 记忆的生命周期
14
+
15
+ ```
16
+ 写入(规则 / LLM 蒸馏 / 手动)
17
+ │
18
+ ▼
19
+ status = pending ← 不参与召回
20
+ │
21
+ 人工确认 ──► status = active ← 参与召回
22
+ └──► status = rejected ← 保留做抑制,不再重复提取
23
+ ```
24
+
25
+ 三条硬规则:
26
+
27
+ - **pending 不注入**:自动提取必然有噪声,未确认的内容不进上下文
28
+ - **拒绝留痕**:被拒的内容参与后续去重,不会反复冒出来
29
+ - **新说法不立刻顶掉旧说法**:只挂 `supersedes` 链接,确认时才替换,旧条目转为 `superseded` 但保留在链条里
30
+
31
+ ## 提取的两种方式
32
+
33
+ | 方式 | 依赖 | 适用 |
34
+ |---|---|---|
35
+ | 规则提取 `memory_extract` | 无 | 离线环境、LLM 不可用时 |
36
+ | LLM 蒸馏 `memory_distill` | 可用的模型通道 | 需要理解隐含表达时,准确率更高 |
37
+
38
+ 两者都会扫描 `~/.dsh/sessions` 下的会话日志(追加式 zstd 多帧,按魔数切帧解压),用文件水位线去重,不会重复扫同一份日志。
39
+
40
+ LLM 蒸馏按 15 条一批切分——整批塞进去时模型容易判定"全是噪声"而返回空数组。
41
+
42
+ ## 分块与检索
43
+
44
+ 三层分块,逐级回退:
45
+
46
+ 1. **标题分块** —— 按 Markdown 标题层级切,面包屑存入 `context_header`(只影响索引,不污染正文)
47
+ 2. **启发式** —— 编号小节、章节标记、换页符、全大写行
48
+ 3. **递归兜底** —— 按 `\n\n` → `\n` → `。` 递归切分,重叠取语义后缀而非定长切片
49
+
50
+ 每层产出都要过校验(无输出、超大文档只有一块、碎片过多、块过小、超预算),不合格降级;**兜底层永不返回空**。
51
+
52
+ 检索是两路召回后融合:
53
+
54
+ - FTS5 trigram(精确子串)
55
+ - 中文二元组 LIKE(短查询、近义措辞)
56
+
57
+ 按加权 RRF 融合,再做 MMR 去冗余(λ=0.7)。
58
+
59
+ ## 版本模型
60
+
61
+ ```
62
+ chunks.version → 当前生效版本
63
+ chunk_versions → 只追加,永不删除
64
+ ```
65
+
66
+ 编辑生成新版本,回滚也是生成新版本(把旧正文写成新版本号),历史完整保留。编辑时可带 `base_version` 做乐观锁,版本对不上就拒绝。
67
+
68
+ ## 配置
69
+
70
+ | 变量 | 默认 | 说明 |
71
+ |---|---|---|
72
+ | `MEM_ROOT` | `~/.dsh-memory` | 数据目录 |
73
+ | `MEM_DB` | `$MEM_ROOT/mem.db` | 数据库路径 |
74
+ | `MEM_WEB_PORT` | `17890` | 浏览器界面端口 |
75
+ | `LLM_KEY_ENV` | `DEEPSEEK_API_KEY` | 从哪个环境变量 / 凭据 ref 取 key |
76
+ | `LLM_MODEL` | 取 profile 配置 | 覆盖模型 |
77
+ | `DEEPSEEK_BASE_URL` | 取 profile 配置 | 覆盖推理网关地址 |
78
+
79
+ ## 边界
80
+
81
+ - 只做词法检索,没有 embedding;语义相近但用词不同的内容可能召回不到
82
+ - 只解析纯文本类文件(md / txt / csv / json / yaml),PDF 与 DOCX 需要先自行转换
83
+ - 自动提取是**辅助**,pending 队列才是质量闸门
package/icon.svg ADDED
@@ -0,0 +1,10 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64" role="img" aria-label="Local memory">
2
+ <rect x="4" y="4" width="56" height="56" rx="14" fill="#1b2433"/>
3
+ <g fill="none" stroke="#7fb2ff" stroke-width="3" stroke-linecap="round" stroke-linejoin="round">
4
+ <ellipse cx="32" cy="24" rx="14" ry="7"/>
5
+ <path d="M18 24v16c0 3.9 6.3 7 14 7s14-3.1 14-7V24"/>
6
+ <path d="M18 32c0 3.9 6.3 7 14 7s14-3.1 14-7"/>
7
+ </g>
8
+ <circle cx="45" cy="45" r="7" fill="#1b2433" stroke="#8ee6b0" stroke-width="3"/>
9
+ <path d="M42 45l2.4 2.4L48.5 43" fill="none" stroke="#8ee6b0" stroke-width="2.6" stroke-linecap="round" stroke-linejoin="round"/>
10
+ </svg>