thincoder 0.7.7 → 0.8.0

package/src/memory/code-sync.mjs

@@ -0,0 +1,306 @@
+/**
+ * memory/code-sync.mjs — 代码索引同步、检索、增量更新
+ */
+
+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 { detectLanguage, _upsertCodeFile, _upsertDocFile, yieldTick } from "./code-index.mjs"
+
+/**
+ * git 驱动增量索引：用 git diff 找出上次索引以来的变更文件，
+ * 只重建这些文件的 FTS5 块（不碰向量）。比全量 mtime 扫描快一个数量级。
+ * 返回 { updated, removed, skipped } 或 null（git 不可用）。
+ */
+export async function gitSync(memory, dir, { onProgress } = {}) {
+  const { execSync, execFileSync } = await import("node:child_process")
+  const opts = { cwd: dir, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 10000 }
+
+  let head
+  try { head = execSync("git rev-parse HEAD", opts).trim() } catch { return null }
+
+  const stored = memory.db.prepare(`SELECT value FROM meta WHERE key = 'last_indexed_commit'`).get()?.value
+  if (!stored) return null
+
+  let diffOut
+  try {
+    const committed = execFileSync("git", ["diff", "--name-only", "--diff-filter=ACMRTD", stored, "HEAD"], { cwd: dir, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 10000 }).trim()
+    const dirty = execSync(`git diff --name-only --diff-filter=ACMRTD`, opts).trim()
+    const lines = [...new Set([...committed.split("\n").filter(Boolean), ...dirty.split("\n").filter(Boolean)])]
+    diffOut = lines
+  } catch {
+    return null
+  }
+
+  if (diffOut.length > 200) {
+    // diff 太大，增量没意义——回退全量同步并更新锚点
+    await codeSync(memory, dir, { onProgress })
+    const { docSync } = await import("./docs.mjs")
+    await docSync(memory, dir, { onProgress })
+    return { updated: -1, removed: 0, skipped: 0, failed: 0, errors: [], fallback: true }
+  }
+
+  let updated = 0, removed = 0, skipped = 0, failed = 0
+  const errors = []
+  for (let i = 0; i < diffOut.length; i++) {
+    const rel = diffOut[i].replaceAll("\\", "/")
+    const abs = join(dir, rel)
+    const ext = rel.slice(rel.lastIndexOf(".")).toLowerCase()
+
+    const pathDirs = rel.split("/")
+    if (pathDirs.some((d) => SKIP_DIRS.has(d) || d.startsWith("."))) continue
+
+    if (!CODE_EXTS.has(ext) && !DOC_EXTS.has(ext)) { skipped++; continue }
+
+    try {
+      const text = await readFile(abs, "utf8")
+      const lines = text.split("\n")
+      if (CODE_EXTS.has(ext)) {
+        const lang = detectLanguage(abs)
+        let mtimeMs = 0
+        try { mtimeMs = Math.floor((await stat(abs)).mtimeMs) } catch { /* 新文件 */ }
+        _upsertCodeFile(memory, dir, rel, lines, lang, mtimeMs)
+      } else {
+        let mtimeMs = 0
+        try { mtimeMs = Math.floor((await stat(abs)).mtimeMs) } catch { /* 新文件 */ }
+        _upsertDocFile(memory, dir, rel, lines, mtimeMs)
+      }
+      updated++
+    } catch (e) {
+      const isDeleted = e.code === "ENOENT"
+      if (isDeleted) {
+        if (CODE_EXTS.has(ext)) memory.db.prepare(`DELETE FROM code_chunks WHERE origin = ? AND path = ?`).run(dir, rel)
+        else memory.db.prepare(`DELETE FROM doc_chunks WHERE origin = ? AND path = ?`).run(dir, rel)
+        removed++
+      } else {
+        failed++
+        if (errors.length < 5) errors.push(`${rel}: ${e.message}`)
+      }
+    }
+    if (onProgress && i % 5 === 0) {
+      onProgress({ phase: "index", current: i + 1, total: diffOut.length, updated, removed, skipped })
+    }
+  }
+
+  if (failed === 0) {
+    memory.db.prepare(`INSERT INTO meta (key, value) VALUES ('last_indexed_commit', ?)
+      ON CONFLICT (key) DO UPDATE SET value = excluded.value`).run(head)
+  }
+
+  onProgress?.({ phase: "done", total: diffOut.length, updated, removed, skipped, failed })
+  return { updated, removed, skipped, failed, errors }
+}
+
+/**
+ * 同步代码索引：扫描 dir 下所有源文件 → 分块 → upsert 到 code_chunks。
+ * 按 mtime 增量——只重建变更过的文件块。
+ */
+export async function codeSync(memory, dir, { onProgress } = {}) {
+  const files = []
+  const { readdir } = await import("node:fs/promises")
+  async function walk(d) {
+    let entries
+    try { entries = await readdir(d, { withFileTypes: true }) } catch { return }
+    for (const e of entries) {
+      if (e.isDirectory()) {
+        if (SKIP_DIRS.has(e.name) || e.name.startsWith(".")) continue
+        await walk(join(d, e.name))
+      } else if (e.isFile()) {
+        const ext = e.name.slice(e.name.lastIndexOf(".")).toLowerCase()
+        if (CODE_EXTS.has(ext)) files.push(join(d, e.name))
+      }
+    }
+  }
+  await walk(dir)
+
+  const indexed = new Map(
+    memory.db.prepare(`SELECT path, mtime_ms FROM code_chunks WHERE origin = ?`).all(dir).map((r) => [r.path, r.mtime_ms])
+  )
+  const seen = new Set()
+
+  onProgress?.({ phase: "scan", total: files.length })
+
+  let updated = 0, removed = 0, skipped = 0, failed = 0
+  const errors = []
+  for (let i = 0; i < files.length; i++) {
+    const abs = files[i]
+    const rel = abs.slice(dir.length + 1).replaceAll("\\", "/")
+    seen.add(rel)
+
+    let mtimeMs
+    try { mtimeMs = Math.floor((await stat(abs)).mtimeMs) } catch { continue }
+    if (indexed.get(rel) === mtimeMs) {
+      skipped++
+      continue
+    }
+
+    try {
+      const text = await readFile(abs, "utf8")
+      const lines = text.split("\n")
+      const lang = detectLanguage(abs)
+      _upsertCodeFile(memory, dir, rel, lines, lang, mtimeMs)
+      updated++
+    } catch (e) {
+      failed++
+      if (errors.length < 5) errors.push(`${rel}: ${e.message}`)
+    }
+    await yieldTick()
+
+    if (onProgress && i % 10 === 0) {
+      onProgress({ phase: "index", current: i + 1, total: files.length, updated, removed, skipped, failed })
+    }
+  }
+
+  for (const stale of indexed.keys()) {
+    if (!seen.has(stale)) {
+      memory.db.prepare(`DELETE FROM code_chunks WHERE origin = ? AND path = ?`).run(dir, stale)
+      removed++
+    }
+  }
+
+  onProgress?.({ phase: "done", total: files.length, updated, removed, skipped, failed })
+  markIndexedCommit(memory, dir)
+  return { updated, removed, skipped, failed, errors, total: files.length }
+}
+
+/** 记录当前 HEAD 作为索引锚点（gitSync 增量 diff 基准）；非 git 仓库静默跳过 */
+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 不可用，跳过 */ }
+}
+
+/**
+ * 代码检索：FTS5(BM25) + 可选向量余弦，RRF 合并。
+ * 无 embedder 时退化为纯 FTS；ftsQuery 为空且有 embedder 时退化为纯向量。
+ */
+export async function codeSearch(memory, query, { limit = 5 } = {}) {
+  const ftsQuery = buildFtsQuery(query)
+  if (!ftsQuery && !memory.embedder) return []
+
+  const ftsOriginFilter = memory.codeOrigin ? `AND c.origin = ?` : ""
+  const vecOriginFilter = memory.codeOrigin ? `AND origin = ?` : ""
+  const originParams = memory.codeOrigin ? [memory.codeOrigin] : []
+
+  const ftsList = ftsQuery ? memory.db.prepare(`
+    SELECT c.rowid, c.path, c.language, c.symbol_name, c.content, c.line_start, c.line_end, bm25(code_chunks_fts) AS rank
+    FROM code_chunks_fts JOIN code_chunks c ON c.rowid = code_chunks_fts.rowid
+    WHERE code_chunks_fts MATCH ? ${ftsOriginFilter}
+    ORDER BY rank LIMIT ?
+  `).all(ftsQuery, ...originParams, Math.max(limit * 4, 20)) : []
+
+  if (!memory.embedder) return ftsList.slice(0, limit)
+
+  try { await ensureEmbeddings(memory) } catch (e) {
+    console.error(`[code] embedding ensure failed, falling back to FTS-only: ${e.message}`)
+    return ftsList.slice(0, limit)
+  }
+  let qvec
+  try { [qvec] = await embed(memory.embedder, [query]) } catch (e) {
+    console.error(`[code] query embedding failed, falling back to FTS-only: ${e.message}`)
+    return ftsList.slice(0, limit)
+  }
+  const rows = memory.db.prepare(`SELECT rowid, embedding FROM code_chunks WHERE embedding IS NOT NULL ${vecOriginFilter}`).all(...originParams)
+  const vecList = rows
+    .map((r) => ({ rowid: r.rowid, score: cosine(qvec, fromBlob(r.embedding)) }))
+    .sort((a, b) => b.score - a.score)
+    .slice(0, Math.max(limit * 4, 20))
+
+  const K = 60
+  const scores = new Map()
+  ftsList.forEach((r, i) => scores.set(r.rowid, (scores.get(r.rowid) ?? 0) + 1 / (K + i + 1)))
+  vecList.forEach((r, i) => scores.set(r.rowid, (scores.get(r.rowid) ?? 0) + 1 / (K + i + 1)))
+
+  const fetchChunk = memory.db.prepare(`
+    SELECT path, language, symbol_name, content, line_start, line_end FROM code_chunks WHERE rowid = ?
+  `)
+  return [...scores.entries()]
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, limit)
+    .map(([rowid]) => fetchChunk.get(rowid))
+    .filter(Boolean)
+}
+
+/** 惰性补算 code_chunks 缺失的向量 */
+export async function ensureCodeEmbeddings(memory) {
+  if (!memory.embedder) return
+  const modelKey = memory.embedder.model
+  const stored = memory.db.prepare(`SELECT value FROM meta WHERE key = 'code_embedding_model'`).get()?.value
+  if (stored !== modelKey) {
+    memory.db.prepare(`UPDATE code_chunks SET embedding = NULL`).run()
+    memory.db.prepare(`INSERT INTO meta (key, value) VALUES ('code_embedding_model', ?)
+      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()
+  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 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 工具（只读）。 */
+export function codeSearchTool(memory) {
+  return {
+    name: "code_search",
+    description:
+      "Search the project's source code for relevant code. Use this to find functions, classes, or code patterns across the codebase. Supports natural language queries and code snippets. Returns matching code chunks with file paths and line numbers.",
+    parameters: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "Natural language or code snippet to search for" },
+        limit: { type: "number", description: "Max results (default 5)" },
+      },
+      required: ["query"],
+    },
+    readonly: true,
+    async execute(args) {
+      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)}`
+      ).join("\n\n---\n\n")
+    },
+  }
+}
+
+/**
+ * 单文件增量重索引：write/edit/delete 后调用，只重建这一条路径。
+ */
+export async function reindexFile(memory, cwd, absPath) {
+  const ext = absPath.slice(absPath.lastIndexOf(".")).toLowerCase()
+  const rel = relative(cwd, absPath).replaceAll("\\", "/")
+  if (rel === ".." || rel.startsWith("../")) return
+  const dirs = rel.split("/").slice(0, -1)
+  if (dirs.some((d) => SKIP_DIRS.has(d) || d.startsWith("."))) return
+
+  let text
+  try { text = await readFile(absPath, "utf8") } catch {
+    if (CODE_EXTS.has(ext)) memory.db.prepare(`DELETE FROM code_chunks WHERE origin = ? AND path = ?`).run(cwd, rel)
+    else if (DOC_EXTS.has(ext)) memory.db.prepare(`DELETE FROM doc_chunks WHERE origin = ? AND path = ?`).run(cwd, rel)
+    return
+  }
+  const lines = text.split("\n")
+
+  if (CODE_EXTS.has(ext)) {
+    const lang = detectLanguage(absPath)
+    let mtimeMs = 0
+    try { mtimeMs = Math.floor((await stat(absPath)).mtimeMs) } catch { /* 新文件 */ }
+    _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 { /* 新文件 */ }
+    _upsertDocFile(memory, cwd, rel, lines, mtimeMs)
+  }
+  if (memory.embedder) {
+    try { await ensureEmbeddings(memory) } catch { /* embedding 失败不阻塞 */ }
+  }
+}

package/src/memory/core.mjs

@@ -0,0 +1,277 @@
+/**
+ * memory/core.mjs — 记忆 CRUD、混合检索、embedding 管理
+ */
+
+import { parseEntry, serializeEntry, entryFilename } from "../markdown.mjs"
+import { embed, cosine, toBlob, fromBlob } from "../embedding.mjs"
+import { readFile, stat, readdir, writeFile, mkdir } from "node:fs/promises"
+import { join } from "node:path"
+import { segmentCJK, VALID_TYPES, SCHEMA_VERSION } from "./schema.mjs"
+
+/**
+ * 写入一条记忆。entry: { type, title, content, tags? }
+ * 返回新条目 id。
+ */
+export async function put(memory, { type, title, content, tags = "" }) {
+  if (!VALID_TYPES.has(type)) {
+    throw new Error(`Invalid memory type "${type}"; expected one of: ${[...VALID_TYPES].join(", ")}`)
+  }
+  if (!title || !content) throw new Error("memory entry requires title and content")
+  const now = Date.now()
+  const stmt = memory.db.prepare(
+    `INSERT INTO entries (type, title, content, tags, seg_title, seg_content, seg_tags, created_at, updated_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+  )
+  const info = stmt.run(type, title, content, tags, segmentCJK(title), segmentCJK(content), segmentCJK(tags), now, now)
+  return Number(info.lastInsertRowid)
+}
+
+/**
+ * 混合检索：FTS5(BM25) + 向量余弦，RRF(k=60) 合并排序。
+ * 无 embedder 时退化为纯 FTS。结果带 layer 标记。
+ * 返回 [{ id, layer, type, title, content, tags, rank }]
+ */
+export async function search(memory, query, { limit = 5 } = {}) {
+  const ftsQuery = buildFtsQuery(query)
+  const ftsList = ftsQuery ? ftsSearch(memory, ftsQuery, Math.max(limit * 4, 20)) : []
+
+  if (!memory.embedder) return ftsList.slice(0, limit)
+
+  // ---- 向量通道 ----
+  try { await ensureEmbeddings(memory) } catch (e) {
+    console.error(`[memory] embedding ensure failed, falling back to FTS-only: ${e.message}`)
+    return ftsList.slice(0, limit)
+  }
+  let qvec
+  try { [qvec] = await embed(memory.embedder, [query]) } catch (e) {
+    console.error(`[memory] query embedding failed, falling back to FTS-only: ${e.message}`)
+    return ftsList.slice(0, limit)
+  }
+  const vecFilter = memory.projectOrigin ? `AND (layer = 'team' OR origin = ?)` : ""
+  const vecParams = memory.projectOrigin ? [memory.projectOrigin] : []
+  const rows = memory.db.prepare(`
+    SELECT 'personal:' || id AS uid, embedding FROM entries WHERE embedding IS NOT NULL
+    UNION ALL
+    SELECT layer || ':' || COALESCE(origin, '') || ':' || path AS uid, embedding FROM files WHERE embedding IS NOT NULL ${vecFilter}
+  `).all(...vecParams)
+  const vecList = rows
+    .map((r) => ({ id: r.uid, score: cosine(qvec, fromBlob(r.embedding)) }))
+    .sort((a, b) => b.score - a.score)
+    .slice(0, Math.max(limit * 4, 20))
+
+  // ---- RRF 合并 ----
+  const K = 60
+  const scores = new Map()
+  ftsList.forEach((r, i) => scores.set(r.id, (scores.get(r.id) ?? 0) + 1 / (K + i + 1)))
+  vecList.forEach((r, i) => scores.set(r.id, (scores.get(r.id) ?? 0) + 1 / (K + i + 1)))
+
+  return [...scores.entries()]
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, limit)
+    .map(([id, score]) => {
+      const entry = fetchEntry(memory, id)
+      return entry ? { ...entry, rrf: score } : null
+    })
+    .filter(Boolean)
+}
+
+/** 纯 FTS 检索（两表合并，按 bm25 排序），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
+    FROM entries_fts JOIN entries e ON e.id = entries_fts.rowid
+    WHERE entries_fts MATCH ?
+    ORDER BY rank LIMIT ?
+  `).all(ftsQuery, limit).map((r) => ({ ...r, layer: "personal", id: `personal:${r.id}` }))
+
+  const originFilter = memory.projectOrigin ? `AND (f.layer = 'team' OR f.origin = ?)` : ""
+  const originParams = memory.projectOrigin ? [ftsQuery, memory.projectOrigin, limit] : [ftsQuery, limit]
+  const files = memory.db.prepare(`
+    SELECT f.layer, f.path, f.type, f.title, f.content, f.tags, f.author, bm25(files_fts) AS rank
+    FROM files_fts JOIN files f ON f.rowid = files_fts.rowid
+    WHERE files_fts MATCH ? ${originFilter}
+    ORDER BY rank LIMIT ?
+  `).all(...originParams).map((r) => ({ ...r, id: `${r.layer}:${r.origin ?? ""}:${r.path}` }))
+
+  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 层取任意一行（跨团队仓库同名时取首条）。 */
+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 可能为空字符串（旧格式兼容）
+  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）
+  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 }
+  }
+  const r = memory.db.prepare(`SELECT type, title, content, tags, author FROM files WHERE layer = ? AND path = ?`).get(layer, path || rest.join(":"))
+  return r ? { ...r, layer, id: uid } : null
+}
+
+/**
+ * 惰性 embedding：把还没有向量的条目批量补算落库（首次慢、后续零成本）。
+ * 检测到 embedding 模型变更时，清空全部向量重建。
+ */
+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，防维度不匹配的陈旧向量残留
+    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()
+    memory.db.prepare(`UPDATE doc_chunks SET embedding = NULL`).run()
+    const upsert = memory.db.prepare(`INSERT INTO meta (key, value) VALUES (?, ?) ON CONFLICT (key) DO UPDATE SET value = excluded.value`)
+    upsert.run("embedding_model", modelKey)
+    upsert.run("code_embedding_model", modelKey)
+    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()
+  if (pendingEntries.length + pendingFiles.length === 0) {
+    // 记忆不算 pending，也补一下代码和文档块的向量
+    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 vecs = await embed(memory.embedder, texts)
+
+  const updateEntry = memory.db.prepare(`UPDATE entries SET embedding = ? WHERE id = ?`)
+  pendingEntries.forEach((r, i) => updateEntry.run(toBlob(vecs[i]), r.id))
+  const updateFile = memory.db.prepare(`UPDATE files SET embedding = ? WHERE rowid = ?`)
+  pendingFiles.forEach((r, i) => updateFile.run(toBlob(vecs[pendingEntries.length + i]), r.rowid))
+
+  // 每批嵌入后也补一下代码和文档块
+  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 负责。
+ * 返回文件名。
+ */
+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}`)
+  const filename = entryFilename(title)
+  const markdown = serializeEntry({ type, title, tags, author }, content)
+  await mkdir(dir, { recursive: true })
+  await writeFile(join(dir, filename), markdown, "utf8")
+  await indexMarkdownFile(memory, { layer, dir, filename })
+  return filename
+}
+
+/**
+ * 同步一个 markdown 目录到索引：新增/变更（按 mtime）重建索引，消失的条目从索引删除。
+ */
+export async function syncDir(memory, { layer, dir }) {
+  let names = []
+  try {
+    names = (await readdir(dir)).filter((n) => n.endsWith(".md"))
+  } catch {
+    names = []
+  }
+
+  const indexed = new Map(
+    memory.db.prepare(`SELECT path, mtime_ms FROM files WHERE layer = ? AND origin = ?`).all(layer, dir).map((r) => [r.path, r.mtime_ms]),
+  )
+
+  let added = 0, updated = 0, skipped = 0
+  for (const filename of names) {
+    const mtimeMs = Math.floor((await stat(join(dir, filename))).mtimeMs)
+    const old = indexed.get(filename)
+    const isNew = old === undefined
+    if (!isNew && old === mtimeMs) continue
+    try {
+      await indexMarkdownFile(memory, { layer, dir, filename, mtimeMs })
+    } catch (e) {
+      console.error(`[memory] skip ${layer}/${filename}: ${e.message}`)
+      skipped++
+      indexed.delete(filename)
+      continue
+    }
+    if (isNew) added++
+    else updated++
+    indexed.delete(filename)
+  }
+
+  let removed = 0
+  for (const stale of indexed.keys()) {
+    memory.db.prepare(`DELETE FROM files WHERE layer = ? AND origin = ? AND path = ?`).run(layer, dir, stale)
+    removed++
+  }
+  return { added, updated, removed, skipped }
+}
+
+/** 解析单个 .md 并 upsert 进 files 表 */
+export async function indexMarkdownFile(memory, { layer, dir, filename, mtimeMs }) {
+  const abs = join(dir, filename)
+  const mtime = mtimeMs ?? Math.floor((await stat(abs)).mtimeMs)
+  const { meta, content } = parseEntry(await readFile(abs, "utf8"))
+  const tags = meta.tags.join(" ")
+  memory.db.prepare(`
+    INSERT INTO files (layer, origin, path, type, title, content, tags, author, mtime_ms, seg_title, seg_content, seg_tags, updated_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(layer, origin, path) DO UPDATE SET
+      type=excluded.type, title=excluded.title, content=excluded.content, tags=excluded.tags,
+      author=excluded.author, mtime_ms=excluded.mtime_ms, origin=excluded.origin,
+      seg_title=excluded.seg_title, seg_content=excluded.seg_content, seg_tags=excluded.seg_tags,
+      updated_at=excluded.updated_at
+  `).run(
+    layer, dir, filename, meta.type, meta.title, content, tags, meta.author, mtime,
+    segmentCJK(meta.title), segmentCJK(content), segmentCJK(tags), Date.now(),
+  )
+}
+
+/** 列出新条目，可按 type 过滤 */
+export async function list(memory, { type, limit = 50 } = {}) {
+  if (type) {
+    if (!VALID_TYPES.has(type)) throw new Error(`Invalid memory type "${type}"`)
+    return memory.db
+      .prepare(`SELECT id, type, title, content, tags, updated_at FROM entries WHERE type = ? ORDER BY updated_at DESC LIMIT ?`)
+      .all(type, limit)
+  }
+  return memory.db
+    .prepare(`SELECT id, type, title, content, tags, updated_at FROM entries ORDER BY updated_at DESC LIMIT ?`)
+    .all(limit)
+}
+
+/** 删除一条记忆。返回是否删除成功 */
+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 "规 范"，两个短语各需相邻匹配）。
+ */
+export function buildFtsQuery(query) {
+  const terms = query
+    .split(/[\s,，。、;；!！?？()（）"`]+/)
+    .map((t) => t.trim())
+    .filter(Boolean)
+    .slice(0, 16)
+    .map((t) => segmentCJK(t))
+  if (terms.length === 0) return ""
+  return terms.map((t) => `"${t.replaceAll('"', '""')}"`).join(" OR ")
+}