@thincoder/core 0.9.1

package/memory/core.mjs

@@ -0,0 +1,318 @@
+/**
+ * memory/core.mjs — memory CRUD, hybrid retrieval, embedding management.
+ * The disk-truth row-match + deletion family (matchMemoryRows/deleteWhere/deleteByUid/remove/
+ * assertPathInside) lives in delete.mjs — this module imports nothing from it (delete.mjs
+ * imports fetchEntry/syncDir from here).
+ */
+
+import { parseEntry, serializeEntry, entryFilename } from "../markdown.mjs"
+import { embed, cosine, toBlob, fromBlob } from "../embedding.mjs"
+import { scanVectors, createTopK } from "./scan.mjs"
+import { normalizeOrigin } from "./origin.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"
+import { safeSliceUTF16 } from "../text-budget.mjs"
+
+const EMBED_BATCH_SIZE = 256
+export const EMBED_TEXT_MAX_LEN = 2000
+const FTS_TOKEN_MAX = 16
+const DEFAULT_LIST_LIMIT = 50
+
+/**
+ * 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)) {
+    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)
+}
+
+/**
+ * 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)
+  const ftsList = ftsQuery ? ftsSearch(memory, ftsQuery, Math.max(limit * 4, 20)) : []
+
+  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)
+  }
+  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)
+  }
+  // §6.11 读缝归一（单点取名——函数体内一律用归一值）
+  const projectOrigin = normalizeOrigin(memory.projectOrigin)
+  const vecFilter = projectOrigin ? `AND (layer = 'team' OR origin = ?)` : ""
+  const vecParams = projectOrigin ? [projectOrigin] : []
+  // TUI-OOM-ROOTCAUSE（MEMORY.md §6.8）：分块扫描 + 有界 top-K（原全表 .all() 物化 +
+  // 全量排序——峰值 = 块 + K；召回语义不变）。两表各自游标扫描、共享同一 top-K。
+  // TUI 假死批（§6.10）：scanVectors = async（让出）——游标键缺省 rowid（= 本表 PK 别名，零改）。
+  const top = createTopK(Math.max(limit * 4, 20))
+  const onRow = (r) => top.push({ id: r.uid, score: cosine(qvec, fromBlob(r.embedding)) })
+  await scanVectors(memory.db, `SELECT rowid, 'personal:' || id AS uid, embedding FROM entries WHERE embedding IS NOT NULL`, [], { onRow })
+  await scanVectors(memory.db, `SELECT rowid, layer || ':' || COALESCE(origin, '') || ':' || path AS uid, embedding FROM files WHERE embedding IS NOT NULL ${vecFilter}`, vecParams, { onRow })
+  const vecList = top.list()
+
+  // ---- 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)))
+  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)
+}
+
+/** 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
+    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 projectOrigin = normalizeOrigin(memory.projectOrigin) // §6.11 读缝归一
+  const originFilter = projectOrigin ? `AND (f.layer = 'team' OR f.origin = ?)` : ""
+  const originParams = projectOrigin ? [ftsQuery, projectOrigin, limit] : [ftsQuery, limit]
+  const files = memory.db.prepare(`
+    SELECT f.layer, f.origin, 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)
+}
+
+/** 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
+  }
+  // Files branch: origins may contain colons (Windows drive letters, e.g. project:C:\dir:file.md),
+  // so the LAST colon is always the origin/path separator — same parsing as deleteByUid.
+  // origin may be empty (compat with the old `project::file.md` format).
+  const lastColon = uid.lastIndexOf(":")
+  const origin = lastColon > layer.length ? uid.slice(layer.length + 1, lastColon) : ""
+  const path = lastColon > layer.length ? uid.slice(lastColon + 1) : uid.slice(layer.length + 1)
+  const projectOrigin = normalizeOrigin(memory.projectOrigin) // §6.11 读缝归一（uid 解析面零改——`:131` 余量兜底仍在）
+  if (layer === "project" && projectOrigin) {
+    const r = memory.db.prepare(`SELECT type, title, content, tags, author FROM files WHERE layer = ? AND origin = ? AND path = ?`).get(layer, origin || projectOrigin, path)
+    if (r) return { ...r, layer, id: 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 }
+  }
+  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
+}
+
+/**
+ * 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.
+ * Guarded by a module-level lock — concurrent fire-and-forget callers share the same promise,
+ * so embedding API calls are never duplicated.
+ */
+let _embedLock = null
+export function ensureEmbeddings(memory) {
+  if (_embedLock) return _embedLock
+  _embedLock = _runEnsureEmbeddings(memory).finally(() => { _embedLock = null })
+  return _embedLock
+}
+
+async function _runEnsureEmbeddings(memory) {
+  const modelKey = memory.embedder.model
+  const stored = memory.db.prepare(`SELECT value FROM meta WHERE key = 'embedding_model'`).get()?.value
+  if (stored !== modelKey) {
+    // 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()
+    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 ${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) {
+    // 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${safeSliceUTF16(r.content, EMBED_TEXT_MAX_LEN)}`)
+  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))
+
+  // 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)
+}
+
+/**
+ * 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}`)
+  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
+}
+
+/**
+ * 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 }) {
+  const origin = normalizeOrigin(dir) // §6.11 写缝归一（目录 I/O 用原样 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, origin).map((r) => [r.path, r.mtime_ms]),
+  )
+
+  let added = 0, updated = 0, skipped = 0
+  for (const filename of names) {
+    let mtimeMs
+    // 档在 readdir 与 stat 之间消失 / 不可读 ⇒ 跳过本行（**不**移出 stale 候选：该文件已无
+    // 盘面依据，交由下方清理移除其索引行——避免 stat 抛出打断整趟 sync，调用面
+    // `deleteByUid` 先 unlink 后 syncDir，抛出即「删除已成功却报失败」）
+    try { mtimeMs = Math.floor((await stat(join(dir, filename))).mtimeMs) } catch { continue }
+    const old = indexed.get(filename)
+    const isNew = old === undefined
+    if (!isNew && old === mtimeMs) {
+      // 已见且未变：行完好——**必须**移出 stale 候选（既有缺陷修复：原 `continue` 不带
+      // delete ⇒ 未变文件被下方清理误删，索引在两次 sync 间 1→0→1 翻覆；T-O1 暴露）
+      skipped++
+      indexed.delete(filename)
+      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, origin, stale)
+    removed++
+  }
+  return { added, updated, removed, skipped }
+}
+
+/** Parse a single .md and upsert into the files table */
+export async function indexMarkdownFile(memory, { layer, dir, filename, mtimeMs }) {
+  const origin = normalizeOrigin(dir) // §6.11 写缝归一（文件 I/O 用原样 dir；origin 列用归一值）
+  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, origin, filename, meta.type, meta.title, content, tags, meta.author, mtime,
+    segmentCJK(meta.title), segmentCJK(content), segmentCJK(tags), Date.now(),
+  )
+}
+
+/** 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
+      .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)
+}
+
+/** §6 clear action: wipe ALL personal entries (pure DB rows — files are project/team only).
+ *  FTS + embedding go with the row triggers. Returns the number of deleted rows. */
+export function clearPersonal(memory) {
+  const { changes } = memory.db.prepare(`DELETE FROM entries`).run()
+  return changes
+}
+
+/**
+ * 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, FTS_TOKEN_MAX)
+    .map((t) => segmentCJK(t))
+  if (terms.length === 0) return ""
+  return terms.map((t) => `"${t.replaceAll('"', '""')}"`).join(" OR ")
+}

package/memory/delete.mjs

@@ -0,0 +1,242 @@
+/**
+ * memory/delete.mjs — file-layer disk-truth row match + deletion family.
+ *
+ * Split out of core.mjs (2026-09-08 — core.mjs crossed the 500-line hard limit).
+ * Owns: the shared §6 list/batch-delete row match (matchMemoryRows/diskFileRows/
+ * likePattern — one match surface, MEMORY.md §6), single/batch deletion
+ * (deleteByUid/deleteWhere), the legacy personal-only compat shell (remove),
+ * file-row fetching and path containment (fetchFileEntry/assertPathInside).
+ *
+ * Imports CRUD/retrieval/sync primitives from core.mjs (fetchEntry/syncDir) —
+ * one direction, no cycle.
+ */
+
+import { parseEntry } from "../markdown.mjs"
+import { readFile, stat, readdir, unlink } from "node:fs/promises"
+import { join, resolve } from "node:path"
+import { fetchEntry, syncDir } from "./core.mjs"
+import { normalizeOrigin } from "./origin.mjs"
+
+/** LIKE pattern from a keyword (wildcards escaped — literal substring match, MEMORY.md §6 keyword filter). */
+function likePattern(keyword) {
+  return `%${keyword.replace(/[\\%_]/g, (c) => `\\${c}`)}%`
+}
+
+/**
+ * Shared row query for the §6 list action and the §6 batch delete (one match surface —
+ * rows carry { layer, id, type, title, ts }). Filters:
+ *   layer: "personal" | "project" | "team" | null (null = all layers)
+ *   type / keyword: optional (keyword matches title OR content, substring)
+ * Personal rows come from the entries table; project/team rows come from a DISK scan of
+ * the managed dir (2026-09-05 fix — disk is the truth): files present on disk but
+ * missing from the files index (orphans: external copies / gitmem pull / an earlier
+ * index failure) were invisible to list AND immune to batch delete — the old table-only
+ * match surface made a layer wipe need repeated delete rounds (deleteWhere→syncDir
+ * re-indexed the orphans one round later). Scanning disk keeps list and batch delete
+ * consistent with what the user can see and delete. Rows from other projects'/team
+ * repos' dirs stay out (the scan only covers the dirs this memory context manages).
+ * Malformed files are skipped (parseEntry failure — same semantics as syncDir). Sorted
+ * by ts (created/updated, ms) DESC.
+ */
+export async function matchMemoryRows(memory, { layer = null, type = null, keyword = null, projectDir = null, teamDir = null } = {}) {
+  const rows = []
+  const wantLayer = (l) => !layer || layer === l
+  if (wantLayer("personal")) {
+    let sql = `SELECT id, type, title, created_at AS ts FROM entries`
+    const cond = []
+    const params = []
+    if (type) { cond.push("type = ?"); params.push(type) }
+    if (keyword) { cond.push("(title LIKE ? ESCAPE '\\' OR content LIKE ? ESCAPE '\\')"); const p = likePattern(keyword); params.push(p, p) }
+    if (cond.length) sql += " WHERE " + cond.join(" AND ")
+    sql += " ORDER BY created_at DESC"
+    for (const r of memory.db.prepare(sql).all(...params)) {
+      rows.push({ layer: "personal", id: `personal:${r.id}`, uid: `personal:${r.id}`, type: r.type, title: r.title, ts: r.ts })
+    }
+  }
+  if (wantLayer("project") && projectDir) {
+    // §6.11 删/读缝归一：uid 的 origin 段与索引行的 origin 必须同一形态
+    const org = normalizeOrigin(projectDir)
+    for (const r of await diskFileRows(projectDir, type, keyword)) rows.push({ ...r, layer: "project", id: `project:${org}:${r.path}` })
+  }
+  if (wantLayer("team") && teamDir) {
+    const org = normalizeOrigin(teamDir)
+    for (const r of await diskFileRows(teamDir, type, keyword)) rows.push({ ...r, layer: "team", id: `team:${org}:${r.path}` })
+  }
+  rows.sort((a, b) => (b.ts ?? 0) - (a.ts ?? 0))
+  return rows
+}
+
+/**
+ * Disk-truth file scan for the project/team layer (2026-09-05 fix — see matchMemoryRows):
+ * readdir + parse every .md entry in dir, filter by type equality and keyword substring
+ * on title OR content (case-insensitive — SQLite LIKE parity). ts = file mtime (ms).
+ * Rows come back WITHOUT the layer field — the caller stamps layer and builds the uid.
+ */
+async function diskFileRows(dir, type, keyword) {
+  let names
+  try {
+    names = (await readdir(dir)).filter((n) => n.endsWith(".md"))
+  } catch {
+    return []
+  }
+  const kw = keyword ? keyword.toLowerCase() : null
+  const out = []
+  for (const name of names) {
+    try {
+      const abs = join(dir, name)
+      const { meta, content } = parseEntry(await readFile(abs, "utf8"))
+      if (type && meta.type !== type) continue
+      if (kw && !(meta.title.toLowerCase().includes(kw) || content.toLowerCase().includes(kw))) continue
+      const mtime = Math.floor((await stat(abs)).mtimeMs)
+      out.push({ path: name, type: meta.type, title: meta.title, ts: mtime })
+    } catch (e) {
+      console.error(`[memory] skip ${name}: ${e.message}`)
+    }
+  }
+  out.sort((a, b) => b.ts - a.ts)
+  return out
+}
+
+/**
+ * §6 batch delete (action delete + type/keyword filter, confirm handled by the tool layer):
+ * deletes every row matchMemoryRows returns for the layer. Personal rows go straight to the
+ * DB (FTS + embedding cleanup via row triggers); project/team rows delete the markdown file
+ * (path containment enforced, ENOENT tolerated) then re-sync the layer dir once (index
+ * cleanup single source). Match surface = disk scan (2026-09-05 fix — orphans on disk
+ * with no index row are matched and deleted in the same pass; the trailing syncDir
+ * re-indexes the survivors). Team deletion never touches git — a later gitmem pull may
+ * resurrect the file while the remote still has it (same semantics as deleteByUid).
+ * Returns the number of deleted rows.
+ */
+export async function deleteWhere(memory, { layer, type = null, keyword = null } = {}, { dirs = {} } = {}) {
+  const rows = await matchMemoryRows(memory, { layer, type, keyword, projectDir: dirs.project ?? null, teamDir: dirs.team ?? null })
+  if (rows.length === 0) return 0
+  const personalIds = []
+  const byDir = new Map() // "layer\x00dir" → { layer, dir, paths: [] }
+  for (const r of rows) {
+    if (r.layer === "personal") {
+      const id = Number(String(r.uid).split(":")[1])
+      if (Number.isInteger(id)) personalIds.push(id)
+      continue
+    }
+    const dir = r.layer === "project" ? dirs.project : dirs.team
+    if (!dir) continue
+    const key = `${r.layer}\x00${dir}`
+    let group = byDir.get(key)
+    if (!group) { group = { layer: r.layer, dir, paths: [] }; byDir.set(key, group) }
+    group.paths.push(r.path)
+  }
+  const del = memory.db.prepare(`DELETE FROM entries WHERE id = ?`)
+  for (const id of personalIds) del.run(id)
+  for (const group of byDir.values()) {
+    for (const path of group.paths) {
+      assertPathInside(group.dir, path)
+      const abs = join(group.dir, path)
+      await unlink(abs).catch((e) => { if (e.code !== "ENOENT") throw e })
+    }
+    await syncDir(memory, { layer: group.layer, dir: group.dir })
+  }
+  return rows.length
+}
+
+/** Delete a memory entry by unified id. Returns the deleted entry (F3: { id, layer, type, title, content, tags }).
+ *  - personal:<n> (or bare <n>) → DELETE the entries row; FTS syncs via the entries_ad trigger and the
+ *    embedding BLOB column goes with the row.
+ *  - project:<origin>:<path> / team:<origin>:<path> → delete the markdown file at the uid's ORIGIN dir
+ *    (2026-09-08, MEMORY.md §6.2: search rows surfaced from a non-current origin — another project's
+ *    memory dir / another team clone — must be deletable where the file actually lives; the caller's
+ *    dirs[layer] is only the fallback base for origin-less legacy uids `project::file.md`/`project:file.md`).
+ *    Path containment is enforced against that base (assertPathInside — `..`/absolute variants incl.
+ *    `..\` are rejected), then syncDir clears the files row (single source of index cleanup). ENOENT on
+ *    the file is treated as already-deleted and continues; when the origin dir is missing locally,
+ *    syncDir still drops the stale (layer, origin) index rows (readdir of a missing dir yields nothing —
+ *    every row of a vanished dir is stale). Team deletion never touches git (git propagation is gitmem's
+ *    job; a later gitmem pull may resurrect the file while the remote still has it).
+ *  Throws on invalid id / missing entry (NF2) / path escaping the base dir.
+ *  2026-09-08 (code review): the orphan-disk fallback below is confined to managed memory dirs —
+ *    an unmanaged origin must not make deleteByUid a crafted-id deletion primitive. */
+export async function deleteByUid(memory, uid, { dirs = {} } = {}) {
+  const norm = /^\d+$/.test(uid) ? `personal:${uid}` : String(uid)
+  const [layer, ...rest] = norm.split(":")
+  if (layer === "personal") {
+    // 畸形尾缀拒绝（2026-09-08 代码正确性批 2.2）：personal:5:extra 不得静默删 id=5
+    if (norm.split(":").length > 2) throw new Error(`invalid memory id: ${norm}`)
+    const id = rest[0] ?? ""
+    if (!/^\d+$/.test(id)) throw new Error(`invalid memory id: ${norm}`)
+    const entry = fetchEntry(memory, norm)
+    if (!entry) throw new Error(`memory ${norm} not found in layer personal`)
+    memory.db.prepare(`DELETE FROM entries WHERE id = ?`).run(Number(id))
+    return entry
+  }
+  if (layer !== "project" && layer !== "team") throw new Error(`invalid memory id: ${norm}`)
+  // origin = between the layer prefix and the LAST colon (origins may contain colons — Windows drive
+  // letters); path = segment after the last colon. Empty origin = legacy uid (`project::file.md` /
+  // `project:file.md`) → dirs[layer] fallback.
+  const lastColon = norm.lastIndexOf(":")
+  // §6.11 删面归一（uid 解析面）：uid 内 origin 与库内键同一形态——旧形态 uid（`C:\…`）仍可直接删；
+  // `path` = 末冒号后段（原样）；`origin` 空串 = 旧式无 origin uid ⇒ 落到 `dirs[layer]` 基准。
+  const origin = normalizeOrigin(lastColon > layer.length ? norm.slice(layer.length + 1, lastColon) : "")
+  const path = lastColon > layer.length ? norm.slice(lastColon + 1) : norm.slice(layer.length + 1)
+  const dir = origin || normalizeOrigin(dirs[layer])
+  if (!dir) throw new Error(`${layer} layer unavailable: no ${layer} directory configured for an origin-less id`)
+  assertPathInside(dir, path)
+  // Entry lookup: exact (layer, origin, path) row for origin-ful uids — the delete target is the uid's
+  // own dir, so a path-only fallback row from another origin must not be reported as deleted.
+  // Origin-less legacy uids keep the compat fallbacks (fetchFileEntry: current-origin then path-only).
+  let entry = null
+  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) entry = { ...r, layer, id: norm }
+  } else {
+    entry = fetchFileEntry(memory, layer, norm, path)
+  }
+  const abs = join(dir, path)
+  let fileExists = false
+  try { await stat(abs); fileExists = true } catch { /* ENOENT — treat as already deleted */ }
+  if (!entry && fileExists) {
+    // Origin confinement (2026-09-08 code review): the orphan fallback deletes a file that has NO
+    // index row — only allow it when the origin is a managed memory dir (it already has files rows,
+    // or it is the caller's current layer dir). A uid naming an unmanaged directory must not delete
+    // a memory-shaped .md there.
+    if (origin && origin !== normalizeOrigin(dirs[layer])) {
+      const known = memory.db.prepare(`SELECT 1 FROM files WHERE layer = ? AND origin = ? LIMIT 1`).get(layer, origin)
+      if (!known) throw new Error(`memory ${norm} not found in layer ${layer}: origin is not a managed ${layer} memory dir`)
+    }
+    try {
+      const { meta, content } = parseEntry(await readFile(abs, "utf8"))
+      entry = { layer, id: norm, type: meta.type, title: meta.title, content, tags: meta.tags.join(" ") }
+    } catch { /* malformed file — keep the DB row (or null → not found below) */ }
+  }
+  if (!entry) throw new Error(`memory ${norm} not found in layer ${layer}`)
+  if (fileExists) await unlink(abs).catch((e) => { if (e.code !== "ENOENT") throw e })
+  await syncDir(memory, { layer, dir })
+  return entry
+}
+
+/** Legacy personal-only delete (bare numeric id) — kept as the compat surface over deleteByUid. */
+export async function remove(memory, id) {
+  const uid = /^\d+$/.test(String(id)) ? `personal:${id}` : String(id)
+  if (!fetchEntry(memory, uid)) return false
+  await deleteByUid(memory, uid, {})
+  return true
+}
+
+/** Fetch a project/team file row for deletion: fetchEntry first, then a path-only fallback
+ *  (origins with Windows drive letters, e.g. project:C:\dir:file.md, break naive ":" splitting). */
+function fetchFileEntry(memory, layer, uid, path) {
+  const entry = fetchEntry(memory, uid)
+  if (entry) return entry
+  const r = memory.db.prepare(`SELECT type, title, content, tags, author FROM files WHERE layer = ? AND path = ?`).get(layer, path)
+  return r ? { ...r, layer, id: uid } : null
+}
+
+/** Separator-agnostic containment check: the resolved path must stay inside dir.
+ *  Both / and \ count as separators, so Windows-style traversal (..\..\\x) is caught on every platform. */
+function assertPathInside(dir, path) {
+  if (!path) throw new Error(`invalid memory id: empty path`)
+  const base = resolve(dir).replaceAll("\\", "/")
+  const abs = resolve(dir, path.replaceAll("\\", "/")).replaceAll("\\", "/")
+  if (abs !== base && !abs.startsWith(base + "/")) {
+    throw new Error(`invalid memory path "${path}": must stay within ${dir}`)
+  }
+}