@remnic/core 9.3.753 → 9.3.755

package/src/storage.ts

@@ -4,6 +4,8 @@ import { createHash } from "node:crypto"
 import { normalizeContent, computeContentHash } from "./content-hash.js";;
 import path from "node:path";
 import { log } from "./logger.js";
+import { EntityStore } from "./storage/entity-store.js";
+import { selfDeps } from "./orchestration/self-deps.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";
@@ -1651,7 +1653,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 +1673,7 @@ function collectStructuredSectionFacts(structuredSections: EntityStructuredSecti
   return [...new Set(facts)];
 }
 
-function compileEntityFacts(
+export function compileEntityFacts(
   timeline: EntityTimelineEntry[],
   structuredSections: EntityStructuredSection[],
 ): string[] {
@@ -1811,7 +1813,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 +2191,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))
@@ -2259,8 +2261,9 @@ 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;
+  /** Read by storage/entity-store.ts (decomposition), hence not `private`. */
+  static readonly KNOWLEDGE_INDEX_CACHE_TTL_MS = 600_000; // 10 minutes (entity mutations invalidate)
   private 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>();
@@ -2514,6 +2517,18 @@ export class StorageManager {
   }
 
   /** The root directory of this storage instance. */
+  /** 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;
   }
@@ -3476,9 +3491,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,
+    );
   }
 
   /**
@@ -4109,124 +4126,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> {
@@ -5106,30 +5011,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(
+    );
   }
 
   /**
@@ -6554,9 +6443,6 @@ export class StorageManager {
     this.invalidateKnowledgeIndexCache();
   }
 
-  /**
-   * Set or rewrite the synthesis layer of an entity file.
-   */
   async updateEntitySynthesis(
     name: string,
     synthesis: string,
@@ -6569,45 +6455,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 +6583,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 +6629,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 +6651,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[]> {