@restregular/dsh-memory 0.4.1 → 0.5.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.
@@ -14,7 +14,15 @@
14
14
 
15
15
 
16
16
 
17
- import { MemoryStore, } from './store.js'
17
+ import { MemoryStore, scopeFileName, } from './store.js'
18
+ import {
19
+ isCustomScope,
20
+ resolveCurrentScopes,
21
+ scopeKind,
22
+ scopeTier,
23
+ writeScopeForDefault,
24
+
25
+ } from './scope.js'
18
26
  import { buildStats, lexicalScore, recordScore, tokenize, cosine, normalizeInPlace, hasStrongHit } from './scoring.js'
19
27
  import { EmbedClient } from './embed.js'
20
28
  import { DailyBudget, blendScores, rerank, } from './rerank.js'
@@ -57,7 +65,16 @@ function isInside(parent , child ) {
57
65
 
58
66
 
59
67
 
60
-
68
+
69
+                        
70
+                 
71
+
72
+
73
+
74
+
75
+
76
+
77
+
61
78
 
62
79
 
63
80
 
@@ -136,6 +153,12 @@ function isInside(parent , child ) {
136
153
 
137
154
 
138
155
 
156
+                      
157
+
158
+            
159
+
160
+              
161
+
139
162
 
140
163
 
141
164
 
@@ -358,10 +381,20 @@ export function resolveConfig(config = {}) {
358
381
  const configured = endpointConfigured || spawnConfigured
359
382
  const vectorEnabled = v.enabled ?? configured
360
383
  const flavor = selection.flavor ?? 'cpu'
384
+ // scopes.custom 既可能是布尔(简写)也可能是对象 —— 两种都要认,旧配置(只有
385
+ // global/project 两个布尔)当然照常工作。
386
+ const customCfg = config.scopes?.custom
387
+ const customEnabled = typeof customCfg === 'boolean' ? customCfg : (customCfg?.enabled ?? true)
388
+ const customMax = typeof customCfg === 'object' && customCfg !== null && typeof customCfg.max === 'number'
389
+ ? customCfg.max
390
+ : 200
361
391
  return {
362
392
  storeDir,
363
393
  globalEnabled: config.scopes?.global ?? true,
364
394
  projectEnabled: config.scopes?.project ?? true,
395
+ sessionEnabled: config.scopes?.session ?? true,
396
+ customEnabled,
397
+ customMaxScopes: customMax,
365
398
  topK: config.retrieval?.topK ?? 5,
366
399
  recallN: config.retrieval?.recallN ?? 30,
367
400
  globalThreshold: config.retrieval?.globalThreshold ?? 0.12,
@@ -448,8 +481,12 @@ export class LocalMemoryService {
448
481
  rerankCache = new RerankCache()
449
482
  /** Host-provided one-shot LLM call; null = rerank disabled (recall order). */
450
483
  llmInvoke = null
451
- /** Where saves land when the caller does not pin a scope. */
452
- defaultScope = 'global'
484
+ /** 写路径的默认口径(tools.defaultScope);'session' 拿不到会话时回退 project。 */
485
+ defaultWriteScope = 'session'
486
+ /** 当前项目 scope 键;缺省 project:<启动 cwd>。 */
487
+ projectScope = `project:${process.cwd()}`
488
+ /** 上次发现磁盘 scope 的时间(限流用;0 = 还没发现过)。 */
489
+ discoveredAt = 0
453
490
 
454
491
  constructor(config = {}) {
455
492
  this.cfg = resolveConfig(config)
@@ -461,7 +498,13 @@ export class LocalMemoryService {
461
498
  // whenever the dimensions matched — and the next flush would then rewrite the
462
499
  // header as the new model, making the mismatch permanent.
463
500
  this.store.setVecIdentity(this.cfg.vector.model, this.cfg.vector.dims)
464
- this.store.loadAll(this.cfg.projectEnabled && this.cfg.globalEnabled ? [this.defaultScope, 'global'] : [this.defaultScope])
501
+ // 会话 scope 是按会话动态生成的,**不能**在这里 eager 加载(加载谁?);只预载
502
+ // project 与 global 这两个稳定作用域。其余按需 peek/loadDiscovered。
503
+ // eager 只加载"已存在"的 scope(peek),不会为不存在的 scope 建空文件。
504
+ const eager = []
505
+ if (this.cfg.projectEnabled) eager.push(this.projectScope)
506
+ if (this.cfg.globalEnabled) eager.push('global')
507
+ for (const scope of eager) this.store.peek(scope)
465
508
  this.embed = new EmbedClient({
466
509
  endpoint: this.cfg.vector.endpoint,
467
510
  model: this.cfg.vector.model,
@@ -936,8 +979,22 @@ export class LocalMemoryService {
936
979
  return this.backfillAll({ throttleMs: 100 })
937
980
  }
938
981
 
939
- setDefaultScope(scope ) {
940
- this.defaultScope = scope
982
+ /**
983
+ * 写路径默认 scope 口径(tools.defaultScope 取值)。
984
+ * 兼容:旧调用方传的是**具体 scope 键**(如 'project:<cwd>'),此时按"固定项目"处理。
985
+ */
986
+ setDefaultScope(scope ) {
987
+ if (scope === 'session' || scope === 'project' || scope === 'global') {
988
+ this.defaultWriteScope = scope
989
+ return
990
+ }
991
+ this.defaultWriteScope = 'project'
992
+ this.projectScope = scope
993
+ }
994
+
995
+ /** 固定项目 scope(默认 project:<启动 cwd>);宿主装配用它对齐 session.header.cwd。 */
996
+ setProjectScope(scope ) {
997
+ this.projectScope = scope
941
998
  }
942
999
 
943
1000
  /**
@@ -950,22 +1007,104 @@ export class LocalMemoryService {
950
1007
  this.llmInvoke = invoke
951
1008
  }
952
1009
 
953
- get activeDefaultScope() {
954
- return this.defaultScope
1010
+ /** 写路径默认口径('session' | 'project' | 'global')。 */
1011
+ get activeDefaultScope() {
1012
+ return this.defaultWriteScope
1013
+ }
1014
+
1015
+ get activeProjectScope() {
1016
+ return this.projectScope
955
1017
  }
956
1018
 
957
1019
  assertScopeAllowed(scope ) {
958
- if (scope === 'global' && !this.cfg.globalEnabled) {
959
- throw memoryError('SCOPE_DISABLED', 'global scope is disabled by configuration')
1020
+ if (scope === 'global') {
1021
+ if (!this.cfg.globalEnabled) throw memoryError('SCOPE_DISABLED', 'global scope is disabled by configuration')
1022
+ return
960
1023
  }
961
- if (scope.startsWith('project:') && !this.cfg.projectEnabled) {
962
- throw memoryError('SCOPE_DISABLED', 'project scope is disabled by configuration')
1024
+ if (scope.startsWith('project:')) {
1025
+ if (!this.cfg.projectEnabled) throw memoryError('SCOPE_DISABLED', 'project scope is disabled by configuration')
1026
+ return
963
1027
  }
1028
+ if (scope.startsWith('session:')) {
1029
+ if (!this.cfg.sessionEnabled) throw memoryError('SCOPE_DISABLED', 'session scope is disabled by configuration')
1030
+ return
1031
+ }
1032
+ if (!this.cfg.customEnabled) throw memoryError('SCOPE_DISABLED', 'custom scopes are disabled by configuration')
1033
+ }
1034
+
1035
+ /**
1036
+ * scopes.custom.max 只统计**新建**的自定义 scope,而且只统计自定义的
1037
+ * (会话 / project / global 既不计入也不受限)。
1038
+ *
1039
+ * 计数走 `store.customScopeCount()`,它会顺带扫一遍磁盘 —— 只在"内存里的已加载数已经触到
1040
+ * 上限"时才真扫,否则直接放行,避免每次保存都读一遍 projects/ 目录。
1041
+ */
1042
+ assertCustomScopeBudget(scope ) {
1043
+ if (!isCustomScope(scope)) return
1044
+ if (this.store.peek(scope) !== undefined) return // 已存在(内存或磁盘)→ 写入不受限
1045
+ const loaded = this.store.allScopes().filter((s) => isCustomScope(s.scope)).length
1046
+ if (loaded < this.cfg.customMaxScopes && this.store.customScopeCount() < this.cfg.customMaxScopes) return
1047
+ throw memoryError(
1048
+ 'SCOPE_LIMIT',
1049
+ `custom scope limit reached (${this.cfg.customMaxScopes}); reuse an existing scope instead. ${this.scopeInventory(5)}`,
1050
+ )
1051
+ }
1052
+
1053
+ /** 作用域清单(名字 + 条数),给 SCOPE_LIMIT 之类的错误提示用。 */
1054
+ scopeInventory(limit = 20) {
1055
+ const scopes = this.scopeStats()
1056
+ const lines = scopes.slice(0, limit).map((s) => `${s.scope}(${s.records})`)
1057
+ const rest = scopes.length - lines.length
1058
+ return rest > 0 ? `${lines.join(', ')}, …另有 ${rest} 个` : lines.join(', ')
1059
+ }
1060
+
1061
+ /**
1062
+ * 写路径的 scope 解析:agent 上下文 → 当前会话 / 当前项目;模型省略 scope 时按
1063
+ * `tools.defaultScope`(默认 'session')落点。拿不到会话信息就回退 project,**不抛错**。
1064
+ */
1065
+ resolveWriteScope(agent , requested ) {
1066
+ const refs = this.scopeRefs(agent)
1067
+ const want = requested?.trim()
1068
+ if (want === undefined || want === '' || want.toLowerCase() === 'session') {
1069
+ // scopes.session 关掉时"当前会话"不存在:按 defaultScope 口径回退(默认口径是
1070
+ // session 而会话被关 → project),而不是让写撞上 SCOPE_DISABLED。
1071
+ const session = this.cfg.sessionEnabled ? refs.session : undefined
1072
+ return writeScopeForDefault(this.defaultWriteScope, { ...refs, session })
1073
+ }
1074
+ if (want.toLowerCase() === 'project') return refs.project
1075
+ if (want.toLowerCase() === 'global') return 'global'
1076
+ return requested // 具体键(project:/session:/自定义名)由工具层 normalize 后传入
1077
+ }
1078
+
1079
+ /** agent 上下文 → { session?, project }(会话能否用由调用方按 scopes.session 决定)。 */
1080
+ scopeRefs(agent ) {
1081
+ return resolveCurrentScopes(agent, { projectScope: this.projectScope })
1082
+ }
1083
+
1084
+ /**
1085
+ * 无显式 scope 时的**读取**合并集合:当前会话 + 当前项目 + global(各自开关生效、按 key 去重)。
1086
+ * 工具 / 注入都用它,保证"写进会话的东西,默认读得回来"。
1087
+ */
1088
+ resolveReadScopes(agent ) {
1089
+ const refs = this.scopeRefs(agent)
1090
+ const out = []
1091
+ const push = (scope , enabled ) => {
1092
+ if (scope === undefined || !enabled || out.includes(scope)) return
1093
+ out.push(scope)
1094
+ }
1095
+ push(refs.session, this.cfg.sessionEnabled)
1096
+ push(refs.project, this.cfg.projectEnabled)
1097
+ push('global', this.cfg.globalEnabled)
1098
+ return out
964
1099
  }
965
1100
 
966
1101
  async save(input ) {
967
- const scope = input.scope ?? this.defaultScope
1102
+ // 省略 scope 时按当前会话落点 —— 会话上下文必须**从调用方带进来**
1103
+ // (工具 handler 拿得到 exec.agent,provider 自己看不到)。
1104
+ const scope = input.scope ?? this.resolveWriteScope((input ).agent)
968
1105
  this.assertScopeAllowed(scope)
1106
+ // 自定义 scope 的**新建**受 scopes.custom.max 限制;写已存在的 scope 不受限。
1107
+ this.assertCustomScopeBudget(scope)
969
1108
  let content = input.content?.trim()
970
1109
  if (!content) throw memoryError('CONTENT_EMPTY', 'content must be a non-empty string')
971
1110
  if (content.length > this.cfg.maxRecordChars) {
@@ -987,7 +1126,7 @@ export class LocalMemoryService {
987
1126
  const { record } = this.store.save(
988
1127
  { ...input, scope, content },
989
1128
  { importance: input.source?.origin === 'auto' ? 0.4 : 0.8, source: { origin: 'explicit' } },
990
- )
1129
+ )
991
1130
  void this.embedRecord(record).catch(() => {})
992
1131
  this.store.scheduleFlush()
993
1132
  return record
@@ -1059,18 +1198,30 @@ export class LocalMemoryService {
1059
1198
  }
1060
1199
 
1061
1200
  async search(query ) {
1201
+ // 多 scope 合并由调用方显式给出(工具层传"会话 + 项目 + global");宿主类型里的
1202
+ // MemoryQuery 只有单值 scope,所以这里按结构化读一次可选数组,保持原语义不变。
1203
+ const queryScopes = (query ).scopes
1062
1204
  const topK = query.topK ?? this.cfg.topK
1063
1205
  const recallN = query.recallN ?? this.cfg.recallN
1064
1206
  const now = Date.now()
1065
1207
  const queryTokens = [...new Set(tokenize(query.text))]
1066
1208
 
1067
- // candidate scopes: pinned, else project + global
1068
- const stores = []
1069
- if (query.scope) {
1070
- stores.push({ store: this.store.scope(query.scope), isGlobal: query.scope === 'global' })
1071
- } else {
1072
- if (this.cfg.projectEnabled) stores.push({ store: this.store.scope(this.defaultScope), isGlobal: this.defaultScope === 'global' })
1073
- if (this.cfg.globalEnabled) stores.push({ store: this.store.scope('global'), isGlobal: true })
1209
+ // 候选 scope:显式 pin(单值)优先;否则用调用方给的合并集合(query.scopes,
1210
+ // 工具 / 注入传"会话 + 项目 + global");两者都没有才退回旧的 project + global。
1211
+ // `peek` 而不是 `scope`:读路径不创建,不存在的 scope 直接跳过。
1212
+ const wanted = query.scope
1213
+ ? [query.scope]
1214
+ : (queryScopes ?? []).length > 0
1215
+ ? queryScopes
1216
+ : [this.projectScope, 'global']
1217
+ const stores = []
1218
+ const seen = new Set ()
1219
+ for (const scope of wanted) {
1220
+ if (seen.has(scope)) continue // 按 scope key 去重(也顺手消掉 defaultScope==='global' 时的重复 push)
1221
+ seen.add(scope)
1222
+ const store = this.store.peek(scope)
1223
+ if (!store) continue
1224
+ stores.push({ store, scope, isGlobal: scope === 'global' })
1074
1225
  }
1075
1226
 
1076
1227
  // --- channel 1: lexical recall, scored per scope with local IDF ---
@@ -1087,6 +1238,8 @@ export class LocalMemoryService {
1087
1238
  if (lex <= 0) continue
1088
1239
  // Weak-only overlap (no shared word/bigram) must clear the "real hit"
1089
1240
  // floor, not the permissive threshold — kills single-char collisions.
1241
+ // 阈值只分两档:global 用 globalThreshold,其余(session / project / 自定义)用
1242
+ // projectThreshold —— 不新增配置项。
1090
1243
  const floor = isGlobal ? this.cfg.globalThreshold : this.cfg.projectThreshold
1091
1244
  const effective = hasStrongHit(queryTokens, tokenSets[i] ) ? floor : Math.max(floor, REAL_HIT_FLOOR)
1092
1245
  if (lex < effective) continue
@@ -1136,7 +1289,13 @@ export class LocalMemoryService {
1136
1289
  superseded: supersededIds.has(c.record.id),
1137
1290
  })
1138
1291
 
1139
- const ranked = [...candidates.values()].sort((a, b) => shape(b) - shape(a)).slice(0, recallN)
1292
+ // 稳定 tie-break:同分时 session > project > 自定义 > global,再同分按 record id ——
1293
+ // 否则 Map 的插入顺序(取决于 scope 顺序)会让同一查询在不同进程间给出不同结果。
1294
+ const ranked = [...candidates.values()]
1295
+ .sort((a, b) => shape(b) - shape(a)
1296
+ || scopeTier(a.record.scope) - scopeTier(b.record.scope)
1297
+ || a.record.id.localeCompare(b.record.id))
1298
+ .slice(0, recallN)
1140
1299
 
1141
1300
  // --- channel 3: LLM rerank (optional; any skip/failure keeps recall order) ---
1142
1301
  const finalScores = new Map (ranked.map((c) => [c.id, shape(c)]))
@@ -1176,19 +1335,32 @@ export class LocalMemoryService {
1176
1335
  return undefined
1177
1336
  }
1178
1337
 
1179
- async forget(input ) {
1338
+ async forget(input ) {
1180
1339
  const ids = []
1181
1340
  if (input.id) {
1341
+ // 按 id 删除天然跨 scope:调用方给的是精确 id,不存在误删别的 scope 的风险。
1182
1342
  for (const s of this.store.allScopes()) {
1183
1343
  if (s.remove(input.id)) ids.push(input.id)
1184
1344
  }
1185
1345
  if (ids.length === 0) throw memoryError('RECORD_NOT_FOUND', `id ${input.id} not found`)
1186
1346
  } else if (input.query) {
1187
- const scope = input.scope ?? this.defaultScope
1188
- ids.push(...this.store.findIdsByQuery(scope, input.query))
1189
- const s = this.store.scope(scope)
1190
- for (const id of ids) s.remove(id)
1191
- if (ids.length === 0) throw memoryError('RECORD_NOT_FOUND', `no record matching query in ${scope}`)
1347
+ // 按 query 删除的默认范围由工具层显式给出(默认只有当前会话);这里不再回退到
1348
+ // provider 的默认 scope —— 那正是"以为删了会话记忆、其实删了 global"的来源。
1349
+ const targets = input.scope !== undefined
1350
+ ? [input.scope]
1351
+ : (input.scopes ?? []).length > 0
1352
+ ? input.scopes
1353
+ : [this.projectScope]
1354
+ const seen = new Set ()
1355
+ for (const scope of targets) {
1356
+ if (seen.has(scope)) continue
1357
+ seen.add(scope)
1358
+ const store = this.store.peek(scope) // 读/删路径不创建
1359
+ if (!store) continue
1360
+ const hit = this.store.findIdsByQuery(scope, input.query)
1361
+ for (const id of hit) if (store.remove(id)) ids.push(id)
1362
+ }
1363
+ if (ids.length === 0) throw memoryError('RECORD_NOT_FOUND', `no record matching query in ${targets.join(', ')}`)
1192
1364
  } else {
1193
1365
  throw memoryError('RECORD_NOT_FOUND', 'forget requires id or query')
1194
1366
  }
@@ -1196,14 +1368,78 @@ export class LocalMemoryService {
1196
1368
  return { removed: ids.length, ids }
1197
1369
  }
1198
1370
 
1371
+ /**
1372
+ * 列记录。显式 scope 只列它;`scopes` 数组用于"全部作用域";两者都没有时退回项目 scope。
1373
+ * 一律走 `peek`,所以列一个不存在的 scope 只会得到空数组,不会造出文件。
1374
+ */
1199
1375
  async list(input = {}) {
1200
- const scope = input.scope ?? this.defaultScope
1201
- let records = [...this.store.scope(scope).records.values()]
1376
+ const wanted = input.scope !== undefined
1377
+ ? [input.scope]
1378
+ : (input.scopes ?? []).length > 0
1379
+ ? input.scopes
1380
+ : [this.projectScope]
1381
+ const seen = new Set ()
1382
+ let records = []
1383
+ for (const scope of wanted) {
1384
+ if (seen.has(scope)) continue
1385
+ seen.add(scope)
1386
+ const store = this.store.peek(scope)
1387
+ if (store) records.push(...store.records.values())
1388
+ }
1202
1389
  if (input.kind) records = records.filter((r) => r.kind === input.kind)
1203
1390
  records.sort((a, b) => b.updatedAt - a.updatedAt)
1204
1391
  return records.slice(0, input.limit ?? 50)
1205
1392
  }
1206
1393
 
1394
+ /**
1395
+ * 作用域清单(名字 + 条数 + 待嵌入 + 最近活跃时间),给面板 /status 与 memory_list 的尾部清单用。
1396
+ *
1397
+ * 先 `discoverScopes()`:进程内 store 是懒加载的,只列"已加载"的 scope 会让面板/清单
1398
+ * 漏掉别的进程(上一次会话、另一个 agent)写下的作用域。
1399
+ * 排序键是"最近活跃"(`updatedAt`):面板据此只给最近活跃的前 N 个会话 scope 查标题。
1400
+ */
1401
+ scopeStats() {
1402
+ this.discoverScopes()
1403
+ return this.store.allScopes()
1404
+ .map((s) => ({
1405
+ scope: s.scope,
1406
+ records: s.records.size,
1407
+ pendingEmbeds: s.embedPending.size,
1408
+ updatedAt: [...s.records.values()].reduce((max, r) => Math.max(max, r.updatedAt), 0),
1409
+ }))
1410
+ .sort((a, b) => b.updatedAt - a.updatedAt || b.records - a.records || a.scope.localeCompare(b.scope))
1411
+ }
1412
+
1413
+ /**
1414
+ * 发现磁盘上的 scope(带时间缓存)。面板每次 /status、每次 memory_list 都要一份完整
1415
+ * 清单,而 discovery 要读每个文件的第一条记录 —— 限流到最短 3 秒一次,既保证清单够新,
1416
+ * 也不至于把 projects/ 目录读成热路径(面板侧还有一层同样时长的缓存,旧 provider 也能受益)。
1417
+ */
1418
+ /**
1419
+ * 当前进程已知的 scope 键:**只读**,不触发发现(要完整清单用 discoverScopes()/scopeStats())。
1420
+ */
1421
+ knownScopes() {
1422
+ return this.store.allScopes().map((s) => s.scope)
1423
+ }
1424
+
1425
+ /**
1426
+ * 发现磁盘上的 scope(带时间缓存)。面板每次 /status、每次 memory_list 都要一份完整
1427
+ * 清单,而 discovery 要读每个文件的第一条记录 —— 限流到最短 3 秒一次,既保证清单够新,
1428
+ * 也不至于把 projects/ 目录读成热路径(面板侧还有一层同样时长的缓存,旧 provider 也能受益)。
1429
+ */
1430
+ discoverScopes() {
1431
+ const now = Date.now()
1432
+ if (this.discoveredAt === 0 || now - this.discoveredAt >= DISCOVER_TTL_MS) {
1433
+ this.discoveredAt = now
1434
+ try {
1435
+ this.store.loadDiscovered()
1436
+ } catch {
1437
+ // 发现失败不影响读写,清单里少几个而已
1438
+ }
1439
+ }
1440
+ return this.knownScopes()
1441
+ }
1442
+
1207
1443
  /** Force a synchronous flush (dispose/HMR path). */
1208
1444
  flushSync() {
1209
1445
  if (this.maintenanceTimer) {
@@ -1265,6 +1501,9 @@ function memoryError(code , message ) {
1265
1501
  return err
1266
1502
  }
1267
1503
 
1504
+ /** discoverScopes() 的最短间隔:清单要够新,但 projects/ 目录不该被读成热路径。 */
1505
+ const DISCOVER_TTL_MS = 3000
1506
+
1268
1507
  export function createMemoryService(config = {}) {
1269
1508
  return new LocalMemoryService(config)
1270
1509
  }