typeclaw 0.36.7 → 0.37.0

package/src/bundled-plugins/memory/index.ts

@@ -11,11 +11,27 @@ import { formatLocalDate } from '@/shared'
 
 import { createDreamingSubagent, type DreamingPayload } from './dreaming'
 import { buildInjectionPlan, DEFAULT_INJECTION_BUDGET_BYTES, MIN_INJECTION_BUDGET_BYTES } from './injection-plan'
+import {
+  forceIndexForChannel,
+  loadMemoryInjectionPlan,
+  renderDedupedMemorySection,
+  renderMemorySection,
+  renderRetrievedMemorySection,
+} from './load-memory'
 import { loadAllShards } from './load-shards'
 import { createMemoryLoggerSubagent, type MemoryLoggerPayload } from './memory-logger'
 import { createMemoryRetrievalSubagent, type MemoryRetrievalPayload } from './memory-retrieval'
 import { preShardBackupPath, streamFilePath, streamsDir, topicsDir } from './paths'
-import { memorySearchTool } from './search-tool'
+import { bumpReferenceAccess } from './references/load-references'
+import { createMemorySearchTool } from './search-tool'
+import { type InjectedShardState, partitionDirectShards } from './turn-dedup'
+import { vectorConfigSchema } from './vector/config'
+import { runVectorIndexDoctor } from './vector/doctor'
+import { embed } from './vector/embedder'
+import { hybridSearch, type EmbedFn } from './vector/hybrid'
+import { makeAppendHook } from './vector/index-on-write'
+import { makeReferenceStoredHook } from './vector/reference-index-on-write'
+import { VectorStore } from './vector/store'
 
 const DEFAULT_IDLE_MS = 60_000
 const DEFAULT_BUFFER_BYTES = 500_000
@@ -120,6 +136,7 @@ const memoryConfigSchema = z
     // in milliseconds instead of the production 30s.
     retrievalSpawnTimeoutMs: z.number().int().min(1).default(RETRIEVAL_SPAWN_TIMEOUT_MS),
     dreaming: dreamingConfigSchema.optional(),
+    vector: vectorConfigSchema,
   })
   .default({
     idleMs: DEFAULT_IDLE_MS,
@@ -128,442 +145,569 @@ const memoryConfigSchema = z
     minIdleDeltaLines: DEFAULT_MIN_IDLE_DELTA_LINES,
     spawnTimeoutMs: SPAWN_TIMEOUT_MS,
     retrievalSpawnTimeoutMs: RETRIEVAL_SPAWN_TIMEOUT_MS,
+    vector: { enabled: false },
   })
 
-export default definePlugin({
-  configSchema: memoryConfigSchema,
-  plugin: async (ctx) => {
-    const idleMs = ctx.config.idleMs
-    const bufferBytes = ctx.config.bufferBytes
-    const minIdleDeltaLines = ctx.config.minIdleDeltaLines
-    const spawnTimeoutMs = ctx.config.spawnTimeoutMs
-    const retrievalSpawnTimeoutMs = ctx.config.retrievalSpawnTimeoutMs
-    const dreamingSchedule = ctx.config.dreaming?.schedule ?? DEFAULT_DREAMING_SCHEDULE
-
-    const idleTimers = new Map<string, ReturnType<typeof setTimeout>>()
-    const lastIdleEvent = new Map<string, { parentTranscriptPath: string | undefined; origin?: SessionOrigin }>()
-    const bytesAtLastRun = new Map<string, number>()
-    const linesAtLastRun = new Map<string, number>()
-    // Per-session stream-file cursor: the JSONL line count of the daily
-    // stream file at the END of this session's most recent memory-logger
-    // spawn. Keyed by sessionId, valued by `{ date, lineCount }`. Honored
-    // only when `date` matches today's date — yesterday's cursor points
-    // into yesterday's file and the spawn's payload omits it.
-    const streamCursorAtLastRun = new Map<string, { date: string; lineCount: number }>()
-
-    // memory-logger is coalesced per agentDir (not per parentSessionId) so that
-    // two concurrent channel sessions for the same agent never write to the same
-    // daily stream file at the same time. The subagent consumer would silently drop
-    // a colliding fire, so we serialize spawn calls *here* (chaining each onto the
-    // previous one's settlement) instead of letting the consumer choose between
-    // dropping or queueing. The chain holds at most one in-flight promise plus one
-    // queued.
-    //
-    // The `lastIdleEvent` lookup happens SYNCHRONOUSLY at call time and the
-    // snapshot is captured in `payload` before any await. This is load-bearing
-    // for `session.end`'s fire-and-forget path (see hook below): the hook
-    // synchronously cleans up `lastIdleEvent.delete(sessionId)` immediately
-    // after calling fireMemoryLogger, so if the snapshot were read lazily
-    // inside the chained `.then`, it would race with cleanup and the spawn
-    // would silently no-op. Capturing the payload up front decouples the
-    // session-end snapshot from the cleanup that follows.
-    let spawnChain: Promise<void> = Promise.resolve()
-
-    const fireMemoryLogger = (sessionId: string, reason: 'idle' | 'buffer-trip' | 'session-end'): Promise<void> => {
-      const last = lastIdleEvent.get(sessionId)
-      if (!last || last.parentTranscriptPath === undefined) return Promise.resolve()
-      const parentTranscriptPath = last.parentTranscriptPath
-      const today = formatLocalDate()
-      const priorCursor = streamCursorAtLastRun.get(sessionId)
-      const streamLineCursor =
-        priorCursor !== undefined && priorCursor.date === today ? priorCursor.lineCount : undefined
-      const payload: MemoryLoggerPayload = {
-        parentSessionId: sessionId,
-        parentTranscriptPath,
-        agentDir: ctx.agentDir,
-        ...(last.origin !== undefined ? { origin: last.origin } : {}),
-        ...(streamLineCursor !== undefined ? { streamLineCursor } : {}),
+const VECTOR_TURN_TOP_K = 10
+
+// Per-instance collaborators for the vector index-mode retrieval path. Injected
+// through the plugin factory (not a module global or PluginContext field) so a
+// test can override exactly one — `queryEmbedFn` to drive the real hybridSearch
+// without loading the ~279 MB model, or `hybridSearch` to fake retrieval while
+// testing hook orchestration — without leaking state across other tests in the
+// same worker. Production uses the real `embed` and `hybridSearch`.
+type MemoryPluginDeps = {
+  hybridSearch: typeof hybridSearch
+  queryEmbedFn: EmbedFn
+}
+
+const defaultDeps: MemoryPluginDeps = { hybridSearch, queryEmbedFn: embed }
+
+// Builds the per-turn user-prompt memory block for a vector agent. Under budget
+// (direct mode) injects shard bodies, but de-duplicates across turns: a shard
+// whose body was already injected in full this session is rendered as a compact
+// slug reference (see `partitionDirectShards`) so a long conversation stops
+// re-sending identical bodies every turn while keeping every topic named and
+// recoverable. Over budget falls back to top-K hybrid search.
+//
+// Channel origins never carry bodies (memory-bleed defense). A channel direct-mode
+// turn is force-indexed to a headings/slugs-only section over EVERY shard, not run
+// through hybridSearch: hybrid is relevance-filtered top-K, so an off-topic turn or
+// stale vector index could silently drop headings that direct mode always had.
+async function renderVectorTurnMemory(
+  event: { agentDir: string; userPrompt: string; origin?: SessionOrigin },
+  injectionBudgetBytes: number,
+  injectedState: InjectedShardState,
+  deps: MemoryPluginDeps,
+  logger?: { info: (msg: string) => void },
+): Promise<string> {
+  const plan = await loadMemoryInjectionPlan(event.agentDir, { injectionBudgetBytes })
+  const isChannel = event.origin?.kind === 'channel'
+  if (plan.mode === 'direct' && isChannel) {
+    const indexed = forceIndexForChannel(plan, { origin: event.origin, injectionBudgetBytes })
+    logger?.info(`[vector-retrieval] mode=index topics=${plan.shards.length} channel=forced`)
+    return renderMemorySection(indexed, { origin: event.origin })
+  }
+  if (plan.mode === 'direct') {
+    const { full, unchanged } = partitionDirectShards(plan.shards, injectedState)
+    logger?.info(`[vector-retrieval] mode=direct topics=${plan.shards.length} full=${full.length}`)
+    return renderDedupedMemorySection(full, unchanged)
+  }
+  const store = VectorStore.open(join(event.agentDir, 'memory', '.vectors', 'index.db'))
+  try {
+    const startedAt = Date.now()
+    const results = await deps.hybridSearch(
+      event.userPrompt,
+      store,
+      event.agentDir,
+      VECTOR_TURN_TOP_K,
+      deps.queryEmbedFn,
+    )
+    const elapsedMs = Date.now() - startedAt
+    let topicHits = 0
+    let referenceHits = 0
+    for (const result of results) {
+      if (result.source === 'topic') topicHits += 1
+      else if (result.source === 'reference') referenceHits += 1
+    }
+    const streamHits = results.length - topicHits - referenceHits
+    // results.length === 0 on a non-empty query means the relevance gate suppressed
+    // every candidate (or nothing matched) — an empty memory block, indistinguishable
+    // from "no memory" without this explicit signal.
+    const suppressed = results.length === 0 ? ' suppressed=1' : ''
+    logger?.info(
+      `[vector-retrieval] mode=index topic_results=${topicHits} stream_results=${streamHits} reference_results=${referenceHits} elapsed_ms=${elapsedMs}${suppressed}`,
+    )
+    // Count a vector-surfaced reference as an access so it survives dreaming's
+    // time-decay the same way a memory_search hit does. Fire-and-forget: the
+    // bump only feeds the 30-min dreaming saturation pass, so it must not add a
+    // frontmatter write to the per-turn response critical path.
+    const referenceSlugs = results.flatMap((r) => (r.source === 'reference' ? [r.key] : []))
+    if (referenceSlugs.length > 0) {
+      void bumpReferenceAccess(event.agentDir, referenceSlugs).catch((err) => {
+        logger?.info(`[vector-retrieval] reference access bump failed: ${err instanceof Error ? err.message : err}`)
+      })
+    }
+    return renderRetrievedMemorySection(results, { origin: event.origin })
+  } finally {
+    store.close()
+  }
+}
+
+function createMemoryPlugin(deps: MemoryPluginDeps = defaultDeps) {
+  return definePlugin({
+    configSchema: memoryConfigSchema,
+    plugin: async (ctx) => {
+      const idleMs = ctx.config.idleMs
+      const bufferBytes = ctx.config.bufferBytes
+      const minIdleDeltaLines = ctx.config.minIdleDeltaLines
+      const spawnTimeoutMs = ctx.config.spawnTimeoutMs
+      const retrievalSpawnTimeoutMs = ctx.config.retrievalSpawnTimeoutMs
+      const dreamingSchedule = ctx.config.dreaming?.schedule ?? DEFAULT_DREAMING_SCHEDULE
+
+      const idleTimers = new Map<string, ReturnType<typeof setTimeout>>()
+      const lastIdleEvent = new Map<string, { parentTranscriptPath: string | undefined; origin?: SessionOrigin }>()
+      const bytesAtLastRun = new Map<string, number>()
+      const linesAtLastRun = new Map<string, number>()
+      // Per-session stream-file cursor: the JSONL line count of the daily
+      // stream file at the END of this session's most recent memory-logger
+      // spawn. Keyed by sessionId, valued by `{ date, lineCount }`. Honored
+      // only when `date` matches today's date — yesterday's cursor points
+      // into yesterday's file and the spawn's payload omits it.
+      const streamCursorAtLastRun = new Map<string, { date: string; lineCount: number }>()
+      // Per-session record of shard bodies already injected in full this session,
+      // so direct-mode vector turns can de-duplicate unchanged bodies across turns.
+      // Cleared on session.end alongside the other per-session bookkeeping below.
+      const injectedShards = new Map<string, InjectedShardState>()
+
+      // memory-logger is coalesced per agentDir (not per parentSessionId) so that
+      // two concurrent channel sessions for the same agent never write to the same
+      // daily stream file at the same time. The subagent consumer would silently drop
+      // a colliding fire, so we serialize spawn calls *here* (chaining each onto the
+      // previous one's settlement) instead of letting the consumer choose between
+      // dropping or queueing. The chain holds at most one in-flight promise plus one
+      // queued.
+      //
+      // The `lastIdleEvent` lookup happens SYNCHRONOUSLY at call time and the
+      // snapshot is captured in `payload` before any await. This is load-bearing
+      // for `session.end`'s fire-and-forget path (see hook below): the hook
+      // synchronously cleans up `lastIdleEvent.delete(sessionId)` immediately
+      // after calling fireMemoryLogger, so if the snapshot were read lazily
+      // inside the chained `.then`, it would race with cleanup and the spawn
+      // would silently no-op. Capturing the payload up front decouples the
+      // session-end snapshot from the cleanup that follows.
+      let spawnChain: Promise<void> = Promise.resolve()
+
+      const fireMemoryLogger = (sessionId: string, reason: 'idle' | 'buffer-trip' | 'session-end'): Promise<void> => {
+        const last = lastIdleEvent.get(sessionId)
+        if (!last || last.parentTranscriptPath === undefined) return Promise.resolve()
+        const parentTranscriptPath = last.parentTranscriptPath
+        const today = formatLocalDate()
+        const priorCursor = streamCursorAtLastRun.get(sessionId)
+        const streamLineCursor =
+          priorCursor !== undefined && priorCursor.date === today ? priorCursor.lineCount : undefined
+        const payload: MemoryLoggerPayload = {
+          parentSessionId: sessionId,
+          parentTranscriptPath,
+          agentDir: ctx.agentDir,
+          ...(last.origin !== undefined ? { origin: last.origin } : {}),
+          ...(streamLineCursor !== undefined ? { streamLineCursor } : {}),
+        }
+        // Execution authority is `system` (resolves to owner), NOT the
+        // triggering turn's role: memory-logging is TypeClaw infrastructure over
+        // operator-owned sessions//memory/, so a guest channel turn that triggers
+        // it must not demote the logger to guest and get its transcript read
+        // blocked by privateSurfaceRead. The triggering origin is preserved two
+        // ways: `triggeredBy` for audit provenance, and `payload.origin` for
+        // content provenance (memory extraction/retrieval channel-safety).
+        const spawnOptions: SpawnSubagentOptions = {
+          parentSessionId: sessionId,
+          spawnedByOrigin: {
+            kind: 'system',
+            component: 'memory-logger',
+            ...(last.origin !== undefined ? { triggeredBy: last.origin } : {}),
+          },
+        }
+        const next = spawnChain
+          .catch(() => undefined)
+          .then(async () => {
+            const currentSize = await readSize(parentTranscriptPath)
+            const currentLines = await readLineCount(parentTranscriptPath)
+            bytesAtLastRun.set(sessionId, currentSize)
+            linesAtLastRun.set(sessionId, currentLines)
+            ctx.logger.info(`memory-logger spawn ${sessionId} reason=${reason} transcript_bytes=${currentSize}`)
+            try {
+              await raceSpawn(ctx.spawnSubagent('memory-logger', payload, spawnOptions), spawnTimeoutMs)
+            } catch (err) {
+              ctx.logger.error(`memory-logger spawn failed: ${err instanceof Error ? err.message : String(err)}`)
+            }
+            // Capture the daily-stream line count POST-spawn so the next spawn
+            // (in the same session, on the same day) can resume past anything
+            // this spawn appended. Tied to today's date — `fireMemoryLogger`
+            // checks the date before honoring the cursor.
+            const todayAfterSpawn = formatLocalDate()
+            const streamPath = streamFilePath(ctx.agentDir, todayAfterSpawn)
+            const streamLineCount = await readLineCount(streamPath)
+            streamCursorAtLastRun.set(sessionId, { date: todayAfterSpawn, lineCount: streamLineCount })
+          })
+        spawnChain = next
+        return next
       }
-      // Execution authority is `system` (resolves to owner), NOT the
-      // triggering turn's role: memory-logging is TypeClaw infrastructure over
-      // operator-owned sessions//memory/, so a guest channel turn that triggers
-      // it must not demote the logger to guest and get its transcript read
-      // blocked by privateSurfaceRead. The triggering origin is preserved two
-      // ways: `triggeredBy` for audit provenance, and `payload.origin` for
-      // content provenance (memory extraction/retrieval channel-safety).
-      const spawnOptions: SpawnSubagentOptions = {
-        parentSessionId: sessionId,
-        spawnedByOrigin: {
-          kind: 'system',
-          component: 'memory-logger',
-          ...(last.origin !== undefined ? { triggeredBy: last.origin } : {}),
-        },
+
+      const cancelTimer = (sessionId: string): void => {
+        const t = idleTimers.get(sessionId)
+        if (t !== undefined) {
+          clearTimeout(t)
+          idleTimers.delete(sessionId)
+        }
       }
-      const next = spawnChain
-        .catch(() => undefined)
-        .then(async () => {
-          const currentSize = await readSize(parentTranscriptPath)
-          const currentLines = await readLineCount(parentTranscriptPath)
-          bytesAtLastRun.set(sessionId, currentSize)
-          linesAtLastRun.set(sessionId, currentLines)
-          ctx.logger.info(`memory-logger spawn ${sessionId} reason=${reason} transcript_bytes=${currentSize}`)
-          try {
-            await raceSpawn(ctx.spawnSubagent('memory-logger', payload, spawnOptions), spawnTimeoutMs)
-          } catch (err) {
-            ctx.logger.error(`memory-logger spawn failed: ${err instanceof Error ? err.message : String(err)}`)
-          }
-          // Capture the daily-stream line count POST-spawn so the next spawn
-          // (in the same session, on the same day) can resume past anything
-          // this spawn appended. Tied to today's date — `fireMemoryLogger`
-          // checks the date before honoring the cursor.
-          const todayAfterSpawn = formatLocalDate()
-          const streamPath = streamFilePath(ctx.agentDir, todayAfterSpawn)
-          const streamLineCount = await readLineCount(streamPath)
-          streamCursorAtLastRun.set(sessionId, { date: todayAfterSpawn, lineCount: streamLineCount })
-        })
-      spawnChain = next
-      return next
-    }
 
-    const cancelTimer = (sessionId: string): void => {
-      const t = idleTimers.get(sessionId)
-      if (t !== undefined) {
-        clearTimeout(t)
-        idleTimers.delete(sessionId)
+      const shouldTripBufferCeiling = async (sessionId: string, transcriptPath: string): Promise<boolean> => {
+        if (bufferBytes === 0) return false
+        const currentSize = await readSize(transcriptPath)
+        const baseline = bytesAtLastRun.get(sessionId)
+        if (baseline === undefined) {
+          bytesAtLastRun.set(sessionId, currentSize)
+          return false
+        }
+        return currentSize - baseline >= bufferBytes
       }
-    }
 
-    const shouldTripBufferCeiling = async (sessionId: string, transcriptPath: string): Promise<boolean> => {
-      if (bufferBytes === 0) return false
-      const currentSize = await readSize(transcriptPath)
-      const baseline = bytesAtLastRun.get(sessionId)
-      if (baseline === undefined) {
-        bytesAtLastRun.set(sessionId, currentSize)
-        return false
+      const shouldSkipIdleSpawn = async (sessionId: string, transcriptPath: string): Promise<boolean> => {
+        if (minIdleDeltaLines === 0) return false
+        const currentLines = await readLineCount(transcriptPath)
+        if (currentLines === 0) return false
+        const baseline = linesAtLastRun.get(sessionId) ?? 0
+        return currentLines - baseline < minIdleDeltaLines
       }
-      return currentSize - baseline >= bufferBytes
-    }
 
-    const shouldSkipIdleSpawn = async (sessionId: string, transcriptPath: string): Promise<boolean> => {
-      if (minIdleDeltaLines === 0) return false
-      const currentLines = await readLineCount(transcriptPath)
-      if (currentLines === 0) return false
-      const baseline = linesAtLastRun.get(sessionId) ?? 0
-      return currentLines - baseline < minIdleDeltaLines
-    }
+      const runMemoryRetrieval = async (event: {
+        sessionId: string
+        agentDir: string
+        userPrompt: string
+        origin?: SessionOrigin
+      }): Promise<void> => {
+        const shards = await loadAllShards(event.agentDir)
+        const plan = buildInjectionPlan(shards, { budgetBytes: ctx.config.injectionBudgetBytes })
+        if (plan.mode === 'direct') return
 
-    const runMemoryRetrieval = async (event: {
-      sessionId: string
-      agentDir: string
-      userPrompt: string
-      origin?: SessionOrigin
-    }): Promise<void> => {
-      const shards = await loadAllShards(event.agentDir)
-      const plan = buildInjectionPlan(shards, { budgetBytes: ctx.config.injectionBudgetBytes })
-      if (plan.mode === 'direct') return
-
-      const cacheFilePath = join(event.agentDir, 'memory', '.retrieval-cache', `${event.sessionId}.md`)
-      const payload: MemoryRetrievalPayload = {
-        parentSessionId: event.sessionId,
-        agentDir: event.agentDir,
-        recentPrompt: event.userPrompt,
-        cacheFilePath,
-        ...(event.origin !== undefined ? { origin: event.origin } : {}),
+        const cacheFilePath = join(event.agentDir, 'memory', '.retrieval-cache', `${event.sessionId}.md`)
+        const payload: MemoryRetrievalPayload = {
+          parentSessionId: event.sessionId,
+          agentDir: event.agentDir,
+          recentPrompt: event.userPrompt,
+          cacheFilePath,
+          ...(event.origin !== undefined ? { origin: event.origin } : {}),
+        }
+        // System authority, not the triggering turn's role — see the
+        // memory-logger spawn above. memory-retrieval writes
+        // memory/.retrieval-cache/, which a guest-demoted role cannot.
+        const retrievalSpawnOptions: SpawnSubagentOptions = {
+          parentSessionId: event.sessionId,
+          spawnedByOrigin: {
+            kind: 'system',
+            component: 'memory-retrieval',
+            ...(event.origin !== undefined ? { triggeredBy: event.origin } : {}),
+          },
+        }
+        await ctx.spawnSubagent('memory-retrieval', payload, retrievalSpawnOptions)
       }
-      // System authority, not the triggering turn's role — see the
-      // memory-logger spawn above. memory-retrieval writes
-      // memory/.retrieval-cache/, which a guest-demoted role cannot.
-      const retrievalSpawnOptions: SpawnSubagentOptions = {
-        parentSessionId: event.sessionId,
-        spawnedByOrigin: {
-          kind: 'system',
-          component: 'memory-retrieval',
-          ...(event.origin !== undefined ? { triggeredBy: event.origin } : {}),
-        },
+
+      // Subagents are constructed at boot here (rather than imported as constants)
+      // so their lifecycle logs route through the plugin logger and pick up the
+      // `[plugin:memory]` prefix. Without this, they would write directly to
+      // console and bypass the plugin namespace.
+      const subagentLogger = {
+        info: (m: string) => ctx.logger.info(m),
+        warn: (m: string) => ctx.logger.warn(m),
+        error: (m: string) => ctx.logger.error(m),
       }
-      await ctx.spawnSubagent('memory-retrieval', payload, retrievalSpawnOptions)
-    }
 
-    // Subagents are constructed at boot here (rather than imported as constants)
-    // so their lifecycle logs route through the plugin logger and pick up the
-    // `[plugin:memory]` prefix. Without this, they would write directly to
-    // console and bypass the plugin namespace.
-    const subagentLogger = {
-      info: (m: string) => ctx.logger.info(m),
-      warn: (m: string) => ctx.logger.warn(m),
-      error: (m: string) => ctx.logger.error(m),
-    }
+      // Open a long-lived VectorStore for append-time indexing when vector is enabled.
+      const appendVectorStore = ctx.config.vector.enabled
+        ? VectorStore.open(join(ctx.agentDir, 'memory', '.vectors', 'index.db'))
+        : undefined
 
-    return {
-      subagents: {
-        'memory-logger': createMemoryLoggerSubagent({ logger: subagentLogger }),
-        'memory-retrieval': createMemoryRetrievalSubagent({
-          logger: subagentLogger,
-          timeoutMs: retrievalSpawnTimeoutMs,
-        }),
-        dreaming: createDreamingSubagent({ logger: subagentLogger }),
-      },
-      tools: {
-        memory_search: memorySearchTool,
-      },
-      cronJobs: {
-        dreaming: {
-          schedule: dreamingSchedule,
-          kind: 'prompt' as const,
-          prompt: '(internal: dreaming consolidation; user prompt is built by the dreaming subagent handler)',
-          subagent: 'dreaming',
-          payload: { agentDir: ctx.agentDir } satisfies DreamingPayload,
+      return {
+        subagents: {
+          'memory-logger': createMemoryLoggerSubagent({
+            logger: subagentLogger,
+            ...(appendVectorStore !== undefined
+              ? {
+                  onFragmentsAppended: makeAppendHook(appendVectorStore),
+                  onReferenceStored: makeReferenceStoredHook(appendVectorStore),
+                }
+              : {}),
+          }),
+          'memory-retrieval': createMemoryRetrievalSubagent({
+            logger: subagentLogger,
+            timeoutMs: retrievalSpawnTimeoutMs,
+          }),
+          dreaming: createDreamingSubagent({
+            logger: subagentLogger,
+          }),
         },
-      },
-      hooks: {
-        // Memory injection lives in core (`createResourceLoader` calls `loadMemory`
-        // directly, appended LAST in the system prompt). It does not run from a
-        // plugin hook because positioning matters for cache-prefix stability:
-        // the daily-stream file grows after every channel turn (memory-logger
-        // appends a fragment + watermark) and memory/topics/ changes on every dream.
-        // A volatile region in the middle of the system prompt invalidates the
-        // entire cacheable suffix below it on every session resurrection
-        // (channel sessions evicted by idle GC, container restarts). Pinning
-        // memory to the bottom of the system prompt keeps everything above it
-        // cacheable across resurrections, at the cost of re-billing only the
-        // memory section itself when it grows.
-        //
-        // Core fires `session.idle` immediately after every prompt completion;
-        // the plugin owns the debounce timer so memory-logger only spawns
-        // after the user has been quiet for `idleMs`. Re-arming a still-armed
-        // timer cancels it first, matching the previous core IdleDetector.
-        // The size-based ceiling fires synchronously when the transcript has
-        // grown by `bufferBytes` since the last run, so busy channel sessions
-        // (which rarely go idle) still produce memory updates.
-        'session.idle': async (event) => {
-          if (event.origin?.kind === 'subagent') return
-          lastIdleEvent.set(event.sessionId, {
-            parentTranscriptPath: event.parentTranscriptPath,
-            ...(event.origin !== undefined ? { origin: event.origin } : {}),
-          })
-          cancelTimer(event.sessionId)
-          const sessionId = event.sessionId
-          const transcriptPath = event.parentTranscriptPath
-          const timer = setTimeout(() => {
-            idleTimers.delete(sessionId)
-            void (async () => {
-              if (transcriptPath !== undefined && (await shouldSkipIdleSpawn(sessionId, transcriptPath))) {
-                ctx.logger.info(
-                  `memory-logger idle skip ${sessionId} (delta below minIdleDeltaLines=${minIdleDeltaLines})`,
-                )
-                return
-              }
-              void fireMemoryLogger(sessionId, 'idle')
-            })()
-          }, idleMs)
-          idleTimers.set(sessionId, timer)
-          if (
-            event.parentTranscriptPath !== undefined &&
-            (await shouldTripBufferCeiling(sessionId, event.parentTranscriptPath))
-          ) {
-            ctx.logger.info(`buffer-ceiling trip ${sessionId} bufferBytes=${bufferBytes}`)
-            cancelTimer(sessionId)
-            await fireMemoryLogger(sessionId, 'buffer-trip')
-          }
+        tools: {
+          memory_search: createMemorySearchTool(),
         },
-        // memory-retrieval used to run from `session.prompt`, which fires
-        // during system-prompt assembly (createResourceLoader) and carries
-        // the ASSEMBLING SYSTEM PROMPT as `event.prompt` — not the user's
-        // message. The plugin was feeding that string into the subagent as
-        // `recentPrompt`, so the LLM keyword-mined TypeClaw's framing prose
-        // (`TypeClaw`, `subagent`, `AGENTS.md`, `systemPromptLeak`, etc.)
-        // and burned 15+ memory_search calls per session on terms the user
-        // never said. `session.turn.start` is the correct trigger: it fires
-        // before each `session.prompt(text)` call with the actual text the
-        // session is about to receive.
-        //
-        // The hook body is fully detached. `runSessionTurnStart` has no
-        // per-handler timeout (unlike session.prompt/idle/end), and the
-        // caller awaits it before `session.prompt(text)` runs — so an
-        // inline `await loadAllShards(...)` would gate every channel turn
-        // on N shard reads. Detaching mirrors PR #337's "fire-and-forget
-        // the slow work" pattern, pushed one level earlier to cover both
-        // the shard read AND the LLM spawn.
-        //
-        // Per-turn instead of per-session-creation means N spawns over the
-        // session's lifetime, but the subagent's own `inFlightKey` on
-        // `parentSessionId` (memory-retrieval.ts) coalesces overlapping
-        // fires: if turn N's retrieval is still running when turn N+1 fires,
-        // the second spawn is dropped with a warning, and the cache from
-        // turn N is still consumed by turn N+1 via the documented
-        // lag-by-one-prompt contract (load-memory.ts:appendRetrievalCache).
-        //
-        // Known limitation: a detached spawn can theoretically settle after
-        // `session.end` has unlinked the cache file, leaving a single ~5 KB
-        // file in memory/.retrieval-cache/ that never gets read. The next
-        // session.end that matches this sessionId would clean it up, but
-        // sessionIds are UUIDv7 so reuse is effectively never. Fix would
-        // serialize session.end behind the in-flight spawn, which
-        // re-introduces the cold-start blocking shape PR #337 fixed. The
-        // leaked file is bounded (one per disconnected session) and lives
-        // in a dir already marked transient.
-        //
-        // ctx.spawnSubagent IS reject-able in production: it wraps
-        // dispatchSpawnSubagent (src/run/index.ts) which calls invokeSubagent
-        // directly with no try/catch. SubagentConsumer's catch only protects
-        // stream-initiated spawns (target.kind === 'new-session'), not the
-        // direct ctx.spawnSubagent path the hooks use. Same for
-        // loadAllShards' fs errors. The .catch() on the void-discarded
-        // promise below is load-bearing — without it, every shard-read or
-        // handler failure (LLM provider error, payload validation throw)
-        // would surface as an unhandled rejection because nothing awaits
-        // the promise.
-        'session.turn.start': (event) => {
-          if (event.origin?.kind === 'subagent') return
-          void runMemoryRetrieval(event).catch((err) => {
-            ctx.logger.error(`memory-retrieval spawn failed: ${err instanceof Error ? err.message : String(err)}`)
-          })
+        cronJobs: {
+          dreaming: {
+            schedule: dreamingSchedule,
+            kind: 'prompt' as const,
+            prompt: '(internal: dreaming consolidation; user prompt is built by the dreaming subagent handler)',
+            subagent: 'dreaming',
+            payload: { agentDir: ctx.agentDir } satisfies DreamingPayload,
+          },
         },
-        // The memory-logger spawn is intentionally detached (`void`) instead
-        // of awaited. The channel router calls `tearDownLive` synchronously
-        // inside `ensureLive`'s stale-rollover path (router.ts:718), and
-        // `tearDownLive` awaits `fireSessionEnd` which awaits this hook. An
-        // awaited memory-logger spawn here would block new-session creation
-        // for the full subagent runtime — observed as 22+ seconds of channel
-        // silence on a 22 KB transcript before the new session even starts
-        // its cold-start chain.
-        //
-        // Safety: `fireMemoryLogger` captures the payload synchronously from
-        // `lastIdleEvent` (see comment above), so the `delete` calls below
-        // cannot race with the chained spawn. `spawnChain` still serializes
-        // memory-logger fires per agentDir — the detached promise is queued
-        // onto the chain before this hook returns, so a subsequent fire from
-        // the new session (idle, buffer-trip, or session-end) waits for the
-        // session-end spawn to settle before running.
-        //
-        // The only durability tradeoff: if the agent process dies between
-        // this hook returning and `spawnChain` settling, the session-end
-        // memory-logger fire is lost (its transcript fragments don't make
-        // it into today's daily stream). This is already true for the idle
-        // and buffer-trip paths, which are timer-driven and fire-and-forget
-        // by design. Session JSONLs are force-committed elsewhere, so no
-        // user-visible transcript is lost — only the LLM-distilled stream
-        // fragments for the final batch.
-        'session.end': (event) => {
-          if (event.origin?.kind === 'subagent') return
-          cancelTimer(event.sessionId)
-          const sessionId = event.sessionId
-          // The skip path detaches via `void (async () => …)()` because
-          // readSize requires an await. fireMemoryLogger itself captures its
-          // payload synchronously from `lastIdleEvent` (see fireMemoryLogger
-          // comment block), so the `lastIdleEvent.delete` that follows can
-          // never race with the chained spawn. The cache-cleanup and
-          // bookkeeping deletes are dispatched alongside (not blocking the
-          // hook return) to preserve the "session.end returns synchronously"
-          // contract that the channel router's tearDownLive path depends on
-          // (see the comment block above this hook).
-          void (async () => {
-            const last = lastIdleEvent.get(sessionId)
-            let skip = false
-            if (last?.parentTranscriptPath !== undefined) {
-              const baseline = bytesAtLastRun.get(sessionId)
-              if (baseline !== undefined && baseline > 0) {
-                const currentSize = await readSize(last.parentTranscriptPath)
-                if (currentSize === baseline) {
+        hooks: {
+          // Memory injection lives in core (`createResourceLoader` calls `loadMemory`
+          // directly, appended LAST in the system prompt). It does not run from a
+          // plugin hook because positioning matters for cache-prefix stability:
+          // the daily-stream file grows after every channel turn (memory-logger
+          // appends a fragment + watermark) and memory/topics/ changes on every dream.
+          // A volatile region in the middle of the system prompt invalidates the
+          // entire cacheable suffix below it on every session resurrection
+          // (channel sessions evicted by idle GC, container restarts). Pinning
+          // memory to the bottom of the system prompt keeps everything above it
+          // cacheable across resurrections, at the cost of re-billing only the
+          // memory section itself when it grows.
+          //
+          // Core fires `session.idle` immediately after every prompt completion;
+          // the plugin owns the debounce timer so memory-logger only spawns
+          // after the user has been quiet for `idleMs`. Re-arming a still-armed
+          // timer cancels it first, matching the previous core IdleDetector.
+          // The size-based ceiling fires synchronously when the transcript has
+          // grown by `bufferBytes` since the last run, so busy channel sessions
+          // (which rarely go idle) still produce memory updates.
+          'session.idle': async (event) => {
+            if (event.origin?.kind === 'subagent') return
+            lastIdleEvent.set(event.sessionId, {
+              parentTranscriptPath: event.parentTranscriptPath,
+              ...(event.origin !== undefined ? { origin: event.origin } : {}),
+            })
+            cancelTimer(event.sessionId)
+            const sessionId = event.sessionId
+            const transcriptPath = event.parentTranscriptPath
+            const timer = setTimeout(() => {
+              idleTimers.delete(sessionId)
+              void (async () => {
+                if (transcriptPath !== undefined && (await shouldSkipIdleSpawn(sessionId, transcriptPath))) {
                   ctx.logger.info(
-                    `memory-logger session-end skip ${sessionId} (no new bytes since last spawn at ${baseline})`,
+                    `memory-logger idle skip ${sessionId} (delta below minIdleDeltaLines=${minIdleDeltaLines})`,
                   )
-                  skip = true
+                  return
                 }
-              }
+                void fireMemoryLogger(sessionId, 'idle')
+              })()
+            }, idleMs)
+            idleTimers.set(sessionId, timer)
+            if (
+              event.parentTranscriptPath !== undefined &&
+              (await shouldTripBufferCeiling(sessionId, event.parentTranscriptPath))
+            ) {
+              ctx.logger.info(`buffer-ceiling trip ${sessionId} bufferBytes=${bufferBytes}`)
+              cancelTimer(sessionId)
+              await fireMemoryLogger(sessionId, 'buffer-trip')
             }
-            if (!skip) void fireMemoryLogger(sessionId, 'session-end')
-            lastIdleEvent.delete(sessionId)
-            bytesAtLastRun.delete(sessionId)
-            linesAtLastRun.delete(sessionId)
-            streamCursorAtLastRun.delete(sessionId)
-          })()
-          const cacheFilePath = join(ctx.agentDir, 'memory', '.retrieval-cache', `${sessionId}.md`)
-          unlink(cacheFilePath).catch((err) => {
-            if (!isEnoent(err)) ctx.logger.warn(`[memory] failed to clean retrieval cache: ${err}`)
-          })
-        },
-      },
-      doctorChecks: {
-        'dir-writable': {
-          description: 'memory/topics/ exists and is writable',
-          run: async (dctx) => {
-            const dir = topicsDir(dctx.agentDir)
-            try {
-              await access(dir, fsConstants.W_OK)
-              return { status: 'ok', message: `${dir} writable` }
-            } catch {
+          },
+          // memory-retrieval used to run from `session.prompt`, which fires
+          // during system-prompt assembly (createResourceLoader) and carries
+          // the ASSEMBLING SYSTEM PROMPT as `event.prompt` — not the user's
+          // message. The plugin was feeding that string into the subagent as
+          // `recentPrompt`, so the LLM keyword-mined TypeClaw's framing prose
+          // (`TypeClaw`, `subagent`, `AGENTS.md`, `systemPromptLeak`, etc.)
+          // and burned 15+ memory_search calls per session on terms the user
+          // never said. `session.turn.start` is the correct trigger: it fires
+          // before each `session.prompt(text)` call with the actual text the
+          // session is about to receive.
+          //
+          'session.turn.start': async (event) => {
+            if (ctx.config.vector.enabled) {
+              // Vector agents inject long-term memory PER-TURN into the user
+              // prompt (the system-prompt `# Memory` section is suppressed at
+              // session creation). This runs for every origin that supplies a
+              // retrievalContext bag — including subagents, which no longer get
+              // memory via the system prompt either.
+              if (event.retrievalContext === undefined) return
               try {
-                await mkdir(dir, { recursive: true })
-                return { status: 'ok', message: `created ${dir}` }
-              } catch {
-                return {
-                  status: 'error',
-                  message: `${dir} is missing and could not be created`,
-                  fix: { description: 'Create memory/topics/ in the agent folder or fix its permissions on the host.' },
+                let injectedState = injectedShards.get(event.sessionId)
+                if (injectedState === undefined) {
+                  injectedState = new Map()
+                  injectedShards.set(event.sessionId, injectedState)
                 }
+                event.retrievalContext.results = await renderVectorTurnMemory(
+                  event,
+                  ctx.config.injectionBudgetBytes,
+                  injectedState,
+                  deps,
+                  ctx.logger,
+                )
+              } catch (err) {
+                ctx.logger.error(`vector-retrieval failed: ${err instanceof Error ? err.message : String(err)}`)
               }
+              return
             }
+            // Non-vector agents keep memory in the system prompt. The index-mode
+            // retrieval subagent must NOT fire for subagent-origin turns (it would
+            // recurse: the subagent it spawns triggers another turn.start).
+            if (event.origin?.kind === 'subagent') return
+            void runMemoryRetrieval(event).catch((err) => {
+              ctx.logger.error(`memory-retrieval spawn failed: ${err instanceof Error ? err.message : String(err)}`)
+            })
           },
-        },
-        'daily-stream-current': {
-          description: "today's daily stream file exists",
-          run: async (dctx) => {
-            const today = new Date().toISOString().slice(0, 10)
-            const rel = join('memory', 'streams', `${today}.jsonl`)
-            const abs = streamFilePath(dctx.agentDir, today)
-            if (existsSync(abs)) return { status: 'ok', message: `${rel} present` }
-            return {
-              status: 'warning',
-              message: `${rel} missing`,
-              fix: {
-                description: `Create empty ${rel} so memory-logger has a target.`,
-                apply: async () => {
-                  await mkdir(streamsDir(dctx.agentDir), { recursive: true })
-                  await writeFile(abs, '', 'utf8')
-                  return { summary: `created ${rel}`, changedPaths: [rel] }
-                },
-              },
-            }
+          // The memory-logger spawn is intentionally detached (`void`) instead
+          // of awaited. The channel router calls `tearDownLive` synchronously
+          // inside `ensureLive`'s stale-rollover path (router.ts:718), and
+          // `tearDownLive` awaits `fireSessionEnd` which awaits this hook. An
+          // awaited memory-logger spawn here would block new-session creation
+          // for the full subagent runtime — observed as 22+ seconds of channel
+          // silence on a 22 KB transcript before the new session even starts
+          // its cold-start chain.
+          //
+          // Safety: `fireMemoryLogger` captures the payload synchronously from
+          // `lastIdleEvent` (see comment above), so the `delete` calls below
+          // cannot race with the chained spawn. `spawnChain` still serializes
+          // memory-logger fires per agentDir — the detached promise is queued
+          // onto the chain before this hook returns, so a subsequent fire from
+          // the new session (idle, buffer-trip, or session-end) waits for the
+          // session-end spawn to settle before running.
+          //
+          // The only durability tradeoff: if the agent process dies between
+          // this hook returning and `spawnChain` settling, the session-end
+          // memory-logger fire is lost (its transcript fragments don't make
+          // it into today's daily stream). This is already true for the idle
+          // and buffer-trip paths, which are timer-driven and fire-and-forget
+          // by design. Session JSONLs are force-committed elsewhere, so no
+          // user-visible transcript is lost — only the LLM-distilled stream
+          // fragments for the final batch.
+          'session.end': (event) => {
+            // Dedup state is populated for every vector turn (subagents included),
+            // so it must be cleared before the subagent-origin early-return below.
+            injectedShards.delete(event.sessionId)
+            if (event.origin?.kind === 'subagent') return
+            cancelTimer(event.sessionId)
+            const sessionId = event.sessionId
+            // The skip path detaches via `void (async () => …)()` because
+            // readSize requires an await. fireMemoryLogger itself captures its
+            // payload synchronously from `lastIdleEvent` (see fireMemoryLogger
+            // comment block), so the `lastIdleEvent.delete` that follows can
+            // never race with the chained spawn. The cache-cleanup and
+            // bookkeeping deletes are dispatched alongside (not blocking the
+            // hook return) to preserve the "session.end returns synchronously"
+            // contract that the channel router's tearDownLive path depends on
+            // (see the comment block above this hook).
+            void (async () => {
+              const last = lastIdleEvent.get(sessionId)
+              let skip = false
+              if (last?.parentTranscriptPath !== undefined) {
+                const baseline = bytesAtLastRun.get(sessionId)
+                if (baseline !== undefined && baseline > 0) {
+                  const currentSize = await readSize(last.parentTranscriptPath)
+                  if (currentSize === baseline) {
+                    ctx.logger.info(
+                      `memory-logger session-end skip ${sessionId} (no new bytes since last spawn at ${baseline})`,
+                    )
+                    skip = true
+                  }
+                }
+              }
+              if (!skip) void fireMemoryLogger(sessionId, 'session-end')
+              lastIdleEvent.delete(sessionId)
+              bytesAtLastRun.delete(sessionId)
+              linesAtLastRun.delete(sessionId)
+              streamCursorAtLastRun.delete(sessionId)
+            })()
+            const cacheFilePath = join(ctx.agentDir, 'memory', '.retrieval-cache', `${sessionId}.md`)
+            unlink(cacheFilePath).catch((err) => {
+              if (!isEnoent(err)) ctx.logger.warn(`[memory] failed to clean retrieval cache: ${err}`)
+            })
           },
         },
-        'pre-shard-backup-age': {
-          description: 'Warn when pre-shard backup is older than 30 days',
-          run: async (dctx) => {
-            const backupPath = preShardBackupPath(dctx.agentDir)
-            let s
-            try {
-              s = await stat(backupPath)
-            } catch {
-              return { status: 'ok', message: 'no pre-shard backup present' }
-            }
-            const ageDays = (Date.now() - s.mtimeMs) / 86_400_000
-            if (ageDays > 30) {
+        doctorChecks: {
+          'dir-writable': {
+            description: 'memory/topics/ exists and is writable',
+            run: async (dctx) => {
+              const dir = topicsDir(dctx.agentDir)
+              try {
+                await access(dir, fsConstants.W_OK)
+                return { status: 'ok', message: `${dir} writable` }
+              } catch {
+                try {
+                  await mkdir(dir, { recursive: true })
+                  return { status: 'ok', message: `created ${dir}` }
+                } catch {
+                  return {
+                    status: 'error',
+                    message: `${dir} is missing and could not be created`,
+                    fix: {
+                      description: 'Create memory/topics/ in the agent folder or fix its permissions on the host.',
+                    },
+                  }
+                }
+              }
+            },
+          },
+          'daily-stream-current': {
+            description: "today's daily stream file exists",
+            run: async (dctx) => {
+              const today = new Date().toISOString().slice(0, 10)
+              const rel = join('memory', 'streams', `${today}.jsonl`)
+              const abs = streamFilePath(dctx.agentDir, today)
+              if (existsSync(abs)) return { status: 'ok', message: `${rel} present` }
               return {
                 status: 'warning',
-                message: `pre-shard backup is ${Math.round(ageDays)} days old; safe to delete if migration is verified`,
+                message: `${rel} missing`,
                 fix: {
-                  description: 'Delete the pre-shard backup file',
+                  description: `Create empty ${rel} so memory-logger has a target.`,
                   apply: async () => {
-                    await unlink(backupPath)
-                    return {
-                      summary: 'deleted pre-shard backup',
-                      changedPaths: [join('memory', 'MEMORY.md.pre-shard.bak')],
-                    }
+                    await mkdir(streamsDir(dctx.agentDir), { recursive: true })
+                    await writeFile(abs, '', 'utf8')
+                    return { summary: `created ${rel}`, changedPaths: [rel] }
                   },
                 },
               }
-            }
-            return {
-              status: 'ok',
-              message: `pre-shard backup is ${Math.round(ageDays)} days old (under 30-day threshold)`,
-            }
+            },
+          },
+          'pre-shard-backup-age': {
+            description: 'Warn when pre-shard backup is older than 30 days',
+            run: async (dctx) => {
+              const backupPath = preShardBackupPath(dctx.agentDir)
+              let s
+              try {
+                s = await stat(backupPath)
+              } catch {
+                return { status: 'ok', message: 'no pre-shard backup present' }
+              }
+              const ageDays = (Date.now() - s.mtimeMs) / 86_400_000
+              if (ageDays > 30) {
+                return {
+                  status: 'warning',
+                  message: `pre-shard backup is ${Math.round(ageDays)} days old; safe to delete if migration is verified`,
+                  fix: {
+                    description: 'Delete the pre-shard backup file',
+                    apply: async () => {
+                      await unlink(backupPath)
+                      return {
+                        summary: 'deleted pre-shard backup',
+                        changedPaths: [join('memory', 'MEMORY.md.pre-shard.bak')],
+                      }
+                    },
+                  },
+                }
+              }
+              return {
+                status: 'ok',
+                message: `pre-shard backup is ${Math.round(ageDays)} days old (under 30-day threshold)`,
+              }
+            },
+          },
+          'vector-index': {
+            description: 'vector index is consistent with memory (only when memory.vector is enabled)',
+            run: async (dctx) => {
+              const config = dctx.config as typeof ctx.config
+              if (!vectorEnabled(config)) {
+                return { status: 'ok', message: 'vector memory not enabled; skipping index health check' }
+              }
+              return runVectorIndexDoctor(dctx.agentDir)
+            },
           },
         },
-      },
-    }
-  },
-})
+      }
+    },
+  })
+}
+
+export default createMemoryPlugin()
+
+export function createMemoryPluginForTests(overrides: Partial<MemoryPluginDeps> = {}) {
+  return createMemoryPlugin({ ...defaultDeps, ...overrides })
+}
+
+function vectorEnabled(config: unknown): boolean {
+  if (typeof config !== 'object' || config === null) return false
+  const parsed = vectorConfigSchema.safeParse((config as Record<string, unknown>).vector)
+  return parsed.success && parsed.data.enabled
+}
 
 async function readSize(path: string): Promise<number> {
   try {