@yolk_vat-y/dsh-project-memory 0.5.11 → 0.5.13

package/src/store.js

@@ -18,33 +18,122 @@ const GITIGNORE_FILE = '.gitignore'
 const LEGACY_TYPE_CACHE_DIR = 'type-cache'
 
 const storeCache = new Map()
+/** 单实例超预算的告警只打一次（key = 解析后的 store 目录）。 */
+const warnedOverBudget = new Set()
 /** 条目数上限（兜底）。 */
 const STORE_CACHE_MAX = 32
 /**
- * 驻留内存的估算上限。只数"几个 store"是不够的：单个大仓库 store 加载后堆占用实测
- * 130–200MB，32 个就是几 GB。按 store 的条目数与读入文本量估算，约 2.5KB/entry。
+ * 驻留内存的估算上限。只数"几个 store"是不够的：单个大仓库 store 实测驻留
+ * 68MB（`load()` 后）～110MB（物化 `searchText` + 建 IDF/符号索引后），
+ * 语料是 deepseek-harness / 70119 条目。32 个就是几 GB。
+ * 估算口径见 `_estimateResidentBytes`（对内存里的对象图精确计数，不再用读盘文本量换算）。
  */
-const STORE_CACHE_MAX_BYTES = 256 * 1024 * 1024
+let STORE_CACHE_MAX_BYTES = 256 * 1024 * 1024
 /** 每轮 save 最多补写多少个待压实的老分片（有界，避免升级后一次重写整库）。 */
 const COMPACT_BATCH = 200
 
-/** 单个 store 的驻留估算（驻留文本量 vs 条目数换算，取大者）。 */
-function estimateResidentBytes(store) {
-  let entries = 0
-  for (const list of Object.values(store.entries)) entries += list.length
-  return Math.max(store._residentChars || 0, entries * 2500)
+/**
+ * 一个值的驻留字节：形状开销 + 字符串的**编码字节数**。
+ *
+ * 用 `Buffer.byteLength()` 而不是 `String.length`：CJK 在 UTF-8 里 3 字节/字符，而 V8
+ * 双字节串 2 字节/字符——UTF-8 对非 ASCII 是偏高的代理指标，对纯 ASCII 精确。缓存预算
+ * 容得下这个误差（实测两端 ±13%，见 `test/store-cache.test.mjs` 与 PLAN 附七）。
+ *
+ * 递归用深度上限而不是 `Set` 去环：store 的对象图来自 `JSON.parse`，本就无环；深度上限
+ * 既挡畸形数据，又比逐对象 `Set` 查重快 ~30%（70119 条目实测 36ms vs 52ms）。
+ */
+const RESIDENT_OBJ_BYTES = 60
+const RESIDENT_ARR_BYTES = 40
+const RESIDENT_KEY_BYTES = 40
+const RESIDENT_STR_BYTES = 16
+const RESIDENT_MAX_DEPTH = 8
+
+function residentBytesOf(value, depth = 0) {
+  if (depth > RESIDENT_MAX_DEPTH) return 0
+  const type = typeof value
+  if (type === 'string') return RESIDENT_STR_BYTES + Buffer.byteLength(value)
+  if (type === 'number' || type === 'bigint') return 16
+  if (type === 'boolean' || value === null) return 8
+  if (Array.isArray(value)) {
+    let sum = RESIDENT_ARR_BYTES
+    for (const item of value) sum += 8 + residentBytesOf(item, depth + 1)
+    return sum
+  }
+  if (type === 'object') {
+    let sum = RESIDENT_OBJ_BYTES
+    for (const key in value) sum += RESIDENT_KEY_BYTES + residentBytesOf(value[key], depth + 1)
+    return sum
+  }
+  return 0
+}
+
+/**
+ * 单个 store 的驻留估算：数**内存里留下的对象图**，按版本记忆化。
+ *
+ * 为什么不是"读盘文本量换算"（旧实现）：那个口径有两个错。
+ *  1. 时序错位——它量的是 `load()` 读进来的 JSON 文本，而 `searchText` 要到
+ *     `allEntries()` 才物化，同一份数据在物化前后估出两个数（实测 76MB → 107MB）。
+ *  2. 账不对物——旧分片里还带着 `searchText` / `linkedSymbols`，`load()` 会
+ *     `stripPersistedDerived` 把它们删掉，可文本量已经把被删的字节算进去了。
+ *     `/home/sxt/project` 的 store 实测：读盘 212.6MB，真实驻留 101.7MB。
+ *
+ * 两个版本键都参与失效：`_entriesVersion`（`setEntries` / `removeFile` / `_loadSharded`）
+ * 与 `_materializeVersion`（`allEntries()` 物化 `searchText`）。漏掉后者就是旧实现的错。
+ *
+ * 代价：版本变化后的**一次**全量遍历（70119 条目 ~40ms）。必须记忆化——`evictStoreCache`
+ * 是对**整个缓存**逐 store 求和的，不记忆化等于每次冷加载都把缓存里所有 store 重数一遍。
+ */
+export function _estimateResidentBytes(store) {
+  const stamp = `${store._entriesVersion}:${store._materializeVersion}`
+  if (store._residentStamp !== stamp) {
+    store._residentBytes =
+      residentBytesOf(store.entries) +
+      residentBytesOf(store.files) +
+      residentBytesOf(store.experience) +
+      residentBytesOf(store.tasks) +
+      residentBytesOf(store.insights) +
+      residentBytesOf(store.watchlist) +
+      residentBytesOf(store.binding)
+    store._residentStamp = stamp
+  }
+  return store._residentBytes
 }
 
 /** 按 LRU 逐出，直到同时满足条数与字节预算；刚加入的 keepKey 即使超预算也保留。 */
 function evictStoreCache(keepKey) {
   let total = 0
-  for (const store of storeCache.values()) total += estimateResidentBytes(store)
+  for (const store of storeCache.values()) total += _estimateResidentBytes(store)
   while (storeCache.size > STORE_CACHE_MAX || total > STORE_CACHE_MAX_BYTES) {
     const oldest = storeCache.keys().next().value
     if (oldest === undefined || oldest === keepKey) break
-    total -= estimateResidentBytes(storeCache.get(oldest))
+    total -= _estimateResidentBytes(storeCache.get(oldest))
     storeCache.delete(oldest)
   }
+  // keepKey 豁免是**有意**的：刚加载的 store 必须立刻可用。但它的代价是"单实例超预算时
+  // 预算不再是上界"——这个代价不能是隐式的，所以每个这样的 store 告警一次（每 root 一次）。
+  const kept = _estimateResidentBytes(storeCache.get(keepKey))
+  if (kept > STORE_CACHE_MAX_BYTES && !warnedOverBudget.has(keepKey)) {
+    warnedOverBudget.add(keepKey)
+    console.error(
+      `[dsh-project-memory] store ${keepKey} 单实例驻留约 ${Math.round(kept / 1048576)}MB，` +
+        `超过 storeCache 预算 ${Math.round(STORE_CACHE_MAX_BYTES / 1048576)}MB；` +
+        '刚加载的 store 不逐出（有意豁免），多 root 场景下其他 store 会被更频繁地逐出。',
+    )
+  }
+}
+
+/** 仅供测试：临时收窄字节预算（返回恢复函数），免得测试真去分配 256MB 字符串。 */
+export function _setStoreCacheBudgetForTest(bytes) {
+  const previous = STORE_CACHE_MAX_BYTES
+  STORE_CACHE_MAX_BYTES = bytes
+  return () => {
+    STORE_CACHE_MAX_BYTES = previous
+  }
+}
+
+/** 仅供测试：当前缓存 key 的 LRU 顺序（最旧在前）。 */
+export function _storeCacheKeysForTest() {
+  return [...storeCache.keys()]
 }
 
 /** 已就"无法迁移的旧 store"告警过的目录：避免每次 load() 都刷一行。 */
@@ -78,14 +167,13 @@ function withoutPersistedDerived(entry) {
   return out
 }
 
-function loadJson(filePath, fallback, sizeSink) {
+function loadJson(filePath, fallback) {
   let raw
   try {
     raw = readFileSync(filePath, 'utf8')
   } catch {
     return fallback
   }
-  if (sizeSink) sizeSink.bytes += raw.length
   try {
     return JSON.parse(raw)
   } catch {
@@ -142,8 +230,14 @@ export class ProjectMemoryStore {
     this._entriesVersion = 0
     /** 待压实的老分片（≤0.5.10 落盘时带 linkedSymbols/searchText）；save() 每轮有界补写。 */
     this._compactQueue = new Set()
-    /** 从磁盘读入的 JSON 文本量（UTF-16 字符数），作为驻留内存的估算基数。 */
-    this._residentChars = 0
+    /** 驻留字节估算的记忆化结果与版本戳（见 `_estimateResidentBytes`）。 */
+    this._residentBytes = 0
+    this._residentStamp = ''
+    /**
+     * `searchText` 的物化计数。它和 `_entriesVersion` 一起构成驻留估算的失效键：
+     * 物化只改 entry 对象本身，不改 entries 的构成，所以不会 bump `_entriesVersion`。
+     */
+    this._materializeVersion = 0
   }
 
   load() {
@@ -243,9 +337,8 @@ export class ProjectMemoryStore {
     } catch {
       shardNames = []
     }
-    const sizeSink = { bytes: 0 }
     for (const name of shardNames) {
-      const shard = loadJson(path.join(this.dir, SHARDS_DIR, name), null, sizeSink)
+      const shard = loadJson(path.join(this.dir, SHARDS_DIR, name), null)
       if (!shard || typeof shard.relPath !== 'string' || !isRecord(shard.record)) continue
       this.files[shard.relPath] = shard.record
       // 畸形 shard（entries 被写成对象/null）不能让 allEntries() 在 `for…of` 上抛错，
@@ -256,11 +349,10 @@ export class ProjectMemoryStore {
       this.entries[shard.relPath] = list.map(stripPersistedDerived)
     }
     this._entriesVersion++
-    this.experience = loadJson(path.join(this.dir, EXPERIENCE_FILE), [], sizeSink)
-    this.tasks = loadJson(path.join(this.dir, TASKS_FILE), [], sizeSink)
-    this.binding = loadJson(path.join(this.dir, BINDING_FILE), {}, sizeSink)
-    this.watchlist = loadJson(path.join(this.dir, WATCH_FILE), [], sizeSink)
-    this._residentChars = sizeSink.bytes
+    this.experience = loadJson(path.join(this.dir, EXPERIENCE_FILE), [])
+    this.tasks = loadJson(path.join(this.dir, TASKS_FILE), [])
+    this.binding = loadJson(path.join(this.dir, BINDING_FILE), {})
+    this.watchlist = loadJson(path.join(this.dir, WATCH_FILE), [])
     this._formatWritten = existsSafe(path.join(this.dir, FORMAT_FILE))
   }
 
@@ -563,6 +655,24 @@ export class ProjectMemoryStore {
     return this._entriesVersion
   }
 
+  /**
+   * 这个 store 里有没有任何"事实"。
+   *
+   * 用于判断"值不值得为一条记账把它落盘"：一个从没被索引过、也没写过任何东西的根，
+   * 不该因为一次**全局** insight 命中就被建出一个 store 目录（审计侧同理，见 audit.js）。
+   * 刻意不调 `stats()`——那个会 `allEntries()` 物化 `searchText`。
+   */
+  get hasContent() {
+    return (
+      Object.keys(this.files).length > 0 ||
+      this.experience.length > 0 ||
+      this.tasks.length > 0 ||
+      this.insights.items.length > 0 ||
+      Object.keys(this.binding).length > 0 ||
+      this.watchlist.length > 0
+    )
+  }
+
   /** 还有多少个老分片等着被 save() 压实（0 = 存量已收敛）。 */
   get pendingCompaction() {
     return this._compactQueue.size
@@ -570,13 +680,20 @@ export class ProjectMemoryStore {
 
   allEntries() {
     const out = []
+    let materialized = 0
     for (const list of Object.values(this.entries)) {
       for (const entry of list) {
         // searchText 不落盘，首次用到时按需物化并挂在对象上（同一 entry 只算一次）。
-        if (entry.searchText === undefined) entry.searchText = makeSearchText(entry)
+        if (entry.searchText === undefined) {
+          entry.searchText = makeSearchText(entry)
+          materialized++
+        }
         out.push(entry)
       }
     }
+    // 物化只改 entry 对象、不改 entries 的构成，所以 `_entriesVersion` 不会动；但驻留会实打实
+    // 增加（70119 条目实测 +34MB）。这里是它的第二个失效键——漏了它，估算就停在物化前的水位。
+    if (materialized) this._materializeVersion++
     return out
   }
 

package/src/tools/index-repo.js

@@ -1,7 +1,7 @@
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import path from 'node:path'
 import { statSync } from 'node:fs'
-import { assertIndexRoot, assertSafeRoot, memoryRootFor, relativePath, scanLimits, storeKey, walkDir } from '../util/fs.js'
+import { assertIndexRoot, assertSafeRoot, memoryDirName, memoryRootFor, relativePath, scanLimits, storeKey, walkDir } from '../util/fs.js'
 import { DROP, OVERSIZE, UNCHANGED, commitFileUpdates, fileKind, planFileIndex, toFileUpdate } from '../index-pipeline.js'
 import { ProjectMemoryStore } from '../store.js'
 import { onFileIndexed, isTypeScriptFile } from '../enhancer.js'
@@ -38,7 +38,10 @@ export async function indexRepository(ctx, config, root, { reindex = false, allo
     batch = []
   }
 
-  const { files, truncated } = walkDir(root, scanLimits(config))
+  const { files, truncated, skipped: nestedRoots } = walkDir(root, {
+    ...scanLimits(config),
+    nestedStoreName: memoryDirName(config),
+  })
   for (const filePath of files) {
     const rel = storeKey(relativePath(root, filePath))
     seen.add(rel)
@@ -91,6 +94,13 @@ export async function indexRepository(ctx, config, root, { reindex = false, allo
       `\nscan truncated at the safety limit (maxFiles=${maxFiles}, maxDepth=${maxDepth}): only part of the tree was indexed.` +
       ' Raise maxScanFiles/maxScanDepth if this project is legitimately that large.'
   }
+  if (nestedRoots.length) {
+    const rels = nestedRoots.map((p) => storeKey(relativePath(root, p)))
+    report +=
+      `\nskipped ${nestedRoots.length} nested project root(s) with their own store: ${rels.join(', ')}` +
+      "\n(their content lives in their own root's index; this root keeps no duplicate copy)"
+    if (removed) report += `, ${removed} stale duplicate entr${removed === 1 ? 'y' : 'ies'} removed`
+  }
   if (failures.length) {
     report += `\nfailed to index ${failures.length} file(s): ${failures.join(', ')}`
   }

package/src/tools/query-memory.js

@@ -1,6 +1,6 @@
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import path from 'node:path'
-import { memoryRootFor, resolveSafeIndexRoot } from '../util/fs.js'
+import { memoryDirName, memoryRootFor, nestedStoreRoots, resolveSafeIndexRoot } from '../util/fs.js'
 import { ProjectMemoryStore, storeOverview } from '../store.js'
 import { expandQuery } from '../llm.js'
 import { resolveRoute } from '../llm-route.js'
@@ -13,6 +13,22 @@ function toAbs(root, rel) {
   return path.isAbsolute(rel) ? rel : path.join(root, rel)
 }
 
+/**
+ * 本根未命中记忆层时，把"这里有哪几个独立子索引"告诉模型。
+ *
+ * 父根不再重复保存子项目的内容（`walkDir()` 跳过自带 store 的嵌套根），所以"在父根下问子项目的
+ * 事"必然查不到；换 `root=` 再问一次是唯一正确的下一步。只在未命中时算，不在热路径上。
+ */
+function nestedIndexNote(root, config) {
+  const nested = nestedStoreRoots(root, memoryDirName(config))
+  if (!nested.length) return ''
+  return (
+    `\n\nNote: this root keeps no copy of ${nested.length} nested project(s) — each has its own index. ` +
+    'Re-run query_memory with `root: <path>` for the one you want:\n' +
+    nested.map((p) => `- ${p}`).join('\n')
+  )
+}
+
 export function queryMemoryTool(ctx, config) {
   return defineTool({
     name: 'query_memory',
@@ -66,6 +82,8 @@ export function queryMemoryTool(ctx, config) {
       const boundTaskId = sessionId && typeof store.getBoundTaskId === 'function' ? store.getBoundTaskId(sessionId) : null
       const globalStore = new GlobalStore(cfgInsight(config).globalFile || defaultGlobalFile()).load()
       const wantMemory = type === 'all' || type === 'doc' || type === 'symbol'
+      /** 本根记忆层（doc/symbol）的命中数：0 且存在子索引时，末尾要指路。 */
+      let memHitCount = 0
       const wantInsight = type === 'all' || type === 'insight'
       // 一次 recall 覆盖全部层：doc/symbol/experience/insight 共用同一个检索核心（src/recall.js）。
       const recalled = recallItems({
@@ -100,6 +118,7 @@ export function queryMemoryTool(ctx, config) {
           .flatMap((l) => l.hits)
           .sort((a, b) => b.weightedScore - a.weightedScore)
           .slice(0, limit)
+        memHitCount = memHits.length
         if (memHits.length) {
           const top = memHits[0].weightedScore || 1
           lines.push(`## Memory (${type === 'all' ? 'docs + symbols' : type})`)
@@ -196,12 +215,16 @@ export function queryMemoryTool(ctx, config) {
             : overview.latest
               ? `, last indexed at ${overview.latest}. Use memory_stats to see what the store contains.`
               : '. Use memory_stats to see what the store contains.'
+        const nestedNote = wantMemory && memHitCount === 0 ? nestedIndexNote(root, config) : ''
         return (
           `No memory matches for "${args.query}" in ${root}. ${hint}\n` +
-          `Store overview: ${overview.files} files indexed, ${overview.entries} entries, ${overview.experience} experience notes${tail}`
+          `Store overview: ${overview.files} files indexed, ${overview.entries} entries, ${overview.experience} experience notes${tail}${nestedNote}`
         )
       }
-      return truncate(lines.join('\n\n'), config.maxOutputChars)
+      // 提示放在**最前**：`truncate()` 截的是尾部，而 insight/procedure 类条目单条就能到 600+
+      // 字符，放末尾会被整段截掉（实测 8000 字符预算下必被截）。
+      const note = wantMemory && memHitCount === 0 ? nestedIndexNote(root, config).trimStart() + '\n\n' : ''
+      return truncate(note + lines.join('\n\n'), config.maxOutputChars)
     },
   })
 }

package/src/util/fs.js

@@ -130,11 +130,62 @@ export function scanLimits(config) {
  *   - `truncated` 让调用方区分「这棵树扫完了」和「只扫了一部分」——后者绝不能拿
  *     本轮未见到的文件去删旧条目（见 index-repo/watch 的 unseen 用法）。
  */
+/**
+ * 一个目录是否**自带 store**（即它自己已经是一个被索引过的项目根）。
+ *
+ * 判据用 `format.json`：任何走过一次 `save()` 的 store 都必然有它，而误建/刚建的空
+ * `.dsh-project-memory` 目录没有——那种不能作为跳过的依据，否则父 store 一跳过，内容两头都没了。
+ */
+export function hasOwnStore(dir, memoryDirName) {
+  return existsSync(path.join(dir, memoryDirName, 'format.json'))
+}
+
+/**
+ * 列出 `root` 下**自带 store** 的子目录 —— 也就是"这部分内容有自己的独立索引"。
+ *
+ * 存在的理由：`walkDir()` 会跳过这些子树（父根不再重复保存它们的内容），于是"在父根下问子项目
+ * 的事"必须换个 `root=` 再问一次。这个函数就是用来在**查询未命中时给模型指路**的，不是文件系统
+ * 巡检：BFS、限深 3 层、最多列 8 个、最多看 300 个目录，且不往已知的子根里下探。
+ */
+export function nestedStoreRoots(root, memoryDirName, { maxDepth = 3, maxEntries = 8, maxVisited = 300 } = {}) {
+  const found = []
+  const queue = [[root, 0]]
+  let visited = 0
+  while (queue.length && found.length < maxEntries && visited < maxVisited) {
+    const [dir, depth] = queue.shift()
+    visited++
+    let entries
+    try {
+      entries = readdirSync(dir, { withFileTypes: true })
+    } catch {
+      continue
+    }
+    for (const entry of entries) {
+      if (found.length >= maxEntries) break
+      if (!entry.isDirectory() || entry.name.startsWith('.')) continue
+      if (DEFAULT_IGNORE.has(entry.name)) continue
+      const full = path.join(dir, entry.name)
+      if (hasOwnStore(full, memoryDirName)) {
+        found.push(full)
+        continue // 已知的子根不再往里下探
+      }
+      if (depth + 1 <= maxDepth) queue.push([full, depth + 1])
+    }
+  }
+  return found.sort()
+}
+
 export function walkDir(root, opts = {}) {
   const ignoreNames = opts.ignoreNames || DEFAULT_IGNORE
   const maxFiles = Number.isFinite(opts.maxFiles) && opts.maxFiles > 0 ? opts.maxFiles : Infinity
   const maxDepth = Number.isFinite(opts.maxDepth) && opts.maxDepth > 0 ? opts.maxDepth : Infinity
+  // 传 memoryDir 名即开启「嵌套根不重复索引」：子目录自带 store 时不再往下走。
+  // 理由是跟解析规则保持一致——`findProjectRoot()` 对子树里的文件返回的正是那个子根，
+  // 扫描也该同意这一点；否则父根会把子项目的全部内容再存一份（实测 `/home/sxt/project`
+  // 的 store 里 9075/9081 个文件是子根 store 的重复副本）。
+  const nestedStoreName = opts.nestedStoreName || null
   const out = []
+  const skipped = []
   const stack = [[root, 0]]
   let truncated = false
   let hitFileCap = false
@@ -151,6 +202,10 @@ export function walkDir(root, opts = {}) {
       const full = path.join(dir, entry.name)
       if (entry.isDirectory()) {
         if (ignoreNames.has(entry.name)) continue
+        if (nestedStoreName && hasOwnStore(full, nestedStoreName)) {
+          skipped.push(full)
+          continue
+        }
         if (depth + 1 > maxDepth) {
           truncated = true
           continue
@@ -168,7 +223,8 @@ export function walkDir(root, opts = {}) {
     if (hitFileCap) break
   }
   out.sort()
-  return { files: out, truncated }
+  skipped.sort()
+  return { files: out, truncated, skipped }
 }
 
 export function isSupportedDoc(ext) {
@@ -206,6 +262,14 @@ export function memoryRootFor(indexRoot, memoryDir) {
   return path.join(indexRoot, memoryDir)
 }
 
+/** store 目录名（配置项 `memoryDir`；调用方可能来自工具参数，缺省时兜底成默认值）。 */
+export const DEFAULT_MEMORY_DIR = '.dsh-project-memory'
+
+export function memoryDirName(config) {
+  const raw = config?.memoryDir
+  return typeof raw === 'string' && raw.trim() ? raw : DEFAULT_MEMORY_DIR
+}
+
 /**
  * 危险根目录：整体扫描/监听它们会直接吃满内存（issue #5 实测把 DSH 撑死的就是
  * 家目录与 `/opt/homebrew`）。判定是**精确匹配**：只拒绝这些目录**本身**，不拒绝

package/src/watch.js

@@ -1,6 +1,6 @@
 import { existsSync, statSync } from 'node:fs'
 import path from 'node:path'
-import { isUnsafeRoot, memoryRootFor, relativePath, scanLimits, storeKey, walkDir } from './util/fs.js'
+import { isUnsafeRoot, memoryDirName, memoryRootFor, relativePath, scanLimits, storeKey, walkDir } from './util/fs.js'
 import { OVERSIZE, UNCHANGED, commitFileUpdates, fileKind, planFileIndex, toFileUpdate } from './index-pipeline.js'
 import { ProjectMemoryStore } from './store.js'
 import { onFileChanged, isTypeScriptFile } from './enhancer.js'
@@ -13,6 +13,8 @@ export class WatchManager {
     this.timer = null
     this._polling = false
     this._truncationWarned = new Set()
+    /** 已就「跳过了嵌套项目根」告警过的根：同上，只提示一次。 */
+    this._nestedStoreWarned = new Set()
   }
 
   /** 包含该路径的已注册根（最长前缀）：懒索引据此把文件归到显式 watch 过的无标记项目里。 */
@@ -64,8 +66,11 @@ export class WatchManager {
     // 文件系统根 / 家目录 / 系统前缀不整体监听（它们的子目录允许），除非显式放行。
     if (!this.unsafeAllowed() && isUnsafeRoot(root)) return false
     if (!this.roots.has(root)) {
+      // **不在这里 load()**：`restorePersisted()` 会对 cwd store 的整条 watchlist 逐个 addRoot，
+      // 急切读盘等于「watch 过多少个根，启动就同步读多少个 store 的全部 shard」——一个万文件
+      // 的 store 就是秒级，几十个根就是启动卡死 + 内存无上界。这里只登记，store 到第一次
+      // pollRoot 真正需要时才取（见 `storeFor`）。
       this.roots.set(root, {
-        store: new ProjectMemoryStore(memoryRootFor(root, this.config.memoryDir)).load(),
         snapshot: {},
         // rel → 上次已上报的错误信息。坏文件每轮都会重试，逐轮打印会刷屏。
         failures: new Map(),
@@ -75,6 +80,21 @@ export class WatchManager {
     return false
   }
 
+  /**
+   * 每个根**按需**取 store：命中 `storeCache` 时是 O(1)（一次 Map 查找 + LRU 挪位）。
+   *
+   * 刻意不让本类长期持有实例。旧实现把 `store` 塞进 `this.roots` 里，等于给每个 watch 根
+   * 加了一个**进程级强引用**，于是：
+   *   - 逐出对 watch 根完全不省内存（`storeCache` 丢了 key，watcher 还攥着）；
+   *   - 一旦真被逐出，下一次 `load()` 会从盘上**再建一份**，同一个 root 在同一进程里出现两份
+   *     互不可见的内存状态，两份各自 `save()` 脏分片 → 最后写者赢，存在丢更新的窗口。
+   * 现在唯一的活实例就是缓存里那一个：逐出即真正释放，下一轮 poll 重新读盘（缓存该有的语义），
+   * 而内存上界回到 `STORE_CACHE_MAX_BYTES`，不再由「watch 了多少个根」决定。
+   */
+  storeFor(root) {
+    return new ProjectMemoryStore(memoryRootFor(root, this.config.memoryDir)).load()
+  }
+
   removeRoot(root) {
     return this.roots.delete(root)
   }
@@ -142,8 +162,22 @@ export class WatchManager {
     const updates = []
     // rel → 本轮采集的 mtime:size。提交成功后才落进快照；CAS 失败的条目留在原地等下一轮。
     const signatures = new Map()
+    // 本轮用的 store：命中缓存即 O(1)，被逐出则重新读盘。整个 pollRoot 期间共用同一个实例。
+    const store = this.storeFor(root)
 
-    const { files, truncated } = walkDir(root, scanLimits(this.config))
+    const { files, truncated, skipped: nestedRoots } = walkDir(root, {
+      ...scanLimits(this.config),
+      nestedStoreName: memoryDirName(this.config),
+    })
+    if (nestedRoots.length && !this._nestedStoreWarned.has(root)) {
+      // 同上，只提示一次。这里同时说明"旧副本会被本轮清掉"——升级后的存量重复就是这么收敛的。
+      this._nestedStoreWarned.add(root)
+      const rels = nestedRoots.map((p) => storeKey(relativePath(root, p)))
+      console.error(
+        `[dsh-project-memory] watch of ${root} skips nested project root(s) with their own store: ${rels.join(', ')}; ` +
+          'their content is refreshed by their own root, and any duplicate copy previously indexed here is being removed.',
+      )
+    }
     if (truncated && !this._truncationWarned.has(root)) {
       // 只提示一次：这是一条**永久**的降级说明，不是每轮都要刷屏的故障。
       this._truncationWarned.add(root)
@@ -169,7 +203,7 @@ export class WatchManager {
       const sig = `${stats.mtimeMs}:${stats.size}`
       if (state.snapshot[rel] === sig) continue
 
-      const record = state.store.fileRecord(rel)
+      const record = store.fileRecord(rel)
       let plan
       try {
         plan = await planFileIndex({
@@ -178,7 +212,7 @@ export class WatchManager {
           kind,
           config: this.config,
           record,
-          existingEntries: state.store.entries[rel],
+          existingEntries: store.entries[rel],
           size: stats.size,
         })
       } catch (err) {
@@ -204,7 +238,7 @@ export class WatchManager {
     // 单事务写盘；CAS 失败的条目本轮不落快照，下一轮自然重试。
     // 截断时**不传 unseen**：没扫到的文件不等于被删了，否则一份被上限截掉的树每轮都会
     // 把自己的记忆删掉一半（先删再下轮重新索引，纯粹的抖动）。
-    const { stale, removed } = commitFileUpdates(state.store, {
+    const { stale, removed } = commitFileUpdates(store, {
       updates,
       unseen: truncated ? null : seen,
     })
@@ -217,7 +251,7 @@ export class WatchManager {
       if (update.type !== 'code') continue
       const filePath = path.join(root, update.rel)
       if (isTypeScriptFile(filePath)) {
-        onFileChanged(state.store, update.rel, filePath, this.config, root)
+        onFileChanged(store, update.rel, filePath, this.config, root)
       }
     }
     // 有变化 → 下一轮回到 base 间隔；纯空转 → 退避。