@remnic/core 9.3.754 → 9.3.756

package/src/storage.ts

@@ -4,6 +4,9 @@ import { createHash } from "node:crypto"
 import { normalizeContent, computeContentHash } from "./content-hash.js";;
 import path from "node:path";
 import { log } from "./logger.js";
+import { MemoryReadStore } from "./storage/memory-read-store.js";
+import { selfDeps } from "./orchestration/self-deps.js";
+import { EntityStore } from "./storage/entity-store.js";
 import { isErrnoCode } from "./utils/errno.js";
 import { RECALL_FALLBACK_DIRS, getCategoryDir, categoryDirName } from "./utils/category-dir.js";
 import { assertPathInsideRoot } from "./utils/path-containment.js";
@@ -519,7 +522,7 @@ function parseLinkReasonValue(rawValue: string): string {
   }
 }
 
-function parseFrontmatterStringValue(rawValue: string | undefined): string | undefined {
+export function parseFrontmatterStringValue(rawValue: string | undefined): string | undefined {
   if (rawValue === undefined) return undefined;
   const trimmed = rawValue.trim();
   if (trimmed.length === 0) return undefined;
@@ -565,7 +568,7 @@ function parseReinforcementCountField(raw: string | undefined): number | undefin
   return n;
 }
 
-function parseFrontmatter(
+export function parseFrontmatter(
   raw: string,
 ): { frontmatter: MemoryFrontmatter; content: string } | null {
   const match = raw.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
@@ -952,7 +955,7 @@ function inferEntityTypeFromFilename(pathRel: string): string | undefined {
   return KNOWN_ENTITY_FILENAME_PREFIXES.has(candidate) ? candidate : undefined;
 }
 
-function normalizeFrontmatterForPath(frontmatter: MemoryFrontmatter, pathRel: string, content: string = ""): MemoryFrontmatter {
+export function normalizeFrontmatterForPath(frontmatter: MemoryFrontmatter, pathRel: string, content: string = ""): MemoryFrontmatter {
   const normalizedPath = pathRel.split(path.sep).join("/");
   let normalizedFrontmatter = frontmatter;
 
@@ -1651,7 +1654,7 @@ function normalizeEntitySectionFact(value: string): string {
   return value.replace(/\s+/g, " ").trim();
 }
 
-function normalizeStructuredSectionFacts(facts: string[]): string[] {
+export function normalizeStructuredSectionFacts(facts: string[]): string[] {
   return [...new Set(
     facts
       .map((fact) => normalizeEntitySectionFact(fact))
@@ -1671,7 +1674,7 @@ function collectStructuredSectionFacts(structuredSections: EntityStructuredSecti
   return [...new Set(facts)];
 }
 
-function compileEntityFacts(
+export function compileEntityFacts(
   timeline: EntityTimelineEntry[],
   structuredSections: EntityStructuredSection[],
 ): string[] {
@@ -1811,7 +1814,7 @@ export function compareEntityTimestamps(left?: string, right?: string): number {
   return leftValue.localeCompare(rightValue);
 }
 
-function countEntityStructuredFacts(entity: EntityFile): number {
+export function countEntityStructuredFacts(entity: EntityFile): number {
   return (entity.structuredSections ?? []).reduce((count, section) => count + section.facts.length, 0);
 }
 
@@ -2189,7 +2192,7 @@ export function serializeEntityFile(
   return lines.join("\n");
 }
 
-function buildEntitySchemaCacheKey(entitySchemas?: PluginConfig["entitySchemas"]): string {
+export function buildEntitySchemaCacheKey(entitySchemas?: PluginConfig["entitySchemas"]): string {
   if (!entitySchemas) return "";
   const normalized = Object.entries(entitySchemas)
     .sort(([left], [right]) => left.localeCompare(right))
@@ -2220,7 +2223,7 @@ function buildEntitySchemaCacheKey(entitySchemas?: PluginConfig["entitySchemas"]
  * downstream report requires at read time so the limit semantics and
  * the distribution semantics stay consistent.
  */
-function isValidBufferSurpriseEvent(value: unknown): value is BufferSurpriseEvent {
+export function isValidBufferSurpriseEvent(value: unknown): value is BufferSurpriseEvent {
   if (!value || typeof value !== "object" || Array.isArray(value)) return false;
   const v = value as Record<string, unknown>;
   if (v.event !== "BUFFER_SURPRISE") return false;
@@ -2259,9 +2262,11 @@ export interface MemoryWriteResult {
 
 export class StorageManager {
   private knowledgeIndexCache: { result: string; builtAt: number } | null = null;
-  private static readonly KNOWLEDGE_INDEX_CACHE_TTL_MS = 600_000; // 10 minutes (entity mutations invalidate)
   private artifactIndexCache: { memories: MemoryFile[]; loadedAtMs: number; writeVersion: number } | null = null;
-  private static readonly ARTIFACT_INDEX_CACHE_TTL_MS = 60_000; // 1 minute
+  /** Read by storage/entity-store.ts (decomposition), hence not `private`. */
+  static readonly KNOWLEDGE_INDEX_CACHE_TTL_MS = 600_000; // 10 minutes (entity mutations invalidate)
+  /** Read by storage/memory-read-store.ts (decomposition). */
+  static readonly ARTIFACT_INDEX_CACHE_TTL_MS = 60_000; // 1 minute
   private static readonly artifactWriteVersionByDir = new Map<string, number>();
   private static readonly memoryStatusVersionByDir = new Map<string, number>();
   private static readonly secureStoreEntityCacheKeyIds = new WeakMap<Buffer, number>();
@@ -2290,14 +2295,18 @@ export 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.
-  private static readonly COLD_SCAN_CACHE_TTL_MS = 30_000; // 30 seconds
-  private static readonly coldMemoriesCache = new Map<string, { memories: MemoryFile[]; loadedAt: number; coldVersion: number }>();
+  /** Read by storage/memory-read-store.ts (decomposition). */
+  static readonly COLD_SCAN_CACHE_TTL_MS = 30_000; // 30 seconds
+  /** Read by storage/memory-read-store.ts (decomposition). */
+  static readonly coldMemoriesCache = new Map<string, { memories: MemoryFile[]; loadedAt: number; coldVersion: number }>();
 
   // 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.
-  private static readonly QUESTIONS_CACHE_TTL_MS = 60_000; // 1 minute
-  private static readonly questionsCache = new Map<
+  /** Read by storage/memory-read-store.ts (decomposition). */
+  static readonly QUESTIONS_CACHE_TTL_MS = 60_000; // 1 minute
+  /** Read by storage/memory-read-store.ts (decomposition). */
+  static readonly questionsCache = new Map<
     string,
     {
       questions: Array<{
@@ -2513,7 +2522,44 @@ export class StorageManager {
     this.loadAliasesSync();
   }
 
+  /**
+   * 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(): typeof StorageManager {
+    return this.constructor as typeof StorageManager;
+  }
+
   /** The root directory of this storage instance. */
+  /** MemoryReadStore (storage.ts decomposition). Lazy; selfDeps live wiring. */
+  private _memoryReadStore: MemoryReadStore | undefined;
+
+  private get memoryReadStore(): MemoryReadStore {
+    if (!this._memoryReadStore) {
+      this._memoryReadStore = new MemoryReadStore(
+        selfDeps<ConstructorParameters<typeof MemoryReadStore>[0]>(this),
+      );
+    }
+    return this._memoryReadStore;
+  }
+
+  /** EntityStore (storage.ts decomposition). Lazy; selfDeps live wiring. */
+  private _entityStore: EntityStore | undefined;
+
+  private get entityStore(): EntityStore {
+    if (!this._entityStore) {
+      this._entityStore = new EntityStore(
+        selfDeps<ConstructorParameters<typeof EntityStore>[0]>(this),
+      );
+    }
+    return this._entityStore;
+  }
+
   get dir(): string {
     return this.baseDir;
   }
@@ -2645,52 +2691,12 @@ export class StorageManager {
     }
   }
 
-  /**
-   * List stored transcript days, newest first, optionally scoped to one
-   * source. Non-transcript files in the tree are ignored.
-   */
   async listWearableTranscriptDays(
     sourceId?: string,
   ): Promise<Array<{ source: string; date: string }>> {
-    const days: Array<{ source: string; date: string }> = [];
-    let sources: string[];
-    if (sourceId !== undefined) {
-      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 as NodeJS.ErrnoException).code === "ENOENT") return [];
-        throw err;
-      }
-    }
-    for (const source of sources) {
-      if (!/^[a-z][a-z0-9-]{0,63}$/.test(source)) continue;
-      let entries: string[];
-      try {
-        entries = await readdir(path.join(this.wearablesDir, source));
-      } catch (err) {
-        if ((err as NodeJS.ErrnoException).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;
+    return this.memoryReadStore.listWearableTranscriptDays(
+      sourceId,
+    );
   }
 
   /**
@@ -3476,9 +3482,11 @@ export class StorageManager {
    */
   private userAliases: Record<string, string> = {};
 
-  /** Normalize an entity name using this store's alias table. */
   normalizeEntityName(raw: string, type: string): string {
-    return normalizeEntityName(raw, type, this.userAliases);
+    return this.entityStore.normalizeEntityName(
+      raw,
+      type,
+    );
   }
 
   /**
@@ -4027,55 +4035,8 @@ export class StorageManager {
   }
 
   private async readAllArtifactsCached(): Promise<MemoryFile[]> {
-    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 (): Promise<MemoryFile[]> => {
-      const artifacts: MemoryFile[] = [];
-      const readDir = async (dir: string) => {
-        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 {
-          // Directory doesn't exist yet
-        }
-      };
-      await readDir(this.artifactsDir);
-      return artifacts;
-    };
-
-    const MAX_REBUILD_RETRIES = 2;
-    let latestArtifacts: MemoryFile[] = [];
-    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;
-      }
-    }
-
-    // Highly concurrent writer churn; keep cache invalid so next read retries a clean rebuild.
-    // Return best-effort latest scan instead of an empty set to avoid dropping recall entirely.
-    this.artifactIndexCache = null;
-    return latestArtifacts;
+    return this.memoryReadStore.readAllArtifactsCached(
+    );
   }
 
   async searchArtifacts(query: string, maxResults: number): Promise<MemoryFile[]> {
@@ -4109,124 +4070,12 @@ export class StorageManager {
       structuredSections?: EntityStructuredSection[];
     } = {},
   ): Promise<string> {
-    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);
-
-    // Check for fuzzy match against existing entities before creating a new file
-    const match = await this.findMatchingEntity(name, type);
-    if (match && match !== normalized) {
-      log.debug(`fuzzy match: "${normalized}" → existing "${match}"`);
-      normalized = match;
-    }
-
-    const filePath = path.join(this.entitiesDir, `${normalized}.md`);
-
-    // Parse existing file to preserve relationships/activity/aliases/summary
-    let entity: EntityFile = {
+    return this.entityStore.writeEntity(
       name,
       type,
-      created: "",
-      updated: new Date().toISOString(),
-      facts: [],
-      summary: undefined,
-      synthesis: undefined,
-      synthesisUpdatedAt: undefined,
-      synthesisVersion: undefined,
-      synthesisStructuredFactCount: undefined,
-      synthesisStructuredFactDigest: undefined,
-      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;
-      // File doesn't exist yet
-    }
-
-    const timestamp = options.timestamp?.trim() || new Date().toISOString();
-    const source = options.source?.trim() || undefined;
-    const sessionKey = options.sessionKey?.trim() || undefined;
-    const principal = options.principal?.trim() || undefined;
-    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 = new Date().toISOString();
-
-    await this.snapshotBeforeWrite(filePath, "write");
-    await this.writeStorageSecureFile(filePath, serializeEntityFile(entity, this.entitySchemas));
-    this.invalidateKnowledgeIndexCache();
-    this.bumpMemoryStatusVersion(); // invalidate entity cache
-    log.debug(`wrote entity ${normalized}`);
-    return normalized;
   }
 
   async readProfile(): Promise<string> {
@@ -4458,98 +4307,8 @@ export class StorageManager {
   }
 
   private async collectActiveMemoryPaths(): Promise<string[]> {
-    const filePaths: string[] = [];
-
-    // Resolve the memory root once for containment checks below. A category dir
-    // symlinked outside memoryDir (e.g. decisions/ -> an external dir) must NOT
-    // pull out-of-store files into the QMD-unavailable recall fallback (info
-    // leak). Same walker-hardening pattern as document-scanner.ts / cli.ts /
-    // consolidation-provenance-check.ts; reuses the shared containment helper.
-    let memoryRootReal: string;
-    try {
-      memoryRootReal = await realpath(this.baseDir);
-    } catch {
-      return filePaths;
-    }
-
-    const collectPaths = async (dir: string) => {
-      // Directory-level guard, isolated from per-entry handling: skip symlinked
-      // or non-directory category dirs and assert the resolved dir stays inside
-      // the memory root before reading. A failure here means the whole subtree
-      // does not exist or escaped the store — fail closed by skipping it.
-      let entries: Dirent[];
-      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: string[] = [];
-      for (const entry of entries) {
-        // Never follow symlinked entries out of the store.
-        if (entry.isSymbolicLink()) continue;
-        const fullPath = path.join(dir, entry.name);
-        if (entry.isDirectory()) {
-          subdirs.push(fullPath);
-        } else if (entry.name.endsWith(".md")) {
-          // Isolate per-entry failures in their own try/catch: a containment or
-          // realpath failure on ONE .md entry must not drop sibling files or,
-          // crucially, the deferred subdir recursion below (Cursor Bugbot:
-          // "Poisoned md skips sibling subdirs"). Mirrors the per-file try/catch
-          // in search/document-scanner.ts scanDir and
-          // consolidation-provenance-check.ts walkMarkdownFiles.
-          try {
-            assertPathInsideRoot(memoryRootReal, await realpath(fullPath), fullPath);
-            filePaths.push(fullPath);
-          } catch {
-            // Skip just this entry (symlink/containment/realpath failure).
-          }
-        }
-      }
-      // Recurse into real subdirectories regardless of any single poisoned entry
-      // above, so valid nested in-store memories are never dropped.
-      for (const subdir of subdirs) {
-        await collectPaths(subdir);
-      }
-    };
-
-    // Scan EVERY supported memory category directory, not just the legacy four
-    // (facts/procedures/reasoning-traces/corrections). Issue #1497: the QMD
-    // filesystem-fallback recall path (orchestrator `recent_scan` ->
-    // readAllMemoriesForNamespaces -> readAllMemories -> here) must read every
-    // recall category dir so on-disk memories in preferences/decisions/moments/
-    // commitments/principles/rules/skills/relationships are not missed when QMD
-    // is disabled, missing, or unhealthy. RECALL_FALLBACK_DIRS is the single
-    // source of truth derived from ALL_CATEGORY_DIRS (shared with
-    // ensureDirectories() and the write routing in utils/category-dir.ts).
-    // These paths resolve identically to the legacy this.factsDir /
-    // this.correctionsDir / this.proceduresDir / this.reasoningTracesDir
-    // getters (all `path.join(this.baseDir, <dir>)`), so the scan stays
-    // namespace-aware: this.baseDir is per-namespace, set by the storage router.
-    // Deliberately EXCLUDED (issue #1497 + PR #1503 review): the non-category
-    // content dirs that ensureDirectories() also creates — entities/, state/,
-    // artifacts/, identity/, config/ — plus the root profile.md, AND the
-    // questions/ queue dir. questions/ holds operational question-QUEUE items
-    // written by writeQuestion() (frontmatter `{ id, created, priority,
-    // resolved }`), read only via readQuestions() and surfaced through the
-    // dedicated, disabled-by-default `injectQuestions` recall-pipeline stage —
-    // never as standard recall memories. The QMD primary recall corpus does not
-    // include them, so the fallback must not either (corpus parity; CLAUDE.md
-    // rule #39). Were questions/ scanned here, parseFrontmatter() would accept
-    // those files (they have a `---` frontmatter block) and leak queue items
-    // into recall. None of these excluded dirs are in RECALL_FALLBACK_DIRS; the
-    // exclusion is asserted by tests in storage-fallback-category-dirs.test.ts.
-    //
-    // collectPaths() already ignores missing dirs (try/catch) and the parser
-    // returns null for non-memory markdown, so unrelated files never crash the
-    // scan.
-    for (const dir of RECALL_FALLBACK_DIRS) {
-      await collectPaths(path.join(this.baseDir, dir));
-    }
-    return filePaths;
+    return this.memoryReadStore.collectActiveMemoryPaths(
+    );
   }
 
   private async readParsedMemoriesFromPaths(
@@ -4693,52 +4452,9 @@ export class StorageManager {
     batchSize?: number;
     updatedAfter?: Date;
   } = {}): Promise<{ memories: MemoryFile[]; filePaths: string[] }> {
-    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))
-        : undefined;
-    const maxCandidatePaths = maxMemories === undefined ? undefined : maxMemories * 2;
-    const updatedAfterMs = options.updatedAfter?.getTime();
-    const normalizedBatchSize = this.normalizeMemoryReadBatchSize(options.batchSize);
-    const memories: MemoryFile[] = [];
-    const selectedPaths: string[] = [];
-
-    for (let i = 0; i < sortedPaths.length; i += normalizedBatchSize) {
-      if (
-        maxMemories !== undefined
-        && (memories.length >= maxMemories || (maxCandidatePaths !== undefined && selectedPaths.length >= maxCandidatePaths))
-      ) {
-        return { memories, filePaths: selectedPaths };
-      }
-      const batchPaths = sortedPaths.slice(i, i + normalizedBatchSize);
-      const candidateBatchPaths = updatedAfterMs === undefined
-        ? batchPaths
-        : await this.filterWindowPathsByUpdatedAfter(batchPaths, updatedAfterMs);
-      const remainingSlots = maxMemories === undefined ? undefined : Math.max(0, maxMemories - memories.length);
-      const remainingInspectionBudget = maxCandidatePaths === undefined ? undefined : Math.max(0, maxCandidatePaths - selectedPaths.length);
-      const { memories: batchMemories, filePaths: parsedCandidatePaths } = remainingSlots === undefined
-        ? {
-            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 !== undefined && memories.length >= maxMemories) {
-          return { memories, filePaths: selectedPaths };
-        }
-      }
-    }
-
-    return { memories, filePaths: selectedPaths };
+    return this.memoryReadStore.readMemoriesWindow(
+      options,
+    );
   }
 
   private async _readAllMemoriesFromDisk(): Promise<MemoryFile[]> {
@@ -4746,85 +4462,9 @@ export class StorageManager {
     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(): Promise<MemoryFile[]> {
-    const coldRoot = this.resolveTierRootDir("cold");
-
-    // Read the on-disk cold-version sentinel BEFORE checking the cache so that
-    // writes made by other processes (gateway + CLI) are detected immediately.
-    // Finding UvUy (PR #402 round-11): without this check the cache served
-    // stale data for up to 30s when another process wrote a new cold memory.
-    const currentColdVersion = this.readColdWriteVersion();
-
-    // Return cached result if still valid by both TTL and sentinel version.
-    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: string[] = [];
-
-    const collectPaths = async (dir: string) => {
-      try {
-        const entries = await readdir(dir, { withFileTypes: true });
-        const subdirs: string[] = [];
-        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 {
-        // Directory does not exist yet — cold tier may be empty.
-      }
-    };
-
-    // Scan the entire cold root so that memories in any subdirectory (facts/,
-    // corrections/, artifacts/, or any future category-specific subdirectory)
-    // are included.  This is broader than the previous facts/+corrections/ scan
-    // and ensures that any memory with structuredAttributes is found regardless
-    // of which category it was written with.
-    await collectPaths(coldRoot);
-    const memories = await this.readParsedMemoriesFromPaths(filePaths, 50);
-
-    // Store in cache with the sentinel version captured above so that any
-    // subsequent cold-version bump (by this or another process) invalidates it.
-    StorageManager.coldMemoriesCache.set(coldRoot, { memories, loadedAt: Date.now(), coldVersion: currentColdVersion });
-    return memories;
+    return this.memoryReadStore.readAllColdMemories(
+    );
   }
 
   /**
@@ -4874,67 +4514,10 @@ export class StorageManager {
     return memories;
   }
 
-  /** Read a single memory file by its absolute path. Returns null if unreadable. */
   async readMemoryByPath(filePath: string): Promise<MemoryFile | null> {
-    try {
-      const raw = await readMaybeEncryptedFile(filePath, this._secureStoreKey, this.baseDir);
-      // Note: the outer catch intentionally swallows most errors (ENOENT etc.)
-      // but SecureStoreLockedError must propagate — see re-throw below.
-      const parsed = parseFrontmatter(raw);
-      if (parsed) {
-        return {
-          path: filePath,
-          frontmatter: normalizeFrontmatterForPath(
-            parsed.frontmatter,
-            toMemoryPathRel(this.baseDir, filePath),
-            parsed.content,
-          ),
-          content: parsed.content,
-        };
-      }
-
-      // Entity files use a `# Name` + `**Type:** ...` markdown format rather than
-      // YAML frontmatter. Build a synthetic MemoryFile so entity files returned by
-      // the direct retrieval agent participate in boostSearchResults and last-recall
-      // tracking rather than being silently dropped.
-      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");
-        // Fall back to file mtime rather than new Date() so that entities without
-        // an explicit Updated: timestamp are not treated as freshly created on every
-        // read. Using new Date() would inflate boostSearchResults recency scores for
-        // every entity that lacks a timestamp.
-        // Use epoch as the last-resort fallback so that entities without a
-        // parseable timestamp don't appear as "freshly created" and inflate scores.
-        const fileMtime = entity.updated
-          || await stat(filePath).then((s) => s.mtime.toISOString()).catch(() => 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) {
-      // Re-throw store-locked errors — callers need to distinguish "locked"
-      // from "file not found / parse error". Swallowing a locked error here
-      // would silently return null and leave the daemon appearing to work
-      // while returning no memories (subtle data loss).
-      if (err instanceof SecureStoreLockedError) throw err;
-      return null;
-    }
+    return this.memoryReadStore.readMemoryByPath(
+      filePath,
+    );
   }
 
   private resolveTierRootDir(tier: "hot" | "cold"): string {
@@ -5106,30 +4689,14 @@ export class StorageManager {
   }
 
   async readEntity(name: string): Promise<string> {
-    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(): Promise<string[]> {
-    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(
+    );
   }
 
   /**
@@ -5451,130 +5018,20 @@ export class StorageManager {
     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: BufferSurpriseEvent[],
   ): Promise<number> {
-    if (events.length === 0) return 0;
-    await this.ensureDirectories();
-
-    const nowIso = new Date().toISOString();
-    const payload = events
-      .map((event) => {
-        const normalized: BufferSurpriseEvent = {
-          ...event,
-          event: "BUFFER_SURPRISE",
-          timestamp:
-            event.timestamp && event.timestamp.length > 0
-              ? event.timestamp
-              : nowIso,
-        };
-        return `${JSON.stringify(normalized)}\n`;
-      })
-      .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: { limit?: number } = {},
   ): Promise<BufferSurpriseEvent[]> {
-    let raw: string;
-    try {
-      raw = await this.readStorageSecureFile(this.bufferSurpriseLedgerPath);
-    } catch (err) {
-      if (err instanceof SecureStoreLockedError) throw err;
-      const code = (err as NodeJS.ErrnoException).code;
-      if (code === "ENOENT") return [];
-      throw err;
-    }
-
-    // Resolve the effective limit up front. Any non-finite / non-positive
-    // value returns no rows — callers who want "everything" should OMIT
-    // the `limit` key (treated as "no bound" below). We intentionally
-    // reject `Infinity` too, because the slice math `events.slice(-Inf)`
-    // is surprising and ambiguous; omit the key instead. Fractional
-    // values <1 floor to 0, which would make `slice(-0)` return the
-    // entire file — guard against that too.
-    let effectiveLimit: number | null = null;
-    if (options.limit !== undefined) {
-      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: BufferSurpriseEvent[] = [];
-    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 {
-        // Malformed row — fail open, skip.
-      }
-    }
-
-    events.sort(
-      (left, right) => Date.parse(left.timestamp) - Date.parse(right.timestamp),
+    return this.memoryReadStore.readBufferSurpriseEvents(
+      options,
     );
-
-    if (effectiveLimit === null) return events;
-    // Slice over VALID rows, not raw lines, so malformed tails cannot
-    // mask good data above them. Sort by event timestamp before slicing
-    // so concurrent probe completion order cannot make an older scored
-    // turn look newer than a later scored turn.
-    return events.slice(-effectiveLimit);
   }
 
   async appendBehaviorSignals(events: BehaviorSignalEvent[]): Promise<number> {
@@ -5892,106 +5349,9 @@ export class StorageManager {
   private async readCompressionGuidelineStateFile(
     filePath: string,
   ): Promise<CompressionGuidelineOptimizerState | null> {
-    const isFiniteNonNegativeInteger = (value: unknown): value is number =>
-      typeof value === "number" && Number.isFinite(value) && Number.isInteger(value) && value >= 0;
-    const isValidActionSummary = (
-      value: unknown,
-    ): value is NonNullable<CompressionGuidelineOptimizerState["actionSummaries"]>[number] => {
-      if (!value || typeof value !== "object") return false;
-      const summary = value as NonNullable<CompressionGuidelineOptimizerState["actionSummaries"]>[number];
-      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: unknown,
-    ): value is NonNullable<CompressionGuidelineOptimizerState["ruleUpdates"]>[number] => {
-      if (!value || typeof value !== "object") return false;
-      const rule = value as NonNullable<CompressionGuidelineOptimizerState["ruleUpdates"]>[number];
-      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) as Partial<CompressionGuidelineOptimizerState>;
-      const sourceWindow = parsed?.sourceWindow as Partial<CompressionGuidelineOptimizerState["sourceWindow"]>;
-      const eventCounts = parsed?.eventCounts as Partial<CompressionGuidelineOptimizerState["eventCounts"]>;
-      const activationState =
-        parsed?.activationState === "draft" || parsed?.activationState === "active"
-          ? parsed.activationState
-          : undefined;
-      const contentHash =
-        typeof parsed?.contentHash === "string" && parsed.contentHash.length > 0
-          ? parsed.contentHash
-          : undefined;
-      const actionSummaries = Array.isArray(parsed?.actionSummaries)
-        ? parsed.actionSummaries.filter(isValidActionSummary)
-        : undefined;
-      const ruleUpdates = Array.isArray(parsed?.ruleUpdates)
-        ? parsed.ruleUpdates.filter(isValidRuleUpdate)
-        : undefined;
-      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: string): Promise<void> {
@@ -6220,40 +5580,9 @@ export class StorageManager {
       filePath: string;
     }>
   > {
-    const cacheKey = this.questionsDir;
-    const cached = StorageManager.questionsCache.get(cacheKey);
-    if (cached && Date.now() - cached.loadedAt < StorageManager.QUESTIONS_CACHE_TTL_MS) {
-      // Check dir mtime for cross-process invalidation — if another process
-      // wrote/resolved a question, the directory mtime will be newer than loadedAt.
-      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 {
-        // Dir doesn't exist — fall through to re-read
-      }
-    }
-
-    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). */
@@ -6554,9 +5883,6 @@ export class StorageManager {
     this.invalidateKnowledgeIndexCache();
   }
 
-  /**
-   * Set or rewrite the synthesis layer of an entity file.
-   */
   async updateEntitySynthesis(
     name: string,
     synthesis: string,
@@ -6569,45 +5895,11 @@ export class StorageManager {
       incrementVersion?: boolean;
     } = {},
   ): Promise<void> {
-    const filePath = path.join(this.entitiesDir, `${name}.md`);
-    let entity: EntityFile;
-    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() || undefined;
-    const entityUpdatedAt = options.entityUpdatedAt?.trim() || updatedAt || entity.updated || new Date().toISOString();
-    const synthesisTimelineCount = Number.isInteger(options.synthesisTimelineCount)
-      && (options.synthesisTimelineCount ?? 0) >= 0
-      ? options.synthesisTimelineCount
-      : undefined;
-    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([
-      ...new Set([name, this.normalizeEntityName(entity.name, entity.type)]),
-    ]);
-    this.invalidateKnowledgeIndexCache();
-    this.bumpMemoryStatusVersion(); // invalidate entity cache
+    return this.entityStore.updateEntitySynthesis(
+      name,
+      synthesis,
+      options,
+    );
   }
 
   /**
@@ -6731,52 +6023,9 @@ export class StorageManager {
   // 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(): Promise<EntityFile[]> {
-    const currentVersion = this.getMemoryStatusVersion();
-    const schemaCacheKey = buildEntitySchemaCacheKey(this.entitySchemas);
-    const cacheKey = `${this.getEntityCacheSecureStoreKey()}\u0000${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 [];
-
-      // Read all entity files in parallel batches to avoid O(N) sequential I/O.
-      // With 3000+ entity files, sequential reads can take 15-20s under load.
-      // Batching at 100 keeps file-descriptor pressure manageable while staying fast.
-      const BATCH_SIZE = 100;
-      const entities: EntityFile[] = [];
-      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;
-      // Directory doesn't exist yet
-      return [];
-    }
+    return this.entityStore.readAllEntityFiles(
+    );
   }
 
   /**
@@ -6820,77 +6069,14 @@ export class StorageManager {
     );
   }
 
-  /**
-   * Build the Knowledge Index: a compact markdown table of top-scored entities.
-   * Respects maxEntities and maxChars limits from config.
-   */
   async buildKnowledgeIndex(
     config: PluginConfig,
     overrides?: { maxEntities?: number; maxChars?: number },
   ): Promise<{ result: string; cached: boolean }> {
-    const useDefaultLimits =
-      overrides?.maxEntities === undefined &&
-      overrides?.maxChars === undefined;
-    // Return cached index if still fresh
-    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 = new Date();
-    const scored: ScoredEntity[] = 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),
-    }));
-
-    // Sort by score descending, take top N
-    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 };
-    }
-
-    // Build markdown table
-    const header = "## Knowledge Index\n\n| Entity | Type | Summary | Connected to |\n|--------|------|---------|-------------|";
-    const rows: string[] = [];
-    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(", ")
-        : "—";
-      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}\n${rows.join("\n")}\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). */
@@ -6905,275 +6091,9 @@ export class StorageManager {
   /** Max lines for profile.md before LLM consolidation triggers */
   private static readonly 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(): Promise<number> {
-    let merged = 0;
-    try {
-      const entries = await readdir(this.entitiesDir);
-      const mdFiles = entries.filter((e) => e.endsWith(".md"));
-
-      // Group files by their canonical name
-      const groups = new Map<string, string[]>();
-      for (const file of mdFiles) {
-        const baseName = file.replace(".md", "");
-        // Extract type and name from filename (type-rest-of-name)
-        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);
-      }
-
-      // Merge groups with more than one file
-      for (const [canonical, files] of groups) {
-        if (files.length <= 1) continue;
-
-        // Parse all files and merge into a single EntityFile
-        const mergedEntity: EntityFile = {
-          name: "",
-          type: "other",
-          created: "",
-          updated: "",
-          extraFrontmatterLines: [],
-          preSectionLines: [],
-          facts: [],
-          summary: undefined,
-          synthesis: undefined,
-          synthesisUpdatedAt: undefined,
-          synthesisTimelineCount: undefined,
-          synthesisStructuredFactCount: undefined,
-          synthesisStructuredFactDigest: undefined,
-          synthesisVersion: undefined,
-          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);
-
-            // Prefer specific types over "other"
-            if (!mergedEntity.type || mergedEntity.type === "other") {
-              mergedEntity.type = parsed.type;
-            }
-
-            // Keep latest update time
-            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;
-            }
-
-            // Keep longest/best name
-            if (parsed.name.length > mergedEntity.name.length) {
-              mergedEntity.name = parsed.name;
-            }
-
-            const parsedSynthesisUpdatedAt = parsed.synthesisUpdatedAt?.trim() || undefined;
-            const mergedSynthesisUpdatedAt = mergedEntity.synthesisUpdatedAt?.trim() || undefined;
-
-            // Prefer the freshest synthesis/summary available.
-            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;
-            }
-
-            // Collect all timeline evidence; facts are derived below.
-            mergedEntity.timeline.push(...parsed.timeline);
-
-            // Collect relationships (dedup later)
-            mergedEntity.relationships.push(...parsed.relationships);
-
-            // Collect activity entries
-            mergedEntity.activity.push(...parsed.activity);
-
-            // Collect aliases
-            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());
-
-            // Preserve custom metadata and user-authored freeform content from fragments.
-            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;
-            // Skip unreadable
-          }
-        }
-
-        // Deduplicate timeline entries and derive facts from the timeline.
-        const timelineKeys = new Set<string>();
-        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;
-        });
-        // Deduplicate relationships by target+label
-        const relKeys = new Set<string>();
-        mergedEntity.relationships = mergedEntity.relationships.filter((r) => {
-          const key = `${r.target}::${r.label}`;
-          if (relKeys.has(key)) return false;
-          relKeys.add(key);
-          return true;
-        });
-
-        // Sort activity by date descending, deduplicate by date+note
-        const actKeys = new Set<string>();
-        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));
-
-        // Deduplicate aliases
-        mergedEntity.aliases = [...new Set(mergedEntity.aliases)];
-        mergedEntity.structuredSections = sortStructuredSectionsBySchema(
-          mergedEntity.type,
-          mergedEntity.structuredSections ?? [],
-          this.entitySchemas,
-        );
-        mergedEntity.facts = compileEntityFacts(mergedEntity.timeline, mergedEntity.structuredSections);
-
-        const extraSectionKeys = new Set<string>();
-        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;
-        });
-
-        // Fallback name from canonical
-        if (!mergedEntity.name) {
-          const dashIdx = canonical.indexOf("-");
-          mergedEntity.name = dashIdx !== -1 ? canonical.slice(dashIdx + 1) : canonical;
-        }
-
-        mergedEntity.created = mergedEntity.created || mergedEntity.updated || new Date().toISOString();
-        mergedEntity.updated = mergedEntity.updated || new Date().toISOString();
-
-        const canonicalPath = path.join(this.entitiesDir, `${canonical}.md`);
-        await this.writeStorageSecureFile(canonicalPath, serializeEntityFile(mergedEntity, this.entitySchemas));
-
-        // Remove non-canonical files
-        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} → ${canonical}.md`);
-            } catch {
-              // Ignore
-            }
-          }
-        }
-      }
-    } catch (err) {
-      if (err instanceof SecureStoreLockedError || !isErrnoCode(err, "ENOENT")) throw err;
-      // Directory doesn't exist yet
-    }
-
-    return merged;
+    return this.entityStore.mergeFragmentedEntities(
+    );
   }
 
   async cleanExpiredCommitments(decayDays: number): Promise<MemoryFile[]> {