dsh-memu-memory 1.1.1 → 1.1.3

package/lib/engine.js

@@ -5,7 +5,7 @@ import path from 'node:path'
 import { spawn } from 'node:child_process'
 import { fileURLToPath } from 'node:url'
 import {
-  dataDir, engineDir, downloadsDir, logsDir, librariesDir, ensureDir, readJson, writeJson, stamp,
+  dataDir, engineDir, downloadsDir, logsDir, librariesDir, ensureDir, readJson, writeJson, stamp, windowsSystemEnv,
 } from './paths.js'
 import { getSettings, globalDbPath } from './state.js'
 import { ensureManagedPython } from './managed-runtime.js'
@@ -158,7 +158,7 @@ function run(cmd, args, opts = {}) {
   return new Promise((resolve) => {
     const child = spawn(cmd, args, {
       cwd: opts.cwd,
-      env: { ...process.env, ...(opts.env || {}) },
+      env: { ...windowsSystemEnv(), ...process.env, ...(opts.env || {}) },
       windowsHide: true,
       stdio: ['ignore', 'pipe', 'pipe'],
     })

package/lib/index.js

@@ -1,10 +1,14 @@
 import { registerTools } from './tools.js'
 import { registerInjection } from './inject.js'
+import { registerPresetAttachment } from './preset-scope.js'
 import { registerRpc } from './rpc.js'
 import { registerCycle } from './cycle.js'
 import { syncPromptDefaults } from './prompts.js'
 import { ensureEngine, engineStatus, ENGINE_VERSION } from './engine.js'
 import { getSettings, getMemoryBackend, backupDatabases, flushState } from './state.js'
+import { closeEmbeddingWorkers } from './local-embedding-manager.js'
+import { bootstrapLocalVector } from './local-vector-service.js'
+import { vectorStatus } from './vector-profile.js'
 import { setWarnSink } from './paths.js'
 
 export const name = 'dsh-memu-memory'
@@ -14,6 +18,29 @@ export const inject = ['tools', 'timer']
 
 const applied = new WeakSet()
 
+// 首用引导（§14.13）：本地向量模式且已有（或待切换）受管模型时，启动后把受管运行时复用起来、
+// 拉起 loopback worker 并健康检查 /v1/embeddings。这里不下载：没有确认的联网动作留给她在
+// 设置页点按钮，启动路径只做 reuse + 健康检查。失败只 warn（召回照旧退词法）。
+function startLocalVectorBootstrap(ctx) {
+  try {
+    if (getMemoryBackend() !== 'api') return
+    if (getSettings().vectorSource !== 'local') return
+    const state = vectorStatus()
+    const catalogId = state?.active?.profile?.catalogId || state?.requested?.catalogId || null
+    if (!catalogId) return
+    const timer = setTimeout(() => {
+      void bootstrapLocalVector({ confirmed: false }).then((ready) => {
+        try { ctx.logger?.info?.(`dsh-memu-memory: managed local embedding runtime ready (${String(ready?.model || catalogId)} ${Number(ready?.dimension) || '?'}d)`) } catch {}
+      }).catch((error) => {
+        try { ctx.logger?.warn?.(`dsh-memu-memory: local embedding bootstrap skipped: ${error?.message || error}`) } catch {}
+      })
+    }, 2500)
+    timer.unref?.()
+  } catch (error) {
+    try { ctx.logger?.warn?.(`dsh-memu-memory: local embedding bootstrap skipped: ${error?.message || error}`) } catch {}
+  }
+}
+
 function startEngineBootstrap(ctx) {
   try {
     const settings = getSettings()
@@ -36,6 +63,17 @@ function startEngineBootstrap(ctx) {
 }
 
 export function apply(ctx, config) {
+  // A conversation that names an agent preset composes its model-facing plugin set from
+  // that preset's cordis.yml alone, and that subtree never delivers `agent/pre-step` to
+  // this instance — so nothing here runs for those conversations. `lib/preset-scope.js`
+  // walks the live agent registry and attaches the injection listener on each such
+  // agent's own context instead. No preset file is touched.
+  //
+  // `config.preset === true` remains for the opposite case: a user who *does* list this
+  // plugin inside a preset gets a second instance in the same process, and that instance
+  // must not re-register the process-global surfaces (RPC prefix, idle sweep, engine
+  // installer). The tools and the pre-step hook are what such a mount needs.
+  const inPreset = config?.preset === true
   if (applied.has(ctx)) {
     try { ctx.logger?.warn?.('dsh-memu-memory: apply() already ran on this context; skipping') } catch {}
     return
@@ -72,13 +110,32 @@ export function apply(ctx, config) {
     ctx.effect(() => disposeInjection, 'dsh-memu-memory: injection')
   }
 
-  registerRpc(ctx)
-  startEngineBootstrap(ctx)
-
-  const disposeCycle = registerCycle(ctx, {
+  const disposeAttach = registerPresetAttachment(ctx, {
     log: (message) => { try { ctx.logger?.warn?.(`dsh-memu-memory: ${message}`) } catch {} },
   })
   if (typeof ctx.effect === 'function') {
+    ctx.effect(() => disposeAttach, 'dsh-memu-memory: preset attachment')
+  }
+
+  if (!inPreset) {
+    registerRpc(ctx)
+    startEngineBootstrap(ctx)
+    startLocalVectorBootstrap(ctx)
+  }
+
+  // The embedding worker is a process-global singleton, so it outlives any single
+  // acquire() and would keep a native session and a loopback port alive after this
+  // instance is unloaded. Preset mounts share that same worker, so only the instance
+  // that owns the process-global surfaces may close it. Recall degrades to lexical
+  // afterwards instead of failing.
+  if (!inPreset && typeof ctx.effect === 'function') {
+    ctx.effect(() => () => { closeEmbeddingWorkers() }, 'dsh-memu-memory: embedding workers')
+  }
+
+  const disposeCycle = inPreset ? null : registerCycle(ctx, {
+    log: (message) => { try { ctx.logger?.warn?.(`dsh-memu-memory: ${message}`) } catch {} },
+  })
+  if (disposeCycle && typeof ctx.effect === 'function') {
     ctx.effect(() => disposeCycle, 'dsh-memu-memory: cycle')
   }
 

package/lib/inject.js

@@ -9,9 +9,10 @@ import {
 import {
   decayStrength, privateRecall, globalRecall, appliesToDomain, domainOf,
   relativeTime, daysSince, dueOpenLoops, noteInjected, noteGlobalInjected, visibleToSession,
-  cueCandidates, isTipOfTongue, isMemoryEligible,
+  cueCandidates, isTipOfTongue, isMemoryEligible, sessionIdOf,
   salientDateFires, isDatedSalientDate, salientDaysAhead,
 } from './memory.js'
+import { record, clipQuery } from './activity-log.js'
 import { readMood } from './mood.js'
 import { loadPromptForDomain } from './prompts.js'
 import { estTokens, packToBudget, truncateToTokens } from './budget.js'
@@ -605,6 +606,31 @@ export async function buildRecall(binding, query, turn, settings = getSettings()
   const pieces = []
   const errors = []
   let candidateCount = 0
+  let privateRoute = null
+  let globalRoute = null
+  // 每个回合都留一条召回记录：走了哪条路、召回/注入的是什么 id、哪些腿降级了。
+  // 这是"为什么这台机器上的召回从来不出来"唯一能在 UI 里自查的证据。
+  const finish = (payload) => {
+    record({
+      kind: 'recall',
+      scope: null,
+      sessionId: sessionId || sessionIdOf(exec) || null,
+      libraryId: binding.libraryId || null,
+      ok: (payload.errors || []).length === 0,
+      message: `召回 ${payload.ids.length} 条注入 / ${candidateCount} 候选` + ((payload.errors || []).length ? ` · ${payload.errors.length} 个错误` : ''),
+      detail: {
+        query: clipQuery(query),
+        turn,
+        privateRoute,
+        globalRoute,
+        ids: payload.ids,
+        candidateCount,
+        errors: payload.errors || [],
+      },
+      refs: payload.ids,
+    })
+    return payload
+  }
 
   // Compare against the history first, then record this message into it.
   const switched = topicShifted(binding, query, settings)
@@ -618,7 +644,12 @@ export async function buildRecall(binding, query, turn, settings = getSettings()
       // The turn's settings snapshot decides the cutoff, so a caller that runs with
       // different settings (tests, per-turn overrides) sees matching behaviour.
       const result = await privateRecall({ exec, query, topK: settings.privateTopK, relevanceThreshold: settings.relevanceThreshold, purpose: 'automatic' })
+      // A degraded hybrid recall is not a failed turn: the lexical leg still
+      // answered. The error must still reach lastRecallError so the next healthy
+      // recall clears it instead of the degradation disappearing.
+      for (const warning of result.errors || []) errors.push(warning)
       candidateCount += result.files?.length || 0
+      privateRoute = result.recallRoute || null
       const fresh = (result.files || [])
         .filter((f) => !seenRecently(binding, f.name, turn, settings.dedupeTurns))
       if (fresh.length > 0) {
@@ -645,6 +676,7 @@ export async function buildRecall(binding, query, turn, settings = getSettings()
     try {
       const result = await globalRecall({ exec, query, topK: settings.globalTopK, relevanceThreshold: settings.relevanceThreshold })
       candidateCount += result.files?.length || 0
+      globalRoute = result.recallRoute || null
       if (result.unbound) errors.push('global recall ran without a session binding; results are limited to the general domain')
       const fresh = (result.files || [])
         .filter((f) => !seenRecently(binding, f.name, turn, settings.dedupeTurns))
@@ -656,7 +688,7 @@ export async function buildRecall(binding, query, turn, settings = getSettings()
     }
   }
 
-  if (pieces.length === 0) return { text: '', ids: [], errors, outcome: errors.length ? 'error' : candidateCount ? 'deduped' : 'no-match', candidateCount }
+  if (pieces.length === 0) return finish({ text: '', ids: [], errors, outcome: errors.length ? 'error' : candidateCount ? 'deduped' : 'no-match', candidateCount })
   const budget = Math.max(0, Number(settings.turnTokens ?? 640))
   const blocks = []
   for (const piece of pieces) {
@@ -681,7 +713,7 @@ export async function buildRecall(binding, query, turn, settings = getSettings()
   }
   const text = blocks.join('\n\n')
   if (!text) errors.push('recall omitted: token budget cannot fit a memory entry')
-  return { text, ids, errors, outcome: text ? 'injected' : 'budget', candidateCount }
+  return finish({ text, ids, errors, outcome: text ? 'injected' : 'budget', candidateCount })
 }
 
 export function createMemoryMessage(text) {
@@ -691,6 +723,80 @@ export function createMemoryMessage(text) {
   })
 }
 
+// Every part of the first-step message is built from one binding snapshot, but
+// retrieval awaits an external engine. During that window the conversation can be
+// switched to another library, moved to another channel/character, or have a layer
+// turned off. A snapshot that no longer matches must be discarded whole: catching
+// the recall error alone would still ship the pre-switch anchor and other parts.
+function injectionSnapshot(binding) {
+  return {
+    libraryId: binding?.libraryId || null,
+    scopeKey: binding?.scopeKey || null,
+    memoryContext: JSON.stringify(binding?.memoryContext || {}),
+    useLibrary: binding?.useLibrary !== false,
+    useGlobal: binding?.useGlobal !== false,
+  }
+}
+
+function injectionSnapshotIsCurrent(sessionId, snapshot, autoInject) {
+  const current = getSessionBinding(sessionId)
+  if (!current) return false
+  if ((current.libraryId || null) !== snapshot.libraryId) return false
+  if ((current.scopeKey || null) !== snapshot.scopeKey) return false
+  if (JSON.stringify(current.memoryContext || {}) !== snapshot.memoryContext) return false
+  if (getSettings().autoInject !== autoInject) return false
+  const scope = effectiveScope(current)
+  return scope.enabled
+    && scope.useLibrary === snapshot.useLibrary
+    && scope.useGlobal === snapshot.useGlobal
+}
+
+// Both the ordinary first-step injection and the guide message must pass the same
+// admission. A guide that ignores the switches tells a disabled conversation to use
+// memory tools it is not supposed to use, and consumes the once-only flag while doing
+// it — so re-enabling later would never deliver the rules.
+function admissionFor(binding) {
+  const settings = getSettings()
+  if (settings.autoInject === 'off') return null
+  const scope = effectiveScope(binding)
+  if (!scope.enabled) return null
+  return { settings, scope }
+}
+
+/**
+ * Deliver the memory rules as a message when the system prompt cannot hold them.
+ *
+ * A preset persona with `complete: true` is restored as the *only* system prompt
+ * section after assembly, so `systemPrompt.section()` from this plugin is dropped and
+ * the model never learns it may write memories — it sees the tools but not the habit.
+ * A plugin message survives that, so send it once per conversation (binding flag), on
+ * the first step, before the model answers.
+ */
+function withGuideMessage(ctx, payload, decision) {
+  try {
+    const header = payload?.agent?.session?.header
+    const sessionId = header?.id
+    if (!sessionId || header.origin === 'subagent') return decision
+    if (typeof payload?.step === 'number' && payload.step !== 1) return decision
+    const binding = getSessionBinding(sessionId)
+    if (!binding || binding.guideMessageAt) return decision
+    if (!admissionFor(binding)) return decision
+    if (!decision || !Array.isArray(decision.messages)) return decision
+    const rules = sectionText(ctx, 'system-guide', payload)
+    const text = [
+      '<memory-guide>',
+      rules,
+      '</memory-guide>',
+      '以上是本插件的记忆规则，不是用户的新指令。若本会话的工具列表里没有 memu_* 工具，请忽略本段，也不要声称自己能写记忆。',
+    ].join('\n')
+    setSessionBinding(sessionId, { guideMessageAt: new Date().toISOString() })
+    return { ...decision, messages: [...decision.messages, createMemoryMessage(text)] }
+  } catch (error) {
+    try { ctx.logger?.warn?.(`dsh-memu-memory: guide message skipped: ${error?.message || error}`) } catch {}
+    return decision
+  }
+}
+
 async function injectInboundForStep({ agent, decision, turn, signal, log, ctx }) {
   const sessionId = agent.session.header.id
   const before = getSessionBinding(sessionId)
@@ -725,33 +831,38 @@ async function injectInboundForStep({ agent, decision, turn, signal, log, ctx })
   const imageCount = images.length
   setSessionBinding(sessionId, { lastImageCount: imageCount })
   const anchorNeeded = effective.reinjectPending || !(effective.injectedIds || []).includes(ANCHOR_SENTINEL)
-  const budget = Math.max(0, Number(settings.turnTokens ?? 640))
+  // turnTokens remains the recall block's own ceiling, but injectionTotalTokens is
+  // the ceiling for the whole plugin message. The two must be applied together:
+  // otherwise a 160-token total with an 800-token recall budget injects ~786.
+  const turnBudget = Math.max(0, Number(settings.turnTokens ?? 640))
+  const totalBudget = Math.max(0, Number(settings.injectionTotalTokens ?? 2000))
+  const totalRoom = () => Math.max(0, totalBudget - estTokens(parts.join('\n\n')) - (parts.length ? 2 : 0))
   const appendBounded = (text, candidateIds = []) => {
     if (!text) return
-    const room = budget - estTokens(parts.join('\n\n')) - (parts.length ? 2 : 0)
-    if (room <= 0) return
-    if (estTokens(text) > room) return
+    if (estTokens(text) > totalRoom()) return
     const clipped = text
     parts.push(clipped)
     ids.push(...candidateIds.filter(id => clipped.includes(`[${id}]`)))
   }
-  if (anchorNeeded && budget >= 160) {
-    const anchor = buildAnchor(effective, { ...settings, anchorTokens: Math.min(Number(settings.anchorTokens || 700), Math.floor(budget / 2)) }, sessionId)
+  if (anchorNeeded && totalRoom() >= 160) {
+    const anchor = buildAnchor(effective, { ...settings, anchorTokens: Math.min(Number(settings.anchorTokens || 700), Math.floor(turnBudget / 2), totalRoom()) }, sessionId)
     appendBounded(anchor.text, anchor.ids)
   }
   if (media.length) {
     const lines = media.map(item => `${item.sha256} · ${item.captionBy}: ${clip(item.caption || '[图片]', 35)}${item.missing ? ' · missing' : ''}`).join('\n')
-    const text = ['<memory-media>', truncateToTokens(lines, Math.min(140, Math.floor(budget / 3))), '图片引用不是视觉证据；attachments 只接受 sha256。', '</memory-media>'].join('\n')
-    if (estTokens(text) + estTokens(parts.join('\n\n')) + 2 <= budget) parts.push(text)
+    const text = ['<memory-media>', truncateToTokens(lines, Math.min(140, Math.floor(totalRoom() / 3))), '图片引用不是视觉证据；attachments 只接受 sha256。', '</memory-media>'].join('\n')
+    appendBounded(text)
   }
   let outcome = 'anchor-only'
   let errors = []
   if (settings.autoInject !== 'anchor-only' && (imageCount || query.length >= Number(settings.minUserChars ?? 6))) {
-    const remaining = Math.max(0, budget - estTokens(parts.join('\n\n')) - (parts.length ? 2 : 0))
-    const recall = await buildRecall(effective, query, clock, { ...settings, turnTokens: remaining }, { agent }, sessionId)
-    if (recall.text) { parts.push(recall.text); ids.push(...recall.ids) }
-    errors = recall.errors
-    outcome = recall.outcome || 'no-match'
+    const recallBudget = Math.max(0, Math.min(turnBudget, totalRoom()))
+    if (recallBudget > 0) {
+      const recall = await buildRecall(effective, query, clock, { ...settings, turnTokens: recallBudget }, { agent }, sessionId)
+      appendBounded(recall.text, recall.ids)
+      errors = recall.errors
+      outcome = recall.outcome || 'no-match'
+    }
   }
   if (signal?.aborted) return decision
   const current = getSessionBinding(sessionId)
@@ -765,6 +876,13 @@ async function injectInboundForStep({ agent, decision, turn, signal, log, ctx })
     return decision
   } else setRecallError(sessionId, null)
   const text = parts.join('\n\n')
+  // Final assertion: every block above is individually bounded, so exceeding the
+  // whole-message ceiling here means the accounting drifted. Drop the batch rather
+  // than publish an over-budget message.
+  if (estTokens(text) > totalBudget) {
+    setRecallError(sessionId, 'inbound injection exceeded injectionTotalTokens')
+    return decision
+  }
   if (text) {
     const pushed = [...new Set(ids)]
     markInjected(sessionId, pushed, clock)
@@ -821,13 +939,14 @@ export async function injectForStep({ agent, decision, turn, step, signal, log =
   // Advance the idle clock even when injection is off, so sleep consolidation
   // still knows when this conversation last did anything.
   touchSession(sessionId)
-  const settings = getSettings()
-  if (settings.autoInject === 'off') return decision
   // The folder policy is the ceiling: a conversation cannot opt into a memory
-  // layer its folder has switched off.
-  const scope = effectiveScope(binding)
-  if (!scope.enabled) return decision
+  // layer its folder has switched off. The guide message shares this admission.
+  const admitted = admissionFor(binding)
+  if (!admitted) return decision
+  const { settings, scope } = admitted
   const effective = { ...binding, useLibrary: scope.useLibrary, useGlobal: scope.useGlobal }
+  // Captured before any await below; re-checked immediately before the splice.
+  const snapshot = injectionSnapshot(effective)
 
   const query = contextualQuery(decision.messages, lastUser)
   const imageCount = imageTurn(lastUser).imageCount
@@ -841,18 +960,27 @@ export async function injectForStep({ agent, decision, turn, step, signal, log =
 
   const parts = []
   const ids = []
+  // The sub-budgets (anchorTokens, turnTokens, the hint's own cap) are ceilings for
+  // their own blocks; injectionTotalTokens is the ceiling for the whole plugin
+  // message. Without this outer gate the sub-budgets can add up past the configured
+  // total even when each one individually looks fine.
+  const injectionBudget = Math.max(0, Number(settings.injectionTotalTokens ?? 2000))
+  const totalRoom = () => Math.max(0, injectionBudget - estTokens(parts.join('\n\n')) - (parts.length ? 2 : 0))
   if (imageCount && effective.useLibrary) {
     const current = getSessionBinding(sessionId)
     const pending = (current?.pendingMedia || []).slice(-8)
     if (pending.length) {
       const details = pending.map(item => `${item.sha256} · ${item.captionBy}: ${clip(item.caption || '[图片]', 35)}${item.missing ? ' · missing' : ''}`).join('\n')
-      parts.push(['<memory-media>', truncateToTokens(details, 150), current.stickerHint ? '同图反复出现，可以用 track=habit 聚合表达习惯，不必逐次写记忆。' : '', '只知道描述与引用，不能凭空声称看过像素。attachments 只接受 sha256。', '</memory-media>'].filter(Boolean).join('\n'))
+      const mediaText = ['<memory-media>', truncateToTokens(details, 150), current.stickerHint ? '同图反复出现，可以用 track=habit 聚合表达习惯，不必逐次写记忆。' : '', '只知道描述与引用，不能凭空声称看过像素。attachments 只接受 sha256。', '</memory-media>'].filter(Boolean).join('\n')
+      if (estTokens(mediaText) <= totalRoom()) parts.push(mediaText)
     }
   }
 
   if (anchorNeeded) {
-    const anchor = buildAnchor(effective, settings, sessionId)
-    if (anchor.text) {
+    const anchor = totalRoom() >= 160
+      ? buildAnchor(effective, { ...settings, anchorTokens: Math.min(Number(settings.anchorTokens || 800), totalRoom()) }, sessionId)
+      : { text: '', ids: [] }
+    if (anchor.text && estTokens(anchor.text) <= totalRoom()) {
       parts.push(anchor.text)
       ids.push(ANCHOR_SENTINEL, ...anchor.ids)
     }
@@ -860,7 +988,7 @@ export async function injectForStep({ agent, decision, turn, step, signal, log =
     // the only moment the pre-compaction memories are missing from the window.
     if (reinject) {
       const replay = buildReplay(effective, settings, sessionId)
-      if (replay.text) {
+      if (replay.text && estTokens(replay.text) <= totalRoom()) {
         parts.push(replay.text)
         ids.push(...replay.ids)
       }
@@ -869,7 +997,7 @@ export async function injectForStep({ agent, decision, turn, step, signal, log =
 
   if (!reinject) {
     const anniversary = buildAnniversary(sessionId, effective)
-    if (anniversary.text) {
+    if (anniversary.text && estTokens(anniversary.text) <= totalRoom()) {
       parts.push(anniversary.text)
       ids.push(...anniversary.ids)
       for (const id of anniversary.fired) markAnniversaryShown(sessionId, id, anniversary.dayKey)
@@ -880,7 +1008,7 @@ export async function injectForStep({ agent, decision, turn, step, signal, log =
     // Independent of retrieval: a loop can be worth raising in a conversation that
     // shares no vocabulary with it, which is exactly the case lexical recall misses.
     const nudge = buildOpenLoopNudge(effective, settings, sessionId)
-    if (nudge.text) {
+    if (nudge.text && estTokens(nudge.text) <= totalRoom()) {
       parts.push(nudge.text)
       ids.push(...nudge.ids)
     }
@@ -890,7 +1018,8 @@ export async function injectForStep({ agent, decision, turn, step, signal, log =
     // The recall path takes the host's exec shape, where the session lives under
     // `.agent`; passing the Agent itself made sessionIdOf return null and turned
     // every per-turn recall into a silent no-op (P0-1).
-    const recall = await buildRecall(effective, query, memoryClock, settings, { agent }, sessionId)
+    const recallBudget = Math.max(0, Math.min(Number(settings.turnTokens ?? 800), totalRoom()))
+    const recall = await buildRecall(effective, query, memoryClock, { ...settings, turnTokens: recallBudget }, { agent }, sessionId)
     setSessionBinding(sessionId, { lastRecallOutcome: { reason: recall.outcome || 'no-match', candidateCount: recall.candidateCount || 0, injectedCount: recall.ids.length, at: new Date().toISOString() } })
     if (recall.text) {
       parts.push(recall.text)
@@ -906,14 +1035,14 @@ export async function injectForStep({ agent, decision, turn, step, signal, log =
 
   if (!reinject) {
     const cue = await maybeCue({ sessionId, turn, settings, binding: effective, exec: { agent } })
-    if (cue) {
+    if (cue && estTokens(cue.text) <= totalRoom()) {
       parts.push(cue.text)
       // The related pointers reached the window, so they count towards habituation and
       // dedupe exactly like the recall block's ids.
       ids.push(...cue.ids)
     }
     const texture = maybeTexture(sessionId, settings)
-    if (texture) parts.push(texture)
+    if (texture && estTokens(texture) <= totalRoom()) parts.push(texture)
   }
 
   if (parts.length === 0) {
@@ -921,6 +1050,11 @@ export async function injectForStep({ agent, decision, turn, step, signal, log =
     return decision
   }
 
+  // This is the last point before the message enters decision.messages. Recall,
+  // cue and texture all awaited above; a library/context/switch change during any
+  // of them invalidates every part built from the old snapshot, not just recall.
+  if (!injectionSnapshotIsCurrent(sessionId, snapshot, settings.autoInject)) return decision
+
   const text = parts.join('\n\n')
   const message = createMemoryMessage(text)
   const rewritten = [...decision.messages]
@@ -974,36 +1108,48 @@ function sectionText(ctx, key, context) {
   }
 }
 
-export function registerInjection(ctx) {
+export function registerInjection(ctx, options = {}) {
   const disposers = []
-  try {
-    ctx.inject(['systemPrompt'], (sctx) => {
-      sctx.effect(() => sctx.systemPrompt.section({
-        name: 'dsh-memu-memory:guide',
-        order: 320,
-        interpolate: false,
-        text: (context) => sectionText(sctx, 'system-guide', context),
-      }), 'dsh-memu-memory: guide prompt')
-      sctx.effect(() => sctx.systemPrompt.section({
-        name: 'dsh-memu-memory:private-policy',
-        order: 321,
-        interpolate: false,
-        text: (context) => sectionText(sctx, 'private-policy', context),
-      }), 'dsh-memu-memory: private policy prompt')
-    })
-  } catch (e) {
-    try { ctx.logger?.warn?.(`dsh-memu-memory: systemPrompt guide unavailable: ${e?.message || e}`) } catch {}
+  // `guide: false` is how a *preset* conversation gets the memory anchor without being
+  // told about tools its preset never mounted — the guide text references memu_* tools,
+  // and a preset that does not list this plugin has no such tools.
+  const wantGuide = options.guide !== false
+  // `guideMessage` exists for conversations whose preset persona uses `complete: true`:
+  // that flag makes the persona the only system prompt section, so a section injected
+  // here is discarded before the model ever sees it. A plugin message still arrives, so
+  // the rules are delivered once per conversation as text instead of as a section.
+  const guideInMessage = options.guideMessage === true
+  if (wantGuide) {
+    try {
+      ctx.inject(['systemPrompt'], (sctx) => {
+        sctx.effect(() => sctx.systemPrompt.section({
+          name: 'dsh-memu-memory:guide',
+          order: 320,
+          interpolate: false,
+          text: (context) => sectionText(sctx, 'system-guide', context),
+        }), 'dsh-memu-memory: guide prompt')
+        sctx.effect(() => sctx.systemPrompt.section({
+          name: 'dsh-memu-memory:private-policy',
+          order: 321,
+          interpolate: false,
+          text: (context) => sectionText(sctx, 'private-policy', context),
+        }), 'dsh-memu-memory: private policy prompt')
+      })
+    } catch (e) {
+      try { ctx.logger?.warn?.(`dsh-memu-memory: systemPrompt guide unavailable: ${e?.message || e}`) } catch {}
+    }
   }
 
   const offPre = ctx.on('agent/pre-step', async (payload, next) => {
     const decision = await next()
     try {
-      return await injectForStep({
+      const injected = await injectForStep({
         ...payload,
         decision,
         ctx,
         log: (message) => { try { ctx.logger?.warn?.(`dsh-memu-memory: ${message}`) } catch {} },
       })
+      return guideInMessage ? withGuideMessage(ctx, payload, injected) : injected
     } catch (error) {
       try { setRecallError(payload?.agent?.session?.header?.id, `injection failed: ${error?.message || error}`) } catch {}
       try { ctx.logger?.warn?.(`dsh-memu-memory: pre-step injection failed (fail-open): ${error?.stack || error}`) } catch {}