@@ -1514,35 +1514,99 @@ export function createStore(path) {
15141514 // Issue #202:embedding 解析缓存。检索路径此前每次调用都对全部带向量行
15151515 // JSON.parse(993 × 512 维 ≈ 48 ms/次,且 SQL 拖着 10 MB 的 TEXT),余弦本身
15161516 // 只占 3%。向量只经 setEmbedding 写入(单一失效点),把解析结果按 id 缓存,
1517- // 命中即零解析;上限 FIFO 驱逐防大库内存无界(4000 × 512 维 double ≈ 16 MB)。
1517+ // 命中即零解析。
1518+ //
1519+ // 上限为什么不能是固定常量(2026-11-05 实测):上限 4000、活跃带向量行 6685,
1520+ // 扫到第 4001 条开始驱逐自己刚填的条目,扫完只剩最后 4000 条,下一轮又从第
1521+ // 一条 miss——四轮实测命中率恒 0.0%,缓存等于不存在,每次检索都全量重解析
1522+ // (实测 624 ms)。固定调大只是把复发推到下个月(活跃行近 30 天净增 6156 条,
1523+ // 上限 20000 也只撑到 2027-01-09),所以上限跟工作集自适应:
1524+ // · 每次全量扫(searchVector / vectorDimensionState)在循环前把上限抬到
1525+ // 「本次扫到的行数 ×1.25」,一次扫完不会被自己的驱逐打断;
1526+ // · 内存预算封顶(默认 256 MB),超预算的行仍按 FIFO 驱逐——大库退化回
1527+ // 「部分命中」,不会无界吃内存。
1528+ // 存储用 Float32Array。同一口径(GC 后 heapUsed + arrayBuffers,6730 条
1529+ // 1024 维全常驻)实测:number[] 56.4MB → Float32Array 29.7MB(heap 1.9 +
1530+ // arrayBuffers 27.8),省 26.7MB / 47%。注意 heapUsed 不统计 TypedArray 的
1531+ // 底层 ArrayBuffer,只看 heapUsed 会读成「省 96%」的假象;旧实现若保持上限
1532+ // 4000 则装不下工作集(常驻 31.9MB 但命中率 0%),两者不可比,所以对照组是
1533+ // 把旧上限抬到 20000 让工作集全常驻。cosine 全量 25.4ms → 18.0ms,前 50 条
1534+ // 排序精度差 0.00e+0。对外契约不变:
1535+ // getParsedEmbedding / getEmbeddings 仍返回 number[],只有内部热路径
1536+ // (readVector)拿 Float32Array。
15181537 const embeddingCache = new Map ( ) ;
1519- const EMBEDDING_CACHE_MAX = 4000 ;
1538+ const EMBEDDING_CACHE_FLOOR = 4000 ;
1539+ const EMBEDDING_CACHE_BUDGET_BYTES = 256 * 1024 * 1024 ;
1540+ let embeddingCacheCap = EMBEDDING_CACHE_FLOOR ;
1541+ let embeddingCacheHits = 0 ;
1542+ let embeddingCacheMisses = 0 ;
1543+
1544+ /** Vector-like = number[] or Float32Array (typed). All cosine guards use this
1545+ * instead of Array.isArray, which is false for typed arrays — with the old
1546+ * guard every cached vector would silently score 0. */
1547+ function isVectorLike ( v ) {
1548+ return Array . isArray ( v ) || ( ArrayBuffer . isView ( v ) && ! ( v instanceof DataView ) ) ;
1549+ }
15201550
15211551 function cacheEmbedding ( id , vector ) {
1522- if ( embeddingCache . size >= EMBEDDING_CACHE_MAX && ! embeddingCache . has ( id ) ) {
1552+ if ( embeddingCache . size >= embeddingCacheCap && ! embeddingCache . has ( id ) ) {
15231553 const oldest = embeddingCache . keys ( ) . next ( ) . value ;
15241554 embeddingCache . delete ( oldest ) ;
15251555 }
15261556 embeddingCache . set ( id , vector ) ;
15271557 }
15281558
1529- /** Parsed embedding for one id (cache-first); undefined when none/parse
1530- * failure. Single read path shared by searchVector / getEmbedding(s). */
1531- function getParsedEmbedding ( id ) {
1559+ /** Raise the cap to fit a sweep of `rows` rows (×1.25 headroom), clamped by
1560+ * the memory budget. Called before a full scan so the scan itself does not
1561+ * evict what it just cached. */
1562+ function noteSweep ( rows , avgDim ) {
1563+ if ( ! rows || ! avgDim ) return ;
1564+ const perVector = avgDim * Float32Array . BYTES_PER_ELEMENT ;
1565+ const budgetRows = Math . floor ( EMBEDDING_CACHE_BUDGET_BYTES / perVector ) ;
1566+ const want = Math . ceil ( rows * 1.25 ) ;
1567+ embeddingCacheCap = Math . max ( EMBEDDING_CACHE_FLOOR , Math . min ( budgetRows , want ) ) ;
1568+ }
1569+
1570+ /** Cache-first read returning Float32Array (internal hot path only).
1571+ * undefined when none/parse failure. */
1572+ function readVector ( id ) {
15321573 const cached = embeddingCache . get ( id ) ;
1533- if ( cached ) return cached ;
1574+ if ( cached ) { embeddingCacheHits += 1 ; return cached ; }
1575+ embeddingCacheMisses += 1 ;
15341576 const row = db . prepare ( "SELECT embedding FROM memories WHERE id = ?" ) . get ( id ) ;
15351577 if ( ! row ?. embedding ) return undefined ;
15361578 try {
1537- const v = JSON . parse ( row . embedding ) ;
1538- if ( Array . isArray ( v ) && v . length ) {
1579+ const parsed = JSON . parse ( row . embedding ) ;
1580+ if ( Array . isArray ( parsed ) && parsed . length ) {
1581+ const v = new Float32Array ( parsed ) ;
15391582 cacheEmbedding ( id , v ) ;
15401583 return v ;
15411584 }
15421585 } catch { /* corrupt embedding text: treated as absent */ }
15431586 return undefined ;
15441587 }
15451588
1589+ /** Parsed embedding for one id (cache-first); undefined when none/parse
1590+ * failure. Single read path shared by searchVector / getEmbedding(s).
1591+ * Public contract: returns number[] (callers guard with Array.isArray). */
1592+ function getParsedEmbedding ( id ) {
1593+ const v = readVector ( id ) ;
1594+ return v ? Array . from ( v ) : undefined ;
1595+ }
1596+
1597+ /** Cache instrumentation for the regression lock (hit rate must not collapse
1598+ * back to 0 when the working set outgrows a fixed cap). */
1599+ function embeddingCacheStats ( ) {
1600+ const total = embeddingCacheHits + embeddingCacheMisses ;
1601+ return {
1602+ size : embeddingCache . size ,
1603+ cap : embeddingCacheCap ,
1604+ hits : embeddingCacheHits ,
1605+ misses : embeddingCacheMisses ,
1606+ hitRate : total ? embeddingCacheHits / total : 0
1607+ } ;
1608+ }
1609+
15461610 // all()/list() 的显式列清单:从实际 schema 派生(迁移后),只排除 embedding
15471611 // 列——consolidation/sleep/inject 的消费方都不读向量,而它是全表里最重的一列
15481612 // (5k 行库 ≈ 9.4 MB TEXT),每次全表调用都白搬。经 PRAGMA 派生而非硬编码,
@@ -2413,7 +2477,10 @@ export function createStore(path) {
24132477 * name; omitting modelHash leaves the column untouched (callers that
24142478 * predate the column still work, their rows simply read as unknown). */
24152479 function setEmbedding ( id , vector , modelHash ) {
2416- const json = Array . isArray ( vector ) && vector . length ? JSON . stringify ( vector ) : null ;
2480+ // isVectorLike 而非 Array.isArray:调用方可能递进 Float32Array(本模块缓存的
2481+ // 就是它)。旧守卫对 typed array 返回 false,会把「设置向量」读成「清空向量」,
2482+ // 静默把行改成 NULL。
2483+ const json = isVectorLike ( vector ) && vector . length ? JSON . stringify ( Array . from ( vector ) ) : null ;
24172484 if ( json ) {
24182485 if ( modelHash !== undefined ) {
24192486 db . prepare ( "UPDATE memories SET embedding = ?, embedding_model = ? WHERE id = ?" )
@@ -2426,15 +2493,10 @@ export function createStore(path) {
24262493 }
24272494 // Issue #202:单一写入口即单一失效点——重写缓存条目(向量在手上不必重解析),
24282495 // 清空则移除,删除过的 id 不会被下一次 searchVector 的 id 集合选中。
2429- if ( json ) {
2430- try {
2431- const parsed = JSON . parse ( json ) ;
2432- if ( Array . isArray ( parsed ) && parsed . length ) cacheEmbedding ( id , parsed ) ;
2433- else embeddingCache . delete ( id ) ;
2434- } catch { embeddingCache . delete ( id ) ; }
2435- } else {
2436- embeddingCache . delete ( id ) ;
2437- }
2496+ // 缓存里存 Float32Array(与 readVector 同一表示),不存 JSON.parse 出来的
2497+ // number[],否则写后第一次读还要再转一次。
2498+ if ( json ) cacheEmbedding ( id , new Float32Array ( vector ) ) ;
2499+ else embeddingCache . delete ( id ) ;
24382500 }
24392501
24402502 /** Batch fetch stored embeddings by id (v0.5.0 search-time semantic dedup).
@@ -2595,18 +2657,21 @@ export function createStore(path) {
25952657 */
25962658 function vectorDimensionState ( dimension ) {
25972659 if ( ! Number . isInteger ( dimension ) || dimension <= 0 ) return { state : "invalid" } ;
2598- // 与 searchVector 的 WHERE 谓词逐条相同(顺序不同、语义等价)——同源行集,同步改。
2660+ // 与 searchVector 的行集逐条相同(顺序不同、语义等价)——同源行集,同步改。
2661+ // 同样不带 `embedding != ''`:只取 id,读 embedding 列纯属白搬;空串行由
2662+ // readVector 返回 undefined,落到下面 sawVector 分支(不影响 unreadable 判定)。
25992663 const rows = db . prepare (
26002664 `SELECT id FROM memories
2601- WHERE embedding IS NOT NULL AND embedding != ''
2665+ WHERE embedding IS NOT NULL
26022666 AND forgotten = 0 AND archived = 0`
26032667 ) . all ( ) ;
26042668 if ( ! rows . length ) return { state : "none" } ;
26052669 let sawVector = false ;
2670+ noteSweep ( rows . length , dimension ) ;
26062671 for ( const row of rows ) {
2607- // 走 getParsedEmbedding 的解析缓存 ,不自己 JSON.parse——与 searchVector /
2608- // getEmbedding(s) 同一条读路径,缓存热时零解析。
2609- const v = getParsedEmbedding ( row . id ) ;
2672+ // 走同一解析缓存 ,不自己 JSON.parse——与 searchVector / getEmbedding(s)
2673+ // 同一条读路径,缓存热时零解析。
2674+ const v = readVector ( row . id ) ;
26102675 if ( ! v || ! v . length ) continue ;
26112676 sawVector = true ;
26122677 if ( v . length === dimension ) return { state : "match" } ;
@@ -2640,7 +2705,7 @@ export function createStore(path) {
26402705 // --- vector search ------------------------------------------------------
26412706
26422707 function cosine ( a , b ) {
2643- if ( ! Array . isArray ( a ) || ! Array . isArray ( b ) || a . length !== b . length || ! a . length ) return 0 ;
2708+ if ( ! isVectorLike ( a ) || ! isVectorLike ( b ) || a . length !== b . length || ! a . length ) return 0 ;
26442709 let dot = 0 ;
26452710 let na = 0 ;
26462711 let nb = 0 ;
@@ -2663,13 +2728,22 @@ export function createStore(path) {
26632728 // Issue #202:只取 id 列(~40 KB)而非 SELECT *(~11 MB)——向量从缓存取,
26642729 // 缓存未命中时按 id 点查 embedding 再解析回填。SQL 里保留 embedding 的
26652730 // IS NOT NULL 过滤,保证「有向量的行」集合始终以库为准(删除/清空即时生效)。
2731+ //
2732+ // 为什么不带 `embedding != ''`(2026-11-05 实测):`!= ''` 要读 embedding 列
2733+ // 才能判定,SQLite 就得把 134MB 向量文本整个从磁盘搬一遍——而这里只 SELECT
2734+ // id,一条文本都不用。真库副本实测:这条 SQL 单独跑 265ms → 96ms;落到
2735+ // 一轮完整检索上是 138ms → 47ms(省约 90ms,其余是解析/打分开销)。
2736+ // 空串行(外部直接 UPDATE 造出来的,setEmbedding 写的是 NULL)由 readVector
2737+ // 兜住:JSON.parse('') 抛错 → 返回 undefined → 跳过,既不计分也不崩。
26662738 const rows = db . prepare (
26672739 `SELECT id FROM memories
2668- WHERE ${ archivedFilter } forgotten = 0 AND embedding IS NOT NULL AND embedding != '' `
2740+ WHERE ${ archivedFilter } forgotten = 0 AND embedding IS NOT NULL`
26692741 ) . all ( ) ;
26702742 const scored = [ ] ;
2743+ // 自适应上限:本次要扫这么多行,先让缓存装得下,否则会边扫边驱逐自己。
2744+ noteSweep ( rows . length , vector . length ) ;
26712745 for ( const row of rows ) {
2672- const v = getParsedEmbedding ( row . id ) ;
2746+ const v = readVector ( row . id ) ;
26732747 if ( ! v ) continue ;
26742748 // distill-tx-embed-gap 顺带修:维度不匹配的行按维度分流,直接跳过。旧路径
26752749 // 喂进 cosine 不等长就 return 0,换了模型/维度的旧向量以 0 分混进结果尾部
@@ -5082,6 +5156,7 @@ export function createStore(path) {
50825156 setEmbedding,
50835157 getEmbeddings,
50845158 getParsedEmbedding,
5159+ embeddingCacheStats,
50855160 embeddedCount,
50865161 needsEmbedding,
50875162 needsEmbeddingFor,
0 commit comments