@kenz1117/dsh-engram 0.9.0 → 0.9.2
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.en.md +35 -20
- package/README.md +34 -19
- package/lib/client.js +2 -2
- package/lib/client.js.map +1 -1
- package/lib/index.js +1 -1
- package/package.json +2 -2
package/README.en.md
CHANGED
|
@@ -1,5 +1,7 @@
|
|
|
1
1
|
<div align="center">
|
|
2
2
|
|
|
3
|
+
<img src="docs/screenshots/hero.jpg" width="100%" alt="dsh-engram · Memory Palace — a cross-session long-term memory plugin for DeepSeek Harness">
|
|
4
|
+
|
|
3
5
|
# dsh-engram · Memory Palace
|
|
4
6
|
|
|
5
7
|
<p align="center">Cross-session long-term memory for DeepSeek Harness — it puts the memory palace's <b>information architecture</b> (not its neuroscience metaphor) into the agent: <b>location as index</b> (every memory pinned to a <code>room#slot</code> coordinate), <b>fixed route as order</b> (the tour route is append-only), <b>skeleton reused long-term</b> (a topic always lands in the same room and index), and <b>every marker unique</b> (placard rule: unique · distinctive · dated). Paired with spaced-repetition retrieval practice (cues only, never the body) and a knowledge flywheel (capture → reinforce → distill → decay). Pure TypeScript: no external processes, no Python dependency.</p>
|
|
@@ -28,6 +30,21 @@ dsh plugin --profile web add @kenz1117/dsh-engram
|
|
|
28
30
|
|
|
29
31
|
Zero configuration after install (stores and model cache default to `~/.dsh/engram`; profile injection on, automatic capture off).
|
|
30
32
|
|
|
33
|
+
|
|
34
|
+
## Screenshots
|
|
35
|
+
|
|
36
|
+
**Today** — the palace dashboard: KPI hero, activity heatmap, tour proposal, room directory.
|
|
37
|
+
|
|
38
|
+
<p align="center"><img src="docs/screenshots/today.png" width="820" alt="Today view: KPI hero, activity heatmap, room directory"></p>
|
|
39
|
+
|
|
40
|
+
**Full-width refurb list** — every suggestion shows its full reasoning and the complete memory text, read and act in place (demote / distill-merge), no popup detours.
|
|
41
|
+
|
|
42
|
+
<p align="center"><img src="docs/screenshots/refurb-fullwidth.png" width="820" alt="Refurb list: full-width, complete texts, in-place actions"></p>
|
|
43
|
+
|
|
44
|
+
**Library** — the full memory store with filters, sorting and inline placard expansion.
|
|
45
|
+
|
|
46
|
+
<p align="center"><img src="docs/screenshots/library.png" width="820" alt="Library view: filters, sorting, inline details"></p>
|
|
47
|
+
|
|
31
48
|
## Palace Structure: the Directory Is the Room, the Path Is the Route
|
|
32
49
|
|
|
33
50
|
What actually works in a memory palace is its **information architecture**, not the biology — machines can use the former, while an AI has neither the latter nor any need for it. Stripped down, there are only four things:
|
|
@@ -181,27 +198,23 @@ Session agent Host half (Node)
|
|
|
181
198
|
- **Offline embeddings**: the model downloads once (q8, ~50MB; mirror endpoint configurable), then runs fully offline; on failure the plugin keeps working and retrieval degrades to keyword-only with an explicit marker.
|
|
182
199
|
- **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.
|
|
183
200
|
|
|
184
|
-
## Web Management Panel
|
|
201
|
+
## Web Management Panel
|
|
185
202
|
|
|
186
|
-
|
|
203
|
+
After installation, a **Memory Palace** entry appears in the host sidebar (a standalone panel app since v0.8, no longer a settings tab), with 9 views covering everything a memory library needs day to day:
|
|
187
204
|
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
Since v0.7.12 the plugin integrates **Jev System-One adjudication** (off by default, the `jev` block in yml) and adds an eighth panel view, **"Jev"**: the DEFER fuzzy-band three-way ruling and contradiction-edge confirmation can be delegated to Jev, and when Jev is unavailable (network failure, timeout, or a missing key) it silently falls back to the pure-rule four-way behavior without blocking writes. The panel overrides five yml fields — the switch, API key, endpoint, model, and timeout — stored at `<dbDir>/jev-config.json` (0600 file inside a 0700 directory) and effective immediately on save: the judge re-reads the override at every assembly point, no restart needed; the three thresholds stay yml-only advanced settings, shown read-only in the panel. Key safety: GET responses return only a mask (last 4 characters when longer than 8), the plaintext never leaves the process, and the input field is never back-filled. Turning the switch on without any key degrades to off automatically; a corrupted override file heals as an empty override, fixed by the next panel save. The Jev tab also gains a "Test connection" action (verify endpoint and model reachability right after filling in the key — unsaved input is tested as typed and never written to the override file) and a "Recent adjudications" card (the last 50 adjudications in this process: verdict, whether Jev took part, elapsed time, and the fallback reason; cleared on restart), so "why was this one deferred" no longer needs guesswork.
|
|
203
|
-
|
|
204
|
-
v0.7.13 fixes the every-turn failure on DSH 0.1.7 (native session format v4) ([#5](https://github.com/kenz1117/dsh-engram/issues/5)): v4 retired the `kind: "plugin"` message-source wrapper (it is only rewritten to `plugin:<package>` when migrating historical v3 sessions; a native v4 event carrying it is refused by `assertV4MessageSources`), and the two injection sites (profile snapshot and assess reminder) used exactly that retired shape — with engram enabled, every new turn failed with `format v4 message requires a producer-owned source kind`. The sources are now producer-owned (`plugin:<package>`, matching what DSH's own v3→v4 migration produces; the other attribution fields are unchanged), and the internal auxiliary-call message source is unified the same way. The three read sites that skip our own injected snapshots relaxed from exact equality to a `plugin` prefix match, so both the v3 historical shape and the v4 shape are recognized and the plugin never ingests its own injections (self-pollution). 0.1.5 (v3 sessions) is unaffected; on 0.1.7 keep engram disabled until you upgrade to 0.7.13.
|
|
205
|
+
| View | What it shows |
|
|
206
|
+
|---|---|
|
|
207
|
+
| **Today** | KPI hero (memories / open / clarity / due today, each with a sparkline) + 6-month activity heatmap + tour proposal + **full-width refurb list** + room directory + resident profile |
|
|
208
|
+
| **Library** | The full memory store: filter by room / status / text, time & tour-route sorting, inline placard expansion, edit-via-supersession, batch forget / restore |
|
|
209
|
+
| **Corridor** | The memory graph: floorplan (architectural metaphor) / force-directed modes, plus a retrieval workbench with 1–3 hop roaming |
|
|
210
|
+
| **Spiral** | A spiral-layout overview, older towards the centre |
|
|
211
|
+
| **Episodes** | The episode timeline: grouped by session with LLM summaries, anchor-based proximity expansion |
|
|
212
|
+
| **Entities** | The people / projects / tools / concepts dictionary with per-entity memory links |
|
|
213
|
+
| **Beliefs** | Distilled higher-level patterns with six-step evidence strength |
|
|
214
|
+
| **Log** | The merged op_log audit trail, filterable by operation class |
|
|
215
|
+
| **Ops** | History backfill (estimate → run → resume), Jev adjudication setup and the recent-verdicts feed |
|
|
216
|
+
|
|
217
|
+
The UI language follows the panel switcher (中文 / English / Русский), and server-generated reason strings follow it too. All data flows over the loopback API `/api/engram/*` (write actions are gated by loopback origin plus the three-layer write guard). When the panel bundle and the backend process are different versions, a banner reminds you to restart the app. Headless profiles without a webServer mount nothing; everything else keeps working. The per-release panel notes from the v0.7 era live in [docs/panel-history-v0.7.md](docs/panel-history-v0.7.md).
|
|
205
218
|
|
|
206
219
|
## Development
|
|
207
220
|
|
|
@@ -261,7 +274,9 @@ The palace IA (position-as-index / fixed routes / retrieval practice) is the ind
|
|
|
261
274
|
|
|
262
275
|
Thanks to the community contributors who made this project better:
|
|
263
276
|
|
|
264
|
-
- **[@
|
|
277
|
+
- **[@dsv180](https://github.com/dsv180)** — the most prolific community contributor. [PR #13](https://github.com/kenz1117/dsh-engram/pull/13): bilingual host message catalog (zh/en) plus the language-pattern acceptance script (the skeleton of `check-patterns`). [PR #22](https://github.com/kenz1117/dsh-engram/pull/22): CI gates that make the two peer-free checks actually run on a hosted runner. [PR #23](https://github.com/kenz1117/dsh-engram/pull/23): made every peer optional via `peerDependenciesMeta` — fixing the packaging incident that left releases 0.8.0–0.8.14 uninstallable in clean profiles. [PR #20](https://github.com/kenz1117/dsh-engram/pull/20) (Jev credentials move up into the host; the plugin stores no keys) and [PR #21](https://github.com/kenz1117/dsh-engram/pull/21) (the embedder becomes a deployment property with a hard dimension guard) are under review. Every PR arrives with bilingual write-ups, itemised verification evidence and an honest limits list — a model of collaboration.
|
|
278
|
+
- **[@FeiLZX3Km](https://github.com/FeiLZX3Km)** — [Issue #19](https://github.com/kenz1117/dsh-engram/issues/19): three rounds of high-quality UI feedback (sidebar icon back to monochrome, full-width refurb list, popup readability), each with their own code investigation; the v0.8.15 / v0.9.1 interface fixes trace directly to it.
|
|
279
|
+
- - **[@lujfsd](https://github.com/lujfsd)** — [PR #2](https://github.com/kenz1117/dsh-engram/pull/2): adapting to the new dsh `sessionPersistence` read-handle API (`load()` was removed upstream), per-candidate scope on capture (the extraction output now carries `scope`), the project palace following the active workspace (`GET /api/engram/workspaces` plus the panel workspace picker), and renaming the no-git store key from "first 12 chars of cwd" to a full cwd sha256 (fixing collisions between sibling directories) — with 17 new tests and two design documents.
|
|
265
280
|
- **[@f0909172434](https://github.com/f0909172434)** — [PR #4](https://github.com/kenz1117/dsh-engram/pull/4): governance for ambiguous legacy database ownership — the eager rename now writes a JSON tombstone sidecar (`<old db>.migrated-to`, created exclusively with 0o600, recording `migratedTo` / `claimedByCwd` / `claimedAt`), and a later workspace hitting the same legacy name receives a warning naming the prior claim; a new `legacyMigration` config (`eager` migrates automatically by default / `conservative` leaves old databases untouched with a warning), with migration outcomes refined into `renamed` / `kept-both` / `deferred` / `already-migrated`. Ships with tests.
|
|
266
281
|
|
|
267
282
|
## License
|
package/README.md
CHANGED
|
@@ -1,5 +1,7 @@
|
|
|
1
1
|
<div align="center">
|
|
2
2
|
|
|
3
|
+
<img src="docs/screenshots/hero.jpg" width="100%" alt="dsh-engram · 记忆宫殿 — DeepSeek Harness 跨会话长期记忆插件(位置当索引 · 固定路线定顺序 · 骨架长期复用 · 标记独一无二)">
|
|
4
|
+
|
|
3
5
|
# dsh-engram · 记忆宫殿
|
|
4
6
|
|
|
5
7
|
<p align="center">DeepSeek Harness 跨会话长期记忆插件 — 把记忆宫殿的<b>信息架构</b>(而不是它的神经科学隐喻)真正落进 agent:<b>位置当索引</b>(每条记忆钉在「房间#桩位」坐标上)、<b>固定路线定顺序</b>(巡游路线只增不改)、<b>骨架长期复用</b>(同主题永远同房同序)、<b>标记独一无二</b>(门牌纪律:唯一 · 差异化 · 带日期)。配套间隔重复的检索练习(只给线索、不给正文)与知识飞轮(摄取 → 强化 → 蒸馏 → 衰减)。纯 TypeScript,零外部进程、零 Python 依赖。</p>
|
|
@@ -28,6 +30,21 @@ dsh plugin --profile web add @kenz1117/dsh-engram
|
|
|
28
30
|
|
|
29
31
|
安装后无需配置即可使用(默认分库与模型缓存在 `~/.dsh/engram`,画像注入开启,自动摄取关闭)。
|
|
30
32
|
|
|
33
|
+
## 界面速览
|
|
34
|
+
|
|
35
|
+
**今日**——记忆宫殿的仪表盘:速览 KPI、半年活动热力、入殿导航、房间目录。
|
|
36
|
+
|
|
37
|
+
<p align="center"><img src="docs/screenshots/today.png" width="820" alt="今日视图:速览 KPI、活动热力图、房间目录"></p>
|
|
38
|
+
|
|
39
|
+
**满宽翻新清单**——每条建议完整展示决策理由与记忆原文,就地阅读、就地执行(降级 / 蒸馏合并),不再挤在小卡里靠弹窗补全。
|
|
40
|
+
|
|
41
|
+
<p align="center"><img src="docs/screenshots/refurb-fullwidth.png" width="820" alt="翻新清单:满宽铺开,理由与原文完整展示,就地执行"></p>
|
|
42
|
+
|
|
43
|
+
**陈展**——全量记忆库:房间 / 状态 / 内容过滤,行内铭牌展开与取代链编辑。
|
|
44
|
+
|
|
45
|
+
<p align="center"><img src="docs/screenshots/library.png" width="820" alt="陈展视图:过滤、排序与行内详情"></p>
|
|
46
|
+
|
|
47
|
+
|
|
31
48
|
## 宫殿结构:目录即房间,路径即路线
|
|
32
49
|
|
|
33
50
|
记忆宫殿真正管用的是它的**信息架构**,不是那套生物学机制——前者机器完全能用,后者 AI 既没有也不需要。拆开看只有四件事:
|
|
@@ -182,27 +199,23 @@ dsh plugin --profile web add @kenz1117/dsh-engram
|
|
|
182
199
|
- **嵌入离线**:模型首次使用需联网下载(q8 约 50MB,端点可配镜像),此后完全离线;失败时插件照常工作,检索降级纯关键词并显式标记。
|
|
183
200
|
- **界面本地化**:client 半经宿主 locale 服务注册 zh/en 词典,跟随宿主语言设置实时切换;状态/种类等数据枚举仅在显示层映射,存储值保持英文。
|
|
184
201
|
|
|
185
|
-
## Web
|
|
202
|
+
## Web 管理面板
|
|
186
203
|
|
|
187
|
-
|
|
204
|
+
安装后在宿主**侧栏**出现「记忆宫殿」入口(v0.8 起为独立面板应用,不再寄居设置页),9 个视图覆盖记忆库的全部日常操作:
|
|
188
205
|
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
v0.7.12 起接入 **Jev 系统一裁决**(默认关闭,yml `jev` 子配置)并给面板加第八个视图**「裁决」**:DEFER 模糊带的三路判定与矛盾边确认可交 Jev 判决,Jev 不可用(网络失败/超时/未配密钥)时静默回落纯规则四态,不阻断写入。面板可覆盖 yml 的开关、密钥、端点、模型、超时五项(存 `<dbDir>/jev-config.json`,0600 文件 + 0700 目录双保护),保存即时生效——judge 每次装配即时读覆盖,无需重启;三阈值保持 yml 高级配置、面板只读展示。密钥安全:GET 响应只回掩码(长度 > 8 显尾 4 位),明文不出进程,输入框不回填。合并后开了开关但没有密钥时自动降级为关闭;覆盖文件损坏按空覆盖自愈,面板重新保存即修复。裁决 tab 另配「测试连接」按钮(填完密钥即时验证端点与模型可达性,未保存的输入按当前输入测、不落覆盖文件)与「近期裁决」卡(本进程内最近 50 条裁决:判定结果、Jev 是否参与、耗时与回落原因,重启清空),排查「为什么这条被搁置」不必再猜。
|
|
204
|
-
|
|
205
|
-
v0.7.13 修复 DSH 0.1.7(原生会话格式 v4)下的每回合失败([#5](https://github.com/kenz1117/dsh-engram/issues/5)):v4 退役了消息源的 `kind: "plugin"` 包装(只在迁移历史 v3 会话时改写为 `plugin:<包名>`,原生 v4 事件携带即被 `assertV4MessageSources` 拒收),而画像注入与 assess 提醒两处恰好用这个旧形状——启用后每个新回合都报 `format v4 message requires a producer-owned source kind`。现改为 producer-owned 形状 `plugin:<包名>`(与 DSH 自身 v3→v4 迁移产物一致,其余来源字段原样保留),内部辅助调用的消息源同步统一;三处「跳过自己注入快照」的读判断从精确等值放宽为 `plugin` 前缀匹配,v3 历史形状与 v4 新形状都识别,避免插件摄取自己注入的内容(自污染)。0.1.5(v3 会话)不受影响;0.7.12 及更早在 0.1.7 上请保持 engram 关闭,升级到 0.7.13 即可。
|
|
206
|
+
| 视图 | 内容 |
|
|
207
|
+
|---|---|
|
|
208
|
+
| **今日** | 速览 KPI(记忆 / 开放 / 清晰度 / 今日到期,各带 120 天 sparkline)+ 半年活动热力图 + 入殿导航 + **满宽翻新清单** + 房间目录 + 常驻画像 |
|
|
209
|
+
| **陈展** | 全量记忆库:按房间 / 状态 / 内容过滤,时间与巡游路线双排序,行内铭牌展开、编辑走取代链,批量遗忘 / 恢复 |
|
|
210
|
+
| **走廊** | 记忆关系图谱:平面图(建筑隐喻)/ 力导向关系图双模式,检索实验台支持 1-3 跳邻居漫游 |
|
|
211
|
+
| **回忆螺旋** | 按时间窗的螺旋布局鸟瞰,远老近新 |
|
|
212
|
+
| **往事** | episode 情景时间线:按会话分组、带 LLM 摘要组头,锚点邻近扩展回答「当时前后还发生了什么」 |
|
|
213
|
+
| **实体** | 人物 / 项目 / 工具 / 概念词典,类别与别名搜索,单实体关联记忆全貌 |
|
|
214
|
+
| **信念** | 蒸馏出的高层规律,六档证据强度 |
|
|
215
|
+
| **日志** | 双库合并的 op_log 审计流水,按操作类别筛选 |
|
|
216
|
+
| **运维** | 历史回填(估算 → 执行 → 续跑)、Jev 系统一裁决配置与近期裁决观测 |
|
|
217
|
+
|
|
218
|
+
界面语言随面板切换(中文 / English / Русский),服务端理由文案跟随面板语言。数据经回环 API `/api/engram/*`(写操作校验回环 Origin + 环绕三重防线);面板与后端进程版本不一致时顶部出现重启提醒横幅。headless 等无 webServer 的组合不挂载面板,其余能力不受影响。v0.7 时代逐版本的面板演进记录见 [docs/panel-history-v0.7.md](docs/panel-history-v0.7.md)。
|
|
206
219
|
|
|
207
220
|
## 开发
|
|
208
221
|
|
|
@@ -262,6 +275,8 @@ pnpm test
|
|
|
262
275
|
|
|
263
276
|
感谢社区贡献者让这个项目更好:
|
|
264
277
|
|
|
278
|
+
- **[@dsv180](https://github.com/dsv180)** —— 最高产的社区贡献者。[PR #13](https://github.com/kenz1117/dsh-engram/pull/13):宿主消息目录双语化(zh/en)+ 语言模式验收脚本(`check-patterns` 的骨架)。[PR #22](https://github.com/kenz1117/dsh-engram/pull/22):CI 门禁,让两道不依赖私有 peer 的检查在托管 runner 上真实执行。[PR #23](https://github.com/kenz1117/dsh-engram/pull/23):`peerDependenciesMeta` 全 peer optional——修复了 0.8.0–0.8.14 十五个版本在干净环境装不上的打包事故。另有 [PR #20](https://github.com/kenz1117/dsh-engram/pull/20)(Jev 凭据上收宿主、插件不再存密钥)与 [PR #21](https://github.com/kenz1117/dsh-engram/pull/21)(嵌入器成为部署属性 + 维度硬守卫)在评审中。每个 PR 都附双语说明、逐项验证证据与诚实的限制清单——协作范本。
|
|
279
|
+
- **[@FeiLZX3Km](https://github.com/FeiLZX3Km)** —— [Issue #19](https://github.com/kenz1117/dsh-engram/issues/19):三轮高质量 UI 反馈(侧栏图标回归单色、翻新清单满宽铺开 + 弹窗可读性),每轮都附自己的代码排查,v0.8.15 / v0.9.1 的界面修复直接源于此。
|
|
265
280
|
- **[@lujfsd](https://github.com/lujfsd)(路杰锋)** —— [PR #2](https://github.com/kenz1117/dsh-engram/pull/2):适配新版 dsh 的 `sessionPersistence` 只读句柄(新版已移除 `load()`)、摄取逐条判宫殿(提炼输出新增 `scope`)、项目宫殿随工作区切换(`GET /api/engram/workspaces` + 面板工作区选择器),并把无 git 时的分库命名从「cwd 前 12 字符」改为 cwd 全量 sha256(修掉同前缀目录撞库)。随 PR 附 17 条测试与两份设计文档。
|
|
266
281
|
- **[@f0909172434](https://github.com/f0909172434)** —— [PR #4](https://github.com/kenz1117/dsh-engram/pull/4):遗留项目库迁移的归属治理——eager 迁移改名时补写 JSON 墓碑 sidecar(`<旧库名>.migrated-to`,独占创建 + 0o600,记录 `migratedTo` / `claimedByCwd` / `claimedAt`),后续工作区撞上同一旧命名时收到指向先前归属的告警;新增 `legacyMigration` 配置(`eager` 默认自动迁移 / `conservative` 不动旧库只告警),迁移结果细化为 `renamed` / `kept-both` / `deferred` / `already-migrated` 等状态。随 PR 附测试。
|
|
267
282
|
|