@thincoder/core 0.9.1

package/memory/scan.mjs

@@ -0,0 +1,177 @@
+/**
+ * memory/scan.mjs — 检索向量通道的分块扫描 + 有界 top-K。
+ * （TUI-OOM-ROOTCAUSE 批——MEMORY.md §10；扫描面修复批——§6.10 修法 A1/A2，2026-09-18。）
+ *
+ * 病灶一（调度面 · §6.10）：块循环**零 `await`** ⇒ 独占事件循环（TUI 假死：滚轮 / 键盘 /
+ * 渲染与 agent 同一条事件循环）。
+ * 病灶二（访问序面 · §6.10）：游标 = rowid 序，而两张大表索引序 = PK `(origin, path,
+ * line_start)` ⇒ 每块 `USE TEMP B-TREE FOR ORDER BY`（重排**整个过滤集**，SELECT 含
+ * `embedding` ⇒ 排序物化带 blob；真库实测单表 29.4 s）。
+ *
+ * 修法 A2（让出 · 只改调度）：块内每 `SCAN_YIELD_CHECK_ROWS` 行读一次钟，自上次让出累计
+ * ≥ `SCAN_YIELD_MS` 即 `await yieldFn()`；**块边界同判**（同一预算——预算未耗不白让出）。
+ * 访问序 / 评分 / top-K 候选集 / 并列稳定规则**零变**。
+ * 修法 A1（PK 游标 · 只改访问序）：游标列由调用点声明（`cursorKey`，缺省 `["rowid"]` =
+ * 现行为）；键 = **表 PK 去掉「被等值过滤的前缀列」**——SQLite 只把与索引列序对齐的元组
+ * 比较用作 seek；被等值约束的前导列留在元组里则整条谓词退化为**残余过滤**（每块从头扫起 =
+ * 静默二次方，且无 `TEMP B-TREE`、无报错——§6.10 否决形）。
+ *
+ * 对外结构不变：调用方拿到的仍是 `[{id, score}]` 降序候选（RRF 融合输入）——并列分数按
+ * 既有稳定规则（先到先留——与「全量稳定 sort + slice(0,K)」等价）。
+ *
+ * 可测缝（N-M1 · §6.10）：`cursorKey` · `runChunkedQuery(sql, params)`（传入**构建后的**
+ * SQL 与参数——计划面与分页行为皆可机判）· `yieldFn`（缺省 `yieldTick`）· `nowFn`
+ * （缺省 `Date.now`）· `yieldMs`（缺省常量）——让出行为可**确定性**断言，不依赖真实时钟。
+ */
+
+import { yieldTick } from "./code-index.mjs"
+
+/** 单块行数（单源——三处共用；D-M2：块内存量级 KB~MB，随维度有界）。 */
+export const SCAN_CHUNK_ROWS = 2_000
+
+/** 让出检查间隔（行）——每处理这么多行读一次时钟（§6.10 修法 A2）。 */
+export const SCAN_YIELD_CHECK_ROWS = 64
+
+/** 让出预算（毫秒）——自上次让出累计达此值即让出（§6.10 修法 A2；D-MEM17）。 */
+export const SCAN_YIELD_MS = 50
+
+/** 缺省游标键 = rowid（**即现行为**——`entries` / `files` 两调用点零改，§6.10 逐调用点表）。 */
+const DEFAULT_CURSOR_KEY = ["rowid"]
+
+/**
+ * 有界 top-K（升序小顶堆）：`push({id, score})` 摊销 O(log K)；`list()` 返回降序
+ * `[{id, score}]`。并列分数先到先留（与全量稳定排序一致）。
+ */
+export function createTopK(k) {
+  const cap = Math.max(1, k)
+  const heap = [] // 升序小顶堆（堆顶 = 当前最差）
+  let seq = 0
+
+  /** a 比 b 更差？（分低者差；同分 → 迟到者差（seq 大）——堆顶恒为最差） */
+  const worse = (a, b) => a.score < b.score || (a.score === b.score && a.seq > b.seq)
+  /** a 严格优于 b？（同分不互优——先到先留） */
+  const strictlyBetter = (a, b) => a.score > b.score || (a.score === b.score && a.seq < b.seq)
+  const siftUp = (i) => {
+    while (i > 0) {
+      const p = (i - 1) >> 1
+      if (worse(heap[i], heap[p])) { const t = heap[i]; heap[i] = heap[p]; heap[p] = t; i = p; continue }
+      break
+    }
+  }
+  const siftDown = (i) => {
+    for (;;) {
+      const l = i * 2 + 1
+      const r = l + 1
+      let worst = i
+      if (l < heap.length && worse(heap[l], heap[worst])) worst = l
+      if (r < heap.length && worse(heap[r], heap[worst])) worst = r
+      if (worst === i) break
+      const t = heap[i]; heap[i] = heap[worst]; heap[worst] = t
+      i = worst
+    }
+  }
+
+  return {
+    get size() { return heap.length },
+    push(item) {
+      const node = { id: item.id, score: item.score, seq: seq++ }
+      if (heap.length < cap) { heap.push(node); siftUp(heap.length - 1); return true }
+      if (!strictlyBetter(node, heap[0])) return false // 不优于当前最差（含同分迟到）→ 丢弃（先到先留）
+      heap[0] = node
+      siftDown(0)
+      return true
+    },
+    /** 降序 [{id, score}]（K 上限——与「全量 sort desc + slice(0,K)」逐条等价）。 */
+    list() {
+      return [...heap]
+        .sort((a, b) => (b.score - a.score) || (a.seq - b.seq))
+        .map((n) => ({ id: n.id, score: n.score }))
+    },
+  }
+}
+
+/** 末行键值元组：任一键列缺失（`undefined` / `null`）⇒ `null`（防呆①：等价现 `:90`）。 */
+function cursorValues(keys, row) {
+  if (!row) return null
+  const out = []
+  for (const k of keys) {
+    const v = row[k]
+    if (v === undefined || v === null) return null
+    out.push(v)
+  }
+  return out
+}
+
+/** 文本键比较（`-1` / `0` / `1`）：**与 SQLite BINARY 同序**（UTF-8 字节序 = 码点序）。
+ *  JS 字符串 `<`/`>` 是 UTF-16 码元序——键含增补平面字符（emoji 等 U+10000+）且相邻处有
+ *  U+E000–U+FFFF 字符时与 BINARY 相抵 ⇒ 防呆①会误判「游标未前进」而**提前止**（静默少覆盖）。 */
+function compareText(x, y) {
+  const c = Buffer.compare(Buffer.from(x, "utf8"), Buffer.from(y, "utf8"))
+  return c === 0 ? 0 : c > 0 ? 1 : -1
+}
+
+/** 键元组序比较：数值按数值、其余按 BINARY 同序文本（`-1` / `0` / `1`）。 */
+function compareKeyTuples(a, b) {
+  for (let i = 0; i < a.length; i++) {
+    const x = a[i], y = b[i]
+    if (x === y) continue
+    if (typeof x === "number" && typeof y === "number") return x > y ? 1 : -1
+    return compareText(String(x), String(y))
+  }
+  return 0
+}
+
+/**
+ * 分块扫描（键序游标——§6.10 修法 A1）+ 时间片让出（修法 A2）：逐块物化 → 逐行 `onRow`
+ * → 块内存随迭代释放。
+ * @param {object} db  sqlite 句柄（`.prepare(sql).all(...params)`）
+ * @param {string} sql 单表查询（须含键列【见 `cursorKey`】；不含 ORDER BY / LIMIT）
+ * @param {Array}  params 绑定参数（`?` 占位——顺序与 SQL 一致）
+ * @param {object} opts `{ chunk, onRow, runChunkedQuery, cursorKey, yieldFn, nowFn, yieldMs }`
+ * @returns {Promise<number>} 扫描到的行数
+ */
+export async function scanVectors(db, sql, params = [], {
+  chunk = SCAN_CHUNK_ROWS,
+  onRow = null,
+  runChunkedQuery = null,
+  cursorKey = DEFAULT_CURSOR_KEY,
+  yieldFn = yieldTick,
+  nowFn = Date.now,
+  yieldMs = SCAN_YIELD_MS,
+} = {}) {
+  const run = runChunkedQuery ?? ((q, p) => db.prepare(q).all(...p))
+  const keys = Array.isArray(cursorKey) && cursorKey.length > 0 ? cursorKey : DEFAULT_CURSOR_KEY
+  const keyList = keys.join(", ")
+  const orderBy = `ORDER BY ${keyList}`
+  // 首块不带游标谓词（否决哨兵值——哨兵须假设列域下界）；中块 = 与索引列序对齐的元组比较
+  const firstSql = `${sql} ${orderBy} LIMIT ?`
+  const midSql = `${sql} AND (${keyList}) > (${keys.map(() => "?").join(", ")}) ${orderBy} LIMIT ?`
+
+  let cursor = null
+  let total = 0
+  let checked = 0
+  let lastYieldAt = nowFn()
+  /** 时间片预算：自上次让出累计 ≥ `yieldMs` ⇒ 让出（`yieldMs: Infinity` = 不让出）。 */
+  const mightYield = async () => {
+    if (nowFn() - lastYieldAt >= yieldMs) { await yieldFn(); lastYieldAt = nowFn() }
+  }
+
+  for (;;) {
+    const rows = (cursor === null
+      ? run(firstSql, [...params, chunk])
+      : run(midSql, [...params, ...cursor, chunk])) ?? []
+    if (rows.length === 0) break
+    for (const r of rows) {
+      total++
+      onRow?.(r)
+      if (++checked >= SCAN_YIELD_CHECK_ROWS) { checked = 0; await mightYield() }
+    }
+    const next = cursorValues(keys, rows[rows.length - 1])
+    // 防呆①：键值缺失 ∨ 末键元组未严格大于上一游标键 ⇒ 止（游标不前进即止——防异常行序空转）
+    if (!next || (cursor !== null && compareKeyTuples(next, cursor) <= 0)) break
+    cursor = next
+    if (rows.length < chunk) break // 防呆②：尾块（末块读尽——不再多打一次空查询）
+    await mightYield() // 块边界同判（同一预算）
+  }
+  return total
+}

package/memory/schema.mjs

@@ -0,0 +1,460 @@
+/**
+ * memory/schema.mjs — database schema definition, migration, CJK segmentation
+ * v1: node:sqlite + FTS5 standalone implementation, zero dependencies.
+ *
+ * Chinese search strategy: FTS5 unicode61 tokenizer + CJK character-by-character spacing (applied to both write and query sides).
+ * Effect: Chinese indexed by character; two-character words like "分号" still match; ASCII stays whole-word.
+ */
+
+import { DatabaseSync } from "node:sqlite"
+import { mkdirSync } from "node:fs"
+import { dirname } from "node:path"
+
+export const VALID_TYPES = new Set(["rule", "knowledge", "decision", "pattern"])
+export const SCHEMA_VERSION = 9
+export const SQLITE_BUSY_TIMEOUT = 3000
+/** WAL 回收后的文件截断上界（§6.12 修法①——防复胀；实测曾达 587 MB）。 */
+export const WAL_SIZE_LIMIT_BYTES = 64 * 1024 * 1024
+
+// Code index: source file extensions. Curated DEFAULTS — a project can declare
+// more (union) through .thincoder/conventions.json → index.codeExtensions
+// (PORTABILITY PO-9: an unlisted extension used to be invisible AND undeclarable).
+export const CODE_EXTS = new Set([
+  ".mjs", ".js", ".cjs", ".mts", ".cts", ".ts", ".tsx", ".jsx",
+  ".py", ".rs", ".go", ".java", ".c", ".h", ".cpp", ".hpp",
+  ".rb", ".swift", ".kt", ".dart", ".lua", ".cs", ".fs", ".fsx",
+  ".clj", ".cljs", ".ex", ".exs", ".erl", ".hrl", ".scala", ".groovy",
+  ".pl", ".pm", ".r", ".jl", ".zig", ".ps1",
+  ".sh", ".bash", ".sql", ".yaml", ".yml", ".toml", ".json",
+  ".proto", ".graphql", ".tf", ".hcl",
+  ".css", ".html", ".vue", ".svelte",
+])
+// Doc index: markdown / plain text (separate index makes it easier for LLM to distinguish "design specs" from "existing code")
+// Same declaration rule as CODE_EXTS (index.docExtensions).
+export const DOC_EXTS = new Set([".md", ".mdc", ".mdx", ".txt", ".rst", ".adoc", ".org", ".wiki", ".tex"])
+// Directory names always skipped during code/doc indexing
+// NOTE: these are case-sensitive basename matches; add common platform-specific dirs
+export const SKIP_DIRS = new Set([
+  "node_modules", ".git", "dist", "build", ".turbo", "coverage",
+  "__pycache__", ".venv", "venv", "target", ".next", ".nuxt", ".svelte-kit",
+  // Windows user profile directories (never contain project code)
+  "AppData", "Application Data", "Desktop", "Documents", "Downloads",
+  "Music", "Pictures", "Videos", "OneDrive", "Contacts", "Favorites",
+  "Links", "Saved Games", "Searches",
+  // Other common non-code directories
+  "Program Files", "Program Files (x86)", "Windows", "$Recycle.Bin",
+])
+// Files larger than these limits are skipped during bulk indexing
+// (minified bundles, test fixtures, generated code, etc.)
+export const MAX_CODE_FILE_BYTES = 1024 * 1024   // 1 MB
+export const MAX_DOC_FILE_BYTES  = 512 * 1024    // 512 KB
+export const BIG_FILE_LINES = 2000
+
+/**
+ * CJK character-by-character spacing: makes unicode61 treat each Han/Kana/Hangul character as an independent token.
+ * Both write and query must use the same processing for retrieval to match.
+ */
+export function segmentCJK(text) {
+  return text.replace(
+    /[぀-ヿ㐀-䶿一-鿿豈-﫿가-힯]+/g,
+    (run) => [...run].join(" "),
+  )
+}
+
+/**
+ * Open/initialize the memory store. dbPath is auto-created if missing.
+ * The returned memory object is the interface; all subsequent functions take it as their first argument.
+ */
+export function createMemory({ dbPath }) {
+  mkdirSync(dirname(dbPath), { recursive: true })
+  const db = new DatabaseSync(dbPath)
+  // WAL: reads and writes don't block each other (TUI search and background indexing can run concurrently); busy_timeout prevents SQLITE_BUSY from multi-process same-db access
+  db.exec(`PRAGMA journal_mode = WAL`)
+  db.exec(`PRAGMA busy_timeout = ${SQLITE_BUSY_TIMEOUT}`)
+  // §6.12 WAL 卫生（TUI 假死批）：① `journal_size_limit` = 回收后 WAL 文件截断上界（防复胀）；
+  // ② 开库**一次性** `wal_checkpoint(TRUNCATE)`——失败容忍（另一实例持读事务 ⇒ busy：静默跳过，
+  // 不重试不报错）。边界写实：最坏等待上界 = 连接上的 `busy_timeout`（**不是**「不阻塞」；
+  // `wal_checkpoint` 是否走 busy handler = unverified——判据面 = 批档 §2.5 T-W2）。
+  db.exec(`PRAGMA journal_size_limit = ${WAL_SIZE_LIMIT_BYTES}`)
+  try { db.exec(`PRAGMA wal_checkpoint(TRUNCATE)`) } catch { /* busy / 非 WAL（内存库）⇒ 保持现状 */ }
+
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS entries (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      type TEXT NOT NULL CHECK(type IN ('rule','knowledge','decision','pattern')),
+      title TEXT NOT NULL,
+      content TEXT NOT NULL,
+      tags TEXT NOT NULL DEFAULT '',
+      seg_title TEXT NOT NULL DEFAULT '',
+      seg_content TEXT NOT NULL DEFAULT '',
+      seg_tags TEXT NOT NULL DEFAULT '',
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL
+    )
+  `)
+
+  migrate(db)
+  return { db }
+}
+
+/** Step-by-step migration by user_version. Single transaction — any step failure rolls back, no half-finished schema left behind. */
+export function migrate(db) {
+  const { user_version: version } = db.prepare(`PRAGMA user_version`).get()
+  if (version >= SCHEMA_VERSION) return
+
+  db.exec("BEGIN IMMEDIATE")
+  try {
+  if (version < 2) {
+    // v1 (trigram) or empty DB → v2 (unicode61 + CJK char-by-char): rebuild FTS and triggers
+    db.exec(`
+      DROP TRIGGER IF EXISTS entries_ai;
+      DROP TRIGGER IF EXISTS entries_ad;
+      DROP TRIGGER IF EXISTS entries_au;
+      DROP TABLE IF EXISTS entries_fts;
+    `)
+    // Old DB (v1) has no seg columns — add them
+    const columns = db.prepare(`PRAGMA table_info(entries)`).all().map((c) => c.name)
+    for (const col of ["seg_title", "seg_content", "seg_tags"]) {
+      if (!columns.includes(col)) {
+        db.exec(`ALTER TABLE entries ADD COLUMN ${col} TEXT NOT NULL DEFAULT ''`)
+      }
+    }
+    // Backfill seg columns (segmentation done in JS; SQL can't do it)
+    const rows = db.prepare(`SELECT id, title, content, tags FROM entries`).all()
+    const update = db.prepare(`UPDATE entries SET seg_title = ?, seg_content = ?, seg_tags = ? WHERE id = ?`)
+    for (const r of rows) {
+      update.run(segmentCJK(r.title), segmentCJK(r.content), segmentCJK(r.tags), r.id)
+    }
+
+    db.exec(`
+      CREATE VIRTUAL TABLE entries_fts USING fts5(
+        seg_title, seg_content, seg_tags,
+        content='entries', content_rowid='id',
+        tokenize='unicode61'
+      )
+    `)
+    db.exec(`
+      CREATE TRIGGER entries_ai AFTER INSERT ON entries BEGIN
+        INSERT INTO entries_fts(rowid, seg_title, seg_content, seg_tags)
+        VALUES (new.id, new.seg_title, new.seg_content, new.seg_tags);
+      END;
+      CREATE TRIGGER entries_ad AFTER DELETE ON entries BEGIN
+        INSERT INTO entries_fts(entries_fts, rowid, seg_title, seg_content, seg_tags)
+        VALUES ('delete', old.id, old.seg_title, old.seg_content, old.seg_tags);
+      END;
+      CREATE TRIGGER entries_au AFTER UPDATE ON entries BEGIN
+        INSERT INTO entries_fts(entries_fts, rowid, seg_title, seg_content, seg_tags)
+        VALUES ('delete', old.id, old.seg_title, old.seg_content, old.seg_tags);
+        INSERT INTO entries_fts(rowid, seg_title, seg_content, seg_tags)
+        VALUES (new.id, new.seg_title, new.seg_content, new.seg_tags);
+      END;
+    `)
+    db.exec(`INSERT INTO entries_fts(entries_fts) VALUES('rebuild')`)
+    db.exec(`PRAGMA user_version = 2`)
+  }
+
+  if (version < 3) {
+    // v3: markdown layer (project/team) files table + FTS + triggers
+    db.exec(`
+      CREATE TABLE IF NOT EXISTS files (
+        layer TEXT NOT NULL CHECK(layer IN ('project','team')),
+        path TEXT NOT NULL,
+        type TEXT NOT NULL CHECK(type IN ('rule','knowledge','decision','pattern')),
+        title TEXT NOT NULL,
+        content TEXT NOT NULL,
+        tags TEXT NOT NULL DEFAULT '',
+        author TEXT NOT NULL DEFAULT '',
+        embedding BLOB,
+        mtime_ms INTEGER NOT NULL DEFAULT 0,
+        seg_title TEXT NOT NULL DEFAULT '',
+        seg_content TEXT NOT NULL DEFAULT '',
+        seg_tags TEXT NOT NULL DEFAULT '',
+        updated_at INTEGER NOT NULL,
+        PRIMARY KEY (layer, path)
+      )
+    `)
+    db.exec(`
+      CREATE VIRTUAL TABLE IF NOT EXISTS files_fts USING fts5(
+        seg_title, seg_content, seg_tags,
+        content='files', content_rowid='rowid',
+        tokenize='unicode61'
+      )
+    `)
+    db.exec(`
+      CREATE TRIGGER files_ai AFTER INSERT ON files BEGIN
+        INSERT INTO files_fts(rowid, seg_title, seg_content, seg_tags)
+        VALUES (new.rowid, new.seg_title, new.seg_content, new.seg_tags);
+      END;
+      CREATE TRIGGER files_ad AFTER DELETE ON files BEGIN
+        INSERT INTO files_fts(files_fts, rowid, seg_title, seg_content, seg_tags)
+        VALUES ('delete', old.rowid, old.seg_title, old.seg_content, old.seg_tags);
+      END;
+      CREATE TRIGGER files_au AFTER UPDATE ON files BEGIN
+        INSERT INTO files_fts(files_fts, rowid, seg_title, seg_content, seg_tags)
+        VALUES ('delete', old.rowid, old.seg_title, old.seg_content, old.seg_tags);
+        INSERT INTO files_fts(rowid, seg_title, seg_content, seg_tags)
+        VALUES (new.rowid, new.seg_title, new.seg_content, new.seg_tags);
+      END;
+    `)
+    db.exec(`PRAGMA user_version = 3`)
+  }
+
+  if (version < 4) {
+    // v4: add vector column to personal entries table (files table already had it since v3); meta table stores embedding model name
+    const columns = db.prepare(`PRAGMA table_info(entries)`).all().map((c) => c.name)
+    if (!columns.includes("embedding")) {
+      db.exec(`ALTER TABLE entries ADD COLUMN embedding BLOB`)
+    }
+    db.exec(`CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value TEXT)`)
+    db.exec(`PRAGMA user_version = 4`)
+  }
+
+  if (version < 5) {
+    // v5: add origin column to files table (absolute project path), prevent cross-project memory collision
+    const columns = db.prepare(`PRAGMA table_info(files)`).all().map((c) => c.name)
+    if (!columns.includes("origin")) {
+      db.exec(`ALTER TABLE files ADD COLUMN origin TEXT NOT NULL DEFAULT ''`)
+    }
+    db.exec(`PRAGMA user_version = 5`)
+  }
+
+  if (version < 6) {
+    // v6: code index — code_chunks table + FTS5 (same pattern as files table)
+    db.exec(`
+      CREATE TABLE IF NOT EXISTS code_chunks (
+        path TEXT NOT NULL,
+        language TEXT NOT NULL,
+        chunk_type TEXT NOT NULL CHECK(chunk_type IN ('file','symbol')),
+        symbol_name TEXT NOT NULL DEFAULT '',
+        content TEXT NOT NULL,
+        line_start INTEGER NOT NULL DEFAULT 0,
+        line_end INTEGER NOT NULL DEFAULT 0,
+        mtime_ms INTEGER NOT NULL DEFAULT 0,
+        embedding BLOB,
+        seg_content TEXT NOT NULL DEFAULT '',
+        PRIMARY KEY (path, line_start)
+      )
+    `)
+    db.exec(`
+      CREATE VIRTUAL TABLE IF NOT EXISTS code_chunks_fts USING fts5(
+        path, symbol_name, seg_content,
+        content='code_chunks', content_rowid='rowid',
+        tokenize='unicode61'
+      )
+    `)
+    db.exec(`
+      CREATE TRIGGER code_chunks_ai AFTER INSERT ON code_chunks BEGIN
+        INSERT INTO code_chunks_fts(rowid, path, symbol_name, seg_content)
+        VALUES (new.rowid, new.path, new.symbol_name, new.seg_content);
+      END;
+      CREATE TRIGGER code_chunks_ad AFTER DELETE ON code_chunks BEGIN
+        INSERT INTO code_chunks_fts(code_chunks_fts, rowid, path, symbol_name, seg_content)
+        VALUES ('delete', old.rowid, old.path, old.symbol_name, old.seg_content);
+      END;
+      CREATE TRIGGER code_chunks_au AFTER UPDATE ON code_chunks BEGIN
+        INSERT INTO code_chunks_fts(code_chunks_fts, rowid, path, symbol_name, seg_content)
+        VALUES ('delete', old.rowid, old.path, old.symbol_name, old.seg_content);
+        INSERT INTO code_chunks_fts(rowid, path, symbol_name, seg_content)
+        VALUES (new.rowid, new.path, new.symbol_name, new.seg_content);
+      END;
+    `)
+    db.exec(`PRAGMA user_version = 6`)
+  }
+
+  if (version < 7) {
+    // v7: doc index — doc_chunks table + FTS5 (same pattern as code_chunks), markdown chunked by ## headings
+    db.exec(`
+      CREATE TABLE IF NOT EXISTS doc_chunks (
+        path TEXT NOT NULL,
+        language TEXT NOT NULL DEFAULT 'markdown',
+        heading TEXT NOT NULL DEFAULT '',
+        content TEXT NOT NULL,
+        line_start INTEGER NOT NULL DEFAULT 0,
+        line_end INTEGER NOT NULL DEFAULT 0,
+        mtime_ms INTEGER NOT NULL DEFAULT 0,
+        embedding BLOB,
+        seg_content TEXT NOT NULL DEFAULT '',
+        PRIMARY KEY (path, line_start)
+      )
+    `)
+    db.exec(`
+      CREATE VIRTUAL TABLE IF NOT EXISTS doc_chunks_fts USING fts5(
+        path, heading, seg_content,
+        content='doc_chunks', content_rowid='rowid',
+        tokenize='unicode61'
+      )
+    `)
+    db.exec(`
+      CREATE TRIGGER doc_chunks_ai AFTER INSERT ON doc_chunks BEGIN
+        INSERT INTO doc_chunks_fts(rowid, path, heading, seg_content)
+        VALUES (new.rowid, new.path, new.heading, new.seg_content);
+      END;
+      CREATE TRIGGER doc_chunks_ad AFTER DELETE ON doc_chunks BEGIN
+        INSERT INTO doc_chunks_fts(doc_chunks_fts, rowid, path, heading, seg_content)
+        VALUES ('delete', old.rowid, old.path, old.heading, old.seg_content);
+      END;
+      CREATE TRIGGER doc_chunks_au AFTER UPDATE ON doc_chunks BEGIN
+        INSERT INTO doc_chunks_fts(doc_chunks_fts, rowid, path, heading, seg_content)
+        VALUES ('delete', old.rowid, old.path, old.heading, old.seg_content);
+        INSERT INTO doc_chunks_fts(rowid, path, heading, seg_content)
+        VALUES (new.rowid, new.path, new.heading, new.seg_content);
+      END;
+    `)
+    db.exec(`PRAGMA user_version = 7`)
+  }
+
+  if (version < 8) {
+    // v8: add origin column to code_chunks/doc_chunks (absolute project root), PK changed to (origin, path, line_start).
+    // SQLite can't ALTER primary key → drop and recreate table (auto-reindexed by next codeSync/docSync).
+    db.exec(`
+      DROP TRIGGER IF EXISTS code_chunks_ai;
+      DROP TRIGGER IF EXISTS code_chunks_ad;
+      DROP TRIGGER IF EXISTS code_chunks_au;
+      DROP TABLE IF EXISTS code_chunks_fts;
+      DROP TABLE IF EXISTS code_chunks;
+      DROP TRIGGER IF EXISTS doc_chunks_ai;
+      DROP TRIGGER IF EXISTS doc_chunks_ad;
+      DROP TRIGGER IF EXISTS doc_chunks_au;
+      DROP TABLE IF EXISTS doc_chunks_fts;
+      DROP TABLE IF EXISTS doc_chunks;
+    `)
+    db.exec(`
+      CREATE TABLE code_chunks (
+        origin TEXT NOT NULL DEFAULT '',
+        path TEXT NOT NULL,
+        language TEXT NOT NULL,
+        chunk_type TEXT NOT NULL CHECK(chunk_type IN ('file','symbol')),
+        symbol_name TEXT NOT NULL DEFAULT '',
+        content TEXT NOT NULL,
+        line_start INTEGER NOT NULL DEFAULT 0,
+        line_end INTEGER NOT NULL DEFAULT 0,
+        mtime_ms INTEGER NOT NULL DEFAULT 0,
+        embedding BLOB,
+        seg_content TEXT NOT NULL DEFAULT '',
+        PRIMARY KEY (origin, path, line_start)
+      )
+    `)
+    db.exec(`
+      CREATE VIRTUAL TABLE code_chunks_fts USING fts5(
+        path, symbol_name, seg_content,
+        content='code_chunks', content_rowid='rowid',
+        tokenize='unicode61'
+      )
+    `)
+    db.exec(`
+      CREATE TRIGGER code_chunks_ai AFTER INSERT ON code_chunks BEGIN
+        INSERT INTO code_chunks_fts(rowid, path, symbol_name, seg_content)
+        VALUES (new.rowid, new.path, new.symbol_name, new.seg_content);
+      END;
+      CREATE TRIGGER code_chunks_ad AFTER DELETE ON code_chunks BEGIN
+        INSERT INTO code_chunks_fts(code_chunks_fts, rowid, path, symbol_name, seg_content)
+        VALUES ('delete', old.rowid, old.path, old.symbol_name, old.seg_content);
+      END;
+      CREATE TRIGGER code_chunks_au AFTER UPDATE ON code_chunks BEGIN
+        INSERT INTO code_chunks_fts(code_chunks_fts, rowid, path, symbol_name, seg_content)
+        VALUES ('delete', old.rowid, old.path, old.symbol_name, old.seg_content);
+        INSERT INTO code_chunks_fts(rowid, path, symbol_name, seg_content)
+        VALUES (new.rowid, new.path, new.symbol_name, new.seg_content);
+      END;
+    `)
+    db.exec(`
+      CREATE TABLE doc_chunks (
+        origin TEXT NOT NULL DEFAULT '',
+        path TEXT NOT NULL,
+        language TEXT NOT NULL DEFAULT 'markdown',
+        heading TEXT NOT NULL DEFAULT '',
+        content TEXT NOT NULL,
+        line_start INTEGER NOT NULL DEFAULT 0,
+        line_end INTEGER NOT NULL DEFAULT 0,
+        mtime_ms INTEGER NOT NULL DEFAULT 0,
+        embedding BLOB,
+        seg_content TEXT NOT NULL DEFAULT '',
+        PRIMARY KEY (origin, path, line_start)
+      )
+    `)
+    db.exec(`
+      CREATE VIRTUAL TABLE doc_chunks_fts USING fts5(
+        path, heading, seg_content,
+        content='doc_chunks', content_rowid='rowid',
+        tokenize='unicode61'
+      )
+    `)
+    db.exec(`
+      CREATE TRIGGER doc_chunks_ai AFTER INSERT ON doc_chunks BEGIN
+        INSERT INTO doc_chunks_fts(rowid, path, heading, seg_content)
+        VALUES (new.rowid, new.path, new.heading, new.seg_content);
+      END;
+      CREATE TRIGGER doc_chunks_ad AFTER DELETE ON doc_chunks BEGIN
+        INSERT INTO doc_chunks_fts(doc_chunks_fts, rowid, path, heading, seg_content)
+        VALUES ('delete', old.rowid, old.path, old.heading, old.seg_content);
+      END;
+      CREATE TRIGGER doc_chunks_au AFTER UPDATE ON doc_chunks BEGIN
+        INSERT INTO doc_chunks_fts(doc_chunks_fts, rowid, path, heading, seg_content)
+        VALUES ('delete', old.rowid, old.path, old.heading, old.seg_content);
+        INSERT INTO doc_chunks_fts(rowid, path, heading, seg_content)
+        VALUES (new.rowid, new.path, new.heading, new.seg_content);
+      END;
+    `)
+    db.exec(`PRAGMA user_version = 8`)
+  }
+
+  if (version < 9) {
+    // v9: files table PK gains origin, prevents cross-project project-layer memory overwrite
+    // SQLite can't ALTER primary key → drop and recreate table (auto-reindexed by next syncDir)
+    db.exec(`
+      DROP TRIGGER IF EXISTS files_ai;
+      DROP TRIGGER IF EXISTS files_ad;
+      DROP TRIGGER IF EXISTS files_au;
+      DROP TABLE IF EXISTS files_fts;
+      DROP TABLE IF EXISTS files;
+    `)
+    db.exec(`
+      CREATE TABLE files (
+        layer TEXT NOT NULL CHECK(layer IN ('project','team')),
+        origin TEXT NOT NULL DEFAULT '',
+        path TEXT NOT NULL,
+        type TEXT NOT NULL CHECK(type IN ('rule','knowledge','decision','pattern')),
+        title TEXT NOT NULL,
+        content TEXT NOT NULL,
+        tags TEXT NOT NULL DEFAULT '',
+        author TEXT NOT NULL DEFAULT '',
+        embedding BLOB,
+        mtime_ms INTEGER NOT NULL DEFAULT 0,
+        seg_title TEXT NOT NULL DEFAULT '',
+        seg_content TEXT NOT NULL DEFAULT '',
+        seg_tags TEXT NOT NULL DEFAULT '',
+        updated_at INTEGER NOT NULL,
+        PRIMARY KEY (layer, origin, path)
+      )
+    `)
+    db.exec(`
+      CREATE VIRTUAL TABLE files_fts USING fts5(
+        seg_title, seg_content, seg_tags,
+        content='files', content_rowid='rowid',
+        tokenize='unicode61'
+      )
+    `)
+    db.exec(`
+      CREATE TRIGGER files_ai AFTER INSERT ON files BEGIN
+        INSERT INTO files_fts(rowid, seg_title, seg_content, seg_tags)
+        VALUES (new.rowid, new.seg_title, new.seg_content, new.seg_tags);
+      END;
+      CREATE TRIGGER files_ad AFTER DELETE ON files BEGIN
+        INSERT INTO files_fts(files_fts, rowid, seg_title, seg_content, seg_tags)
+        VALUES ('delete', old.rowid, old.seg_title, old.seg_content, old.seg_tags);
+      END;
+      CREATE TRIGGER files_au AFTER UPDATE ON files BEGIN
+        INSERT INTO files_fts(files_fts, rowid, seg_title, seg_content, seg_tags)
+        VALUES ('delete', old.rowid, old.seg_title, old.seg_content, old.seg_tags);
+        INSERT INTO files_fts(rowid, seg_title, seg_content, seg_tags)
+        VALUES (new.rowid, new.seg_title, new.seg_content, new.seg_tags);
+      END;
+    `)
+    db.exec(`PRAGMA user_version = 9`)
+  }
+  db.exec("COMMIT")
+  } catch (err) {
+    db.exec("ROLLBACK")
+    throw err
+  }
+}

package/memory.mjs

@@ -0,0 +1,21 @@
+/**
+ * memory.mjs — memory system re-export hub
+ * Submodules in src/memory/ directory, split by responsibility.
+ */
+
+// schema + constants
+export { createMemory, migrate, segmentCJK, VALID_TYPES, SCHEMA_VERSION, CODE_EXTS, DOC_EXTS, SKIP_DIRS, BIG_FILE_LINES } from "./memory/schema.mjs"
+
+// CRUD + search + ensureEmbeddings
+// (delete.mjs owns the disk-truth row match + deletion family — see its header)
+export { put, search, ftsSearch, fetchEntry, ensureEmbeddings, putMarkdown, syncDir, indexMarkdownFile, list, clearPersonal, buildFtsQuery } from "./memory/core.mjs"
+export { matchMemoryRows, deleteWhere, deleteByUid, remove } from "./memory/delete.mjs"
+
+// code chunking + markdown chunking
+export { detectLanguage, extractSymbols, extractPySymbols, chunkCode, extractLeadingDoc, yieldTick, _upsertCodeFile, chunkMarkdown, _upsertDocFile } from "./memory/code-index.mjs"
+
+// code sync + search + reindex
+export { gitSync, codeSync, markIndexedCommit, codeSearch, ensureCodeEmbeddings, codeSearchTool, reindexFile } from "./memory/code-sync.mjs"
+
+// doc sync + search + memoryTools
+export { docSync, docSearch, ensureDocEmbeddings, docSearchTool, memoryTools } from "./memory/docs.mjs"