dsh-memu-memory 1.1.2 → 1.1.3

package/lib/memory.js

@@ -6,16 +6,18 @@ import {
   ensureSession, getSessionBinding, memoryDbPath, globalDbPath,
   loadPrivateIndex, savePrivateIndex, loadGlobalIndex, saveGlobalIndex,
   updatePrivateIndex, updateGlobalIndex,
-  newMemoryId, getSettings, getMemoryBackend, getActiveCue, consumeCue,
-  getLibrary, setSessionBinding, effectiveScope, listLibrariesAll,
+  newMemoryId, getSettings, effectiveVectorRoute, getActiveCue, consumeCue,
+  getLibrary, setSessionBinding, setRecallError, effectiveScope, listLibrariesAll,
 } from './state.js'
-import { stamp, redactSecrets, retryStoreWrite } from './paths.js'
+import { stamp, redactSecrets, retryStoreWrite, warn } from './paths.js'
+import { record } from './activity-log.js'
 import { BASE_AROUSAL, moodCongruence, moodDecay } from './mood.js'
 import { commit, retrieve, listFiles, forget } from './memu.js'
 import { bumpStats } from './stats.js'
 import { recallRelations } from './graph.js'
 import { attachmentRefs } from './media.js'
 import { normalizeMemoryContext, contextVisible, sameFactContext } from './context.js'
+import { assertGeneration, assertVectorWriteAllowed, captureGeneration, enrollActiveLibrary, hasActiveVectorGeneration, isVectorStateError, readVectorState, withVectorWrite } from './vector-profile.js'
 
 const HALF_LIFE_DAYS = 14
 // A short-term entry is meant to live for the length of a conversation, not a
@@ -35,6 +37,14 @@ const HABITUATION_FLOOR = 0.5
 // library with three variants of the same decision would spend the whole block on it.
 // The top hit is always kept; later picks pay lambda x max-similarity-to-what-is-in.
 const MMR_LAMBDA = 0.72
+// Semantic fusion uses RRF: each route contributes a
+// rank term and the merged score is normalised to the best fused hit before the
+// existing mood/strength/MMR pipeline sees it. The candidate cap keeps a long
+// library from turning every turn into two full scans.
+const HYBRID_RRF_K = 60
+const HYBRID_CANDIDATE_MIN = 12
+const HYBRID_CANDIDATE_MAX = 40
+const HYBRID_SEMANTIC_TIMEOUT_MS = 15_000
 const LAYERS = ['long_term', 'short_term', 'must_remember']
 // These three are read back by the injector to decide how a memory may be spoken and
 // where it may appear. An unchecked typo would silently mean "no suffix at all", so
@@ -51,6 +61,89 @@ const VISIBILITIES = STORED_VISIBILITIES
 // quote, which systematically inflated confidence in things nobody had said.
 const SOURCES = ['user_said', 'inferred', 'imagined', 'told']
 
+function managedVectorIntent() {
+  if (effectiveVectorRoute() !== 'managed-local') return { managed: false, route: effectiveVectorRoute(), state: null, error: null }
+  try {
+    const state = readVectorState({ tolerateMissing: true }).state
+    return { managed: true, route: 'managed-local', state, error: null }
+  } catch (error) {
+    return { managed: true, route: 'managed-local', state: null, error }
+  }
+}
+
+// 引擎调用用的路由。受管路由被选中但还没有任何代际时，MemU 的 envFor 会直接拒绝
+// managed-local（"managed local vector profile is not active"），写入/删除/列举都会连带
+// 失败。这时引擎这一步按词法处理：索引照常写，等下一次迁移把历史补进向量库。
+// 召回仍按原路由走，好让侧边栏继续显示降级原因，而不是悄悄退回词法。
+function engineRoute() {
+  const route = effectiveVectorRoute()
+  return route === 'managed-local' && !hasActiveVectorGeneration() ? 'lexical' : route
+}
+
+function rememberRecallError(exec, error) {
+  const message = String(error?.message || error)
+  warn('managed vector recall degraded to lexical: ' + message)
+  const sessionId = sessionIdOf(exec)
+  if (sessionId) setRecallError(sessionId, message)
+  return message
+}
+
+function clearRecallError(exec) {
+  const sessionId = sessionIdOf(exec)
+  if (sessionId) setRecallError(sessionId, null)
+}
+
+async function withManagedPrivateWrite(libraryId, action) {
+  const intent = managedVectorIntent()
+  if (!intent.managed) return action()
+  // 选了本地向量、但下载完模型后从没跑过迁移（vector-active 只有 requested）：这里
+  // 没有可对齐的代际，写入必须降级成索引 + 引擎，而不是把整次整理写死。召回侧一直是
+  // 这个口径（local-fallback），写入侧漏了同样的降级 —— 结果就是整理跑完一条没写进来。
+  if (!hasActiveVectorGeneration()) {
+    warn('managed vector write degraded to index+engine: no active vector generation; run the profile switch to enable vectors')
+    record({ kind: 'vector', level: 'warn', libraryId, message: '向量未激活，写入已降级为索引+引擎', detail: { reason: 'no active vector generation' } })
+    return action()
+  }
+  return withVectorWrite(async () => {
+    assertVectorWriteAllowed()
+    enrollActiveLibrary(libraryId)
+    return action()
+  })
+}
+
+async function withManagedGlobalWrite(action) {
+  const intent = managedVectorIntent()
+  if (!intent.managed) return action()
+  if (!hasActiveVectorGeneration()) {
+    warn('managed vector write degraded to index+engine: no active vector generation; run the profile switch to enable vectors')
+    record({ kind: 'vector', level: 'warn', scope: 'global', message: '向量未激活，全局写入已降级为索引+引擎', detail: { reason: 'no active vector generation' } })
+    return action()
+  }
+  return withVectorWrite(() => { assertVectorWriteAllowed(); return action() })
+}
+
+async function managedRecall({ exec, index, query, topK, libraryId, automatic = false, intent, retrieveImpl, byId = false }) {
+  const local = localRecall(index, query)
+  try {
+    if (intent.error) throw intent.error
+    const captured = intent.route === 'managed-local' ? captureGeneration() : null
+    if (byId) return { ...local, recallRoute: 'local' }
+    const db = captured ? (libraryId ? captured.libraries[libraryId] : captured.global) : (libraryId ? memoryDbPath(libraryId) : globalDbPath())
+    if (!db) throw new Error('managed vector generation has no database for library ' + libraryId)
+    const semantic = await retrieveImpl({ query, db, route: intent.route, timeoutMs: HYBRID_SEMANTIC_TIMEOUT_MS })
+    if (semantic?.parseWarning) throw new Error(semantic.parseWarning)
+    if (!Array.isArray(semantic?.files)) throw new Error('managed vector recall returned no file list')
+    if (captured) assertGeneration(captured)
+    const fused = fuseRecallCandidates({ local: local.files, semantic: semantic.files, index,
+      limit: hybridCandidateLimit(topK), automatic, sessionId: memorySessionId(exec), route: 'managed-vector-rrf' })
+    clearRecallError(exec)
+    return { ...semantic, files: fused.files, recallRoute: 'managed-vector-rrf', fusion: fused.debug }
+  } catch (error) {
+    const reason = rememberRecallError(exec, error)
+    return { ...local, recallRoute: 'local-fallback', errors: ['semantic recall failed: ' + reason] }
+  }
+}
+
 function checkEnums({ disclosure, owner, visibility, source }) {
   if (disclosure !== undefined && !DISCLOSURES.includes(disclosure)) {
     throw new Error(`disclosure must be ${DISCLOSURES.join(', ')}`)
@@ -237,6 +330,22 @@ const RELATIVE_DAY_OFFSETS = [
   [/tomorrow/i, 1], [/明天|明日/, 1], [/tonight/i, 0], [/today/i, 0], [/今天|今晚/, 0],
 ]
 
+/**
+ * 从标题/正文里取唯一的显式日期，作为"模型忘了填 salient_date"的兜底。
+ * 只接受全篇唯一的 YYYY-MM-DD；出现多个候选就不猜（宁可为空，也不把日志里的日期
+ * 误装成纪念日）。相对日期不在这里解析，交给 reconcileSalientDate。
+ */
+export function deriveSalientDateFromText(title, content) {
+  const dates = new Set()
+  for (const text of [title, content]) {
+    for (const match of String(text || '').matchAll(/(\d{4})[-/](\d{1,2})[-/](\d{1,2})/g)) {
+      const normalized = normalizeSalientDate(`${match[1]}-${match[2]}-${match[3]}`)
+      if (normalized && isDatedSalientDate(normalized)) dates.add(normalized)
+    }
+  }
+  return dates.size === 1 ? [...dates][0] : null
+}
+
 export function reconcileSalientDate(value, text, now = new Date()) {
   if (!SALIENT_SHORT.test(String(value || ''))) return value
   const body = String(text || '')
@@ -559,6 +668,108 @@ function localRecall(index, query, filter = () => true) {
   }
 }
 
+/** The per-route candidate cap for a requested topK; bounded on both ends. */
+export function hybridCandidateLimit(topK) {
+  const wanted = Math.max(1, Number(topK) || 1)
+  return Math.max(HYBRID_CANDIDATE_MIN, Math.min(HYBRID_CANDIDATE_MAX, wanted * 4))
+}
+
+/**
+ * Reciprocal-rank fusion of lexical index hits and MemU vector hits.
+ *
+ * Filtering happens before the per-route cap and before fusion: a pending review,
+ * an out-of-context entry or an automatic secret must not occupy a candidate slot
+ * and then be dropped later. Ids are canonicalised against the live index so the
+ * two routes cannot return the same memory twice under a prefix or a .md suffix.
+ *
+ * The returned retrievalScore is the normalised RRF share (best fused hit = 1).
+ * recallScore consumes that value instead of recomputing 1/(rank+1), so the
+ * fusion order is not silently overwritten by the old rank decay.
+ */
+export function fuseRecallCandidates({ local = [], semantic = [], index, limit = HYBRID_CANDIDATE_MIN, automatic = false, sessionId = null, now = Date.now(), route = 'vector-rrf' } = {}) {
+  const entries = index?.entries || {}
+  const canonical = (ref) => {
+    const raw = String(ref || '').trim()
+    if (!raw) return null
+    try { return resolveEntryId(index, raw) } catch {
+      const clean = raw.replace(/\.md$/i, '')
+      return entries[clean] ? clean : null
+    }
+  }
+  const eligible = (file, route, rank) => {
+    const id = canonical(file?.name)
+    if (!id) return null
+    const entry = entries[id] || file?.entry || null
+    if (!entry) return null
+    if (!isMemoryEligible(entry, { automatic, now })) return null
+    if (!visibleToSession(entry, sessionId)) return null
+    if (automatic && entry.visibility === 'secret') return null
+    return { id, entry, file, route, rank }
+  }
+  const take = (files, route) => {
+    const picked = []
+    // One route can name the same canonical entry more than once: a caller may
+    // pass both `mem-x` and `mem-x.md`, and an engine can repeat a hit. Dedupe by
+    // canonical id before scoring and truncating, keeping the first (best) rank.
+    // Otherwise every duplicate adds another 1/(k+rank) and consumes a slot.
+    const seen = new Set()
+    for (const file of Array.isArray(files) ? files : []) {
+      const item = eligible(file, route, picked.length + 1)
+      if (!item || seen.has(item.id)) continue
+      seen.add(item.id)
+      picked.push(item)
+      if (picked.length >= limit) break
+    }
+    return picked
+  }
+  const localPicked = take(local, 'local')
+  const semanticPicked = take(semantic, 'semantic')
+  const merged = new Map()
+  const add = (item) => {
+    const current = merged.get(item.id) || { id: item.id, entry: item.entry, file: item.file, rrf: 0, bestRank: Infinity, localRank: null, semanticRank: null, routes: [] }
+    current.rrf += 1 / (HYBRID_RRF_K + item.rank)
+    current.bestRank = Math.min(current.bestRank, item.rank)
+    if (item.route === 'local') current.localRank = item.rank
+    else current.semanticRank = item.rank
+    if (!current.routes.includes(item.route)) current.routes.push(item.route)
+    // Prefer the local object when both routes carry the entry: it already has the
+    // lexical score and the index-backed content used below by enrichFiles.
+    if (item.route === 'local') current.file = item.file
+    merged.set(item.id, current)
+  }
+  for (const item of localPicked) add(item)
+  for (const item of semanticPicked) add(item)
+  const rows = [...merged.values()]
+  const maxRrf = rows.reduce((max, row) => Math.max(max, row.rrf), 0) || 1
+  const files = rows
+    .map((row) => ({
+      ...row.file,
+      name: row.id,
+      entry: row.entry,
+      retrievalScore: row.rrf / maxRrf,
+      fusion: { rrf: row.rrf, bestRank: row.bestRank, localRank: row.localRank, semanticRank: row.semanticRank, routes: row.routes.slice() },
+    }))
+    .sort((a, b) => b.retrievalScore - a.retrievalScore
+      || a.fusion.bestRank - b.fusion.bestRank
+      || a.name.localeCompare(b.name))
+  const localIds = new Set(localPicked.map((item) => item.id))
+  const semanticIds = new Set(semanticPicked.map((item) => item.id))
+  return {
+    files,
+    debug: {
+      route,
+      k: HYBRID_RRF_K,
+      candidateLimit: limit,
+      localCandidates: localPicked.length,
+      semanticCandidates: semanticPicked.length,
+      fused: files.length,
+      localOnly: [...localIds].filter((id) => !semanticIds.has(id)).length,
+      semanticOnly: [...semanticIds].filter((id) => !localIds.has(id)).length,
+      shared: [...localIds].filter((id) => semanticIds.has(id)).length,
+    },
+  }
+}
+
 // Human-like recall ordering. Retrieval answers first (semantic match is still
 // the primary signal, which is why it stays a rank decay), then these biases
 // re-order within that set:
@@ -568,7 +779,10 @@ function localRecall(index, query, filter = () => true) {
 // Every factor is bounded so no bias can outrank a good semantic hit by luck.
 function recallScore(file, rank, context) {
   const entry = file.entry || {}
-  const retrieval = 1 / (rank + 1)
+  // A fused file carries its own normalised RRF share. Falling back to the old
+  // rank decay keeps every lexical caller byte-for-byte compatible.
+  const fused = Number(file.retrievalScore)
+  const retrieval = Number.isFinite(fused) ? Math.max(0, Math.min(1, fused)) : 1 / (rank + 1)
   const strengthTerm = 0.6 + 0.4 * file.strength
   const marginal = entry.marginalized ? 0.35 : 1
 
@@ -738,7 +952,7 @@ function createdAtSpan(files) {
   return { first: stamps[0] || null, last: stamps[stamps.length - 1] || null }
 }
 
-export async function privateRemember({
+async function privateRememberImpl({
   exec, libraryId, content, title, layer, pinReason = null, pinSource = null,
   sideEventId = null, tags = [], openLoop = false, disclosure = 'can_tell',
   owner = 'me', visibility = 'shared', source = 'inferred', confidence = 0.8,
@@ -771,8 +985,14 @@ export async function privateRemember({
   // An unreadable date is refused instead of dropped. Dropping it looked like
   // success to the caller while losing the only part of the memory it asked for:
   // a date that never fires is indistinguishable from no date at all.
-  const normalizedSalientDate = reconcileSalientDate(normalizeSalientDate(salientDate), `${title || ''} ${content || ''}`)
-  if (normalizedSalientDate === null && salientDate !== null && salientDate !== undefined && String(salientDate).trim()) {
+  let normalizedSalientDate = reconcileSalientDate(normalizeSalientDate(salientDate), `${title || ''} ${content || ''}`)
+  // 模型常把日期写进正文却漏填 salient_date（详情页日期栏因此为空）。只有显式传了
+  // 非法值才报错；什么都没传时，从文本取唯一的 YYYY-MM-DD 作为兜底。
+  const explicitDate = salientDate !== null && salientDate !== undefined && String(salientDate).trim()
+  if (normalizedSalientDate === null && !explicitDate) {
+    normalizedSalientDate = deriveSalientDateFromText(title, content)
+  }
+  if (normalizedSalientDate === null && explicitDate) {
     throw new Error('salient_date must be MM-DD (recurs every year) or YYYY-MM-DD (one specific day)')
   }
   content = redactSecrets(content)
@@ -885,9 +1105,24 @@ export async function privateRemember({
   // A held (pending_review) claim stays index-only: committing it to MemU now
   // would make a contested memory retrievable before anyone decided it. Accepting
   // the review later is what commits it (see resolveReview → privateUpdate).
-  const result = getMemoryBackend() === 'api' && !conflict
-    ? await commit({ payload, db: memoryDbPath(scope.libraryId) })
-    : { ok: true, backend: getMemoryBackend(), held: conflict ? true : undefined }
+  const route = engineRoute()
+  const result = (route !== 'lexical') && !conflict
+    ? await commit({ payload, route, db: memoryDbPath(scope.libraryId) })
+    : { ok: true, backend: route, held: conflict ? true : undefined }
+  // 记下"这条进没进向量库"：只有真的带代际提交成功才写，冲突暂扣/降级都不写。
+  // 之前没有任何字段能回答"哪条记忆进向量库了"，只能靠猜。
+  if (route !== 'lexical' && !conflict && result?.ok !== false && !result?.parseWarning) {
+    const active = readVectorState({ tolerateMissing: true }).state?.active
+    if (active) {
+      entry.vector = {
+        route,
+        model: active.profile?.catalogId || null,
+        generation: active.generation,
+        fingerprint: String(active.fingerprint || '').slice(0, 8),
+        at: stamp(),
+      }
+    }
+  }
   // Re-read after the await: a curator job or another turn may have written in
   // the meantime, and saving the pre-await snapshot would erase it.
   await retryStoreWrite(() => updatePrivateIndex(scope.libraryId, (fresh) => {
@@ -918,7 +1153,7 @@ export async function privateRemember({
 // writes the index directly instead of going through privateRemember: the pin cap,
 // the short-term deadline and the "no duplicate text" check would otherwise turn a
 // faithful restore into a pile of downgrades.
-export async function importMemories({ libraryId, memories, maxFiles = 2000, now = Date.now() }) {
+async function importMemoriesImpl({ libraryId, memories, maxFiles = 2000, now = Date.now() }) {
   const library = getLibrary(libraryId)
   if (!library) throw new Error('library not found')
   const list = Array.isArray(memories) ? memories : []
@@ -1048,7 +1283,9 @@ export async function importMemories({ libraryId, memories, maxFiles = 2000, now
   // committed there too or they would only show up in the browser. Best effort: a
   // failed commit must not roll back a restore that already passed validation.
   let engineWarning = null
-  if (getMemoryBackend() === "api") {
+  const route = engineRoute()
+  const managed = route === 'managed-local'
+  if (route !== 'lexical') {
     try {
       await commit({
         payload: {
@@ -1061,9 +1298,10 @@ export async function importMemories({ libraryId, memories, maxFiles = 2000, now
           resource: [],
           user: {},
         },
-        db: memoryDbPath(libraryId),
+        route, db: memoryDbPath(libraryId),
       })
     } catch (error) {
+      if (managed || isVectorStateError(error)) throw error
       engineWarning = String(error?.message || error)
     }
   }
@@ -1078,30 +1316,30 @@ export async function importMemories({ libraryId, memories, maxFiles = 2000, now
   bumpStats(libraryId, 'written', entries.length)
   return { imported: entries.length, ids: entries.map((item) => item.id), idMap, counts, examples, engineWarning }
 }
-export async function privateRecall({ exec, query, topK, relevanceThreshold, purpose = 'explicit' }) {
-  // Reads must not materialize a library; only the explicit new-session choice
-  // (or a user-initiated write) is allowed to create one.
+export async function privateRecall({ exec, query, topK, relevanceThreshold, purpose = 'explicit', retrieveImpl = retrieve }) {
   const binding = peekBinding(exec)
   if (!binding) throw new Error('no bound session')
-  // An opt-out is not a missing binding. Reporting both as "no bound session" sent
-  // the reader looking for a broken session when the conversation simply has no
-  // library to read.
   if (!binding.libraryId) throw new Error('this conversation has no memory library')
   assertScopeEnabled(binding)
   const settings = getSettings()
-  // The caller may hand in its own settings snapshot (injection carries one for the
-  // turn); falling back to the stored defaults keeps tool-initiated reads identical.
   const threshold = relevanceThreshold === undefined ? settings.relevanceThreshold : relevanceThreshold
   let index = loadPrivateIndex(binding.libraryId)
   const byId = /^(?:g?mem)[-_][a-z0-9_-]+(?:\.md)?$/i.test(String(query || '').trim())
-  const result = getMemoryBackend() === 'api' && !byId
-    ? await retrieve({ query, db: memoryDbPath(binding.libraryId) })
-    : localRecall(index, query)
+  const route = effectiveVectorRoute(settings)
+  const wanted = Number(topK || settings.privateTopK || 4)
+  const result = route === 'lexical' || byId
+    ? { ...localRecall(index, query), recallRoute: 'local' }
+    : await managedRecall({ exec, index, query, topK: wanted, libraryId: binding.libraryId, automatic: purpose === 'automatic', intent: managedVectorIntent(), retrieveImpl, byId })
   const current = peekBinding(exec)
   if (!current || current.libraryId !== binding.libraryId) throw new Error('memory scope changed during recall; retry')
   assertScopeEnabled(current)
   index = loadPrivateIndex(binding.libraryId)
   const enriched = enrichFiles(result, index)
+  // enrichFiles rebuilds the result object; carry the route/error metadata across
+  // so buildRecall can report a degraded semantic leg and the tool can warn.
+  if (result?.recallRoute) enriched.recallRoute = result.recallRoute
+  if (result?.errors) enriched.errors = result.errors.slice()
+  if (result?.fusion) enriched.fusion = result.fusion
   const span = createdAtSpan(Object.values(index.entries || {}).map((entry) => ({ entry })))
   const mood = moodDecay(binding.mood)
   const scored = privateWeighted(enriched, Number(topK || settings.privateTopK || 4), {
@@ -1133,15 +1371,24 @@ export async function privateRecall({ exec, query, topK, relevanceThreshold, pur
   return scored
 }
 
-export async function privateList({ exec, libraryId }) {
+export async function privateList({ exec, libraryId, preferIndex = false }) {
   const scope = resolveLibrary({ exec, libraryId, readOnly: true })
   if (scope.binding) assertScopeEnabled(scope.binding)
   const index = loadPrivateIndex(scope.libraryId)
   const allowed = (entry) => !!entry && (!sessionIdOf(exec) || (isMemoryEligible(entry) && visibleToSession(entry, memorySessionId(exec))))
-  if (getMemoryBackend() === 'agent') {
+  // UI 列表直接读索引：索引是权威，引擎只是一面镜子。走引擎意味着起 Python 和
+  // embedding worker（秒级），归档/还原后刷新一下就卡住，这就是 2026-10-30 的现场。
+  const route = preferIndex ? 'lexical' : engineRoute()
+  // 引擎没有可用代际时列表照样能从索引给出答案，但必须说清为什么这里没有向量：
+  // 静默返回"空库"曾被当成"记忆丢了"。
+  const warning = !preferIndex && effectiveVectorRoute() !== 'lexical' && route === 'lexical'
+    ? '本地向量未激活（只有 requested，尚未建成 active 代际）；以下列表来自索引，向量库为空'
+    : null
+  if (route === 'lexical') {
     return {
       libraryId: scope.libraryId,
       source: 'index',
+      warning,
       files: localIndexFiles(index).filter(file => allowed(file.entry)).map((file) => ({
         name: file.name,
         description: file.description,
@@ -1152,11 +1399,12 @@ export async function privateList({ exec, libraryId }) {
       parseWarning: null,
     }
   }
-  const result = await listFiles({ db: memoryDbPath(scope.libraryId) })
+  const result = await listFiles({ route, db: memoryDbPath(scope.libraryId) })
   const files = Array.isArray(result?.recall_files) ? result.recall_files : []
   return {
     libraryId: scope.libraryId,
     source: 'engine',
+    warning: null,
     files: files.filter(file => allowed(index.entries[file.name])).map((file) => ({
       ...file,
       entry: index.entries[file.name] || null,
@@ -1171,7 +1419,7 @@ export async function privateList({ exec, libraryId }) {
 // mood lens and the attachment list all change how an entry is scored, aggregated or
 // rendered, so a wrong value in any of them was a permanent mis-filing that could
 // only be undone by archiving the memory and writing it again.
-export async function privateUpdate({ exec, libraryId, id, content, title, tags, status, openLoop, disclosure, confidence, layer, owner, visibility, source, salientDate, track, peak, moodValence, arousal, attachments, context }) {
+async function privateUpdateImpl({ exec, libraryId, id, content, title, tags, status, openLoop, disclosure, confidence, layer, owner, visibility, source, salientDate, track, peak, moodValence, arousal, attachments, context }) {
   // `source` is editable because it is a claim about provenance, and claims get
   // corrected: a memory the model first filed as `inferred` may turn out to be
   // something the user actually said. Enum-checked like the rest — a typo here
@@ -1205,19 +1453,21 @@ export async function privateUpdate({ exec, libraryId, id, content, title, tags,
     const conflict = findConflict(others, { ...entry, title: title ?? entry.title, content: nextContent })
     if (conflict) throw new Error(`content conflicts with ${conflict.id}; write a new memory for review`)
   }
-  if (nextContent !== undefined) {
+  const route = engineRoute()
+  const managed = route === 'managed-local'
+  if ((nextContent !== undefined || managed) && entry.status !== 'pending_review' && status !== 'pending_review') {
     const payload = {
       recall_files: [{
         name: id_,
         track: entry.track || 'memory',
         description: clampText(title || entry.title || nextContent, 180),
-        content: nextContent,
+        content: nextContent === undefined ? entry.content : nextContent,
       }],
       resource: [],
       user: {},
     }
-    if (getMemoryBackend() === 'api') {
-      await commit({ payload, db: memoryDbPath(scope.libraryId) })
+    if (route !== 'lexical') {
+      await commit({ payload, route, db: memoryDbPath(scope.libraryId) })
     }
   }
   const updated = await retryStoreWrite(() => updatePrivateIndex(scope.libraryId, (fresh) => {
@@ -1307,7 +1557,7 @@ export async function privateUpdate({ exec, libraryId, id, content, title, tags,
 }
 
 /** Review activation and invalidation of the previous claim are one index commit. */
-export async function resolveMemoryReview({ libraryId = null, id, action, resolution = 'replace', reason = '', content, title }) {
+async function resolveMemoryReviewImpl({ libraryId = null, id, action, resolution = 'replace', reason = '', content, title }) {
   if (!['accept', 'reject'].includes(action)) throw new Error('action must be accept or reject')
   if (!['replace', 'coexist'].includes(resolution)) throw new Error('resolution must be replace or coexist')
   if (resolution === 'coexist' && String(reason).trim().length < 8) throw new Error('coexist needs a reason describing the distinct conditions (at least 8 characters)')
@@ -1319,9 +1569,11 @@ export async function resolveMemoryReview({ libraryId = null, id, action, resolu
   if (action === 'accept') {
     if (typeof content === 'string' && content.trim()) next.content = content
     if (typeof title === 'string' && title.trim()) next.title = title
-    if (getMemoryBackend() === 'api') {
+    const reviewRoute = engineRoute()
+    if (reviewRoute !== 'lexical') {
       await commit({
         payload: { recall_files: [{ name: id, track: next.track || 'memory', description: clampText(next.title, 180), content: next.content }], resource: [], user: {} },
+        route: reviewRoute,
         db: libraryId ? memoryDbPath(libraryId) : globalDbPath(),
       })
     }
@@ -1424,7 +1676,7 @@ export function privateArchive({ exec, libraryId, id }) {
  * is still in the index and no longer in the engine — visible in the browser, still
  * deletable, never recalled from a ghost row.
  */
-export async function privateDelete({ exec, libraryId, id }) {
+async function privateDeleteImpl({ exec, libraryId, id }) {
   const scope = resolveLibrary({ exec, libraryId })
   if (scope.binding) assertScopeEnabled(scope.binding)
   const index = loadPrivateIndex(scope.libraryId)
@@ -1435,10 +1687,10 @@ export async function privateDelete({ exec, libraryId, id }) {
   if (!['archived', 'suppressed', 'expired'].includes(entry.status)) {
     throw new Error('only archived memories can be deleted permanently; archive it first')
   }
-  const backend = getMemoryBackend()
+  const backend = engineRoute()
   let engine = null
-  if (backend === 'api') {
-    engine = await forget({ db: memoryDbPath(scope.libraryId), name: id_ })
+  if (backend !== 'lexical') {
+    engine = await forget({ route: backend, db: memoryDbPath(scope.libraryId), name: id_ })
   }
   await retryStoreWrite(() => updatePrivateIndex(scope.libraryId, (fresh) => {
     if (JSON.stringify(fresh.entries[id_]) !== JSON.stringify(entry)) throw new Error('memory changed during deletion; reload and retry')
@@ -1507,6 +1759,78 @@ export function privateUnpin({ exec, id, reason }) {
   return { id: resolvedId, entry: updated.entries[resolvedId], remaining: Math.max(0, budget - used - 1) }
 }
 
+export async function privateRemember(args) {
+  const libraryId = resolveLibrary(args).libraryId
+  const result = await withManagedPrivateWrite(libraryId, () => privateRememberImpl(args))
+  record({
+    kind: 'write',
+    scope: 'private',
+    sessionId: sessionIdOf(args.exec) || null,
+    libraryId,
+    message: '写入 ' + (result?.id || '?') + '：' + clampText(args.title || args.content, 60) + (result?.conflict ? '（待复核）' : ''),
+    detail: { id: result?.id || null, title: args.title || null, layer: args.layer || null, conflict: result?.conflict || null },
+    refs: result?.id ? [result.id] : [],
+  })
+  return result
+}
+
+export async function privateUpdate(args) {
+  const libraryId = resolveLibrary(args).libraryId
+  const result = await withManagedPrivateWrite(libraryId, () => privateUpdateImpl(args))
+  record({
+    kind: 'write',
+    scope: 'private',
+    sessionId: sessionIdOf(args.exec) || null,
+    libraryId,
+    message: '更新 ' + (result?.id || args.id || '?') + (args.content ? '：' + clampText(args.content, 60) : ''),
+    detail: { id: result?.id || args.id || null, fields: Object.keys(args).filter(key => key !== 'exec' && key !== 'id') },
+    refs: result?.id || args.id ? [result?.id || args.id] : [],
+  })
+  return result
+}
+
+export async function privateDelete(args) {
+  const libraryId = resolveLibrary(args).libraryId
+  const result = await withManagedPrivateWrite(libraryId, () => privateDeleteImpl(args))
+  record({
+    kind: 'write',
+    scope: 'private',
+    sessionId: sessionIdOf(args.exec) || null,
+    libraryId,
+    message: '删除 ' + (args.id || '?'),
+    detail: { id: args.id || null, deleted: result?.deleted !== false },
+    refs: args.id ? [args.id] : [],
+  })
+  return result
+}
+
+export async function importMemories(args) {
+  const result = await withManagedPrivateWrite(args.libraryId, () => importMemoriesImpl(args))
+  record({
+    kind: 'write',
+    scope: 'private',
+    libraryId: args.libraryId || null,
+    message: '导入 ' + (result?.imported ?? 0) + ' 条' + (result?.engineWarning ? '（引擎警告：' + clampText(result.engineWarning, 80) + '）' : ''),
+    detail: { imported: result?.imported ?? 0, counts: result?.counts || null, engineWarning: result?.engineWarning || null },
+    refs: Array.isArray(result?.ids) ? result.ids.slice(0, 20) : [],
+  })
+  return result
+}
+
+export async function resolveMemoryReview(args) {
+  const action = () => resolveMemoryReviewImpl(args)
+  const result = args.libraryId ? await withManagedPrivateWrite(args.libraryId, action) : await withManagedGlobalWrite(action)
+  record({
+    kind: 'write',
+    scope: args.libraryId ? 'private' : 'global',
+    libraryId: args.libraryId || null,
+    message: '复核 ' + (args.id || '?') + ' → ' + (args.action || '?'),
+    detail: { id: args.id || null, action: args.action || null, status: result?.status || null },
+    refs: args.id ? [args.id] : [],
+  })
+  return result
+}
+
 export function appliesToDomain(entry, binding) {
   const domain = domainOf(binding)
   if (!entry) return domain === 'general'
@@ -1523,7 +1847,7 @@ export function appliesToDomain(entry, binding) {
   return false
 }
 
-export async function globalRecall({ exec, query, topK, relevanceThreshold }) {
+export async function globalRecall({ exec, query, topK, relevanceThreshold, retrieveImpl = retrieve }) {
   // peek, not ensure: injection has already bound any live session before a tool
   // can run, so a missing binding here means a read from an unbound conversation.
   // That fallback quietly narrows results to the `general` domain, so it is
@@ -1536,8 +1860,12 @@ export async function globalRecall({ exec, query, topK, relevanceThreshold }) {
   const settings = getSettings()
   const threshold = relevanceThreshold === undefined ? settings.relevanceThreshold : relevanceThreshold
   let index = loadGlobalIndex()
-  const result = getMemoryBackend() === 'api'
-    ? await retrieve({ query, db: globalDbPath() })
+  const intent = managedVectorIntent()
+  const domainIndex = { ...index, entries: Object.fromEntries(Object.entries(index.entries || {})
+    .filter(([, entry]) => appliesToDomain(entry, binding))) }
+  const result = effectiveVectorRoute() !== 'lexical'
+    ? await managedRecall({ exec, index: domainIndex, query, topK: topK || settings.globalTopK || 3,
+      libraryId: null, automatic: true, intent, retrieveImpl })
     : localRecall(index, query, (file) => appliesToDomain(file.entry, binding))
   if (peeked) {
     const current = peekBinding(exec)
@@ -1546,6 +1874,9 @@ export async function globalRecall({ exec, query, topK, relevanceThreshold }) {
   }
   index = loadGlobalIndex()
   const enriched = enrichFiles(result, index)
+  if (result?.recallRoute) enriched.recallRoute = result.recallRoute
+  if (result?.errors) enriched.errors = result.errors.slice()
+  if (result?.fusion) enriched.fusion = result.fusion
   const filtered = enriched.files
     .filter((f) => isMemoryEligible(f.entry, { automatic: true }))
     .filter((f) => appliesToDomain(f.entry, binding))
@@ -1554,7 +1885,7 @@ export async function globalRecall({ exec, query, topK, relevanceThreshold }) {
       // Local lexical rank is already meaningful; confidence still nudges ties, and
       // a cross-session fact that has been injected three turns running gets the same
       // wear penalty as a private one.
-      score: (f.lexical > 0 ? f.lexical : 1 / (i + 1))
+      score: (Number.isFinite(f.retrievalScore) ? f.retrievalScore : f.lexical > 0 ? f.lexical : 1 / (i + 1))
         * (0.85 + 0.15 * Number(f.entry.confidence ?? 0.5))
         * habituationFactor(f.entry),
     }))
@@ -1567,7 +1898,7 @@ export async function globalRecall({ exec, query, topK, relevanceThreshold }) {
   }
 }
 
-export async function globalList({ exec, domain }) {
+export async function globalList({ exec, domain, preferIndex = false }) {
   const binding = peekBinding(exec)
   if (binding) assertScopeEnabled(binding, { layer: 'global' })
   const index = loadGlobalIndex()
@@ -1575,11 +1906,19 @@ export async function globalList({ exec, domain }) {
   // "Optional domain filter", so a caller asking for one domain must not get all.
   const domainFilter = (file) => (!domain || (file.entry?.domain || 'unknown') === domain)
     && (!sessionIdOf(exec) || (isMemoryEligible(file.entry) && appliesToDomain(file.entry, binding || { domain: 'general' })))
-  if (getMemoryBackend() === 'agent') {
+  // 与 privateList 同一条口径：受管路由还没有 active 代际时，引擎必然抛
+  // "managed local vector profile is not active"；列表本身其实能答，就按索引答，
+  // 并把原因带上。否则全局记忆页会闪一下红字再消失。
+  const route = preferIndex ? 'lexical' : engineRoute()
+  const warning = !preferIndex && effectiveVectorRoute() !== 'lexical' && route === 'lexical'
+    ? '本地向量未激活（只有 requested，尚未建成 active 代际）；以下列表来自索引，向量库为空'
+    : null
+  if (route === 'lexical') {
     const files = localIndexFiles(index)
     return {
       domain: domain || (binding ? domainOf(binding) : 'general'),
       source: 'index',
+      warning,
       files: (domainFilter ? files.filter(domainFilter) : files).map((file) => ({
         name: file.name,
         description: file.description,
@@ -1590,7 +1929,7 @@ export async function globalList({ exec, domain }) {
       parseWarning: null,
     }
   }
-  const result = await listFiles({ db: globalDbPath() })
+  const result = await listFiles({ route, db: globalDbPath() })
   const files = Array.isArray(result?.recall_files) ? result.recall_files : []
   const enriched = files.map((file) => ({
     ...file,
@@ -1600,6 +1939,7 @@ export async function globalList({ exec, domain }) {
   return {
     domain: domain || (binding ? domainOf(binding) : 'general'),
     source: 'engine',
+    warning: null,
     files: domainFilter ? enriched.filter(domainFilter) : enriched,
     raw: result?.raw,
     parseWarning: result?.parseWarning,