@yolk_vat-y/dsh-project-memory 0.1.5 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## 0.2.0 (2026-08-27)
+
+### CJK 检索增强
+- 链接侧：非拉丁符号名改用 CJK 边界正则 `(?<![CJK])名(?![CJK])`，解决 `用户服务` 误链 `用户服务管理器`；英文分支零改动
+- 查询侧：BM25 增加精确短语乘法加分 —— 3+ 字 CJK 短语命中 `title`/`keywords` 时 `score *= 1.5` 并重排，自适应不压过高相关结果
+- 查询侧：同义词表（`数据库连接池` ↔ `连接池` ↔ `DB pool`），查询展开后再走短语加分
+
+### 经验笔记 supersede 阈值收紧
+- 双向重叠判定：`overlap / query_tokens ≥ 0.7` 且 `overlap / item_tokens ≥ 0.7`（原单向 0.6），减少短问题误吞长笔记
+
+## 0.1.6 (2026-08-25)
+
+### 存储
+- 存储布局升级 v2（分片式）：`entries.json` 拆为 `shards/` 下每源文件一个自描述分片（relPath + 元数据 + 条目），单文件索引只写自己的分片，不再全量序列化；同进程内所有工具共享每项目单一 store 实例，热路径无全量读写
+- 旧布局自动幂等迁移：首次加载检测旧 `entries.json`/`index.json` 即迁移为分片并移除旧文件，中途崩溃可安全重试
+- watchlist/experience 写入改脏标记驱动，未变更不落盘
+
+### 新增
+- 新工具 `memory_stats`：列出记忆库总量（文件 / 条目 / 经验笔记）、最近索引时间与逐文件清单（Top 30），不看 JSON 即可回答"记忆库里有什么"
+- `query_memory` 无命中时输出追加库存概况（N 文件 / M 条目 / K 经验笔记 / 最近索引时间），可区分"没索引过"和"索引了但没命中"
+
+### 性能/质量
+- JS/TS 与 Python 符号扫描器重写：字符级字符串/注释掩码（不再误扫字符串与注释里的伪声明）、多行签名续行、Python 缩进感知（此前缩进的类方法全部漏报）、JS 类方法上下文识别；零新增依赖
+- Go/Rust/C 系/Shell 补上同款掩码（含 Rust 嵌套块注释、生命周期标记、Shell `${#}` 边界）
+- doc↔symbol 链接对纯拉丁符号名启用词边界匹配：符号名 `run` 不再命中文档里的 `runtime`
+- 修复掩码状态跨行泄漏：正则字面量里的引号、未闭合的单行字符串不再污染后续行
+- README「已知限制」改为「设计取舍」框架，每条补充动机与边界说明
+
+- 修复分片增量写引入的回归：`linkedSymbols` 在 `save()` 之后才计算，第二次 save 变 no-op 导致链接只存在于进程内存、重启即丢；对齐为链接后统一落盘
+- 新增跨进程磁盘级回归测试：直接读分片文件断言链接已持久化
+
+### 测试
+- 测试从 121 项增至 146 项：扫描器掩码/续行/方法识别、存储迁移/分片/缓存语义、无命中内省、stats 工具、链接落盘探针
+- JS/TS 与 Python 符号扫描器重写：字符级字符串/注释掩码（不再误扫字符串与注释里的伪声明）、多行签名续行、Python 缩进感知（此前缩进的类方法全部漏报）、JS 类方法上下文识别；零新增依赖
+- Go/Rust/C 系/Shell 暂维持行级正则扫描
+- 存量索引按内容哈希增量更新，升级后未变更的文件保持旧扫描结果；需要立即重建请用 `index_repo` 的 `reindex: true`
+
 ## 0.1.5 (2026-08-25)
 
 ### 修复

package/README.md

@@ -11,7 +11,7 @@ Persistent project memory for [DeepSeek Harness](https://github.com/deepseek-ai/
 ## Features
 
 - **Document indexing** — PDF, Markdown, and plain text files are chunked and summarized by the LLM; each entry carries a `path:line` citation back to the source.
-- **Code symbol table** — function and class names are extracted with a lightweight regex scanner, without LLM token usage.
+- **Code symbol table** — function, class, and method names are extracted by a dependency-free source scanner (string/comment masking, multi-line signature joining, indentation-aware Python, class-method context), without LLM token usage.
 - **Automatic refresh** — a background poll (`watch_repo`) detects new or changed files by content hash and re-indexes only those.
 - **Read-time indexing** — files are indexed the moment the model actually reads them (`fs/observed`), so the index is a byproduct of normal work, not a separate upfront scan. Files that are never read are never indexed. The project root is detected by markers (`.git`, `package.json`, …), a README plus source directories, or the file's own directory as a last resort.
 - **Doc ↔ code cross-linking** — when a document mentions a symbol, the match is recorded as a `reference`; querying a symbol also surfaces the documents that describe it.
@@ -52,7 +52,7 @@ dsh plugin --profile web add @yolk_vat-y/dsh-project-memory -w
 A prebuilt tarball is published with each release, installable without a build step:
 
 ```bash
-dsh plugin --profile web add /path/to/dsh-project-memory-0.1.5.tgz
+dsh plugin --profile web add /path/to/dsh-project-memory-0.1.6.tgz
 ```
 
 Each indexed project has its own store at `<root>/.dsh-project-memory/`. Add it to `.gitignore` if it should not be committed.
@@ -66,6 +66,7 @@ The tools below are **invoked by the agent**, not typed by the user. In the chat
 | `index_doc file_path` | Index one document (PDF/MD/txt): chunk → LLM summary → store with `path:line`. Unchanged files are skipped. |
 | `index_repo root` | Index a whole project: docs get LLM summaries, code files get a zero-token symbol table. Incremental, cleans up deleted files, cross-links docs to symbols. |
 | `watch_repo root` | Enable automatic refresh: a background poll detects new/changed files (mtime + content hash) and re-indexes only those. Watched roots persist across plugin restarts. |
+| `memory_stats root` | Show what the store contains: totals (files / entries / experience notes), last index time, and the per-file list sorted by recency. |
 | `query_memory query` | BM25 search over docs + symbols + experience, optionally query-expanded by the LLM. Returns ranked hits with relative scores, sources, and doc→symbol references. |
 | `remember problem solution` | Save an experience note. Similar problems supersede instead of duplicating. |
 | `forget id_or_query` | Delete stale experience notes. |
@@ -74,25 +75,30 @@ The tools below are **invoked by the agent**, not typed by the user. In the chat
 
 ```
 .dsh-project-memory/
-  index.json       file-level content-hash map (incremental)
-  entries.json     doc summaries + symbol table entries, keyed by file
+  format.json      layout marker (v2, sharded)
+  shards/          one self-describing JSON per indexed source file
+                   ({ relPath, record, entries }) — writes touch only dirty shards
   experience.json  problem → solution notes (retrieval-only)
   watch.json       watched roots
 ```
 
+Stores created before v0.2.0 (single `entries.json` / `index.json`) migrate automatically and idempotently on first load. Within one dsh process, all tool calls share a single in-memory store per project, so hot-path indexing writes only the shard that changed.
+
 - **Incremental** — content hash per file; only changed files are re-extracted.
 - **Cross-linking** — after indexing, doc summaries are matched against symbol names; matches are attached to the doc entry as `references` and surfaced by `query_memory`.
 - **Query expansion** — when `llmQueryExpansion` is on, `query_memory` asks `ctx.llm` to rewrite the query into several variants (synonyms, EN/CN, identifier guesses) and merges BM25 scores across variants; when off, queries never touch the LLM. Cross-language recall (a Chinese question hitting English content) comes from index time instead: doc keywords are required to cover the document's own language AND English, and doc↔symbol links surface English symbol names from Chinese hits.
 - **Consistency** — the fact layer follows the codebase (hash re-extract / remove-on-delete); the experience layer is retrieval-only with supersede and `forget`. Store writes are serialized per memory directory; the lock is in-process, so avoid running multiple dsh instances against the same project store concurrently.
 
-## Known limitations
+## Design tradeoffs
+
+These are deliberate scope choices.
 
-- **In-process locking** — store writes are serialized per memory directory within one dsh process; two dsh instances sharing a project store is last-writer-wins.
-- **Watch poll holds the lock** — while the watcher re-indexes changed docs (LLM summarization), `remember`/`forget` queue behind it. Overlapping polls serialize on the same lock: safe, but they can pile up on very large diffs.
-- **Silent corruption recovery** — a corrupt store JSON falls back to empty for that file and is rebuilt on the next write; the broken file is renamed to `*.corrupt` with an error logged, but its data cannot be recovered.
+- **In-process locking** — store writes are serialized per memory directory within one dsh process; two dsh instances sharing a project store is last-writer-wins. A cross-process lock would need a resident daemon, which conflicts with the pure-JS, no-background-service positioning, so multi-instance writes are explicitly unsupported.
+- **Watch poll holds the lock** — while the watcher re-indexes changed docs (LLM summarization), `remember`/`forget` queue behind it. Polling (mtime + content hash) instead of `fs.watch` events keeps behavior consistent across platforms; overlapping polls serialize on the same lock: safe, but they can pile up on very large diffs. Tune via `watchInterval`.
+- **Corrupt files are quarantined** — a store JSON that fails to parse falls back to empty for that file and is rebuilt on the next write; the broken file is renamed to `*.corrupt` with an error logged, but its data cannot be recovered. Auto-repairing partial writes would need a write-ahead journal or an embedded database — out of proportion when quarantining one bad file costs nothing.
 - **Absolute source paths** — entries cite absolute paths; moving a project invalidates citations until the next re-index.
 - **`forget` by query is eager** — keyword deletion matches at ≥0.5 token overlap and may remove several notes at once; prefer deleting by id for precision.
-- **Cross-language recall depends on index time** — with `llmQueryExpansion` off, a Chinese-only query reaches English content through bilingual keywords captured when docs are indexed, plus doc↔symbol links. Stores indexed before v0.1.1 gain bilingual keywords as files change, or immediately via `index_repo` with `reindex: true`.
+- **Cross-language recall depends on index time** — with `llmQueryExpansion` off, a Chinese-only query reaches English content through bilingual keywords captured when docs are indexed, plus doc↔symbol links; queries stay LLM-free. Stores indexed before v0.1.1 gain bilingual keywords as files change, or immediately via `index_repo` with `reindex: true`.
 
 ## Configuration
 
@@ -143,7 +149,7 @@ These commands are for **maintaining the plugin code** — regular users do not
 
 ```bash
 npm install
-npm test          # 101 checks: chunker / symbols / store / tools / BM25 / links / watch / lazy / config / dump / concurrency / restore / size limit
+npm test          # chunker / symbols / store / tools / BM25 / links / watch / lazy / config / dump / concurrency / restore / size limit
 ```
 
 ## License

package/README.zh-CN.md

@@ -11,7 +11,7 @@
 ## 特性
 
 - **文档索引** — PDF、Markdown、纯文本按块切分并由 LLM 生成摘要，每条索引携带 `路径:行号` 引用回源文件。
-- **代码符号表** — 通过轻量正则扫描提取函数与类名，不使用 LLM token。
+- **代码符号表** — 通过零依赖的源码扫描器提取函数、类与方法名（字符串/注释掩码、多行签名续行、Python 缩进感知、类方法上下文），不使用 LLM token。
 - **自动刷新** — `watch_repo` 后台轮询，按内容哈希识别新增或变更文件，仅重抽这些文件。
 - **读到即索引** — 文件在模型**实际读取的瞬间**被索引（监听 `fs/observed`），索引是正常工作的副产品，而非额外的一次全量扫描。从未读过的文件不会被索引。项目根通过标记（`.git`、`package.json` 等）、README 加源码目录、或兜底到文件所在目录逐级识别。
 - **文档 ↔ 代码交叉链接** — 文档提及某符号时记录为 `reference`；查询符号时同时带出描述该符号的文档。
@@ -52,7 +52,7 @@ dsh plugin --profile web add @yolk_vat-y/dsh-project-memory -w
 每个版本会附带预构建 tarball，无需构建步骤即可安装：
 
 ```bash
-dsh plugin --profile web add /path/to/dsh-project-memory-0.1.5.tgz
+dsh plugin --profile web add /path/to/dsh-project-memory-0.1.6.tgz
 ```
 
 每个被索引的项目在 `<root>/.dsh-project-memory/` 下有独立存储。如无需入库，可加入 `.gitignore`。
@@ -66,6 +66,7 @@ dsh plugin --profile web add /path/to/dsh-project-memory-0.1.5.tgz
 | `index_doc file_path` | 索引单个文档（PDF/MD/txt）：分块 → LLM 摘要 → 带 `路径:行号` 入库。未变更文件自动跳过。 |
 | `index_repo root` | 索引整个项目：文档由 LLM 生成摘要，代码文件生成零 token 符号表。增量更新、清理已删除文件、文档与符号交叉链接。 |
 | `watch_repo root` | 启用自动刷新：后台轮询检测新增/变更文件（mtime + 内容哈希），仅重抽这些文件。监听的项目在插件重启后自动恢复。 |
+| `memory_stats root` | 查看记忆库内容：总量（文件 / 条目 / 经验笔记）、最近索引时间，以及按时间排序的逐文件清单。 |
 | `query_memory query` | 对文档、符号、经验执行 BM25 检索，可选 LLM 查询扩展。返回带相对分数（0-100）、引用与文档→符号链接的排序结果。 |
 | `remember problem solution` | 保存经验笔记。相似问题覆盖而非重复。 |
 | `forget id_or_query` | 删除过期经验笔记。 |
@@ -74,25 +75,30 @@ dsh plugin --profile web add /path/to/dsh-project-memory-0.1.5.tgz
 
 ```
 .dsh-project-memory/
-  index.json       文件级内容哈希表（增量）
-  entries.json     文档摘要 + 符号表条目，按文件
+  format.json      布局标记（v2，分片式）
+  shards/          每个被索引源文件一个自描述 JSON
+                   （{ relPath, record, entries }）——写入只落脏分片
   experience.json  问题 → 方案笔记（仅检索）
   watch.json       被监听根目录
 ```
 
+v0.2.0 之前创建的库（单文件 `entries.json` / `index.json`）在首次加载时自动幂等迁移。同一个 dsh 进程内，所有工具调用共享每个项目的单一内存 store 实例，热路径索引只写发生变化的那一个分片。
+
 - **增量** — 按文件内容哈希，仅重新抽取变更文件。
 - **交叉链接** — 索引后将文档摘要与符号名匹配，命中符号以 `references` 挂载到文档条目，由 `query_memory` 带出。
 - **查询扩展** — `llmQueryExpansion` 开启时，`query_memory` 让 `ctx.llm` 将查询改写为多个变体（同义词、中英、符号名猜测），再跨变体合并 BM25 分数；关闭时查询完全不碰 LLM。跨语种召回（中文问题命中英文内容）改由索引时承担：文档 keywords 要求同时覆盖文档语言与英文，doc↔symbol 链接也会从中文命中带出英文符号名。
 - **一致性** — 事实层跟随代码库（哈希重抽 / 删除即移除）；经验层仅检索，配合覆盖与 `forget` 机制。每个记忆目录的写入按进程内互斥锁串行化；请避免多个 dsh 实例同时写同一项目存储。
 
-## 已知限制
+## 设计取舍
+
+以下是刻意的范围选择。
 
-- **进程内锁** — 存储写入按记忆目录在一个 dsh 进程内串行化；两个 dsh 实例共享同一项目存储时后写覆盖先写。
-- **watch 轮询持锁** — watcher 重索引变更文档（LLM 摘要）期间，`remember`/`forget` 会排队等待。重叠轮询靠同一把锁串行：安全，但大改动时可能堆积。
-- **损坏静默重建** — 存储 JSON 损坏时该文件回落为空并在下次写入时重建；坏文件会改名备份为 `*.corrupt` 并输出错误日志，但该文件内的数据无法恢复。
+- **进程内锁** — 存储写入按记忆目录在一个 dsh 进程内串行化；两个 dsh 实例共享同一项目存储时后写覆盖先写。跨进程锁需要常驻守护进程，违背纯 JS 插件、无后台服务的定位，故明确不支持多实例共写。
+- **watch 轮询持锁** — watcher 重索引变更文档（LLM 摘要）期间，`remember`/`forget` 会排队等待。轮询（mtime + 内容哈希）而非 `fs.watch` 事件驱动，是为了跨平台行为一致；重叠轮询靠同一把锁串行：安全，但大改动时可能堆积。间隔可用 `watchInterval` 调整。
+- **损坏隔离重建** — 存储 JSON 损坏时该文件回落为空并在下次写入时重建；坏文件会改名备份为 `*.corrupt` 并输出错误日志，但该文件内的数据无法恢复。自动修复半写文件需要预写日志或嵌入式数据库，代价与收益不成比例——而隔离一个坏文件的成本几乎为零。
 - **绝对路径引用** — 条目引用绝对路径；项目搬家后引用失效，重建索引即恢复。
 - **`forget` 按关键词删除偏激进** — 关键词删除按 ≥0.5 token 重叠匹配，可能一次删掉多条；追求精确请用 id 删除。
-- **跨语种召回依赖索引时** — `llmQueryExpansion` 关闭时，纯中文查询靠索引时捕获的双语 keywords 和 doc↔symbol 链接触达英文内容。v0.1.1 之前建立的索引随文件变更逐步获得双语关键词，或用 `index_repo` 的 `reindex: true` 立即重建。
+- **跨语种召回依赖索引时** — `llmQueryExpansion` 关闭时，纯中文查询靠索引时捕获的双语 keywords 和 doc↔symbol 链接触达英文内容，查询侧保持零 LLM 调用。v0.1.1 之前建立的索引随文件变更逐步获得双语关键词，或用 `index_repo` 的 `reindex: true` 立即重建。
 
 ## 配置
 
@@ -143,7 +149,7 @@ dsh web --patch ./config.yml
 
 ```bash
 npm install
-npm test          # 101 项检查：chunker / symbols / store / tools / BM25 / links / watch / lazy / config / dump / concurrency / restore / size limit
+npm test          # 检查项：chunker / symbols / store / tools / BM25 / links / watch / lazy / config / dump / concurrency / restore / size limit
 ```
 
 ## 许可证

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yolk_vat-y/dsh-project-memory",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "description": "Persistent project memory for dsh agents: index docs (PDF/Markdown/text) and code symbols into a searchable per-workspace store, recall them with cited sources, and keep experience entries (problems -> solutions) searchable on demand.",
   "type": "module",
   "main": "src/index.js",

package/src/index.js

@@ -5,6 +5,7 @@ import { queryMemoryTool } from './tools/query-memory.js'
 import { rememberTool } from './tools/remember.js'
 import { forgetTool } from './tools/forget.js'
 import { watchRepoTool } from './tools/watch-repo.js'
+import { statsTool } from './tools/stats.js'
 import { WatchManager } from './watch.js'
 import { setupLazyIndexing } from './lazy.js'
 
@@ -46,6 +47,7 @@ export function apply(ctx, config) {
   ctx.tools.register(rememberTool(config))
   ctx.tools.register(forgetTool(config))
   ctx.tools.register(watchRepoTool(watchManager, config))
+  ctx.tools.register(statsTool(config))
 
   if (config.autoIndexOnFirstUse) {
     ctx.effect(async () => {

package/src/lazy.js

@@ -122,9 +122,8 @@ export async function indexFile(ctx, config, filePath, watchManager = null) {
       store.markFile(rel, { sha256: hash, size, type: 'doc', indexedAt: new Date().toISOString() })
     }
     store.setEntries(rel, entries)
+    linkEntries(store)
     store.save()
-    const links = linkEntries(store)
-    if (links) store.save()
     return true
   })
 }

package/src/link.js

@@ -1,9 +1,13 @@
 const LATIN_NAME = /^[A-Za-z0-9_]+$/
+const CJK_CHAR = /[\u3400-\u9fff\uf900-\ufaff\u3040-\u309f\u30a0-\u30ff\uac00-\ud7af]/
 
 function buildMatcher(name) {
   const lower = name.toLowerCase()
-  if (!LATIN_NAME.test(name)) return { lower, re: null }
-  return { lower, re: new RegExp(`(?<![a-z0-9_$])${lower}(?![a-z0-9_$])`) }
+  if (LATIN_NAME.test(name)) {
+    return { lower, re: new RegExp(`(?<![a-z0-9_$])${lower}(?![a-z0-9_$])`) }
+  }
+  const escaped = lower.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  return { lower, re: new RegExp(`(?<!${CJK_CHAR.source})${escaped}(?!${CJK_CHAR.source})`) }
 }
 
 export function linkEntries(store) {

package/src/store.js

@@ -1,14 +1,17 @@
+import { createHash, randomUUID } from 'node:crypto'
 import { mkdirSync, readFileSync, readdirSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs'
-import { randomUUID } from 'node:crypto'
 import path from 'node:path'
 import { rankEntries, rankExperience, tokenize } from './util/search.js'
 
+const FORMAT_FILE = 'format.json'
 const INDEX_FILE = 'index.json'
 const ENTRIES_FILE = 'entries.json'
 const EXPERIENCE_FILE = 'experience.json'
 const WATCH_FILE = 'watch.json'
+const SHARDS_DIR = 'shards'
 
 const dirLocks = new Map()
+const storeCache = new Map()
 
 export async function withStoreLock(memoryDir, fn) {
   const key = path.resolve(memoryDir)
@@ -64,6 +67,10 @@ function writeJsonAtomic(filePath, data) {
   }
 }
 
+function shardRelPath(dir, rel) {
+  return path.join(dir, SHARDS_DIR, createHash('sha256').update(rel).digest('hex') + '.json')
+}
+
 export class ProjectMemoryStore {
   constructor(memoryDir) {
     this.dir = memoryDir
@@ -71,31 +78,100 @@ export class ProjectMemoryStore {
     this.entries = {}
     this.experience = []
     this.watchlist = []
+    this._dirtyShards = new Set()
+    this._removedShards = new Set()
+    this._dirtyExperience = false
+    this._dirtyWatch = false
+    this._formatWritten = false
   }
 
   load() {
-    const index = loadJson(path.join(this.dir, INDEX_FILE), {})
-    this.files = index.files || {}
-    this.entries = loadJson(path.join(this.dir, ENTRIES_FILE), {})
-    this.experience = loadJson(path.join(this.dir, EXPERIENCE_FILE), [])
-    this.watchlist = loadJson(path.join(this.dir, WATCH_FILE), [])
+    const key = path.resolve(this.dir)
+    const hot = storeCache.get(key)
+    if (hot && hot !== this) return hot
+    this._migrateLegacyIfNeeded()
+    this._loadSharded()
+    storeCache.set(key, this)
     return this
   }
 
-  cleanStaleTmp() {
-    let entries
+  _migrateLegacyIfNeeded() {
+    const formatPath = path.join(this.dir, FORMAT_FILE)
+    if (loadJson(formatPath, null)?.version === 2) {
+      // 迁移在“写完标记、删旧文件前”崩溃会留下死文件；这里顺手清掉
+      for (const stale of [path.join(this.dir, ENTRIES_FILE), path.join(this.dir, INDEX_FILE)]) {
+        if (existsSafe(stale)) {
+          try {
+            unlinkSync(stale)
+            console.error(`[dsh-project-memory] removed leftover legacy file ${path.basename(stale)} after migration`)
+          } catch {
+            // locked or gone; will be retried next load
+          }
+        }
+      }
+      return
+    }
+    const legacyEntriesPath = path.join(this.dir, ENTRIES_FILE)
+    if (!existsSafe(legacyEntriesPath)) return
+    const index = loadJson(path.join(this.dir, INDEX_FILE), {})
+    const files = index.files || {}
+    const entries = loadJson(legacyEntriesPath, {})
+    const orphans = Object.keys(entries).filter((rel) => !(rel in files))
+    if (orphans.length) {
+      console.error(
+        `[dsh-project-memory] migration dropped ${orphans.length} entry group(s) with no index record: ${orphans.slice(0, 3).join(', ')}${orphans.length > 3 ? ' …' : ''}`,
+      )
+    }
+    mkdirSync(path.join(this.dir, SHARDS_DIR), { recursive: true })
+    for (const rel of Object.keys(files)) {
+      writeJsonAtomic(shardRelPath(this.dir, rel), { relPath: rel, record: files[rel], entries: entries[rel] || [] })
+    }
+    writeJsonAtomic(formatPath, { version: 2, layout: 'sharded' })
+    for (const stale of [legacyEntriesPath, path.join(this.dir, INDEX_FILE)]) {
+      try {
+        unlinkSync(stale)
+      } catch {
+        // already renamed away by corrupt backup, or gone; nothing to do
+      }
+    }
+    console.error(`[dsh-project-memory] migrated legacy store at ${this.dir} to sharded layout (${Object.keys(files).length} files)`)
+  }
+
+  _loadSharded() {
+    let shardNames = []
     try {
-      entries = readdirSync(this.dir)
+      shardNames = readdirSync(path.join(this.dir, SHARDS_DIR)).filter((n) => n.endsWith('.json'))
     } catch {
-      return
+      shardNames = []
     }
+    for (const name of shardNames) {
+      const shard = loadJson(path.join(this.dir, SHARDS_DIR, name), null)
+      if (!shard || typeof shard.relPath !== 'string' || !shard.record) continue
+      this.files[shard.relPath] = shard.record
+      this.entries[shard.relPath] = shard.entries || []
+    }
+    this.experience = loadJson(path.join(this.dir, EXPERIENCE_FILE), [])
+    this.watchlist = loadJson(path.join(this.dir, WATCH_FILE), [])
+    this._formatWritten = existsSafe(path.join(this.dir, FORMAT_FILE))
+  }
+
+  cleanStaleTmp() {
+    const scanDirs = [this.dir, path.join(this.dir, SHARDS_DIR)]
     const now = Date.now()
-    for (const name of entries) {
-      if (!name.endsWith('.tmp')) continue
+    for (const dir of scanDirs) {
+      let entries
       try {
-        if (now - statSync(path.join(this.dir, name)).mtimeMs > 60000) unlinkSync(path.join(this.dir, name))
+        entries = readdirSync(dir)
       } catch {
-        // already gone or locked; skip
+        continue
+      }
+      for (const name of entries) {
+        if (!name.endsWith('.tmp')) continue
+        try {
+          if (now - statSync(path.join(dir, name)).mtimeMs > 60000) unlinkSync(path.join(dir, name))
+        } catch {
+          // already gone or locked; skip
+        }
       }
     }
   }
@@ -103,26 +179,61 @@ export class ProjectMemoryStore {
   save() {
     mkdirSync(this.dir, { recursive: true })
     this.cleanStaleTmp()
-    writeJsonAtomic(path.join(this.dir, INDEX_FILE), { version: 1, files: this.files })
-    writeJsonAtomic(path.join(this.dir, ENTRIES_FILE), this.entries)
-    writeJsonAtomic(path.join(this.dir, EXPERIENCE_FILE), this.experience)
-    writeJsonAtomic(path.join(this.dir, WATCH_FILE), this.watchlist)
+    if (!this._formatWritten) {
+      writeJsonAtomic(path.join(this.dir, FORMAT_FILE), { version: 2, layout: 'sharded' })
+      this._formatWritten = true
+    }
+    for (const rel of this._dirtyShards) {
+      if (this.files[rel]) {
+        mkdirSync(path.join(this.dir, SHARDS_DIR), { recursive: true })
+        writeJsonAtomic(shardRelPath(this.dir, rel), { relPath: rel, record: this.files[rel], entries: this.entries[rel] || [] })
+      } else {
+        this._removedShards.add(rel)
+      }
+    }
+    this._dirtyShards.clear()
+    for (const rel of this._removedShards) {
+      try {
+        unlinkSync(shardRelPath(this.dir, rel))
+      } catch {
+        // shard file already gone; nothing to do
+      }
+    }
+    this._removedShards.clear()
+    if (this._dirtyExperience) {
+      writeJsonAtomic(path.join(this.dir, EXPERIENCE_FILE), this.experience)
+      this._dirtyExperience = false
+    }
+    if (this._dirtyWatch) {
+      writeJsonAtomic(path.join(this.dir, WATCH_FILE), this.watchlist)
+      this._dirtyWatch = false
+    }
   }
 
   addWatch(root) {
     if (!this.watchlist.includes(root)) {
       this.watchlist.push(root)
+      this._dirtyWatch = true
       return true
     }
     return false
   }
 
+  removeWatch(root) {
+    const before = this.watchlist.length
+    this.watchlist = this.watchlist.filter((r) => r !== root)
+    if (this.watchlist.length !== before) this._dirtyWatch = true
+    return before !== this.watchlist.length
+  }
+
   fileRecord(relPath) {
     return this.files[relPath]
   }
 
   markFile(relPath, record) {
     this.files[relPath] = record
+    this._dirtyShards.add(relPath)
+    this._removedShards.delete(relPath)
   }
 
   setEntries(relPath, entries) {
@@ -131,11 +242,17 @@ export class ProjectMemoryStore {
     } else {
       delete this.entries[relPath]
     }
+    this._dirtyShards.add(relPath)
+    this._removedShards.delete(relPath)
   }
 
   removeFile(relPath) {
-    delete this.files[relPath]
-    delete this.entries[relPath]
+    if (relPath in this.files) {
+      delete this.files[relPath]
+      delete this.entries[relPath]
+      this._dirtyShards.add(relPath)
+      this._removedShards.add(relPath)
+    }
   }
 
   allEntries() {
@@ -158,11 +275,13 @@ export class ProjectMemoryStore {
       existing.solution = solution
       if (sourceFile) existing.sourceFile = sourceFile
       existing.updatedAt = now
+      this._dirtyExperience = true
       return { id: existing.id, superseded: true }
     }
     const id = randomUUID()
     this.experience.push({ id, problem, solution, sourceFile, createdAt: now, updatedAt: now })
     this.pruneExperience()
+    this._dirtyExperience = true
     return { id, superseded: false }
   }
 
@@ -184,8 +303,10 @@ export class ProjectMemoryStore {
     for (const item of this.experience) {
       const itemTokens = tokenize(item.problem)
       const overlap = itemTokens.filter((t) => tokens.includes(t)).length
-      const base = Math.min(tokens.length, itemTokens.length)
-      if (base && overlap / base >= 0.6 && overlap > bestOverlap) {
+      if (overlap === 0) continue
+      const ratioQuery = overlap / tokens.length
+      const ratioItem = overlap / itemTokens.length
+      if (ratioQuery >= 0.7 && ratioItem >= 0.7 && overlap > bestOverlap) {
         best = item
         bestOverlap = overlap
       }
@@ -207,6 +328,7 @@ export class ProjectMemoryStore {
         return overlap / Math.min(tokens.length, itemTokens.length) < 0.5
       })
     }
+    if (this.experience.length !== before) this._dirtyExperience = true
     return before - this.experience.length
   }
 
@@ -218,3 +340,25 @@ export class ProjectMemoryStore {
     }
   }
 }
+
+function existsSafe(p) {
+  try {
+    statSync(p)
+    return true
+  } catch {
+    return false
+  }
+}
+
+export function storeOverview(store) {
+  let latest = null
+  for (const rec of Object.values(store.files)) {
+    if (rec.indexedAt && (!latest || rec.indexedAt > latest)) latest = rec.indexedAt
+  }
+  return {
+    files: Object.keys(store.files).length,
+    entries: store.allEntries().length,
+    experience: store.experience.length,
+    latest,
+  }
+}

package/src/symbols.js

@@ -9,6 +9,93 @@ const SHELL = new Set(['.sh', '.zsh'])
 
 const CONTROL = new Set(['if', 'for', 'while', 'switch', 'catch', 'return', 'foreach', 'using', 'lock', 'var', 'function'])
 
+const JS_MASKER = { lineComment: '//', blockStart: '/*', blockEnd: '*/', quotes: ['`', '"', "'"], multilineQuotes: ['`'] }
+const PY_MASKER = { lineComment: '#', blockStart: null, blockEnd: null, quotes: ['"""', "'''", '"', "'"], multilineQuotes: ['"""', "'''"] }
+const GO_MASKER = { lineComment: '//', blockStart: '/*', blockEnd: '*/', quotes: ['`', '"'], multilineQuotes: ['`'] }
+const RUST_MASKER = { lineComment: '//', blockStart: '/*', blockEnd: '*/', blockNested: true, quotes: ['"'], multilineQuotes: [] }
+const C_FAMILY_MASKER = { lineComment: '//', blockStart: '/*', blockEnd: '*/', quotes: ['"', "'"], multilineQuotes: [] }
+const SHELL_MASKER = { lineComment: '#', lineCommentBoundary: true, blockStart: null, blockEnd: null, quotes: ["'", '"'], multilineQuotes: [] }
+
+function maskTokens(lines, { lineComment, lineCommentBoundary = false, blockStart, blockEnd, blockNested = false, quotes, multilineQuotes = [] }) {
+  const out = new Array(lines.length)
+  let mode = 'code'
+  let blockDepth = 0
+  const blank = (n) => ' '.repeat(n)
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    let res = ''
+    let j = 0
+    while (j < line.length) {
+      if (mode === 'code') {
+        if (lineComment && line.startsWith(lineComment, j)) {
+          if (!lineCommentBoundary || j === 0 || /\s/.test(line[j - 1])) {
+            res += blank(line.length - j)
+            break
+          }
+        }
+        if (blockStart && line.startsWith(blockStart, j)) {
+          mode = blockEnd
+          blockDepth = 1
+          j += blockStart.length
+          res += blank(blockStart.length)
+          continue
+        }
+        const quote = quotes.find((q) => line.startsWith(q, j))
+        if (quote) {
+          mode = quote
+          j += quote.length
+          res += blank(quote.length)
+          continue
+        }
+        res += line[j]
+        j++
+      } else if (quotes.includes(mode)) {
+        if (line[j] === '\\') {
+          j += 2
+          res += '  '
+          continue
+        }
+        if (line.startsWith(mode, j)) {
+          j += mode.length
+          res += blank(mode.length)
+          mode = 'code'
+          continue
+        }
+        res += ' '
+        j++
+      } else {
+        if (blockNested && blockStart && line.startsWith(blockStart, j)) {
+          blockDepth++
+          res += blank(blockStart.length)
+          j += blockStart.length
+          continue
+        }
+        if (line.startsWith(mode, j)) {
+          j += mode.length
+          res += blank(mode.length)
+          if (blockNested && blockDepth > 1) blockDepth--
+          else mode = 'code'
+          continue
+        }
+        res += ' '
+        j++
+      }
+    }
+    if (mode && quotes.includes(mode) && !multilineQuotes.includes(mode)) mode = 'code'
+    out[i] = res
+  }
+  return out
+}
+
+function balanceDelta(text) {
+  let delta = 0
+  for (const ch of text) {
+    if (ch === '(') delta++
+    else if (ch === ')') delta--
+  }
+  return delta
+}
+
 function matchJsLike(line) {
   let m = line.match(/^export\s+(?:default\s+)?(?:async\s+)?(?:function\s+([A-Za-z_$][\w$]*)|class\s+([A-Za-z_$][\w$]*))/)
   if (m) return { name: m[1] || m[2], kind: m[1] ? 'function' : 'class' }
@@ -18,19 +105,74 @@ function matchJsLike(line) {
   if (m) return { name: m[1], kind: 'class' }
   m = line.match(/^(?:export\s+)?const\s+([A-Za-z_$][\w$]*)\s*=\s*(?:async\s*)?\(/)
   if (m) return { name: m[1], kind: 'function' }
+  m = line.match(/^(?:export\s+)?const\s+([A-Za-z_$][\w$]*)\s*=\s*(?:async\s*)?(?:\([^)]*\)|[A-Za-z_$][\w$]*)\s*=>/)
+  if (m) return { name: m[1], kind: 'function' }
   m = line.match(/^(?:export\s+)?(?:async\s+)?function\s*\(/) // anonymous
   if (m) return { name: '(anonymous)', kind: 'function' }
   return null
 }
 
-function matchPython(line) {
-  let m = line.match(/^class\s+(\w+)\s*(?:\(|:)/)
-  if (m) return { name: m[1], kind: 'class' }
-  m = line.match(/^def\s+(\w+)\s*\(/)
-  if (m) return { name: m[1], kind: 'function' }
-  m = line.match(/^async\s+def\s+(\w+)\s*\(/)
-  if (m) return { name: m[1], kind: 'function' }
-  return null
+const JS_DECL_START = /^(?:export\s+)?(?:default\s+)?(?:async\s+)?(?:function\b|class\b|const\b)/
+
+const JS_NON_METHOD = new Set([
+  'if', 'else', 'for', 'foreach', 'while', 'do', 'switch', 'case', 'default',
+  'try', 'catch', 'finally', 'return', 'throw', 'break', 'continue',
+  'new', 'delete', 'typeof', 'instanceof', 'void', 'await', 'yield', 'with',
+])
+
+function scanJsLike(masked, filePath, rawLines) {
+  const symbols = []
+  let prevOpensBlock = false
+  for (let i = 0; i < masked.length; i++) {
+    const text = masked[i].trim()
+    if (!text) continue
+    let matched = null
+    if (prevOpensBlock) {
+      const method = text.match(/^([A-Za-z_$][\w$]*)\s*(?:<[^<>]*>)?\s*\(([^()]*)\)\s*(?::\s*[^={]{1,80})?\{/)
+      if (method && !JS_NON_METHOD.has(method[1])) matched = { name: method[1], kind: 'method' }
+    }
+    if (!matched) matched = matchJsLike(text)
+    if (!matched && JS_DECL_START.test(text)) {
+      let joined = text
+      let extra = 0
+      for (let j = i + 1; j < masked.length && extra < 3; j++) {
+        const tail = masked[j].trim()
+        if (!tail) continue
+        joined += ' ' + tail
+        extra++
+        matched = matchJsLike(joined)
+        if (matched) {
+          i = j
+          break
+        }
+        if (/[{};]/.test(tail)) break
+      }
+    }
+    if (matched) symbols.push(buildSymbol(matched, filePath, rawLines[i], i + 1))
+    prevOpensBlock = masked[i].trim().endsWith('{')
+  }
+  return symbols
+}
+
+function scanPython(masked, filePath, rawLines) {
+  const symbols = []
+  let depth = 0
+  for (let i = 0; i < masked.length; i++) {
+    const text = masked[i].trim()
+    const delta = balanceDelta(text)
+    if (depth > 0) {
+      depth += delta
+      continue
+    }
+    let matched = null
+    const fn = text.match(/^(?:async\s+)?def\s+(\w+)\s*\(/)
+    const cls = fn ? null : text.match(/^class\s+(\w+)\s*[(:]/)
+    if (fn) matched = { name: fn[1], kind: 'function' }
+    else if (cls) matched = { name: cls[1], kind: 'class' }
+    if (matched) symbols.push(buildSymbol(matched, filePath, rawLines[i], i + 1))
+    depth += delta
+  }
+  return symbols
 }
 
 function matchGo(line) {
@@ -44,7 +186,7 @@ function matchGo(line) {
 }
 
 function matchRust(line) {
-  let m = line.match(/^(?:pub(?:\([^)]*\))?\s+)?(?:async\s+)?fn\s+([A-Za-z_]\w*)\s*\(/)
+  let m = line.match(/^(?:pub(?:\([^)]*\))?\s+)?(?:async\s+)?fn\s+([A-Za-z_]\w*)\s*(?:<[^<>]*>)?\s*\(/)
   if (m) return { name: m[1], kind: 'function' }
   m = line.match(/^(?:pub\s+)?(?:struct|enum|trait|impl)\s+(\w+)/)
   if (m) return { name: m[1], kind: line.includes('impl') ? 'impl' : 'type' }
@@ -66,36 +208,46 @@ function matchShell(line) {
   return m ? { name: m[1], kind: 'function' } : null
 }
 
+function buildSymbol(matched, filePath, rawLine, lineNo) {
+  return {
+    id: `${String(filePath).replace(/[\\/:\s]/g, '_')}#${lineNo}`,
+    sourcePath: filePath,
+    sourceLine: lineNo,
+    type: 'symbol',
+    title: `${matched.name} (${matched.kind})`,
+    summary: `${matched.kind} "${matched.name}" declared at ${filePath}:${lineNo}`,
+    keywords: [matched.name, matched.kind],
+    text: String(rawLine).trim().slice(0, 200),
+  }
+}
+
 export function scanSymbols(filePath, content) {
   const ext = filePath.slice(filePath.lastIndexOf('.'))
-  const symbols = []
   const lines = content.split(/\r?\n/)
-  for (let i = 0; i < lines.length; i++) {
+  if (JS_LIKE.has(ext)) return scanJsLike(maskTokens(lines, JS_MASKER), filePath, lines)
+  if (PYTHON.has(ext)) return scanPython(maskTokens(lines, PY_MASKER), filePath, lines)
+
+  let masker = null
+  if (GO.has(ext)) masker = GO_MASKER
+  else if (RUST.has(ext)) masker = RUST_MASKER
+  else if (C_FAMILY.has(ext)) masker = C_FAMILY_MASKER
+  else if (SHELL.has(ext)) masker = SHELL_MASKER
+  const masked = masker ? maskTokens(lines, masker) : lines
+
+  const symbols = []
+  for (let i = 0; i < masked.length; i++) {
     const raw = lines[i]
-    const line = raw.replace(/\/\/.*$/, '').replace(/#.*$/, '').trim()
+    const line = masked[i].trim()
     if (!line) continue
     let matched = null
-    if (JS_LIKE.has(ext)) matched = matchJsLike(line)
-    else if (PYTHON.has(ext)) matched = matchPython(line)
-    else if (GO.has(ext)) matched = matchGo(line)
+    if (GO.has(ext)) matched = matchGo(line)
     else if (RUST.has(ext)) matched = matchRust(line)
     else if (C_FAMILY.has(ext)) matched = matchCFamily(line)
     else if (SHELL.has(ext)) matched = matchShell(line)
     else if (/^(?:def|func|fn|function)\s+(\w+)/.test(line)) {
       matched = { name: line.match(/^(?:def|func|fn|function)\s+(\w+)/)[1], kind: 'function' }
     }
-    if (matched) {
-      symbols.push({
-        id: `${String(filePath).replace(/[\\/:\s]/g, '_')}#${i + 1}`,
-        sourcePath: filePath,
-        sourceLine: i + 1,
-        type: 'symbol',
-        title: `${matched.name} (${matched.kind})`,
-        summary: `${matched.kind} "${matched.name}" declared at ${filePath}:${i + 1}`,
-        keywords: [matched.name, matched.kind],
-        text: raw.trim().slice(0, 200),
-      })
-    }
+    if (matched) symbols.push(buildSymbol(matched, filePath, raw, i + 1))
   }
   return symbols
 }

package/src/tools/index-doc.js

@@ -56,9 +56,8 @@ export function indexDocTool(ctx, config) {
         }
         store.setEntries(rel, entries)
         store.markFile(rel, { sha256: hash, size, type: 'doc', indexedAt: new Date().toISOString() })
+        linkEntries(store)
         store.save()
-        const links = linkEntries(store)
-        if (links) store.save()
 
         const preview = entries
           .map((e) => `  - ${e.title} @ ${rel}:${e.sourceLine}`)

package/src/tools/index-repo.js

@@ -81,9 +81,8 @@ export async function indexRepository(ctx, config, root, { reindex = false } = {
       }
     }
 
-    store.save()
     const links = linkEntries(store)
-    if (links) store.save()
+    store.save()
     const stats = store.stats()
     let report =
       `Indexed project: ${root}\n` +

package/src/tools/query-memory.js

@@ -1,6 +1,6 @@
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import { memoryRootFor, resolveIndexRoot } from '../util/fs.js'
-import { ProjectMemoryStore } from '../store.js'
+import { ProjectMemoryStore, storeOverview } from '../store.js'
 import { expandQuery } from '../llm.js'
 import { rankEntriesMergedScored, rankExperienceScored } from '../util/search.js'
 import { truncate } from '../util/text.js'
@@ -87,7 +87,23 @@ export function queryMemoryTool(ctx, config) {
       }
 
       if (!lines.length) {
-        return `No memory matches for "${args.query}" in ${root}. Index it first with index_repo / index_doc, or note a fix with remember.`
+        const overview = storeOverview(store)
+        const hint =
+          type === 'experience'
+            ? 'Note a fix with remember so it can be recalled next time.'
+            : type === 'all'
+              ? 'Index it first with index_repo / index_doc, or note a fix with remember.'
+              : 'Index it first with index_repo / index_doc.'
+        const tail =
+          overview.files === 0
+            ? '. The store has never been indexed.'
+            : 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.'
+        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}`
+        )
       }
       return truncate(lines.join('\n\n'), config.maxOutputChars)
     },

package/src/tools/stats.js

@@ -0,0 +1,45 @@
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { memoryRootFor, resolveIndexRoot } from '../util/fs.js'
+import { ProjectMemoryStore, storeOverview } from '../store.js'
+import { truncate } from '../util/text.js'
+
+const TOP_N = 30
+
+export function statsTool(config) {
+  return defineTool({
+    name: 'memory_stats',
+    description:
+      'Show what the project memory store contains: totals (files / entries / experience notes), last index time, ' +
+      'and the per-file list with entry counts sorted by most recently indexed. Use this to answer "what is in my memory store" without reading JSON files.',
+    parameters: {
+      root: {
+        type: 'string',
+        description: 'Project root of the memory store. Defaults to the current working directory.',
+      },
+    },
+    output: {
+      schema: { type: 'string' },
+      render: (_args, value) => [{ type: 'text', text: value }],
+    },
+    async execute(args, exec) {
+      const root = resolveIndexRoot(exec, args.root)
+      const store = new ProjectMemoryStore(memoryRootFor(root, config.memoryDir)).load()
+      const overview = storeOverview(store)
+      const files = Object.entries(store.files).sort((a, b) => String(b[1].indexedAt || '').localeCompare(String(a[1].indexedAt || '')))
+      const lines = [
+        `Memory store: ${store.dir}`,
+        `Files indexed: ${overview.files} | Entries: ${overview.entries} | Experience notes: ${overview.experience}`,
+        overview.latest ? `Last index: ${overview.latest}` : 'Last index: never',
+      ]
+      if (files.length) {
+        lines.push('')
+        for (const [rel, rec] of files.slice(0, TOP_N)) {
+          const count = (store.entries[rel] || []).length
+          lines.push(`- ${rel} [${rec.type}] entries: ${count}, indexed at ${rec.indexedAt || 'unknown'}`)
+        }
+        if (files.length > TOP_N) lines.push(`- ... ${files.length - TOP_N} more files`)
+      }
+      return truncate(lines.join('\n'), config.maxOutputChars)
+    },
+  })
+}

package/src/tools/watch-repo.js

@@ -36,15 +36,14 @@ export function watchRepoTool(watchManager, config) {
           if (path.resolve(sessionMemoryDir) === path.resolve(memoryDir)) return
           await withStoreLock(sessionMemoryDir, () => {
             const sessionStore = new ProjectMemoryStore(sessionMemoryDir).load()
-            const before = sessionStore.watchlist.length
-            sessionStore.watchlist = sessionStore.watchlist.filter((r) => r !== root)
-            if (present) sessionStore.addWatch(root)
-            if (sessionStore.watchlist.length !== before || present) sessionStore.save()
+            const removed = sessionStore.removeWatch(root)
+            const added = present ? sessionStore.addWatch(root) : false
+            if (removed || added) sessionStore.save()
           })
         }
         if (args.watch === false) {
           watchManager.removeRoot(root)
-          store.watchlist = store.watchlist.filter((r) => r !== root)
+          store.removeWatch(root)
           store.save()
           await mirrorSessionWatchlist(false)
           return `Stopped watching: ${root}`

package/src/util/search.js

@@ -1,6 +1,42 @@
 export const CJK_RANGE =
   /[\u3400-\u9fff\uf900-\ufaff\u3040-\u309f\u30a0-\u30ff\uac00-\ud7af]/
 
+const SYNONYMS = new Map([
+  ['数据库连接池', ['连接池', 'DB pool', 'db pool']],
+  ['连接池', ['数据库连接池', 'DB pool', 'db pool']],
+  ['DB pool', ['数据库连接池', '连接池']],
+  ['db pool', ['数据库连接池', '连接池']],
+])
+
+function extractCjkPhrases(text) {
+  const phrases = []
+  let run = ''
+  for (const ch of text) {
+    if (CJK_RANGE.test(ch)) {
+      run += ch
+    } else if (run.length >= 3) {
+      phrases.push(run)
+      run = ''
+    } else {
+      run = ''
+    }
+  }
+  if (run.length >= 3) phrases.push(run)
+  return phrases
+}
+
+function expandQuery(query) {
+  const lower = query.toLowerCase()
+  const expanded = new Set([lower])
+  for (const [key, vals] of SYNONYMS) {
+    if (lower.includes(key.toLowerCase())) {
+      for (const v of vals) expanded.add(v.toLowerCase())
+    }
+  }
+  const cjkPhrases = extractCjkPhrases(query)
+  return { original: lower, expanded: [...expanded], cjkPhrases }
+}
+
 export function tokenizeRaw(text) {
   if (!text) return []
   const lower = text.toLowerCase()
@@ -43,7 +79,9 @@ export function buildBm25(docs, getFieldText) {
     const terms = tokenizeRaw(text)
     const tf = {}
     for (const t of terms) tf[t] = (tf[t] || 0) + 1
-    return { doc, length: terms.length, tf }
+    const title = (doc.title || '').toLowerCase()
+    const keywords = (doc.keywords || []).join(' ').toLowerCase()
+    return { doc, length: terms.length, tf, title, keywords }
   })
   const df = {}
   for (const d of documents) {
@@ -55,7 +93,12 @@ export function buildBm25(docs, getFieldText) {
   return {
     idf,
     score(query) {
-      const q = tokenize(query)
+      const { expanded, cjkPhrases } = expandQuery(query)
+      const qTokens = new Set()
+      for (const term of expanded) {
+        for (const tok of tokenizeRaw(term)) qTokens.add(tok)
+      }
+      const q = [...qTokens]
       if (!q.length) return []
       const avgLen = avgdl
       return documents
@@ -67,6 +110,12 @@ export function buildBm25(docs, getFieldText) {
             if (!tf) continue
             score += idf(t) * ((tf * (K1 + 1)) / (tf + K1 * (1 - B + (B * len) / avgLen)))
           }
+          for (const phrase of cjkPhrases) {
+            const lowerPhrase = phrase.toLowerCase()
+            if (d.title.includes(lowerPhrase) || d.keywords.includes(lowerPhrase)) {
+              score *= 1.5
+            }
+          }
           return { doc: d.doc, score }
         })
         .filter((r) => r.score > 0)