@a9i5k4/dsh-auto-memory 0.1.39 β†’ 2.1.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,368 +1,478 @@
1
- # dsh-auto-memory β€” Auto Memory & Proactive Companion for DeepSeek Harness
2
-
3
- <p align="center">
4
- <a href="https://htmlpreview.github.io/?https://github.com/Aik358/dsh-auto-memory/blob/preview/docs/landing/index.html"><strong>🌐 Landing page (full feature tour · data flow · papers · screenshots)</strong></a>
5
- </p>
6
-
7
- <p align="center">
8
- <a href="docs/screenshots/promo/promo-0-banner-v2.png"><img width="820" alt="dsh-auto-memory hero: she remembers, unbidden" src="docs/screenshots/promo/promo-0-banner-v2.png"></a>
9
- </p>
10
-
11
- <p align="center">
12
- <a href="docs/screenshots/promo/promo-0-banner-v2.png"><img width="130" alt="hero" src="docs/screenshots/promo/promo-0-banner-v2.png"></a>
13
- <a href="docs/screenshots/promo/promo-2-tour.png"><img width="130" alt="welcome tour" src="docs/screenshots/promo/promo-2-tour.png"></a>
14
- <a href="docs/screenshots/promo/promo-3-recall.png"><img width="130" alt="recall & crystallization" src="docs/screenshots/promo/promo-3-recall.png"></a>
15
- <a href="docs/screenshots/promo/promo-4-unattended.png"><img width="130" alt="unattended mode" src="docs/screenshots/promo/promo-4-unattended.png"></a>
16
- <a href="docs/screenshots/promo/promo-5-external.png"><img width="130" alt="external memory inheritance" src="docs/screenshots/promo/promo-5-external.png"></a>
17
- <a href="docs/screenshots/promo/promo-6-greeting.png"><img width="130" alt="scheduled greetings" src="docs/screenshots/promo/promo-6-greeting.png"></a>
18
- </p>
19
- <p align="center"><sub>Promo gallery Β· six frames Β· click any thumbnail to view full size</sub></p>
20
-
21
- <details>
22
- <summary><b>Promo gallery, frame by frame</b> (expand and flip through)</summary>
23
-
24
- #### Frame 1 Β· Hero β€” She remembers, unbidden
25
-
26
- <p align="center"><img width="720" alt="hero" src="docs/screenshots/promo/promo-1-hero.png"></p>
27
-
28
- #### Frame 2 Β· Welcome Tour β€” Every feature, explained and toggled on the spot
29
-
30
- <p align="center"><img width="720" alt="welcome tour" src="docs/screenshots/promo/promo-2-tour.png"></p>
31
-
32
- #### Frame 3 Β· Recall & Crystallization β€” Conversation condenses into skills, traceably
33
-
34
- <p align="center"><img width="720" alt="recall" src="docs/screenshots/promo/promo-3-recall.png"></p>
35
-
36
- #### Frame 4 Β· Unattended Mode β€” Runs all night, zero small talk, zero interruptions
37
-
38
- <p align="center"><img width="720" alt="unattended" src="docs/screenshots/promo/promo-4-unattended.png"></p>
39
-
40
- #### Frame 5 Β· External Memory Inheritance β€” Your other AIs feed her memory too
41
-
42
- <p align="center"><img width="720" alt="external" src="docs/screenshots/promo/promo-5-external.png"></p>
43
-
44
- #### Frame 6 Β· Scheduled Greetings β€” Every day remembered
45
-
46
- <p align="center"><img width="720" alt="greeting" src="docs/screenshots/promo/promo-6-greeting.png"></p>
47
-
48
- </details>
49
-
50
- <p align="center">
51
- <a href="README.zh-CN.md">δΈ­ζ–‡</a> Β· <b>English</b> Β· License BSD-3-Clause Β· <code>pnpm add @a9i5k4/dsh-auto-memory</code>
52
- </p>
53
-
54
- > **v0.1.30 MAJOR UPDATE** β€” A brand-new Welcome Tour: every feature introduced step by step with per-feature switches; an Office/Fluent-style liquid-glass app icon family; a changelog intro animation; and an unattended mode built for long batch jobs.
55
-
56
- A **proactive associative-memory plugin** for the DeepSeek Harness Web GUI: memory is recalled by situation and injected into the next turn without the model ever asking for it β€” alongside three-layer auto-consolidation, AI greetings and daily reflections, calendar reminders, cross-tool memory inheritance, and production-grade unattended/batch support.
57
-
58
- **The problem it solves**: AI assistants start from zero every session, and every existing memory solution still relies on the model "remembering to look" β€” call a tool, send a request; skip it once and the memory might as well not exist. This plugin removes the instruction entirely: a host-side middleware watches the conversation context continuously, and the right memories walk toward the model on their own β€” your preferences, project conventions, yesterday's progress, next week's deadlines, plus that "welcome back" when you return.
59
-
60
- ---
61
-
62
- ## Highlights in 30 seconds
63
-
64
- | | |
65
- |---|---|
66
- | **Proactive recall, zero instructions** | Memory is never fetched by the model β€” the host watches context and recalls automatically, injected at a fixed boundary, prefix-cache friendly |
67
- | **Three-layer memory engine** | User rules β†’ project notes β†’ daily logs; injected + on-demand recall |
68
- | **Memory writes itself** | A subagent quietly evaluates every turn and files topic-grouped entries β€” you never "remember to log" |
69
- | **Every activation is auditable** | Each recall decision carries a full evidence chain, gradeable in the Recall review tab; skills crystallize from cross-session evidence |
70
- | **Proactive reminders** | The AI spots deadlines and promises in conversation, files them into the calendar and reminds you later |
71
- | **Everything is a switch** | Welcome tour + settings page, every feature individually toggleable (incl. unattended mode) |
72
- | **External memory inheritance** | Memories from WorkBuddy / CodeBuddy / Claude Code / Codex are scanned, importable, per-source managed |
73
- | **Production-grade hygiene** | Write gate (mojibake/stutter/JSON-injection blocking) + dirty-token scanner + credentials never enter prompts |
74
-
75
- ---
76
-
77
- ## Welcome Tour (new in v0.1.30)
78
-
79
- After first install or an upgrade, the plugin auto-plays a **step-by-step welcome tour** β€” not an ad popup, but the home of every feature switch:
80
-
81
- <p align="center"><img width="720" alt="welcome tour" src="docs/screenshots/tour-welcome.png"></p>
82
-
83
- - **One Office/Fluent-style liquid-glass app icon per step**: cyan inject, amber greeting, green calendar, violet engine, sky radar, coral finish β€” each with its own looping motion (bell sway, page flip, radar sweep, rising spark…)
84
- - **Flip every feature right in the tour**: switches write config instantly; no second trip to settings required
85
- - **Semantic-engine detection/download inline**: the three retrieval tiers (lexical 0GB floor β†’ built-in ~130MB β†’ advanced Python BGE-M3) are auto-detected and one-click installable (SHA256 verify + inference self-test)
86
- - **Live external-memory scan**: WorkBuddy / Claude Code / Codex sources found on your machine, tick-per-source
87
- - **No "how do I close this"**: closing mid-tour lands on a finish page telling you exactly where each feature lives in Settings
88
-
89
- <p align="center"><img width="720" alt="tour core" src="docs/screenshots/tour-core.png"></p>
90
-
91
- One-time catch-up for upgraders: from v0.1.30 every user auto-plays the full tour once after upgrading, then the changelog follows (skippable). Reopen anytime via **Settings β†’ Appearance β†’ Welcome tour β†’ β–Ά Replay**.
92
-
93
- ---
94
-
95
- ## Three-layer memory system
96
-
97
- | Layer | Location | Content |
98
- |---|---|---|
99
- | User-level memory | `~/.dsh/memory/MEMORY.md` | Cross-project rules & preferences |
100
- | Project notes | `~/.dsh/memory/workspaces/{workspace}/MEMORY.md` | Conventions & decisions |
101
- | Daily logs | `~/.dsh/memory/workspaces/{workspace}/YYYY-MM-DD.md` | Append-only work log |
102
- | Daily reflections | `…/reflections/YYYY-MM-DD.md` | Structured review (results / lessons / next) |
103
-
104
- **Injection strategy**: static discipline lives in the system prompt (byte-stable, keeps the prefix cache hot); dynamic memory rides a runtime snapshot β€” only the last day of logs plus a reflection digest are injected, everything else is fetched on demand via `memory_read` / `memory_recall`. Credential/secret sections are **always filtered out of prompts**.
105
-
106
- ---
107
-
108
- ## Feature tour
109
-
110
- ### Auto-consolidation β€” memory writes itself
111
-
112
- After every turn a small subagent quietly evaluates what happened: long-term-valuable topics are grouped into today's log (`## Topic (HH:MM)` + bullets), durable decisions are promoted to project notes, cross-project rules to user-level memory, small talk is skipped, failures queue and retry every 5 minutes (a 15-second heartbeat file proves the loop is alive). Daily write budgets with AI auto-compaction β€” going over budget never rejects a write.
113
-
114
- ### Activation & crystallization β€” interrupt only when it matters
115
-
116
- Associative recall detects memory needs directly in the conversation chain and injects at the next boundary (prefix-cache friendly); frequent workflows crystallize into skill checklists that attach automatically, promote after cross-session validation (approvals in the Memory Hub tab, 90-day auto-archive with pinning). **Every "should I interrupt" decision can be reviewed and graded** in the Recall review tab (A activate / P prefetch / S suppress / H harmful / E edit); the review queue digests into policy hints.
117
-
118
- <p align="center"><img width="720" alt="refine" src="docs/screenshots/panel-refine.png"></p>
119
-
120
- ### Unattended mode β€” built for batch jobs
121
-
122
- Running long pipelines or automated flows? Settings β†’ Automation offers **Unattended mode** and **auto-unattended overnight** (22:00-08:00, tunable). While engaged: no greetings, no niceties or behavioural directives, calendar silent, context stable β€” tokens go to the work, not the small talk.
123
-
124
- ### AI greetings & daily reflections
125
-
126
- A period-aware greeting (morning/afternoon/evening) that mentions your most important work; return after an hour away and the memory panel auto-opens with "welcome back" plus a recent-work digest; the first session of each day presents yesterday's structured reflection.
127
-
128
- ### Smart search
129
-
130
- Ask in natural language β€” the AI expands your query into keywords, scans every memory layer, and answers conversationally with sources cited; cross-workspace search included.
131
-
132
- ### Calendar β€” maintained by the AI
133
-
134
- The AI spots deadlines and promises in conversation and files them (`calendar_add`); pending items are injected into later sessions until completed; day view is a 07:00–22:00 timeline with location/reminder fields and urgency-tinted colors.
135
-
136
- ### External memory inheritance
137
-
138
- Sessions and memories from WorkBuddy / CodeBuddy / Claude Code / Codex are scanned, importable per source (**path pointers only, never copied content**), removable per source; import-side and injection-side hygiene gates keep external dirt out.
139
-
140
- ### Memory hygiene (production-grade write gate)
141
-
142
- - All three write tools run `sanitizeForWrite`: GBK mojibake (34-feature table), stutter degeneration, consecutive duplicate lines, external-AI-profile JSON signatures, base64 residue β€” rejected with a human-readable reason
143
- - Settings β†’ Debug Center "Scan dirty tokens": one-click scan of user memory / notes / logs / reflections, reported by line range (locations only, no content)
144
- - Caps: 8,000 chars per append, 200,000 per rewrite; appends deduped against the last ~60 lines
145
-
146
- ---
147
-
148
- ## Engineering core (restraint by design)
149
-
150
- - **Zero runtime dependencies** beyond Node built-ins
151
- - **Prefix-cache friendly**: byte-stable prompts keep DeepSeek's prefix cache hitting β€” your history is never re-encoded
152
- - **Rate-limited AI**: auto-consolidation ≀8Γ—/day with cooldown; useful memory without burning budget
153
- - **Centralized storage**: all workspace memory under one root (`~/.dsh/memory/workspaces/`), readable from any session
154
- - **30-day distillation**: old logs are AI-distilled into project notes; originals archived, nothing lost
155
-
156
- ---
157
-
158
- ## UI gallery
159
-
160
- ### Memory panel Β· Overview (away greeting + AI period summaries)
161
-
162
- <img width="480" alt="overview" src="docs/screenshots/panel-overview.png">
163
-
164
- ### Memory Hub Β· three stores + skill promotion approvals
165
-
166
- <img width="480" alt="hub" src="docs/screenshots/panel-hub.png">
167
-
168
- ### Recall review Β· grade every activation decision
169
-
170
- <img width="720" alt="refine" src="docs/screenshots/panel-refine.png">
171
-
172
- ### Welcome tour Β· feature switches + engine detection
173
-
174
- <img width="720" alt="tour" src="docs/screenshots/tour-toggles.png">
175
-
176
- <details>
177
- <summary><b>More screenshots</b> (click to expand)</summary>
178
-
179
- ### External memory scan (inside the tour)
180
-
181
- <img width="720" alt="external scan" src="docs/screenshots/tour-external.png">
182
-
183
- ### Connect other AI tools
184
-
185
- <img width="480" alt="connect" src="docs/screenshots/connect-en.png">
186
-
187
- ### Calendar view
188
-
189
- <img width="480" alt="calendar" src="docs/screenshots/calendar-zh.png">
190
-
191
- ### Workspace mind map
192
-
193
- <img width="480" alt="workspace map" src="docs/screenshots/workspace-map-zh.png">
194
-
195
- ### Settings
196
-
197
- <img width="480" alt="settings" src="docs/screenshots/settings-en.png">
198
- <img width="480" alt="settings 2" src="docs/screenshots/settings-2-zh.png">
199
-
200
- </details>
201
-
202
- ---
203
-
204
- ## Install (one command)
205
-
206
- > Prerequisite: install [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) and start `dsh web` at least once.
207
-
208
- Run in the **profile directory** (`~/.dsh/profiles/web`):
209
-
210
- ```bash
211
- cd ~/.dsh/profiles/web
212
- pnpm add @a9i5k4/dsh-auto-memory
213
- ```
214
-
215
- Then edit `package.json` in that directory and append to the `dsh.profile.bundles` array:
216
-
217
- ```json
218
- "@a9i5k4/dsh-auto-memory"
219
- ```
220
-
221
- Restart **dsh web** (the γ€ŒMemory」entry appears in the sidebar).
222
-
223
- ### Semantic engine (optional but recommended)
224
-
225
- The built-in JS semantic tier (e5-small q8, ~130MB) needs the `@huggingface/transformers` inference library, installed automatically as an optional dependency of the main package. If your pnpm security policy blocked its native scripts (you see `ERR_PNPM_IGNORED_BUILDS` / `Ignored build scripts: onnxruntime-node, sharp`), approve and reinstall once:
226
-
227
- ```bash
228
- # approve the onnxruntime-node / sharp native install scripts, then reinstall transformers
229
- pnpm approve-builds
230
- pnpm add @huggingface/transformers
231
- ```
232
-
233
- Restart `dsh web` β€” the welcome tour's semantic-engine step auto-detects readiness (SHA256 verify + inference self-test). Lexical BM25 (0GB) always works as a fallback; skipping the engine only lowers recall precision.
234
-
235
- > No pnpm? `npm install @a9i5k4/dsh-auto-memory` works the same.
236
- > pnpm v11 blocks packages published <1 day ago: set `minimumReleaseAge: 0` in pnpm-workspace.yaml or pin an explicit version for same-day updates.
237
-
238
- ### AI-era installation
239
-
240
- Copy this to the AI assistant you're already using:
241
-
242
- ```text
243
- Install the npm package @a9i5k4/dsh-auto-memory in the DeepSeek Harness web profile
244
- directory ~/.dsh/profiles/web (pnpm add or npm install),
245
- append "@a9i5k4/dsh-auto-memory" to the dsh.profile.bundles array in package.json,
246
- then restart dsh web to activate the plugin.
247
- ```
248
-
249
- ### Updating
250
-
251
- ```bash
252
- cd ~/.dsh/profiles/web && pnpm up @a9i5k4/dsh-auto-memory
253
- ```
254
-
255
- The Settings β†’ Auto Memory page has a "Check for updates" button comparing your version with the npm registry; registry installs get a one-click update.
256
-
257
- ---
258
-
259
- ## Configuration
260
-
261
- Config file `~/.dsh/dsh-auto-memory.json` (everything adjustable in the Settings GUI, zh/en UI and panel font size included):
262
-
263
- ```json
264
- {
265
- "userMemoryDir": "~/.dsh/memory",
266
- "memoryRoot": "~/.dsh/memory/workspaces",
267
- "injectEnabled": true,
268
- "injectBudgetChars": 2400,
269
- "recentDaysInjected": 1,
270
- "reflectEnabled": true,
271
- "autoConsolidate": true,
272
- "autoConsolidateCooldownMinutes": 30,
273
- "autoConsolidateDailyMax": 8,
274
- "unattendedMode": false,
275
- "unattendedAuto": false,
276
- "unattendedAutoHours": ["22:00-08:00"],
277
- "memoryHubEnabled": true,
278
- "externalSources": { "workbuddy-user": true, "claude-global": true },
279
- "dayBoundaryMinutes": 450
280
- }
281
- ```
282
-
283
- > Full key reference lives in the Settings page β€” every switch has a description, and every welcome-tour switch maps 1:1 to settings.
284
-
285
- ---
286
-
287
- ## Structure
288
-
289
- - `lib/index.js` β€” Host half: engine, injection, tools, routes (zero runtime deps, Node built-ins only)
290
- - `lib/client.js` β€” Browser half: memory panel (calendar / mind map) + settings page + welcome tour (zh/en i18n)
291
- - `python/` β€” optional Python semantic sidecar (BGE-M3 int8, advanced tier)
292
- - `cordis.patch.yml` β€” plugin registration row
293
-
294
- ## Architecture
295
-
296
- All milestones are implemented and live-verified. The full interactive architecture map lives at [docs/proactive-associative-memory-system-map.html](docs/proactive-associative-memory-system-map.html); the core layering:
297
-
298
- ```
299
- DeepSeek Harness (Node, 127.0.0.1:3080)
300
- β”œβ”€ JS memory core (lib/*_pre.js, zero runtime deps)
301
- β”‚ M1 session isolation Β· M2 ContextObserver projection
302
- β”‚ M3 memory anchoring (anchored records + sidecar identity)
303
- β”‚ M4 corpus adapter + shadow retrieval host (evidence store)
304
- β”‚ M5 context/evidence bridge (envelope Β· coverage Β· cite/correction)
305
- │ M6 activation inbox (validate→offer→claim→reference tail→delivered/seen)
306
- β”‚ lexical_pre_v2 lexical fallback retrieval (BM25 + CJK 2gram, 0GB always-on)
307
- β”‚ C2 built-in semantic tier (e5-small q8 ~130MB, default)
308
- └─ Python sidecar M7 (optional, lazy-spawned child process)
309
- worker_semantic_pre_v1.py
310
- β”œβ”€ index_sync: JS-authorized paged index build (digest checks, scope grouping)
311
- β”œβ”€ dense: BGE-M3 int8 + para-512 chunks + cosine (R@5 0.925)
312
- β”œβ”€ hybrid: dense 0.7 + lexical 0.3 fusion
313
- └─ fv2 activation policy: two lanes + hard gates (echo/correction/stale/scope)
314
- ```
315
-
316
- **Separation of powers**: the Python semantic layer decides *what to recall and when to suggest*; the JS authority layer decides identity, authorization, timing, and delivery β€” Python never creates evidence nor injects directly. Data flow: `context_push β†’ M5 envelope β†’ decision β†’ M6 fixed-boundary injection β†’ delivered/seen evidence back`.
317
-
318
- ### Design papers
319
-
320
- The design is not guesswork β€” every algorithmic conclusion comes from reproducible experiments, frozen into an engineering decision ledger:
321
-
322
- | Paper | Content |
323
- |---|---|
324
- | [Multilingual Embedding Retrieval Study](docs/M7-RESEARCH-PAPER.md) | 3 models Γ— 5 chunkings Γ— 6 retrieval channels β‰ˆ 90 evaluation cells; BGE-M3 leads across the board, frozen as decisions D1–D11 |
325
- | [Activation v2: The Echo Trap](docs/M7-ACTIVATION-V2-PAPER.md) | Why semantic relevance β‰  recall necessity β€” activation policy technical report + dual-track deployment architecture (Β§7) |
326
- | [Embedding Benchmark Report](docs/M7-EMBEDDING-BENCHMARK.md) | Frozen basis for model/chunk/fusion: bge-m3 + para-512-noov + weighted fusion |
327
- | [Frozen Algorithm Decisions D1–D11](docs/M7-ALGORITHM-DECISION.md) | The decision ledger from research conclusions to production implementation |
328
- | [Held-out Human-Gold Acceptance](docs/M7-ACTIVATION-V2-HOLDEDOUT-EVAL.md) | 67 human-labeled verdicts: actPrecision 0.917 / harmful injections 0 / echo tier 7/7 |
329
- | [Python Sidecar Contract](docs/PYTHON-SIDECAR-CONTRACT.md) | Protocol / lifecycle / authority boundary / per-milestone regression evidence |
330
-
331
- Papers were authored by the autonomous engineering agent (ZCode / GLM); all conclusions were frozen into the production implementation under human review.
332
-
333
- ## Known limitations
334
-
335
- - Memory files are plain-text Markdown; no secrets stored unless explicitly requested.
336
- - `memory_recall` session search depends on the deployed session-query index; without it, only local search works.
337
- - Plugin-set changes require a dsh restart.
338
-
339
- ---
340
-
341
- ## Community
342
-
343
- **Feedback & chat:** join the community QQ group β€” [Join the dsh-auto-memory group](https://qm.qq.com/q/v7Asxn6vPa) β€” for bug reports, usage tips, and quick responses faster than GitHub issues.
344
-
345
- Community contributors:
346
-
347
- - [@ProperSAMA](https://github.com/ProperSAMA) β€” panel readability fix for DSH Desktop enhanced mode (transparent/Mica materials) + entry-button anti-occlusion & outside-click/Esc close ([PR #12](https://github.com/Aik358/dsh-auto-memory/pull/12))
348
- - [@nkh0472](https://github.com/nkh0472) β€” unattended/batch workflow hardening feedback that drove the welcome tour and per-feature switches ([Issue #10](https://github.com/Aik358/dsh-auto-memory/issues/10))
349
-
350
- ---
351
-
352
- ## Credits
353
-
354
- This project is built human-machine collaboratively. In addition to engineering and community contributions above:
355
-
356
- - **Aik358** β€” project owner: product direction, architecture, and engineering.
357
- - **ZCode (GLM, Z.ai)** β€” autonomous engineering agent: M-series semantic-engine implementation, benchmark research papers ([M7-RESEARCH-PAPER](docs/M7-RESEARCH-PAPER.md) / [Activation v2 report](docs/M7-ACTIVATION-V2-PAPER.md)), regression suites, and the landing-page design/build.
358
- - **Kimi K3 (Moonshot AI)** β€” frontend agent: contributed to the v0.1.30 welcome-tour interface assets and visual QA.
359
-
360
- AI agents are credited as authors of the research papers and parts of the implementation, under human review and direction.
361
-
362
- ---
363
-
364
- ## Release
365
-
366
- - GitHub: https://github.com/Aik358/dsh-auto-memory
367
- - npm: `@a9i5k4/dsh-auto-memory`
368
- - License: BSD-3-Clause
1
+ # dsh-auto-memory β€” She remembers, unbidden
2
+
3
+ > **Now, across windows, too.**
4
+ > Context that survives windows, sessions, and tools
5
+
6
+ <p align="center">
7
+ <a href="https://htmlpreview.github.io/?https://github.com/Aik358/dsh-auto-memory/blob/preview/docs/landing/index.html"><strong>🌐 Landing page (full feature tour · data flow · papers · screenshots)</strong></a>
8
+ </p>
9
+
10
+ <p align="center">
11
+ <a href="docs/screenshots/promo/promo-0-banner-v2.png"><img width="820" alt="dsh-auto-memory hero: she remembers, unbidden" src="docs/screenshots/promo/promo-0-banner-v2.png"></a>
12
+ </p>
13
+
14
+ <p align="center">
15
+ <a href="docs/screenshots/promo/promo-0-banner-v2.png"><img width="130" alt="hero" src="docs/screenshots/promo/promo-0-banner-v2.png"></a>
16
+ <a href="docs/screenshots/promo/promo-2-tour.png"><img width="130" alt="welcome tour" src="docs/screenshots/promo/promo-2-tour.png"></a>
17
+ <a href="docs/screenshots/promo/promo-3-recall.png"><img width="130" alt="recall & crystallization" src="docs/screenshots/promo/promo-3-recall.png"></a>
18
+ <a href="docs/screenshots/promo/promo-4-unattended.png"><img width="130" alt="unattended mode" src="docs/screenshots/promo/promo-4-unattended.png"></a>
19
+ <a href="docs/screenshots/promo/promo-5-external.png"><img width="130" alt="external memory inheritance" src="docs/screenshots/promo/promo-5-external.png"></a>
20
+ <a href="docs/screenshots/promo/promo-6-greeting.png"><img width="130" alt="scheduled greetings" src="docs/screenshots/promo/promo-6-greeting.png"></a>
21
+ </p>
22
+ <p align="center"><sub>Promo gallery Β· six frames Β· click any thumbnail to view full size</sub></p>
23
+
24
+ <details>
25
+ <summary><b>Promo gallery, frame by frame</b> (expand and flip through)</summary>
26
+
27
+ #### Frame 1 Β· Hero β€” She remembers, unbidden
28
+
29
+ <p align="center"><img width="720" alt="hero" src="docs/screenshots/promo/promo-1-hero.png"></p>
30
+
31
+ #### Frame 2 Β· Welcome Tour β€” Every feature, explained and toggled on the spot
32
+
33
+ <p align="center"><img width="720" alt="welcome tour" src="docs/screenshots/promo/promo-2-tour.png"></p>
34
+
35
+ #### Frame 3 Β· Recall & Crystallization β€” Conversation condenses into skills, traceably
36
+
37
+ <p align="center"><img width="720" alt="recall" src="docs/screenshots/promo/promo-3-recall.png"></p>
38
+
39
+ #### Frame 4 Β· Unattended Mode β€” Runs all night, zero small talk, zero interruptions
40
+
41
+ <p align="center"><img width="720" alt="unattended" src="docs/screenshots/promo/promo-4-unattended.png"></p>
42
+
43
+ #### Frame 5 Β· External Memory Inheritance β€” Your other AIs feed her memory too
44
+
45
+ <p align="center"><img width="720" alt="external" src="docs/screenshots/promo/promo-5-external.png"></p>
46
+
47
+ #### Frame 6 Β· Scheduled Greetings β€” Every day remembered
48
+
49
+ <p align="center"><img width="720" alt="greeting" src="docs/screenshots/promo/promo-6-greeting.png"></p>
50
+
51
+ </details>
52
+
53
+ <p align="center">
54
+ <a href="README.zh-CN.md">δΈ­ζ–‡</a> Β· <b>English</b> Β· License BSD-3-Clause Β· <code>pnpm add @a9i5k4/dsh-auto-memory</code> Β· <a href="https://qm.qq.com/q/v7Asxn6vPa">QQ group</a>
55
+ </p>
56
+
57
+ ---
58
+
59
+ ## The burned book keeps no book report
60
+
61
+ Everyone who does real work with AI knows the moment: halfway through, the context window fills, and she "forgets". Not for lack of intelligence β€” her thinking was compressed into a summary, like burning a whole book and keeping one line of book report. Why that fix failed, why that path dead-ended β€” all in the fire.
62
+
63
+ dsh-auto-memory never believed it had to be this way. She keeps memory outside the window: what should resurface, resurfaces unbidden; and everything she recalls has provenance β€” checkable, editable, deletable.
64
+
65
+ Now we push this route to its last missing piece β€” when the context fills, she no longer compresses herself. She **closes a notebook filled with margin notes and opens a new page**. The notebook stays within reach.
66
+
67
+ **Compression distorts, closed windows reset, tool switches zero out β€” starting from here, none of that holds.**
68
+
69
+ ---
70
+
71
+ ## Highlights in 30 seconds
72
+
73
+ | | |
74
+ |---|---|
75
+ | **Proactive recall, zero instructions** | Memory is never fetched by the model β€” the host watches context and recalls automatically, injected at a fixed boundary, prefix-cache friendly |
76
+ | **Three-layer memory engine** | User rules β†’ project notes β†’ daily logs; injected + on-demand recall |
77
+ | **Memory writes itself** | A subagent quietly evaluates every turn and files topic-grouped entries β€” you never "remember to log" |
78
+ | **Every activation is auditable** | Each recall decision carries a full evidence chain, gradeable in the Recall review tab; skills crystallize from cross-session evidence |
79
+ | **Proactive reminders** | The AI spots deadlines and promises in conversation, files them into the calendar and reminds you later |
80
+ | **Everything is a switch** | Welcome tour + settings page, every feature individually toggleable (incl. unattended mode) |
81
+ | **External memory inheritance** | Memories from WorkBuddy / CodeBuddy / Claude Code / Codex are scanned, importable, per-source managed |
82
+ | **Production-grade hygiene** | Write gate (mojibake/stutter/JSON-injection blocking) + dirty-token scanner + credentials never enter prompts |
83
+ | **Astra-style context management (experimental)** | A filling context no longer collapses into one summary β€” four-part handoff notes carry work across windows, full history stays searchable, the agent retrieves on demand (off by default; enable in Settings β†’ Automation) |
84
+ | **Model-agnostic** | No vendor lock, no tier lock: any model on DSH works out of the box β€” lexical 0GB floor, built-in ~130MB semantic tier, advanced 563MB |
85
+ | **Portable memory** | Everything lives on your own disk; memories scan in from other AI tools, every entry has an evidence chain β€” auditable, deletable. Memory belongs to you, not to any vendor |
86
+
87
+ ---
88
+
89
+ ## Four things we poured our heart into
90
+
91
+ Four features in this plugin were raised one by one, by hand; everything else β€” calendar, search, the mind map, unattended mode, memory hygiene β€” grows around them.
92
+
93
+ ### The first Β· She takes notes, and she says welcome back
94
+
95
+ The earliest version of this plugin learned two small things: after every conversation, it wrote down what was worth keeping, unprompted; and when you returned from time away, or in the morning, afternoon, and late-night hours, it greeted you in a fitting tone. Simple β€” but these two acts set her character: memory is not a database, a greeting is not a notification chime; it is what a colleague who remembers you says when you walk back in. Everything else grew on that character. We call this plugin "she" throughout β€” not marketing polish, but because from the very first feature, she was doing the things a person does.
96
+
97
+ ### The second Β· Not "look it up when I remember", but remembering while doing
98
+
99
+ Humans use memory two ways: deliberately retracing what was done before β€” and, far more often, having the right memory surface on its own in the middle of doing. The last major release gave her the second kind. We put a Transformers model next to the memory stores so that, mid-conversation, she judges two things: whether anything is worth recalling right now, and which memory it should be β€” judging from the very material of the dialogue: what you're thinking, what you said, what she answered. The relevant memory thus walks into place, through a fixed boundary into the next turn, before the model even opens its mouth. It never depends on the model "remembering to look" β€” forget once, and the memory might as well not exist. **She remembers to think for you.**
100
+
101
+ ### The third Β· Like riding a bicycle β€” no need to think about how
102
+
103
+ Once a person learns to ride, they never replay the tutorial β€” muscle memory takes over, and the skill transfers to the next road on its own. She grows that kind of memory too: after watching your corrections a few times, or doing the same kind of thing again and again, a workflow crystallizes into a skill; next time something similar shows up, the checklist attaches itself β€” no one reminding. What was learned deliberately becomes something done casually β€” her procedural memory, the part you can review, pin, and watch grow in the Memory Hub tab.
104
+
105
+ ### The fourth Β· Handoff, not compression (in progress)
106
+
107
+ When the context fills, she no longer burns the whole book for a one-line summary; she writes a four-part handoff note β€” state, goals, dead ends and why, progress and next step β€” closes this window, and opens the next. The full history stays archived and searchable; details can always be looked back up. The newest of the four, and the last piece of a complete memory β€” see [How she hands off](#how-she-hands-off-next-major--coming-soon).
108
+
109
+ ---
110
+
111
+ ## Why a plugin
112
+
113
+ In September 2026, GPT-6 Astra shipped Context Management as an experimental flagship feature: notes kept across context windows, earlier history searchable, handoff preferred over compression as the window fills.
114
+
115
+ Seeing the announcement, we were quietly glad β€” like someone walking a night road alone who sees a light come on in the distance. Putting memory outside the window: structured notes, searchable archives, handoff over compression β€” it turns out we are not the only traveler on this road. That a flagship is willing to press the experimental button for it says this idea deserves to be taken seriously by more people.
116
+
117
+ So we built it as an open plugin: no experimental gate, no subscription tier β€” install it in DSH, and every model on your machine gets its own.
118
+
119
+ | | GPT-6 Astra / Codex experimental feature | dsh-auto-memory |
120
+ |---|---|---|
121
+ | Availability | Single-vendor flagship, experimental | Open plugin, any DSH model, install and go |
122
+ | Notes | Keep notes across windows | Four-part handoff ledger, directly readable and editable by you |
123
+ | Archive | Earlier windows searchable | Local full archive + lexical/semantic dual-channel retrieval |
124
+ | Retrieval | history/_context tools | memory_search / memory_note gated-agent tools |
125
+ | Trigger | Token budget + handoff | Water-level awareness + pre-completion interception |
126
+ | Ownership | Vendor side | All on the user's disk, governance-style writes, auditable |
127
+ | Tiers | Bound to subscription plans | 0GB lexical β†’ 130MB built-in semantic β†’ 563MB Python advanced |
128
+
129
+ **One route, two arrivals: it ships with a flagship; ours walks into your machine as a plugin.**
130
+
131
+ *Handoff is experimental and off by default in this release β€” enable via Settings β†’ Automation β†’ Handoff whiteboard (see [How she hands off](#how-she-hands-off-experimental--off-by-default)).*
132
+
133
+ ---
134
+
135
+ ## One week
136
+
137
+ Monday, you hand her a research task and shut the laptop halfway through.
138
+
139
+ Wednesday, you're on a different machine and have switched the default model while you were at it. What she picks up is not "sorry, I don't remember" β€” it's last week's progress, three dead ends already tried, and the next step. The handoff note is there, the raw record is searchable, and the memory travels with you.
140
+
141
+ Friday, you ask casually: "Why do you remember this?" She shows you: which message, which tool output, which late-night reflection it came from. You can have her hold onto it tighter β€” or let it go.
142
+
143
+ **She remembers, unbidden. And if you want her to forget β€” that's one sentence too.**
144
+
145
+ > Handoff-related scenes require Settings β†’ Automation β†’ Handoff whiteboard (experimental).
146
+
147
+ ---
148
+
149
+ ## How she remembers
150
+
151
+ Memory comes in four layers, each minding its own shelf:
152
+
153
+ | Layer | Location | Content |
154
+ |---|---|---|
155
+ | User-level memory | `~/.dsh/memory/MEMORY.md` | Cross-project rules & preferences |
156
+ | Project notes | `~/.dsh/memory/workspaces/{workspace}/MEMORY.md` | Conventions & decisions |
157
+ | Daily logs | `~/.dsh/memory/workspaces/{workspace}/YYYY-MM-DD.md` | Append-only work log |
158
+ | Daily reflections | `…/reflections/YYYY-MM-DD.md` | Structured review (results / lessons / next) |
159
+
160
+ Static discipline lives in the system prompt β€” byte-stable, keeps the prefix cache hot, never re-encodes history; dynamic memory rides a runtime snapshot β€” only the last day of logs plus a reflection digest are injected, everything else fetched on demand via `memory_read` / `memory_recall`. **Credential/secret sections are always filtered out of prompts.**
161
+
162
+ **Memory writes itself.** After every turn a small subagent quietly makes one judgment β€” what's worth keeping: long-term-valuable topics are grouped into today's log (`## Topic (HH:MM)` + bullets), durable decisions are promoted to project notes, cross-project rules to user-level memory, small talk skipped. Failures don't panic β€” they queue and retry every 5 minutes, with a 15-second heartbeat file proving the loop is alive. Daily writes have a budget; over budget, the AI merges and dedupes before writing β€” she remembers restraint, and she remembers not to lose things.
163
+
164
+ Then, periodically, she looks back: `memory_consolidate` reads recent logs and distills what deserves long-term promotion into project notes β€” auto-consolidation handles "log the flow each turn"; this handles "after a while, what's worth keeping".
165
+
166
+ ---
167
+
168
+ ## How she recalls
169
+
170
+ **Never depends on the model "remembering to look".** Existing memory solutions either rely on the model calling a retrieval tool, or on you pasting context by hand β€” skip it once, and the memory might as well not exist. This is host-side associative middleware: while the conversation runs, she watches context and runtime events continuously, and the relevant memories are retrieved, decided, and injected into the next turn before the model opens its mouth. Sent requests can't be rewritten, so injection runs at a fixed boundary β€” **the prefix cache never goes cold, and tokens never pay twice for a memory.** Her judging material is the dialogue itself: what you're thinking, what you said, what she answered; whether to recall, and what to recall, is decided live by the semantic model β€” not "look it up when I remember", but remembering while doing.
171
+
172
+ Powers are separated too: what to recall belongs to the semantic decision layer; whether and when belongs to the identity/authorization/timing governance layer β€” every delivery carries an evidence chain. Every page she hands over has also passed inspection: injected content is neutralized for template variables at every exit β€” a plain `{{baseUrl}}` in a log can no longer brick an entire turn.
173
+
174
+ Ask, and she answers: natural-language questions get expanded into keywords, every memory layer is scanned, and the reply is conversational with sources cited. `memory_recall` is cross-workspace by nature β€” other projects' logs, notes, and conclusions are one sentence away.
175
+
176
+ The panel's Workspace tab draws all of this as a mind map: workspaces at the center, memory topics as branches, dashed lines for cross-workspace shares; draggable, zoomable, click a card for details. **Your memory has a shape for the first time.**
177
+
178
+ ---
179
+
180
+ ## How she reminds
181
+
182
+ **The calendar maintains itself β€” she does the paperwork.** Deadlines and promises spotted in conversation are filed automatically (`calendar_add`); **pending items keep being injected into later sessions until completed** β€” no agreement gets lost in the depths of some chat log. The day view is a 07:00–22:00 timeline with location, reminders, and urgency-tinted colors; `calendar_list` / `calendar_done` / `calendar_remove` let her report, check off, and withdraw.
183
+
184
+ Period-aware greetings: morning, afternoon, late night β€” each one mentions the most important work of your day. Not template small talk; a greeting from someone who read your log.
185
+
186
+ Return after more than an hour away and the memory panel opens itself β€” a "welcome back", plus the digest of what you should know. Don't like being greeted? One switch β€” "Auto-open memory panel" β€” turns it off.
187
+
188
+ ---
189
+
190
+ ## How she grows
191
+
192
+ **Distillation: trading process logs for reusable conclusions.** Daily logs older than 30 days are read through, and only what carries cross-session value is distilled β€” technical decisions, architecture conventions, preferences, hard-won pitfalls β€” into project notes; originals are archived as a floor, degrading to verbatim archiving if the AI is unavailable β€” **not a single character lost**. The recall boundary is just as clear: skills, user-level and project notes are never distilled β€” only date-named logs go through, and the untouchable stays untouched.
193
+
194
+ **Skills: like riding a bicycle β€” no need to think about how.** After learning to ride, a person never replays the tutorial β€” muscle memory takes over. She grows that too: after watching your corrections a few times, or repeating similar work, a workflow crystallizes into a skill; next time something similar appears, the checklist attaches itself. Injection comes in three grades β€” full steps / excerpt / hint β€” with high-risk scenarios auto-downgraded to a hint, never in the way. Skills promote gradually on cross-session evidence, approved in the Memory Hub tab; 90 days unused and they auto-archive, important ones can be pinned, frequently used ones stay gently warm.
195
+
196
+ **Reflections: before closing the books each day, she writes her own review.** Results, lessons, next steps β€” in a reflection layer of their own; the first session of the next day presents yesterday's review. From Monday on, your project has someone who remembers everything yesterday said.
197
+
198
+ ---
199
+
200
+ ## How she hands off (experimental Β· off by default)
201
+
202
+ > **Experimental**: these capabilities ship in 2.1 but are disabled by default β€” enable via Settings β†’ Automation β†’ Handoff whiteboard. The window auto-follows the active model (settings.yaml contextWindow, e.g. 1M), or set it manually.
203
+
204
+ When the context fills, she no longer burns the whole book for a one-line summary; she writes a **four-part handoff note** β€” task state, goals, approaches tried and why they failed, progress and next step β€” closes this window, and opens the next. What didn't fit in the notes is safe too: the full history of messages and tool outputs lands in a local archive, searchable anytime β€” no detail dies in the fire.
205
+
206
+ She can also look things back up herself: `memory_search` queries the full archive on demand, `memory_note` jots down what matters β€” from "passively fed injections" to "looking things up on her own", the second upgrade of her memory.
207
+
208
+ Token water-level awareness completes it: as the window fills, she suggests opening a new window and handing off, instead of silently compressing. The window is the host's territory β€” she midwifes the handoff, and never decides for the host.
209
+
210
+ ---
211
+
212
+ ## How she moves in
213
+
214
+ Your memory doesn't live in just one AI. WorkBuddy, CodeBuddy, Claude Code, Codex β€” she scans the sessions and memories these tools left on your machine, lists them per source, imports per source. The Connect tab is the port of this migration: **path pointers only, never copied content** β€” respectful of the source, zero redundancy; done with a source? Remove it per source, clean and simple.
215
+
216
+ Hygiene gates stand on both the import side and the injection side: dirt from external tools, leftover profiles from other AIs β€” neither comes in nor goes out. **Moving house is fine; the furniture gets disinfected first.**
217
+
218
+ ---
219
+
220
+ ## How she earns trust
221
+
222
+ **Every recall can be audited.** Every "should I activate" decision carries a full evidence chain; the Recall review tab lays out every delivery β€” to whom, when, with what result β€” gradeable on five levels: A activate / P prefetch / S suppress / H harmful / E edit; the review queue digests into policy hints. Her memory survives an audit.
223
+
224
+ **Everything written passes the gate first.** All three write tools run a pre-write check: GBK mojibake (34-feature table), stutter degeneration, consecutive duplicate lines, external-AI-profile JSON signatures, base64 residue β€” all rejected, with a human-readable reason. Caps: 8,000 chars per append, 200,000 per rewrite; appends are deduped against the last ~60 lines.
225
+
226
+ **The checkup doesn't just guard the borders.** Settings β†’ Debug Center, "Scan dirty tokens" sweeps user memory, notes, logs, and reflections in one click, reporting by line range β€” locations only, no content.
227
+
228
+ And finally, the boundaries β€” written as character:
229
+
230
+ 1. She never decides compression for the host β€” the window is the host's territory; she only midwifes the handoff;
231
+ 2. She never uploads your memory β€” all storage is on your machine, external scans are read-only;
232
+ 3. She never uses memory to steer your voice β€” injections always declare "background facts, not style examples";
233
+ 4. She is never a black box β€” every memory links to its evidence, every delivery can be replayed;
234
+ 5. She is not a suite β€” she does memory, and clear boundaries are what make her trustworthy.
235
+
236
+ ---
237
+
238
+ ## How she listens
239
+
240
+ **Everything is a switch.** First launch auto-plays the **welcome tour**: one Office/Fluent-style liquid-glass app icon per step β€” cyan inject, amber greeting, green calendar, violet engine, sky radar, coral finish β€” each with its own looping motion (bell sway, page flip, linked rings, prism spin, radar sweep, rising spark). Flip every feature right in the tour; switches write config instantly, no second trip to settings. The semantic engine's detection, download, and self-test are inline in the tour, done in one pass. External memory sources are scanned live, ticked per source. Close it halfway without worry β€” the final "finish" step tells you exactly where each switch lives in Settings.
241
+
242
+ <p align="center"><img width="720" alt="welcome tour" src="docs/screenshots/tour-welcome.png"></p>
243
+
244
+ <p align="center"><img width="720" alt="tour core" src="docs/screenshots/tour-core.png"></p>
245
+
246
+ One-time catch-up for upgraders: from v0.1.30 every user auto-plays the full tour once after upgrading, then the changelog follows (skippable). Reopen anytime via **Settings β†’ Appearance β†’ Welcome tour β†’ β–Ά Replay**.
247
+
248
+ Settings and the tour are twin entrances, mapped one-to-one: proactive recall, periodic snapshots, away greetings, night unattended, daily reflection, scheduled digests, external memory, skill crystallization, auto-open… every switch carries a description, the UI switches between Chinese and English, and the panel font size is adjustable.
249
+
250
+ Ten tabs, each minding its own post: **Workspace** (mind map), **Calendar**, **Connect** (external memory), **Memory Hub** (skill approvals), **Logs**, **Notes**, **Reflections**, **Recall review** (the audit), **Search**, **Storage**. The panel is considerate too: in DSH Desktop enhanced mode (transparent/Mica materials) it keeps its readability; the default position never covers the sidebar "Memory" entry; click outside or press Esc and it's gone β€” present, but never in the way.
251
+
252
+ **Long batch jobs? Go unattended.** Settings β†’ Automation offers **Unattended mode** and **auto-unattended overnight** (22:00–08:00, tunable): while engaged, no greetings, no niceties or behavioural directives, calendar silent β€” the model focuses on the work, and tokens go to the work too.
253
+
254
+ **Upgrades with dignity.** The Settings "Check for updates" button compares against the npm registry, and registry installs get one-click updates; major-version changelogs open with a glass-logo animation β€” three slabs assembling, expanding, dissolving β€” click anywhere to skip.
255
+
256
+ ---
257
+
258
+ ## Install (one command)
259
+
260
+ > Prerequisite: install [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) and start `dsh web` at least once.
261
+
262
+ Run in the **profile directory** (`~/.dsh/profiles/web`):
263
+
264
+ ```bash
265
+ cd ~/.dsh/profiles/web
266
+ pnpm add @a9i5k4/dsh-auto-memory
267
+ ```
268
+
269
+ Then edit `package.json` in that directory and append to the `dsh.profile.bundles` array:
270
+
271
+ ```json
272
+ "@a9i5k4/dsh-auto-memory"
273
+ ```
274
+
275
+ Restart **dsh web** (the γ€ŒMemory」entry appears in the sidebar).
276
+
277
+ > No pnpm? `npm install @a9i5k4/dsh-auto-memory` works the same.
278
+ > pnpm v11 blocks packages published <1 day ago: set `minimumReleaseAge: 0` in pnpm-workspace.yaml or pin an explicit version for same-day updates.
279
+
280
+ ### Semantic engine (optional but recommended)
281
+
282
+ The built-in JS semantic tier (e5-small q8, ~130MB) needs the `@huggingface/transformers` inference library, installed automatically as an optional dependency of the main package. If your pnpm security policy blocked its native scripts (you see `ERR_PNPM_IGNORED_BUILDS` / `Ignored build scripts: onnxruntime-node, sharp`), approve and reinstall once:
283
+
284
+ ```bash
285
+ # approve the onnxruntime-node / sharp native install scripts, then reinstall transformers
286
+ pnpm approve-builds
287
+ pnpm add @huggingface/transformers
288
+ ```
289
+
290
+ Restart `dsh web` β€” the welcome tour's semantic-engine step auto-detects readiness (SHA256 verify + inference self-test). Lexical retrieval (0GB) always works as a fallback; skipping the engine only lowers recall precision.
291
+
292
+ ### AI-era installation
293
+
294
+ Copy this to the AI assistant you're already using:
295
+
296
+ ```text
297
+ Install the npm package @a9i5k4/dsh-auto-memory in the DeepSeek Harness web profile
298
+ directory ~/.dsh/profiles/web (pnpm add or npm install),
299
+ append "@a9i5k4/dsh-auto-memory" to the dsh.profile.bundles array in package.json,
300
+ then restart dsh web to activate the plugin.
301
+ ```
302
+
303
+ ### Updating
304
+
305
+ ```bash
306
+ cd ~/.dsh/profiles/web && pnpm up @a9i5k4/dsh-auto-memory
307
+ ```
308
+
309
+ The Settings page has a "Check for updates" button comparing your version with the npm registry; registry installs get a one-click update.
310
+
311
+ ---
312
+
313
+ ## Configuration
314
+
315
+ Config file `~/.dsh/dsh-auto-memory.json` (everything adjustable in the Settings GUI, zh/en UI and panel font size included):
316
+
317
+ ```json
318
+ {
319
+ "userMemoryDir": "~/.dsh/memory",
320
+ "memoryRoot": "~/.dsh/memory/workspaces",
321
+ "injectEnabled": true,
322
+ "injectBudgetChars": 2400,
323
+ "recentDaysInjected": 1,
324
+ "reflectEnabled": true,
325
+ "autoConsolidate": true,
326
+ "autoConsolidateCooldownMinutes": 30,
327
+ "autoConsolidateDailyMax": 8,
328
+ "unattendedMode": false,
329
+ "unattendedAuto": false,
330
+ "unattendedAutoHours": ["22:00-08:00"],
331
+ "memoryHubEnabled": true,
332
+ "externalSources": { "workbuddy-user": true, "claude-global": true },
333
+ "dayBoundaryMinutes": 450
334
+ }
335
+ ```
336
+
337
+ > Full key reference lives in the Settings page β€” every switch has a description, and every welcome-tour switch maps 1:1 to settings.
338
+
339
+ ---
340
+
341
+ ## Engineering core (restraint by design)
342
+
343
+ - **Zero runtime dependencies** beyond Node built-ins
344
+ - **Prefix-cache friendly**: byte-stable injection keeps DeepSeek's prefix cache hitting β€” your history is never re-encoded
345
+ - **Rate-limited AI**: auto-consolidation ≀8Γ—/day with a 30-minute cooldown; dynamic injection defaults to a 2,400-char budget β€” useful memory without burning tokens
346
+ - **Centralized storage**: all workspace memory under one root (`~/.dsh/memory/workspaces/`), readable from any session
347
+ - **30-day distillation**: old logs are AI-distilled into project notes; originals archived, nothing lost
348
+
349
+ ---
350
+
351
+ ## UI gallery
352
+
353
+ ### Memory panel Β· Overview (away greeting + AI period summaries)
354
+
355
+ <img width="480" alt="overview" src="docs/screenshots/panel-overview.png">
356
+
357
+ ### Memory Hub Β· three stores + skill promotion approvals
358
+
359
+ <img width="480" alt="hub" src="docs/screenshots/panel-hub.png">
360
+
361
+ ### Recall review Β· grade every activation decision
362
+
363
+ <img width="720" alt="refine" src="docs/screenshots/panel-refine.png">
364
+
365
+ ### Welcome tour Β· feature switches + engine detection
366
+
367
+ <img width="720" alt="tour" src="docs/screenshots/tour-toggles.png">
368
+
369
+ <details>
370
+ <summary><b>More screenshots</b> (click to expand)</summary>
371
+
372
+ ### External memory scan (inside the tour)
373
+
374
+ <img width="720" alt="external scan" src="docs/screenshots/tour-external.png">
375
+
376
+ ### Connect other AI tools
377
+
378
+ <img width="480" alt="connect" src="docs/screenshots/connect-en.png">
379
+
380
+ ### Calendar view
381
+
382
+ <img width="480" alt="calendar" src="docs/screenshots/calendar-zh.png">
383
+
384
+ ### Workspace mind map
385
+
386
+ <img width="480" alt="workspace map" src="docs/screenshots/workspace-map-zh.png">
387
+
388
+ ### Settings
389
+
390
+ <img width="480" alt="settings" src="docs/screenshots/settings-en.png">
391
+ <img width="480" alt="settings 2" src="docs/screenshots/settings-2-zh.png">
392
+
393
+ </details>
394
+
395
+ ---
396
+
397
+ ## Structure
398
+
399
+ - `lib/index.js` β€” Host half: engine, injection, tools, routes (zero runtime deps, Node built-ins only)
400
+ - `lib/client.js` β€” Browser half: memory panel (calendar / mind map) + settings page + welcome tour (zh/en i18n)
401
+ - `python/` β€” optional Python semantic sidecar (BGE-M3 int8, advanced tier)
402
+ - `cordis.patch.yml` β€” plugin registration row
403
+
404
+ ## Architecture
405
+
406
+ All milestones are implemented and live-verified. The full interactive architecture map lives at [docs/proactive-associative-memory-system-map.html](docs/proactive-associative-memory-system-map.html); the core layering:
407
+
408
+ ```
409
+ DeepSeek Harness (Node, 127.0.0.1:3080)
410
+ β”œβ”€ JS memory core (lib/*_pre.js, zero runtime deps)
411
+ β”‚ M1 session isolation Β· M2 ContextObserver projection
412
+ β”‚ M3 memory anchoring (anchored records + sidecar identity)
413
+ β”‚ M4 corpus adapter + shadow retrieval host (evidence store)
414
+ β”‚ M5 context/evidence bridge (envelope Β· coverage Β· cite/correction)
415
+ │ M6 activation inbox (validate→offer→claim→reference tail→delivered/seen)
416
+ β”‚ lexical_pre_v2 lexical fallback retrieval (BM25 + CJK 2gram, 0GB always-on)
417
+ β”‚ C2 built-in semantic tier (e5-small q8 ~130MB, default)
418
+ └─ Python sidecar M7 (optional, lazy-spawned child process)
419
+ worker_semantic_pre_v1.py
420
+ β”œβ”€ index_sync: JS-authorized paged index build (digest checks, scope grouping)
421
+ β”œβ”€ dense: BGE-M3 int8 + para-512 chunks + cosine (R@5 0.925)
422
+ β”œβ”€ hybrid: dense 0.7 + lexical 0.3 fusion
423
+ └─ fv2 activation policy: two lanes + hard gates (echo/correction/stale/scope)
424
+ ```
425
+
426
+ **Separation of powers**: the Python semantic layer decides *what to recall and when to suggest*; the JS authority layer decides identity, authorization, timing, and delivery β€” Python never creates evidence nor injects directly. Data flow: `context_push β†’ M5 envelope β†’ decision β†’ M6 fixed-boundary injection β†’ delivered/seen evidence back`.
427
+
428
+ ### Design papers
429
+
430
+ The design is not guesswork β€” every algorithmic conclusion comes from reproducible experiments, frozen into an engineering decision ledger:
431
+
432
+ | Paper | Content |
433
+ |---|---|
434
+ | [Multilingual Embedding Retrieval Study](docs/M7-RESEARCH-PAPER.md) | 3 models Γ— 5 chunkings Γ— 6 retrieval channels β‰ˆ 90 evaluation cells; BGE-M3 leads across the board, frozen as decisions D1–D11 |
435
+ | [Activation v2: The Echo Trap](docs/M7-ACTIVATION-V2-PAPER.md) | Why semantic relevance β‰  recall necessity β€” activation policy technical report + dual-track deployment architecture (Β§7) |
436
+ | [Embedding Benchmark Report](docs/M7-EMBEDDING-BENCHMARK.md) | Frozen basis for model/chunk/fusion: bge-m3 + para-512-noov + weighted fusion |
437
+ | [Frozen Algorithm Decisions D1–D11](docs/M7-ALGORITHM-DECISION.md) | The decision ledger from research conclusions to production implementation |
438
+ | [Held-out Human-Gold Acceptance](docs/M7-ACTIVATION-V2-HOLDEDOUT-EVAL.md) | 67 human-labeled verdicts: actPrecision 0.917 / harmful injections 0 / echo tier 7/7 |
439
+ | [Python Sidecar Contract](docs/PYTHON-SIDECAR-CONTRACT.md) | Protocol / lifecycle / authority boundary / per-milestone regression evidence |
440
+
441
+ Papers were authored by the autonomous engineering agent (ZCode / GLM); all conclusions were frozen into the production implementation under human review.
442
+
443
+ ## Known limitations
444
+
445
+ - Memory files are plain-text Markdown; no secrets stored unless explicitly requested.
446
+ - `memory_recall` session search depends on the deployed session-query index; without it, only local search works.
447
+ - Plugin-set changes require a dsh restart.
448
+
449
+ ---
450
+
451
+ ## Community
452
+
453
+ **Feedback & chat:** join the community QQ group β€” [Join the dsh-auto-memory group](https://qm.qq.com/q/v7Asxn6vPa) β€” for bug reports, usage tips, and quick responses faster than GitHub issues.
454
+
455
+ Community contributors:
456
+
457
+ - [@ProperSAMA](https://github.com/ProperSAMA) β€” panel readability fix for DSH Desktop enhanced mode (transparent/Mica materials) + entry-button anti-occlusion & outside-click/Esc close ([PR #12](https://github.com/Aik358/dsh-auto-memory/pull/12))
458
+ - [@nkh0472](https://github.com/nkh0472) β€” unattended/batch workflow hardening feedback that drove the welcome tour and per-feature switches ([Issue #10](https://github.com/Aik358/dsh-auto-memory/issues/10))
459
+
460
+ ---
461
+
462
+ ## Credits
463
+
464
+ This project is built human-machine collaboratively. In addition to engineering and community contributions above:
465
+
466
+ - **Aik358** β€” project owner: product direction, architecture, and engineering.
467
+ - **ZCode (GLM, Z.ai)** β€” autonomous engineering agent: M-series semantic-engine implementation, benchmark research papers ([M7-RESEARCH-PAPER](docs/M7-RESEARCH-PAPER.md) / [Activation v2 report](docs/M7-ACTIVATION-V2-PAPER.md)), regression suites, and the landing-page design/build.
468
+ - **Kimi K3 (Moonshot AI)** β€” frontend agent: contributed to the v0.1.30 welcome-tour interface assets and visual QA.
469
+
470
+ AI agents are credited as authors of the research papers and parts of the implementation, under human review and direction.
471
+
472
+ ---
473
+
474
+ ## Release
475
+
476
+ - GitHub: https://github.com/Aik358/dsh-auto-memory
477
+ - npm: `@a9i5k4/dsh-auto-memory`
478
+ - License: BSD-3-Clause