dsh-memu-memory 1.1.2 → 1.2.0

package/lib/state.js

@@ -5,12 +5,21 @@ import {
   dataDir, librariesDir, indexDir, backupsDir,
   ensureDir, readJson, readFailure, readFailuresUnder, writeJson, withFileLock, assertJsonShape, warn, stamp, shortHash, libraryIdForScope, isSafeId,
 } from './paths.js'
+import {
+  activeLeases, createBackup, deleteBackupEntry, listBackupEntries,
+  pruneBackups, restoreFromBackup, withBackupLock,
+} from './backup.js'
 import { migrateIndexVisibility } from './visibility.js'
+import { memuDbFor, memuGlobalDbFor, removeActiveLibrary } from './vector-profile.js'
+import { normalizeEmotion, derivedValence } from './mood.js'
 
 const STATE_FILE = () => path.join(dataDir(), 'state.json')
 const GLOBAL_DB = () => path.join(dataDir(), 'global.sqlite3')
 const GLOBAL_INDEX = () => path.join(indexDir(), 'global.json')
 
+// Observable outcome of the last backup action; see listBackupEntries().
+let lastBackupReport = null
+
 export const DEFAULT_SETTINGS = {
   sidebarSettings: false,
   visionCaptionEnabled: true,
@@ -24,12 +33,17 @@ export const DEFAULT_SETTINGS = {
   // "too little memory", it is noise: a per-turn block sized for paragraph-long
   // prompts drowns the conversation it was meant to help. So the per-turn budgets
   // are small, and the windows that stop repetition are measured in many turns.
-  privateTopK: 3,
-  globalTopK: 2,
-  anchorTokens: 700,
-  // 640 tokens per user turn. A dense chat calls recall on almost every message,
-  // so the injected block has to stay clearly smaller than the message it serves.
-  turnTokens: 640,
+  privateTopK: 5,
+  globalTopK: 5,
+  anchorTokens: 800,
+  // 800 tokens for one recall block. A dense chat calls recall on almost every
+  // message, so the injected block has to stay clearly smaller than the message it
+  // serves. This is the recall budget, not the whole plugin-message ceiling.
+  turnTokens: 800,
+  // Whole plugin-message ceiling: anchor + recall + optional cue/texture. It must
+  // be at least the sum of the sub-budgets the user wants to allow; the default leaves
+  // room for the default anchor and recall blocks.
+  injectionTotalTokens: 2000,
   relevanceThreshold: 0.4,
   // 16 turns is a couple of minutes of group traffic. The old 8 expired inside a
   // single burst, so the same entry came back every minute or two.
@@ -81,6 +95,12 @@ export const DEFAULT_SETTINGS = {
   // "gone", and short enough that a conversation which ended gets tidied in the
   // same sitting instead of waiting for a quiet hour that may never arrive.
   sleepAfterIdleMinutes: 3,
+  // 主动记忆：分数门槛、饥饿阈值（空闲超过它无条件检查）、两种抑制冷却（分钟；整理冷却默认 0，
+  // 薄证据的重复 fork 由评分拦截，只有用户显式配置才启用硬冷却）。
+  activeMemoryMinScore: 0.8,
+  activeMemoryStarvationMinutes: 15,
+  activeMemoryCooldownMinutes: 0,
+  activeMemoryRecallCooldownMinutes: 15,
   autoCurateEveryHours: 0,
   autoCurateSessionLimit: 8,
   // 'local' keeps every memory on this machine; 'cloud' hands MemU's own backend
@@ -90,6 +110,7 @@ export const DEFAULT_SETTINGS = {
   // agent writes and summarizes into the JSON index, with no MemU engine and no
   // embedding API. 'api' hands the work to the configured remote MemU service.
   memoryBackend: 'agent',
+  vectorSource: 'local',
   habitsInjection: true,
   // A positive age marks cleanup candidates; deletion always needs a user action.
   purgeArchivedAfterDays: 0,
@@ -110,10 +131,14 @@ function defaultState() {
 function mergeState(raw) {
   const base = defaultState()
   if (!raw || typeof raw !== 'object') return base
+  const rawSettings = raw.settings && typeof raw.settings === 'object' ? raw.settings : {}
+  const legacyVectorSource = rawSettings.vectorSource === 'api' || rawSettings.vectorSource === 'local'
+    ? rawSettings.vectorSource
+    : (rawSettings.memoryMode === 'cloud' ? 'api' : 'local')
   return {
     ...base,
     ...raw,
-    settings: { ...base.settings, ...(raw.settings || {}) },
+    settings: { ...base.settings, ...rawSettings, vectorSource: legacyVectorSource },
     libraries: raw.libraries && typeof raw.libraries === 'object' ? raw.libraries : {},
     sessions: raw.sessions && typeof raw.sessions === 'object' ? raw.sessions : {},
     workspacePolicies: raw.workspacePolicies && typeof raw.workspacePolicies === 'object' ? raw.workspacePolicies : {},
@@ -306,16 +331,29 @@ export function getMemoryBackend() {
   return loadState().settings?.memoryBackend === 'api' ? 'api' : 'agent'
 }
 
+// Single route authority for automatic memory reads and writes.
+export function effectiveVectorRoute(settings = loadState().settings) {
+  if (settings?.memoryBackend !== 'api') return 'lexical'
+  return settings?.vectorSource === 'api' ? 'remote-api' : 'managed-local'
+}
+
+export function vectorBackendEnabled(settings = loadState().settings) {
+  return effectiveVectorRoute(settings) !== 'lexical'
+}
+
 export function updateSettings(patch) {
   const clean = {}
   const ranges = {
     privateTopK: [1, 20], globalTopK: [1, 20], anchorTokens: [160, 8000], turnTokens: [80, 8000],
+    injectionTotalTokens: [160, 16000],
     relevanceThreshold: [0, 1], dedupeTurns: [0, 200], globalEveryNTurns: [0, 200], minUserChars: [0, 1000],
     mustRememberCap: [1, 100], randomCueChance: [0, 1], shortTermTtlHours: [0, 8760],
     unpinBudgetPerSession: [1, 20], unpinCooldownMinutes: [0, 1440], sleepAfterIdleMinutes: [1, 1440],
     autoCurateEveryHours: [0, 8760], autoCurateSessionLimit: [1, 10], purgeArchivedAfterDays: [0, 36500],
+    activeMemoryMinScore: [0, 10], activeMemoryStarvationMinutes: [1, 1440],
+    activeMemoryCooldownMinutes: [0, 10080], activeMemoryRecallCooldownMinutes: [0, 10080],
   }
-  const enums = { autoInject: ['smart', 'anchor-only', 'per-turn', 'off'], memoryMode: ['local', 'cloud'], memoryBackend: ['agent', 'api'], newSessionDefault: ['off', 'auto', 'global', 'both'] }
+  const enums = { autoInject: ['smart', 'anchor-only', 'per-turn', 'off'], memoryMode: ['local', 'cloud'], memoryBackend: ['agent', 'api'], vectorSource: ['local', 'api'], newSessionDefault: ['off', 'auto', 'global', 'both'] }
   for (const [key, value] of Object.entries(patch || {})) {
     if (!Object.hasOwn(DEFAULT_SETTINGS, key)) continue
     if (enums[key]) {
@@ -512,13 +550,20 @@ export function deleteLibrary(id) {
   const state = loadState()
   if (!state.libraries[id]) return { ok: false, error: 'library not found' }
   if (state.libraries[id].archived !== true) return { ok: false, error: 'archive the library before deleting it' }
+  const activeVectorDb = removeActiveLibrary(id)
+  const legacyVectorDb = path.join(librariesDir(), id + '.sqlite3')
   delete state.libraries[id]
   for (const [sessionId, binding] of Object.entries(state.sessions || {})) {
     if (binding?.libraryId === id) delete state.sessions[sessionId]
   }
   saveState(state)
   const removed = []
-  for (const file of [memoryDbPath(id), ...['json', 'entities.json', 'media.json', 'stats.json'].map(suffix => path.join(indexDir(), `${id}.${suffix}`))]) {
+  const vectorPrefix = id + '.'
+  const vectorGenerationFiles = fs.existsSync(librariesDir())
+    ? fs.readdirSync(librariesDir()).filter(name => name.startsWith(vectorPrefix) && name.endsWith('.sqlite3')).map(name => path.join(librariesDir(), name))
+    : []
+  for (const file of [activeVectorDb, legacyVectorDb, ...vectorGenerationFiles, ...['json', 'entities.json', 'media.json', 'stats.json'].map(suffix => path.join(indexDir(), `${id}.${suffix}`))]) {
+    if (!file) continue
     try {
       if (fs.existsSync(file)) { fs.rmSync(file, { force: true }); removed.push(file) }
     } catch {}
@@ -762,6 +807,8 @@ export function markInjected(sessionId, ids, turn) {
     for (const id of ids || []) at[id] = turn ?? Date.now()
     binding.injectedAt = at
     binding.lastInjectedTurn = turn ?? binding.lastInjectedTurn ?? 0
+    // 主动记忆抑制要一个"最近一次真正注入了记忆"的墙钟时间；turn 号不能跨会话比较。
+    binding.lastInjectedAt = stamp()
     return state
   })
 }
@@ -841,17 +888,16 @@ export function consumeCue(sessionId, cueId) {
   return true
 }
 
-// The session's running mood, kept on the binding rather than in a memory entry:
-// it is a retrieval lens, not a fact about the user, and must never be recalled
-// as a stored memory.
+// The session's running mood is a retrieval lens on the binding, not a fact about
+// the user: it must never be recalled as a stored memory.
 export function setSessionMood(sessionId, mood) {
-  return setSessionBinding(sessionId, {
-    mood: {
-      valence: Math.max(-1, Math.min(1, Number(mood?.valence) || 0)),
-      arousal: Math.max(0, Math.min(1, Number(mood?.arousal) || 0)),
-      at: Date.now(),
-    },
-  })
+  // 给了 emotion 就以四轴为准，valence 只是投影；只有 valence 的旧形状原样存，不反推四轴。
+  const emotion = normalizeEmotion(mood?.emotion ?? null)
+  const bounded = (raw, min, max) => Math.max(min, Math.min(max, Number.isFinite(raw) ? raw : 0)) // 显式 0 是读数的一部分，不能用 `|| 默认值`
+  return setSessionBinding(sessionId, { mood: {
+    valence: emotion ? derivedValence(emotion) : bounded(mood?.valence, -1, 1),
+    emotion, arousal: bounded(mood?.arousal, 0, 1), dominance: bounded(mood?.dominance, -1, 1), at: Date.now(),
+  } })
 }
 
 export function getSessionMood(sessionId) {
@@ -906,12 +952,12 @@ export function markAnniversaryShown(sessionId, memoryId, dayKey) {
 
 export function memoryDbPath(libraryId) {
   ensureDir(librariesDir())
-  return path.join(librariesDir(), `${libraryId}.sqlite3`)
+  return effectiveVectorRoute() === 'managed-local' ? memuDbFor(libraryId) : path.join(librariesDir(), `${libraryId}.sqlite3`)
 }
 
 export function globalDbPath() {
   ensureDir(dataDir())
-  return GLOBAL_DB()
+  return effectiveVectorRoute() === 'managed-local' ? memuGlobalDbFor() : GLOBAL_DB()
 }
 
 // Index files are parsed on every folder in the sidebar, and the parse (full
@@ -1144,175 +1190,94 @@ export function newMemoryId(prefix = 'mem') {
   return `${prefix}-${Date.now().toString(36)}-${crypto.randomBytes(3).toString('hex')}`
 }
 
-export function backupDatabases() {
+/**
+ * Creates a managed backup of the local memory stores (plugin state, indexes,
+ * prompts, attachments, the vector journal and every MemU database), then keeps
+ * the newest BACKUP_KEEP complete ones. Retention, staging, checksums, atomic
+ * publish and the shared lock all live in lib/backup.js so there is exactly one
+ * place that decides what a backup is and which backup may be deleted.
+ *
+ * Returns the published directory: callers (engine switch, library delete,
+ * scripts) treat the return value as a path.
+ */
+export function backupDatabases(options = {}) {
   // Pending bookkeeping changes live in memory for up to 50ms; a backup taken
   // before a flush would silently capture the previous state.
-  flushState()
-  const dest = path.join(backupsDir(), stamp().replace(/[:.]/g, '-'))
-  ensureDir(dest)
-  ensureDir(path.join(dest, 'libraries'))
-  ensureDir(path.join(dest, 'index'))
-  // The prompt manifest copy below silently no-opped without this directory —
-  // an empty catch swallowed the ENOENT and backups shipped without it.
-  ensureDir(path.join(dest, 'prompts'))
-  const copy = (from, to) => {
-    let info
-    try { info = fs.lstatSync(from) } catch (error) { if (error.code === 'ENOENT') return; throw error }
-    if (!info.isFile()) throw new Error(`backup refuses non-file: ${path.basename(from)}`)
-    fs.copyFileSync(from, to)
-  }
-  copy(STATE_FILE(), path.join(dest, 'state.json'))
-  copy(GLOBAL_DB(), path.join(dest, 'global.sqlite3'))
-  copy(GLOBAL_INDEX(), path.join(dest, 'index', 'global.json'))
-  copy(path.join(dataDir(), 'prompts', 'manifest.json'), path.join(dest, 'prompts', 'manifest.json'))
-  try {
-    for (const name of fs.readdirSync(librariesDir())) {
-      if (name.endsWith('.sqlite3') || name.endsWith('.sqlite3-wal') || name.endsWith('.sqlite3-shm')) {
-        copy(path.join(librariesDir(), name), path.join(dest, 'libraries', name))
-      }
-    }
-  } catch (error) { if (error.code !== 'ENOENT') throw error }
+  let report
   try {
-    for (const name of fs.readdirSync(indexDir())) {
-      if (name.endsWith('.json')) copy(path.join(indexDir(), name), path.join(dest, 'index', name))
-    }
-  } catch (error) { if (error.code !== 'ENOENT') throw error }
-  const copyTree = (source, target) => {
-    let names
-    try { names = fs.readdirSync(source, { withFileTypes: true }) } catch (error) { if (error.code === 'ENOENT') return; throw error }
-    ensureDir(target)
-    for (const item of names) {
-      if (item.isSymbolicLink()) throw new Error('backup refuses symbolic links')
-      if (item.isDirectory()) copyTree(path.join(source, item.name), path.join(target, item.name))
-      else copy(path.join(source, item.name), path.join(target, item.name))
-    }
-  }
-  copyTree(path.join(dataDir(), 'attachments'), path.join(dest, 'attachments'))
-  copyTree(path.join(dataDir(), 'prompts'), path.join(dest, 'prompts'))
-
-  // A backup whose integrity nobody can check is only a hope. Hash every file so
-  // a restore can refuse a truncated or half-written copy.
-  const files = {}
-  const walk = (dir, prefix = '') => {
-    let names = []
-    try { names = fs.readdirSync(dir) } catch { return }
-    for (const name of names) {
-      const full = path.join(dir, name)
-      let stat = null
-      try { stat = fs.statSync(full) } catch { continue }
-      if (stat.isDirectory()) { walk(full, `${prefix}${name}/`); continue }
-      let sha256 = null
-      try { sha256 = crypto.createHash('sha256').update(fs.readFileSync(full)).digest('hex') } catch {}
-      files[`${prefix}${name}`] = { bytes: stat.size, sha256 }
+    report = createBackup({ ...options, flushState })
+  } catch (error) {
+    // A refusal is the safety property working, not something to swallow: a
+    // database the engine could not snapshot aborts the backup, and the reason
+    // has to stay visible on the same channel the panel already reads.
+    lastBackupReport = {
+      at: stamp(),
+      action: 'create',
+      status: 'failed',
+      code: error?.code || null,
+      error: String(error?.message || error),
+      name: null,
+      dir: null,
+      files: 0,
+      bytes: 0,
+      snapshots: [],
+      pruned: [],
+      pruneFailed: [],
+      pendingCleanup: 0,
+      notice: null,
     }
+    throw error
   }
-  walk(dest)
-  const current = engineCurrentSafe()
-  writeJson(path.join(dest, 'manifest.json'), {
-    version: 1,
-    createdAt: stamp(),
-    engine: current ? { version: current.version, schemaVersion: current.schemaVersion || null } : null,
-    files,
-  })
-  return dest
+  lastBackupReport = { at: stamp(), action: 'create', ...report }
+  return report.dir
 }
 
-function engineCurrentSafe() {
-  try {
-    return JSON.parse(fs.readFileSync(path.join(dataDir(), 'engine', 'current.json'), 'utf8'))
-  } catch {
-    return null
-  }
+/** What the last backup/restore/prune did, so the outcome stays observable. */
+export function lastBackupReportView() {
+  return lastBackupReport ? { ...lastBackupReport } : null
 }
 
+/** Newest first, including entries that failed to complete (reported, never deleted). */
 export function listBackups() {
-  let names = []
-  try { names = fs.readdirSync(backupsDir()) } catch { return [] }
-  return names
-    .map((name) => {
-      const dir = path.join(backupsDir(), name)
-      let stat = null
-      try { stat = fs.statSync(dir) } catch { return null }
-      if (!stat.isDirectory()) return null
-      const manifest = readJson(path.join(dir, 'manifest.json'), null)
-      const fileCount = manifest?.files ? Object.keys(manifest.files).length : null
-      const bytes = manifest?.files
-        ? Object.values(manifest.files).reduce((sum, f) => sum + Number(f.bytes || 0), 0)
-        : null
-      return {
-        name,
-        dir,
-        createdAt: manifest?.createdAt || stat.mtime.toISOString(),
-        engine: manifest?.engine || null,
-        files: fileCount,
-        bytes,
-        hasManifest: Boolean(manifest),
-      }
-    })
-    .filter(Boolean)
-    .sort((a, b) => String(b.name).localeCompare(String(a.name)))
+  return listBackupEntries()
 }
 
 /** Removes one backup directory. The name is validated, never used as a path. */
 export function deleteBackup(name) {
-  if (!isSafeId(name)) throw new Error('invalid backup name')
-  const dir = path.join(backupsDir(), name)
-  if (!fs.existsSync(dir)) throw new Error(`backup not found: ${name}`)
-  fs.rmSync(dir, { recursive: true, force: true })
-  return { deleted: name }
+  const result = deleteBackupEntry(name)
+  lastBackupReport = { at: stamp(), action: 'delete', ...result }
+  return { deleted: result.deleted, status: result.status }
 }
 
 /**
- * Puts a backup back. The current state is backed up first, so a restore is
- * itself reversible. Nothing is written until the target verifies, and the
- * in-memory caches are dropped so the next read sees the restored files.
+ * Applies the retention rule on demand. Creation already prunes, so this exists
+ * for the paths that must reclaim the space a protected restore target kept
+ * alive, and for callers that want the report without making a backup.
  */
-export function restoreBackup(name, { beforeRestore = null } = {}) {
-  if (!isSafeId(name)) throw new Error('invalid backup name')
-  const dir = path.join(backupsDir(), name)
-  if (!fs.existsSync(dir)) throw new Error(`backup not found: ${name}`)
-  const manifest = readJson(path.join(dir, 'manifest.json'), null)
-  if (manifest?.files) {
-    for (const [rel, info] of Object.entries(manifest.files)) {
-      const full = path.join(dir, rel)
-      if (!full.startsWith(path.resolve(dir) + path.sep) || path.isAbsolute(rel) || rel.split(/[\\/]/).includes('..')) throw new Error('invalid backup manifest path')
-      if (!fs.existsSync(full)) throw new Error(`backup is incomplete: ${rel} is missing`)
-      if (info.sha256) {
-        const actual = crypto.createHash('sha256').update(fs.readFileSync(full)).digest('hex')
-        if (actual !== info.sha256) throw new Error(`backup is corrupt: ${rel} failed its checksum`)
-      }
-    }
-  }
-  const safety = typeof beforeRestore === 'function' ? beforeRestore() : backupDatabases()
-  const copy = (from, to) => {
-    if (!fs.existsSync(from)) return
-    ensureDir(path.dirname(to))
-    fs.copyFileSync(from, to)
-  }
-  copy(path.join(dir, 'state.json'), STATE_FILE())
-  copy(path.join(dir, 'global.sqlite3'), GLOBAL_DB())
-  copy(path.join(dir, 'index', 'global.json'), GLOBAL_INDEX())
-  copy(path.join(dir, 'prompts', 'manifest.json'), path.join(dataDir(), 'prompts', 'manifest.json'))
-  for (const [sub, target] of [['index', indexDir()], ['libraries', librariesDir()]]) {
-    let names = []
-    try { names = fs.readdirSync(path.join(dir, sub)) } catch { continue }
-    for (const file of names) copy(path.join(dir, sub, file), path.join(target, file))
-  }
-  const restoreTree = (from, target) => {
-    let items
-    try { items = fs.readdirSync(from, { withFileTypes: true }) } catch (error) { if (error.code === 'ENOENT') return; throw error }
-    for (const item of items) {
-      if (item.isSymbolicLink()) throw new Error('restore refuses symbolic links')
-      if (item.isDirectory()) restoreTree(path.join(from, item.name), path.join(target, item.name))
-      else copy(path.join(from, item.name), path.join(target, item.name))
-    }
-  }
-  restoreTree(path.join(dir, 'attachments'), path.join(dataDir(), 'attachments'))
-  restoreTree(path.join(dir, 'prompts'), path.join(dataDir(), 'prompts'))
-  // The restored files are the truth now; anything cached describes the state
-  // that was just replaced.
-  clearCaches()
-  return { restored: name, safety }
+export function pruneOldBackups(options = {}) {
+  const result = pruneBackups(options)
+  lastBackupReport = { at: stamp(), action: 'prune', ...result }
+  return result
+}
+
+/** Names of backups that a running restore or migration is reading right now. */
+export function leasedBackups() {
+  return Object.keys(activeLeases())
+}
+
+/**
+ * Puts a backup back. The target is leased and its whole inventory is verified
+ * before anything is written; the live root is saved as a safety backup next;
+ * only then are files replaced. Failure leaves a recovery path: the safety
+ * backup holds the state that was replaced and retention may not delete it.
+ * A backup that predates the vector journal also retires the stale live
+ * vector-active pointer, so recall falls back to text instead of querying
+ * databases that no longer match the restored index.
+ */
+export function restoreBackup(name, { beforeRestore = null, keep = undefined } = {}) {
+  const result = restoreFromBackup(name, { beforeRestore, flushState, clearCaches, keep })
+  lastBackupReport = { at: stamp(), action: 'restore', ...result }
+  return result
 }
 
 /** Drops the in-memory mirrors so the next read comes from disk. */

package/lib/tools.js

@@ -80,6 +80,28 @@ function salientTag(entry) {
   return isDatedSalientDate(entry.salientDate) ? `date=${entry.salientDate}` : `anniversary=${entry.salientDate}`
 }
 
+// 四轴名在展示层就地映射：这是给人读的一行摘要，不是本地化词条。
+const EMOTION_LABELS = { joy: '喜', anger: '怒', sorrow: '哀', fear: '惧' }
+const EMOTION_AXES_IN_ORDER = ['joy', 'anger', 'sorrow', 'fear']
+
+// 只留够显眼的份额，最多两项：四项全列会把一行标签读成噪声。
+function emotionBrief(entry) {
+  const emotion = entry.emotion
+  if (!emotion || typeof emotion !== 'object') return ''
+  const shares = EMOTION_AXES_IN_ORDER
+    .map((axis) => ({ axis, share: Number(emotion[axis]) || 0 }))
+    .filter((item) => item.share >= 0.05)
+    .sort((a, b) => b.share - a.share)
+    .slice(0, 2)
+  if (!shares.length) return ''
+  const parts = shares.map((item) => `${EMOTION_LABELS[item.axis]}${item.share.toFixed(2)}`)
+  const dominance = Number(entry.dominance)
+  if (Number.isFinite(dominance)) parts.push(`dom${dominance >= 0 ? '+' : ''}${dominance.toFixed(2)}`)
+  const arousal = Number(entry.arousal)
+  if (Number.isFinite(arousal)) parts.push(`a${arousal.toFixed(2)}`)
+  return parts.join(' · ')
+}
+
 function formatPrivateItem(item, index, options = {}) {
   const entry = item.entry || {}
   const lines = [
@@ -107,7 +129,10 @@ function formatPrivateItem(item, index, options = {}) {
   // way made "the test is tomorrow" read like a recurring commemorative date.
   const tag = salientTag(entry)
   if (tag) lines.push(`   ${tag}`)
-  if (typeof entry.moodValence === 'number' && entry.moodValence !== 0) lines.push(`   mood=${entry.moodValence.toFixed(2)}`)
+  // 有构成就讲构成：同一个 valence 可能来自怒，也可能来自哀，一个数字分不出来。
+  const brief = emotionBrief(entry)
+  if (brief) lines.push(`   emo=${brief}`)
+  else if (typeof entry.moodValence === 'number' && entry.moodValence !== 0) lines.push(`   mood=${entry.moodValence.toFixed(2)}`)
   if (item.content) {
     const body = options.query
       ? centeredSnippet(item.content, options.query)
@@ -187,10 +212,18 @@ export function registerTools(ctx) {
         description: 'Where this came from: inferred (default — you concluded it), user_said (only when the words are actually theirs and quotable), imagined, or told.',
       },
       confidence: { type: 'number', description: '0-1 confidence in this memory. Below 0.45 it is injected as a hedge, so use it honestly.' },
-      mood_valence: { type: 'number', description: 'How this moment felt, -1 (bad) to 1 (good). Omit to inherit the current conversation mood.' },
+      mood_valence: { type: 'number', description: '派生值：给了 emotion 时由四项算出，-1（坏）到 1（好）。省略则沿用当前会话读数。' },
       arousal: { type: 'number', description: 'How strongly it hit, 0-1.' },
+      emotion: {
+        type: 'object',
+        properties: { joy: { type: 'number' }, anger: { type: 'number' }, sorrow: { type: 'number' }, fear: { type: 'number' } },
+        // 四个轴是封闭集合：多写的键只会被误当成第五种情绪。
+        additionalProperties: false,
+        description: '情绪构成：喜悦/愤怒/哀伤/恐惧，四项自动归一化到和为 1。填记忆所述那件事的情绪，不是此刻整理时的心情。省略=继承当前会话读数；显式全零=明确中性；工程事实请用中性，不要因为 bug 难修或结论重要就填负面情绪。',
+      },
+      dominance: { type: 'number', description: '谁在掌控：-1 完全失控 … +1 完全掌控。省略=继承当前会话。' },
       peak: { type: 'boolean', description: 'A high point or low point of the arc — peaks and endings stay easier to recall.' },
-      salient_date: { type: 'string', description: 'MM-DD for something that comes back every year (a birthday, an anniversary of an event); it resurfaces on that day each year. YYYY-MM-DD for a one-off dated commitment or appointment: it is raised the day before and on the day itself, and never again after it has passed. Use the annual form only when the day really does recur. A relative day (今天/明天/后天/today/tomorrow) must be resolved to the absolute date it points at: sending a bare MM-DD turns one appointment into a yearly reminder.' },
+      salient_date: { type: 'string', description: 'MM-DD for something that comes back every year (a birthday, an anniversary of an event); it resurfaces on that day each year. YYYY-MM-DD for a one-off dated commitment or appointment: it is raised the day before and on the day itself, and never again after it has passed. Use the annual form only when the day really does recur. A relative day (今天/明天/后天/today/tomorrow) must be resolved to the absolute date it points at: sending a bare MM-DD turns one appointment into a yearly reminder. If the content itself names a date, pass it here too: when this field is empty the plugin only falls back to a single unambiguous YYYY-MM-DD found in the text.' },
       track: { type: 'string', description: 'memory (default) or habit for an aggregated expression/sticker habit; do not write one habit per occurrence.' },
       attachments: { type: 'array', items: { type: 'object', properties: { sha256: { type: 'string', required: true } }, additionalProperties: true }, description: 'At most 8 sha256 references received in this conversation. Never supply paths or bytes. Ordinary image memories default to short_term if layer is omitted; choose long_term explicitly only when important.' },
       context: { type: 'object', properties: {
@@ -219,6 +252,11 @@ export function registerTools(ctx) {
         confidence: args.confidence,
         moodValence: args.mood_valence ?? null,
         arousal: args.arousal ?? null,
+        // `undefined` means "the model said nothing" and is allowed to inherit the
+        // turn's mood; `null` means "explicitly neutral" and must survive as such. Using
+        // `?? null` here would erase that difference and re-inherit on a neutral call.
+        emotion: args.emotion,
+        dominance: args.dominance ?? null,
         peak: args.peak === true,
         salientDate: args.salient_date ?? null,
       })
@@ -252,11 +290,14 @@ export function registerTools(ctx) {
     },
     async (args, exec) => {
       const result = await privateRecall({ exec, query: args.query, topK: args.topK })
+      // Surface a degraded semantic leg on the explicit tool path too; silently
+      // returning fewer hits would make a failed backend look like an empty library.
+      const warning = (result.errors || []).length ? `\n注意：本次召回已降级：${(result.errors || []).join('; ')}` : ''
       // Read-only: never materialize a binding/library from a recall header.
       const binding = peekBinding(exec)
       const header = `私有记忆（library=${binding?.libraryId || '?'}, domain=${domainOf(binding)}）`
-      if (!result.files?.length) return `${header}\n没有命中。`
-      return [header, ...result.files.map((f, i) => formatPrivateItem(f, i + 1, { query: args.query }))].join('\n\n')
+      if (!result.files?.length) return `${header}\n没有命中。${warning}`
+      return [header, ...result.files.map((f, i) => formatPrivateItem(f, i + 1, { query: args.query }))].join('\n\n') + warning
     },
     { isConcurrencySafe: () => true },
   ))
@@ -270,14 +311,15 @@ export function registerTools(ctx) {
       // instead of ensureSession() silently creating a placeholder library.
       if (!peekBinding(exec)?.libraryId) return '当前对话没有绑定记忆库。'
       const result = await privateList({ exec })
-      if (!result.files?.length) return `私有记忆库 ${result.libraryId} 为空。`
+      const warning = result.warning ? `\n注意：${result.warning}` : ''
+      if (!result.files?.length) return `私有记忆库 ${result.libraryId} 为空。${warning}`
       const lines = [`私有记忆库 ${result.libraryId}（${result.files.length} 条）`]
       for (const file of result.files) {
         const e = file.entry || {}
         const tag = salientTag(e)
         lines.push(`- [${file.name}] ${e.title || file.description || '(untitled)'} · ${e.layer || 'long_term'} · ${e.status || 'active'}${e.marginalized ? ' · marginalized' : ''}${tag ? ` · ${tag}` : ''}`)
       }
-      return lines.join('\n')
+      return lines.join('\n') + warning
     },
     { isConcurrencySafe: () => true },
   ))
@@ -305,6 +347,13 @@ export function registerTools(ctx) {
       peak: { type: 'boolean', description: 'Flashbulb flag: the moment was charged. Changing it recomputes accuracy.' },
       mood_valence: { type: 'number', description: 'How the moment felt, -1..1. Used as a retrieval lens; omitted keeps the stored value.' },
       arousal: { type: 'number', description: 'How charged the moment was, 0..1. Used as a retrieval lens; omitted keeps the stored value.' },
+      emotion: {
+        type: 'object',
+        properties: { joy: { type: 'number' }, anger: { type: 'number' }, sorrow: { type: 'number' }, fear: { type: 'number' } },
+        additionalProperties: false,
+        description: '情绪构成，三项语义不同：省略=保留原值；显式 null=清除 emotion，来源变 unknown；显式对象=校验并归一化后整份替换。改的是那条记忆所述事件的感受，不是此刻的心情。',
+      },
+      dominance: { type: 'number', description: '谁在掌控：-1 完全失控 … +1 完全掌控。省略=保留原值。' },
       salient_date: { type: 'string', description: 'Re-date the memory: MM-DD for an annual anniversary, YYYY-MM-DD for a one-off dated commitment, or an empty string to remove the date. Use this to repair a date that was stored without its year.' },
     },
     async (args, exec) => {
@@ -314,6 +363,8 @@ export function registerTools(ctx) {
         layer: args.layer, owner: args.owner, visibility: args.visibility,
         source: args.source, track: args.track, peak: args.peak,
         moodValence: args.mood_valence, arousal: args.arousal,
+        // undefined 就是"省略"，必须原样传下去；换成 null 会把保留变成清除。
+        emotion: args.emotion, dominance: args.dominance,
         // Sentinel: absent means "leave the date as it is", '' means "clear it".
         salientDate: args.salient_date,
       })