@restregular/dsh-memory 0.1.2 → 0.3.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.
@@ -21,6 +21,29 @@ import { DailyBudget, blendScores, rerank, } f
21
21
  import { RerankCache } from './rerank-cache.js'
22
22
  import { scanSecrets, redactSecrets } from './secrets.js'
23
23
  import { EmbedServerManager, } from './embed-server.js'
24
+ import { VectorInstaller, detectInstalled, installPaths, } from './embed-install.js'
25
+ import { existsSync, readdirSync, rmSync, statSync } from 'node:fs'
26
+ import { dirname, isAbsolute, join, relative, resolve } from 'node:path'
27
+ import { homedir } from 'node:os'
28
+
29
+ /** Recursive byte count; 0 for anything unreadable. */
30
+ function pathSize(path ) {
31
+ try {
32
+ const st = statSync(path)
33
+ if (!st.isDirectory()) return st.size
34
+ let total = 0
35
+ for (const entry of readdirSync(path)) total += pathSize(join(path, entry))
36
+ return total
37
+ } catch {
38
+ return 0
39
+ }
40
+ }
41
+
42
+ /** True when `child` is `parent` or lives under it (both resolved). */
43
+ function isInside(parent , child ) {
44
+ const rel = relative(resolve(parent), resolve(child))
45
+ return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel))
46
+ }
24
47
 
25
48
 
26
49
 
@@ -51,6 +74,22 @@ import { EmbedServerManager, } fro
51
74
 
52
75
 
53
76
 
77
+
78
+
79
+
80
+
81
+  
82
+
83
+
84
+
85
+
86
+
87
+  
88
+  
89
+
90
+
91
+
92
+
54
93
 
55
94
 
56
95
 
@@ -70,6 +109,14 @@ import { EmbedServerManager, } fro
70
109
 
71
110
 
72
111
 
112
+
113
+
114
+
115
+
116
+
117
+
118
+  
119
+
73
120
 
74
121
 
75
122
 
@@ -89,8 +136,32 @@ import { EmbedServerManager, } fro
89
136
 
90
137
  export function resolveConfig(config = {}) {
91
138
  const v = config.retrieval?.vector ?? {}
139
+ // Do not touch an embedding backend the user never asked for: pointing at the
140
+ // stock localhost endpoint on a machine that has nothing listening means
141
+ // failed embeds, a tripped breaker and scary log lines for a feature that is
142
+ // optional. Vector retrieval is therefore opt-in by CONFIGURATION — writing
143
+ // `endpoint` (any OpenAI-compatible service), configuring `spawn`, or having
144
+ // the panel's installer put a backend on disk implies intent; an explicit
145
+ // `enabled` always wins.
146
+ const storeDir = config.storeDir ?? '.dsh-memory'
147
+ // Installer target: explicit config → that directory; explicit storeDir →
148
+ // its parent (so a hand-made `<root>/llamacpp` + `<root>/models` layout is
149
+ // recognised as-is); otherwise a stable per-user directory under ~/.dsh.
150
+ const installRoot = v.autoInstall?.dir
151
+ ?? (config.storeDir !== undefined ? dirname(resolve(storeDir)) : join(homedir(), '.dsh', 'memory-vector'))
152
+ const installed = detectInstalled(installRoot)
153
+ const endpointConfigured = v.endpoint !== undefined
154
+ // A configured spawn path that no longer exists (plugin uninstalled the
155
+ // backend, or the user moved it) must not count as configured: that would
156
+ // leave the panel showing a managed server that can never start, instead of
157
+ // offering the download button again.
158
+ const spawnExe = v.spawn?.exe
159
+ const spawnExeUsable = spawnExe === undefined || spawnExe === '' || existsSync(spawnExe)
160
+ const spawnConfigured = ((v.spawn?.enabled === true || (spawnExe ?? '') !== '') && spawnExeUsable) || installed !== null
161
+ const configured = endpointConfigured || spawnConfigured
162
+ const vectorEnabled = v.enabled ?? configured
92
163
  return {
93
- storeDir: config.storeDir ?? '.dsh-memory',
164
+ storeDir,
94
165
  globalEnabled: config.scopes?.global ?? true,
95
166
  projectEnabled: config.scopes?.project ?? true,
96
167
  topK: config.retrieval?.topK ?? 5,
@@ -99,7 +170,12 @@ export function resolveConfig(config = {}) {
99
170
  projectThreshold: config.retrieval?.projectThreshold ?? 0.1,
100
171
  halfLifeDays: config.retrieval?.recencyHalfLifeDays ?? 30,
101
172
  vector: {
102
- enabled: v.enabled ?? true,
173
+ enabled: vectorEnabled,
174
+ configured,
175
+ endpointConfigured,
176
+ spawnConfigured,
177
+ installRoot,
178
+ ...(v.autoInstall?.modelSources ? { installModelSources: v.autoInstall.modelSources } : {}),
103
179
  endpoint: v.endpoint ?? 'http://127.0.0.1:8078/v1/embeddings',
104
180
  model: v.model ?? 'bge-m3',
105
181
  dims: v.dims ?? 1024,
@@ -115,9 +191,19 @@ export function resolveConfig(config = {}) {
115
191
  backfillBatchSize: v.backfillBatchSize ?? 32,
116
192
  // Port defaults to the one in the embeddings endpoint so the two can never
117
193
  // drift apart; opt-in (enabled:false) keeps dev/test runs from spawning.
194
+ // A backend the panel installed (or a hand-made one at installRoot) is
195
+ // adopted as the spawn target when the user configured no explicit paths.
118
196
  spawn: {
119
197
  ...(v.spawn ?? {}),
120
- enabled: v.spawn?.enabled ?? false,
198
+ enabled: v.spawn?.enabled ?? installed !== null,
199
+ ...(installed
200
+ ? {
201
+ exe: v.spawn?.exe ?? installed.exe,
202
+ model: v.spawn?.model ?? installed.model,
203
+ cwd: v.spawn?.cwd ?? installed.cwd,
204
+ logFile: v.spawn?.logFile ?? installed.logFile,
205
+ }
206
+ : {}),
121
207
  port: v.spawn?.port ?? portOf(v.endpoint ?? 'http://127.0.0.1:8078/v1/embeddings') ?? 8078,
122
208
  },
123
209
  },
@@ -169,6 +255,9 @@ export class LocalMemoryService {
169
255
 
170
256
  /** Own the embedding backend's lifetime: spawn on activation, stop on dispose. */
171
257
  startEmbedServer() {
258
+ // Nothing configured and retrieval switched off → do not even build the
259
+ // manager, so no probe, no spawn attempt, no misleading panel state.
260
+ if (!this.cfg.vector.enabled || !this.cfg.vector.configured) return
172
261
  this.embedServer = new EmbedServerManager(this.cfg.vector.spawn)
173
262
  // fire-and-forget: activation must never block on a model load
174
263
  void this.ensureEmbedServer(60_000).catch(() => { /* lifecycle never breaks activation */ })
@@ -210,20 +299,213 @@ export class LocalMemoryService {
210
299
  return { stopped: mgr.stop(), reason: mgr.isOwned ? 'NOT_RUNNING' : 'STOPPED' }
211
300
  }
212
301
 
213
- /** Lifecycle snapshot for the memory panel. */
302
+ /**
303
+ * Lifecycle snapshot for the memory panel.
304
+ *
305
+ * `mode` is what the panel needs to decide whether a start/stop switch even
306
+ * makes sense:
307
+ * - 'off' nothing configured → no switch, show how to opt in
308
+ * - 'external' we only know an endpoint (cloud or a server the user runs)
309
+ * → no switch, we must not claim ownership of that process
310
+ * - 'managed' spawn is configured → the switch toggles OUR child process
311
+ * `enabled` is the retrieval switch from config; when it is false while a
312
+ * backend IS configured the panel explains the config instead of showing a
313
+ * switch that cannot turn retrieval on.
314
+ */
214
315
  async embedServerStatus()
215
316
 
317
+
318
+
319
+
320
+
321
+
216
322
 
217
323
 
218
324
 
219
325
 
220
326
 
327
+
328
+
329
+
221
330
  {
222
331
  const mgr = this.embedServer
332
+ const cfg = this.cfg.vector
223
333
  const pendingEmbeds = this.pendingEmbedCount
224
- if (!mgr) return { enabled: false, owned: false, pid: null, baseUrl: '', reachable: false, pendingEmbeds }
334
+ const mode = !cfg.configured ? 'off' : cfg.spawnConfigured ? 'managed' : 'external'
335
+ const usage = this.vectorInstallUsage()
336
+ const base = {
337
+ enabled: cfg.enabled,
338
+ configured: cfg.configured,
339
+ mode,
340
+ endpoint: cfg.endpoint,
341
+ model: cfg.model,
342
+ spawnConfigured: cfg.spawnConfigured,
343
+ pendingEmbeds,
344
+ install: this.installSnapshot(),
345
+ maintenance: {
346
+ usageBytes: usage.bytes,
347
+ paths: usage.paths,
348
+ // NOTE: `cfg` is the VECTOR config here, not the whole config — reading
349
+ // cfg.storeDir would silently yield undefined (and JSON drops it).
350
+ storeDir: this.cfg.storeDir,
351
+ records: this.store.allScopes().reduce((n, s) => n + s.records.size, 0),
352
+ },
353
+ }
354
+ if (!mgr) return { ...base, owned: false, pid: null, baseUrl: '', reachable: false }
225
355
  const reachable = await mgr.healthCheck()
226
- return { ...mgr.info(), reachable, pendingEmbeds }
356
+ return { ...base, ...mgr.info(), reachable, pendingEmbeds }
357
+ }
358
+
359
+ /** Installer state for the panel (idle when nothing was ever requested). */
360
+ installSnapshot() {
361
+ const root = this.cfg.vector.installRoot
362
+ const installed = detectInstalled(root) !== null
363
+ const progress = this.installer?.progress ?? {
364
+ phase: 'idle' ,
365
+ message: '',
366
+ receivedBytes: 0,
367
+ totalBytes: null,
368
+ error: null,
369
+ paths: installed ? installPaths(root) : null,
370
+ }
371
+ return { ...progress, installed, root }
372
+ }
373
+
374
+ /**
375
+ * Panel action: download llama.cpp + the GGML model into installRoot, then
376
+ * adopt them (start the managed server). Never runs on its own — a fresh
377
+ * install downloads nothing until the user asks.
378
+ */
379
+ installVectorBackend() {
380
+ if (detectInstalled(this.cfg.vector.installRoot)) {
381
+ this.adoptInstalledBackend()
382
+ return
383
+ }
384
+ if (!this.installer) {
385
+ this.installer = new VectorInstaller({
386
+ root: this.cfg.vector.installRoot,
387
+ ...(this.cfg.vector.installModelSources ? { modelSources: this.cfg.vector.installModelSources } : {}),
388
+ onProgress: (progress) => {
389
+ if (progress.phase === 'done') this.adoptInstalledBackend()
390
+ },
391
+ })
392
+ }
393
+ this.installer.start()
394
+ }
395
+
396
+ /** Panel action: abort an in-flight download. */
397
+ cancelVectorInstall() {
398
+ this.installer?.cancel()
399
+ }
400
+
401
+ /**
402
+ * What the installer put on disk, so the panel can say "释放 xxx MB" before
403
+ * offering to remove it. Counts only our own layout (runtime dir, models dir,
404
+ * log + pid), never the memory store.
405
+ */
406
+ vectorInstallUsage() {
407
+ const paths = installPaths(this.cfg.vector.installRoot)
408
+ const roots = [paths.dir, join(this.cfg.vector.installRoot, 'models')]
409
+ const files = [paths.logFile, `${paths.logFile}.pid`, `${paths.logFile}.err`]
410
+ let bytes = 0
411
+ const seen = []
412
+ for (const p of [...roots, ...files]) {
413
+ if (!existsSync(p)) continue
414
+ seen.push(p)
415
+ bytes += pathSize(p)
416
+ }
417
+ return { bytes, paths: seen }
418
+ }
419
+
420
+ /**
421
+ * Remove the vector backend we installed (runtime + model + logs).
422
+ *
423
+ * Refuses when the configured backend lives outside installRoot: that is a
424
+ * server the user installed and manages, and deleting it would be destroying
425
+ * something we never created. The memory store is never touched — it lives
426
+ * beside the runtime, not inside it.
427
+ */
428
+ uninstallVectorBackend()
429
+
430
+
431
+
432
+
433
+ {
434
+ const root = this.cfg.vector.installRoot
435
+ const configuredExe = this.cfg.vector.spawn.exe
436
+ if (configuredExe && !isInside(root, configuredExe)) {
437
+ return { removed: false, reason: 'EXTERNAL_BACKEND', freedBytes: 0, paths: [] }
438
+ }
439
+ const usage = this.vectorInstallUsage()
440
+ if (usage.paths.length === 0) {
441
+ return { removed: false, reason: 'NOT_INSTALLED', freedBytes: 0, paths: [] }
442
+ }
443
+ // Stop our child first: on Windows the executable and its DLLs are locked
444
+ // while it runs, so removal would fail with EBUSY/EPERM.
445
+ try { this.embedServer?.stop() } catch { /* best effort */ }
446
+ const removedPaths = []
447
+ for (const p of usage.paths) {
448
+ // Belt and braces: never step outside the install root, and never delete
449
+ // the memory store even if someone pointed storeDir inside it.
450
+ if (!isInside(root, p)) continue
451
+ if (isInside(p, this.cfg.storeDir) || resolve(p) === resolve(this.cfg.storeDir)) continue
452
+ try {
453
+ rmSync(p, { recursive: true, force: true })
454
+ removedPaths.push(p)
455
+ } catch { /* leave it; the panel reports what went */ }
456
+ }
457
+ this.cfg.vector.configured = false
458
+ this.cfg.vector.spawnConfigured = false
459
+ this.cfg.vector.enabled = false
460
+ this.embedServer = null
461
+ return { removed: true, reason: 'REMOVED', freedBytes: usage.bytes, paths: removedPaths }
462
+ }
463
+
464
+ /**
465
+ * Delete every memory record in every scope (the panel's "delete all data"
466
+ * action, used when someone wants the plugin gone without leaving notes
467
+ * behind). Goes through the store so the JSONL + vector sidecars stay
468
+ * consistent instead of ripping files out from under a live store.
469
+ */
470
+ wipeAllRecords() {
471
+ let removed = 0
472
+ const scopes = []
473
+ for (const scope of this.store.allScopes()) {
474
+ const ids = [...scope.records.keys()]
475
+ if (ids.length === 0) continue
476
+ let local = 0
477
+ for (const id of ids) if (scope.remove(id)) local += 1
478
+ removed += local
479
+ scopes.push(scope.scope)
480
+ }
481
+ try { this.store.flushSync() } catch { /* scheduled flush covers it */ }
482
+ return { removed, scopes }
483
+ }
484
+
485
+ /**
486
+ * Switch the provider over to a backend that is now on disk: fill the spawn
487
+ * config from the installed layout and start it. Idempotent.
488
+ */
489
+ adoptInstalledBackend() {
490
+ const paths = detectInstalled(this.cfg.vector.installRoot)
491
+ if (!paths) return
492
+ this.cfg.vector.configured = true
493
+ this.cfg.vector.spawnConfigured = true
494
+ this.cfg.vector.enabled = true
495
+ this.cfg.vector.spawn = {
496
+ ...this.cfg.vector.spawn,
497
+ enabled: true,
498
+ exe: this.cfg.vector.spawn.exe ?? paths.exe,
499
+ model: this.cfg.vector.spawn.model ?? paths.model,
500
+ cwd: this.cfg.vector.spawn.cwd ?? paths.cwd,
501
+ logFile: this.cfg.vector.spawn.logFile ?? paths.logFile,
502
+ port: this.cfg.vector.spawn.port,
503
+ }
504
+ if (!this.embedServer) {
505
+ this.startEmbedServer()
506
+ return
507
+ }
508
+ void this.ensureEmbedServer(60_000).catch(() => { /* panel shows the outcome */ })
227
509
  }
228
510
 
229
511
  /**
@@ -261,6 +543,8 @@ export class LocalMemoryService {
261
543
  initialDrainTimer = null
262
544
  /** Owns the llama-server child process when vector.spawn.enabled. */
263
545
  embedServer = null
546
+ /** Lazily created by the panel's "download and configure" action. */
547
+ installer = null
264
548
  exitHook = null
265
549
 
266
550
  /**
@@ -270,6 +554,9 @@ export class LocalMemoryService {
270
554
  * only path that can flip that flag back to healthy).
271
555
  */
272
556
  async retryPendingEmbeds() {
557
+ // Vector retrieval opt-in: with no configured backend there is nothing to
558
+ // retry, and probing would only produce failed requests in the log.
559
+ if (!this.cfg.vector.enabled || !this.cfg.vector.configured) return 0
273
560
  // Scopes load lazily, so without discovery the queue of an untouched scope
274
561
  // (e.g. a project store written by a previous session) is invisible here and
275
562
  // would never drain — exactly the 待嵌入>0 the panel showed on 2026-10-10.
@@ -340,6 +627,7 @@ export class LocalMemoryService {
340
627
  }
341
628
 
342
629
  async embedRecord(record ) {
630
+ if (!this.cfg.vector.enabled || !this.cfg.vector.configured) return
343
631
  const s = this.store.scope(record.scope)
344
632
  // save-time budget: one full record, much slower than a search query
345
633
  const vec = await this.embed.embed([record.content], undefined, { timeoutMs: this.cfg.vector.writeTimeoutMs }).catch(() => null)
@@ -354,6 +642,7 @@ export class LocalMemoryService {
354
642
  * interactive timeout would abort every attempt.
355
643
  */
356
644
  async backfillEmbeddings() {
645
+ if (!this.cfg.vector.enabled || !this.cfg.vector.configured) return 0
357
646
  if (!this.embed.isHealthy) return 0
358
647
  let done = 0
359
648
  for (const s of this.store.allScopes()) {
@@ -438,7 +727,11 @@ export class LocalMemoryService {
438
727
  }
439
728
 
440
729
  // --- channel 2: vector recall over embedded records ---
441
- const qvec = await this.embed.embed([query.text], query.signal).catch(() => null)
730
+ // Skipped entirely when no backend is configured (lexical recall above
731
+ // already produced the candidates; a request here would just fail).
732
+ const qvec = this.cfg.vector.enabled && this.cfg.vector.configured
733
+ ? await this.embed.embed([query.text], query.signal).catch(() => null)
734
+ : null
442
735
  if (qvec?.[0]) {
443
736
  const vectorScores = new Map ()
444
737
  for (const { store } of stores) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@restregular/dsh-memory",
3
- "version": "0.1.2",
3
+ "version": "0.3.0",
4
4
  "description": "DeepSeek Harness 本地长期记忆:JSONL 存储 + 本地向量检索(BGE-M3)+ 四个模型工具 + 自动召回注入。",
5
5
  "type": "module",
6
6
  "exports": {