@xopcai/xopc 0.0.115 → 0.0.117

package/dist/src/agent/memory/dreaming/deep-promotion.js.map

@@ -1 +1 @@
-{"version":3,"file":"deep-promotion.js","names":[],"sources":["../../../../../src/agent/memory/dreaming/deep-promotion.ts"],"sourcesContent":["import fs from 'node:fs/promises';\nimport path from 'node:path';\n\nimport { createLogger } from '../../../utils/logger.js';\nimport { MEMORY_MD_FILENAME } from './constants.js';\nimport {\n  loadDreamingStore,\n  saveDreamingStore,\n  withDreamingPromotionLock,\n  type DreamingStoreEntry,\n} from './short-term-store.js';\nimport {\n  DREAMING_LAST_RUN_FORMAT_VERSION,\n  emptyDeepPhaseSkipped,\n  writeDreamingDeepLastRun,\n  type DreamingDeepLastRun,\n  type DreamingDeepPhaseSkipped,\n} from './last-run.js';\nimport type { DreamingDeepConfig } from './config.js';\nimport {\n  clamp01,\n  compareCandidatesByScore,\n  computeCandidateScore,\n  extractPromotionMarkers,\n  isContaminatedSnippet,\n  isExpiredEntry,\n  isoDay,\n  readFileLines,\n  resolveDeepDefaults,\n  sliceRange,\n  snippetHash,\n} from './utils.js';\n\nconst log = createLogger('Dreaming:Deep');\n\nexport type { DreamingDeepConfig } from './config.js';\n\nexport type DreamingPromotionCandidate = DreamingStoreEntry & {\n  avgScore: number;\n  /** Time-decay-adjusted final score used for ranking. */\n  score: number;\n  /** Raw recency decay multiplier (0–1). */\n  recencyDecay: number;\n};\n\n\nfunction markerForPromotion(key: string, hash: string): string {\n  // Quote values to allow spaces/colons in key.\n  return `<!-- xopc-memory-promotion key=\"${key}\" hash=\"${hash}\" -->`;\n}\n\n\nasync function rehydrateSnippet(params: {\n  workspaceDir: string;\n  candidate: DreamingPromotionCandidate;\n}): Promise<{ snippet: string; startLine: number; endLine: number } | null> {\n  const fullPath = path.join(params.workspaceDir, params.candidate.path);\n  const lines = await readFileLines(fullPath);\n  if (!lines) return null;\n\n  const startLine = Math.max(1, Math.floor(params.candidate.startLine));\n  const endLine = Math.max(startLine, Math.floor(params.candidate.endLine));\n  const snippet = sliceRange(lines, startLine, endLine);\n  if (!snippet) return null;\n  return { snippet, startLine, endLine };\n}\n\n\nfunction buildDeepLastRun(base: {\n  runId: string;\n  startedAt: string;\n  finishedAt: string;\n  t0: number;\n  ok: boolean;\n  reason: string;\n  config: DreamingDeepConfig;\n  memoryPath: string;\n  errorMessage?: string;\n  deep: DreamingDeepLastRun['deep'];\n}): DreamingDeepLastRun {\n  const durationMs = Math.max(0, Date.now() - base.t0);\n  return {\n    version: DREAMING_LAST_RUN_FORMAT_VERSION,\n    phase: 'deep',\n    runId: base.runId,\n    startedAt: base.startedAt,\n    finishedAt: base.finishedAt,\n    durationMs,\n    ok: base.ok,\n    reason: base.reason,\n    config: base.config,\n    memoryPath: base.memoryPath,\n    ...(base.errorMessage ? { errorMessage: base.errorMessage } : {}),\n    deep: base.deep,\n  };\n}\n\nexport async function runDreamingDeepPromotion(params: {\n  workspaceDir: string;\n  config?: Partial<DreamingDeepConfig>;\n  now?: Date;\n}): Promise<{\n  ok: boolean;\n  reason: string;\n  candidates: number;\n  applied: number;\n  memoryPath: string;\n}> {\n  const cfg = resolveDeepDefaults(params.config);\n  const now = params.now ?? new Date();\n  const startedAt = now.toISOString();\n  const runId = `${startedAt}:${process.pid}:${Math.random().toString(16).slice(2)}`;\n  const memoryPath = path.join(params.workspaceDir, MEMORY_MD_FILENAME);\n  const t0 = Date.now();\n\n  // Early exit for disabled or zero-limit configurations.\n  const earlyExitReason = !cfg.enabled ? 'dreaming disabled' : cfg.limit === 0 ? 'dreaming limit=0' : null;\n  if (earlyExitReason) {\n    const finishedAt = new Date().toISOString();\n    const empty = emptyDeepPhaseSkipped();\n    await writeDreamingDeepLastRun({\n      workspaceDir: params.workspaceDir,\n      lastRun: buildDeepLastRun({\n        runId,\n        startedAt,\n        finishedAt,\n        t0,\n        ok: true,\n        reason: earlyExitReason,\n        config: cfg,\n        memoryPath,\n        deep: { candidatesRanked: 0, applied: 0, skipped: empty },\n      }),\n    }).catch(() => undefined);\n    return { ok: true, reason: earlyExitReason, candidates: 0, applied: 0, memoryPath };\n  }\n\n  try {\n    const result = await withDreamingPromotionLock(params.workspaceDir, async () => {\n      const { store } = await loadDreamingStore({ workspaceDir: params.workspaceDir });\n\n      const nowMs = now.getTime();\n\n      const all = Object.values(store.entries ?? {}).filter((e): e is DreamingStoreEntry => {\n        if (!e || typeof e !== 'object') return false;\n        if (e.promotedAt) return false;\n        if (!e.path || !e.path.startsWith('memory/')) return false;\n        if (e.recallCount < cfg.minRecallCount) return false;\n        // Require minimum unique queries to avoid single-query inflation.\n        if ((e.queryHashes?.length ?? 0) < cfg.minUniqueQueries) return false;\n        // Expire entries older than maxAgeDays since last recall.\n        if (isExpiredEntry(e.lastRecalledAt, nowMs, cfg.maxAgeDays)) return false;\n        const avg = e.recallCount > 0 ? e.totalScore / e.recallCount : 0;\n        return clamp01(avg) >= cfg.minScore;\n      });\n\n      const ranked: DreamingPromotionCandidate[] = all\n        .map((e) => {\n          const { avgScore, score, recencyDecay } = computeCandidateScore(e, nowMs, cfg.recencyHalfLifeDays);\n          return { ...e, avgScore, score, recencyDecay };\n        })\n        .sort(compareCandidatesByScore)\n        .slice(0, cfg.limit);\n\n      if (ranked.length === 0) {\n        const z = emptyDeepPhaseSkipped();\n        return { ok: true, reason: 'no eligible candidates', candidates: 0, applied: 0, memoryPath, skipped: z };\n      }\n\n      const existing = await fs.readFile(memoryPath, 'utf-8').catch((err: unknown) => {\n        if ((err as NodeJS.ErrnoException | undefined)?.code === 'ENOENT') return '';\n        throw err;\n      });\n      const existingMarkers = extractPromotionMarkers(existing);\n\n      const appliedCandidates: Array<{\n        key: string;\n        hash: string;\n        snippet: string;\n        path: string;\n        startLine: number;\n        endLine: number;\n        score: number;\n        recallCount: number;\n        avgScore: number;\n      }> = [];\n\n      const skipped: DreamingDeepPhaseSkipped = emptyDeepPhaseSkipped();\n      for (const candidate of ranked) {\n        if (existingMarkers.keys.has(candidate.key)) {\n          skipped.alreadyPromotedKey += 1;\n          // Treat as already applied; mark promotedAt for idempotency and keep going.\n          const entry = store.entries[candidate.key];\n          if (entry && !entry.promotedAt) {\n            entry.promotedAt = now.toISOString();\n          }\n          continue;\n        }\n        const rehydrated = await rehydrateSnippet({ workspaceDir: params.workspaceDir, candidate });\n        if (!rehydrated) {\n          skipped.rehydrateFailed += 1;\n          continue;\n        }\n        if (isContaminatedSnippet(rehydrated.snippet)) {\n          skipped.contaminated += 1;\n          continue;\n        }\n        const hash = snippetHash(rehydrated.snippet);\n        if (existingMarkers.hashes.has(hash)) {\n          skipped.hashDuplicate += 1;\n          // Already promoted (possibly from a different key/line range). Mark promoted for idempotency.\n          const entry = store.entries[candidate.key];\n          if (entry && !entry.promotedAt) {\n            entry.promotedAt = now.toISOString();\n          }\n          continue;\n        }\n        appliedCandidates.push({\n          key: candidate.key,\n        hash,\n          snippet: rehydrated.snippet,\n          path: candidate.path,\n          startLine: rehydrated.startLine,\n          endLine: rehydrated.endLine,\n          score: candidate.score,\n          recallCount: candidate.recallCount,\n          avgScore: candidate.avgScore,\n        });\n      }\n\n      if (appliedCandidates.length === 0) {\n        await saveDreamingStore({ workspaceDir: params.workspaceDir, store });\n        return {\n          ok: true,\n          reason: 'candidates were stale or already applied',\n          candidates: ranked.length,\n          applied: 0,\n          memoryPath,\n          skipped,\n        };\n      }\n\n      const day = isoDay(now);\n      const header = existing.trim().length > 0 ? '' : '# Long-Term Memory\\n\\n';\n      const sectionLines: string[] = ['', `## Promoted From Short-Term Memory (${day})`, ''];\n      for (const c of appliedCandidates) {\n        const src = `${c.path}:${c.startLine}-${c.endLine}`;\n        sectionLines.push(markerForPromotion(c.key, c.hash));\n        sectionLines.push(\n          `- ${c.snippet} [score=${c.score.toFixed(3)} recalls=${c.recallCount} avg=${c.avgScore.toFixed(3)} source=${src}]`,\n        );\n      }\n      sectionLines.push('');\n\n      const next = `${header}${existing.endsWith('\\n') || existing.length === 0 ? existing : `${existing}\\n`}${sectionLines.join('\\n')}`;\n      await fs.writeFile(memoryPath, next, 'utf-8');\n\n      const nowIso = now.toISOString();\n      for (const c of appliedCandidates) {\n        const entry = store.entries[c.key];\n        if (entry) {\n          entry.promotedAt = nowIso;\n          entry.snippet = c.snippet;\n          entry.startLine = c.startLine;\n          entry.endLine = c.endLine;\n        }\n      }\n      store.updatedAt = nowIso;\n      await saveDreamingStore({ workspaceDir: params.workspaceDir, store });\n\n      log.info(\n        { workspaceDir: params.workspaceDir, candidates: ranked.length, applied: appliedCandidates.length },\n        'Dreaming deep promotion complete',\n      );\n\n      return {\n        ok: true,\n        reason: 'applied promotions',\n        candidates: ranked.length,\n        applied: appliedCandidates.length,\n        memoryPath,\n        skipped,\n      };\n    });\n\n    const finishedAt = new Date().toISOString();\n    const empty = emptyDeepPhaseSkipped();\n    const resultSkipped = 'skipped' in result ? result.skipped : empty;\n    await writeDreamingDeepLastRun({\n      workspaceDir: params.workspaceDir,\n      lastRun: buildDeepLastRun({\n        runId,\n        startedAt,\n        finishedAt,\n        t0,\n        ok: result.ok,\n        reason: result.reason,\n        config: cfg,\n        memoryPath: result.memoryPath,\n        deep: {\n          candidatesRanked: result.candidates,\n          applied: result.applied,\n          skipped: resultSkipped,\n        },\n      }),\n    }).catch(() => undefined);\n\n    return {\n      ok: result.ok,\n      reason: result.reason,\n      candidates: result.candidates,\n      applied: result.applied,\n      memoryPath: result.memoryPath,\n    };\n  } catch (err) {\n    const finishedAt = new Date().toISOString();\n    const em = err instanceof Error ? err.message : String(err);\n    const z = emptyDeepPhaseSkipped();\n    await writeDreamingDeepLastRun({\n      workspaceDir: params.workspaceDir,\n      lastRun: buildDeepLastRun({\n        runId,\n        startedAt,\n        finishedAt,\n        t0,\n        ok: false,\n        reason: 'error',\n        config: cfg,\n        memoryPath,\n        errorMessage: em,\n        deep: { candidatesRanked: 0, applied: 0, skipped: z },\n      }),\n    }).catch(() => undefined);\n    throw err;\n  }\n}\n\n"],"mappings":"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"}
+{"version":3,"file":"deep-promotion.js","names":[],"sources":["../../../../../src/agent/memory/dreaming/deep-promotion.ts"],"sourcesContent":["import fs from 'node:fs/promises';\nimport path from 'node:path';\n\nimport { createLogger } from '../../../utils/logger.js';\nimport { MEMORY_MD_FILENAME } from './constants.js';\nimport {\n  loadDreamingStore,\n  saveDreamingStore,\n  withDreamingPromotionLock,\n  type DreamingStoreEntry,\n} from './short-term-store.js';\nimport {\n  DREAMING_LAST_RUN_FORMAT_VERSION,\n  emptyDeepPhaseSkipped,\n  writeDreamingDeepLastRun,\n  type DreamingDeepLastRun,\n  type DreamingDeepPhaseSkipped,\n} from './last-run.js';\nimport type { DreamingDeepConfig } from './config.js';\nimport type { MemoryManager } from '../manager.js';\nimport {\n  clamp01,\n  compareCandidatesByScore,\n  computeCandidateScore,\n  extractPromotionMarkers,\n  isContaminatedSnippet,\n  isExpiredEntry,\n  isoDay,\n  readFileLines,\n  resolveDeepDefaults,\n  sliceRange,\n  snippetHash,\n} from './utils.js';\n\nconst log = createLogger('Dreaming:Deep');\n\nexport type { DreamingDeepConfig } from './config.js';\n\nexport type DreamingPromotionCandidate = DreamingStoreEntry & {\n  avgScore: number;\n  /** Time-decay-adjusted final score used for ranking. */\n  score: number;\n  /** Raw recency decay multiplier (0–1). */\n  recencyDecay: number;\n};\n\n\nfunction markerForPromotion(key: string, hash: string): string {\n  // Quote values to allow spaces/colons in key.\n  return `<!-- xopc-memory-promotion key=\"${key}\" hash=\"${hash}\" -->`;\n}\n\n\nasync function rehydrateSnippet(params: {\n  workspaceDir: string;\n  candidate: DreamingPromotionCandidate;\n}): Promise<{ snippet: string; startLine: number; endLine: number } | null> {\n  const fullPath = path.join(params.workspaceDir, params.candidate.path);\n  const lines = await readFileLines(fullPath);\n  if (!lines) return null;\n\n  const startLine = Math.max(1, Math.floor(params.candidate.startLine));\n  const endLine = Math.max(startLine, Math.floor(params.candidate.endLine));\n  const snippet = sliceRange(lines, startLine, endLine);\n  if (!snippet) return null;\n  return { snippet, startLine, endLine };\n}\n\n\nfunction buildDeepLastRun(base: {\n  runId: string;\n  startedAt: string;\n  finishedAt: string;\n  t0: number;\n  ok: boolean;\n  reason: string;\n  config: DreamingDeepConfig;\n  memoryPath: string;\n  errorMessage?: string;\n  deep: DreamingDeepLastRun['deep'];\n}): DreamingDeepLastRun {\n  const durationMs = Math.max(0, Date.now() - base.t0);\n  return {\n    version: DREAMING_LAST_RUN_FORMAT_VERSION,\n    phase: 'deep',\n    runId: base.runId,\n    startedAt: base.startedAt,\n    finishedAt: base.finishedAt,\n    durationMs,\n    ok: base.ok,\n    reason: base.reason,\n    config: base.config,\n    memoryPath: base.memoryPath,\n    ...(base.errorMessage ? { errorMessage: base.errorMessage } : {}),\n    deep: base.deep,\n  };\n}\n\nexport async function runDreamingDeepPromotion(params: {\n  workspaceDir: string;\n  config?: Partial<DreamingDeepConfig>;\n  memoryManager?: MemoryManager;\n  now?: Date;\n}): Promise<{\n  ok: boolean;\n  reason: string;\n  candidates: number;\n  applied: number;\n  memoryPath: string;\n}> {\n  const cfg = resolveDeepDefaults(params.config);\n  const now = params.now ?? new Date();\n  const startedAt = now.toISOString();\n  const runId = `${startedAt}:${process.pid}:${Math.random().toString(16).slice(2)}`;\n  const memoryPath = path.join(params.workspaceDir, MEMORY_MD_FILENAME);\n  const t0 = Date.now();\n\n  // Early exit for disabled or zero-limit configurations.\n  const earlyExitReason = !cfg.enabled ? 'dreaming disabled' : cfg.limit === 0 ? 'dreaming limit=0' : null;\n  if (earlyExitReason) {\n    const finishedAt = new Date().toISOString();\n    const empty = emptyDeepPhaseSkipped();\n    await writeDreamingDeepLastRun({\n      workspaceDir: params.workspaceDir,\n      lastRun: buildDeepLastRun({\n        runId,\n        startedAt,\n        finishedAt,\n        t0,\n        ok: true,\n        reason: earlyExitReason,\n        config: cfg,\n        memoryPath,\n        deep: { candidatesRanked: 0, applied: 0, skipped: empty },\n      }),\n    }).catch(() => undefined);\n    return { ok: true, reason: earlyExitReason, candidates: 0, applied: 0, memoryPath };\n  }\n\n  try {\n    const result = await withDreamingPromotionLock(params.workspaceDir, async () => {\n      const { store } = await loadDreamingStore({ workspaceDir: params.workspaceDir });\n\n      const nowMs = now.getTime();\n\n      const all = Object.values(store.entries ?? {}).filter((e): e is DreamingStoreEntry => {\n        if (!e || typeof e !== 'object') return false;\n        if (e.promotedAt) return false;\n        if (!e.path || !e.path.startsWith('memory/')) return false;\n        if (e.recallCount < cfg.minRecallCount) return false;\n        // Require minimum unique queries to avoid single-query inflation.\n        if ((e.queryHashes?.length ?? 0) < cfg.minUniqueQueries) return false;\n        // Expire entries older than maxAgeDays since last recall.\n        if (isExpiredEntry(e.lastRecalledAt, nowMs, cfg.maxAgeDays)) return false;\n        const avg = e.recallCount > 0 ? e.totalScore / e.recallCount : 0;\n        return clamp01(avg) >= cfg.minScore;\n      });\n\n      const ranked: DreamingPromotionCandidate[] = all\n        .map((e) => {\n          const { avgScore, score, recencyDecay } = computeCandidateScore(e, nowMs, cfg.recencyHalfLifeDays);\n          return { ...e, avgScore, score, recencyDecay };\n        })\n        .sort(compareCandidatesByScore)\n        .slice(0, cfg.limit);\n\n      if (ranked.length === 0) {\n        const z = emptyDeepPhaseSkipped();\n        return { ok: true, reason: 'no eligible candidates', candidates: 0, applied: 0, memoryPath, skipped: z };\n      }\n\n      const existing = await fs.readFile(memoryPath, 'utf-8').catch((err: unknown) => {\n        if ((err as NodeJS.ErrnoException | undefined)?.code === 'ENOENT') return '';\n        throw err;\n      });\n      const existingMarkers = extractPromotionMarkers(existing);\n\n      const appliedCandidates: Array<{\n        key: string;\n        hash: string;\n        snippet: string;\n        path: string;\n        startLine: number;\n        endLine: number;\n        score: number;\n        recallCount: number;\n        avgScore: number;\n      }> = [];\n\n      const skipped: DreamingDeepPhaseSkipped = emptyDeepPhaseSkipped();\n      for (const candidate of ranked) {\n        if (existingMarkers.keys.has(candidate.key)) {\n          skipped.alreadyPromotedKey += 1;\n          // Treat as already applied; mark promotedAt for idempotency and keep going.\n          const entry = store.entries[candidate.key];\n          if (entry && !entry.promotedAt) {\n            entry.promotedAt = now.toISOString();\n          }\n          continue;\n        }\n        const rehydrated = await rehydrateSnippet({ workspaceDir: params.workspaceDir, candidate });\n        if (!rehydrated) {\n          skipped.rehydrateFailed += 1;\n          continue;\n        }\n        if (isContaminatedSnippet(rehydrated.snippet)) {\n          skipped.contaminated += 1;\n          continue;\n        }\n        const hash = snippetHash(rehydrated.snippet);\n        if (existingMarkers.hashes.has(hash)) {\n          skipped.hashDuplicate += 1;\n          // Already promoted (possibly from a different key/line range). Mark promoted for idempotency.\n          const entry = store.entries[candidate.key];\n          if (entry && !entry.promotedAt) {\n            entry.promotedAt = now.toISOString();\n          }\n          continue;\n        }\n        appliedCandidates.push({\n          key: candidate.key,\n        hash,\n          snippet: rehydrated.snippet,\n          path: candidate.path,\n          startLine: rehydrated.startLine,\n          endLine: rehydrated.endLine,\n          score: candidate.score,\n          recallCount: candidate.recallCount,\n          avgScore: candidate.avgScore,\n        });\n      }\n\n      if (appliedCandidates.length === 0) {\n        await saveDreamingStore({ workspaceDir: params.workspaceDir, store });\n        return {\n          ok: true,\n          reason: 'candidates were stale or already applied',\n          candidates: ranked.length,\n          applied: 0,\n          memoryPath,\n          skipped,\n        };\n      }\n\n      const day = isoDay(now);\n      const header = existing.trim().length > 0 ? '' : '# Long-Term Memory\\n\\n';\n      const sectionLines: string[] = ['', `## Promoted From Short-Term Memory (${day})`, ''];\n      for (const c of appliedCandidates) {\n        const src = `${c.path}:${c.startLine}-${c.endLine}`;\n        sectionLines.push(markerForPromotion(c.key, c.hash));\n        sectionLines.push(\n          `- ${c.snippet} [score=${c.score.toFixed(3)} recalls=${c.recallCount} avg=${c.avgScore.toFixed(3)} source=${src}]`,\n        );\n      }\n      sectionLines.push('');\n\n      const next = `${header}${existing.endsWith('\\n') || existing.length === 0 ? existing : `${existing}\\n`}${sectionLines.join('\\n')}`;\n      await fs.writeFile(memoryPath, next, 'utf-8');\n\n      const nowIso = now.toISOString();\n      for (const c of appliedCandidates) {\n        const writeResult = await params.memoryManager?.write({\n          kind: 'derived_insight',\n          content: c.snippet,\n          source: {\n            provider: 'dreaming',\n            path: c.path,\n            lineStart: c.startLine,\n            lineEnd: c.endLine,\n          },\n          tags: ['dreaming', 'promoted'],\n        });\n        params.memoryManager?.recordSignal({\n          source: 'dreaming',\n          recordId: writeResult?.record?.id,\n          score: c.score,\n          content: c.snippet,\n          metadata: {\n            path: c.path,\n            startLine: c.startLine,\n            endLine: c.endLine,\n            recallCount: c.recallCount,\n            avgScore: c.avgScore,\n          },\n        });\n        const entry = store.entries[c.key];\n        if (entry) {\n          entry.promotedAt = nowIso;\n          entry.snippet = c.snippet;\n          entry.startLine = c.startLine;\n          entry.endLine = c.endLine;\n        }\n      }\n      store.updatedAt = nowIso;\n      await saveDreamingStore({ workspaceDir: params.workspaceDir, store });\n\n      log.info(\n        { workspaceDir: params.workspaceDir, candidates: ranked.length, applied: appliedCandidates.length },\n        'Dreaming deep promotion complete',\n      );\n\n      return {\n        ok: true,\n        reason: 'applied promotions',\n        candidates: ranked.length,\n        applied: appliedCandidates.length,\n        memoryPath,\n        skipped,\n      };\n    });\n\n    const finishedAt = new Date().toISOString();\n    const empty = emptyDeepPhaseSkipped();\n    const resultSkipped = 'skipped' in result ? result.skipped : empty;\n    await writeDreamingDeepLastRun({\n      workspaceDir: params.workspaceDir,\n      lastRun: buildDeepLastRun({\n        runId,\n        startedAt,\n        finishedAt,\n        t0,\n        ok: result.ok,\n        reason: result.reason,\n        config: cfg,\n        memoryPath: result.memoryPath,\n        deep: {\n          candidatesRanked: result.candidates,\n          applied: result.applied,\n          skipped: resultSkipped,\n        },\n      }),\n    }).catch(() => undefined);\n\n    return {\n      ok: result.ok,\n      reason: result.reason,\n      candidates: result.candidates,\n      applied: result.applied,\n      memoryPath: result.memoryPath,\n    };\n  } catch (err) {\n    const finishedAt = new Date().toISOString();\n    const em = err instanceof Error ? err.message : String(err);\n    const z = emptyDeepPhaseSkipped();\n    await writeDreamingDeepLastRun({\n      workspaceDir: params.workspaceDir,\n      lastRun: buildDeepLastRun({\n        runId,\n        startedAt,\n        finishedAt,\n        t0,\n        ok: false,\n        reason: 'error',\n        config: cfg,\n        memoryPath,\n        errorMessage: em,\n        deep: { candidatesRanked: 0, applied: 0, skipped: z },\n      }),\n    }).catch(() => undefined);\n    throw err;\n  }\n}\n"],"mappings":"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"}

package/dist/src/agent/memory/index.d.ts

@@ -1,6 +1,7 @@
 export { BuiltinMemoryStore, MEMORY_ENTRY_DELIMITER, scanForThreats } from './builtin-memory-store.js';
 export { BuiltinMemoryProvider } from './builtin-provider.js';
 export { buildMemoryContextBlock, sanitizeMemoryContextFenceEscapes } from './context-fence.js';
+export { MemoryContextAssembler } from './context-assembler.js';
 export { createMemoryManagerFromConfig } from './create-memory-manager.js';
 export { injectPrefetchIntoUserMessage } from './inject-prefetch.js';
 export { isCuratedMemoryInPrompt, isMemorySubsystemEnabled, resolveBuiltinMemoryStoreConfig, shouldInjectMemoryPrefetchThisTurn, shouldRegisterCuratedMemoryTool, } from './memory-config.js';

package/dist/src/agent/memory/index.js

@@ -1,12 +1,13 @@
 import { isCuratedMemoryInPrompt, isMemorySubsystemEnabled, resolveBuiltinMemoryStoreConfig, shouldInjectMemoryPrefetchThisTurn, shouldRegisterCuratedMemoryTool } from "./memory-config.js";
 import { extractAgentUserPlainText } from "./user-message-text.js";
 import { buildMemoryContextBlock, sanitizeMemoryContextFenceEscapes } from "./context-fence.js";
+import { MemoryContextAssembler } from "./context-assembler.js";
 import { injectPrefetchIntoUserMessage } from "./inject-prefetch.js";
 import { BuiltinMemoryStore, MEMORY_ENTRY_DELIMITER, scanForThreats } from "./builtin-memory-store.js";
 import { BuiltinMemoryProvider } from "./builtin-provider.js";
 import { MemoryManager } from "./manager.js";
-import { StubMemoryProvider } from "./stub-memory-provider.js";
+import { discoverMemoryPlugins } from "./plugin-discovery.js";
 import { createMemoryManagerFromConfig } from "./create-memory-manager.js";
 import { MemoryFlushService } from "./memory-flush.js";
-import { discoverMemoryPlugins } from "./plugin-discovery.js";
-export { BuiltinMemoryProvider, BuiltinMemoryStore, MEMORY_ENTRY_DELIMITER, MemoryFlushService, MemoryManager, StubMemoryProvider, buildMemoryContextBlock, createMemoryManagerFromConfig, discoverMemoryPlugins, extractAgentUserPlainText, injectPrefetchIntoUserMessage, isCuratedMemoryInPrompt, isMemorySubsystemEnabled, resolveBuiltinMemoryStoreConfig, sanitizeMemoryContextFenceEscapes, scanForThreats, shouldInjectMemoryPrefetchThisTurn, shouldRegisterCuratedMemoryTool };
+import { StubMemoryProvider } from "./stub-memory-provider.js";
+export { BuiltinMemoryProvider, BuiltinMemoryStore, MEMORY_ENTRY_DELIMITER, MemoryContextAssembler, MemoryFlushService, MemoryManager, StubMemoryProvider, buildMemoryContextBlock, createMemoryManagerFromConfig, discoverMemoryPlugins, extractAgentUserPlainText, injectPrefetchIntoUserMessage, isCuratedMemoryInPrompt, isMemorySubsystemEnabled, resolveBuiltinMemoryStoreConfig, sanitizeMemoryContextFenceEscapes, scanForThreats, shouldInjectMemoryPrefetchThisTurn, shouldRegisterCuratedMemoryTool };

package/dist/src/agent/memory/inject-prefetch.js

@@ -1,5 +1,5 @@
 import { readAgentMessageContent } from "./agent-message-access.js";
-import { buildMemoryContextBlock } from "./context-fence.js";
+import { MemoryContextAssembler } from "./context-assembler.js";
 //#region src/agent/memory/inject-prefetch.ts
 /**
 * Prefix user message with fenced prefetched memory context (if any).
@@ -7,7 +7,11 @@ import { buildMemoryContextBlock } from "./context-fence.js";
 async function injectPrefetchIntoUserMessage(memoryManager, sessionKey, userMessage, queryText) {
 	const q = queryText.trim();
 	if (!q) return userMessage;
-	const block = buildMemoryContextBlock(await memoryManager.prefetchAll(q, { sessionId: sessionKey }));
+	const block = await new MemoryContextAssembler().assemble({
+		memoryManager,
+		sessionKey,
+		query: q
+	});
 	if (!block.trim()) return userMessage;
 	const prefix = `${block}\n\n`;
 	const c = readAgentMessageContent(userMessage);

package/dist/src/agent/memory/inject-prefetch.js.map

@@ -1 +1 @@
-{"version":3,"file":"inject-prefetch.js","names":[],"sources":["../../../../src/agent/memory/inject-prefetch.ts"],"sourcesContent":["import type { AgentMessage } from '@earendil-works/pi-agent-core';\n\nimport { readAgentMessageContent } from './agent-message-access.js';\nimport { buildMemoryContextBlock } from './context-fence.js';\nimport type { MemoryManager } from './manager.js';\n\n/**\n * Prefix user message with fenced prefetched memory context (if any).\n */\nexport async function injectPrefetchIntoUserMessage(\n  memoryManager: MemoryManager,\n  sessionKey: string,\n  userMessage: AgentMessage,\n  queryText: string,\n): Promise<AgentMessage> {\n  const q = queryText.trim();\n  if (!q) {\n    return userMessage;\n  }\n\n  const raw = await memoryManager.prefetchAll(q, { sessionId: sessionKey });\n  const block = buildMemoryContextBlock(raw);\n  if (!block.trim()) {\n    return userMessage;\n  }\n\n  const prefix = `${block}\\n\\n`;\n  const c = readAgentMessageContent(userMessage);\n\n  if (typeof c === 'string') {\n    return { ...userMessage, content: prefix + c } as AgentMessage;\n  }\n\n  if (Array.isArray(c) && c.length > 0) {\n    const first = c[0] as { type?: string; text?: string };\n    if (first?.type === 'text' && typeof first.text === 'string') {\n      const copy = [...c];\n      copy[0] = { type: 'text', text: prefix + first.text };\n      return { ...userMessage, content: copy } as AgentMessage;\n    }\n    return {\n      ...userMessage,\n      content: [{ type: 'text' as const, text: prefix }, ...c],\n    } as AgentMessage;\n  }\n\n  return userMessage;\n}\n"],"mappings":";;;;;;AASA,eAAsB,8BACpB,eACA,YACA,aACA,WACuB;CACvB,MAAM,IAAI,UAAU,MAAM;AAC1B,KAAI,CAAC,EACH,QAAO;CAIT,MAAM,QAAQ,wBAAwB,MADpB,cAAc,YAAY,GAAG,EAAE,WAAW,YAAY,CAAC,CAC/B;AAC1C,KAAI,CAAC,MAAM,MAAM,CACf,QAAO;CAGT,MAAM,SAAS,GAAG,MAAM;CACxB,MAAM,IAAI,wBAAwB,YAAY;AAE9C,KAAI,OAAO,MAAM,SACf,QAAO;EAAE,GAAG;EAAa,SAAS,SAAS;EAAG;AAGhD,KAAI,MAAM,QAAQ,EAAE,IAAI,EAAE,SAAS,GAAG;EACpC,MAAM,QAAQ,EAAE;AAChB,MAAI,OAAO,SAAS,UAAU,OAAO,MAAM,SAAS,UAAU;GAC5D,MAAM,OAAO,CAAC,GAAG,EAAE;AACnB,QAAK,KAAK;IAAE,MAAM;IAAQ,MAAM,SAAS,MAAM;IAAM;AACrD,UAAO;IAAE,GAAG;IAAa,SAAS;IAAM;;AAE1C,SAAO;GACL,GAAG;GACH,SAAS,CAAC;IAAE,MAAM;IAAiB,MAAM;IAAQ,EAAE,GAAG,EAAE;GACzD;;AAGH,QAAO"}
+{"version":3,"file":"inject-prefetch.js","names":[],"sources":["../../../../src/agent/memory/inject-prefetch.ts"],"sourcesContent":["import type { AgentMessage } from '@earendil-works/pi-agent-core';\n\nimport { readAgentMessageContent } from './agent-message-access.js';\nimport { MemoryContextAssembler } from './context-assembler.js';\nimport type { MemoryManager } from './manager.js';\n\n/**\n * Prefix user message with fenced prefetched memory context (if any).\n */\nexport async function injectPrefetchIntoUserMessage(\n  memoryManager: MemoryManager,\n  sessionKey: string,\n  userMessage: AgentMessage,\n  queryText: string,\n): Promise<AgentMessage> {\n  const q = queryText.trim();\n  if (!q) {\n    return userMessage;\n  }\n\n  const block = await new MemoryContextAssembler().assemble({\n    memoryManager,\n    sessionKey,\n    query: q,\n  });\n  if (!block.trim()) {\n    return userMessage;\n  }\n\n  const prefix = `${block}\\n\\n`;\n  const c = readAgentMessageContent(userMessage);\n\n  if (typeof c === 'string') {\n    return { ...userMessage, content: prefix + c } as AgentMessage;\n  }\n\n  if (Array.isArray(c) && c.length > 0) {\n    const first = c[0] as { type?: string; text?: string };\n    if (first?.type === 'text' && typeof first.text === 'string') {\n      const copy = [...c];\n      copy[0] = { type: 'text', text: prefix + first.text };\n      return { ...userMessage, content: copy } as AgentMessage;\n    }\n    return {\n      ...userMessage,\n      content: [{ type: 'text' as const, text: prefix }, ...c],\n    } as AgentMessage;\n  }\n\n  return userMessage;\n}\n"],"mappings":";;;;;;AASA,eAAsB,8BACpB,eACA,YACA,aACA,WACuB;CACvB,MAAM,IAAI,UAAU,MAAM;AAC1B,KAAI,CAAC,EACH,QAAO;CAGT,MAAM,QAAQ,MAAM,IAAI,wBAAwB,CAAC,SAAS;EACxD;EACA;EACA,OAAO;EACR,CAAC;AACF,KAAI,CAAC,MAAM,MAAM,CACf,QAAO;CAGT,MAAM,SAAS,GAAG,MAAM;CACxB,MAAM,IAAI,wBAAwB,YAAY;AAE9C,KAAI,OAAO,MAAM,SACf,QAAO;EAAE,GAAG;EAAa,SAAS,SAAS;EAAG;AAGhD,KAAI,MAAM,QAAQ,EAAE,IAAI,EAAE,SAAS,GAAG;EACpC,MAAM,QAAQ,EAAE;AAChB,MAAI,OAAO,SAAS,UAAU,OAAO,MAAM,SAAS,UAAU;GAC5D,MAAM,OAAO,CAAC,GAAG,EAAE;AACnB,QAAK,KAAK;IAAE,MAAM;IAAQ,MAAM,SAAS,MAAM;IAAM;AACrD,UAAO;IAAE,GAAG;IAAa,SAAS;IAAM;;AAE1C,SAAO;GACL,GAAG;GACH,SAAS,CAAC;IAAE,MAAM;IAAiB,MAAM;IAAQ,EAAE,GAAG,EAAE;GACzD;;AAGH,QAAO"}

package/dist/src/agent/memory/manager.d.ts

@@ -1,9 +1,31 @@
 import type { AgentTool } from '@earendil-works/pi-agent-core';
 import type { MemoryProvider, MemoryProviderInitOptions } from './provider.js';
+import type { MemoryDeleteRequest, MemoryListRequest, MemoryReadRequest, MemoryReadResult, MemorySearchRequest, MemorySearchResult, MemoryUpdateRequest, MemoryWriteRequest, MemoryWriteResult, MemoryRecord, MemorySignal, MemoryKind } from './types.js';
+export type MemorySearchStrategy = 'local-first' | 'external-first' | 'fanout' | 'local-only' | 'external-only';
+export type MemoryWriteStrategy = 'local-first' | 'external-first' | 'write-through' | 'local-only' | 'external-only';
+export interface MemoryRoutingOptions {
+    searchStrategy?: MemorySearchStrategy;
+    writeStrategy?: MemoryWriteStrategy;
+    replicateTo?: string[];
+}
+export interface MemoryManagerOptions extends MemoryRoutingOptions {
+    loadProviders?: () => Promise<MemoryProvider[]>;
+    writePolicy?: MemoryWritePolicy;
+}
+export interface MemoryWritePolicy {
+    allowExternalWrites?: boolean;
+    allowedProviderIds?: string[];
+    autoWriteKinds?: MemoryKind[];
+    requireUserProfileApproval?: boolean;
+}
 export declare class MemoryManager {
     private providers;
     private toolToProvider;
-    private hasExternal;
+    private readonly routing;
+    private readonly loadProviders?;
+    private readonly writePolicy;
+    private pluginProvidersLoaded;
+    constructor(options?: MemoryManagerOptions);
     addProvider(provider: MemoryProvider): void;
     get providersList(): MemoryProvider[];
     /**
@@ -21,7 +43,21 @@ export declare class MemoryManager {
     }): void;
     getAdditionalTools(): AgentTool[];
     handleToolCall(toolName: string, args: Record<string, unknown>): Promise<string>;
+    search(request: MemorySearchRequest): Promise<MemorySearchResult[]>;
+    read(request: MemoryReadRequest): Promise<MemoryReadResult | null>;
+    get(id: string): Promise<MemoryRecord | null>;
+    list(request: MemoryListRequest): Promise<MemoryRecord[]>;
+    write(request: MemoryWriteRequest): Promise<MemoryWriteResult>;
+    update(request: MemoryUpdateRequest): Promise<MemoryWriteResult>;
+    delete(request: MemoryDeleteRequest): Promise<MemoryWriteResult>;
     onMemoryWrite(action: 'add' | 'replace' | 'remove', target: 'memory' | 'user', content: string): void;
+    recordSignal(signal: MemorySignal): void;
     initializeAll(sessionId: string, options?: MemoryProviderInitOptions): Promise<void>;
+    private loadPluginProvidersOnce;
     shutdownAll(): Promise<void>;
+    private providersForSearch;
+    private providersForWrite;
+    private writeWithStrategy;
+    private providerAllowedForWrite;
+    private trace;
 }