@xopcai/xopc 0.0.140 → 0.0.142

package/dist/src/agent/memory/dreaming/rem-patterns.js

@@ -2,8 +2,10 @@ import { createLogger } from "../../../utils/logger/index.js";
 import { init_logger } from "../../../utils/logger.js";
 import { DREAMING_DIR_RELATIVE, DREAMS_MD_FILENAME, MS_PER_DAY } from "./constants.js";
 import { isoDay } from "./utils.js";
-import { bumpEntryPhaseSignal, loadDreamingStore, saveDreamingStore } from "./short-term-store.js";
+import { bumpEntryPhaseSignal, loadDreamingStore, saveDreamingStore, withDreamingStoreLock } from "./short-term-store.js";
+import { inferMemorySensitivity } from "../sensitivity.js";
 import "./last-run.js";
+import { activateRemInsight, remPatternKey } from "./promotion-lifecycle.js";
 import path from "node:path";
 import fs from "node:fs/promises";
 //#region src/agent/memory/dreaming/rem-patterns.ts
@@ -56,71 +58,89 @@ async function runRemPatterns(params) {
 		};
 	}
 	try {
-		const { store } = await loadDreamingStore({ dreamingRoot: params.dreamingRoot });
-		const cutoffMs = nowMs - cfg.lookbackDays * MS_PER_DAY;
-		const recentEntries = Object.values(store.entries ?? {}).filter((entry) => {
-			if (!entry || typeof entry !== "object") return false;
-			if (!entry.lastRecalledAt) return false;
-			const lastMs = Date.parse(entry.lastRecalledAt);
-			return Number.isFinite(lastMs) && lastMs >= cutoffMs;
-		});
-		if (recentEntries.length < 2) {
+		return await withDreamingStoreLock(params.dreamingRoot, async () => {
+			const { store } = await loadDreamingStore({ dreamingRoot: params.dreamingRoot });
+			const cutoffMs = nowMs - cfg.lookbackDays * MS_PER_DAY;
+			const recentEntries = Object.values(store.entries ?? {}).filter((entry) => {
+				if (!entry || typeof entry !== "object") return false;
+				if (!entry.lastRecalledAt) return false;
+				const lastMs = Date.parse(entry.lastRecalledAt);
+				return Number.isFinite(lastMs) && lastMs >= cutoffMs;
+			});
+			if (recentEntries.length < 2) {
+				await writeLastRun(params.dreamingRoot, {
+					runId,
+					startedAt,
+					cfg,
+					ok: true,
+					reason: "not enough recent entries for pattern analysis",
+					startMs,
+					rem: {
+						patternsDiscovered: 0,
+						entriesAnalyzed: recentEntries.length
+					}
+				});
+				return {
+					ok: true,
+					reason: "not enough recent entries for pattern analysis",
+					patternsDiscovered: 0,
+					entriesAnalyzed: recentEntries.length
+				};
+			}
+			const topClusters = discoverPatternClusters(recentEntries, cfg.minPatternStrength).filter((cluster) => {
+				return inferMemorySensitivity(cluster.members.map((member) => member.snippet).join("\n")) === "normal" || params.sensitiveWritePolicy === "allow";
+			}).slice(0, cfg.limit);
+			const touchedKeys = /* @__PURE__ */ new Set();
+			for (const cluster of topClusters) for (const member of cluster.members) if (!touchedKeys.has(member.key)) {
+				touchedKeys.add(member.key);
+				const storeEntry = store.entries[member.key];
+				if (storeEntry) bumpEntryPhaseSignal(storeEntry, "remHits");
+			}
+			store.updatedAt = now.toISOString();
+			await saveDreamingStore({
+				dreamingRoot: params.dreamingRoot,
+				store
+			});
+			if (params.promotionWritePolicy === "allow") for (const cluster of topClusters) {
+				const sensitivity = inferMemorySensitivity(cluster.members.map((member) => member.snippet).join("\n"));
+				activateRemInsight({
+					agentId: params.agentId,
+					workspaceId: params.workspaceDir,
+					memberKeys: cluster.members.map((member) => member.key),
+					representative: cluster.representative.snippet,
+					distinctPaths: cluster.distinctPaths,
+					strength: cluster.strength,
+					observedAt: now.toISOString(),
+					evidence: cluster.members.map((member) => member.snippet),
+					sensitivity
+				});
+			}
+			if (topClusters.length > 0) await appendPatternSummary(params.dreamingRoot, topClusters, now);
+			log.info({
+				dreamingRoot: params.dreamingRoot,
+				patterns: topClusters.length,
+				entriesAnalyzed: recentEntries.length,
+				touched: touchedKeys.size
+			}, "REM pattern discovery complete");
 			await writeLastRun(params.dreamingRoot, {
 				runId,
 				startedAt,
 				cfg,
 				ok: true,
-				reason: "not enough recent entries for pattern analysis",
+				reason: "REM patterns complete",
 				startMs,
 				rem: {
-					patternsDiscovered: 0,
+					patternsDiscovered: topClusters.length,
 					entriesAnalyzed: recentEntries.length
 				}
 			});
 			return {
 				ok: true,
-				reason: "not enough recent entries for pattern analysis",
-				patternsDiscovered: 0,
-				entriesAnalyzed: recentEntries.length
-			};
-		}
-		const topClusters = discoverPatternClusters(recentEntries, cfg.minPatternStrength).slice(0, cfg.limit);
-		const touchedKeys = /* @__PURE__ */ new Set();
-		for (const cluster of topClusters) for (const member of cluster.members) if (!touchedKeys.has(member.key)) {
-			touchedKeys.add(member.key);
-			const storeEntry = store.entries[member.key];
-			if (storeEntry) bumpEntryPhaseSignal(storeEntry, "remHits");
-		}
-		store.updatedAt = now.toISOString();
-		await saveDreamingStore({
-			dreamingRoot: params.dreamingRoot,
-			store
-		});
-		if (topClusters.length > 0) await appendPatternSummary(params.dreamingRoot, topClusters, now);
-		log.info({
-			dreamingRoot: params.dreamingRoot,
-			patterns: topClusters.length,
-			entriesAnalyzed: recentEntries.length,
-			touched: touchedKeys.size
-		}, "REM pattern discovery complete");
-		await writeLastRun(params.dreamingRoot, {
-			runId,
-			startedAt,
-			cfg,
-			ok: true,
-			reason: "REM patterns complete",
-			startMs,
-			rem: {
+				reason: "REM patterns complete",
 				patternsDiscovered: topClusters.length,
 				entriesAnalyzed: recentEntries.length
-			}
+			};
 		});
-		return {
-			ok: true,
-			reason: "REM patterns complete",
-			patternsDiscovered: topClusters.length,
-			entriesAnalyzed: recentEntries.length
-		};
 	} catch (err) {
 		const errorMessage = err instanceof Error ? err.message : String(err);
 		log.error({
@@ -238,11 +258,14 @@ async function appendPatternSummary(dreamingRoot, clusters, now) {
 	});
 	const day = isoDay(now);
 	const lines = [];
+	const newClusters = clusters.filter((cluster) => !existing.includes(`xopc-rem-pattern id="${remPatternKey(cluster.members.map((member) => member.key))}"`));
+	if (newClusters.length === 0) return;
 	if (existing.trim().length === 0) lines.push("# Dream Diary", "");
 	lines.push(`## REM Pattern Discovery — ${day}`, "");
 	lines.push(`*${now.toISOString()}*`, "");
-	for (let i = 0; i < clusters.length; i++) {
-		const cluster = clusters[i];
+	for (let i = 0; i < newClusters.length; i++) {
+		const cluster = newClusters[i];
+		lines.push(`<!-- xopc-rem-pattern id="${remPatternKey(cluster.members.map((member) => member.key))}" -->`);
 		lines.push(`### Pattern ${i + 1}: ${cluster.distinctPaths.length} files, strength=${cluster.strength.toFixed(2)}`);
 		lines.push("");
 		lines.push(`**Files involved:** ${cluster.distinctPaths.join(", ")}`);

package/dist/src/agent/memory/dreaming/rem-patterns.js.map

@@ -1 +1 @@
-{"version":3,"file":"rem-patterns.js","names":[],"sources":["../../../../../src/agent/memory/dreaming/rem-patterns.ts"],"sourcesContent":["import fs from 'node:fs/promises';\nimport path from 'node:path';\n\nimport { createLogger } from '../../../utils/logger.js';\nimport { DREAMING_DIR_RELATIVE, DREAMS_MD_FILENAME, MS_PER_DAY } from './constants.js';\nimport type { DreamingRemConfig } from './config.js';\nimport {\n  bumpEntryPhaseSignal,\n  loadDreamingStore,\n  saveDreamingStore,\n  type DreamingStoreEntry,\n} from './short-term-store.js';\nimport { isoDay } from './utils.js';\nimport {\n  DREAMING_LAST_RUN_FORMAT_VERSION,\n  type DreamingRemLastRun,\n} from './last-run.js';\n\nconst log = createLogger('Dreaming:REM');\n\n// ── Pattern types ──────────────────────────────────────────────────────\n\ntype PatternCluster = {\n  representative: DreamingStoreEntry;\n  members: DreamingStoreEntry[];\n  strength: number;\n  /** Shared query hashes across members. */\n  sharedQueries: string[];\n  /** Distinct source files involved. */\n  distinctPaths: string[];\n};\n\n// ── Config defaults ────────────────────────────────────────────────────\n\nfunction resolveConfig(overrides?: Partial<DreamingRemConfig>): DreamingRemConfig {\n  return {\n    enabled: overrides?.enabled === true,\n    cron: typeof overrides?.cron === 'string' ? overrides.cron : '0 5 * * 0',\n    lookbackDays: Math.max(1, Math.floor(Number(overrides?.lookbackDays) || 7)),\n    limit: Math.max(0, Math.floor(Number(overrides?.limit) || 10)),\n    minPatternStrength: Math.max(0, Math.min(1, Number(overrides?.minPatternStrength) || 0.75)),\n  };\n}\n\n// ── Core REM pattern discovery ─────────────────────────────────────────\n\n/**\n * REM phase: cross-session pattern discovery.\n *\n * Scans the short-term store for entries that share query hashes or\n * appear across multiple indexed memory sources, then clusters them to identify\n * recurring themes/patterns. Bumps `remHits` on touched entries and\n * optionally writes a pattern summary to DREAMS.md.\n *\n * Runs weekly; expensive but insightful.\n */\nexport async function runRemPatterns(params: {\n  dreamingRoot: string;\n  config?: Partial<DreamingRemConfig>;\n  now?: Date;\n}): Promise<{\n  ok: boolean;\n  reason: string;\n  patternsDiscovered: number;\n  entriesAnalyzed: number;\n}> {\n  const cfg = resolveConfig(params.config);\n  const now = params.now ?? new Date();\n  const startedAt = now.toISOString();\n  const runId = `rem:${startedAt}:${process.pid}`;\n  const startMs = Date.now();\n  const nowMs = now.getTime();\n\n  if (!cfg.enabled) {\n    await writeLastRun(params.dreamingRoot, {\n      runId, startedAt, cfg, ok: true, reason: 'REM patterns disabled', startMs,\n      rem: { patternsDiscovered: 0, entriesAnalyzed: 0 },\n    });\n    return { ok: true, reason: 'REM patterns disabled', patternsDiscovered: 0, entriesAnalyzed: 0 };\n  }\n\n  try {\n    const { store } = await loadDreamingStore({ dreamingRoot: params.dreamingRoot });\n\n    // Filter entries within the lookback window.\n    const cutoffMs = nowMs - cfg.lookbackDays * MS_PER_DAY;\n    const recentEntries = Object.values(store.entries ?? {}).filter(\n      (entry): entry is DreamingStoreEntry => {\n        if (!entry || typeof entry !== 'object') return false;\n        if (!entry.lastRecalledAt) return false;\n        const lastMs = Date.parse(entry.lastRecalledAt);\n        return Number.isFinite(lastMs) && lastMs >= cutoffMs;\n      },\n    );\n\n    if (recentEntries.length < 2) {\n      await writeLastRun(params.dreamingRoot, {\n        runId, startedAt, cfg, ok: true, reason: 'not enough recent entries for pattern analysis', startMs,\n        rem: { patternsDiscovered: 0, entriesAnalyzed: recentEntries.length },\n      });\n      return {\n        ok: true,\n        reason: 'not enough recent entries for pattern analysis',\n        patternsDiscovered: 0,\n        entriesAnalyzed: recentEntries.length,\n      };\n    }\n\n    // Discover patterns by clustering entries that share query hashes.\n    const clusters = discoverPatternClusters(recentEntries, cfg.minPatternStrength);\n    const topClusters = clusters.slice(0, cfg.limit);\n\n    // Bump remHits on all entries that belong to a discovered pattern.\n    const touchedKeys = new Set<string>();\n    for (const cluster of topClusters) {\n      for (const member of cluster.members) {\n        if (!touchedKeys.has(member.key)) {\n          touchedKeys.add(member.key);\n          const storeEntry = store.entries[member.key];\n          if (storeEntry) {\n            bumpEntryPhaseSignal(storeEntry, 'remHits');\n          }\n        }\n      }\n    }\n\n    store.updatedAt = now.toISOString();\n    await saveDreamingStore({ dreamingRoot: params.dreamingRoot, store });\n\n    // Write pattern summary to DREAMS.md (append).\n    if (topClusters.length > 0) {\n      await appendPatternSummary(params.dreamingRoot, topClusters, now);\n    }\n\n    log.info(\n      {\n        dreamingRoot: params.dreamingRoot,\n        patterns: topClusters.length,\n        entriesAnalyzed: recentEntries.length,\n        touched: touchedKeys.size,\n      },\n      'REM pattern discovery complete',\n    );\n\n    await writeLastRun(params.dreamingRoot, {\n      runId, startedAt, cfg, ok: true, reason: 'REM patterns complete', startMs,\n      rem: { patternsDiscovered: topClusters.length, entriesAnalyzed: recentEntries.length },\n    });\n\n    return {\n      ok: true,\n      reason: 'REM patterns complete',\n      patternsDiscovered: topClusters.length,\n      entriesAnalyzed: recentEntries.length,\n    };\n  } catch (err) {\n    const errorMessage = err instanceof Error ? err.message : String(err);\n    log.error({ err, errorMessage, dreamingRoot: params.dreamingRoot }, `REM pattern discovery failed: ${errorMessage}`);\n    await writeLastRun(params.dreamingRoot, {\n      runId, startedAt, cfg, ok: false, reason: `REM error: ${errorMessage}`, startMs,\n      rem: { patternsDiscovered: 0, entriesAnalyzed: 0 }, errorMessage,\n    }).catch(() => undefined);\n    return { ok: false, reason: errorMessage, patternsDiscovered: 0, entriesAnalyzed: 0 };\n  }\n}\n\n// ── Pattern clustering ─────────────────────────────────────────────────\n\n/**\n * Build an inverted index of queryHash → entries, then form clusters\n * where multiple entries share overlapping query hashes. Each cluster's\n * \"strength\" is the ratio of shared queries to total unique queries.\n */\nfunction discoverPatternClusters(\n  entries: DreamingStoreEntry[],\n  minStrength: number,\n): PatternCluster[] {\n  // Build inverted index: queryHash → entry keys.\n  const hashToEntries = new Map<string, DreamingStoreEntry[]>();\n  for (const entry of entries) {\n    for (const queryHash of entry.queryHashes ?? []) {\n      const group = hashToEntries.get(queryHash);\n      if (group) {\n        group.push(entry);\n      } else {\n        hashToEntries.set(queryHash, [entry]);\n      }\n    }\n  }\n\n  // Find query hashes that appear in 2+ distinct entries from different paths.\n  const significantHashes: Array<{ hash: string; entries: DreamingStoreEntry[] }> = [];\n  for (const [hash, group] of hashToEntries) {\n    const uniquePaths = new Set(group.map((e) => e.path));\n    if (group.length >= 2 && uniquePaths.size >= 2) {\n      significantHashes.push({ hash, entries: group });\n    }\n  }\n\n  if (significantHashes.length === 0) return [];\n\n  // Merge overlapping groups into clusters using union-find.\n  const keyToCluster = new Map<string, Set<string>>();\n  const keyToEntry = new Map<string, DreamingStoreEntry>();\n\n  for (const entry of entries) {\n    keyToEntry.set(entry.key, entry);\n  }\n\n  for (const { entries: groupEntries } of significantHashes) {\n    const keys = groupEntries.map((e) => e.key);\n    // Find or create the cluster for the first key.\n    let mergedCluster = keyToCluster.get(keys[0]!);\n    if (!mergedCluster) {\n      mergedCluster = new Set<string>();\n      mergedCluster.add(keys[0]!);\n      keyToCluster.set(keys[0]!, mergedCluster);\n    }\n    // Merge all other keys into this cluster.\n    for (const key of keys.slice(1)) {\n      const existingCluster = keyToCluster.get(key);\n      if (existingCluster && existingCluster !== mergedCluster) {\n        for (const existingKey of existingCluster) {\n          mergedCluster.add(existingKey);\n          keyToCluster.set(existingKey, mergedCluster);\n        }\n      } else {\n        mergedCluster.add(key);\n        keyToCluster.set(key, mergedCluster);\n      }\n    }\n  }\n\n  // Deduplicate cluster sets.\n  const seenClusters = new Set<Set<string>>();\n  const rawClusters: Set<string>[] = [];\n  for (const cluster of keyToCluster.values()) {\n    if (!seenClusters.has(cluster) && cluster.size >= 2) {\n      seenClusters.add(cluster);\n      rawClusters.push(cluster);\n    }\n  }\n\n  // Score each cluster.\n  const scoredClusters: PatternCluster[] = [];\n  for (const clusterKeys of rawClusters) {\n    const members: DreamingStoreEntry[] = [];\n    for (const key of clusterKeys) {\n      const entry = keyToEntry.get(key);\n      if (entry) members.push(entry);\n    }\n    if (members.length < 2) continue;\n\n    // Shared queries: hashes that appear in 2+ members.\n    const hashCounts = new Map<string, number>();\n    for (const member of members) {\n      for (const hash of member.queryHashes ?? []) {\n        hashCounts.set(hash, (hashCounts.get(hash) ?? 0) + 1);\n      }\n    }\n    const sharedQueries = [...hashCounts.entries()]\n      .filter(([, count]) => count >= 2)\n      .map(([hash]) => hash);\n\n    const allUniqueHashes = new Set<string>();\n    for (const member of members) {\n      for (const hash of member.queryHashes ?? []) allUniqueHashes.add(hash);\n    }\n\n    const strength = allUniqueHashes.size > 0 ? sharedQueries.length / allUniqueHashes.size : 0;\n    if (strength < minStrength) continue;\n\n    const distinctPaths = [...new Set(members.map((m) => m.path))];\n\n    // Representative: the member with the highest totalSignalCount.\n    const representative = members.reduce((best, current) =>\n      (current.totalSignalCount ?? 0) > (best.totalSignalCount ?? 0) ? current : best,\n    );\n\n    scoredClusters.push({\n      representative,\n      members,\n      strength,\n      sharedQueries,\n      distinctPaths,\n    });\n  }\n\n  // Sort by strength descending, then by member count.\n  scoredClusters.sort((a, b) => {\n    if (b.strength !== a.strength) return b.strength - a.strength;\n    return b.members.length - a.members.length;\n  });\n\n  return scoredClusters;\n}\n\n// ── DREAMS.md writer ───────────────────────────────────────────────────\n\nasync function appendPatternSummary(\n  dreamingRoot: string,\n  clusters: PatternCluster[],\n  now: Date,\n): Promise<void> {\n  const dreamsPath = path.join(dreamingRoot, DREAMS_MD_FILENAME);\n  const existing = await fs.readFile(dreamsPath, 'utf-8').catch((err: unknown) => {\n    if ((err as NodeJS.ErrnoException)?.code === 'ENOENT') return '';\n    throw err;\n  });\n\n  const day = isoDay(now);\n  const lines: string[] = [];\n\n  if (existing.trim().length === 0) {\n    lines.push('# Dream Diary', '');\n  }\n\n  lines.push(`## REM Pattern Discovery — ${day}`, '');\n  lines.push(`*${now.toISOString()}*`, '');\n\n  for (let i = 0; i < clusters.length; i++) {\n    const cluster = clusters[i]!;\n    lines.push(\n      `### Pattern ${i + 1}: ${cluster.distinctPaths.length} files, strength=${cluster.strength.toFixed(2)}`,\n    );\n    lines.push('');\n    lines.push(`**Files involved:** ${cluster.distinctPaths.join(', ')}`);\n    lines.push(`**Shared query themes:** ${cluster.sharedQueries.length} overlapping queries`);\n    lines.push(`**Members:** ${cluster.members.length} snippets`);\n    lines.push('');\n    // Include the representative snippet.\n    const rep = cluster.representative;\n    lines.push(`> ${rep.snippet?.slice(0, 200) ?? '(no snippet)'}`);\n    lines.push(`> — ${rep.path}:${rep.startLine}-${rep.endLine}`);\n    lines.push('');\n  }\n\n  lines.push('---', '');\n\n  const separator = existing.trim().length > 0 && !existing.endsWith('\\n') ? '\\n' : '';\n  const next = `${existing}${separator}${lines.join('\\n')}`;\n  await fs.writeFile(dreamsPath, next, 'utf-8');\n}\n\n// ── Last-run writer ────────────────────────────────────────────────────\n\nasync function writeLastRun(\n  dreamingRoot: string,\n  params: {\n    runId: string;\n    startedAt: string;\n    cfg: DreamingRemConfig;\n    ok: boolean;\n    reason: string;\n    startMs: number;\n    rem: DreamingRemLastRun['rem'];\n    errorMessage?: string;\n  },\n): Promise<void> {\n  const finishedAt = new Date().toISOString();\n  const durationMs = Math.max(0, Date.now() - params.startMs);\n\n  const lastRun: DreamingRemLastRun = {\n    version: DREAMING_LAST_RUN_FORMAT_VERSION,\n    phase: 'rem',\n    runId: params.runId,\n    startedAt: params.startedAt,\n    finishedAt,\n    durationMs,\n    ok: params.ok,\n    reason: params.reason,\n    config: params.cfg,\n    rem: params.rem,\n    ...(params.errorMessage ? { errorMessage: params.errorMessage } : {}),\n  };\n\n  const lastRunPath = path.join(dreamingRoot, DREAMING_DIR_RELATIVE, 'last-run-rem.json');\n  await fs.mkdir(path.dirname(lastRunPath), { recursive: true });\n  const tmp = `${lastRunPath}.${process.pid}.${Date.now()}.tmp`;\n  await fs.writeFile(tmp, `${JSON.stringify(lastRun, null, 2)}\\n`, 'utf-8');\n  await fs.rename(tmp, lastRunPath);\n}\n"],"mappings":"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"}
+{"version":3,"file":"rem-patterns.js","names":[],"sources":["../../../../../src/agent/memory/dreaming/rem-patterns.ts"],"sourcesContent":["import fs from 'node:fs/promises';\nimport path from 'node:path';\n\nimport { createLogger } from '../../../utils/logger.js';\nimport { DREAMING_DIR_RELATIVE, DREAMS_MD_FILENAME, MS_PER_DAY } from './constants.js';\nimport type { DreamingRemConfig } from './config.js';\nimport {\n  bumpEntryPhaseSignal,\n  loadDreamingStore,\n  saveDreamingStore,\n  withDreamingStoreLock,\n  type DreamingStoreEntry,\n} from './short-term-store.js';\nimport { isoDay } from './utils.js';\nimport { inferMemorySensitivity } from '../sensitivity.js';\nimport { activateRemInsight, remPatternKey } from './promotion-lifecycle.js';\nimport {\n  DREAMING_LAST_RUN_FORMAT_VERSION,\n  type DreamingRemLastRun,\n} from './last-run.js';\n\nconst log = createLogger('Dreaming:REM');\n\n// ── Pattern types ──────────────────────────────────────────────────────\n\ntype PatternCluster = {\n  representative: DreamingStoreEntry;\n  members: DreamingStoreEntry[];\n  strength: number;\n  /** Shared query hashes across members. */\n  sharedQueries: string[];\n  /** Distinct source files involved. */\n  distinctPaths: string[];\n};\n\n// ── Config defaults ────────────────────────────────────────────────────\n\nfunction resolveConfig(overrides?: Partial<DreamingRemConfig>): DreamingRemConfig {\n  return {\n    enabled: overrides?.enabled === true,\n    cron: typeof overrides?.cron === 'string' ? overrides.cron : '0 5 * * 0',\n    lookbackDays: Math.max(1, Math.floor(Number(overrides?.lookbackDays) || 7)),\n    limit: Math.max(0, Math.floor(Number(overrides?.limit) || 10)),\n    minPatternStrength: Math.max(0, Math.min(1, Number(overrides?.minPatternStrength) || 0.75)),\n  };\n}\n\n// ── Core REM pattern discovery ─────────────────────────────────────────\n\n/**\n * REM phase: cross-session pattern discovery.\n *\n * Scans the short-term store for entries that share query hashes or\n * appear across multiple indexed memory sources, then clusters them to identify\n * recurring themes/patterns. Bumps `remHits` on touched entries and\n * optionally writes a pattern summary to DREAMS.md.\n *\n * Runs weekly; expensive but insightful.\n */\nexport async function runRemPatterns(params: {\n  agentId: string;\n  workspaceDir: string;\n  dreamingRoot: string;\n  config?: Partial<DreamingRemConfig>;\n  sensitiveWritePolicy?: 'deny' | 'confirm' | 'allow';\n  promotionWritePolicy?: 'deny' | 'confirm' | 'allow';\n  now?: Date;\n}): Promise<{\n  ok: boolean;\n  reason: string;\n  patternsDiscovered: number;\n  entriesAnalyzed: number;\n}> {\n  const cfg = resolveConfig(params.config);\n  const now = params.now ?? new Date();\n  const startedAt = now.toISOString();\n  const runId = `rem:${startedAt}:${process.pid}`;\n  const startMs = Date.now();\n  const nowMs = now.getTime();\n\n  if (!cfg.enabled) {\n    await writeLastRun(params.dreamingRoot, {\n      runId, startedAt, cfg, ok: true, reason: 'REM patterns disabled', startMs,\n      rem: { patternsDiscovered: 0, entriesAnalyzed: 0 },\n    });\n    return { ok: true, reason: 'REM patterns disabled', patternsDiscovered: 0, entriesAnalyzed: 0 };\n  }\n\n  try {\n    return await withDreamingStoreLock(params.dreamingRoot, async () => {\n    const { store } = await loadDreamingStore({ dreamingRoot: params.dreamingRoot });\n\n    // Filter entries within the lookback window.\n    const cutoffMs = nowMs - cfg.lookbackDays * MS_PER_DAY;\n    const recentEntries = Object.values(store.entries ?? {}).filter(\n      (entry): entry is DreamingStoreEntry => {\n        if (!entry || typeof entry !== 'object') return false;\n        if (!entry.lastRecalledAt) return false;\n        const lastMs = Date.parse(entry.lastRecalledAt);\n        return Number.isFinite(lastMs) && lastMs >= cutoffMs;\n      },\n    );\n\n    if (recentEntries.length < 2) {\n      await writeLastRun(params.dreamingRoot, {\n        runId, startedAt, cfg, ok: true, reason: 'not enough recent entries for pattern analysis', startMs,\n        rem: { patternsDiscovered: 0, entriesAnalyzed: recentEntries.length },\n      });\n      return {\n        ok: true,\n        reason: 'not enough recent entries for pattern analysis',\n        patternsDiscovered: 0,\n        entriesAnalyzed: recentEntries.length,\n      };\n    }\n\n    // Discover patterns by clustering entries that share query hashes.\n    const clusters = discoverPatternClusters(recentEntries, cfg.minPatternStrength);\n    const topClusters = clusters\n      .filter((cluster) => {\n        const sensitivity = inferMemorySensitivity(cluster.members.map((member) => member.snippet).join('\\n'));\n        return sensitivity === 'normal' || params.sensitiveWritePolicy === 'allow';\n      })\n      .slice(0, cfg.limit);\n\n    // Bump remHits on all entries that belong to a discovered pattern.\n    const touchedKeys = new Set<string>();\n    for (const cluster of topClusters) {\n      for (const member of cluster.members) {\n        if (!touchedKeys.has(member.key)) {\n          touchedKeys.add(member.key);\n          const storeEntry = store.entries[member.key];\n          if (storeEntry) {\n            bumpEntryPhaseSignal(storeEntry, 'remHits');\n          }\n        }\n      }\n    }\n\n    store.updatedAt = now.toISOString();\n    await saveDreamingStore({ dreamingRoot: params.dreamingRoot, store });\n\n    if (params.promotionWritePolicy === 'allow') {\n      for (const cluster of topClusters) {\n        const sensitivity = inferMemorySensitivity(cluster.members.map((member) => member.snippet).join('\\n'));\n        activateRemInsight({\n          agentId: params.agentId,\n          workspaceId: params.workspaceDir,\n          memberKeys: cluster.members.map((member) => member.key),\n          representative: cluster.representative.snippet,\n          distinctPaths: cluster.distinctPaths,\n          strength: cluster.strength,\n          observedAt: now.toISOString(),\n          evidence: cluster.members.map((member) => member.snippet),\n          sensitivity,\n        });\n      }\n    }\n\n    // Write pattern summary to DREAMS.md (append).\n    if (topClusters.length > 0) {\n      await appendPatternSummary(params.dreamingRoot, topClusters, now);\n    }\n\n    log.info(\n      {\n        dreamingRoot: params.dreamingRoot,\n        patterns: topClusters.length,\n        entriesAnalyzed: recentEntries.length,\n        touched: touchedKeys.size,\n      },\n      'REM pattern discovery complete',\n    );\n\n    await writeLastRun(params.dreamingRoot, {\n      runId, startedAt, cfg, ok: true, reason: 'REM patterns complete', startMs,\n      rem: { patternsDiscovered: topClusters.length, entriesAnalyzed: recentEntries.length },\n    });\n\n    return {\n      ok: true,\n      reason: 'REM patterns complete',\n      patternsDiscovered: topClusters.length,\n      entriesAnalyzed: recentEntries.length,\n    };\n    });\n  } catch (err) {\n    const errorMessage = err instanceof Error ? err.message : String(err);\n    log.error({ err, errorMessage, dreamingRoot: params.dreamingRoot }, `REM pattern discovery failed: ${errorMessage}`);\n    await writeLastRun(params.dreamingRoot, {\n      runId, startedAt, cfg, ok: false, reason: `REM error: ${errorMessage}`, startMs,\n      rem: { patternsDiscovered: 0, entriesAnalyzed: 0 }, errorMessage,\n    }).catch(() => undefined);\n    return { ok: false, reason: errorMessage, patternsDiscovered: 0, entriesAnalyzed: 0 };\n  }\n}\n\n// ── Pattern clustering ─────────────────────────────────────────────────\n\n/**\n * Build an inverted index of queryHash → entries, then form clusters\n * where multiple entries share overlapping query hashes. Each cluster's\n * \"strength\" is the ratio of shared queries to total unique queries.\n */\nfunction discoverPatternClusters(\n  entries: DreamingStoreEntry[],\n  minStrength: number,\n): PatternCluster[] {\n  // Build inverted index: queryHash → entry keys.\n  const hashToEntries = new Map<string, DreamingStoreEntry[]>();\n  for (const entry of entries) {\n    for (const queryHash of entry.queryHashes ?? []) {\n      const group = hashToEntries.get(queryHash);\n      if (group) {\n        group.push(entry);\n      } else {\n        hashToEntries.set(queryHash, [entry]);\n      }\n    }\n  }\n\n  // Find query hashes that appear in 2+ distinct entries from different paths.\n  const significantHashes: Array<{ hash: string; entries: DreamingStoreEntry[] }> = [];\n  for (const [hash, group] of hashToEntries) {\n    const uniquePaths = new Set(group.map((e) => e.path));\n    if (group.length >= 2 && uniquePaths.size >= 2) {\n      significantHashes.push({ hash, entries: group });\n    }\n  }\n\n  if (significantHashes.length === 0) return [];\n\n  // Merge overlapping groups into clusters using union-find.\n  const keyToCluster = new Map<string, Set<string>>();\n  const keyToEntry = new Map<string, DreamingStoreEntry>();\n\n  for (const entry of entries) {\n    keyToEntry.set(entry.key, entry);\n  }\n\n  for (const { entries: groupEntries } of significantHashes) {\n    const keys = groupEntries.map((e) => e.key);\n    // Find or create the cluster for the first key.\n    let mergedCluster = keyToCluster.get(keys[0]!);\n    if (!mergedCluster) {\n      mergedCluster = new Set<string>();\n      mergedCluster.add(keys[0]!);\n      keyToCluster.set(keys[0]!, mergedCluster);\n    }\n    // Merge all other keys into this cluster.\n    for (const key of keys.slice(1)) {\n      const existingCluster = keyToCluster.get(key);\n      if (existingCluster && existingCluster !== mergedCluster) {\n        for (const existingKey of existingCluster) {\n          mergedCluster.add(existingKey);\n          keyToCluster.set(existingKey, mergedCluster);\n        }\n      } else {\n        mergedCluster.add(key);\n        keyToCluster.set(key, mergedCluster);\n      }\n    }\n  }\n\n  // Deduplicate cluster sets.\n  const seenClusters = new Set<Set<string>>();\n  const rawClusters: Set<string>[] = [];\n  for (const cluster of keyToCluster.values()) {\n    if (!seenClusters.has(cluster) && cluster.size >= 2) {\n      seenClusters.add(cluster);\n      rawClusters.push(cluster);\n    }\n  }\n\n  // Score each cluster.\n  const scoredClusters: PatternCluster[] = [];\n  for (const clusterKeys of rawClusters) {\n    const members: DreamingStoreEntry[] = [];\n    for (const key of clusterKeys) {\n      const entry = keyToEntry.get(key);\n      if (entry) members.push(entry);\n    }\n    if (members.length < 2) continue;\n\n    // Shared queries: hashes that appear in 2+ members.\n    const hashCounts = new Map<string, number>();\n    for (const member of members) {\n      for (const hash of member.queryHashes ?? []) {\n        hashCounts.set(hash, (hashCounts.get(hash) ?? 0) + 1);\n      }\n    }\n    const sharedQueries = [...hashCounts.entries()]\n      .filter(([, count]) => count >= 2)\n      .map(([hash]) => hash);\n\n    const allUniqueHashes = new Set<string>();\n    for (const member of members) {\n      for (const hash of member.queryHashes ?? []) allUniqueHashes.add(hash);\n    }\n\n    const strength = allUniqueHashes.size > 0 ? sharedQueries.length / allUniqueHashes.size : 0;\n    if (strength < minStrength) continue;\n\n    const distinctPaths = [...new Set(members.map((m) => m.path))];\n\n    // Representative: the member with the highest totalSignalCount.\n    const representative = members.reduce((best, current) =>\n      (current.totalSignalCount ?? 0) > (best.totalSignalCount ?? 0) ? current : best,\n    );\n\n    scoredClusters.push({\n      representative,\n      members,\n      strength,\n      sharedQueries,\n      distinctPaths,\n    });\n  }\n\n  // Sort by strength descending, then by member count.\n  scoredClusters.sort((a, b) => {\n    if (b.strength !== a.strength) return b.strength - a.strength;\n    return b.members.length - a.members.length;\n  });\n\n  return scoredClusters;\n}\n\n// ── DREAMS.md writer ───────────────────────────────────────────────────\n\nasync function appendPatternSummary(\n  dreamingRoot: string,\n  clusters: PatternCluster[],\n  now: Date,\n): Promise<void> {\n  const dreamsPath = path.join(dreamingRoot, DREAMS_MD_FILENAME);\n  const existing = await fs.readFile(dreamsPath, 'utf-8').catch((err: unknown) => {\n    if ((err as NodeJS.ErrnoException)?.code === 'ENOENT') return '';\n    throw err;\n  });\n\n  const day = isoDay(now);\n  const lines: string[] = [];\n  const newClusters = clusters.filter((cluster) =>\n    !existing.includes(`xopc-rem-pattern id=\"${remPatternKey(cluster.members.map((member) => member.key))}\"`),\n  );\n  if (newClusters.length === 0) return;\n\n  if (existing.trim().length === 0) {\n    lines.push('# Dream Diary', '');\n  }\n\n  lines.push(`## REM Pattern Discovery — ${day}`, '');\n  lines.push(`*${now.toISOString()}*`, '');\n\n  for (let i = 0; i < newClusters.length; i++) {\n    const cluster = newClusters[i]!;\n    lines.push(`<!-- xopc-rem-pattern id=\"${remPatternKey(cluster.members.map((member) => member.key))}\" -->`);\n    lines.push(\n      `### Pattern ${i + 1}: ${cluster.distinctPaths.length} files, strength=${cluster.strength.toFixed(2)}`,\n    );\n    lines.push('');\n    lines.push(`**Files involved:** ${cluster.distinctPaths.join(', ')}`);\n    lines.push(`**Shared query themes:** ${cluster.sharedQueries.length} overlapping queries`);\n    lines.push(`**Members:** ${cluster.members.length} snippets`);\n    lines.push('');\n    // Include the representative snippet.\n    const rep = cluster.representative;\n    lines.push(`> ${rep.snippet?.slice(0, 200) ?? '(no snippet)'}`);\n    lines.push(`> — ${rep.path}:${rep.startLine}-${rep.endLine}`);\n    lines.push('');\n  }\n\n  lines.push('---', '');\n\n  const separator = existing.trim().length > 0 && !existing.endsWith('\\n') ? '\\n' : '';\n  const next = `${existing}${separator}${lines.join('\\n')}`;\n  await fs.writeFile(dreamsPath, next, 'utf-8');\n}\n\n// ── Last-run writer ────────────────────────────────────────────────────\n\nasync function writeLastRun(\n  dreamingRoot: string,\n  params: {\n    runId: string;\n    startedAt: string;\n    cfg: DreamingRemConfig;\n    ok: boolean;\n    reason: string;\n    startMs: number;\n    rem: DreamingRemLastRun['rem'];\n    errorMessage?: string;\n  },\n): Promise<void> {\n  const finishedAt = new Date().toISOString();\n  const durationMs = Math.max(0, Date.now() - params.startMs);\n\n  const lastRun: DreamingRemLastRun = {\n    version: DREAMING_LAST_RUN_FORMAT_VERSION,\n    phase: 'rem',\n    runId: params.runId,\n    startedAt: params.startedAt,\n    finishedAt,\n    durationMs,\n    ok: params.ok,\n    reason: params.reason,\n    config: params.cfg,\n    rem: params.rem,\n    ...(params.errorMessage ? { errorMessage: params.errorMessage } : {}),\n  };\n\n  const lastRunPath = path.join(dreamingRoot, DREAMING_DIR_RELATIVE, 'last-run-rem.json');\n  await fs.mkdir(path.dirname(lastRunPath), { recursive: true });\n  const tmp = `${lastRunPath}.${process.pid}.${Date.now()}.tmp`;\n  await fs.writeFile(tmp, `${JSON.stringify(lastRun, null, 2)}\\n`, 'utf-8');\n  await fs.rename(tmp, lastRunPath);\n}\n"],"mappings":"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"}

package/dist/src/agent/memory/dreaming/short-term-store.d.ts

@@ -25,6 +25,7 @@ export type DreamingStoreEntry = {
     recallDays: string[];
     firstRecalledAt: string;
     lastRecalledAt: string;
+    lastObservedAt?: string;
     promotedAt?: string;
 };
 export type DreamingStore = {
@@ -44,6 +45,9 @@ export declare function recordDreamingRecalls(params: {
     skipped: number;
     storePath: string;
 }>;
+/** Serialize all read-modify-write operations against the shared Dreaming store. */
+export declare function withDreamingStoreLock<T>(dreamingRoot: string, task: () => Promise<T>): Promise<T>;
+/** @deprecated Use the store-level name; retained for callers outside this module. */
 export declare function withDreamingPromotionLock<T>(dreamingRoot: string, task: () => Promise<T>): Promise<T>;
 export declare function loadDreamingStore(params: {
     dreamingRoot: string;
@@ -55,6 +59,12 @@ export declare function saveDreamingStore(params: {
     dreamingRoot: string;
     store: DreamingStore;
 }): Promise<void>;
+export declare function resetDreamingStore(params: {
+    dreamingRoot: string;
+    now?: Date;
+}): Promise<number>;
+/** Remove only a stale lock whose owning process is no longer alive. */
+export declare function clearStaleDreamingLock(dreamingRoot: string): Promise<boolean>;
 type PhaseSignalField = 'sourceCount' | 'groundedCount' | 'lightHits' | 'remHits';
 /**
  * Increment a phase-specific signal counter on an existing store entry.

package/dist/src/agent/memory/dreaming/short-term-store.js

@@ -8,6 +8,10 @@ import fs from "node:fs/promises";
 //#region src/agent/memory/dreaming/short-term-store.ts
 init_logger();
 const log = createLogger("Dreaming:Store");
+const STORE_MAX_ENTRIES = 2e3;
+const STORE_MAX_AGE_MS = 2160 * 60 * 60 * 1e3;
+const PROMOTED_MAX_AGE_MS = 720 * 60 * 60 * 1e3;
+const LOCK_STALE_MS = 6e4;
 function isRecordableMemoryPath(rel) {
 	const p = normalizeMemoryPath(rel);
 	return p.length > 0 && !p.startsWith("../") && !path.isAbsolute(p);
@@ -41,9 +45,9 @@ async function readStore(dreamingRoot, nowIso) {
 	try {
 		const raw = await fs.readFile(storePath, "utf-8");
 		const parsed = JSON.parse(raw);
-		if (!parsed || typeof parsed !== "object") return emptyStore(nowIso);
+		if (!parsed || typeof parsed !== "object") throw new Error("Dreaming store root must be an object");
 		const rec = parsed;
-		if (rec.version !== 1 || !rec.entries || typeof rec.entries !== "object") return emptyStore(nowIso);
+		if (rec.version !== 1 || !rec.entries || typeof rec.entries !== "object") throw new Error("Dreaming store has an unsupported or invalid shape");
 		return {
 			version: 1,
 			updatedAt: typeof rec.updatedAt === "string" ? rec.updatedAt : nowIso,
@@ -51,14 +55,35 @@ async function readStore(dreamingRoot, nowIso) {
 		};
 	} catch (err) {
 		if (err?.code === "ENOENT") return emptyStore(nowIso);
+		const quarantinePath = `${storePath}.corrupt-${Date.now()}`;
+		await fs.rename(storePath, quarantinePath).catch(() => void 0);
 		log.warn({
 			err,
-			dreamingRoot
-		}, "Failed to read dreaming store; resetting");
+			dreamingRoot,
+			quarantinePath
+		}, "Failed to read dreaming store; quarantined corrupt data");
 		return emptyStore(nowIso);
 	}
 }
+function pruneStore(store, nowMs = Date.now()) {
+	for (const [key, entry] of Object.entries(store.entries)) {
+		const lastSeenMs = Math.max(Date.parse(entry.lastRecalledAt || entry.firstRecalledAt), entry.lastObservedAt ? Date.parse(entry.lastObservedAt) : 0);
+		const promotedMs = entry.promotedAt ? Date.parse(entry.promotedAt) : NaN;
+		if (Number.isFinite(promotedMs) && nowMs - promotedMs > PROMOTED_MAX_AGE_MS || Number.isFinite(lastSeenMs) && nowMs - lastSeenMs > STORE_MAX_AGE_MS) delete store.entries[key];
+	}
+	const entries = Object.values(store.entries);
+	if (entries.length <= STORE_MAX_ENTRIES) return;
+	entries.sort((left, right) => {
+		if (Boolean(left.promotedAt) !== Boolean(right.promotedAt)) return left.promotedAt ? 1 : -1;
+		const signalDelta = (right.totalSignalCount ?? 0) - (left.totalSignalCount ?? 0);
+		if (signalDelta !== 0) return signalDelta;
+		return Date.parse(right.lastRecalledAt) - Date.parse(left.lastRecalledAt);
+	});
+	const keep = new Set(entries.slice(0, STORE_MAX_ENTRIES).map((entry) => entry.key));
+	for (const key of Object.keys(store.entries)) if (!keep.has(key)) delete store.entries[key];
+}
 async function writeStore(dreamingRoot, store) {
+	pruneStore(store);
 	await ensureDreamDir(dreamingRoot);
 	const storePath = path.join(dreamingRoot, SHORT_TERM_RECALL_STORE_RELATIVE);
 	const tmp = `${storePath}.${process.pid}.${Date.now()}.${randomUUID()}.tmp`;
@@ -73,84 +98,87 @@ async function recordDreamingRecalls(params) {
 		skipped: params.matches.length,
 		storePath: SHORT_TERM_RECALL_STORE_RELATIVE
 	};
-	const now = params.now ?? /* @__PURE__ */ new Date();
-	const nowIso = now.toISOString();
-	const dayBucket = isoDay(now);
-	const qHash = hashQuery(query);
-	const store = await readStore(dreamingRoot, nowIso);
-	let recorded = 0;
-	let skipped = 0;
-	for (const match of params.matches) {
-		const file = typeof match?.file === "string" ? match.file : "";
-		if (!file || !isRecordableMemoryPath(file)) {
-			skipped += 1;
-			continue;
+	return withDreamingStoreLock(dreamingRoot, async () => {
+		const now = params.now ?? /* @__PURE__ */ new Date();
+		const nowIso = now.toISOString();
+		const dayBucket = isoDay(now);
+		const qHash = hashQuery(query);
+		const store = await readStore(dreamingRoot, nowIso);
+		let recorded = 0;
+		let skipped = 0;
+		for (const match of params.matches) {
+			const file = typeof match?.file === "string" ? match.file : "";
+			if (!file || !isRecordableMemoryPath(file)) {
+				skipped += 1;
+				continue;
+			}
+			const lines = typeof match?.lines === "string" ? match.lines.trim() : "";
+			const lineNumbers = Array.isArray(match?.lineNumbers) ? match.lineNumbers : [];
+			const startLine = Math.max(1, Math.min(...lineNumbers.filter((n) => Number.isFinite(n) && n > 0)));
+			const endLine = Math.max(startLine, Math.max(...lineNumbers.filter((n) => Number.isFinite(n) && n > 0)));
+			if (!Number.isFinite(startLine) || !Number.isFinite(endLine)) {
+				skipped += 1;
+				continue;
+			}
+			const score = clamp01(Number(match.score));
+			const key = buildEntryKey({
+				path: file,
+				startLine,
+				endLine
+			});
+			const existing = store.entries[key];
+			const snippet = lines.length > 0 ? lines.slice(0, 360) : file;
+			const next = existing ? {
+				...existing,
+				snippet,
+				recallCount: Math.max(0, Math.floor(existing.recallCount + 1)),
+				sourceCount: existing.sourceCount ?? 0,
+				groundedCount: existing.groundedCount ?? 0,
+				lightHits: existing.lightHits ?? 0,
+				remHits: existing.remHits ?? 0,
+				phaseHitCount: existing.phaseHitCount ?? 0,
+				totalSignalCount: Math.max(0, (existing.totalSignalCount ?? existing.recallCount ?? 0) + 1),
+				totalScore: Math.max(0, existing.totalScore + score),
+				maxScore: Math.max(existing.maxScore, score),
+				queryHashes: mergeQueryHashes(existing.queryHashes ?? [], qHash),
+				recallDays: mergeRecentDistinct(existing.recallDays ?? [], dayBucket, 16),
+				lastRecalledAt: nowIso
+			} : {
+				key,
+				path: normalizeMemoryPath(file),
+				startLine,
+				endLine,
+				snippet,
+				recallCount: 1,
+				sourceCount: 0,
+				groundedCount: 0,
+				lightHits: 0,
+				remHits: 0,
+				phaseHitCount: 0,
+				totalSignalCount: 1,
+				totalScore: score,
+				maxScore: score,
+				queryHashes: [qHash],
+				recallDays: [dayBucket],
+				firstRecalledAt: nowIso,
+				lastRecalledAt: nowIso
+			};
+			store.entries[key] = next;
+			recorded += 1;
 		}
-		const lines = typeof match?.lines === "string" ? match.lines.trim() : "";
-		const lineNumbers = Array.isArray(match?.lineNumbers) ? match.lineNumbers : [];
-		const startLine = Math.max(1, Math.min(...lineNumbers.filter((n) => Number.isFinite(n) && n > 0)));
-		const endLine = Math.max(startLine, Math.max(...lineNumbers.filter((n) => Number.isFinite(n) && n > 0)));
-		if (!Number.isFinite(startLine) || !Number.isFinite(endLine)) {
-			skipped += 1;
-			continue;
+		if (recorded > 0) {
+			store.updatedAt = nowIso;
+			await writeStore(dreamingRoot, store);
 		}
-		const score = clamp01(Number(match.score));
-		const key = buildEntryKey({
-			path: file,
-			startLine,
-			endLine
-		});
-		const existing = store.entries[key];
-		const snippet = lines.length > 0 ? lines.slice(0, 360) : file;
-		const next = existing ? {
-			...existing,
-			snippet,
-			recallCount: Math.max(0, Math.floor(existing.recallCount + 1)),
-			sourceCount: existing.sourceCount ?? 0,
-			groundedCount: existing.groundedCount ?? 0,
-			lightHits: existing.lightHits ?? 0,
-			remHits: existing.remHits ?? 0,
-			phaseHitCount: existing.phaseHitCount ?? 0,
-			totalSignalCount: Math.max(0, (existing.totalSignalCount ?? existing.recallCount ?? 0) + 1),
-			totalScore: Math.max(0, existing.totalScore + score),
-			maxScore: Math.max(existing.maxScore, score),
-			queryHashes: mergeQueryHashes(existing.queryHashes ?? [], qHash),
-			recallDays: mergeRecentDistinct(existing.recallDays ?? [], dayBucket, 16),
-			lastRecalledAt: nowIso
-		} : {
-			key,
-			path: normalizeMemoryPath(file),
-			startLine,
-			endLine,
-			snippet,
-			recallCount: 1,
-			sourceCount: 0,
-			groundedCount: 0,
-			lightHits: 0,
-			remHits: 0,
-			phaseHitCount: 0,
-			totalSignalCount: 1,
-			totalScore: score,
-			maxScore: score,
-			queryHashes: [qHash],
-			recallDays: [dayBucket],
-			firstRecalledAt: nowIso,
-			lastRecalledAt: nowIso
+		return {
+			recorded,
+			skipped,
+			storePath: SHORT_TERM_RECALL_STORE_RELATIVE
 		};
-		store.entries[key] = next;
-		recorded += 1;
-	}
-	if (recorded > 0) {
-		store.updatedAt = nowIso;
-		await writeStore(dreamingRoot, store);
-	}
-	return {
-		recorded,
-		skipped,
-		storePath: SHORT_TERM_RECALL_STORE_RELATIVE
-	};
+	});
 }
-async function withDreamingPromotionLock(dreamingRoot, task) {
+/** Serialize all read-modify-write operations against the shared Dreaming store. */
+async function withDreamingStoreLock(dreamingRoot, task) {
 	const lockPath = path.join(dreamingRoot, SHORT_TERM_PROMOTION_LOCK_RELATIVE);
 	await ensureDreamDir(dreamingRoot);
 	const startedAt = Date.now();
@@ -167,10 +195,34 @@ async function withDreamingPromotionLock(dreamingRoot, task) {
 		}
 	} catch (err) {
 		if (err?.code !== "EEXIST") throw err;
+		const lockStat = await fs.stat(lockPath).catch(() => null);
+		if (lockStat && Date.now() - lockStat.mtimeMs > LOCK_STALE_MS && await lockOwnerIsDead(lockPath)) {
+			await fs.unlink(lockPath).catch(() => void 0);
+			log.warn({
+				lockPath,
+				ageMs: Date.now() - lockStat.mtimeMs
+			}, "Removed stale dreaming lock");
+			continue;
+		}
 		if (Date.now() - startedAt >= timeoutMs) throw new Error(`Timed out waiting for dreaming promotion lock at ${lockPath}`);
 		await new Promise((r) => setTimeout(r, retryDelayMs));
 	}
 }
+/** @deprecated Use the store-level name; retained for callers outside this module. */
+async function withDreamingPromotionLock(dreamingRoot, task) {
+	return withDreamingStoreLock(dreamingRoot, task);
+}
+async function lockOwnerIsDead(lockPath) {
+	const raw = await fs.readFile(lockPath, "utf-8").catch(() => "");
+	const pid = Number.parseInt(raw.split(":", 1)[0] ?? "", 10);
+	if (!Number.isFinite(pid) || pid <= 0) return true;
+	try {
+		process.kill(pid, 0);
+		return false;
+	} catch (error) {
+		return error?.code === "ESRCH";
+	}
+}
 async function loadDreamingStore(params) {
 	const nowIso = (/* @__PURE__ */ new Date()).toISOString();
 	return {
@@ -181,6 +233,32 @@ async function loadDreamingStore(params) {
 async function saveDreamingStore(params) {
 	await writeStore(params.dreamingRoot, params.store);
 }
+async function resetDreamingStore(params) {
+	return withDreamingStoreLock(params.dreamingRoot, async () => {
+		const nowIso = (params.now ?? /* @__PURE__ */ new Date()).toISOString();
+		const store = await readStore(params.dreamingRoot, nowIso);
+		const removed = Object.keys(store.entries).length;
+		await writeStore(params.dreamingRoot, emptyStore(nowIso));
+		return removed;
+	});
+}
+/** Remove only a stale lock whose owning process is no longer alive. */
+async function clearStaleDreamingLock(dreamingRoot) {
+	const lockPath = path.join(dreamingRoot, SHORT_TERM_PROMOTION_LOCK_RELATIVE);
+	const lockStat = await fs.stat(lockPath).catch((error) => {
+		if (error?.code === "ENOENT") return null;
+		throw error;
+	});
+	if (!lockStat) return false;
+	const ageMs = Date.now() - lockStat.mtimeMs;
+	if (ageMs <= LOCK_STALE_MS || !await lockOwnerIsDead(lockPath)) throw new Error(`Dreaming lock is active and cannot be cleared: ${lockPath}`);
+	await fs.unlink(lockPath);
+	log.warn({
+		lockPath,
+		ageMs
+	}, "Cleared stale dreaming lock");
+	return true;
+}
 /**
 * Increment a phase-specific signal counter on an existing store entry.
 * Also bumps `phaseHitCount` and `totalSignalCount`.
@@ -192,6 +270,6 @@ function bumpEntryPhaseSignal(entry, field, increment = 1) {
 	entry.totalSignalCount = (entry.totalSignalCount ?? 0) + increment;
 }
 //#endregion
-export { bumpEntryPhaseSignal, loadDreamingStore, recordDreamingRecalls, saveDreamingStore, withDreamingPromotionLock };
+export { bumpEntryPhaseSignal, clearStaleDreamingLock, loadDreamingStore, recordDreamingRecalls, resetDreamingStore, saveDreamingStore, withDreamingPromotionLock, withDreamingStoreLock };
 
 //# sourceMappingURL=short-term-store.js.map