@kenz1117/dsh-engram 0.13.10 → 0.13.12
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 +34 -0
- package/README.en.md +9 -6
- package/README.md +13 -10
- package/i18n/ru.txt +3 -0
- package/lib/client.js +1 -1
- package/lib/client.js.map +1 -1
- package/lib/engine/node_modules/onnxruntime-common/index.mjs +3 -0
- package/lib/engine/node_modules/onnxruntime-common/package.json +10 -0
- package/lib/engine/node_modules/onnxruntime-web/package.json +11 -0
- package/lib/engine/node_modules/onnxruntime-web/webgpu.mjs +3 -0
- package/lib/engine/ort-wasm-simd-threaded.jsep.mjs +108 -0
- package/lib/engine/ort-wasm-simd-threaded.jsep.wasm +0 -0
- package/lib/engine/ort.bundle.min.mjs +2954 -0
- package/lib/engine/transformers.web.js +32562 -0
- package/lib/index.js +463 -112
- package/lib/local.js +1459 -0
- package/package.json +12 -11
- package/scripts/backfill-embeddings.mjs +14 -16
- package/scripts/copy-engine.mjs +102 -0
- package/scripts/engine-smoke.mjs +250 -0
package/CHANGELOG.md
CHANGED
|
@@ -8,6 +8,40 @@
|
|
|
8
8
|
|
|
9
9
|
> **v0.x 阶段的版本约定**:`0.MINOR.PATCH` 里的 `MINOR` 是**功能批次**而不是稳定性刻度——0.7.x 整批是「记忆宫殿信息架构」,0.8.x 整批是「面板重构」,0.9.x 整批是「稳定性与可审计」,0.10.x 整批是「多语言与数据驱动」。同一批次内的 `PATCH` 位通常是修复与加固。
|
|
10
10
|
|
|
11
|
+
## [0.13.12] - 2026-11-16
|
|
12
|
+
|
|
13
|
+
### Added
|
|
14
|
+
|
|
15
|
+
- **共享 scope 说明落文档(#58)**:README 特性列表与架构段补「共享 scope(shared.db)」定位(手动挑出、准备借出给别人的记忆暂存区,只显式进出),工具表后补 scope 枚举释义;`package.json` description「dual-scope」改「three-scope」。
|
|
16
|
+
|
|
17
|
+
### Changed
|
|
18
|
+
|
|
19
|
+
- **面板与工具口径对齐三库(#58)**:面板 search-test(召回实验台)/ activity(日志)/ health(诊脉默认合并)的 all 从硬编码 ['user','project'] 扩为三库;health 合并时 shared 有内容才计入(空库计入会把没用 shared 的用户健康分无故拖低)。面板与工具文案「两库」表述改「三库」。
|
|
20
|
+
|
|
21
|
+
## [0.13.11] - 2026-11-15
|
|
22
|
+
|
|
23
|
+
### Fixed
|
|
24
|
+
|
|
25
|
+
- **治理页「闭馆此条」「改判为相关」不再必然失败(#56)**:`POST /api/engram/governance` 分支漏接 `adoptBodySelector`,面板写操作 body 里的 `project` 选择器被丢弃——凡选中具体工作区,治理写操作 100% 落到进程默认项目库,`resolveContradiction` 在错误的库里查不到目标 id,报「条目 xxx 不存在」。报告人 Nicanya 给出了完整根因链与行号定位。修复与其余写分支对齐:POST 分支补采纳 body 选择器。回归测试走真实 Loader 组合链路:选择器只放 body、不放 query,断言改判落在选中工作区库、user scope 对照组照常。
|
|
26
|
+
- **`engram_distill` 不再因输出上限整次失败(#55 缺陷一)**:取材从一次 30 条改为每批 10 条分批过辅助 LLM;单批输出超预算对半递归重试(与 reflect 的 #45 自愈同法),切到单片仍超限或解析失败只丢该批并计入新的 `failed` 计数(条目保持 active,下次蒸馏再取材),不再「一批失败 = 整次失败」。工具文本明说失败条数(zh/en/ru 齐备);`distill-request` 审计行每批一条。
|
|
27
|
+
- **0.88–0.92 模糊带免 LLM 兜底合并(#55 缺陷二)**:JEV 关闭/失败/低置信时模糊带不再永远 defer——同 kind + 余弦 ≥ 0.90 + 字符 bigram Jaccard ≥ 0.5 + 数字令牌一致 → 判为复述合并(强化既有条目);不满足则照旧 defer 落库建边。数字守卫专防「端口 8080→9090」这类字面像但内容异的修正被误并。两个调用方(`engram_save` / 自动摄取)改为始终携带 content 供兜底比对字面。
|
|
28
|
+
- **注入端近似重复折叠(#55 缺陷三)**:会话画像渲染前按存储向量做同 kind 余弦聚类(阈值 0.9),每簇只让 importance 最高的条目占注入槽位,簇头行尾标注「(另含 N 条相似条目)」,其余只从注入块移除、不删库。向量直接读库(新 store API `vectorsFor`,按稳定逻辑身份取),嵌入器不在注入关键路径上;无向量、跨 kind、混维(换过模型的存量库)条目一律保留不折叠。
|
|
29
|
+
|
|
30
|
+
### Changed
|
|
31
|
+
|
|
32
|
+
- **引擎出树(#50/#54 的根治):嵌入引擎从安装树整体移除,改用随包分发的纯 WASM 引擎**。此前本地语义检索依赖 `optionalDependencies` 里的 `@huggingface/transformers`(内部精确钉死 `onnxruntime-node` 1.30.0 原生件,解包约 300MB),桌面宿主的市场更新是「先删后装 + 限时」——弱网机器的 pnpm store 永远填不满这个百 MB 包,每次更新都被限时杀掉。现在:
|
|
33
|
+
- **安装树里没有任何引擎依赖**:`optionalDependencies` 清空(连带 onnxruntime-node/sharp 等原生件与「允许构建脚本」的诉求一起消失);发布包从 775KB 变为约 7.5MB(解包约 33MB,其中 28MB 是 ONNX Runtime 的 wasm 二进制),npm/pnpm 安装量级回到秒级,弱网更新不再有可被限时杀掉的大件。
|
|
34
|
+
- **技术路线**:transformers.js 的 **web 构建** + 预注入的 onnxruntime-web 纯 wasm 后端(`globalThis[Symbol.for('onnxruntime')]` 四步注入、wasm 二进制经 `wasmBinary` 本地注入不走红网络加载、模型缓存经自实现的 Web Cache API fs shim 落盘),全部经 spike 在 Node 下实跑验证后落进 `src/embedder/engine.ts` + `src/embedder/engine-cache.ts`。引擎文件由 `scripts/copy-engine.mjs` 从 devDependencies 拷进 `lib/engine/` 随包分发(`pnpm bundle` 与 `prepack` 都会执行,publish 不可能带不出引擎)。
|
|
35
|
+
- **性能代价(如实告知)**:WASM 单线程推理约 **90ms/条**(原生 onnxruntime-node 约 10-20ms/条);全量回填 3000 条记忆约 **7 分钟**。检索路径单条嵌入占比小,日常使用体感差异有限;批量回填建议挂后台跑。
|
|
36
|
+
- **存量向量完全有效**:模型、量化(q8)、池化(mean)与此前一致,向量逐位相同——**不需要 backfill**,升级后语义检索直接可用(模型文件缓存也沿用原目录)。
|
|
37
|
+
- **弱网行为变化**:引擎不再可能「装不上」(它就在包里);失败面只剩模型下载——首次使用需联网下载模型文件(q8 约 24MB,端点可配镜像),失败仍走既定的纯关键词降级链。引擎文件若真缺失(安装被安全软件截断等),报错从裸栈改为指明「引擎未随包,请重装插件」的人话(zh/en/ru 三语齐备)。
|
|
38
|
+
- **`lib/local.js` 新构建入口**:嵌入器装载器单独成包(`tsdown.config.ts` 的 companions 构建)——插件入口 `lib/index.js` 的导出面是宿主契约(name/apply/inject),嵌入器不能挂上去;`scripts/backfill-embeddings.mjs` 改经它装载引擎(原先直接 `import('@huggingface/transformers')` 的路径随出树一并移除)。
|
|
39
|
+
- **devDependencies 变化**:新增 `@huggingface/transformers@4.3.2` 与 `onnxruntime-web@1.31.0-dev.20260914-8d85527a0`(精确版本,后者与 transformers 4.3.2 内部钉死完全一致——工厂 mjs 与 wasm 二进制必须配套),`pnpm-lock.yaml` 已同步刷新。二者只在构建机存在,用户安装树无感。
|
|
40
|
+
|
|
41
|
+
### Added
|
|
42
|
+
|
|
43
|
+
- **引擎烟测门(`scripts/engine-smoke.mjs` + `.github/workflows/engine-smoke.yml`)**:真实走 build → npm pack → 临时目录安装 → 从安装形态的 `lib/local.js` 驱动随包引擎 embed 两条中文文本(断言 512 维、模长≈1);windows-latest(主)+ ubuntu-latest(对照),模型端点优先 hf-mirror.com、10s 探测失败回退默认端点,15 分钟 job 上限。paths 过滤只在嵌入器/引擎/构建配置变动时触发。本地复现:`pnpm bundle && node scripts/engine-smoke.mjs`(本地反复重跑可加 `--keep-cache` 复用模型缓存,不吃模型端点的网络抖动;CI 保持冷路径)。
|
|
44
|
+
|
|
11
45
|
## [0.13.10] - 2026-11-11
|
|
12
46
|
|
|
13
47
|
### Fixed
|
package/README.en.md
CHANGED
|
@@ -89,7 +89,7 @@ In one line: **we make memory a local library you install once, not a service yo
|
|
|
89
89
|
+--> capture / save --> four dispositions: accept · merge · defer · drop
|
|
90
90
|
agent call+
|
|
91
91
|
|
|
|
92
|
-
SQLite
|
|
92
|
+
SQLite three stores: user.db (follows you) + project-<hash>.db (follows the repo) + shared.db (lending shelf)
|
|
93
93
|
|
|
|
94
94
|
+----------------------+----------------------+----------------------+
|
|
95
95
|
v v v
|
|
@@ -150,7 +150,8 @@ Sensory and emotional dimensions (smell, temperature, emotional weight) are deli
|
|
|
150
150
|
## Features
|
|
151
151
|
|
|
152
152
|
- **Cross-session memory**: a user memory profile is injected at session start (entry cap plus token budget, both configurable; a curated profile maintained via `engram_profile_edit` takes precedence over derived facts), so the agent naturally knows who you are and what you are building; tools recall facts across sessions.
|
|
153
|
-
- **
|
|
153
|
+
- **Three-scope stores**: `user.db` is the private palace, global across projects (unrelated to the shared scope); `project-<hash>.db` isolated per git origin identity (falls back to a working-directory encoding without git; legacy stores migrate automatically) — personal preferences follow the person, project conventions follow the repo.
|
|
154
|
+
- **Shared scope (`shared.db`)**: a staging area for memories you hand-pick to lend out — by design "explicit in, explicit out": automatic capture only routes project/user (the preference-follows-person / convention-follows-repo dichotomy has no slot for shared), and profile injection and review scheduling never touch it; explicit channels only: `engram_save` / `engram_import` to write, `engram_search scope=shared` to retrieve, and `engram_mirror` export appends the `share-manifest.json` loan manifest (`firstLentAt` / `lastAccessedAt` / `accessCount`) recording responsibility and access traces of what went public.
|
|
154
155
|
- **Hybrid retrieval**: FTS5 (unicode61 + Chinese 2-gram pre-tokenization) fused with local vectors (by default `Xenova/paraphrase-multilingual-MiniLM-L12-v2`, 384-dim, q8; model and pooling are configurable — see below) via RRF, plus one-hop expansion over relation edges and a multiplicative recency/proof ranking boost; the embedding model runs offline, and a failed download degrades to keyword-only retrieval with an explicit marker.
|
|
155
156
|
- **Memory-palace information architecture** (v0.7.2+): all four principles live on the core path, not in display-layer paint — **location as index** (writes sort by kind into rooms and pin a `room#slot` coordinate; room capacity 9, overflow opens a new room, slots are never recycled); **fixed route as order** (`tour_routes` is append-only; `engram_tour mode=fixed` walks the whole palace in slot order); **skeleton reused long-term** (a topic always lands in the same room and the same index, so recall is sequential extraction rather than fresh search); **every marker unique** (placard rule scored 0-1: globally unique +0.4 / date anchor +0.3 / no 6-char prefix clash within the room +0.3; low scores enter the refurb list; a palace with fewer than 8 active memories is left unscanned to avoid small-store noise).
|
|
156
157
|
- **Corridor-routed retrieval**: the profile carries a room directory, and `engram_search` accepts a `room` parameter — decide the room first, then search inside it, instead of always running whole-store RRF. The top 5 hits carry neighbouring slot ids from the same room as encoding-specificity cues.
|
|
@@ -198,6 +199,8 @@ Sensory and emotional dimensions (smell, temperature, emotional weight) are deli
|
|
|
198
199
|
| `engram_profile_edit` | Edit the curated profile block: `view` shows the current content and version history; `edit` writes a new version (optimistic lock via `expectedVersion`, conflicts fail loud); `rollback` restores a historical version (appended as a new version; history is never rewritten). The curated profile is injected ahead of the derived profile; every edit lands in the operation log, and the profile card on the panel's Today view shows version diffs |
|
|
199
200
|
| `engram_language_guide` | Output the plugin language guide (the body of `<package-root>/docs/agent-language-guide.ru.md`). The first-run window promises a human whose language is not built in that the agent will print an instruction; this tool keeps that promise. The source text is written in Russian as a draft — the agent translates it into the asker's language itself |
|
|
200
201
|
|
|
202
|
+
> Scope enum: `user` = private palace (global, follows the person); `project` = the current repo's project palace; `shared` = the shared staging area (memories hand-picked to lend out, see "Shared scope" in the feature list); `all` = retrieval tools merge all three stores.
|
|
203
|
+
|
|
201
204
|
## Configuration
|
|
202
205
|
|
|
203
206
|
Optional configuration (cordis.yml):
|
|
@@ -270,7 +273,7 @@ The plugin has a host half (Node) and a browser half (React):
|
|
|
270
273
|
Session agent Host half (Node)
|
|
271
274
|
│ │
|
|
272
275
|
├─ every turn, first step ◀─────────────── ├─ user memory profile injection (plugin-source user snapshot)
|
|
273
|
-
├─ engram_save / search / review … ──────▶ ├─ SQLite
|
|
276
|
+
├─ engram_save / search / review … ──────▶ ├─ SQLite three stores (user.db / project-<origin hash>.db / shared.db)
|
|
274
277
|
│ ├─ FTS5 keyword track + local vector track, RRF fusion + ranking boost
|
|
275
278
|
├─ engram_distill ───────────────────────▶ ├─ aux-LLM distillation (cluster merge → supersedes chain)
|
|
276
279
|
├─ session end (reflect enabled) ────────▶ ├─ belief consolidation (unconsolidated evidence → observations: near-neighbor merge / stale review)
|
|
@@ -278,11 +281,11 @@ Session agent Host half (Node)
|
|
|
278
281
|
└─ Settings "Memory Library" tab ◀──────── ─── loopback API /api/engram/* (writes verify loopback Origin)
|
|
279
282
|
```
|
|
280
283
|
|
|
281
|
-
- **
|
|
284
|
+
- **Three-scope stores**: `user.db` shared globally; `project-<hash>.db` named by the normalized git origin URL hash (`git@github.com:a/b.git` and `https://github.com/a/b` share one store; worktrees resolve through the pointer to the main repo's origin); without git or an origin it falls back to a working-directory encoding, and legacy cwd-named stores are renamed in place at startup (if both exist, nothing moves and a warning is logged). The third store `shared.db` is the shared staging area (see "Shared scope" in the feature list).
|
|
282
285
|
- **Palace structure (the directory is the room, the path is the route)**: the **grand hall** is the standing core profile injected every turn (few and stable, always present); the **corridor** is the room directory in the profile plus the `engram_search room` parameter (pick the room, then search); **rooms** sort by kind (Fact Hall / Preference Pavilion / Decision Chamber / Episode Gallery / Skill Workshop) with capacity 9, overflowing into `<name>-2`; **placards** are each memory's `placard` marker, scored on the unique · distinctive · dated rule. Existing stores are slotted on first open (idempotent; opening a new room logs a warning so a human can name it).
|
|
283
286
|
- **Automatic capture** (when `ingest` is on): each new turn's first step extracts candidate facts from the previous turn out of the session log; session end (`session/disposed`) captures the final turn with a 5-second timeout, and on failure/timeout a pending key lands in the operation log for the next session's first step to replay; captured (session, turn) pairs are idempotent. The read source is the session log; aux-call request auditing goes to the plugin's own operation log — unknown events are never appended to the session log. Candidates are written with low confidence and deduplicated by embedding.
|
|
284
287
|
- **Provenance chain**: every memory records its source session, turn, and event seq, fully traceable via `engram_review`; the operation log table records every write/edit/forget/distill/decay.
|
|
285
|
-
- **Offline embeddings**: the model downloads once (q8, ~
|
|
288
|
+
- **Offline embeddings**: the model downloads once (q8, ~24MB; mirror endpoint configurable), then runs fully offline; on failure the plugin keeps working and retrieval degrades to keyword-only with an explicit marker. **The engine ships with the package as pure WASM** (since 0.13.11: transformers.js web build + the onnxruntime-web wasm backend, single-threaded) — the install tree carries no native dependencies, at the cost of slower inference than the native runtime: ~90ms per text (vs ~10-20ms native), a full 3000-memory backfill takes ~7 minutes. **The dimension is a hard constraint**: when the stored vectors and the current model disagree, writes and similarity comparisons are both refused with `EMBEDDER_DIMENSION_MISMATCH` (naming both dimensions) instead of being truncated into a plausible-looking similarity.
|
|
286
289
|
- **UI localization**: the client half registers zh/en dictionaries through the host locale service and follows the host language setting live; data-level enums (status/kind) are mapped only in the display layer and stay English in storage.
|
|
287
290
|
|
|
288
291
|
## Web Management Panel
|
|
@@ -326,7 +329,7 @@ The first two run on a bare checkout, and CI (`.github/workflows/checks.yml`) ru
|
|
|
326
329
|
Two notes on install and build scripts:
|
|
327
330
|
|
|
328
331
|
- **GitHub source quick-install** (`dsh plugin add github:kenz1117/dsh-engram`) fetches sources; `prepare` runs `pnpm bundle` on the spot when `lib/` is missing. If that build fails, read the bundle section of the prepare log — not the host's misleading "no entry point".
|
|
329
|
-
- **
|
|
332
|
+
- **Bundled engine (since 0.13.11)**: the embedding engine ships as pure WASM — at `pnpm bundle` time `scripts/copy-engine.mjs` copies the transformers.js web build and the onnxruntime-web wasm artifacts from devDependencies into `lib/engine/`. The user install tree carries no native dependencies, so the "allow build scripts" prompt of older versions is obsolete (the 0.13.10-and-earlier notes about onnxruntime-node build permissions no longer apply). `pnpm prepack` (runs automatically on npm pack/publish) re-verifies the engine files — a package without the engine cannot be published.
|
|
330
333
|
|
|
331
334
|
## Model Experience
|
|
332
335
|
|
package/README.md
CHANGED
|
@@ -67,9 +67,9 @@ dsh plugin --profile web add @kenz1117/dsh-engram
|
|
|
67
67
|
## 升级
|
|
68
68
|
|
|
69
69
|
- **用哪个入口装,就用哪个入口升**:市场里装的就一直在市场里更新;命令行 `dsh plugin add` 装的就继续用命令行。两边混用会碰到市场的跨来源保护——它提示「先卸载,再从市场安装」时照做即可,这是防止把不同来源的同名插件互相覆盖的设计,记忆数据在数据目录里,不受卸载影响。
|
|
70
|
-
-
|
|
70
|
+
- **「允许构建脚本并重试」提示可以不点**:0.13.11 起嵌入引擎是随包的纯 WASM(见下),安装树里不再有任何带构建脚本的原生依赖(旧版本的 onnxruntime-node 已随引擎出树移除)。
|
|
71
71
|
- **模型缓存跨升级持久**(`<dbDir>/models`),升级不重复下载模型;0.13.6 起数据目录默认跟随 `$DSH_HOME`,换盘搬家不再把库留在旧盘。
|
|
72
|
-
-
|
|
72
|
+
- **引擎随包,弱网更新不再卡死**(0.13.11 起):本地嵌入引擎从安装树(optionalDependencies,原生件解包约 300MB)整体移出,改为随包分发的纯 WASM(包体 775KB → 约 7.5MB)——市场更新的「先删后装 + 限时」里不再有会被弱网杀掉的百 MB 大件。**存量向量完全有效**(同模型同 q8 同池化,不需要 backfill);只有模型文件(q8 约 24MB,`<dbDir>/models`)仍是首次使用时联网下载,可配镜像。
|
|
73
73
|
- 升级后打开面板「系统 · 运行时」即可核对插件/面板版本是否一致(不一致会挂重启横幅)。
|
|
74
74
|
|
|
75
75
|
## 为什么是它
|
|
@@ -97,7 +97,7 @@ dsh plugin --profile web add @kenz1117/dsh-engram
|
|
|
97
97
|
+--> 摄取 / 保存 --> 写入四态: accept · merge · defer · drop
|
|
98
98
|
agent 调用+
|
|
99
99
|
|
|
|
100
|
-
SQLite
|
|
100
|
+
SQLite 三库: user.db(跟人走)+ project-<hash>.db(跟仓库走)+ shared.db(借阅架)
|
|
101
101
|
|
|
|
102
102
|
+----------------------+----------------------+----------------------+
|
|
103
103
|
v v v
|
|
@@ -159,7 +159,8 @@ DeepSeek Harness 跨会话长期记忆插件 —— 把记忆宫殿的**信息
|
|
|
159
159
|
## 特性
|
|
160
160
|
|
|
161
161
|
- **跨会话记忆**:会话开始注入用户画像摘要(条数 + token 预算双重上限,可配;`engram_profile_edit` 维护的 curated 画像优先于派生事实),Agent 天然"记得"你是谁、在做什么;工具检索跨会话召回历史事实。
|
|
162
|
-
-
|
|
162
|
+
- **三层分库**:`user.db` 跨项目全局(私人宫殿,与「共享 scope」无关);`project-<hash>.db` 按 git origin 标识隔离(无 git 时回退 cwd 全量哈希,旧命名库自动迁移)——个人偏好跟人走,项目约定跟仓库走。**项目宫殿随工作区切换**:管理面板「项目」scope 默认跟随 GUI 当前选中的工作区(Header 显示工作区标题与路径),也可在下拉里固定到某个工作区;`engram_save/search` 等工具的 project 读写同样按当前会话 cwd 归属,与面板同一口径。
|
|
163
|
+
- **共享 scope(`shared.db`)**:手动挑出、准备借出给别人的记忆暂存区——设计上「只显式进出」:自动摄取只判 project/user(「偏好跟人走、约定跟仓库走」二分里没有 shared 的位置),画像注入与复习调度也不碰它;显式通道:`engram_save` / `engram_import` 写入、`engram_search scope=shared` 检索、`engram_mirror` 导出时附 `share-manifest.json` 借阅归还清单(`firstLentAt` / `lastAccessedAt` / `accessCount`),记录公开出去的责任与访问痕迹。
|
|
163
164
|
- **混合检索**:FTS5(unicode61 + 中文 2-gram 预切词)与本地向量(默认 `Xenova/paraphrase-multilingual-MiniLM-L12-v2`,384 维,q8;模型与池化可配,见下)RRF 融合 + 关系边一跳扩展 + 新鲜度/命中次数乘性排序 boost;嵌入模型离线运行,下载失败自动降级纯关键词并显式标记。
|
|
164
165
|
- **记忆宫殿信息架构**(v0.7.2+):四原则全部落进核心路径,而非展示层皮肤——**位置当索引**(写入按 kind 分房并钉「房间#桩位」坐标,房间容量 9,满员开新房,桩位只增不回收);**固定路线定顺序**(`tour_routes` append-only,`engram_tour mode=fixed` 按桩位顺序走全宫);**骨架长期复用**(同一 topic 永远落在同一房间同一序号,顺序提取而非重新检索);**标记独一无二**(门牌规则 0-1 评分:全库唯一 +0.4 / 带日期锚点 +0.3 / 同房前 6 字不重复 +0.3,低分进翻新清单;库内 active 记忆少于 8 条时不扫描,避免小库噪声)。
|
|
165
166
|
- **走廊路由检索**:画像里附房间目录,`engram_search` 支持 `room` 参数——先决定进哪个房间,再在房内检索,而非一上来全库 RRF。检索命中 top5 附同房间相邻桩位 id 作为编码特异性线索。
|
|
@@ -171,7 +172,7 @@ DeepSeek Harness 跨会话长期记忆插件 —— 把记忆宫殿的**信息
|
|
|
171
172
|
- **实体词典**(v0.7.10+):自动摄取与 `engram_save` 的辅助 LLM 输出同时抽取实体提及(人物/项目/工具/概念,可带别名),按归一化名与既有实体的 name/aliases 精确匹配消解——命中复用并刷新「最近提及」,未命中新建;记忆与实体多对多关联,随来源记忆所在 scope 分库。`engram_search` 命中行附关联实体标签;实体消解故障只静默跳过关联,不影响记忆落库。面板「实体」视图按类别筛选、按名称/别名搜索,点开单实体看它牵出的所有记忆。
|
|
172
173
|
- **自动摄取**(`ingest` 配置开启时):新一轮第一步从会话日志提取上一轮的候选事实,会话结束时补摄取最后一轮(失败留 pending 键,下次会话自动补做,幂等不重复),低 confidence 写入,嵌入可用时按四态处置近邻(复述并入强化 / 疑似矛盾建边待裁决 / 全新写入)——不说"记住"也能攒记忆。**逐条判宫殿**:提炼时同步判定作用域,只跟当前项目/仓库有关的(技术选型、项目约定、架构决策)进当前会话 cwd 对应的项目库,跨项目通用的(个人偏好、习惯、本人经历)进私人库——偏好跟人走、约定跟仓库走。
|
|
173
174
|
- **来源审计**:每条记忆记录来源会话、轮次与事件 seq,`engram_review` 完整回查来源链、取代链、矛盾与操作日志;全部写入/修改/遗忘/蒸馏/衰减入操作日志表。
|
|
174
|
-
- **Web 管理面板**(v0.7.0+):v0.8.0 起从「设置 → 记忆库 tab」升级为**顶层侧栏入口**(`sidebar.panellist` + `main` 双槽位,与「Hyreal FDE 工作台」平级),主列满宽渲染所有视图——一键直达、不再被设置弹窗 ~600px 限制、九视图横排展开;入口图标为 18px 宫殿剪影 SVG(屋顶 + 主体 + 门洞 + 两侧窗,Phosphor 风 stroke 1.75)。九个视图:今日(速览条:记忆 / 开放 / 清晰度 + 健康分环,底行「落成 / 发掘 / 整理 / 今日到期」四项小统计与诊脉时间同行;下面是入殿导航、房间目录、待翻新、健康分构成;侧栏画像卡展示常驻画像(curated)当前内容与版本 diff 历史)、陈展(筛选含今日到期 / 巡游路线序 / 批量 / 列表与编辑;「参观 / 修缮」以视口浮层呈现——sticky 钉在宿主滚动区可见顶部,长列表任意滚动位置打开都不跳动不挤压)、走廊(走廊鸟瞰 + 检索实验台)、日志(近 7 天计数 +
|
|
175
|
+
- **Web 管理面板**(v0.7.0+):v0.8.0 起从「设置 → 记忆库 tab」升级为**顶层侧栏入口**(`sidebar.panellist` + `main` 双槽位,与「Hyreal FDE 工作台」平级),主列满宽渲染所有视图——一键直达、不再被设置弹窗 ~600px 限制、九视图横排展开;入口图标为 18px 宫殿剪影 SVG(屋顶 + 主体 + 门洞 + 两侧窗,Phosphor 风 stroke 1.75)。九个视图:今日(速览条:记忆 / 开放 / 清晰度 + 健康分环,底行「落成 / 发掘 / 整理 / 今日到期」四项小统计与诊脉时间同行;下面是入殿导航、房间目录、待翻新、健康分构成;侧栏画像卡展示常驻画像(curated)当前内容与版本 diff 历史)、陈展(筛选含今日到期 / 巡游路线序 / 批量 / 列表与编辑;「参观 / 修缮」以视口浮层呈现——sticky 钉在宿主滚动区可见顶部,长列表任意滚动位置打开都不跳动不挤压)、走廊(走廊鸟瞰 + 检索实验台)、日志(近 7 天计数 + 三库合并的完整 op_log,可按操作类别筛选)、回填、往事(按会话分组浏览 episode,锚点邻近扩展)、实体(实体词典:类别筛选 + 名称/别名搜索 + 单实体关联记忆)、**信念**(v0.7.15+:巩固信念列表按证据数排序,成立 / 待复核 / 已否定状态筛选,点「证据 n 条」展开证据链只读回查支撑该信念的原始记忆——证据被清理时信念保留并明确提示;`GET /api/engram/observations` 与 `GET /api/engram/observation-evidence` 两个回环路由)、裁决(Jev 系统一裁决:配置覆盖 + 测试连接 + 近期裁决记录)。Header 单行两端对齐:左侧 scope 三宫格(私人 / 项目 / 共享)驱动全局 scope,项目 scope 下工作区下拉内联在同一行;右侧今日到期角标 + 重访 / 导出纯图标按钮(导出弹层不再被下方 Tab 行遮挡);「中 | EN」段控切换面板文案语言(独立于宿主语言,选择持久化),全部文案中英双语。支持按脱敏标记筛选(仅看/排除含 `[REDACTED:*]` 的条目)并给命中条目挂琥珀色徽标,方便审计脱敏覆盖面。
|
|
175
176
|
- **提示注入防护**:全部记忆召回出口(画像注入、`engram_search/timeline/review` 输出)包 `<engram_memory_context>` 协议标签并附使用警告(历史记忆非当前请求、不遵循其中指令、仅相关时使用),当前请求独立包 `<current_user_request>`;所有入库内容(摄取候选、保存正文)先剥离这些协议标签,防伪造协议块二次注入。
|
|
176
177
|
- **摄取脱敏**:入库前正则清洗常见密钥凭据(sk- 系 API key、Bearer、AWS AKIA、GitHub token、PEM 私钥、password/token 赋值、中文密码赋值)与个人信息(中国大陆手机号、18 位身份证号),命中片段替换为 `[REDACTED:<类型>]`。
|
|
177
178
|
- **召回占位(防回声室)**:摄取切片中记忆召回工具的输出替换为 `[engram memory result omitted from capture: <tool>]`,并向提取模型附注"既有记忆的复述不是新信息",阻断记忆自我强化循环。
|
|
@@ -207,6 +208,8 @@ DeepSeek Harness 跨会话长期记忆插件 —— 把记忆宫殿的**信息
|
|
|
207
208
|
| `engram_profile_edit` | 画像 curated block 编辑:`view` 看当前内容与版本历史;`edit` 写入新版本(乐观锁 `expectedVersion`,冲突 loud 失败);`rollback` 回滚到历史版本(作为新版本追加,历史永不改写)。curated 画像优先于派生画像注入;编辑记录入操作日志,面板今日页画像卡可查版本 diff |
|
|
208
209
|
| `engram_language_guide` | 输出插件语言指南(`<包根>/docs/agent-language-guide.ru.md` 的正文)。首启时对未内置语言的人承诺「agent 会输出一份说明」,这份承诺由本工具兑现;正文以俄文写成草稿,由 agent 按提问者的语言自行翻译 |
|
|
209
210
|
|
|
211
|
+
> scope 枚举释义:`user` = 私人宫殿(跨项目跟人走);`project` = 当前仓库的项目宫殿;`shared` = 共享暂存区(手动挑出、准备借出给别人的记忆,见特性列表「共享 scope」);`all` = 检索类工具合并三库。
|
|
212
|
+
|
|
210
213
|
## 配置
|
|
211
214
|
|
|
212
215
|
可选配置(cordis.yml):
|
|
@@ -297,7 +300,7 @@ DeepSeek Harness 跨会话长期记忆插件 —— 把记忆宫殿的**信息
|
|
|
297
300
|
会话 Agent 宿主半(Node)
|
|
298
301
|
│ │
|
|
299
302
|
├─ 每轮第一步 ◀─────────────────────────── ├─ 用户画像快照注入(plugin 来源 user 快照)
|
|
300
|
-
├─ engram_save / search / review … ──────▶ ├─ SQLite
|
|
303
|
+
├─ engram_save / search / review … ──────▶ ├─ SQLite 三库(user.db / project-<origin hash>.db / shared.db)
|
|
301
304
|
│ ├─ FTS5 关键词道 + 本地向量道 RRF 融合 + 排序 boost
|
|
302
305
|
├─ engram_distill ───────────────────────▶ ├─ 辅助 LLM 蒸馏(簇合并 → supersedes 链)
|
|
303
306
|
├─ 会话结束(reflect 开启)──────────────▶ ├─ 信念巩固(未巩固证据 → observations:近邻归并 / stale 复核)
|
|
@@ -305,12 +308,12 @@ DeepSeek Harness 跨会话长期记忆插件 —— 把记忆宫殿的**信息
|
|
|
305
308
|
└─ 设置页「记忆库」tab ◀────────────────── ─── 回环 API /api/engram/*(写操作校验回环 Origin)
|
|
306
309
|
```
|
|
307
310
|
|
|
308
|
-
-
|
|
311
|
+
- **三层分库**:`user.db` 跨项目全局(私人宫殿);`project-<hash>.db` 按 git origin URL 归一化哈希命名(`git@github.com:a/b.git` 与 `https://github.com/a/b` 同库;worktree 沿指针解析到主仓库 origin);无 git 或无 origin 时按 **cwd 全量 sha256** 命名(v0.7.6 起;旧的「cwd 前 12 字符」截断命名会同前缀撞库,启动时自动 rename 迁移,新旧并存则不动并告警)。第三库 `shared.db` 是共享暂存区(定位见特性列表「共享 scope」条)。
|
|
309
312
|
- **项目宫殿路由**:`GET /api/engram/workspaces` 给出可选项目宫殿清单(来源 = 宿主 `workspaceRegistry` 工作区 → 会话 header 里出现过的 cwd → 插件进程目录兜底,按分库名去重;同仓库的多个 worktree 共用一个宫殿);所有项目 scope 的接口与工具读写接受选择器(HTTP `?project=<dbName>` / POST body `project`,工具用当前会话 `session.header.cwd`),未知选择器 HTTP 回 404、工具回退进程目录。面板「项目」scope 默认跟随 GUI 当前工作区并可固定到某个工作区。
|
|
310
313
|
- **宫殿结构(目录即房间,路径即路线)**:**主厅** = 每轮注入的常驻核心画像(少而稳,每次都在场);**走廊** = 画像里附的房间目录 + `engram_search room` 参数(先定房间,再检索);**房间** = 按 kind 分房(事实厅 / 偏好阁 / 决策堂 / 往事廊 / 技法坊),容量 9,满员开「房名-2」;**门牌** = 每条记忆的 `placard` 铭牌,受唯一·差异化·带日期纪律评分。存量库首次打开时自动补排桩(幂等,开新房会告警提醒人工命名)。
|
|
311
314
|
- **自动摄取**(`ingest` 开启时):新一轮第一步从会话日志提取上一轮的候选事实;会话结束(session/disposed)补摄取最后一轮,5 秒超时,失败/超时把 pending 键写入操作日志,下次会话首步自动重放补做;已摄取的 (会话, 轮次) 幂等去重(键固定在私人库,实时与历史回填共用一份,跨路径不重复)。读取源是会话日志;辅助调用的请求审计走插件自身操作日志,不向会话日志 append 未知事件。候选以低 confidence 写入并按**目标分库内**的嵌入近邻去重。**作用域逐条判**:提炼输出带 `scope`,`project` 落当前会话 cwd 的项目库、`user` 落私人库;无 cwd 的会话只能进私人库(此类会话不做逐条判定,避免标记与实际分库不符)。历史回填沿用同一判定,默认按各会话自己的 cwd 落项目库。
|
|
312
315
|
- **来源链**:每条记忆记录来源会话、轮次与事件 seq,`engram_review` 可完整回查;操作日志表记录全部写入/修改/遗忘/蒸馏/衰减。
|
|
313
|
-
- **嵌入离线**:模型首次使用需联网下载(q8 约
|
|
316
|
+
- **嵌入离线**:模型首次使用需联网下载(q8 约 24MB,端点可配镜像),此后完全离线;失败时插件照常工作,检索降级纯关键词并显式标记。**引擎是随包的纯 WASM**(0.13.11 起,transformers.js web 构建 + onnxruntime-web wasm 后端,单线程):安装树里没有原生依赖,代价是推理慢于原生件——约 **90ms/条**(原生约 10-20ms/条),全量回填 3000 条约 7 分钟。**维度是硬约束**:库中向量与当前模型的维度不一致时,写入与相似度比较都直接拒绝并报 `EMBEDDER_DIMENSION_MISMATCH`(说清两边各是多少维),而不是逐维截断后给出一个像样的相似度。
|
|
314
317
|
- **界面本地化**:client 半经宿主 locale 服务注册 zh/en 词典,跟随宿主语言设置实时切换;状态/种类等数据枚举仅在显示层映射,存储值保持英文。
|
|
315
318
|
|
|
316
319
|
## Web 管理面板
|
|
@@ -324,7 +327,7 @@ DeepSeek Harness 跨会话长期记忆插件 —— 把记忆宫殿的**信息
|
|
|
324
327
|
| **记忆** | 记录 / 时间线 / 实体 / 图谱 | 记录=全量记忆库(房间 / 状态 / 内容过滤、双排序、批量遗忘 / 恢复、行内「身份与修订」抽屉);时间线=episode 情景时间线与邻近扩展;实体=人物 / 项目 / 工具 / 概念词典;图谱=平面图 / 力导向关系图 / 回忆螺旋 |
|
|
325
328
|
| **治理** | 矛盾 / 信念 | 矛盾队列(双侧记忆与稳定 id,处置前说清后果);信念证据链与成立 / 待复核 / 已否定治理 |
|
|
326
329
|
| **回放** | — | 注入快照 head / detail:逐字 packet、完整哈希、入选记忆 id、curated 与压缩元数据,只展示事实源不重建 |
|
|
327
|
-
| **系统** | 运行时 / 存储 / 模型与词典 / 历史回填 / Jev / 日志 | 版本握手与持久作业队列;三个分库的规模与日志占用;宫殿语言、面板语言与词典编辑器;历史回填(估算 → 执行 → 续跑);Jev
|
|
330
|
+
| **系统** | 运行时 / 存储 / 模型与词典 / 历史回填 / Jev / 日志 | 版本握手与持久作业队列;三个分库的规模与日志占用;宫殿语言、面板语言与词典编辑器;历史回填(估算 → 执行 → 续跑);Jev 裁决配置与观测;三库合并的 op_log 审计流水 |
|
|
328
331
|
|
|
329
332
|
界面语言随面板切换(中文 / English / Русский),服务端理由文案跟随面板语言。数据经回环 API `/api/engram/*`(写操作校验回环 Origin + 环绕三重防线);面板与后端进程版本不一致时顶部出现重启提醒横幅。headless 等无 webServer 的组合不挂载面板,其余能力不受影响。v0.7 时代逐版本的面板演进记录见 [docs/panel-history-v0.7.md](docs/panel-history-v0.7.md)。
|
|
330
333
|
|
|
@@ -351,7 +354,7 @@ pnpm test
|
|
|
351
354
|
安装与构建脚本的两点说明:
|
|
352
355
|
|
|
353
356
|
- **GitHub 源码快捷安装**(`dsh plugin add github:kenz1117/dsh-engram`)拿的是源码,`prepare` 会在 `lib/` 缺失时自动执行 `pnpm bundle` 现场构建——失败时看 prepare 日志的 bundle 段,而不是宿主报的 "no entry point"。
|
|
354
|
-
-
|
|
357
|
+
- **引擎随包(0.13.11 起)**:嵌入引擎是随包的纯 WASM——`pnpm bundle` 时 `scripts/copy-engine.mjs` 把 transformers.js web 构建与 onnxruntime-web 的 wasm 件从 devDependencies 拷进 `lib/engine/`,用户安装树里没有任何原生依赖,也就不再有「允许构建脚本」的诉求(0.13.10 及更早版本的 onnxruntime-node 构建脚本许可说明已随之作废)。`pnpm prepack`(npm pack/publish 时自动跑)会再次核对引擎文件,带不出引擎的包发不出去。
|
|
355
358
|
|
|
356
359
|
## Model Experience
|
|
357
360
|
|
package/i18n/ru.txt
CHANGED
|
@@ -12,6 +12,7 @@ Use engram_search to recall details (pass room to search inside one room); use e
|
|
|
12
12
|
Curated profile (user-maintained via engram_profile_edit; authoritative over derived facts): Курируемый профиль (ведётся пользователем через engram_profile_edit; главнее выведенных фактов):
|
|
13
13
|
Consolidated beliefs (distilled from multiple stored memories; verify against sources before high-stakes use): Устоявшиеся убеждения (выведены из множества сохранённых воспоминаний; перед важными решениями сверяйтесь с источниками):
|
|
14
14
|
- {belief} ({count} sources) - {belief} (источников: {count})
|
|
15
|
+
(+{count} folded) (+{count} свёрнуто)
|
|
15
16
|
\nPalace review due today: {count}{plus} memories. Use engram_review_queue for active recall (recall beats re-reading). \nСегодня пора вспомнить: {count}{plus} воспоминаний во дворце. Используйте engram_review_queue для активного припоминания (припоминание сильнее перечитывания).
|
|
16
17
|
Compress each memory entry into a shorter single-sentence wording (at most 40 characters per entry), keeping the key information that can be reused across sessions (facts, preferences, decisions, methods).\nOutput only one JSON array, each item shaped like {"id": "the id returned verbatim", "content": "the compressed wording"}; the number of items and the ids must correspond one-to-one with the input.\nDo not output anything other than JSON. Сожми каждую запись памяти в более короткую однострочную формулировку (не более 40 символов на запись), сохранив ключевую информацию, пригодную для повторного использования между сессиями (факты, предпочтения, решения, методы).\nВыведи только один JSON-массив, каждый элемент вида {"id": "id, возвращённый как есть", "content": "сжатая формулировка"}; число элементов и id должны взаимно однозначно соответствовать входу.\nНе выводи ничего, кроме JSON.
|
|
17
18
|
This profile holds {count} memories in total; they were picked for the following reasons: В этом профиле всего {count} воспоминаний; причины отбора:
|
|
@@ -164,6 +165,7 @@ before handling this manually, stop the affected hosts and back up every databas
|
|
|
164
165
|
[dsh-engram] the legacy database already has a migration record ({names}, claimed earlier by {cwd}): {pointer}; the database migrated earlier may hold memories of the current directory. {manual} [dsh-engram] У старой базы уже есть запись о переносе ({names}, раньше принадлежала {cwd}): {pointer}; в базе, перенесённой ранее, могут быть воспоминания текущего каталога. {manual}
|
|
165
166
|
write-disposition: merge target {id} does not exist write-disposition: цель слияния {id} не существует
|
|
166
167
|
embedding model download/load failed; retrieval has degraded to keyword-only mode — check the network and retry Не удалось скачать/загрузить модель эмбеддингов; поиск переведён в режим только по ключевым словам — проверьте сеть и повторите
|
|
168
|
+
the local embedding engine was not installed with the plugin (lib/engine is missing) — the package is incomplete or the update was cut short; reinstall the plugin; retrieval has degraded to keyword-only mode локальный движок эмбеддингов не установлен вместе с плагином (отсутствует lib/engine) — пакет неполный или обновление оборвалось на середине; переустановите плагин; поиск переведён в режим только по ключевым словам
|
|
167
169
|
embedding dimension mismatch: the store holds {expected}-dimensional vectors, the embedder returned {found}. Comparison and writes are refused instead of being silently truncated — switch the model back, or re-embed the store with the new one размерность векторов не совпадает: в базе {expected} измерений, эмбеддер вернул {found}. Сравнение и запись отвергаются, а не усекаются молча — верните прежнюю модель или пересчитайте векторы новой
|
|
168
170
|
could not resolve a local embedding model for this language; retrieval has degraded to keyword-only mode — check the model registry Не удалось определить локальную модель вложений для этого языка; поиск переведён в режим только по ключевым словам — проверьте реестр моделей
|
|
169
171
|
embedding endpoint unreachable ({baseUrl}, timeout {timeoutMs} ms) эндпоинт эмбеддингов недоступен ({baseUrl}, таймаут {timeoutMs} мс)
|
|
@@ -427,6 +429,7 @@ engram_distill: the auxiliary LLM is unavailable (the host provides no llm servi
|
|
|
427
429
|
engram_distill: cannot determine the model route (the session has no model request yet); configure provider/model in cordis.yml engram_distill: не удалось определить маршрут модели (в сессии ещё не было запроса к модели); настройте provider/model в cordis.yml
|
|
428
430
|
Distillation complete: drew on {input} memories, produced {distilled} higher-level rules and archived {superseded} old memories (the supersedes chain is in place and can be audited with engram_review). Дистилляция завершена: взято воспоминаний {input}, получено закономерностей более высокого уровня {distilled}, архивировано старых воспоминаний {superseded} (цепочка supersedes построена, проверить можно через engram_review).
|
|
429
431
|
{count} produced records were written without a vector: the embedder was unavailable at that moment, so they show up as “records without a vector” on the maintenance card and the Run button fills them in. {count} записанных правил остались без вектора: эмбеддер в этот момент был недоступен, поэтому они видны в карточке обслуживания как «записи без вектора», а кнопка «Выполнить» их дозаполнит.
|
|
432
|
+
engram_distill: {count} entries left undistilled this run (LLM output budget); they stay active and are retried next run. engram_distill: в этот раз не удалось перегнать {count} записей (лимит вывода LLM); они остались активными и снова пойдут в дело при следующем запуске.
|
|
430
433
|
Belief consolidation: use the auxiliary LLM to consolidate several raw memories into a higher-level belief carrying an evidence count (form / refine / still / refute), merging same-topic beliefs automatically; the raw memories are kept, not archived. Call it after recurring patterns appear or a new batch of memories is added. Закрепление убеждений: с помощью вспомогательной LLM свести несколько исходных воспоминаний в убеждение более высокого уровня с числом доказательств (form — создать / refine — уточнить / still — сохранить / refute — опровергнуть), автоматически объединяя убеждения одной темы; исходные воспоминания сохраняются и не архивируются. Вызывайте после появления повторяющихся закономерностей или новой партии воспоминаний.
|
|
431
434
|
engram_reflect: the auxiliary LLM is unavailable (the host provides no llm service), cannot consolidate engram_reflect: вспомогательная LLM недоступна (хост не предоставляет службу llm), закрепление невозможно
|
|
432
435
|
engram_reflect: cannot determine the model route (the session has no model request yet); configure provider/model in cordis.yml engram_reflect: не удалось определить маршрут модели (в сессии ещё не было запроса к модели); настройте provider/model в cordis.yml
|