thincoder 0.8.2 → 0.8.4

package/src/memory/code-index.mjs

@@ -1,10 +1,10 @@
 /**
- * memory/code-index.mjs — 代码和文档的分块、语言检测、符号提取
+ * memory/code-index.mjs — code and document chunking, language detection, symbol extraction
  */
 
 import { segmentCJK, CODE_EXTS, DOC_EXTS, SKIP_DIRS, BIG_FILE_LINES } from "./schema.mjs"
 
-/** 推断文件语言（按扩展名） */
+/** Infer file language by extension */
 export function detectLanguage(filename) {
   const ext = filename.slice(filename.lastIndexOf(".")).toLowerCase()
   const map = {
@@ -21,8 +21,8 @@ export function detectLanguage(filename) {
 }
 
 /**
- * 用正则提取 JS/TS 文件的顶层符号声明（函数、类、const 导出等）。
- * 返回 [{ name, line, kind }]。
+ * Extract top-level symbol declarations (functions, classes, const exports, etc.)
+ * from JS/TS files using regex. Returns [{ name, line, kind }].
  */
 export function extractSymbols(lines, ext) {
   const jsish = new Set([".mjs", ".js", ".ts", ".jsx", ".tsx"])
@@ -41,7 +41,7 @@ export function extractSymbols(lines, ext) {
   return symbols
 }
 
-/** 提取 Python 文件的顶层 def/class。 */
+/** Extract top-level def/class from Python files. */
 export function extractPySymbols(lines) {
   const symbols = []
   const re = /^(?:async\s+)?(?:def|class)\s+(\w+)/gm
@@ -54,8 +54,9 @@ export function extractPySymbols(lines) {
 }
 
 /**
- * 将一个文件拆成代码块。小文件整文件一块；大文件按符号切分，符号间的内容并入前一个符号块。
- * 每个块会额外带上符号前的 JSDoc / docstring 注释，提升搜索质量。
+ * Split a file into code chunks. Small files become a single chunk;
+ * large files are split by symbol, with inter-symbol content merged into the preceding symbol chunk.
+ * Each chunk includes the JSDoc/docstring before its symbol to improve search quality.
  */
 export function chunkCode(lines, filepath) {
   const ext = filepath.slice(filepath.lastIndexOf(".")).toLowerCase()
@@ -91,9 +92,9 @@ export function chunkCode(lines, filepath) {
 }
 
 /**
- * 提取指定行之前的 JSDoc / docstring 注释。
- * JS/TS: 向前扫描 /** ... *​/ 或 // 连续注释行
- * Python: 符号定义行的下一行开始找 """...""" docstring
+ * Extract the JSDoc/docstring comment preceding a given line.
+ * JS/TS: scan backwards for JSDoc block comments or consecutive // comment lines
+ * Python: look for a """...""" docstring on the line after the symbol definition
  */
 export function extractLeadingDoc(lines, lineNum, ext) {
   if (ext === ".py") {
@@ -139,12 +140,12 @@ export function extractLeadingDoc(lines, lineNum, ext) {
   return text.length > 0 && text.length < 300 ? text : ""
 }
 
-/** 将控制权交还给事件循环一个 tick（让键盘输入有机会被处理） */
+/** Yield control to the event loop for one tick (allows keyboard input to be processed) */
 export function yieldTick() {
   return new Promise((r) => setTimeout(r, 0))
 }
 
-/** 单文件入索引：删除旧块 → 分块 → 插入新块 */
+/** Index a single file: delete old chunks → chunk → insert new chunks */
 export function _upsertCodeFile(memory, origin, rel, lines, lang, mtimeMs) {
   const chunks = chunkCode(lines, rel)
   memory.db.exec("BEGIN")
@@ -166,8 +167,8 @@ export function _upsertCodeFile(memory, origin, rel, lines, lang, mtimeMs) {
 }
 
 /**
- * 按 ## 标题切分 markdown 文件。每个 ## section 独立入索引，
- * 标题路径做 heading（如 "README.md > 部署 > Docker"），方便检索定位。
+ * Split a markdown file by ## headings. Each ## section is indexed independently,
+ * with the heading path as the heading label (e.g. "README.md > Deployment > Docker") for easy retrieval.
  */
 export function chunkMarkdown(lines, filepath) {
   const chunks = []
@@ -190,6 +191,7 @@ export function chunkMarkdown(lines, filepath) {
   return chunks.filter((c) => c.content)
 }
 
+/** Upsert a documentation file's chunks into the doc_chunks table within a transaction */
 export function _upsertDocFile(memory, origin, rel, lines, mtimeMs) {
   const chunks = chunkMarkdown(lines, rel)
   const lang = rel.endsWith(".rst") ? "rst" : rel.endsWith(".adoc") ? "asciidoc" : rel.endsWith(".txt") ? "text" : "markdown"

package/src/memory/code-sync.mjs

@@ -1,18 +1,22 @@
 /**
- * memory/code-sync.mjs — 代码索引同步、检索、增量更新
+ * memory/code-sync.mjs — code index sync, retrieval, incremental update
  */
 
 import { readFile, stat } from "node:fs/promises"
 import { join, relative } from "node:path"
 import { embed, cosine, toBlob, fromBlob } from "../embedding.mjs"
 import { CODE_EXTS, DOC_EXTS, SKIP_DIRS } from "./schema.mjs"
-import { buildFtsQuery, ensureEmbeddings } from "./core.mjs"
+import { buildFtsQuery, ensureEmbeddings, EMBED_TEXT_MAX_LEN } from "./core.mjs"
 import { detectLanguage, _upsertCodeFile, _upsertDocFile, yieldTick } from "./code-index.mjs"
 
+const DIFF_FULL_SYNC_THRESHOLD = 200
+const CODE_EMBED_BATCH = 64
+
 /**
- * git 驱动增量索引：用 git diff 找出上次索引以来的变更文件，
- * 只重建这些文件的 FTS5 块（不碰向量）。比全量 mtime 扫描快一个数量级。
- * 返回 { updated, removed, skipped } 或 null（git 不可用）。
+ * git-driven incremental indexing: use git diff to find files changed since
+ * the last index, and only rebuild FTS5 chunks for those files (vectors are untouched).
+ * An order of magnitude faster than full mtime scanning.
+ * Returns { updated, removed, skipped } or null (git unavailable).
  */
 export async function gitSync(memory, dir, { onProgress } = {}) {
   const { execSync, execFileSync } = await import("node:child_process")
@@ -34,8 +38,8 @@ export async function gitSync(memory, dir, { onProgress } = {}) {
     return null
   }
 
-  if (diffOut.length > 200) {
-    // diff 太大，增量没意义——回退全量同步并更新锚点
+  if (diffOut.length > DIFF_FULL_SYNC_THRESHOLD) {
+    // diff too large, incremental is useless — fall back to full sync and update anchor
     await codeSync(memory, dir, { onProgress })
     const { docSync } = await import("./docs.mjs")
     await docSync(memory, dir, { onProgress })
@@ -60,11 +64,11 @@ export async function gitSync(memory, dir, { onProgress } = {}) {
       if (CODE_EXTS.has(ext)) {
         const lang = detectLanguage(abs)
         let mtimeMs = 0
-        try { mtimeMs = Math.floor((await stat(abs)).mtimeMs) } catch { /* 新文件 */ }
+        try { mtimeMs = Math.floor((await stat(abs)).mtimeMs) } catch { /* new file */ }
         _upsertCodeFile(memory, dir, rel, lines, lang, mtimeMs)
       } else {
         let mtimeMs = 0
-        try { mtimeMs = Math.floor((await stat(abs)).mtimeMs) } catch { /* 新文件 */ }
+        try { mtimeMs = Math.floor((await stat(abs)).mtimeMs) } catch { /* new file */ }
         _upsertDocFile(memory, dir, rel, lines, mtimeMs)
       }
       updated++
@@ -94,8 +98,8 @@ export async function gitSync(memory, dir, { onProgress } = {}) {
 }
 
 /**
- * 同步代码索引：扫描 dir 下所有源文件 → 分块 → upsert 到 code_chunks。
- * 按 mtime 增量——只重建变更过的文件块。
+ * Sync code index: scan all source files under dir → chunk → upsert into code_chunks.
+ * Incremental by mtime — only rebuilds chunks for files that have changed.
  */
 export async function codeSync(memory, dir, { onProgress } = {}) {
   const files = []
@@ -165,19 +169,19 @@ export async function codeSync(memory, dir, { onProgress } = {}) {
   return { updated, removed, skipped, failed, errors, total: files.length }
 }
 
-/** 记录当前 HEAD 作为索引锚点（gitSync 增量 diff 基准）；非 git 仓库静默跳过 */
+/** Record current HEAD as the index anchor (gitSync incremental diff baseline); silently skip non-git repos */
 export async function markIndexedCommit(memory, dir) {
   try {
     const { execSync } = await import("node:child_process")
     const head = execSync("git rev-parse HEAD", { cwd: dir, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 5000 }).trim()
     memory.db.prepare(`INSERT INTO meta (key, value) VALUES ('last_indexed_commit', ?)
       ON CONFLICT (key) DO UPDATE SET value = excluded.value`).run(head)
-  } catch { /* 非 git 仓库或 git 不可用，跳过 */ }
+  } catch { /* not a git repo or git unavailable, skip */ }
 }
 
 /**
- * 代码检索：FTS5(BM25) + 可选向量余弦，RRF 合并。
- * 无 embedder 时退化为纯 FTS；ftsQuery 为空且有 embedder 时退化为纯向量。
+ * Code search: FTS5(BM25) + optional vector cosine, RRF merged.
+ * Falls back to pure FTS when no embedder; falls back to pure vector when ftsQuery is empty and embedder is present.
  */
 export async function codeSearch(memory, query, { limit = 5 } = {}) {
   const ftsQuery = buildFtsQuery(query)
@@ -219,14 +223,20 @@ export async function codeSearch(memory, query, { limit = 5 } = {}) {
   const fetchChunk = memory.db.prepare(`
     SELECT path, language, symbol_name, content, line_start, line_end FROM code_chunks WHERE rowid = ?
   `)
-  return [...scores.entries()]
+  const sorted = [...scores.entries()]
     .sort((a, b) => b[1] - a[1])
     .slice(0, limit)
-    .map(([rowid]) => fetchChunk.get(rowid))
+  return sorted
+    .map(([rowid, score]) => {
+      const chunk = fetchChunk.get(rowid)
+      if (!chunk) return null
+      chunk._score = Math.round(score * 100) / 100
+      return chunk
+    })
     .filter(Boolean)
 }
 
-/** 惰性补算 code_chunks 缺失的向量 */
+/** Lazily backfill missing vectors for code_chunks */
 export async function ensureCodeEmbeddings(memory) {
   if (!memory.embedder) return
   const modelKey = memory.embedder.model
@@ -237,17 +247,17 @@ export async function ensureCodeEmbeddings(memory) {
       ON CONFLICT (key) DO UPDATE SET value = excluded.value`).run(modelKey)
   }
 
-  const pending = memory.db.prepare(`SELECT rowid, path, symbol_name, content FROM code_chunks WHERE embedding IS NULL LIMIT 64`).all()
+  const pending = memory.db.prepare(`SELECT rowid, path, symbol_name, content FROM code_chunks WHERE embedding IS NULL LIMIT ${CODE_EMBED_BATCH}`).all()
   if (pending.length === 0) return
 
-  const texts = pending.map((r) => `${r.path}${r.symbol_name ? " :: " + r.symbol_name : ""}\n${r.content.slice(0, 2000)}`)
+  const texts = pending.map((r) => `${r.path}${r.symbol_name ? " :: " + r.symbol_name : ""}\n${r.content.slice(0, EMBED_TEXT_MAX_LEN)}`)
   const vecs = await embed(memory.embedder, texts)
 
   const update = memory.db.prepare(`UPDATE code_chunks SET embedding = ? WHERE rowid = ?`)
   pending.forEach((r, i) => update.run(toBlob(vecs[i]), r.rowid))
 }
 
-/** 生成 code_search 工具（只读）。 */
+/** Generate the code_search tool (read-only). */
 export function codeSearchTool(memory) {
   return {
     name: "code_search",
@@ -266,14 +276,14 @@ export function codeSearchTool(memory) {
       const results = await codeSearch(memory, args.query, { limit: args.limit ?? 5 })
       if (results.length === 0) return "(no matching code)"
       return results.map((r) =>
-        `${r.path}${r.symbol_name ? ` :: ${r.symbol_name}` : ""} (L${r.line_start}-L${r.line_end}):\n${r.content.slice(0, 2000)}`
+        `${r.path}${r.symbol_name ? ` :: ${r.symbol_name}` : ""} (L${r.line_start}-L${r.line_end}, relevance ${r._score?.toFixed(2) ?? "?"}):\n${r.content.slice(0, 2000)}`
       ).join("\n\n---\n\n")
     },
   }
 }
 
 /**
- * 单文件增量重索引：write/edit/delete 后调用，只重建这一条路径。
+ * Single-file incremental reindex: called after write/edit/delete, only rebuilds this one path.
  */
 export async function reindexFile(memory, cwd, absPath) {
   const ext = absPath.slice(absPath.lastIndexOf(".")).toLowerCase()
@@ -293,14 +303,14 @@ export async function reindexFile(memory, cwd, absPath) {
   if (CODE_EXTS.has(ext)) {
     const lang = detectLanguage(absPath)
     let mtimeMs = 0
-    try { mtimeMs = Math.floor((await stat(absPath)).mtimeMs) } catch { /* 新文件 */ }
+    try { mtimeMs = Math.floor((await stat(absPath)).mtimeMs) } catch { /* new file */ }
     _upsertCodeFile(memory, cwd, rel, lines, lang, mtimeMs)
   } else if (DOC_EXTS.has(ext)) {
     let mtimeMs = 0
-    try { mtimeMs = Math.floor((await stat(absPath)).mtimeMs) } catch { /* 新文件 */ }
+    try { mtimeMs = Math.floor((await stat(absPath)).mtimeMs) } catch { /* new file */ }
     _upsertDocFile(memory, cwd, rel, lines, mtimeMs)
   }
   if (memory.embedder) {
-    try { await ensureEmbeddings(memory) } catch { /* embedding 失败不阻塞 */ }
+    try { await ensureEmbeddings(memory) } catch { /* embedding failure is non-blocking */ }
   }
 }

package/src/memory/core.mjs

@@ -1,5 +1,5 @@
 /**
- * memory/core.mjs — 记忆 CRUD、混合检索、embedding 管理
+ * memory/core.mjs — memory CRUD, hybrid retrieval, embedding management
  */
 
 import { parseEntry, serializeEntry, entryFilename } from "../markdown.mjs"
@@ -8,9 +8,14 @@ import { readFile, stat, readdir, writeFile, mkdir } from "node:fs/promises"
 import { join } from "node:path"
 import { segmentCJK, VALID_TYPES, SCHEMA_VERSION } from "./schema.mjs"
 
+const EMBED_BATCH_SIZE = 256
+export const EMBED_TEXT_MAX_LEN = 2000
+const FTS_TOKEN_MAX = 16
+const DEFAULT_LIST_LIMIT = 50
+
 /**
- * 写入一条记忆。entry: { type, title, content, tags? }
- * 返回新条目 id。
+ * Write a memory entry. entry: { type, title, content, tags? }
+ * Returns the new entry id.
  */
 export async function put(memory, { type, title, content, tags = "" }) {
   if (!VALID_TYPES.has(type)) {
@@ -27,9 +32,9 @@ export async function put(memory, { type, title, content, tags = "" }) {
 }
 
 /**
- * 混合检索：FTS5(BM25) + 向量余弦，RRF(k=60) 合并排序。
- * 无 embedder 时退化为纯 FTS。结果带 layer 标记。
- * 返回 [{ id, layer, type, title, content, tags, rank }]
+ * Hybrid retrieval: FTS5(BM25) + vector cosine, RRF(k=60) merged ranking.
+ * Falls back to pure FTS when no embedder. Results include layer label.
+ * Returns [{ id, layer, type, title, content, tags, rank }]
  */
 export async function search(memory, query, { limit = 5 } = {}) {
   const ftsQuery = buildFtsQuery(query)
@@ -37,7 +42,7 @@ export async function search(memory, query, { limit = 5 } = {}) {
 
   if (!memory.embedder) return ftsList.slice(0, limit)
 
-  // ---- 向量通道 ----
+  // ---- vector channel ----
   try { await ensureEmbeddings(memory) } catch (e) {
     console.error(`[memory] embedding ensure failed, falling back to FTS-only: ${e.message}`)
     return ftsList.slice(0, limit)
@@ -59,7 +64,7 @@ export async function search(memory, query, { limit = 5 } = {}) {
     .sort((a, b) => b.score - a.score)
     .slice(0, Math.max(limit * 4, 20))
 
-  // ---- RRF 合并 ----
+  // ---- RRF merge ----
   const K = 60
   const scores = new Map()
   ftsList.forEach((r, i) => scores.set(r.id, (scores.get(r.id) ?? 0) + 1 / (K + i + 1)))
@@ -75,7 +80,7 @@ export async function search(memory, query, { limit = 5 } = {}) {
     .filter(Boolean)
 }
 
-/** 纯 FTS 检索（两表合并，按 bm25 排序），RRF 的位置输入 */
+/** Pure FTS search (two-table merge, sorted by bm25), used as the positional input for RRF */
 export function ftsSearch(memory, ftsQuery, limit) {
   const personal = memory.db.prepare(`
     SELECT e.id, e.type, e.title, e.content, e.tags, bm25(entries_fts) AS rank
@@ -96,23 +101,23 @@ export function ftsSearch(memory, ftsQuery, limit) {
   return [...personal, ...files].sort((a, b) => a.rank - b.rank).slice(0, limit)
 }
 
-/** 按统一 id 取完整条目（personal:<n> / project:<origin>:<path> / team:<origin>:<path>）
- *  注意：v9 起 files 表 PK 为 (layer, origin, path)，同一 layer+path 可能跨多个 origin。
- *  project 层优先返回 projectOrigin 命中的行，team 层取任意一行（跨团队仓库同名时取首条）。 */
+/** Fetch a full entry by unified id (personal:<n> / project:<origin>:<path> / team:<origin>:<path>)
+ *  Note: since v9 the files table PK is (layer, origin, path); the same layer+path may span multiple origins.
+ *  For project layer, prefers the row matching projectOrigin; for team layer, returns any row (first match when multiple team repos share a path). */
 export function fetchEntry(memory, uid) {
   const [layer, ...rest] = uid.split(":")
   if (layer === "personal") {
     const r = memory.db.prepare(`SELECT id, type, title, content, tags FROM entries WHERE id = ?`).get(Number(rest[0]))
     return r ? { ...r, layer, id: uid } : null
   }
-  // rest = [origin, ...pathParts]；origin 可能为空字符串（旧格式兼容）
+  // rest = [origin, ...pathParts]; origin may be empty string (compat with old format)
   const origin = rest[0] ?? ""
   const path = rest.slice(1).join(":")
   if (layer === "project" && memory.projectOrigin) {
     const r = memory.db.prepare(`SELECT type, title, content, tags, author FROM files WHERE layer = ? AND origin = ? AND path = ?`).get(layer, origin || memory.projectOrigin, path)
     if (r) return { ...r, layer, id: uid }
   }
-  // team 层或 project 兜底：按 origin+path 查，origin 为空时退化为只按 path（兼容旧 UID）
+  // team layer or project fallback: query by origin+path; when origin is empty, degrade to path-only (compat with old UID)
   if (origin) {
     const r = memory.db.prepare(`SELECT type, title, content, tags, author FROM files WHERE layer = ? AND origin = ? AND path = ?`).get(layer, origin, path)
     if (r) return { ...r, layer, id: uid }
@@ -122,14 +127,14 @@ export function fetchEntry(memory, uid) {
 }
 
 /**
- * 惰性 embedding：把还没有向量的条目批量补算落库（首次慢、后续零成本）。
- * 检测到 embedding 模型变更时，清空全部向量重建。
+ * Lazy embedding: batch-compute vectors for entries that don't have them yet (slow first time, zero cost thereafter).
+ * When the embedding model changes, clear all vectors and rebuild.
  */
 export async function ensureEmbeddings(memory) {
   const modelKey = memory.embedder.model
   const stored = memory.db.prepare(`SELECT value FROM meta WHERE key = 'embedding_model'`).get()?.value
   if (stored !== modelKey) {
-    // 统一失效三个表 + 三个 meta key，防维度不匹配的陈旧向量残留
+    // Invalidate all three tables + three meta keys in one go, to prevent stale vectors from dimension mismatch
     memory.db.prepare(`UPDATE entries SET embedding = NULL`).run()
     memory.db.prepare(`UPDATE files SET embedding = NULL`).run()
     memory.db.prepare(`UPDATE code_chunks SET embedding = NULL`).run()
@@ -140,17 +145,17 @@ export async function ensureEmbeddings(memory) {
     upsert.run("doc_embedding_model", modelKey)
   }
 
-  const pendingEntries = memory.db.prepare(`SELECT id, title, content FROM entries WHERE embedding IS NULL LIMIT 256`).all()
-  const pendingFiles = memory.db.prepare(`SELECT rowid, title, content FROM files WHERE embedding IS NULL LIMIT 256`).all()
+  const pendingEntries = memory.db.prepare(`SELECT id, title, content FROM entries WHERE embedding IS NULL LIMIT ${EMBED_BATCH_SIZE}`).all()
+  const pendingFiles = memory.db.prepare(`SELECT rowid, title, content FROM files WHERE embedding IS NULL LIMIT ${EMBED_BATCH_SIZE}`).all()
   if (pendingEntries.length + pendingFiles.length === 0) {
-    // 记忆不算 pending，也补一下代码和文档块的向量
+    // No pending memory entries — also backfill code and doc chunk vectors
     await (await import("./code-sync.mjs")).ensureCodeEmbeddings(memory)
     await (await import("./docs.mjs")).ensureDocEmbeddings(memory)
     return
   }
 
   const items = [...pendingEntries, ...pendingFiles]
-  const texts = items.map((r) => `${r.title}\n${r.content.slice(0, 2000)}`)
+  const texts = items.map((r) => `${r.title}\n${r.content.slice(0, EMBED_TEXT_MAX_LEN)}`)
   const vecs = await embed(memory.embedder, texts)
 
   const updateEntry = memory.db.prepare(`UPDATE entries SET embedding = ? WHERE id = ?`)
@@ -158,16 +163,16 @@ export async function ensureEmbeddings(memory) {
   const updateFile = memory.db.prepare(`UPDATE files SET embedding = ? WHERE rowid = ?`)
   pendingFiles.forEach((r, i) => updateFile.run(toBlob(vecs[pendingEntries.length + i]), r.rowid))
 
-  // 每批嵌入后也补一下代码和文档块
+  // After each batch of embeddings, also backfill code and doc chunks
   await (await import("./code-sync.mjs")).ensureCodeEmbeddings(memory)
   await (await import("./docs.mjs")).ensureDocEmbeddings(memory)
 }
 
 /**
- * 写入一条 markdown 记忆到指定层目录（project/team），并即时索引。
- * 只写文件——project 层绝不替用户的项目仓库做 git 操作；
- * team 层的 commit+push 由 gitmem.mjs 负责。
- * 返回文件名。
+ * Write a markdown memory entry to the specified layer directory (project/team) and index it immediately.
+ * Writes the file only — the project layer never performs git operations on the user's project repo;
+ * team layer commit+push is handled by gitmem.mjs.
+ * Returns the filename.
  */
 export async function putMarkdown(memory, { layer, dir, type, title, content, tags = [], author = "unknown" }) {
   if (layer !== "project" && layer !== "team") throw new Error(`invalid markdown layer: ${layer}`)
@@ -180,7 +185,8 @@ export async function putMarkdown(memory, { layer, dir, type, title, content, ta
 }
 
 /**
- * 同步一个 markdown 目录到索引：新增/变更（按 mtime）重建索引，消失的条目从索引删除。
+ * Sync a markdown directory to the index: new/changed (by mtime) entries are re-indexed,
+ * vanished entries are removed from the index.
  */
 export async function syncDir(memory, { layer, dir }) {
   let names = []
@@ -221,7 +227,7 @@ export async function syncDir(memory, { layer, dir }) {
   return { added, updated, removed, skipped }
 }
 
-/** 解析单个 .md 并 upsert 进 files 表 */
+/** Parse a single .md and upsert into the files table */
 export async function indexMarkdownFile(memory, { layer, dir, filename, mtimeMs }) {
   const abs = join(dir, filename)
   const mtime = mtimeMs ?? Math.floor((await stat(abs)).mtimeMs)
@@ -241,8 +247,8 @@ export async function indexMarkdownFile(memory, { layer, dir, filename, mtimeMs
   )
 }
 
-/** 列出新条目，可按 type 过滤 */
-export async function list(memory, { type, limit = 50 } = {}) {
+/** List entries, optionally filtered by type */
+export async function list(memory, { type, limit = DEFAULT_LIST_LIMIT } = {}) {
   if (type) {
     if (!VALID_TYPES.has(type)) throw new Error(`Invalid memory type "${type}"`)
     return memory.db
@@ -254,23 +260,24 @@ export async function list(memory, { type, limit = 50 } = {}) {
     .all(limit)
 }
 
-/** 删除一条记忆。返回是否删除成功 */
+/** Delete a memory entry. Returns whether deletion succeeded */
 export async function remove(memory, id) {
   const info = memory.db.prepare(`DELETE FROM entries WHERE id = ?`).run(id)
   return info.changes > 0
 }
 
 /**
- * 构造 FTS5 查询：先按空白/标点切词，再对每个词做 CJK 分字。
- * 这样 CJK 多字词保持为 FTS5 短语（"分号" → "分 号" → 短语查询，精确匹配相邻字），
- * 而不同词之间用 OR 连接（"命名 规范" → "命 名" OR "规 范"，两个短语各需相邻匹配）。
+ * Build an FTS5 query: first split by whitespace/punctuation into tokens,
+ * then apply CJK character segmentation to each token.
+ * This keeps multi-character CJK words as FTS5 phrases ("分号" → "分 号" → phrase query, exact adjacency match),
+ * while different tokens are joined with OR ("命名 规范" → "命 名" OR "规 范", each phrase requires its own adjacency).
  */
 export function buildFtsQuery(query) {
   const terms = query
     .split(/[\s,，。、;；!！?？()（）"`]+/)
     .map((t) => t.trim())
     .filter(Boolean)
-    .slice(0, 16)
+    .slice(0, FTS_TOKEN_MAX)
     .map((t) => segmentCJK(t))
   if (terms.length === 0) return ""
   return terms.map((t) => `"${t.replaceAll('"', '""')}"`).join(" OR ")

package/src/memory/docs.mjs

@@ -1,5 +1,5 @@
 /**
- * memory/docs.mjs — 文档索引同步、检索、agent 工具生成
+ * memory/docs.mjs — doc index sync, retrieval, agent tool generation
  */
 
 import { readFile, readdir, stat } from "node:fs/promises"
@@ -11,9 +11,12 @@ import { buildFtsQuery, put, search, putMarkdown } from "./core.mjs"
 import { _upsertDocFile, yieldTick } from "./code-index.mjs"
 import { markIndexedCommit } from "./code-sync.mjs"
 
+const DOC_EMBED_BATCH = 64
+const EMBED_TEXT_MAX_LEN = 2000
+
 /**
- * 同步文档索引：扫描 dir 下所有 .md/.mdc/.txt/.rst/.adoc → 分块 → upsert 到 doc_chunks。
- * 按 mtime 增量。
+ * Sync doc index: scan all .md/.mdc/.txt/.rst/.adoc under dir → chunk → upsert into doc_chunks.
+ * Incremental by mtime.
  */
 export async function docSync(memory, dir, { onProgress } = {}) {
   const files = []
@@ -82,8 +85,8 @@ export async function docSync(memory, dir, { onProgress } = {}) {
 }
 
 /**
- * 文档检索：FTS5(BM25) + 可选向量余弦，RRF 合并。
- * 无 embedder 时退化为纯 FTS；ftsQuery 为空且有 embedder 时退化为纯向量。
+ * Doc search: FTS5(BM25) + optional vector cosine, RRF merged.
+ * Falls back to pure FTS when no embedder; falls back to pure vector when ftsQuery is empty and embedder is present.
  */
 export async function docSearch(memory, query, { limit = 5 } = {}) {
   const ftsQuery = buildFtsQuery(query)
@@ -125,14 +128,20 @@ export async function docSearch(memory, query, { limit = 5 } = {}) {
   const fetchChunk = memory.db.prepare(`
     SELECT path, language, heading, content, line_start, line_end FROM doc_chunks WHERE rowid = ?
   `)
-  return [...scores.entries()]
+  const sorted = [...scores.entries()]
     .sort((a, b) => b[1] - a[1])
     .slice(0, limit)
-    .map(([rowid]) => fetchChunk.get(rowid))
+  return sorted
+    .map(([rowid, score]) => {
+      const chunk = fetchChunk.get(rowid)
+      if (!chunk) return null
+      chunk._score = Math.round(score * 100) / 100
+      return chunk
+    })
     .filter(Boolean)
 }
 
-/** 惰性补算 doc_chunks 缺失的向量 */
+/** Lazily backfill missing vectors for doc_chunks */
 export async function ensureDocEmbeddings(memory) {
   if (!memory.embedder) return
   const modelKey = memory.embedder.model
@@ -143,17 +152,17 @@ export async function ensureDocEmbeddings(memory) {
       ON CONFLICT (key) DO UPDATE SET value = excluded.value`).run(modelKey)
   }
 
-  const pending = memory.db.prepare(`SELECT rowid, path, heading, content FROM doc_chunks WHERE embedding IS NULL LIMIT 64`).all()
+  const pending = memory.db.prepare(`SELECT rowid, path, heading, content FROM doc_chunks WHERE embedding IS NULL LIMIT ${DOC_EMBED_BATCH}`).all()
   if (pending.length === 0) return
 
-  const texts = pending.map((r) => `${r.heading || r.path}\n${r.content.slice(0, 2000)}`)
+  const texts = pending.map((r) => `${r.heading || r.path}\n${r.content.slice(0, EMBED_TEXT_MAX_LEN)}`)
   const vecs = await embed(memory.embedder, texts)
 
   const update = memory.db.prepare(`UPDATE doc_chunks SET embedding = ? WHERE rowid = ?`)
   pending.forEach((r, i) => update.run(toBlob(vecs[i]), r.rowid))
 }
 
-/** 生成 doc_search 工具（只读）。 */
+/** Generate the doc_search tool (read-only). */
 export function docSearchTool(memory) {
   return {
     name: "doc_search",
@@ -172,17 +181,17 @@ export function docSearchTool(memory) {
       const results = await docSearch(memory, args.query, { limit: args.limit ?? 5 })
       if (results.length === 0) return "(no matching documentation)"
       return results.map((r) =>
-        `${r.path}${r.heading ? ` > ${r.heading}` : ""} (L${r.line_start}-L${r.line_end}):\n${r.content.slice(0, 2000)}`
+        `${r.path}${r.heading ? ` > ${r.heading}` : ""} (L${r.line_start}-L${r.line_end}, relevance ${r._score?.toFixed(2) ?? "?"}):\n${r.content.slice(0, 2000)}`
       ).join("\n\n---\n\n")
     },
   }
 }
 
-// ---------------------------------------------------------------- agent 工具
+// ---------------------------------------------------------------- agent tools
 
 /**
- * 生成记忆相关的两个 agent 工具（遵循 tools.mjs 的工具形状）。
- * memory_put 是有副作用工具（需权限确认），memory_search 只读。
+ * Generate the two memory-related agent tools (following the tools.mjs tool shape).
+ * memory_put is a side-effecting tool (needs permission confirmation), memory_search is read-only.
  * opts: { cwd, projectDir, author, team: { dir, name } | null }
  */
 export function memoryTools(memory, opts = {}) {