@remnic/core 9.3.754 → 9.3.756

package/dist/{chunk-THZ4WR5L.js → chunk-7APVFQ34.js}

@@ -16,18 +16,24 @@ import {
 import {
   supersessionKeysForFact
 } from "./chunk-TKZ3AL5V.js";
-import {
-  stripAttributesSuffix
-} from "./chunk-SVOZFLIQ.js";
 import {
   DEFAULT_CITATION_FORMAT,
   hasCitation,
   stripCitationForTemplate
 } from "./chunk-J6A3CX5N.js";
+import {
+  stripAttributesSuffix
+} from "./chunk-SVOZFLIQ.js";
 import {
   SPECULATIVE_TTL_DAYS,
   confidenceTier
 } from "./chunk-JS2HKKOK.js";
+import {
+  inferMemoryStatus,
+  isArchivedMemoryPath,
+  sortMemoryLifecycleEvents,
+  toMemoryPathRel
+} from "./chunk-RULE4VG5.js";
 import {
   normalizeProjectionPreview,
   normalizeProjectionTags
@@ -43,15 +49,6 @@ import {
   invalidateAllForDir,
   setCachedEntities
 } from "./chunk-AWJ2FHCF.js";
-import {
-  inferMemoryStatus,
-  isArchivedMemoryPath,
-  sortMemoryLifecycleEvents,
-  toMemoryPathRel
-} from "./chunk-RULE4VG5.js";
-import {
-  rotateMarkdownFileToArchive
-} from "./chunk-DM2T26WE.js";
 import {
   closeContinuityIncidentRecord,
   createContinuityIncidentRecord,
@@ -61,10 +58,17 @@ import {
   serializeContinuityIncident,
   upsertContinuityLoopInMarkdown
 } from "./chunk-LDXUBPMO.js";
+import {
+  rotateMarkdownFileToArchive
+} from "./chunk-DM2T26WE.js";
 import {
   parseFaithfulnessField,
   serializeFaithfulnessFields
 } from "./chunk-2OZ2JEUP.js";
+import {
+  computeContentHash,
+  normalizeContent
+} from "./chunk-W5H6ZRPT.js";
 import {
   isConsolidationOperator,
   isValidDerivedFromEntry
@@ -72,24 +76,20 @@ import {
 import {
   createVersion
 } from "./chunk-VF4XKTX3.js";
-import {
-  computeContentHash,
-  normalizeContent
-} from "./chunk-W5H6ZRPT.js";
 import {
   parseProvenanceSources,
   parseProvenanceTag,
   reconcileProvenanceRead,
   serializeProvenanceFields
 } from "./chunk-OEHCMALU.js";
+import {
+  sanitizeMemoryContent
+} from "./chunk-5GKPFL3S.js";
 import {
   matchEntitySchemaSection,
   normalizeEntityStructuredSection,
   sortStructuredSectionsBySchema
 } from "./chunk-4DJQYKMN.js";
-import {
-  sanitizeMemoryContent
-} from "./chunk-5GKPFL3S.js";
 import {
   log
 } from "./chunk-NU3CSQ4H.js";
@@ -112,10 +112,935 @@ import {
 } from "./chunk-VS2IYZRU.js";
 
 // src/storage.ts
-import { access, lstat, readdir, readFile, realpath, stat, writeFile, mkdir, unlink, appendFile, open } from "fs/promises";
-import { appendFileSync, createReadStream, mkdirSync, readFileSync, statSync } from "fs";
-import { createHash } from "crypto";
-import path from "path";
+import { access, readdir as readdir3, readFile, stat as stat2, writeFile, mkdir, unlink as unlink2, appendFile, open } from "fs/promises";
+import { appendFileSync, createReadStream, mkdirSync, readFileSync, statSync } from "fs";
+import { createHash } from "crypto";
+import path3 from "path";
+
+// src/storage/memory-read-store.ts
+import { lstat, readdir, realpath, stat } from "fs/promises";
+import path from "path";
+var MemoryReadStore = class {
+  constructor(deps) {
+    this.deps = deps;
+  }
+  deps;
+  /**
+   * List stored transcript days, newest first, optionally scoped to one
+   * source. Non-transcript files in the tree are ignored.
+   */
+  async listWearableTranscriptDays(sourceId) {
+    const days = [];
+    let sources;
+    if (sourceId !== void 0) {
+      sources = [sourceId];
+    } else {
+      try {
+        const entries = await readdir(this.deps.wearablesDir, { withFileTypes: true });
+        sources = entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+      } catch (err) {
+        if (err.code === "ENOENT") return [];
+        throw err;
+      }
+    }
+    for (const source of sources) {
+      if (!/^[a-z][a-z0-9-]{0,63}$/.test(source)) continue;
+      let entries;
+      try {
+        entries = await readdir(path.join(this.deps.wearablesDir, source));
+      } catch (err) {
+        if (err.code === "ENOENT") continue;
+        throw err;
+      }
+      for (const entry of entries) {
+        if (!entry.endsWith(".md")) continue;
+        const date = entry.slice(0, -3);
+        if (!isValidTranscriptDate(date)) continue;
+        days.push({ source, date });
+      }
+    }
+    days.sort((a, b) => {
+      if (a.date > b.date) return -1;
+      if (a.date < b.date) return 1;
+      if (a.source < b.source) return -1;
+      if (a.source > b.source) return 1;
+      return 0;
+    });
+    return days;
+  }
+  async readAllArtifactsCached() {
+    if (this.deps.artifactIndexCache && Date.now() - this.deps.artifactIndexCache.loadedAtMs <= this.deps.storageManagerClass.ARTIFACT_INDEX_CACHE_TTL_MS && this.deps.artifactIndexCache.writeVersion === this.deps.getArtifactWriteVersion()) {
+      return this.deps.artifactIndexCache.memories;
+    }
+    const scanArtifacts = async () => {
+      const artifacts = [];
+      const readDir = async (dir) => {
+        try {
+          const entries = await readdir(dir, { withFileTypes: true });
+          for (const entry of entries) {
+            const fullPath = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+              await readDir(fullPath);
+              continue;
+            }
+            if (!entry.name.endsWith(".md")) continue;
+            const memory = await this.deps.readMemoryByPath(fullPath);
+            if (!memory) continue;
+            artifacts.push(memory);
+          }
+        } catch {
+        }
+      };
+      await readDir(this.deps.artifactsDir);
+      return artifacts;
+    };
+    const MAX_REBUILD_RETRIES = 2;
+    let latestArtifacts = [];
+    for (let attempt = 0; attempt <= MAX_REBUILD_RETRIES; attempt += 1) {
+      const versionBefore = this.deps.getArtifactWriteVersion();
+      const artifacts = await scanArtifacts();
+      const versionAfter = this.deps.getArtifactWriteVersion();
+      latestArtifacts = artifacts;
+      if (versionAfter === versionBefore) {
+        this.deps.artifactIndexCache = { memories: artifacts, loadedAtMs: Date.now(), writeVersion: versionAfter };
+        return artifacts;
+      }
+    }
+    this.deps.artifactIndexCache = null;
+    return latestArtifacts;
+  }
+  async collectActiveMemoryPaths() {
+    const filePaths = [];
+    let memoryRootReal;
+    try {
+      memoryRootReal = await realpath(this.deps.baseDir);
+    } catch {
+      return filePaths;
+    }
+    const collectPaths = async (dir) => {
+      let entries;
+      try {
+        const dirStat = await lstat(dir);
+        if (dirStat.isSymbolicLink() || !dirStat.isDirectory()) return;
+        assertPathInsideRoot(memoryRootReal, await realpath(dir), dir);
+        entries = await readdir(dir, { withFileTypes: true });
+      } catch {
+        return;
+      }
+      const subdirs = [];
+      for (const entry of entries) {
+        if (entry.isSymbolicLink()) continue;
+        const fullPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+          subdirs.push(fullPath);
+        } else if (entry.name.endsWith(".md")) {
+          try {
+            assertPathInsideRoot(memoryRootReal, await realpath(fullPath), fullPath);
+            filePaths.push(fullPath);
+          } catch {
+          }
+        }
+      }
+      for (const subdir of subdirs) {
+        await collectPaths(subdir);
+      }
+    };
+    for (const dir of RECALL_FALLBACK_DIRS) {
+      await collectPaths(path.join(this.deps.baseDir, dir));
+    }
+    return filePaths;
+  }
+  async readMemoriesWindow(options = {}) {
+    const allPaths = await this.deps.collectActiveMemoryPaths();
+    const sortedPaths = this.deps.orderWindowPaths(allPaths);
+    const maxMemories = typeof options.maxMemories === "number" && Number.isFinite(options.maxMemories) ? Math.max(1, Math.floor(options.maxMemories)) : void 0;
+    const maxCandidatePaths = maxMemories === void 0 ? void 0 : maxMemories * 2;
+    const updatedAfterMs = options.updatedAfter?.getTime();
+    const normalizedBatchSize = this.deps.normalizeMemoryReadBatchSize(options.batchSize);
+    const memories = [];
+    const selectedPaths = [];
+    for (let i = 0; i < sortedPaths.length; i += normalizedBatchSize) {
+      if (maxMemories !== void 0 && (memories.length >= maxMemories || maxCandidatePaths !== void 0 && selectedPaths.length >= maxCandidatePaths)) {
+        return { memories, filePaths: selectedPaths };
+      }
+      const batchPaths = sortedPaths.slice(i, i + normalizedBatchSize);
+      const candidateBatchPaths = updatedAfterMs === void 0 ? batchPaths : await this.deps.filterWindowPathsByUpdatedAfter(batchPaths, updatedAfterMs);
+      const remainingSlots = maxMemories === void 0 ? void 0 : Math.max(0, maxMemories - memories.length);
+      const remainingInspectionBudget = maxCandidatePaths === void 0 ? void 0 : Math.max(0, maxCandidatePaths - selectedPaths.length);
+      const { memories: batchMemories, filePaths: parsedCandidatePaths } = remainingSlots === void 0 ? {
+        memories: await this.deps.readParsedMemoriesFromPaths(candidateBatchPaths, normalizedBatchSize),
+        filePaths: candidateBatchPaths
+      } : await this.deps.readWindowBoundedBatch(
+        candidateBatchPaths,
+        remainingSlots,
+        remainingInspectionBudget ?? remainingSlots,
+        normalizedBatchSize
+      );
+      selectedPaths.push(...parsedCandidatePaths);
+      for (const memory of batchMemories) {
+        memories.push(memory);
+        if (maxMemories !== void 0 && memories.length >= maxMemories) {
+          return { memories, filePaths: selectedPaths };
+        }
+      }
+    }
+    return { memories, filePaths: selectedPaths };
+  }
+  /**
+   * Read all memories from the cold tier by scanning the entire cold/ root
+   * tree.  Previously this only scanned cold/facts/ and cold/corrections/, but
+   * structuredAttributes can appear on any MemoryCategory (preference, decision,
+   * entity, etc.).  buildTierMemoryPath now routes each category to its own
+   * cold/<dir>/ subtree via the shared categoryDirName() chokepoint (issue
+   * #1546), so cold decisions/preferences/... live outside cold/facts/.
+   * Scanning the full coldRoot covers every category dir and guards against
+   * files placed in unexpected subdirectories during manual operations or future
+   * refactors.
+   *
+   * Broadened in PR #402 round-6 (Finding UTsP): scanning only facts/ and
+   * corrections/ was a narrower-than-necessary subset of the cold directory
+   * tree.  Correctness trumps the minor performance difference — cold scans
+   * already happen at most once per supersession write.
+   *
+   * Used by applyTemporalSupersession so that memories already demoted to
+   * cold/ can still be marked superseded when a newer hot fact arrives.
+   *
+   * Cached with a TTL (Finding UOGi, PR #402 round-6): back-to-back
+   * structured-attribute writes in the same burst reuse the cached result
+   * instead of re-scanning the cold tree on every call.  The cache is
+   * invalidated whenever a write calls invalidateAllMemoriesCache() (which
+   * covers any hot→cold demotion that changes cold-tier contents) and
+   * expires after COLD_SCAN_CACHE_TTL_MS as a safety net.
+   */
+  async readAllColdMemories() {
+    const coldRoot = this.deps.resolveTierRootDir("cold");
+    const currentColdVersion = this.deps.readColdWriteVersion();
+    const cached = this.deps.storageManagerClass.coldMemoriesCache.get(coldRoot);
+    if (cached && Date.now() - cached.loadedAt < this.deps.storageManagerClass.COLD_SCAN_CACHE_TTL_MS && cached.coldVersion === currentColdVersion) {
+      return cached.memories;
+    }
+    const filePaths = [];
+    const collectPaths = async (dir) => {
+      try {
+        const entries = await readdir(dir, { withFileTypes: true });
+        const subdirs = [];
+        for (const entry of entries) {
+          const fullPath = path.join(dir, entry.name);
+          if (entry.isDirectory()) {
+            subdirs.push(fullPath);
+          } else if (entry.name.endsWith(".md")) {
+            filePaths.push(fullPath);
+          }
+        }
+        for (const subdir of subdirs) {
+          await collectPaths(subdir);
+        }
+      } catch {
+      }
+    };
+    await collectPaths(coldRoot);
+    const memories = await this.deps.readParsedMemoriesFromPaths(filePaths, 50);
+    this.deps.storageManagerClass.coldMemoriesCache.set(coldRoot, { memories, loadedAt: Date.now(), coldVersion: currentColdVersion });
+    return memories;
+  }
+  /** Read a single memory file by its absolute path. Returns null if unreadable. */
+  async readMemoryByPath(filePath) {
+    try {
+      const raw = await readMaybeEncryptedFile(filePath, this.deps._secureStoreKey, this.deps.baseDir);
+      const parsed = parseFrontmatter(raw);
+      if (parsed) {
+        return {
+          path: filePath,
+          frontmatter: normalizeFrontmatterForPath(
+            parsed.frontmatter,
+            toMemoryPathRel(this.deps.baseDir, filePath),
+            parsed.content
+          ),
+          content: parsed.content
+        };
+      }
+      const normalizedPath = filePath.split(path.sep).join("/");
+      if (normalizedPath.includes("/entities/") && filePath.endsWith(".md")) {
+        const entity = parseEntityFile(raw, this.deps.entitySchemas);
+        if (!entity.name) return null;
+        const nameWithoutExt = path.basename(filePath, ".md");
+        const fileMtime = entity.updated || await stat(filePath).then((s) => s.mtime.toISOString()).catch(() => (/* @__PURE__ */ new Date(0)).toISOString());
+        return {
+          path: filePath,
+          frontmatter: {
+            id: nameWithoutExt,
+            category: "entity",
+            created: fileMtime,
+            updated: fileMtime,
+            source: "entity_extraction",
+            confidence: 0.9,
+            confidenceTier: confidenceTier(0.9),
+            tags: entity.type ? [entity.type] : []
+          },
+          content: raw
+        };
+      }
+      return null;
+    } catch (err) {
+      if (err instanceof SecureStoreLockedError) throw err;
+      return null;
+    }
+  }
+  /**
+   * Append a batch of `BUFFER_SURPRISE` telemetry events (issue #563 PR 3).
+   *
+   * Each event records a single buffer flush decision driven by the
+   * surprise gate. The ledger is consumed by
+   * `reportBufferSurpriseDistribution` (Doctor report) and by downstream
+   * benchmark analysis. This method is fire-and-forget by contract:
+   * callers log but do not fail the hot path if the append throws.
+   */
+  async appendBufferSurpriseEvents(events) {
+    if (events.length === 0) return 0;
+    await this.deps.ensureDirectories();
+    const nowIso = (/* @__PURE__ */ new Date()).toISOString();
+    const payload = events.map((event) => {
+      const normalized = {
+        ...event,
+        event: "BUFFER_SURPRISE",
+        timestamp: event.timestamp && event.timestamp.length > 0 ? event.timestamp : nowIso
+      };
+      return `${JSON.stringify(normalized)}
+`;
+    }).join("");
+    await this.deps.appendStorageSecureFile(this.deps.bufferSurpriseLedgerPath, payload);
+    return events.length;
+  }
+  /**
+   * Read the buffer-surprise ledger, most recent rows last.
+   *
+   * `limit` bounds the number of **valid rows** returned (not the
+   * number of raw lines parsed). We parse every row, discard malformed
+   * ones, then take the tail — so a partial/truncated trailing line
+   * (the common failure mode after an interrupted append) cannot hide
+   * otherwise-valid recent data above it.
+   *
+   * Non-positive / non-integer / non-finite limits return `[]` rather
+   * than the entire file, matching the other ledger readers in this
+   * class and protecting against `slice(-0.5)` → `slice(-0)` silently
+   * devolving into an unbounded parse.
+   *
+   * # Performance note
+   *
+   * For very large ledgers (issue #563 follow-up), a tail-first reader
+   * would avoid parsing the full file when only a recent window is
+   * needed. We keep the full-scan implementation here because:
+   *
+   *   - the ledger is opt-in (flag off by default), so early deployments
+   *     accumulate rows slowly;
+   *   - telemetry rows are small (~200 bytes), so even 100k rows parse
+   *     in well under a second;
+   *   - the governance archive/cleanup flow can trim the ledger when
+   *     size becomes a concern, reusing the existing maintenance hooks.
+   *
+   * Swap to a chunked tail-reader if production logs show this is a
+   * hot path — leaving that work for a follow-up keeps this PR scoped
+   * to correctness, not optimization.
+   */
+  async readBufferSurpriseEvents(options = {}) {
+    let raw;
+    try {
+      raw = await this.deps.readStorageSecureFile(this.deps.bufferSurpriseLedgerPath);
+    } catch (err) {
+      if (err instanceof SecureStoreLockedError) throw err;
+      const code = err.code;
+      if (code === "ENOENT") return [];
+      throw err;
+    }
+    let effectiveLimit = null;
+    if (options.limit !== void 0) {
+      if (typeof options.limit !== "number" || !Number.isFinite(options.limit) || options.limit <= 0) {
+        return [];
+      }
+      const floored = Math.floor(options.limit);
+      if (floored <= 0) return [];
+      effectiveLimit = floored;
+    }
+    const lines = raw.split("\n");
+    const events = [];
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (trimmed.length === 0) continue;
+      try {
+        const parsed = JSON.parse(trimmed);
+        if (isValidBufferSurpriseEvent(parsed)) {
+          events.push(parsed);
+        }
+      } catch {
+      }
+    }
+    events.sort(
+      (left, right) => Date.parse(left.timestamp) - Date.parse(right.timestamp)
+    );
+    if (effectiveLimit === null) return events;
+    return events.slice(-effectiveLimit);
+  }
+  async readCompressionGuidelineStateFile(filePath) {
+    const isFiniteNonNegativeInteger = (value) => typeof value === "number" && Number.isFinite(value) && Number.isInteger(value) && value >= 0;
+    const isValidActionSummary = (value) => {
+      if (!value || typeof value !== "object") return false;
+      const summary = value;
+      return typeof summary.action === "string" && isFiniteNonNegativeInteger(summary.total) && summary.outcomes !== null && typeof summary.outcomes === "object" && isFiniteNonNegativeInteger(summary.outcomes.applied) && isFiniteNonNegativeInteger(summary.outcomes.skipped) && isFiniteNonNegativeInteger(summary.outcomes.failed) && summary.quality !== null && typeof summary.quality === "object" && isFiniteNonNegativeInteger(summary.quality.good) && isFiniteNonNegativeInteger(summary.quality.poor) && isFiniteNonNegativeInteger(summary.quality.unknown);
+    };
+    const isValidRuleUpdate = (value) => {
+      if (!value || typeof value !== "object") return false;
+      const rule = value;
+      return typeof rule.action === "string" && typeof rule.delta === "number" && Number.isFinite(rule.delta) && (rule.direction === "increase" || rule.direction === "decrease" || rule.direction === "hold") && (rule.confidence === "low" || rule.confidence === "medium" || rule.confidence === "high") && Array.isArray(rule.notes) && rule.notes.every((note) => typeof note === "string");
+    };
+    try {
+      const raw = await this.deps.readStorageSecureFile(filePath);
+      const parsed = JSON.parse(raw);
+      const sourceWindow = parsed?.sourceWindow;
+      const eventCounts = parsed?.eventCounts;
+      const activationState = parsed?.activationState === "draft" || parsed?.activationState === "active" ? parsed.activationState : void 0;
+      const contentHash = typeof parsed?.contentHash === "string" && parsed.contentHash.length > 0 ? parsed.contentHash : void 0;
+      const actionSummaries = Array.isArray(parsed?.actionSummaries) ? parsed.actionSummaries.filter(isValidActionSummary) : void 0;
+      const ruleUpdates = Array.isArray(parsed?.ruleUpdates) ? parsed.ruleUpdates.filter(isValidRuleUpdate) : void 0;
+      if (!isFiniteNonNegativeInteger(parsed?.version) || typeof parsed?.updatedAt !== "string" || parsed.updatedAt.length === 0 || !sourceWindow || typeof sourceWindow.from !== "string" || sourceWindow.from.length === 0 || typeof sourceWindow.to !== "string" || sourceWindow.to.length === 0 || !eventCounts || !isFiniteNonNegativeInteger(eventCounts.total) || !isFiniteNonNegativeInteger(eventCounts.applied) || !isFiniteNonNegativeInteger(eventCounts.skipped) || !isFiniteNonNegativeInteger(eventCounts.failed) || !isFiniteNonNegativeInteger(parsed?.guidelineVersion)) {
+        return null;
+      }
+      return {
+        version: parsed.version,
+        updatedAt: parsed.updatedAt,
+        sourceWindow: {
+          from: sourceWindow.from,
+          to: sourceWindow.to
+        },
+        eventCounts: {
+          total: eventCounts.total,
+          applied: eventCounts.applied,
+          skipped: eventCounts.skipped,
+          failed: eventCounts.failed
+        },
+        guidelineVersion: parsed.guidelineVersion,
+        ...contentHash ? { contentHash } : {},
+        ...activationState ? { activationState } : {},
+        ...actionSummaries ? { actionSummaries } : {},
+        ...ruleUpdates ? { ruleUpdates } : {}
+      };
+    } catch (err) {
+      if (err instanceof SecureStoreLockedError) throw err;
+      if (!isErrnoCode(err, "ENOENT")) throw err;
+      return null;
+    }
+  }
+  async readQuestions(opts) {
+    const cacheKey = this.deps.questionsDir;
+    const cached = this.deps.storageManagerClass.questionsCache.get(cacheKey);
+    if (cached && Date.now() - cached.loadedAt < this.deps.storageManagerClass.QUESTIONS_CACHE_TTL_MS) {
+      try {
+        const dirStat = await stat(this.deps.questionsDir);
+        if (dirStat.mtimeMs <= cached.loadedAt) {
+          const all = cached.questions;
+          return opts?.unresolvedOnly ? all.filter((q) => !q.resolved) : all;
+        }
+      } catch {
+      }
+    }
+    try {
+      const files = await readdir(this.deps.questionsDir);
+      const questions = [];
+      for (const file of files) {
+        if (!file.endsWith(".md")) continue;
+        const filePath = path.join(this.deps.questionsDir, file);
+        const raw = await readMaybeEncryptedFile(filePath, this.deps._secureStoreKey, this.deps.baseDir);
+        const parsed = this.deps.parseQuestionFile(raw, filePath);
+        if (parsed) {
+          questions.push(parsed);
+        }
+      }
+      const sorted = questions.sort((a, b) => b.priority - a.priority);
+      this.deps.storageManagerClass.questionsCache.set(cacheKey, { questions: sorted, loadedAt: Date.now() });
+      return opts?.unresolvedOnly ? sorted.filter((q) => !q.resolved) : sorted;
+    } catch {
+      return [];
+    }
+  }
+};
+
+// src/orchestration/self-deps.ts
+function selfDeps(self) {
+  const source = self;
+  return new Proxy(/* @__PURE__ */ Object.create(null), {
+    get(_target, prop) {
+      const value = source[prop];
+      return typeof value === "function" && !Object.prototype.hasOwnProperty.call(value, "prototype") ? value.bind(self) : value;
+    },
+    set(_target, prop, value) {
+      if (!(prop in source)) return false;
+      source[prop] = value;
+      return true;
+    },
+    has(_target, prop) {
+      return prop in source;
+    }
+  });
+}
+
+// src/storage/entity-store.ts
+import { readdir as readdir2, unlink } from "fs/promises";
+import path2 from "path";
+var EntityStore = class {
+  constructor(deps) {
+    this.deps = deps;
+  }
+  deps;
+  /** Normalize an entity name using this store's alias table. */
+  normalizeEntityName(raw, type) {
+    return normalizeEntityName(raw, type, this.deps.userAliases);
+  }
+  async writeEntity(name, type, facts, options = {}) {
+    await this.deps.ensureDirectories();
+    if (typeof name !== "string" || !name.trim() || typeof type !== "string" || !type.trim()) {
+      log.warn("writeEntity: invalid entity payload, skipping", {
+        nameType: typeof name,
+        typeType: typeof type
+      });
+      return "";
+    }
+    const safeFacts = Array.isArray(facts) ? [...new Set(
+      facts.filter((fact) => typeof fact === "string").map((fact) => fact.trim()).filter((fact) => fact.length > 0)
+    )] : [];
+    let normalized = this.deps.normalizeEntityName(name, type);
+    const match = await this.deps.findMatchingEntity(name, type);
+    if (match && match !== normalized) {
+      log.debug(`fuzzy match: "${normalized}" \u2192 existing "${match}"`);
+      normalized = match;
+    }
+    const filePath = path2.join(this.deps.entitiesDir, `${normalized}.md`);
+    let entity = {
+      name,
+      type,
+      created: "",
+      updated: (/* @__PURE__ */ new Date()).toISOString(),
+      facts: [],
+      summary: void 0,
+      synthesis: void 0,
+      synthesisUpdatedAt: void 0,
+      synthesisVersion: void 0,
+      synthesisStructuredFactCount: void 0,
+      synthesisStructuredFactDigest: void 0,
+      timeline: [],
+      relationships: [],
+      activity: [],
+      aliases: []
+    };
+    try {
+      const existing = await this.deps.readStorageSecureFile(filePath);
+      entity = parseEntityFile(existing, this.deps.entitySchemas);
+    } catch (err) {
+      if (err instanceof SecureStoreLockedError) throw err;
+      if (!isErrnoCode(err, "ENOENT")) throw err;
+    }
+    const timestamp = options.timestamp?.trim() || (/* @__PURE__ */ new Date()).toISOString();
+    const source = options.source?.trim() || void 0;
+    const sessionKey = options.sessionKey?.trim() || void 0;
+    const principal = options.principal?.trim() || void 0;
+    const structuredSectionMap = new Map(
+      (entity.structuredSections ?? []).map((section) => [section.key, {
+        ...section,
+        facts: [...section.facts]
+      }])
+    );
+    for (const section of options.structuredSections ?? []) {
+      const normalizedSection = normalizeEntityStructuredSection(type, section, this.deps.entitySchemas);
+      const normalizedFacts = normalizeStructuredSectionFacts(section.facts);
+      if (normalizedFacts.length === 0) continue;
+      const existingSection = structuredSectionMap.get(normalizedSection.key);
+      if (!existingSection) {
+        structuredSectionMap.set(normalizedSection.key, {
+          key: normalizedSection.key,
+          title: normalizedSection.title,
+          facts: normalizedFacts
+        });
+        continue;
+      }
+      existingSection.facts = normalizeStructuredSectionFacts([...existingSection.facts, ...normalizedFacts]);
+      if (!existingSection.title.trim() && normalizedSection.title.trim()) {
+        existingSection.title = normalizedSection.title;
+      }
+    }
+    for (const fact of safeFacts) {
+      const nextEntry = {
+        timestamp,
+        text: fact,
+        ...source ? { source } : {},
+        ...sessionKey ? { sessionKey } : {},
+        ...principal ? { principal } : {}
+      };
+      const alreadyPresent = entity.timeline.some(
+        (entry) => entry.timestamp === nextEntry.timestamp && entry.text === nextEntry.text && entry.source === nextEntry.source && entry.sessionKey === nextEntry.sessionKey && entry.principal === nextEntry.principal
+      );
+      if (alreadyPresent) continue;
+      entity.timeline.push(nextEntry);
+    }
+    entity.structuredSections = sortStructuredSectionsBySchema(
+      type,
+      Array.from(structuredSectionMap.values()).filter((section) => section.facts.length > 0),
+      this.deps.entitySchemas
+    );
+    entity.facts = compileEntityFacts(entity.timeline, entity.structuredSections);
+    entity.summary = entity.synthesis || entity.summary;
+    entity.name = name;
+    entity.type = type;
+    entity.created = entity.created || timestamp;
+    entity.updated = (/* @__PURE__ */ new Date()).toISOString();
+    await this.deps.snapshotBeforeWrite(filePath, "write");
+    await this.deps.writeStorageSecureFile(filePath, serializeEntityFile(entity, this.deps.entitySchemas));
+    this.deps.invalidateKnowledgeIndexCache();
+    this.deps.bumpMemoryStatusVersion();
+    log.debug(`wrote entity ${normalized}`);
+    return normalized;
+  }
+  async readEntity(name) {
+    const filePath = this.deps.resolveEntityFilePath(name);
+    if (filePath === null) {
+      return "";
+    }
+    try {
+      return await this.deps.readStorageSecureFile(filePath);
+    } catch (err) {
+      if (err instanceof SecureStoreLockedError) throw err;
+      if (!isErrnoCode(err, "ENOENT")) throw err;
+      return "";
+    }
+  }
+  /** Return sorted list of entity filenames (without .md extension) */
+  async listEntityNames() {
+    try {
+      const entries = await readdir2(this.deps.entitiesDir);
+      return entries.filter((e) => e.endsWith(".md")).map((e) => e.replace(".md", "")).sort();
+    } catch {
+      return [];
+    }
+  }
+  /**
+   * Set or rewrite the synthesis layer of an entity file.
+   */
+  async updateEntitySynthesis(name, synthesis, options = {}) {
+    const filePath = path2.join(this.deps.entitiesDir, `${name}.md`);
+    let entity;
+    try {
+      const content = await this.deps.readStorageSecureFile(filePath);
+      entity = parseEntityFile(content, this.deps.entitySchemas);
+    } catch (err) {
+      if (err instanceof SecureStoreLockedError) throw err;
+      if (!isErrnoCode(err, "ENOENT")) throw err;
+      log.debug(`updateEntitySynthesis: entity file ${name}.md not found`);
+      return;
+    }
+    const updatedAt = options.updatedAt?.trim() || entity.synthesisUpdatedAt?.trim() || void 0;
+    const entityUpdatedAt = options.entityUpdatedAt?.trim() || updatedAt || entity.updated || (/* @__PURE__ */ new Date()).toISOString();
+    const synthesisTimelineCount = Number.isInteger(options.synthesisTimelineCount) && (options.synthesisTimelineCount ?? 0) >= 0 ? options.synthesisTimelineCount : void 0;
+    const synthesisStructuredFactCount = Number.isInteger(options.synthesisStructuredFactCount) && (options.synthesisStructuredFactCount ?? 0) >= 0 ? options.synthesisStructuredFactCount : countEntityStructuredFacts(entity);
+    const synthesisStructuredFactDigest = options.synthesisStructuredFactDigest?.trim() || fingerprintEntityStructuredFacts(entity);
+    entity.synthesis = synthesis.trim();
+    entity.summary = entity.synthesis;
+    entity.synthesisUpdatedAt = updatedAt;
+    entity.synthesisTimelineCount = synthesisTimelineCount;
+    entity.synthesisStructuredFactCount = synthesisStructuredFactCount;
+    entity.synthesisStructuredFactDigest = synthesisStructuredFactDigest;
+    entity.synthesisVersion = Math.max(0, entity.synthesisVersion ?? 0) + (options.incrementVersion === false ? 0 : 1);
+    entity.updated = entityUpdatedAt;
+    await this.deps.writeStorageSecureFile(filePath, serializeEntityFile(entity, this.deps.entitySchemas));
+    await this.deps.removeEntitySynthesisQueueEntries([
+      .../* @__PURE__ */ new Set([name, this.deps.normalizeEntityName(entity.name, entity.type)])
+    ]);
+    this.deps.invalidateKnowledgeIndexCache();
+    this.deps.bumpMemoryStatusVersion();
+  }
+  /**
+   * Read all entity files and return lightweight EntityFile objects.
+   * Parsing is fast (~50-100ms for ~1,800 files) since entity files are small.
+   */
+  async readAllEntityFiles() {
+    const currentVersion = this.deps.getMemoryStatusVersion();
+    const schemaCacheKey = buildEntitySchemaCacheKey(this.deps.entitySchemas);
+    const cacheKey = `${this.deps.getEntityCacheSecureStoreKey()}\0${schemaCacheKey}`;
+    const cached = getCachedEntities(this.deps.baseDir, currentVersion, cacheKey);
+    if (cached) return cached;
+    try {
+      const entries = await readdir2(this.deps.entitiesDir);
+      const mdFiles = entries.filter((e) => e.endsWith(".md"));
+      if (mdFiles.length === 0) return [];
+      const BATCH_SIZE = 100;
+      const entities = [];
+      for (let i = 0; i < mdFiles.length; i += BATCH_SIZE) {
+        const batch = mdFiles.slice(i, i + BATCH_SIZE);
+        const results = await Promise.all(
+          batch.map(async (entry) => {
+            try {
+              return await this.deps.readStorageSecureFile(path2.join(this.deps.entitiesDir, entry));
+            } catch (err) {
+              if (err instanceof SecureStoreLockedError) throw err;
+              if (!isErrnoCode(err, "ENOENT")) throw err;
+              return null;
+            }
+          })
+        );
+        for (const content of results) {
+          if (content !== null) entities.push(parseEntityFile(content, this.deps.entitySchemas));
+        }
+      }
+      setCachedEntities(this.deps.baseDir, entities, currentVersion, cacheKey);
+      return entities;
+    } catch (err) {
+      if (err instanceof SecureStoreLockedError || !isErrnoCode(err, "ENOENT")) throw err;
+      return [];
+    }
+  }
+  /**
+   * Build the Knowledge Index: a compact markdown table of top-scored entities.
+   * Respects maxEntities and maxChars limits from config.
+   */
+  async buildKnowledgeIndex(config, overrides) {
+    const useDefaultLimits = overrides?.maxEntities === void 0 && overrides?.maxChars === void 0;
+    if (useDefaultLimits && this.deps.knowledgeIndexCache && Date.now() - this.deps.knowledgeIndexCache.builtAt < this.deps.storageManagerClass.KNOWLEDGE_INDEX_CACHE_TTL_MS) {
+      return { result: this.deps.knowledgeIndexCache.result, cached: true };
+    }
+    const entities = await this.deps.readAllEntityFiles();
+    if (entities.length === 0) {
+      if (useDefaultLimits) this.deps.knowledgeIndexCache = { result: "", builtAt: Date.now() };
+      return { result: "", cached: false };
+    }
+    const now = /* @__PURE__ */ new Date();
+    const scored = entities.map((e) => ({
+      name: e.name,
+      type: e.type,
+      score: this.deps.storageManagerClass.scoreEntity(e, now),
+      factCount: e.facts.length,
+      summary: e.synthesis ?? e.summary,
+      topRelationships: e.relationships.slice(0, 3).map((r) => r.target)
+    }));
+    scored.sort((a, b) => b.score - a.score);
+    const maxEntities = typeof overrides?.maxEntities === "number" ? Math.max(0, Math.floor(overrides.maxEntities)) : config.knowledgeIndexMaxEntities;
+    const topN = scored.slice(0, maxEntities);
+    if (topN.length === 0) {
+      if (useDefaultLimits) this.deps.knowledgeIndexCache = { result: "", builtAt: Date.now() };
+      return { result: "", cached: false };
+    }
+    const header = "## Knowledge Index\n\n| Entity | Type | Summary | Connected to |\n|--------|------|---------|-------------|";
+    const rows = [];
+    let totalChars = header.length;
+    const maxChars = typeof overrides?.maxChars === "number" ? Math.max(0, Math.floor(overrides.maxChars)) : config.knowledgeIndexMaxChars;
+    for (const entity of topN) {
+      const summary = entity.summary || `${entity.factCount} facts`;
+      const connected = entity.topRelationships.length > 0 ? entity.topRelationships.join(", ") : "\u2014";
+      const row = `| ${entity.name} | ${entity.type} | ${summary} | ${connected} |`;
+      if (totalChars + row.length + 1 > maxChars) break;
+      rows.push(row);
+      totalChars += row.length + 1;
+    }
+    const result = rows.length === 0 ? "" : `${header}
+${rows.join("\n")}
+`;
+    if (useDefaultLimits) this.deps.knowledgeIndexCache = { result, builtAt: Date.now() };
+    return { result, cached: false };
+  }
+  /**
+   * Merge fragmented entity files that resolve to the same canonical name.
+   * Preserves relationships, activity, aliases, and summary from all fragments.
+   * Returns count of files merged.
+   */
+  async mergeFragmentedEntities() {
+    let merged = 0;
+    try {
+      const entries = await readdir2(this.deps.entitiesDir);
+      const mdFiles = entries.filter((e) => e.endsWith(".md"));
+      const groups = /* @__PURE__ */ new Map();
+      for (const file of mdFiles) {
+        const baseName = file.replace(".md", "");
+        const dashIdx = baseName.indexOf("-");
+        if (dashIdx === -1) continue;
+        const type = baseName.slice(0, dashIdx);
+        const restOfName = baseName.slice(dashIdx + 1);
+        const canonical = this.deps.normalizeEntityName(restOfName, type);
+        if (!groups.has(canonical)) groups.set(canonical, []);
+        groups.get(canonical).push(file);
+      }
+      for (const [canonical, files] of groups) {
+        if (files.length <= 1) continue;
+        const mergedEntity = {
+          name: "",
+          type: "other",
+          created: "",
+          updated: "",
+          extraFrontmatterLines: [],
+          preSectionLines: [],
+          facts: [],
+          summary: void 0,
+          synthesis: void 0,
+          synthesisUpdatedAt: void 0,
+          synthesisTimelineCount: void 0,
+          synthesisStructuredFactCount: void 0,
+          synthesisStructuredFactDigest: void 0,
+          synthesisVersion: void 0,
+          timeline: [],
+          relationships: [],
+          activity: [],
+          aliases: [],
+          structuredSections: [],
+          extraSections: []
+        };
+        for (const file of files) {
+          const filePath = path2.join(this.deps.entitiesDir, file);
+          try {
+            const content = await this.deps.readStorageSecureFile(filePath);
+            const parsed = parseEntityFile(content, this.deps.entitySchemas);
+            if (!mergedEntity.type || mergedEntity.type === "other") {
+              mergedEntity.type = parsed.type;
+            }
+            if (!mergedEntity.updated || compareEntityTimestamps(parsed.updated, mergedEntity.updated) > 0) {
+              mergedEntity.updated = parsed.updated;
+            }
+            const parsedCreated = parsed.created || parsed.updated;
+            const mergedCreated = mergedEntity.created?.trim() || "";
+            const parsedCreatedMs = parsedCreated ? Date.parse(parsedCreated) : Number.NaN;
+            const mergedCreatedMs = mergedCreated ? Date.parse(mergedCreated) : Number.NaN;
+            const parsedCreatedIsValid = Number.isFinite(parsedCreatedMs);
+            const mergedCreatedIsValid = Number.isFinite(mergedCreatedMs);
+            if (parsedCreated && (!mergedCreated || parsedCreatedIsValid && !mergedCreatedIsValid || parsedCreatedIsValid && mergedCreatedIsValid && parsedCreatedMs < mergedCreatedMs || !parsedCreatedIsValid && !mergedCreatedIsValid && compareEntityTimestamps(parsedCreated, mergedCreated) < 0)) {
+              mergedEntity.created = parsedCreated;
+            }
+            if (parsed.name.length > mergedEntity.name.length) {
+              mergedEntity.name = parsed.name;
+            }
+            const parsedSynthesisUpdatedAt = parsed.synthesisUpdatedAt?.trim() || void 0;
+            const mergedSynthesisUpdatedAt = mergedEntity.synthesisUpdatedAt?.trim() || void 0;
+            if (parsed.synthesis && (!mergedEntity.synthesis || !mergedSynthesisUpdatedAt && Boolean(parsedSynthesisUpdatedAt) || Boolean(mergedSynthesisUpdatedAt) && Boolean(parsedSynthesisUpdatedAt) && compareEntityTimestamps(parsedSynthesisUpdatedAt, mergedSynthesisUpdatedAt) > 0)) {
+              mergedEntity.synthesis = parsed.synthesis;
+              mergedEntity.summary = parsed.synthesis;
+              mergedEntity.synthesisUpdatedAt = parsedSynthesisUpdatedAt;
+              mergedEntity.synthesisTimelineCount = parsed.synthesisTimelineCount;
+              mergedEntity.synthesisStructuredFactCount = parsed.synthesisStructuredFactCount;
+              mergedEntity.synthesisStructuredFactDigest = parsed.synthesisStructuredFactDigest;
+              mergedEntity.synthesisVersion = parsed.synthesisVersion;
+            } else if (!mergedEntity.summary && parsed.summary) {
+              mergedEntity.summary = parsed.summary;
+              mergedEntity.synthesis = parsed.summary;
+              mergedEntity.synthesisUpdatedAt = parsedSynthesisUpdatedAt;
+              mergedEntity.synthesisTimelineCount = parsed.synthesisTimelineCount;
+              mergedEntity.synthesisStructuredFactCount = parsed.synthesisStructuredFactCount;
+              mergedEntity.synthesisStructuredFactDigest = parsed.synthesisStructuredFactDigest;
+              mergedEntity.synthesisVersion = parsed.synthesisVersion;
+            }
+            mergedEntity.timeline.push(...parsed.timeline);
+            mergedEntity.relationships.push(...parsed.relationships);
+            mergedEntity.activity.push(...parsed.activity);
+            mergedEntity.aliases.push(...parsed.aliases);
+            const mergedStructuredSectionMap = new Map(
+              (mergedEntity.structuredSections ?? []).map((section) => [section.key, {
+                ...section,
+                facts: [...section.facts]
+              }])
+            );
+            for (const section of parsed.structuredSections ?? []) {
+              const existingSection = mergedStructuredSectionMap.get(section.key);
+              if (!existingSection) {
+                mergedStructuredSectionMap.set(section.key, {
+                  key: section.key,
+                  title: section.title,
+                  facts: [...new Set(section.facts.map((fact) => fact.trim()).filter((fact) => fact.length > 0))]
+                });
+                continue;
+              }
+              const mergedFacts = new Set(existingSection.facts.map((fact) => fact.trim()));
+              for (const fact of section.facts) {
+                const trimmed = fact.trim();
+                if (!trimmed) continue;
+                mergedFacts.add(trimmed);
+              }
+              existingSection.facts = Array.from(mergedFacts);
+              if (!existingSection.title.trim() && section.title.trim()) {
+                existingSection.title = section.title;
+              }
+            }
+            mergedEntity.structuredSections = Array.from(mergedStructuredSectionMap.values());
+            mergedEntity.extraFrontmatterLines.push(...parsed.extraFrontmatterLines ?? []);
+            mergedEntity.preSectionLines.push(...parsed.preSectionLines ?? []);
+            mergedEntity.extraSections.push(...(parsed.extraSections ?? []).map((section) => ({
+              title: section.title,
+              lines: [...section.lines]
+            })));
+          } catch (err) {
+            if (err instanceof SecureStoreLockedError) throw err;
+            if (!isErrnoCode(err, "ENOENT")) throw err;
+          }
+        }
+        const timelineKeys = /* @__PURE__ */ new Set();
+        mergedEntity.timeline = mergedEntity.timeline.filter((entry) => {
+          const key = JSON.stringify([
+            entry.timestamp,
+            entry.source ?? "",
+            entry.sessionKey ?? "",
+            entry.principal ?? "",
+            entry.text
+          ]);
+          if (timelineKeys.has(key)) return false;
+          timelineKeys.add(key);
+          return true;
+        });
+        const relKeys = /* @__PURE__ */ new Set();
+        mergedEntity.relationships = mergedEntity.relationships.filter((r) => {
+          const key = `${r.target}::${r.label}`;
+          if (relKeys.has(key)) return false;
+          relKeys.add(key);
+          return true;
+        });
+        const actKeys = /* @__PURE__ */ new Set();
+        mergedEntity.activity = mergedEntity.activity.filter((a) => {
+          const key = `${a.date}::${a.note}`;
+          if (actKeys.has(key)) return false;
+          actKeys.add(key);
+          return true;
+        }).sort((a, b) => b.date.localeCompare(a.date));
+        mergedEntity.aliases = [...new Set(mergedEntity.aliases)];
+        mergedEntity.structuredSections = sortStructuredSectionsBySchema(
+          mergedEntity.type,
+          mergedEntity.structuredSections ?? [],
+          this.deps.entitySchemas
+        );
+        mergedEntity.facts = compileEntityFacts(mergedEntity.timeline, mergedEntity.structuredSections);
+        const extraSectionKeys = /* @__PURE__ */ new Set();
+        mergedEntity.extraSections = (mergedEntity.extraSections ?? []).filter((section) => {
+          const key = `${section.title}::${section.lines.join("\n")}`;
+          if (extraSectionKeys.has(key)) return false;
+          extraSectionKeys.add(key);
+          return true;
+        });
+        if (!mergedEntity.name) {
+          const dashIdx = canonical.indexOf("-");
+          mergedEntity.name = dashIdx !== -1 ? canonical.slice(dashIdx + 1) : canonical;
+        }
+        mergedEntity.created = mergedEntity.created || mergedEntity.updated || (/* @__PURE__ */ new Date()).toISOString();
+        mergedEntity.updated = mergedEntity.updated || (/* @__PURE__ */ new Date()).toISOString();
+        const canonicalPath = path2.join(this.deps.entitiesDir, `${canonical}.md`);
+        await this.deps.writeStorageSecureFile(canonicalPath, serializeEntityFile(mergedEntity, this.deps.entitySchemas));
+        for (const file of files) {
+          const filePath = path2.join(this.deps.entitiesDir, file);
+          if (filePath !== canonicalPath) {
+            try {
+              await unlink(filePath);
+              merged++;
+              log.debug(`merged entity ${file} \u2192 ${canonical}.md`);
+            } catch {
+            }
+          }
+        }
+      }
+    } catch (err) {
+      if (err instanceof SecureStoreLockedError || !isErrnoCode(err, "ENOENT")) throw err;
+    }
+    return merged;
+  }
+};
+
+// src/storage.ts
 var ARTIFACT_SEARCH_STOPWORDS = /* @__PURE__ */ new Set([
   "a",
   "an",
@@ -720,17 +1645,17 @@ var KNOWN_ENTITY_FILENAME_PREFIXES = /* @__PURE__ */ new Set([
   "topic"
 ]);
 function inferEntityTypeFromFilename(pathRel) {
-  const basename = path.basename(pathRel, ".md").toLowerCase();
+  const basename = path3.basename(pathRel, ".md").toLowerCase();
   const separator = basename.indexOf("-");
   if (separator <= 0) return void 0;
   const candidate = basename.slice(0, separator);
   return KNOWN_ENTITY_FILENAME_PREFIXES.has(candidate) ? candidate : void 0;
 }
 function normalizeFrontmatterForPath(frontmatter, pathRel, content = "") {
-  const normalizedPath = pathRel.split(path.sep).join("/");
+  const normalizedPath = pathRel.split(path3.sep).join("/");
   let normalizedFrontmatter = frontmatter;
   if (normalizedPath === "entities" || normalizedPath.startsWith("entities/") || normalizedPath.includes("/entities/")) {
-    const basename = path.basename(pathRel, ".md");
+    const basename = path3.basename(pathRel, ".md");
     const inferredType = inferEntityTypeFromContent(content) || inferEntityTypeFromFilename(pathRel) || "entity";
     const existingTags = Array.isArray(frontmatter.tags) ? frontmatter.tags : [];
     normalizedFrontmatter = {
@@ -797,8 +1722,8 @@ var ContentHashIndex = class _ContentHashIndex {
   secureStoreKeyProvider;
   secureStoreWriteKeyProvider;
   memoryDir;
-  constructor(stateDir, secureStoreKeyProvider = () => null, secureStoreWriteKeyProvider = secureStoreKeyProvider, memoryDir = path.dirname(stateDir)) {
-    this.filePath = path.join(stateDir, "fact-hashes.txt");
+  constructor(stateDir, secureStoreKeyProvider = () => null, secureStoreWriteKeyProvider = secureStoreKeyProvider, memoryDir = path3.dirname(stateDir)) {
+    this.filePath = path3.join(stateDir, "fact-hashes.txt");
     this.secureStoreKeyProvider = secureStoreKeyProvider;
     this.secureStoreWriteKeyProvider = secureStoreWriteKeyProvider;
     this.memoryDir = memoryDir;
@@ -845,7 +1770,7 @@ var ContentHashIndex = class _ContentHashIndex {
   /** Persist index to disk if changed. */
   async save() {
     if (!this.dirty) return;
-    await mkdir(path.dirname(this.filePath), { recursive: true });
+    await mkdir(path3.dirname(this.filePath), { recursive: true });
     await writeMaybeEncryptedFile(
       this.filePath,
       [...this.hashes].join("\n") + "\n",
@@ -1699,7 +2624,7 @@ function isValidBufferSurpriseEvent(value) {
   }
   return true;
 }
-var StorageManager = class _StorageManager {
+var StorageManager3 = class _StorageManager {
   constructor(baseDir, entitySchemas) {
     this.baseDir = baseDir;
     this.entitySchemas = entitySchemas;
@@ -1708,9 +2633,11 @@ var StorageManager = class _StorageManager {
   baseDir;
   entitySchemas;
   knowledgeIndexCache = null;
+  artifactIndexCache = null;
+  /** Read by storage/entity-store.ts (decomposition), hence not `private`. */
   static KNOWLEDGE_INDEX_CACHE_TTL_MS = 6e5;
   // 10 minutes (entity mutations invalidate)
-  artifactIndexCache = null;
+  /** Read by storage/memory-read-store.ts (decomposition). */
   static ARTIFACT_INDEX_CACHE_TTL_MS = 6e4;
   // 1 minute
   static artifactWriteVersionByDir = /* @__PURE__ */ new Map();
@@ -1739,14 +2666,18 @@ var StorageManager = class _StorageManager {
   // on every cold-tier write, making the cache correct across process boundaries
   // (gateway + CLI). After Finding UTsP broadened the scan to the entire cold/
   // subtree, amortizing across back-to-back writes is even more important.
+  /** Read by storage/memory-read-store.ts (decomposition). */
   static COLD_SCAN_CACHE_TTL_MS = 3e4;
   // 30 seconds
+  /** Read by storage/memory-read-store.ts (decomposition). */
   static coldMemoriesCache = /* @__PURE__ */ new Map();
   // Cache for readQuestions() — avoids serially re-reading tens of thousands of
   // question files on every recall.  60-second TTL is intentionally short so that
   // newly written questions surface quickly.
+  /** Read by storage/memory-read-store.ts (decomposition). */
   static QUESTIONS_CACHE_TTL_MS = 6e4;
   // 1 minute
+  /** Read by storage/memory-read-store.ts (decomposition). */
   static questionsCache = /* @__PURE__ */ new Map();
   factHashIndex = null;
   factHashIndexLoadPromise = null;
@@ -1905,7 +2836,7 @@ var StorageManager = class _StorageManager {
         void 0,
         this.baseDir
       );
-      const rel = path.relative(this.baseDir, filePath).split(path.sep).join("/");
+      const rel = path3.relative(this.baseDir, filePath).split(path3.sep).join("/");
       return `${rel}:${version.versionId}`;
     } catch (err) {
       log.warn(
@@ -1914,19 +2845,51 @@ var StorageManager = class _StorageManager {
       return null;
     }
   }
+  /**
+   * The LIVE class object of this instance (issue #1809 review of the
+   * storage decomposition): extracted store modules must read/write the
+   * shared static caches (questionsCache, coldMemoriesCache, ...) through
+   * the SAME class binding the host methods use. Referencing the imported
+   * `StorageManager` symbol from a split bundle chunk can yield a second
+   * class copy with its own statics, split-braining the caches
+   * (resolveQuestion clears copy A while readQuestions reads copy B).
+   */
+  get storageManagerClass() {
+    return this.constructor;
+  }
   /** The root directory of this storage instance. */
+  /** MemoryReadStore (storage.ts decomposition). Lazy; selfDeps live wiring. */
+  _memoryReadStore;
+  get memoryReadStore() {
+    if (!this._memoryReadStore) {
+      this._memoryReadStore = new MemoryReadStore(
+        selfDeps(this)
+      );
+    }
+    return this._memoryReadStore;
+  }
+  /** EntityStore (storage.ts decomposition). Lazy; selfDeps live wiring. */
+  _entityStore;
+  get entityStore() {
+    if (!this._entityStore) {
+      this._entityStore = new EntityStore(
+        selfDeps(this)
+      );
+    }
+    return this._entityStore;
+  }
   get dir() {
     return this.baseDir;
   }
   identityFilePath(workspaceDir, namespace) {
     const rawNamespace = typeof namespace === "string" ? namespace.trim() : "";
-    if (!rawNamespace) return path.join(workspaceDir, "IDENTITY.md");
+    if (!rawNamespace) return path3.join(workspaceDir, "IDENTITY.md");
     const safeNamespace = rawNamespace.replace(/[^a-zA-Z0-9._-]/g, "-");
-    return path.join(workspaceDir, `IDENTITY.${safeNamespace}.md`);
+    return path3.join(workspaceDir, `IDENTITY.${safeNamespace}.md`);
   }
   versionFilePath(kind) {
     const fileName = kind === "memory-status" ? ".memory-status-version.log" : kind === "artifact-write" ? ".artifact-write-version.log" : ".cold-write-version.log";
-    return path.join(this.stateDir, fileName);
+    return path3.join(this.stateDir, fileName);
   }
   bumpSharedVersion(kind, fallbackMap) {
     const filePath = this.versionFilePath(kind);
@@ -1973,7 +2936,7 @@ var StorageManager = class _StorageManager {
   // memories.
   // -------------------------------------------------------------------------
   get wearablesDir() {
-    return path.join(this.baseDir, WEARABLES_DIR_NAME);
+    return path3.join(this.baseDir, WEARABLES_DIR_NAME);
   }
   /**
    * Resolve the on-disk path for a source/day transcript. Throws on
@@ -1991,7 +2954,7 @@ var StorageManager = class _StorageManager {
         `invalid wearable transcript date '${String(date)}' \u2014 expected YYYY-MM-DD`
       );
     }
-    return path.join(this.wearablesDir, sourceId, `${date}.md`);
+    return path3.join(this.wearablesDir, sourceId, `${date}.md`);
   }
   async writeWearableDayTranscript(sourceId, date, serialized) {
     const targetPath = this.wearableTranscriptPath(sourceId, date);
@@ -2000,55 +2963,17 @@ var StorageManager = class _StorageManager {
   /** Read a stored day transcript; null when the day has no file. */
   async readWearableDayTranscript(sourceId, date) {
     const targetPath = this.wearableTranscriptPath(sourceId, date);
-    try {
-      return await readMaybeEncryptedFile(targetPath, this._secureStoreKey, this.baseDir);
-    } catch (err) {
-      if (err.code === "ENOENT") return null;
-      throw err;
-    }
-  }
-  /**
-   * List stored transcript days, newest first, optionally scoped to one
-   * source. Non-transcript files in the tree are ignored.
-   */
-  async listWearableTranscriptDays(sourceId) {
-    const days = [];
-    let sources;
-    if (sourceId !== void 0) {
-      sources = [sourceId];
-    } else {
-      try {
-        const entries = await readdir(this.wearablesDir, { withFileTypes: true });
-        sources = entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
-      } catch (err) {
-        if (err.code === "ENOENT") return [];
-        throw err;
-      }
-    }
-    for (const source of sources) {
-      if (!/^[a-z][a-z0-9-]{0,63}$/.test(source)) continue;
-      let entries;
-      try {
-        entries = await readdir(path.join(this.wearablesDir, source));
-      } catch (err) {
-        if (err.code === "ENOENT") continue;
-        throw err;
-      }
-      for (const entry of entries) {
-        if (!entry.endsWith(".md")) continue;
-        const date = entry.slice(0, -3);
-        if (!isValidTranscriptDate(date)) continue;
-        days.push({ source, date });
-      }
-    }
-    days.sort((a, b) => {
-      if (a.date > b.date) return -1;
-      if (a.date < b.date) return 1;
-      if (a.source < b.source) return -1;
-      if (a.source > b.source) return 1;
-      return 0;
-    });
-    return days;
+    try {
+      return await readMaybeEncryptedFile(targetPath, this._secureStoreKey, this.baseDir);
+    } catch (err) {
+      if (err.code === "ENOENT") return null;
+      throw err;
+    }
+  }
+  async listWearableTranscriptDays(sourceId) {
+    return this.memoryReadStore.listWearableTranscriptDays(
+      sourceId
+    );
   }
   /**
    * Locate a wearable-sourced memory by exact (trimmed) content,
@@ -2116,25 +3041,25 @@ var StorageManager = class _StorageManager {
     });
   }
   get factsDir() {
-    return path.join(this.baseDir, "facts");
+    return path3.join(this.baseDir, "facts");
   }
   get correctionsDir() {
-    return path.join(this.baseDir, "corrections");
+    return path3.join(this.baseDir, "corrections");
   }
   get proceduresDir() {
-    return path.join(this.baseDir, "procedures");
+    return path3.join(this.baseDir, "procedures");
   }
   get reasoningTracesDir() {
-    return path.join(this.baseDir, "reasoning-traces");
+    return path3.join(this.baseDir, "reasoning-traces");
   }
   get entitiesDir() {
-    return path.join(this.baseDir, "entities");
+    return path3.join(this.baseDir, "entities");
   }
   resolveEntityFilePath(name) {
     if (typeof name !== "string") return null;
-    const filePath = path.resolve(this.entitiesDir, `${name}.md`);
-    const relative = path.relative(this.entitiesDir, filePath);
-    if (relative === "" || relative.startsWith("..") || path.isAbsolute(relative)) {
+    const filePath = path3.resolve(this.entitiesDir, `${name}.md`);
+    const relative = path3.relative(this.entitiesDir, filePath);
+    if (relative === "" || relative.startsWith("..") || path3.isAbsolute(relative)) {
       return null;
     }
     return filePath;
@@ -2149,10 +3074,10 @@ var StorageManager = class _StorageManager {
     return writeMaybeEncryptedFileFromChunks(filePath, chunks, this.resolveWriteKey(), {}, this.baseDir).then(() => this.notifyCatalogWrite());
   }
   assertManagedStoragePath(filePath, method) {
-    const resolved = path.resolve(filePath);
-    const base = path.resolve(this.baseDir);
-    const rel = path.relative(base, resolved);
-    if (rel === "" || rel === ".." || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) {
+    const resolved = path3.resolve(filePath);
+    const base = path3.resolve(this.baseDir);
+    const rel = path3.relative(base, resolved);
+    if (rel === "" || rel === ".." || rel.startsWith(`..${path3.sep}`) || path3.isAbsolute(rel)) {
       throw new Error(`${method}: file path escapes memory dir`);
     }
     return resolved;
@@ -2163,8 +3088,8 @@ var StorageManager = class _StorageManager {
   }
   async digestOfflineSyncFile(filePath) {
     const target = this.assertManagedStoragePath(filePath, "storage.digestOfflineSyncFile");
-    const st = await stat(target);
-    const relPath = path.relative(this.baseDir, target).split(path.sep).join("/");
+    const st = await stat2(target);
+    const relPath = path3.relative(this.baseDir, target).split(path3.sep).join("/");
     const cache = await this.loadOfflineSyncDigestCache();
     const cached = cache.get(relPath);
     if (cached && cached.statBytes === st.size && cached.mtimeMs === st.mtimeMs && cached.ctimeMs === st.ctimeMs && !cached.encrypted) {
@@ -2225,7 +3150,7 @@ var StorageManager = class _StorageManager {
         const bytes = typeof record.bytes === "number" ? record.bytes : NaN;
         const sha256 = typeof record.sha256 === "string" ? record.sha256 : "";
         const encrypted = record.encrypted === true;
-        if (cachePath.length === 0 || cachePath === ".." || cachePath.startsWith("../") || path.isAbsolute(cachePath) || !Number.isFinite(statBytes) || !Number.isFinite(mtimeMs) || !Number.isFinite(ctimeMs) || !Number.isFinite(bytes) || !/^[a-f0-9]{64}$/i.test(sha256)) {
+        if (cachePath.length === 0 || cachePath === ".." || cachePath.startsWith("../") || path3.isAbsolute(cachePath) || !Number.isFinite(statBytes) || !Number.isFinite(mtimeMs) || !Number.isFinite(ctimeMs) || !Number.isFinite(bytes) || !/^[a-f0-9]{64}$/i.test(sha256)) {
           continue;
         }
         cache.set(cachePath, { statBytes, mtimeMs, ctimeMs, encrypted, sha256, bytes });
@@ -2267,7 +3192,7 @@ var StorageManager = class _StorageManager {
       const cache = this.offlineSyncDigestCache;
       if (!cache) return;
       const entries = [...cache.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([entryPath, entry]) => ({ path: entryPath, ...entry }));
-      await mkdir(path.dirname(this.offlineSyncDigestCachePath), { recursive: true });
+      await mkdir(path3.dirname(this.offlineSyncDigestCachePath), { recursive: true });
       await writeFile(
         this.offlineSyncDigestCachePath,
         `${JSON.stringify({ version: 1, entries })}
@@ -2306,7 +3231,7 @@ var StorageManager = class _StorageManager {
   }
   async deleteOfflineSyncFile(filePath) {
     const target = this.assertManagedStoragePath(filePath, "storage.deleteOfflineSyncFile");
-    await unlink(target).catch((error) => {
+    await unlink2(target).catch((error) => {
       if (isErrnoCode(error, "ENOENT")) return;
       throw error;
     });
@@ -2316,14 +3241,14 @@ var StorageManager = class _StorageManager {
     this.invalidateAllMemoriesCache();
     this.invalidateKnowledgeIndexCache();
     this.factHashIndexAuthoritative = false;
-    await unlink(this.factHashIndexReadyPath).catch((error) => {
+    await unlink2(this.factHashIndexReadyPath).catch((error) => {
       if (isErrnoCode(error, "ENOENT")) return;
       throw error;
     });
-    if (filePath.includes(`${path.sep}cold${path.sep}`)) {
+    if (filePath.includes(`${path3.sep}cold${path3.sep}`)) {
       this.invalidateColdMemoriesCache();
     }
-    if (filePath.includes(`${path.sep}artifacts${path.sep}`)) {
+    if (filePath.includes(`${path3.sep}artifacts${path3.sep}`)) {
       this.bumpArtifactWriteVersion();
     }
     this.bumpMemoryStatusVersion();
@@ -2351,7 +3276,7 @@ var StorageManager = class _StorageManager {
   }
   async appendStorageSecureFileUnlocked(filePath, content) {
     const writeKey = this.resolveWriteKey();
-    await mkdir(path.dirname(filePath), { recursive: true });
+    await mkdir(path3.dirname(filePath), { recursive: true });
     if (writeKey === null) {
       try {
         if (isEncryptedFile(await readFile(filePath))) {
@@ -2377,16 +3302,16 @@ var StorageManager = class _StorageManager {
     this.notifyCatalogWrite();
   }
   get stateDir() {
-    return path.join(this.baseDir, "state");
+    return path3.join(this.baseDir, "state");
   }
   get offlineSyncDigestCachePath() {
-    return path.join(this.baseDir, ".offline-sync", "digest-cache.v1.json");
+    return path3.join(this.baseDir, ".offline-sync", "digest-cache.v1.json");
   }
   get entitySynthesisQueuePath() {
-    return path.join(this.stateDir, "entity-synthesis-queue.json");
+    return path3.join(this.stateDir, "entity-synthesis-queue.json");
   }
   get factHashIndexReadyPath() {
-    return path.join(this.stateDir, "fact-hashes.ready");
+    return path3.join(this.stateDir, "fact-hashes.ready");
   }
   // ── Tombstone store access (issue #1579) ─────────────────────────────────
   /**
@@ -2396,7 +3321,7 @@ var StorageManager = class _StorageManager {
    * helpers are injected into the store).
    */
   get tombstonesPath() {
-    return path.join(this.stateDir, "tombstones.jsonl");
+    return path3.join(this.stateDir, "tombstones.jsonl");
   }
   /**
    * Configure the tombstone invariant for this storage instance. Installed
@@ -2595,7 +3520,7 @@ var StorageManager = class _StorageManager {
         );
       }
       await factHashIndex.save();
-      await mkdir(path.dirname(this.factHashIndexReadyPath), { recursive: true });
+      await mkdir(path3.dirname(this.factHashIndexReadyPath), { recursive: true });
       await writeFile(this.factHashIndexReadyPath, "v1\n", "utf-8");
       this.factHashIndexAuthoritative = true;
     })().finally(() => {
@@ -2604,55 +3529,55 @@ var StorageManager = class _StorageManager {
     await this.factHashIndexAuthoritativePromise;
   }
   get questionsDir() {
-    return path.join(this.baseDir, "questions");
+    return path3.join(this.baseDir, "questions");
   }
   get artifactsDir() {
-    return path.join(this.baseDir, "artifacts");
+    return path3.join(this.baseDir, "artifacts");
   }
   get identityDir() {
-    return path.join(this.baseDir, "identity");
+    return path3.join(this.baseDir, "identity");
   }
   get identityAnchorPath() {
-    return path.join(this.identityDir, "identity-anchor.md");
+    return path3.join(this.identityDir, "identity-anchor.md");
   }
   get identityIncidentsDir() {
-    return path.join(this.identityDir, "incidents");
+    return path3.join(this.identityDir, "incidents");
   }
   get identityAuditsWeeklyDir() {
-    return path.join(this.identityDir, "audits", "weekly");
+    return path3.join(this.identityDir, "audits", "weekly");
   }
   get identityAuditsMonthlyDir() {
-    return path.join(this.identityDir, "audits", "monthly");
+    return path3.join(this.identityDir, "audits", "monthly");
   }
   get identityImprovementLoopsPath() {
-    return path.join(this.identityDir, "improvement-loops.md");
+    return path3.join(this.identityDir, "improvement-loops.md");
   }
   get identityReflectionsPath() {
-    return path.join(this.identityDir, "reflections.md");
+    return path3.join(this.identityDir, "reflections.md");
   }
   get profilePath() {
-    return path.join(this.baseDir, "profile.md");
+    return path3.join(this.baseDir, "profile.md");
   }
   get memoryActionsPath() {
-    return path.join(this.stateDir, "memory-actions.jsonl");
+    return path3.join(this.stateDir, "memory-actions.jsonl");
   }
   get memoryLifecycleLedgerPath() {
-    return path.join(this.stateDir, "memory-lifecycle-ledger.jsonl");
+    return path3.join(this.stateDir, "memory-lifecycle-ledger.jsonl");
   }
   get compressionGuidelinesPath() {
-    return path.join(this.stateDir, "compression-guidelines.md");
+    return path3.join(this.stateDir, "compression-guidelines.md");
   }
   get compressionGuidelineDraftPath() {
-    return path.join(this.stateDir, "compression-guidelines.draft.md");
+    return path3.join(this.stateDir, "compression-guidelines.draft.md");
   }
   get compressionGuidelineStatePath() {
-    return path.join(this.stateDir, "compression-guideline-state.json");
+    return path3.join(this.stateDir, "compression-guideline-state.json");
   }
   get compressionGuidelineDraftStatePath() {
-    return path.join(this.stateDir, "compression-guideline-draft-state.json");
+    return path3.join(this.stateDir, "compression-guideline-draft-state.json");
   }
   get behaviorSignalsPath() {
-    return path.join(this.stateDir, "behavior-signals.jsonl");
+    return path3.join(this.stateDir, "behavior-signals.jsonl");
   }
   /**
    * Buffer surprise telemetry ledger (issue #563 PR 3).
@@ -2665,7 +3590,7 @@ var StorageManager = class _StorageManager {
    * governance sweeps can treat it uniformly.
    */
   get bufferSurpriseLedgerPath() {
-    return path.join(this.stateDir, "buffer-surprise-ledger.jsonl");
+    return path3.join(this.stateDir, "buffer-surprise-ledger.jsonl");
   }
   /**
    * Entity alias table loaded from THIS store's config/aliases.json.
@@ -2675,9 +3600,11 @@ var StorageManager = class _StorageManager {
    * store loaded last rewrite every other store's canonical entity ids.
    */
   userAliases = {};
-  /** Normalize an entity name using this store's alias table. */
   normalizeEntityName(raw, type) {
-    return normalizeEntityName(raw, type, this.userAliases);
+    return this.entityStore.normalizeEntityName(
+      raw,
+      type
+    );
   }
   /**
    * Read-only view of this store's user alias table, for call sites that
@@ -2697,7 +3624,7 @@ var StorageManager = class _StorageManager {
     this.loadAliasesSync();
   }
   loadAliasesSync() {
-    const aliasPath = path.join(this.baseDir, "config", "aliases.json");
+    const aliasPath = path3.join(this.baseDir, "config", "aliases.json");
     this.userAliases = {};
     try {
       const raw = readFileSync(aliasPath, "utf-8");
@@ -2722,9 +3649,9 @@ var StorageManager = class _StorageManager {
   }
   async ensureDirectories() {
     const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
-    await mkdir(path.join(this.factsDir, today), { recursive: true });
-    await mkdir(path.join(this.proceduresDir, today), { recursive: true });
-    await mkdir(path.join(this.reasoningTracesDir, today), { recursive: true });
+    await mkdir(path3.join(this.factsDir, today), { recursive: true });
+    await mkdir(path3.join(this.proceduresDir, today), { recursive: true });
+    await mkdir(path3.join(this.reasoningTracesDir, today), { recursive: true });
     await mkdir(this.correctionsDir, { recursive: true });
     await mkdir(this.entitiesDir, { recursive: true });
     await mkdir(this.stateDir, { recursive: true });
@@ -2734,7 +3661,7 @@ var StorageManager = class _StorageManager {
     await mkdir(this.identityIncidentsDir, { recursive: true });
     await mkdir(this.identityAuditsWeeklyDir, { recursive: true });
     await mkdir(this.identityAuditsMonthlyDir, { recursive: true });
-    await mkdir(path.join(this.baseDir, "config"), { recursive: true });
+    await mkdir(path3.join(this.baseDir, "config"), { recursive: true });
   }
   /**
    * Resolve the on-disk write path for a memory of the given category, creating
@@ -2751,11 +3678,11 @@ var StorageManager = class _StorageManager {
   async resolveCategoryWritePath(category, id, today) {
     if (category === "correction") {
       await mkdir(this.correctionsDir, { recursive: true });
-      return path.join(this.correctionsDir, `${id}.md`);
+      return path3.join(this.correctionsDir, `${id}.md`);
     }
-    const datedDir = path.join(getCategoryDir(this.baseDir, category), today);
+    const datedDir = path3.join(getCategoryDir(this.baseDir, category), today);
     await mkdir(datedDir, { recursive: true });
-    return path.join(datedDir, `${id}.md`);
+    return path3.join(datedDir, `${id}.md`);
   }
   async writeMemory(category, content, options = {}) {
     await this.ensureDirectories();
@@ -3005,7 +3932,7 @@ ${sanitized.text}
     await this.ensureDirectories();
     const now = /* @__PURE__ */ new Date();
     const day = now.toISOString().slice(0, 10);
-    const dir = path.join(this.artifactsDir, day);
+    const dir = path3.join(this.artifactsDir, day);
     await mkdir(dir, { recursive: true });
     const id = `artifact-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`;
     const fm = {
@@ -3029,7 +3956,7 @@ ${sanitized.text}
       log.warn(`artifact content rejected for ${id}; violations=${sanitized.violations.join(", ")}`);
       return "";
     }
-    const filePath = path.join(dir, `${id}.md`);
+    const filePath = path3.join(dir, `${id}.md`);
     await this.writeStorageSecureFile(filePath, `${serializeFrontmatter(fm)}
 
 ${sanitized.text}
@@ -3048,45 +3975,7 @@ ${sanitized.text}
     return id;
   }
   async readAllArtifactsCached() {
-    if (this.artifactIndexCache && Date.now() - this.artifactIndexCache.loadedAtMs <= _StorageManager.ARTIFACT_INDEX_CACHE_TTL_MS && this.artifactIndexCache.writeVersion === this.getArtifactWriteVersion()) {
-      return this.artifactIndexCache.memories;
-    }
-    const scanArtifacts = async () => {
-      const artifacts = [];
-      const readDir = async (dir) => {
-        try {
-          const entries = await readdir(dir, { withFileTypes: true });
-          for (const entry of entries) {
-            const fullPath = path.join(dir, entry.name);
-            if (entry.isDirectory()) {
-              await readDir(fullPath);
-              continue;
-            }
-            if (!entry.name.endsWith(".md")) continue;
-            const memory = await this.readMemoryByPath(fullPath);
-            if (!memory) continue;
-            artifacts.push(memory);
-          }
-        } catch {
-        }
-      };
-      await readDir(this.artifactsDir);
-      return artifacts;
-    };
-    const MAX_REBUILD_RETRIES = 2;
-    let latestArtifacts = [];
-    for (let attempt = 0; attempt <= MAX_REBUILD_RETRIES; attempt += 1) {
-      const versionBefore = this.getArtifactWriteVersion();
-      const artifacts = await scanArtifacts();
-      const versionAfter = this.getArtifactWriteVersion();
-      latestArtifacts = artifacts;
-      if (versionAfter === versionBefore) {
-        this.artifactIndexCache = { memories: artifacts, loadedAtMs: Date.now(), writeVersion: versionAfter };
-        return artifacts;
-      }
-    }
-    this.artifactIndexCache = null;
-    return latestArtifacts;
+    return this.memoryReadStore.readAllArtifactsCached();
   }
   async searchArtifacts(query, maxResults) {
     const tokens = tokenizeArtifactSearchText(query);
@@ -3106,107 +3995,12 @@ ${sanitized.text}
     return hits.slice(0, maxResults).map((h) => h.memory);
   }
   async writeEntity(name, type, facts, options = {}) {
-    await this.ensureDirectories();
-    if (typeof name !== "string" || !name.trim() || typeof type !== "string" || !type.trim()) {
-      log.warn("writeEntity: invalid entity payload, skipping", {
-        nameType: typeof name,
-        typeType: typeof type
-      });
-      return "";
-    }
-    const safeFacts = Array.isArray(facts) ? [...new Set(
-      facts.filter((fact) => typeof fact === "string").map((fact) => fact.trim()).filter((fact) => fact.length > 0)
-    )] : [];
-    let normalized = this.normalizeEntityName(name, type);
-    const match = await this.findMatchingEntity(name, type);
-    if (match && match !== normalized) {
-      log.debug(`fuzzy match: "${normalized}" \u2192 existing "${match}"`);
-      normalized = match;
-    }
-    const filePath = path.join(this.entitiesDir, `${normalized}.md`);
-    let entity = {
+    return this.entityStore.writeEntity(
       name,
       type,
-      created: "",
-      updated: (/* @__PURE__ */ new Date()).toISOString(),
-      facts: [],
-      summary: void 0,
-      synthesis: void 0,
-      synthesisUpdatedAt: void 0,
-      synthesisVersion: void 0,
-      synthesisStructuredFactCount: void 0,
-      synthesisStructuredFactDigest: void 0,
-      timeline: [],
-      relationships: [],
-      activity: [],
-      aliases: []
-    };
-    try {
-      const existing = await this.readStorageSecureFile(filePath);
-      entity = parseEntityFile(existing, this.entitySchemas);
-    } catch (err) {
-      if (err instanceof SecureStoreLockedError) throw err;
-      if (!isErrnoCode(err, "ENOENT")) throw err;
-    }
-    const timestamp = options.timestamp?.trim() || (/* @__PURE__ */ new Date()).toISOString();
-    const source = options.source?.trim() || void 0;
-    const sessionKey = options.sessionKey?.trim() || void 0;
-    const principal = options.principal?.trim() || void 0;
-    const structuredSectionMap = new Map(
-      (entity.structuredSections ?? []).map((section) => [section.key, {
-        ...section,
-        facts: [...section.facts]
-      }])
-    );
-    for (const section of options.structuredSections ?? []) {
-      const normalizedSection = normalizeEntityStructuredSection(type, section, this.entitySchemas);
-      const normalizedFacts = normalizeStructuredSectionFacts(section.facts);
-      if (normalizedFacts.length === 0) continue;
-      const existingSection = structuredSectionMap.get(normalizedSection.key);
-      if (!existingSection) {
-        structuredSectionMap.set(normalizedSection.key, {
-          key: normalizedSection.key,
-          title: normalizedSection.title,
-          facts: normalizedFacts
-        });
-        continue;
-      }
-      existingSection.facts = normalizeStructuredSectionFacts([...existingSection.facts, ...normalizedFacts]);
-      if (!existingSection.title.trim() && normalizedSection.title.trim()) {
-        existingSection.title = normalizedSection.title;
-      }
-    }
-    for (const fact of safeFacts) {
-      const nextEntry = {
-        timestamp,
-        text: fact,
-        ...source ? { source } : {},
-        ...sessionKey ? { sessionKey } : {},
-        ...principal ? { principal } : {}
-      };
-      const alreadyPresent = entity.timeline.some(
-        (entry) => entry.timestamp === nextEntry.timestamp && entry.text === nextEntry.text && entry.source === nextEntry.source && entry.sessionKey === nextEntry.sessionKey && entry.principal === nextEntry.principal
-      );
-      if (alreadyPresent) continue;
-      entity.timeline.push(nextEntry);
-    }
-    entity.structuredSections = sortStructuredSectionsBySchema(
-      type,
-      Array.from(structuredSectionMap.values()).filter((section) => section.facts.length > 0),
-      this.entitySchemas
+      facts,
+      options
     );
-    entity.facts = compileEntityFacts(entity.timeline, entity.structuredSections);
-    entity.summary = entity.synthesis || entity.summary;
-    entity.name = name;
-    entity.type = type;
-    entity.created = entity.created || timestamp;
-    entity.updated = (/* @__PURE__ */ new Date()).toISOString();
-    await this.snapshotBeforeWrite(filePath, "write");
-    await this.writeStorageSecureFile(filePath, serializeEntityFile(entity, this.entitySchemas));
-    this.invalidateKnowledgeIndexCache();
-    this.bumpMemoryStatusVersion();
-    log.debug(`wrote entity ${normalized}`);
-    return normalized;
   }
   async readProfile() {
     try {
@@ -3364,7 +4158,7 @@ ${sanitized.text}
    * per-process in-memory cache safe across process boundaries.
    */
   invalidateColdMemoriesCache() {
-    const coldRoot = path.join(this.baseDir, "cold");
+    const coldRoot = path3.join(this.baseDir, "cold");
     _StorageManager.coldMemoriesCache.delete(coldRoot);
     this.bumpColdWriteVersion();
     invalidateAllForDir(this.baseDir);
@@ -3387,45 +4181,7 @@ ${sanitized.text}
     return Math.max(1, Math.floor(batchSize));
   }
   async collectActiveMemoryPaths() {
-    const filePaths = [];
-    let memoryRootReal;
-    try {
-      memoryRootReal = await realpath(this.baseDir);
-    } catch {
-      return filePaths;
-    }
-    const collectPaths = async (dir) => {
-      let entries;
-      try {
-        const dirStat = await lstat(dir);
-        if (dirStat.isSymbolicLink() || !dirStat.isDirectory()) return;
-        assertPathInsideRoot(memoryRootReal, await realpath(dir), dir);
-        entries = await readdir(dir, { withFileTypes: true });
-      } catch {
-        return;
-      }
-      const subdirs = [];
-      for (const entry of entries) {
-        if (entry.isSymbolicLink()) continue;
-        const fullPath = path.join(dir, entry.name);
-        if (entry.isDirectory()) {
-          subdirs.push(fullPath);
-        } else if (entry.name.endsWith(".md")) {
-          try {
-            assertPathInsideRoot(memoryRootReal, await realpath(fullPath), fullPath);
-            filePaths.push(fullPath);
-          } catch {
-          }
-        }
-      }
-      for (const subdir of subdirs) {
-        await collectPaths(subdir);
-      }
-    };
-    for (const dir of RECALL_FALLBACK_DIRS) {
-      await collectPaths(path.join(this.baseDir, dir));
-    }
-    return filePaths;
+    return this.memoryReadStore.collectActiveMemoryPaths();
   }
   async readParsedMemoriesFromPaths(filePaths, batchSize) {
     if (filePaths.length === 0) return [];
@@ -3480,7 +4236,7 @@ ${sanitized.text}
         return updatedMs >= updatedAfterMs ? filePath : null;
       }
       try {
-        const fileStat = await stat(filePath);
+        const fileStat = await stat2(filePath);
         return fileStat.mtimeMs >= updatedAfterMs ? filePath : null;
       } catch {
         return filePath;
@@ -3492,7 +4248,7 @@ ${sanitized.text}
     const correctionPaths = [];
     const factPaths = [];
     for (const filePath of filePaths) {
-      if (filePath === this.correctionsDir || filePath.startsWith(`${this.correctionsDir}${path.sep}`)) {
+      if (filePath === this.correctionsDir || filePath.startsWith(`${this.correctionsDir}${path3.sep}`)) {
         correctionPaths.push(filePath);
       } else {
         factPaths.push(filePath);
@@ -3534,103 +4290,18 @@ ${sanitized.text}
     }
     return { memories, filePaths };
   }
-  async readMemoriesWindow(options = {}) {
-    const allPaths = await this.collectActiveMemoryPaths();
-    const sortedPaths = this.orderWindowPaths(allPaths);
-    const maxMemories = typeof options.maxMemories === "number" && Number.isFinite(options.maxMemories) ? Math.max(1, Math.floor(options.maxMemories)) : void 0;
-    const maxCandidatePaths = maxMemories === void 0 ? void 0 : maxMemories * 2;
-    const updatedAfterMs = options.updatedAfter?.getTime();
-    const normalizedBatchSize = this.normalizeMemoryReadBatchSize(options.batchSize);
-    const memories = [];
-    const selectedPaths = [];
-    for (let i = 0; i < sortedPaths.length; i += normalizedBatchSize) {
-      if (maxMemories !== void 0 && (memories.length >= maxMemories || maxCandidatePaths !== void 0 && selectedPaths.length >= maxCandidatePaths)) {
-        return { memories, filePaths: selectedPaths };
-      }
-      const batchPaths = sortedPaths.slice(i, i + normalizedBatchSize);
-      const candidateBatchPaths = updatedAfterMs === void 0 ? batchPaths : await this.filterWindowPathsByUpdatedAfter(batchPaths, updatedAfterMs);
-      const remainingSlots = maxMemories === void 0 ? void 0 : Math.max(0, maxMemories - memories.length);
-      const remainingInspectionBudget = maxCandidatePaths === void 0 ? void 0 : Math.max(0, maxCandidatePaths - selectedPaths.length);
-      const { memories: batchMemories, filePaths: parsedCandidatePaths } = remainingSlots === void 0 ? {
-        memories: await this.readParsedMemoriesFromPaths(candidateBatchPaths, normalizedBatchSize),
-        filePaths: candidateBatchPaths
-      } : await this.readWindowBoundedBatch(
-        candidateBatchPaths,
-        remainingSlots,
-        remainingInspectionBudget ?? remainingSlots,
-        normalizedBatchSize
-      );
-      selectedPaths.push(...parsedCandidatePaths);
-      for (const memory of batchMemories) {
-        memories.push(memory);
-        if (maxMemories !== void 0 && memories.length >= maxMemories) {
-          return { memories, filePaths: selectedPaths };
-        }
-      }
-    }
-    return { memories, filePaths: selectedPaths };
-  }
-  async _readAllMemoriesFromDisk() {
-    const filePaths = await this.collectActiveMemoryPaths();
-    return this.readParsedMemoriesFromPaths(filePaths, 50);
-  }
-  /**
-   * Read all memories from the cold tier by scanning the entire cold/ root
-   * tree.  Previously this only scanned cold/facts/ and cold/corrections/, but
-   * structuredAttributes can appear on any MemoryCategory (preference, decision,
-   * entity, etc.).  buildTierMemoryPath now routes each category to its own
-   * cold/<dir>/ subtree via the shared categoryDirName() chokepoint (issue
-   * #1546), so cold decisions/preferences/... live outside cold/facts/.
-   * Scanning the full coldRoot covers every category dir and guards against
-   * files placed in unexpected subdirectories during manual operations or future
-   * refactors.
-   *
-   * Broadened in PR #402 round-6 (Finding UTsP): scanning only facts/ and
-   * corrections/ was a narrower-than-necessary subset of the cold directory
-   * tree.  Correctness trumps the minor performance difference — cold scans
-   * already happen at most once per supersession write.
-   *
-   * Used by applyTemporalSupersession so that memories already demoted to
-   * cold/ can still be marked superseded when a newer hot fact arrives.
-   *
-   * Cached with a TTL (Finding UOGi, PR #402 round-6): back-to-back
-   * structured-attribute writes in the same burst reuse the cached result
-   * instead of re-scanning the cold tree on every call.  The cache is
-   * invalidated whenever a write calls invalidateAllMemoriesCache() (which
-   * covers any hot→cold demotion that changes cold-tier contents) and
-   * expires after COLD_SCAN_CACHE_TTL_MS as a safety net.
-   */
-  async readAllColdMemories() {
-    const coldRoot = this.resolveTierRootDir("cold");
-    const currentColdVersion = this.readColdWriteVersion();
-    const cached = _StorageManager.coldMemoriesCache.get(coldRoot);
-    if (cached && Date.now() - cached.loadedAt < _StorageManager.COLD_SCAN_CACHE_TTL_MS && cached.coldVersion === currentColdVersion) {
-      return cached.memories;
-    }
-    const filePaths = [];
-    const collectPaths = async (dir) => {
-      try {
-        const entries = await readdir(dir, { withFileTypes: true });
-        const subdirs = [];
-        for (const entry of entries) {
-          const fullPath = path.join(dir, entry.name);
-          if (entry.isDirectory()) {
-            subdirs.push(fullPath);
-          } else if (entry.name.endsWith(".md")) {
-            filePaths.push(fullPath);
-          }
-        }
-        for (const subdir of subdirs) {
-          await collectPaths(subdir);
-        }
-      } catch {
-      }
-    };
-    await collectPaths(coldRoot);
-    const memories = await this.readParsedMemoriesFromPaths(filePaths, 50);
-    _StorageManager.coldMemoriesCache.set(coldRoot, { memories, loadedAt: Date.now(), coldVersion: currentColdVersion });
-    return memories;
-  }
+  async readMemoriesWindow(options = {}) {
+    return this.memoryReadStore.readMemoriesWindow(
+      options
+    );
+  }
+  async _readAllMemoriesFromDisk() {
+    const filePaths = await this.collectActiveMemoryPaths();
+    return this.readParsedMemoriesFromPaths(filePaths, 50);
+  }
+  async readAllColdMemories() {
+    return this.memoryReadStore.readAllColdMemories();
+  }
   /**
    * Read archived memory markdown files under archive/.
    * Used by long-term recall fallback when hot recall has no hits.
@@ -3640,9 +4311,9 @@ ${sanitized.text}
     const root = this.archiveDir;
     const readDir = async (dir) => {
       try {
-        const entries = await readdir(dir, { withFileTypes: true });
+        const entries = await readdir3(dir, { withFileTypes: true });
         for (const entry of entries) {
-          const fullPath = path.join(dir, entry.name);
+          const fullPath = path3.join(dir, entry.name);
           if (entry.isDirectory()) {
             await readDir(fullPath);
           } else if (entry.name.endsWith(".md")) {
@@ -3671,51 +4342,13 @@ ${sanitized.text}
     await readDir(root);
     return memories;
   }
-  /** Read a single memory file by its absolute path. Returns null if unreadable. */
   async readMemoryByPath(filePath) {
-    try {
-      const raw = await readMaybeEncryptedFile(filePath, this._secureStoreKey, this.baseDir);
-      const parsed = parseFrontmatter(raw);
-      if (parsed) {
-        return {
-          path: filePath,
-          frontmatter: normalizeFrontmatterForPath(
-            parsed.frontmatter,
-            toMemoryPathRel(this.baseDir, filePath),
-            parsed.content
-          ),
-          content: parsed.content
-        };
-      }
-      const normalizedPath = filePath.split(path.sep).join("/");
-      if (normalizedPath.includes("/entities/") && filePath.endsWith(".md")) {
-        const entity = parseEntityFile(raw, this.entitySchemas);
-        if (!entity.name) return null;
-        const nameWithoutExt = path.basename(filePath, ".md");
-        const fileMtime = entity.updated || await stat(filePath).then((s) => s.mtime.toISOString()).catch(() => (/* @__PURE__ */ new Date(0)).toISOString());
-        return {
-          path: filePath,
-          frontmatter: {
-            id: nameWithoutExt,
-            category: "entity",
-            created: fileMtime,
-            updated: fileMtime,
-            source: "entity_extraction",
-            confidence: 0.9,
-            confidenceTier: confidenceTier(0.9),
-            tags: entity.type ? [entity.type] : []
-          },
-          content: raw
-        };
-      }
-      return null;
-    } catch (err) {
-      if (err instanceof SecureStoreLockedError) throw err;
-      return null;
-    }
+    return this.memoryReadStore.readMemoryByPath(
+      filePath
+    );
   }
   resolveTierRootDir(tier) {
-    return tier === "cold" ? path.join(this.baseDir, "cold") : this.baseDir;
+    return tier === "cold" ? path3.join(this.baseDir, "cold") : this.baseDir;
   }
   resolveMemoryDateDir(memory) {
     const preferred = memory.frontmatter.created || memory.frontmatter.updated;
@@ -3730,13 +4363,13 @@ ${sanitized.text}
   buildTierMemoryPath(memory, tier) {
     const root = this.resolveTierRootDir(tier);
     if (this.isArtifactMemory(memory)) {
-      return path.join(root, "artifacts", this.resolveMemoryDateDir(memory), `${memory.frontmatter.id}.md`);
+      return path3.join(root, "artifacts", this.resolveMemoryDateDir(memory), `${memory.frontmatter.id}.md`);
     }
     if (memory.frontmatter.category === "correction") {
-      return path.join(root, "corrections", `${memory.frontmatter.id}.md`);
+      return path3.join(root, "corrections", `${memory.frontmatter.id}.md`);
     }
     const dir = categoryDirName(memory.frontmatter.category);
-    return path.join(root, dir, this.resolveMemoryDateDir(memory), `${memory.frontmatter.id}.md`);
+    return path3.join(root, dir, this.resolveMemoryDateDir(memory), `${memory.frontmatter.id}.md`);
   }
   async writeMemoryFileAtomic(targetPath, memory) {
     const fileContent = `${serializeFrontmatter(memory.frontmatter)}
@@ -3749,11 +4382,11 @@ ${memory.content}
   }
   async moveMemoryToPath(memory, targetPath) {
     await this.writeMemoryFileAtomic(targetPath, memory);
-    const sourcePath = path.resolve(memory.path);
-    const destPath = path.resolve(targetPath);
+    const sourcePath = path3.resolve(memory.path);
+    const destPath = path3.resolve(targetPath);
     if (sourcePath !== destPath) {
       try {
-        await unlink(memory.path);
+        await unlink2(memory.path);
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);
         if (!message.includes("ENOENT")) {
@@ -3765,15 +4398,15 @@ ${memory.content}
   }
   async migrateMemoryToTier(memory, targetTier) {
     const targetPath = this.buildTierMemoryPath(memory, targetTier);
-    const sourcePath = path.resolve(memory.path);
-    const destPath = path.resolve(targetPath);
+    const sourcePath = path3.resolve(memory.path);
+    const destPath = path3.resolve(targetPath);
     if (sourcePath === destPath) {
       return { changed: false, targetPath };
     }
     const existing = await this.readMemoryByPath(targetPath);
     if (existing?.frontmatter.id === memory.frontmatter.id) {
       try {
-        await unlink(memory.path);
+        await unlink2(memory.path);
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);
         if (!message.includes("ENOENT")) {
@@ -3792,7 +4425,7 @@ ${memory.content}
     return { changed: true, targetPath };
   }
   get archiveDir() {
-    return path.join(this.baseDir, "archive");
+    return path3.join(this.baseDir, "archive");
   }
   /**
    * Archive a memory by moving it from facts/ to archive/YYYY-MM-DD/.
@@ -3803,7 +4436,7 @@ ${memory.content}
     try {
       const now = lifecycle?.at ?? /* @__PURE__ */ new Date();
       const today = now.toISOString().slice(0, 10);
-      const destDir = path.join(this.archiveDir, today);
+      const destDir = path3.join(this.archiveDir, today);
       await mkdir(destDir, { recursive: true });
       const updatedFm = {
         ...memory.frontmatter,
@@ -3815,9 +4448,9 @@ ${memory.content}
 
 ${memory.content}
 `;
-      const destPath = path.join(destDir, path.basename(memory.path));
+      const destPath = path3.join(destDir, path3.basename(memory.path));
       await this.writeStorageSecureFile(destPath, fileContent);
-      await unlink(memory.path);
+      await unlink2(memory.path);
       this.invalidateAllMemoriesCache();
       await this.appendGeneratedMemoryLifecycleEventFailOpen(
         "storage.archiveMemory",
@@ -3844,33 +4477,19 @@ ${memory.content}
   }
   async readEntities() {
     try {
-      const entries = await readdir(this.entitiesDir);
+      const entries = await readdir3(this.entitiesDir);
       return entries.filter((e) => e.endsWith(".md")).map((e) => e.replace(".md", ""));
     } catch {
       return [];
     }
   }
   async readEntity(name) {
-    const filePath = this.resolveEntityFilePath(name);
-    if (filePath === null) {
-      return "";
-    }
-    try {
-      return await this.readStorageSecureFile(filePath);
-    } catch (err) {
-      if (err instanceof SecureStoreLockedError) throw err;
-      if (!isErrnoCode(err, "ENOENT")) throw err;
-      return "";
-    }
+    return this.entityStore.readEntity(
+      name
+    );
   }
-  /** Return sorted list of entity filenames (without .md extension) */
   async listEntityNames() {
-    try {
-      const entries = await readdir(this.entitiesDir);
-      return entries.filter((e) => e.endsWith(".md")).map((e) => e.replace(".md", "")).sort();
-    } catch {
-      return [];
-    }
+    return this.entityStore.listEntityNames();
   }
   /**
    * Find an existing entity that fuzzy-matches the proposed name.
@@ -3912,7 +4531,7 @@ ${memory.content}
     const memory = memories.find((m) => m.frontmatter.id === id);
     if (!memory) return false;
     try {
-      await unlink(memory.path);
+      await unlink2(memory.path);
       this.invalidateAllMemoriesCache();
       this.bumpMemoryStatusVersion();
       log.debug(`invalidated memory ${id}`);
@@ -3977,7 +4596,7 @@ ${memory.content}
 `;
     await this.writeStorageSecureFile(memory.path, fileContent);
     this.invalidateAllMemoriesCache();
-    if (memory.path.includes(`${path.sep}cold${path.sep}`)) {
+    if (memory.path.includes(`${path3.sep}cold${path3.sep}`)) {
       this.invalidateColdMemoriesCache();
     }
     try {
@@ -4035,7 +4654,7 @@ ${memory.content}
       const expiresAt = new Date(m.frontmatter.expiresAt).getTime();
       if (expiresAt < now) {
         try {
-          await unlink(m.path);
+          await unlink2(m.path);
           deleted.push(m);
           log.debug(`cleaned expired memory ${m.frontmatter.id} (TTL expired)`);
         } catch {
@@ -4049,7 +4668,7 @@ ${memory.content}
     return deleted;
   }
   async loadBuffer() {
-    const bufferPath = path.join(this.stateDir, "buffer.json");
+    const bufferPath = path3.join(this.stateDir, "buffer.json");
     try {
       const raw = await this.readStorageSecureFile(bufferPath);
       return JSON.parse(raw);
@@ -4061,11 +4680,11 @@ ${memory.content}
   }
   async saveBuffer(state) {
     await this.ensureDirectories();
-    const bufferPath = path.join(this.stateDir, "buffer.json");
+    const bufferPath = path3.join(this.stateDir, "buffer.json");
     await this.writeStorageSecureFile(bufferPath, JSON.stringify(state, null, 2));
   }
   async loadMeta() {
-    const metaPath = path.join(this.stateDir, "meta.json");
+    const metaPath = path3.join(this.stateDir, "meta.json");
     try {
       const raw = await this.readStorageSecureFile(metaPath);
       const parsed = JSON.parse(raw);
@@ -4099,7 +4718,7 @@ ${memory.content}
   }
   async saveMeta(state) {
     await this.ensureDirectories();
-    const metaPath = path.join(this.stateDir, "meta.json");
+    const metaPath = path3.join(this.stateDir, "meta.json");
     await this.writeStorageSecureFile(metaPath, JSON.stringify(state, null, 2));
   }
   async appendMemoryActionEvents(events) {
@@ -4132,99 +4751,15 @@ ${memory.content}
     await this.appendStorageSecureFile(this.memoryLifecycleLedgerPath, payload);
     return events.length;
   }
-  /**
-   * Append a batch of `BUFFER_SURPRISE` telemetry events (issue #563 PR 3).
-   *
-   * Each event records a single buffer flush decision driven by the
-   * surprise gate. The ledger is consumed by
-   * `reportBufferSurpriseDistribution` (Doctor report) and by downstream
-   * benchmark analysis. This method is fire-and-forget by contract:
-   * callers log but do not fail the hot path if the append throws.
-   */
   async appendBufferSurpriseEvents(events) {
-    if (events.length === 0) return 0;
-    await this.ensureDirectories();
-    const nowIso = (/* @__PURE__ */ new Date()).toISOString();
-    const payload = events.map((event) => {
-      const normalized = {
-        ...event,
-        event: "BUFFER_SURPRISE",
-        timestamp: event.timestamp && event.timestamp.length > 0 ? event.timestamp : nowIso
-      };
-      return `${JSON.stringify(normalized)}
-`;
-    }).join("");
-    await this.appendStorageSecureFile(this.bufferSurpriseLedgerPath, payload);
-    return events.length;
+    return this.memoryReadStore.appendBufferSurpriseEvents(
+      events
+    );
   }
-  /**
-   * Read the buffer-surprise ledger, most recent rows last.
-   *
-   * `limit` bounds the number of **valid rows** returned (not the
-   * number of raw lines parsed). We parse every row, discard malformed
-   * ones, then take the tail — so a partial/truncated trailing line
-   * (the common failure mode after an interrupted append) cannot hide
-   * otherwise-valid recent data above it.
-   *
-   * Non-positive / non-integer / non-finite limits return `[]` rather
-   * than the entire file, matching the other ledger readers in this
-   * class and protecting against `slice(-0.5)` → `slice(-0)` silently
-   * devolving into an unbounded parse.
-   *
-   * # Performance note
-   *
-   * For very large ledgers (issue #563 follow-up), a tail-first reader
-   * would avoid parsing the full file when only a recent window is
-   * needed. We keep the full-scan implementation here because:
-   *
-   *   - the ledger is opt-in (flag off by default), so early deployments
-   *     accumulate rows slowly;
-   *   - telemetry rows are small (~200 bytes), so even 100k rows parse
-   *     in well under a second;
-   *   - the governance archive/cleanup flow can trim the ledger when
-   *     size becomes a concern, reusing the existing maintenance hooks.
-   *
-   * Swap to a chunked tail-reader if production logs show this is a
-   * hot path — leaving that work for a follow-up keeps this PR scoped
-   * to correctness, not optimization.
-   */
   async readBufferSurpriseEvents(options = {}) {
-    let raw;
-    try {
-      raw = await this.readStorageSecureFile(this.bufferSurpriseLedgerPath);
-    } catch (err) {
-      if (err instanceof SecureStoreLockedError) throw err;
-      const code = err.code;
-      if (code === "ENOENT") return [];
-      throw err;
-    }
-    let effectiveLimit = null;
-    if (options.limit !== void 0) {
-      if (typeof options.limit !== "number" || !Number.isFinite(options.limit) || options.limit <= 0) {
-        return [];
-      }
-      const floored = Math.floor(options.limit);
-      if (floored <= 0) return [];
-      effectiveLimit = floored;
-    }
-    const lines = raw.split("\n");
-    const events = [];
-    for (const line of lines) {
-      const trimmed = line.trim();
-      if (trimmed.length === 0) continue;
-      try {
-        const parsed = JSON.parse(trimmed);
-        if (isValidBufferSurpriseEvent(parsed)) {
-          events.push(parsed);
-        }
-      } catch {
-      }
-    }
-    events.sort(
-      (left, right) => Date.parse(left.timestamp) - Date.parse(right.timestamp)
+    return this.memoryReadStore.readBufferSurpriseEvents(
+      options
     );
-    if (effectiveLimit === null) return events;
-    return events.slice(-effectiveLimit);
   }
   async appendBehaviorSignals(events) {
     if (events.length === 0) return 0;
@@ -4269,7 +4804,7 @@ ${memory.content}
   async appendReextractJobs(events) {
     if (events.length === 0) return 0;
     await this.ensureDirectories();
-    const filePath = path.join(this.stateDir, "reextract-jobs.jsonl");
+    const filePath = path3.join(this.stateDir, "reextract-jobs.jsonl");
     const lines = events.map((event) => JSON.stringify(event)).join("\n") + "\n";
     try {
       await this.appendStorageSecureFile(filePath, lines);
@@ -4282,7 +4817,7 @@ ${memory.content}
   }
   async readReextractJobs(limit = 200) {
     const safeLimit = Number.isFinite(limit) ? Math.max(1, Math.min(1e3, Math.floor(limit))) : 200;
-    const filePath = path.join(this.stateDir, "reextract-jobs.jsonl");
+    const filePath = path3.join(this.stateDir, "reextract-jobs.jsonl");
     try {
       const raw = await this.readStorageSecureFile(filePath);
       const lines = raw.split("\n").filter((line) => line.trim().length > 0);
@@ -4463,59 +4998,15 @@ ${memory.content}
       activationState: "active"
     });
     await Promise.all([
-      unlink(this.compressionGuidelineDraftPath).catch(() => void 0),
-      unlink(this.compressionGuidelineDraftStatePath).catch(() => void 0)
+      unlink2(this.compressionGuidelineDraftPath).catch(() => void 0),
+      unlink2(this.compressionGuidelineDraftStatePath).catch(() => void 0)
     ]);
     return true;
   }
   async readCompressionGuidelineStateFile(filePath) {
-    const isFiniteNonNegativeInteger = (value) => typeof value === "number" && Number.isFinite(value) && Number.isInteger(value) && value >= 0;
-    const isValidActionSummary = (value) => {
-      if (!value || typeof value !== "object") return false;
-      const summary = value;
-      return typeof summary.action === "string" && isFiniteNonNegativeInteger(summary.total) && summary.outcomes !== null && typeof summary.outcomes === "object" && isFiniteNonNegativeInteger(summary.outcomes.applied) && isFiniteNonNegativeInteger(summary.outcomes.skipped) && isFiniteNonNegativeInteger(summary.outcomes.failed) && summary.quality !== null && typeof summary.quality === "object" && isFiniteNonNegativeInteger(summary.quality.good) && isFiniteNonNegativeInteger(summary.quality.poor) && isFiniteNonNegativeInteger(summary.quality.unknown);
-    };
-    const isValidRuleUpdate = (value) => {
-      if (!value || typeof value !== "object") return false;
-      const rule = value;
-      return typeof rule.action === "string" && typeof rule.delta === "number" && Number.isFinite(rule.delta) && (rule.direction === "increase" || rule.direction === "decrease" || rule.direction === "hold") && (rule.confidence === "low" || rule.confidence === "medium" || rule.confidence === "high") && Array.isArray(rule.notes) && rule.notes.every((note) => typeof note === "string");
-    };
-    try {
-      const raw = await this.readStorageSecureFile(filePath);
-      const parsed = JSON.parse(raw);
-      const sourceWindow = parsed?.sourceWindow;
-      const eventCounts = parsed?.eventCounts;
-      const activationState = parsed?.activationState === "draft" || parsed?.activationState === "active" ? parsed.activationState : void 0;
-      const contentHash = typeof parsed?.contentHash === "string" && parsed.contentHash.length > 0 ? parsed.contentHash : void 0;
-      const actionSummaries = Array.isArray(parsed?.actionSummaries) ? parsed.actionSummaries.filter(isValidActionSummary) : void 0;
-      const ruleUpdates = Array.isArray(parsed?.ruleUpdates) ? parsed.ruleUpdates.filter(isValidRuleUpdate) : void 0;
-      if (!isFiniteNonNegativeInteger(parsed?.version) || typeof parsed?.updatedAt !== "string" || parsed.updatedAt.length === 0 || !sourceWindow || typeof sourceWindow.from !== "string" || sourceWindow.from.length === 0 || typeof sourceWindow.to !== "string" || sourceWindow.to.length === 0 || !eventCounts || !isFiniteNonNegativeInteger(eventCounts.total) || !isFiniteNonNegativeInteger(eventCounts.applied) || !isFiniteNonNegativeInteger(eventCounts.skipped) || !isFiniteNonNegativeInteger(eventCounts.failed) || !isFiniteNonNegativeInteger(parsed?.guidelineVersion)) {
-        return null;
-      }
-      return {
-        version: parsed.version,
-        updatedAt: parsed.updatedAt,
-        sourceWindow: {
-          from: sourceWindow.from,
-          to: sourceWindow.to
-        },
-        eventCounts: {
-          total: eventCounts.total,
-          applied: eventCounts.applied,
-          skipped: eventCounts.skipped,
-          failed: eventCounts.failed
-        },
-        guidelineVersion: parsed.guidelineVersion,
-        ...contentHash ? { contentHash } : {},
-        ...activationState ? { activationState } : {},
-        ...actionSummaries ? { actionSummaries } : {},
-        ...ruleUpdates ? { ruleUpdates } : {}
-      };
-    } catch (err) {
-      if (err instanceof SecureStoreLockedError) throw err;
-      if (!isErrnoCode(err, "ENOENT")) throw err;
-      return null;
-    }
+    return this.memoryReadStore.readCompressionGuidelineStateFile(
+      filePath
+    );
   }
   async writeIdentityAnchor(content) {
     await this.ensureDirectories();
@@ -4536,7 +5027,7 @@ ${memory.content}
     const date = nowIso.slice(0, 10);
     const id = this.generateId("incident");
     const incident = createContinuityIncidentRecord(id, input, nowIso);
-    const filePath = path.join(this.identityIncidentsDir, `${date}-${id}.md`);
+    const filePath = path3.join(this.identityIncidentsDir, `${date}-${id}.md`);
     await this.writeStorageSecureFile(filePath, serializeContinuityIncident(incident));
     return { ...incident, filePath };
   }
@@ -4549,7 +5040,7 @@ ${memory.content}
       const incidents = [];
       for (const file of candidates) {
         if (incidents.length >= cappedLimit) break;
-        const filePath = path.join(this.identityIncidentsDir, file);
+        const filePath = path3.join(this.identityIncidentsDir, file);
         try {
           const raw = await this.readStorageSecureFile(filePath);
           const parsed = parseContinuityIncident(raw);
@@ -4580,7 +5071,7 @@ ${memory.content}
     await this.ensureDirectories();
     const safeKey = this.sanitizeIdentityAuditKey(key);
     const dir = period === "weekly" ? this.identityAuditsWeeklyDir : this.identityAuditsMonthlyDir;
-    const filePath = path.join(dir, `${safeKey}.md`);
+    const filePath = path3.join(dir, `${safeKey}.md`);
     await this.writeStorageSecureFile(filePath, content);
     return filePath;
   }
@@ -4588,7 +5079,7 @@ ${memory.content}
     try {
       const safeKey = this.sanitizeIdentityAuditKey(key);
       const dir = period === "weekly" ? this.identityAuditsWeeklyDir : this.identityAuditsMonthlyDir;
-      return await this.readStorageSecureFile(path.join(dir, `${safeKey}.md`));
+      return await this.readStorageSecureFile(path3.join(dir, `${safeKey}.md`));
     } catch (err) {
       if (err instanceof Error && err.message === "Invalid identity audit key") return null;
       if (!isErrnoCode(err, "ENOENT")) throw err;
@@ -4635,7 +5126,7 @@ ${memory.content}
     return `${prefix}-${ts}-${rand}`;
   }
   async readContinuityIncidentFileNames() {
-    const files = await readdir(this.identityIncidentsDir);
+    const files = await readdir3(this.identityIncidentsDir);
     return files.filter((file) => file.endsWith(".md")).sort().reverse();
   }
   async readContinuityIncidentFile(filePath) {
@@ -4652,12 +5143,12 @@ ${memory.content}
     const fileNames = await this.readContinuityIncidentFileNames();
     const directMatch = fileNames.find((name) => name.endsWith(`-${id}.md`));
     if (directMatch) {
-      const directPath = path.join(this.identityIncidentsDir, directMatch);
+      const directPath = path3.join(this.identityIncidentsDir, directMatch);
       const parsed = await this.readContinuityIncidentFile(directPath);
       if (parsed?.id === id) return directPath;
     }
     for (const fileName of fileNames) {
-      const filePath = path.join(this.identityIncidentsDir, fileName);
+      const filePath = path3.join(this.identityIncidentsDir, fileName);
       const parsed = await this.readContinuityIncidentFile(filePath);
       if (parsed?.id === id) return filePath;
     }
@@ -4687,43 +5178,16 @@ ${question}
 
 **Context:** ${context}
 `;
-    const filePath = path.join(this.questionsDir, `${id}.md`);
+    const filePath = path3.join(this.questionsDir, `${id}.md`);
     await this.writeStorageSecureFile(filePath, content);
     log.debug(`wrote question ${id} to ${filePath}`);
     this.invalidateQuestionsCache();
     return id;
   }
   async readQuestions(opts) {
-    const cacheKey = this.questionsDir;
-    const cached = _StorageManager.questionsCache.get(cacheKey);
-    if (cached && Date.now() - cached.loadedAt < _StorageManager.QUESTIONS_CACHE_TTL_MS) {
-      try {
-        const dirStat = await stat(this.questionsDir);
-        if (dirStat.mtimeMs <= cached.loadedAt) {
-          const all = cached.questions;
-          return opts?.unresolvedOnly ? all.filter((q) => !q.resolved) : all;
-        }
-      } catch {
-      }
-    }
-    try {
-      const files = await readdir(this.questionsDir);
-      const questions = [];
-      for (const file of files) {
-        if (!file.endsWith(".md")) continue;
-        const filePath = path.join(this.questionsDir, file);
-        const raw = await readMaybeEncryptedFile(filePath, this._secureStoreKey, this.baseDir);
-        const parsed = this.parseQuestionFile(raw, filePath);
-        if (parsed) {
-          questions.push(parsed);
-        }
-      }
-      const sorted = questions.sort((a, b) => b.priority - a.priority);
-      _StorageManager.questionsCache.set(cacheKey, { questions: sorted, loadedAt: Date.now() });
-      return opts?.unresolvedOnly ? sorted.filter((q) => !q.resolved) : sorted;
-    } catch {
-      return [];
-    }
+    return this.memoryReadStore.readQuestions(
+      opts
+    );
   }
   /** Invalidate the questions cache (call after writing a question). */
   invalidateQuestionsCache() {
@@ -4734,7 +5198,7 @@ ${question}
     if (!match) return null;
     const frontmatterStr = match[1];
     const body = match[2].trim();
-    const id = this.extractFrontmatterValue(frontmatterStr, "id") ?? path.basename(filePath, ".md");
+    const id = this.extractFrontmatterValue(frontmatterStr, "id") ?? path3.basename(filePath, ".md");
     const created = this.extractFrontmatterValue(frontmatterStr, "created") ?? "";
     const priority = parseFloat(
       this.extractFrontmatterValue(frontmatterStr, "priority") ?? "0.5"
@@ -4796,11 +5260,11 @@ ${question}
     } catch {
     }
     const hygiene = opts?.hygiene;
-    const rotateEnabled = hygiene?.enabled === true && hygiene.rotateEnabled === true && Array.isArray(hygiene.rotatePaths) && hygiene.rotatePaths.includes(path.basename(identityPath));
+    const rotateEnabled = hygiene?.enabled === true && hygiene.rotateEnabled === true && Array.isArray(hygiene.rotatePaths) && hygiene.rotatePaths.includes(path3.basename(identityPath));
     if (rotateEnabled) {
       const maxBytes = hygiene.rotateMaxBytes;
       if (existing.length > maxBytes) {
-        const archiveDir = path.join(workspaceDir, hygiene.archiveDir);
+        const archiveDir = path3.join(workspaceDir, hygiene.archiveDir);
         const { newContent } = await rotateMarkdownFileToArchive({
           filePath: identityPath,
           archiveDir,
@@ -4894,7 +5358,7 @@ ${reflection}
    * Deduplicates by target+label.
    */
   async addEntityRelationship(name, rel) {
-    const filePath = path.join(this.entitiesDir, `${name}.md`);
+    const filePath = path3.join(this.entitiesDir, `${name}.md`);
     let entity;
     try {
       const content = await this.readStorageSecureFile(filePath);
@@ -4919,7 +5383,7 @@ ${reflection}
    * Prepends to the beginning, prunes oldest entries beyond maxEntries.
    */
   async addEntityActivity(name, entry, maxEntries) {
-    const filePath = path.join(this.entitiesDir, `${name}.md`);
+    const filePath = path3.join(this.entitiesDir, `${name}.md`);
     let entity;
     try {
       const content = await this.readStorageSecureFile(filePath);
@@ -4942,7 +5406,7 @@ ${reflection}
    * Add an alias to an entity file. Deduplicates.
    */
   async addEntityAlias(name, alias) {
-    const filePath = path.join(this.entitiesDir, `${name}.md`);
+    const filePath = path3.join(this.entitiesDir, `${name}.md`);
     let entity;
     try {
       const content = await this.readStorageSecureFile(filePath);
@@ -4959,40 +5423,12 @@ ${reflection}
     await this.writeStorageSecureFile(filePath, serializeEntityFile(entity, this.entitySchemas));
     this.invalidateKnowledgeIndexCache();
   }
-  /**
-   * Set or rewrite the synthesis layer of an entity file.
-   */
   async updateEntitySynthesis(name, synthesis, options = {}) {
-    const filePath = path.join(this.entitiesDir, `${name}.md`);
-    let entity;
-    try {
-      const content = await this.readStorageSecureFile(filePath);
-      entity = parseEntityFile(content, this.entitySchemas);
-    } catch (err) {
-      if (err instanceof SecureStoreLockedError) throw err;
-      if (!isErrnoCode(err, "ENOENT")) throw err;
-      log.debug(`updateEntitySynthesis: entity file ${name}.md not found`);
-      return;
-    }
-    const updatedAt = options.updatedAt?.trim() || entity.synthesisUpdatedAt?.trim() || void 0;
-    const entityUpdatedAt = options.entityUpdatedAt?.trim() || updatedAt || entity.updated || (/* @__PURE__ */ new Date()).toISOString();
-    const synthesisTimelineCount = Number.isInteger(options.synthesisTimelineCount) && (options.synthesisTimelineCount ?? 0) >= 0 ? options.synthesisTimelineCount : void 0;
-    const synthesisStructuredFactCount = Number.isInteger(options.synthesisStructuredFactCount) && (options.synthesisStructuredFactCount ?? 0) >= 0 ? options.synthesisStructuredFactCount : countEntityStructuredFacts(entity);
-    const synthesisStructuredFactDigest = options.synthesisStructuredFactDigest?.trim() || fingerprintEntityStructuredFacts(entity);
-    entity.synthesis = synthesis.trim();
-    entity.summary = entity.synthesis;
-    entity.synthesisUpdatedAt = updatedAt;
-    entity.synthesisTimelineCount = synthesisTimelineCount;
-    entity.synthesisStructuredFactCount = synthesisStructuredFactCount;
-    entity.synthesisStructuredFactDigest = synthesisStructuredFactDigest;
-    entity.synthesisVersion = Math.max(0, entity.synthesisVersion ?? 0) + (options.incrementVersion === false ? 0 : 1);
-    entity.updated = entityUpdatedAt;
-    await this.writeStorageSecureFile(filePath, serializeEntityFile(entity, this.entitySchemas));
-    await this.removeEntitySynthesisQueueEntries([
-      .../* @__PURE__ */ new Set([name, this.normalizeEntityName(entity.name, entity.type)])
-    ]);
-    this.invalidateKnowledgeIndexCache();
-    this.bumpMemoryStatusVersion();
+    return this.entityStore.updateEntitySynthesis(
+      name,
+      synthesis,
+      options
+    );
   }
   /**
    * Backward-compatible alias for legacy callers/tests.
@@ -5001,7 +5437,7 @@ ${reflection}
     const updatedAt = (/* @__PURE__ */ new Date()).toISOString();
     let synthesisTimelineCount;
     try {
-      const filePath = path.join(this.entitiesDir, `${name}.md`);
+      const filePath = path3.join(this.entitiesDir, `${name}.md`);
       const content = await this.readStorageSecureFile(filePath);
       synthesisTimelineCount = parseEntityFile(content, this.entitySchemas).timeline.length;
     } catch (err) {
@@ -5084,7 +5520,7 @@ ${reflection}
       if (!raw) continue;
       const serialized = serializeEntityFile(parseEntityFile(raw, this.entitySchemas), this.entitySchemas);
       if (raw.trimEnd() === serialized.trimEnd()) continue;
-      await this.writeStorageSecureFile(path.join(this.entitiesDir, `${entityName}.md`), serialized);
+      await this.writeStorageSecureFile(path3.join(this.entitiesDir, `${entityName}.md`), serialized);
       migrated += 1;
     }
     if (migrated > 0) {
@@ -5099,45 +5535,8 @@ ${reflection}
   // ---------------------------------------------------------------------------
   // Scoring + Knowledge Index (Knowledge Graph v7.0)
   // ---------------------------------------------------------------------------
-  /**
-   * Read all entity files and return lightweight EntityFile objects.
-   * Parsing is fast (~50-100ms for ~1,800 files) since entity files are small.
-   */
   async readAllEntityFiles() {
-    const currentVersion = this.getMemoryStatusVersion();
-    const schemaCacheKey = buildEntitySchemaCacheKey(this.entitySchemas);
-    const cacheKey = `${this.getEntityCacheSecureStoreKey()}\0${schemaCacheKey}`;
-    const cached = getCachedEntities(this.baseDir, currentVersion, cacheKey);
-    if (cached) return cached;
-    try {
-      const entries = await readdir(this.entitiesDir);
-      const mdFiles = entries.filter((e) => e.endsWith(".md"));
-      if (mdFiles.length === 0) return [];
-      const BATCH_SIZE = 100;
-      const entities = [];
-      for (let i = 0; i < mdFiles.length; i += BATCH_SIZE) {
-        const batch = mdFiles.slice(i, i + BATCH_SIZE);
-        const results = await Promise.all(
-          batch.map(async (entry) => {
-            try {
-              return await this.readStorageSecureFile(path.join(this.entitiesDir, entry));
-            } catch (err) {
-              if (err instanceof SecureStoreLockedError) throw err;
-              if (!isErrnoCode(err, "ENOENT")) throw err;
-              return null;
-            }
-          })
-        );
-        for (const content of results) {
-          if (content !== null) entities.push(parseEntityFile(content, this.entitySchemas));
-        }
-      }
-      setCachedEntities(this.baseDir, entities, currentVersion, cacheKey);
-      return entities;
-    } catch (err) {
-      if (err instanceof SecureStoreLockedError || !isErrnoCode(err, "ENOENT")) throw err;
-      return [];
-    }
+    return this.entityStore.readAllEntityFiles();
   }
   /**
    * Score an entity based on recency, frequency, activity, type priority,
@@ -5163,53 +5562,11 @@ ${reflection}
     const relDensity = Math.min(entity.relationships.length / 8, 1);
     return recency * 0.4 + frequency * 0.25 + activityScore * 0.15 + typePriority * 0.1 + relDensity * 0.1;
   }
-  /**
-   * Build the Knowledge Index: a compact markdown table of top-scored entities.
-   * Respects maxEntities and maxChars limits from config.
-   */
   async buildKnowledgeIndex(config, overrides) {
-    const useDefaultLimits = overrides?.maxEntities === void 0 && overrides?.maxChars === void 0;
-    if (useDefaultLimits && this.knowledgeIndexCache && Date.now() - this.knowledgeIndexCache.builtAt < _StorageManager.KNOWLEDGE_INDEX_CACHE_TTL_MS) {
-      return { result: this.knowledgeIndexCache.result, cached: true };
-    }
-    const entities = await this.readAllEntityFiles();
-    if (entities.length === 0) {
-      if (useDefaultLimits) this.knowledgeIndexCache = { result: "", builtAt: Date.now() };
-      return { result: "", cached: false };
-    }
-    const now = /* @__PURE__ */ new Date();
-    const scored = entities.map((e) => ({
-      name: e.name,
-      type: e.type,
-      score: _StorageManager.scoreEntity(e, now),
-      factCount: e.facts.length,
-      summary: e.synthesis ?? e.summary,
-      topRelationships: e.relationships.slice(0, 3).map((r) => r.target)
-    }));
-    scored.sort((a, b) => b.score - a.score);
-    const maxEntities = typeof overrides?.maxEntities === "number" ? Math.max(0, Math.floor(overrides.maxEntities)) : config.knowledgeIndexMaxEntities;
-    const topN = scored.slice(0, maxEntities);
-    if (topN.length === 0) {
-      if (useDefaultLimits) this.knowledgeIndexCache = { result: "", builtAt: Date.now() };
-      return { result: "", cached: false };
-    }
-    const header = "## Knowledge Index\n\n| Entity | Type | Summary | Connected to |\n|--------|------|---------|-------------|";
-    const rows = [];
-    let totalChars = header.length;
-    const maxChars = typeof overrides?.maxChars === "number" ? Math.max(0, Math.floor(overrides.maxChars)) : config.knowledgeIndexMaxChars;
-    for (const entity of topN) {
-      const summary = entity.summary || `${entity.factCount} facts`;
-      const connected = entity.topRelationships.length > 0 ? entity.topRelationships.join(", ") : "\u2014";
-      const row = `| ${entity.name} | ${entity.type} | ${summary} | ${connected} |`;
-      if (totalChars + row.length + 1 > maxChars) break;
-      rows.push(row);
-      totalChars += row.length + 1;
-    }
-    const result = rows.length === 0 ? "" : `${header}
-${rows.join("\n")}
-`;
-    if (useDefaultLimits) this.knowledgeIndexCache = { result, builtAt: Date.now() };
-    return { result, cached: false };
+    return this.entityStore.buildKnowledgeIndex(
+      config,
+      overrides
+    );
   }
   /** Invalidate the Knowledge Index cache (call after entity mutations). */
   invalidateKnowledgeIndexCache() {
@@ -5220,201 +5577,8 @@ ${rows.join("\n")}
   // ---------------------------------------------------------------------------
   /** Max lines for profile.md before LLM consolidation triggers */
   static PROFILE_MAX_LINES = 300;
-  /**
-   * Merge fragmented entity files that resolve to the same canonical name.
-   * Preserves relationships, activity, aliases, and summary from all fragments.
-   * Returns count of files merged.
-   */
   async mergeFragmentedEntities() {
-    let merged = 0;
-    try {
-      const entries = await readdir(this.entitiesDir);
-      const mdFiles = entries.filter((e) => e.endsWith(".md"));
-      const groups = /* @__PURE__ */ new Map();
-      for (const file of mdFiles) {
-        const baseName = file.replace(".md", "");
-        const dashIdx = baseName.indexOf("-");
-        if (dashIdx === -1) continue;
-        const type = baseName.slice(0, dashIdx);
-        const restOfName = baseName.slice(dashIdx + 1);
-        const canonical = this.normalizeEntityName(restOfName, type);
-        if (!groups.has(canonical)) groups.set(canonical, []);
-        groups.get(canonical).push(file);
-      }
-      for (const [canonical, files] of groups) {
-        if (files.length <= 1) continue;
-        const mergedEntity = {
-          name: "",
-          type: "other",
-          created: "",
-          updated: "",
-          extraFrontmatterLines: [],
-          preSectionLines: [],
-          facts: [],
-          summary: void 0,
-          synthesis: void 0,
-          synthesisUpdatedAt: void 0,
-          synthesisTimelineCount: void 0,
-          synthesisStructuredFactCount: void 0,
-          synthesisStructuredFactDigest: void 0,
-          synthesisVersion: void 0,
-          timeline: [],
-          relationships: [],
-          activity: [],
-          aliases: [],
-          structuredSections: [],
-          extraSections: []
-        };
-        for (const file of files) {
-          const filePath = path.join(this.entitiesDir, file);
-          try {
-            const content = await this.readStorageSecureFile(filePath);
-            const parsed = parseEntityFile(content, this.entitySchemas);
-            if (!mergedEntity.type || mergedEntity.type === "other") {
-              mergedEntity.type = parsed.type;
-            }
-            if (!mergedEntity.updated || compareEntityTimestamps(parsed.updated, mergedEntity.updated) > 0) {
-              mergedEntity.updated = parsed.updated;
-            }
-            const parsedCreated = parsed.created || parsed.updated;
-            const mergedCreated = mergedEntity.created?.trim() || "";
-            const parsedCreatedMs = parsedCreated ? Date.parse(parsedCreated) : Number.NaN;
-            const mergedCreatedMs = mergedCreated ? Date.parse(mergedCreated) : Number.NaN;
-            const parsedCreatedIsValid = Number.isFinite(parsedCreatedMs);
-            const mergedCreatedIsValid = Number.isFinite(mergedCreatedMs);
-            if (parsedCreated && (!mergedCreated || parsedCreatedIsValid && !mergedCreatedIsValid || parsedCreatedIsValid && mergedCreatedIsValid && parsedCreatedMs < mergedCreatedMs || !parsedCreatedIsValid && !mergedCreatedIsValid && compareEntityTimestamps(parsedCreated, mergedCreated) < 0)) {
-              mergedEntity.created = parsedCreated;
-            }
-            if (parsed.name.length > mergedEntity.name.length) {
-              mergedEntity.name = parsed.name;
-            }
-            const parsedSynthesisUpdatedAt = parsed.synthesisUpdatedAt?.trim() || void 0;
-            const mergedSynthesisUpdatedAt = mergedEntity.synthesisUpdatedAt?.trim() || void 0;
-            if (parsed.synthesis && (!mergedEntity.synthesis || !mergedSynthesisUpdatedAt && Boolean(parsedSynthesisUpdatedAt) || Boolean(mergedSynthesisUpdatedAt) && Boolean(parsedSynthesisUpdatedAt) && compareEntityTimestamps(parsedSynthesisUpdatedAt, mergedSynthesisUpdatedAt) > 0)) {
-              mergedEntity.synthesis = parsed.synthesis;
-              mergedEntity.summary = parsed.synthesis;
-              mergedEntity.synthesisUpdatedAt = parsedSynthesisUpdatedAt;
-              mergedEntity.synthesisTimelineCount = parsed.synthesisTimelineCount;
-              mergedEntity.synthesisStructuredFactCount = parsed.synthesisStructuredFactCount;
-              mergedEntity.synthesisStructuredFactDigest = parsed.synthesisStructuredFactDigest;
-              mergedEntity.synthesisVersion = parsed.synthesisVersion;
-            } else if (!mergedEntity.summary && parsed.summary) {
-              mergedEntity.summary = parsed.summary;
-              mergedEntity.synthesis = parsed.summary;
-              mergedEntity.synthesisUpdatedAt = parsedSynthesisUpdatedAt;
-              mergedEntity.synthesisTimelineCount = parsed.synthesisTimelineCount;
-              mergedEntity.synthesisStructuredFactCount = parsed.synthesisStructuredFactCount;
-              mergedEntity.synthesisStructuredFactDigest = parsed.synthesisStructuredFactDigest;
-              mergedEntity.synthesisVersion = parsed.synthesisVersion;
-            }
-            mergedEntity.timeline.push(...parsed.timeline);
-            mergedEntity.relationships.push(...parsed.relationships);
-            mergedEntity.activity.push(...parsed.activity);
-            mergedEntity.aliases.push(...parsed.aliases);
-            const mergedStructuredSectionMap = new Map(
-              (mergedEntity.structuredSections ?? []).map((section) => [section.key, {
-                ...section,
-                facts: [...section.facts]
-              }])
-            );
-            for (const section of parsed.structuredSections ?? []) {
-              const existingSection = mergedStructuredSectionMap.get(section.key);
-              if (!existingSection) {
-                mergedStructuredSectionMap.set(section.key, {
-                  key: section.key,
-                  title: section.title,
-                  facts: [...new Set(section.facts.map((fact) => fact.trim()).filter((fact) => fact.length > 0))]
-                });
-                continue;
-              }
-              const mergedFacts = new Set(existingSection.facts.map((fact) => fact.trim()));
-              for (const fact of section.facts) {
-                const trimmed = fact.trim();
-                if (!trimmed) continue;
-                mergedFacts.add(trimmed);
-              }
-              existingSection.facts = Array.from(mergedFacts);
-              if (!existingSection.title.trim() && section.title.trim()) {
-                existingSection.title = section.title;
-              }
-            }
-            mergedEntity.structuredSections = Array.from(mergedStructuredSectionMap.values());
-            mergedEntity.extraFrontmatterLines.push(...parsed.extraFrontmatterLines ?? []);
-            mergedEntity.preSectionLines.push(...parsed.preSectionLines ?? []);
-            mergedEntity.extraSections.push(...(parsed.extraSections ?? []).map((section) => ({
-              title: section.title,
-              lines: [...section.lines]
-            })));
-          } catch (err) {
-            if (err instanceof SecureStoreLockedError) throw err;
-            if (!isErrnoCode(err, "ENOENT")) throw err;
-          }
-        }
-        const timelineKeys = /* @__PURE__ */ new Set();
-        mergedEntity.timeline = mergedEntity.timeline.filter((entry) => {
-          const key = JSON.stringify([
-            entry.timestamp,
-            entry.source ?? "",
-            entry.sessionKey ?? "",
-            entry.principal ?? "",
-            entry.text
-          ]);
-          if (timelineKeys.has(key)) return false;
-          timelineKeys.add(key);
-          return true;
-        });
-        const relKeys = /* @__PURE__ */ new Set();
-        mergedEntity.relationships = mergedEntity.relationships.filter((r) => {
-          const key = `${r.target}::${r.label}`;
-          if (relKeys.has(key)) return false;
-          relKeys.add(key);
-          return true;
-        });
-        const actKeys = /* @__PURE__ */ new Set();
-        mergedEntity.activity = mergedEntity.activity.filter((a) => {
-          const key = `${a.date}::${a.note}`;
-          if (actKeys.has(key)) return false;
-          actKeys.add(key);
-          return true;
-        }).sort((a, b) => b.date.localeCompare(a.date));
-        mergedEntity.aliases = [...new Set(mergedEntity.aliases)];
-        mergedEntity.structuredSections = sortStructuredSectionsBySchema(
-          mergedEntity.type,
-          mergedEntity.structuredSections ?? [],
-          this.entitySchemas
-        );
-        mergedEntity.facts = compileEntityFacts(mergedEntity.timeline, mergedEntity.structuredSections);
-        const extraSectionKeys = /* @__PURE__ */ new Set();
-        mergedEntity.extraSections = (mergedEntity.extraSections ?? []).filter((section) => {
-          const key = `${section.title}::${section.lines.join("\n")}`;
-          if (extraSectionKeys.has(key)) return false;
-          extraSectionKeys.add(key);
-          return true;
-        });
-        if (!mergedEntity.name) {
-          const dashIdx = canonical.indexOf("-");
-          mergedEntity.name = dashIdx !== -1 ? canonical.slice(dashIdx + 1) : canonical;
-        }
-        mergedEntity.created = mergedEntity.created || mergedEntity.updated || (/* @__PURE__ */ new Date()).toISOString();
-        mergedEntity.updated = mergedEntity.updated || (/* @__PURE__ */ new Date()).toISOString();
-        const canonicalPath = path.join(this.entitiesDir, `${canonical}.md`);
-        await this.writeStorageSecureFile(canonicalPath, serializeEntityFile(mergedEntity, this.entitySchemas));
-        for (const file of files) {
-          const filePath = path.join(this.entitiesDir, file);
-          if (filePath !== canonicalPath) {
-            try {
-              await unlink(filePath);
-              merged++;
-              log.debug(`merged entity ${file} \u2192 ${canonical}.md`);
-            } catch {
-            }
-          }
-        }
-      }
-    } catch (err) {
-      if (err instanceof SecureStoreLockedError || !isErrnoCode(err, "ENOENT")) throw err;
-    }
-    return merged;
+    return this.entityStore.mergeFragmentedEntities();
   }
   async cleanExpiredCommitments(decayDays) {
     const memories = await this.readAllMemories();
@@ -5429,7 +5593,7 @@ ${rows.join("\n")}
       const updatedAt = new Date(m.frontmatter.updated).getTime();
       if (updatedAt < cutoff) {
         try {
-          await unlink(m.path);
+          await unlink2(m.path);
           deleted.push(m);
           log.debug(`cleaned expired commitment ${m.frontmatter.id}`);
         } catch {
@@ -5499,7 +5663,7 @@ ${memory.content}
     const filePaths = await this.collectActiveMemoryPaths();
     const foundIds = /* @__PURE__ */ new Set();
     for (const filePath of filePaths) {
-      const basename = path.basename(filePath, ".md");
+      const basename = path3.basename(filePath, ".md");
       if (wantedIds.has(basename)) {
         foundIds.add(basename);
         if (foundIds.size === wantedIds.size) break;
@@ -5689,14 +5853,14 @@ Reason: ${reason}`, {
   // Memory Summarization (Phase 4A)
   // ---------------------------------------------------------------------------
   get summariesDir() {
-    return path.join(this.baseDir, "summaries");
+    return path3.join(this.baseDir, "summaries");
   }
   /**
    * Write a memory summary.
    */
   async writeSummary(summary) {
     await mkdir(this.summariesDir, { recursive: true });
-    const filePath = path.join(this.summariesDir, `${summary.id}.json`);
+    const filePath = path3.join(this.summariesDir, `${summary.id}.json`);
     await this.writeStorageSecureFile(filePath, JSON.stringify(summary, null, 2));
     log.debug(`wrote summary ${summary.id}`);
   }
@@ -5705,11 +5869,11 @@ Reason: ${reason}`, {
    */
   async readSummaries() {
     try {
-      const files = await readdir(this.summariesDir);
+      const files = await readdir3(this.summariesDir);
       const summaries = [];
       for (const file of files) {
         if (!file.endsWith(".json")) continue;
-        const filePath = path.join(this.summariesDir, file);
+        const filePath = path3.join(this.summariesDir, file);
         const raw = await this.readStorageSecureFile(filePath);
         summaries.push(JSON.parse(raw));
       }
@@ -5770,7 +5934,7 @@ ${memory.content}
    * Save topic scores to meta.json.
    */
   async saveTopics(topics) {
-    const metaPath = path.join(this.stateDir, "topics.json");
+    const metaPath = path3.join(this.stateDir, "topics.json");
     await mkdir(this.stateDir, { recursive: true });
     await this.writeStorageSecureFile(metaPath, JSON.stringify({ topics, updatedAt: (/* @__PURE__ */ new Date()).toISOString() }, null, 2));
     log.debug(`saved ${topics.length} topic scores`);
@@ -5779,7 +5943,7 @@ ${memory.content}
    * Load topic scores from meta.json.
    */
   async loadTopics() {
-    const metaPath = path.join(this.stateDir, "topics.json");
+    const metaPath = path3.join(this.stateDir, "topics.json");
     try {
       const raw = await this.readStorageSecureFile(metaPath);
       return JSON.parse(raw);
@@ -5857,14 +6021,23 @@ ${memory.content}
 };
 
 export {
+  selfDeps,
+  parseFrontmatterStringValue,
+  parseFrontmatter,
+  normalizeFrontmatterForPath,
   normalizeEntityName,
   ContentHashIndex,
   normalizeAttributePairs,
+  normalizeStructuredSectionFacts,
+  compileEntityFacts,
   compareEntityTimestamps,
+  countEntityStructuredFacts,
   fingerprintEntityStructuredFacts,
   isEntitySynthesisStale,
   parseEntityFile,
   serializeEntityFile,
-  StorageManager
+  buildEntitySchemaCacheKey,
+  isValidBufferSurpriseEvent,
+  StorageManager3 as StorageManager
 };
-//# sourceMappingURL=chunk-THZ4WR5L.js.map
+//# sourceMappingURL=chunk-7APVFQ34.js.map