@remnic/core 1.0.0

package/dist/chunk-QWUUMMIK.js

@@ -0,0 +1,3045 @@
+import {
+  SPECULATIVE_TTL_DAYS,
+  confidenceTier
+} from "./chunk-U4PV25RD.js";
+import {
+  getCachedEntities,
+  setCachedEntities
+} from "./chunk-ESSMF2FR.js";
+import {
+  inferMemoryStatus,
+  isArchivedMemoryPath,
+  sortMemoryLifecycleEvents,
+  toMemoryPathRel
+} from "./chunk-TP4FZJIZ.js";
+import {
+  normalizeProjectionPreview,
+  normalizeProjectionTags
+} from "./chunk-SCU65EZI.js";
+import {
+  readProjectedGovernanceRecord,
+  readProjectedMemoryBrowse,
+  readProjectedMemoryState,
+  readProjectedMemoryTimeline
+} from "./chunk-BOUYNNYD.js";
+import {
+  rotateMarkdownFileToArchive
+} from "./chunk-DM2T26WE.js";
+import {
+  closeContinuityIncidentRecord,
+  createContinuityIncidentRecord,
+  parseContinuityImprovementLoops,
+  parseContinuityIncident,
+  reviewContinuityLoopInMarkdown,
+  serializeContinuityIncident,
+  upsertContinuityLoopInMarkdown
+} from "./chunk-QSVPYQPG.js";
+import {
+  sanitizeMemoryContent
+} from "./chunk-M62O4P4T.js";
+import {
+  log
+} from "./chunk-KWBU5S5U.js";
+
+// src/storage.ts
+import { access, readdir, readFile, stat, writeFile, mkdir, unlink, rename, appendFile } from "fs/promises";
+import { appendFileSync, mkdirSync, statSync } from "fs";
+import { createHash } from "crypto";
+import path from "path";
+var ARTIFACT_SEARCH_STOPWORDS = /* @__PURE__ */ new Set([
+  "a",
+  "an",
+  "and",
+  "are",
+  "as",
+  "at",
+  "be",
+  "but",
+  "by",
+  "for",
+  "from",
+  "has",
+  "have",
+  "i",
+  "in",
+  "is",
+  "it",
+  "of",
+  "on",
+  "or",
+  "that",
+  "the",
+  "this",
+  "to",
+  "was",
+  "were",
+  "with"
+]);
+function tokenizeArtifactSearchText(input) {
+  return input.toLowerCase().split(/[^a-z0-9]+/i).map((t) => t.trim()).filter((t) => t.length >= 2).filter((t) => !ARTIFACT_SEARCH_STOPWORDS.has(t));
+}
+function serializeFrontmatter(fm) {
+  const lines = [
+    "---",
+    `id: ${fm.id}`,
+    `category: ${fm.category}`,
+    `created: ${fm.created}`,
+    `updated: ${fm.updated}`,
+    `source: ${fm.source}`,
+    `confidence: ${fm.confidence}`,
+    `confidenceTier: ${fm.confidenceTier}`,
+    `tags: [${fm.tags.map((t) => `"${t}"`).join(", ")}]`
+  ];
+  if (fm.entityRef) lines.push(`entityRef: ${fm.entityRef}`);
+  if (fm.supersedes) lines.push(`supersedes: ${fm.supersedes}`);
+  if (fm.expiresAt) lines.push(`expiresAt: ${fm.expiresAt}`);
+  if (fm.lineage && fm.lineage.length > 0) {
+    lines.push(`lineage: [${fm.lineage.map((l) => `"${l}"`).join(", ")}]`);
+  }
+  if (fm.status && fm.status !== "active") lines.push(`status: ${fm.status}`);
+  if (fm.supersededBy) lines.push(`supersededBy: ${fm.supersededBy}`);
+  if (fm.supersededAt) lines.push(`supersededAt: ${fm.supersededAt}`);
+  if (fm.archivedAt) lines.push(`archivedAt: ${fm.archivedAt}`);
+  if (fm.lifecycleState) lines.push(`lifecycleState: ${fm.lifecycleState}`);
+  if (fm.verificationState) lines.push(`verificationState: ${fm.verificationState}`);
+  if (fm.policyClass) lines.push(`policyClass: ${fm.policyClass}`);
+  if (fm.lastValidatedAt) lines.push(`lastValidatedAt: ${fm.lastValidatedAt}`);
+  if (fm.decayScore !== void 0) lines.push(`decayScore: ${fm.decayScore}`);
+  if (fm.heatScore !== void 0) lines.push(`heatScore: ${fm.heatScore}`);
+  if (fm.accessCount !== void 0 && fm.accessCount > 0) {
+    lines.push(`accessCount: ${fm.accessCount}`);
+  }
+  if (fm.lastAccessed) lines.push(`lastAccessed: ${fm.lastAccessed}`);
+  if (fm.importance) {
+    lines.push(`importanceScore: ${fm.importance.score}`);
+    lines.push(`importanceLevel: ${fm.importance.level}`);
+    if (fm.importance.reasons.length > 0) {
+      lines.push(
+        `importanceReasons: [${fm.importance.reasons.map((r) => `"${r.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`).join(", ")}]`
+      );
+    }
+    if (fm.importance.keywords.length > 0) {
+      lines.push(`importanceKeywords: [${fm.importance.keywords.map((k) => `"${k}"`).join(", ")}]`);
+    }
+  }
+  if (fm.parentId) lines.push(`parentId: ${fm.parentId}`);
+  if (fm.chunkIndex !== void 0) lines.push(`chunkIndex: ${fm.chunkIndex}`);
+  if (fm.chunkTotal !== void 0) lines.push(`chunkTotal: ${fm.chunkTotal}`);
+  if (fm.links && fm.links.length > 0) {
+    lines.push("links:");
+    for (const link of fm.links) {
+      lines.push(`  - targetId: ${link.targetId}`);
+      lines.push(`    linkType: ${link.linkType}`);
+      lines.push(`    strength: ${link.strength}`);
+      if (link.reason) lines.push(`    reason: ${JSON.stringify(link.reason)}`);
+    }
+  }
+  if (fm.intentGoal) lines.push(`intentGoal: ${fm.intentGoal}`);
+  if (fm.intentActionType) lines.push(`intentActionType: ${fm.intentActionType}`);
+  if (fm.intentEntityTypes && fm.intentEntityTypes.length > 0) {
+    lines.push(`intentEntityTypes: [${fm.intentEntityTypes.map((t) => `"${t}"`).join(", ")}]`);
+  }
+  if (fm.artifactType) lines.push(`artifactType: ${fm.artifactType}`);
+  if (fm.sourceMemoryId) lines.push(`sourceMemoryId: ${fm.sourceMemoryId}`);
+  if (fm.sourceTurnId) lines.push(`sourceTurnId: ${fm.sourceTurnId}`);
+  if (fm.memoryKind) lines.push(`memoryKind: ${fm.memoryKind}`);
+  if (fm.structuredAttributes && Object.keys(fm.structuredAttributes).length > 0) {
+    lines.push(`structuredAttributes: ${JSON.stringify(fm.structuredAttributes)}`);
+  }
+  lines.push("---");
+  return lines.join("\n");
+}
+function parseStructuredAttributes(raw) {
+  if (!raw || !raw.trim()) return void 0;
+  try {
+    const parsed = JSON.parse(raw);
+    if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+      const result = {};
+      for (const [k, v] of Object.entries(parsed)) {
+        if (typeof k === "string" && typeof v === "string") {
+          result[k] = v;
+        }
+      }
+      return Object.keys(result).length > 0 ? result : void 0;
+    }
+  } catch {
+  }
+  return void 0;
+}
+function parseLinkReasonValue(rawValue) {
+  const legacyValue = rawValue.replace(/\\"/g, '"');
+  const looksLikeLegacyPath = !rawValue.includes("\\\\") && (/[A-Za-z]:\\[A-Za-z0-9._ -]+(?:\\[A-Za-z0-9._ -]+)*/.test(rawValue) || /\\[A-Za-z0-9._ -]+\\[A-Za-z0-9._ -]+/.test(rawValue));
+  if (looksLikeLegacyPath) {
+    return legacyValue;
+  }
+  try {
+    return JSON.parse(`"${rawValue}"`);
+  } catch {
+    return legacyValue;
+  }
+}
+function parseFrontmatter(raw) {
+  const match = raw.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+  if (!match) return null;
+  const fmBlock = match[1];
+  const content = match[2].trim();
+  const fm = {};
+  for (const line of fmBlock.split("\n")) {
+    const colonIdx = line.indexOf(":");
+    if (colonIdx === -1) continue;
+    const key = line.slice(0, colonIdx).trim();
+    const value = line.slice(colonIdx + 1).trim();
+    fm[key] = value;
+  }
+  let tags = [];
+  const tagsStr = fm.tags ?? "";
+  const tagMatch = tagsStr.match(/\[(.*)]/);
+  if (tagMatch) {
+    tags = tagMatch[1].split(",").map((t) => t.trim().replace(/^"|"$/g, "")).filter(Boolean);
+  }
+  let intentEntityTypes;
+  const intentEntityTypesStr = fm.intentEntityTypes ?? "";
+  const intentEntityTypesMatch = intentEntityTypesStr.match(/\[(.*)]/);
+  if (intentEntityTypesMatch) {
+    intentEntityTypes = intentEntityTypesMatch[1].split(",").map((t) => t.trim().replace(/^"|"$/g, "")).filter(Boolean);
+  }
+  const conf = parseFloat(fm.confidence ?? "0.8");
+  let lineage;
+  const lineageStr = fm.lineage ?? "";
+  const lineageMatch = lineageStr.match(/\[(.*)]/);
+  if (lineageMatch) {
+    lineage = lineageMatch[1].split(",").map((l) => l.trim().replace(/^"|"$/g, "")).filter(Boolean);
+  }
+  const accessCount = fm.accessCount ? parseInt(fm.accessCount, 10) : void 0;
+  const decayScore = fm.decayScore !== void 0 ? parseFloat(fm.decayScore) : void 0;
+  const heatScore = fm.heatScore !== void 0 ? parseFloat(fm.heatScore) : void 0;
+  let importance;
+  if (fm.importanceScore) {
+    const score = parseFloat(fm.importanceScore);
+    const level = fm.importanceLevel || "normal";
+    let reasons = [];
+    const reasonsStr = fm.importanceReasons ?? "";
+    if (reasonsStr.trim().startsWith("[") && reasonsStr.trim().endsWith("]")) {
+      const reasonMatches = reasonsStr.matchAll(/"((?:\\.|[^"\\])*)"/g);
+      for (const match2 of reasonMatches) {
+        const reason = parseLinkReasonValue(match2[1]);
+        if (reason.length > 0) {
+          reasons.push(reason);
+        }
+      }
+    }
+    let keywords = [];
+    const keywordsStr = fm.importanceKeywords ?? "";
+    const keywordsMatch = keywordsStr.match(/\[(.*)]/);
+    if (keywordsMatch) {
+      keywords = keywordsMatch[1].split(",").map((k) => k.trim().replace(/^"|"$/g, "")).filter(Boolean);
+    }
+    importance = { score, level, reasons, keywords };
+  }
+  const result = {
+    frontmatter: {
+      id: fm.id ?? "",
+      category: fm.category ?? "fact",
+      created: fm.created ?? (/* @__PURE__ */ new Date()).toISOString(),
+      updated: fm.updated ?? (/* @__PURE__ */ new Date()).toISOString(),
+      source: fm.source ?? "unknown",
+      confidence: conf,
+      confidenceTier: fm.confidenceTier || confidenceTier(conf),
+      tags,
+      entityRef: fm.entityRef || void 0,
+      supersedes: fm.supersedes || void 0,
+      expiresAt: fm.expiresAt || void 0,
+      lineage: lineage && lineage.length > 0 ? lineage : void 0,
+      // Status management
+      status: fm.status || "active",
+      supersededBy: fm.supersededBy || void 0,
+      supersededAt: fm.supersededAt || void 0,
+      archivedAt: fm.archivedAt || void 0,
+      lifecycleState: fm.lifecycleState || void 0,
+      verificationState: fm.verificationState || void 0,
+      policyClass: fm.policyClass || void 0,
+      lastValidatedAt: fm.lastValidatedAt || void 0,
+      decayScore: Number.isFinite(decayScore) ? decayScore : void 0,
+      heatScore: Number.isFinite(heatScore) ? heatScore : void 0,
+      // Access tracking
+      accessCount: accessCount && accessCount > 0 ? accessCount : void 0,
+      lastAccessed: fm.lastAccessed || void 0,
+      // Importance scoring
+      importance,
+      // Chunking
+      parentId: fm.parentId || void 0,
+      chunkIndex: fm.chunkIndex ? parseInt(fm.chunkIndex, 10) : void 0,
+      chunkTotal: fm.chunkTotal ? parseInt(fm.chunkTotal, 10) : void 0,
+      // Links are parsed separately below
+      intentGoal: fm.intentGoal || void 0,
+      intentActionType: fm.intentActionType || void 0,
+      intentEntityTypes: intentEntityTypes && intentEntityTypes.length > 0 ? intentEntityTypes : void 0,
+      artifactType: fm.artifactType || void 0,
+      sourceMemoryId: fm.sourceMemoryId || void 0,
+      sourceTurnId: fm.sourceTurnId || void 0,
+      // v8.0 Phase 2B: HiMem episode/note classification
+      memoryKind: fm.memoryKind || void 0,
+      // Structured attributes (JSON on a single line)
+      structuredAttributes: parseStructuredAttributes(fm.structuredAttributes)
+    },
+    content
+  };
+  if (fmBlock.includes("links:")) {
+    const links = [];
+    const linkMatches = fmBlock.matchAll(
+      /- targetId: (\S+)\s+linkType: (\S+)\s+strength: ([\d.]+)(?:\s+reason: "((?:\\.|[^"\\])*)")?/g
+    );
+    for (const match2 of linkMatches) {
+      links.push({
+        targetId: match2[1],
+        linkType: match2[2],
+        strength: parseFloat(match2[3]),
+        reason: match2[4] ? parseLinkReasonValue(match2[4]) : void 0
+      });
+    }
+    if (links.length > 0) {
+      result.frontmatter.links = links;
+    }
+  }
+  return result;
+}
+function normalizeFrontmatterForPath(frontmatter, pathRel) {
+  if (isArchivedMemoryPath(pathRel) && (!frontmatter.status || frontmatter.status === "active")) {
+    return {
+      ...frontmatter,
+      status: "archived"
+    };
+  }
+  return frontmatter;
+}
+function inferCurrentStateStatus(frontmatter, pathRel, fallbackStatus) {
+  return inferMemoryStatus(frontmatter, pathRel, fallbackStatus);
+}
+var userAliases = {};
+var BUILTIN_ALIASES = {
+  openclaw: "openclaw",
+  "open-claw": "openclaw"
+};
+function normalizeEntityName(raw, type) {
+  const rawStr = typeof raw === "string" ? raw : "";
+  const typeStr = typeof type === "string" && type.trim().length > 0 ? type : "entity";
+  let name = rawStr.toLowerCase().trim();
+  const typePrefix = `${typeStr.toLowerCase()}-`;
+  if (name.startsWith(typePrefix)) {
+    name = name.slice(typePrefix.length);
+  }
+  let normalized = name.replace(/[^a-z0-9]+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
+  if (userAliases[normalized]) {
+    normalized = userAliases[normalized];
+  } else if (BUILTIN_ALIASES[normalized]) {
+    normalized = BUILTIN_ALIASES[normalized];
+  }
+  return `${typeStr.toLowerCase()}-${normalized}`;
+}
+function levenshtein(a, b) {
+  const m = a.length;
+  const n = b.length;
+  if (m === 0) return n;
+  if (n === 0) return m;
+  const dp = Array.from({ length: m + 1 }, () => new Array(n + 1).fill(0));
+  for (let i = 0; i <= m; i++) dp[i][0] = i;
+  for (let j = 0; j <= n; j++) dp[0][j] = j;
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      dp[i][j] = a[i - 1] === b[j - 1] ? dp[i - 1][j - 1] : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
+    }
+  }
+  return dp[m][n];
+}
+function dehyphenate(s) {
+  return s.replace(/-/g, "");
+}
+var ContentHashIndex = class _ContentHashIndex {
+  hashes = /* @__PURE__ */ new Set();
+  dirty = false;
+  filePath;
+  constructor(stateDir) {
+    this.filePath = path.join(stateDir, "fact-hashes.txt");
+  }
+  /** Load existing hashes from disk. Safe to call multiple times. */
+  async load() {
+    try {
+      const raw = await readFile(this.filePath, "utf-8");
+      for (const line of raw.split("\n")) {
+        const trimmed = line.trim();
+        if (trimmed.length > 0) {
+          this.hashes.add(trimmed);
+        }
+      }
+      log.debug(`content-hash index: loaded ${this.hashes.size} hashes`);
+    } catch {
+      log.debug("content-hash index: no existing index \u2014 starting fresh");
+    }
+  }
+  /** Check if content already exists in the index. */
+  has(content) {
+    return this.hashes.has(_ContentHashIndex.computeHash(content));
+  }
+  /** Add content hash to the index. */
+  add(content) {
+    const hash = _ContentHashIndex.computeHash(content);
+    if (!this.hashes.has(hash)) {
+      this.hashes.add(hash);
+      this.dirty = true;
+    }
+  }
+  get size() {
+    return this.hashes.size;
+  }
+  /** Persist index to disk if changed. */
+  async save() {
+    if (!this.dirty) return;
+    await mkdir(path.dirname(this.filePath), { recursive: true });
+    await writeFile(this.filePath, [...this.hashes].join("\n") + "\n", "utf-8");
+    this.dirty = false;
+    log.debug(`content-hash index: saved ${this.hashes.size} hashes`);
+  }
+  /** Remove a hash from the index (used when archiving/deleting). */
+  remove(content) {
+    const hash = _ContentHashIndex.computeHash(content);
+    if (this.hashes.delete(hash)) {
+      this.dirty = true;
+    }
+  }
+  /** Normalize content and compute SHA-256 hash. */
+  static normalizeContent(content) {
+    return content.toLowerCase().replace(/[^a-z0-9\s]/g, " ").replace(/\s+/g, " ").trim();
+  }
+  /** Normalize content and compute SHA-256 hash. */
+  static computeHash(content) {
+    const normalized = _ContentHashIndex.normalizeContent(content);
+    return createHash("sha256").update(normalized).digest("hex");
+  }
+};
+function parseEntityFile(content) {
+  const lines = content.split("\n");
+  let name = "";
+  let type = "other";
+  let updated = "";
+  let summary;
+  const facts = [];
+  const relationships = [];
+  const activity = [];
+  const aliases = [];
+  const headingLine = lines.find((l) => l.startsWith("# "));
+  if (headingLine) name = headingLine.slice(2).trim();
+  const typeLine = lines.find((l) => l.startsWith("**Type:**"));
+  if (typeLine) type = typeLine.replace("**Type:**", "").trim();
+  const updatedLine = lines.find((l) => l.startsWith("**Updated:**"));
+  if (updatedLine) updated = updatedLine.replace("**Updated:**", "").trim();
+  let section = "";
+  for (const line of lines) {
+    if (line.startsWith("## ")) {
+      section = line.slice(3).trim().toLowerCase();
+      continue;
+    }
+    if (!line.startsWith("- ")) continue;
+    const bullet = line.slice(2).trim();
+    if (!bullet) continue;
+    switch (section) {
+      case "facts":
+        facts.push(bullet);
+        break;
+      case "summary":
+        break;
+      case "connected to": {
+        const relMatch = bullet.match(/^\[\[([^\]]+)\]\]\s*[—–-]\s*(.+)$/);
+        if (relMatch) {
+          relationships.push({ target: relMatch[1].trim(), label: relMatch[2].trim() });
+        }
+        break;
+      }
+      case "activity": {
+        const actMatch = bullet.match(/^(\d{4}-\d{2}-\d{2}):\s*(.+)$/);
+        if (actMatch) {
+          activity.push({ date: actMatch[1], note: actMatch[2].trim() });
+        }
+        break;
+      }
+      case "aliases":
+        aliases.push(bullet);
+        break;
+    }
+  }
+  const summaryIdx = lines.findIndex((l) => l.startsWith("## Summary"));
+  if (summaryIdx !== -1) {
+    const summaryLines = [];
+    for (let i = summaryIdx + 1; i < lines.length; i++) {
+      if (lines[i].startsWith("## ")) break;
+      const trimmed = lines[i].trim();
+      if (trimmed) summaryLines.push(trimmed);
+    }
+    if (summaryLines.length > 0) summary = summaryLines.join(" ");
+  }
+  return { name, type, updated, facts, summary, relationships, activity, aliases };
+}
+function serializeEntityFile(entity) {
+  const lines = [
+    `# ${entity.name}`,
+    "",
+    `**Type:** ${entity.type}`,
+    `**Updated:** ${entity.updated || (/* @__PURE__ */ new Date()).toISOString()}`,
+    ""
+  ];
+  if (entity.summary) {
+    lines.push("## Summary", "", entity.summary, "");
+  }
+  lines.push("## Facts", "");
+  for (const f of entity.facts) {
+    lines.push(`- ${f}`);
+  }
+  lines.push("");
+  if (entity.relationships.length > 0) {
+    lines.push("## Connected to", "");
+    for (const rel of entity.relationships) {
+      lines.push(`- [[${rel.target}]] \u2014 ${rel.label}`);
+    }
+    lines.push("");
+  }
+  if (entity.activity.length > 0) {
+    lines.push("## Activity", "");
+    for (const act of entity.activity) {
+      lines.push(`- ${act.date}: ${act.note}`);
+    }
+    lines.push("");
+  }
+  if (entity.aliases.length > 0) {
+    lines.push("## Aliases", "");
+    for (const alias of entity.aliases) {
+      lines.push(`- ${alias}`);
+    }
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+var StorageManager = class _StorageManager {
+  constructor(baseDir) {
+    this.baseDir = baseDir;
+  }
+  baseDir;
+  knowledgeIndexCache = null;
+  static KNOWLEDGE_INDEX_CACHE_TTL_MS = 6e5;
+  // 10 minutes (entity mutations invalidate)
+  artifactIndexCache = null;
+  static ARTIFACT_INDEX_CACHE_TTL_MS = 6e4;
+  // 1 minute
+  static artifactWriteVersionByDir = /* @__PURE__ */ new Map();
+  static memoryStatusVersionByDir = /* @__PURE__ */ new Map();
+  // Module-level cache for readAllMemories() keyed by base directory.
+  // Shared across all StorageManager instances to avoid duplicate I/O when
+  // multiple concurrent callers (e.g. verifiedRecall + verifiedRules) read the
+  // same directory simultaneously.  In-flight deduplication prevents multiple
+  // concurrent reads of the same directory.
+  //
+  // Stale-while-revalidate: once the cache has a value, subsequent reads after
+  // TTL expiry return the stale cached data immediately and kick off a background
+  // refresh.  This eliminates the 13-60 s cold-scan penalty that would otherwise
+  // block recall requests every 5 minutes on large memory collections (80k+ files).
+  static allMemoriesInFlight = /* @__PURE__ */ new Map();
+  // Cache for readQuestions() — avoids serially re-reading tens of thousands of
+  // question files on every recall.  60-second TTL is intentionally short so that
+  // newly written questions surface quickly.
+  static QUESTIONS_CACHE_TTL_MS = 6e4;
+  // 1 minute
+  static questionsCache = /* @__PURE__ */ new Map();
+  factHashIndex = null;
+  factHashIndexLoadPromise = null;
+  factHashIndexAuthoritative = null;
+  factHashIndexAuthoritativePromise = null;
+  /** The root directory of this storage instance. */
+  get dir() {
+    return this.baseDir;
+  }
+  identityFilePath(workspaceDir, namespace) {
+    const rawNamespace = typeof namespace === "string" ? namespace.trim() : "";
+    if (!rawNamespace) return path.join(workspaceDir, "IDENTITY.md");
+    const safeNamespace = rawNamespace.replace(/[^a-zA-Z0-9._-]/g, "-");
+    return path.join(workspaceDir, `IDENTITY.${safeNamespace}.md`);
+  }
+  versionFilePath(kind) {
+    const fileName = kind === "memory-status" ? ".memory-status-version.log" : ".artifact-write-version.log";
+    return path.join(this.stateDir, fileName);
+  }
+  bumpSharedVersion(kind, fallbackMap) {
+    const filePath = this.versionFilePath(kind);
+    try {
+      mkdirSync(this.stateDir, { recursive: true });
+      appendFileSync(filePath, "x");
+      const next = statSync(filePath).size;
+      fallbackMap.set(this.baseDir, next);
+      return next;
+    } catch {
+      const next = (fallbackMap.get(this.baseDir) ?? 0) + 1;
+      fallbackMap.set(this.baseDir, next);
+      return next;
+    }
+  }
+  readSharedVersion(kind, fallbackMap) {
+    const filePath = this.versionFilePath(kind);
+    try {
+      return statSync(filePath).size;
+    } catch {
+      return fallbackMap.get(this.baseDir) ?? 0;
+    }
+  }
+  bumpMemoryStatusVersion() {
+    this.bumpSharedVersion("memory-status", _StorageManager.memoryStatusVersionByDir);
+  }
+  getMemoryStatusVersion() {
+    return this.readSharedVersion("memory-status", _StorageManager.memoryStatusVersionByDir);
+  }
+  bumpArtifactWriteVersion() {
+    return this.bumpSharedVersion("artifact-write", _StorageManager.artifactWriteVersionByDir);
+  }
+  getArtifactWriteVersion() {
+    return this.readSharedVersion("artifact-write", _StorageManager.artifactWriteVersionByDir);
+  }
+  get factsDir() {
+    return path.join(this.baseDir, "facts");
+  }
+  get correctionsDir() {
+    return path.join(this.baseDir, "corrections");
+  }
+  get entitiesDir() {
+    return path.join(this.baseDir, "entities");
+  }
+  get stateDir() {
+    return path.join(this.baseDir, "state");
+  }
+  get factHashIndexReadyPath() {
+    return path.join(this.stateDir, "fact-hashes.ready");
+  }
+  async getFactHashIndex() {
+    if (this.factHashIndex) {
+      return this.factHashIndex;
+    }
+    if (!this.factHashIndexLoadPromise) {
+      const index = new ContentHashIndex(this.stateDir);
+      this.factHashIndexLoadPromise = index.load().then(() => {
+        this.factHashIndex = index;
+        return index;
+      }).catch((err) => {
+        this.factHashIndexLoadPromise = null;
+        throw err;
+      });
+    }
+    return this.factHashIndexLoadPromise;
+  }
+  async ensureFactHashIndexAuthoritative() {
+    if (this.factHashIndexAuthoritative === true) {
+      return;
+    }
+    if (this.factHashIndexAuthoritativePromise) {
+      await this.factHashIndexAuthoritativePromise;
+      return;
+    }
+    this.factHashIndexAuthoritativePromise = (async () => {
+      try {
+        await access(this.factHashIndexReadyPath);
+        this.factHashIndexAuthoritative = true;
+        return;
+      } catch {
+      }
+      const factHashIndex = await this.getFactHashIndex();
+      const existing = await this.readAllMemories();
+      for (const memory of existing) {
+        if (memory.frontmatter.category !== "fact") continue;
+        if (inferMemoryStatus(memory.frontmatter, memory.path) !== "active") continue;
+        factHashIndex.add(memory.content);
+      }
+      await factHashIndex.save();
+      await mkdir(path.dirname(this.factHashIndexReadyPath), { recursive: true });
+      await writeFile(this.factHashIndexReadyPath, "v1\n", "utf-8");
+      this.factHashIndexAuthoritative = true;
+    })().finally(() => {
+      this.factHashIndexAuthoritativePromise = null;
+    });
+    await this.factHashIndexAuthoritativePromise;
+  }
+  get questionsDir() {
+    return path.join(this.baseDir, "questions");
+  }
+  get artifactsDir() {
+    return path.join(this.baseDir, "artifacts");
+  }
+  get identityDir() {
+    return path.join(this.baseDir, "identity");
+  }
+  get identityAnchorPath() {
+    return path.join(this.identityDir, "identity-anchor.md");
+  }
+  get identityIncidentsDir() {
+    return path.join(this.identityDir, "incidents");
+  }
+  get identityAuditsWeeklyDir() {
+    return path.join(this.identityDir, "audits", "weekly");
+  }
+  get identityAuditsMonthlyDir() {
+    return path.join(this.identityDir, "audits", "monthly");
+  }
+  get identityImprovementLoopsPath() {
+    return path.join(this.identityDir, "improvement-loops.md");
+  }
+  get identityReflectionsPath() {
+    return path.join(this.identityDir, "reflections.md");
+  }
+  get profilePath() {
+    return path.join(this.baseDir, "profile.md");
+  }
+  get memoryActionsPath() {
+    return path.join(this.stateDir, "memory-actions.jsonl");
+  }
+  get memoryLifecycleLedgerPath() {
+    return path.join(this.stateDir, "memory-lifecycle-ledger.jsonl");
+  }
+  get compressionGuidelinesPath() {
+    return path.join(this.stateDir, "compression-guidelines.md");
+  }
+  get compressionGuidelineDraftPath() {
+    return path.join(this.stateDir, "compression-guidelines.draft.md");
+  }
+  get compressionGuidelineStatePath() {
+    return path.join(this.stateDir, "compression-guideline-state.json");
+  }
+  get compressionGuidelineDraftStatePath() {
+    return path.join(this.stateDir, "compression-guideline-draft-state.json");
+  }
+  get behaviorSignalsPath() {
+    return path.join(this.stateDir, "behavior-signals.jsonl");
+  }
+  /**
+   * Load user-defined entity aliases from config/aliases.json in the memory store.
+   * File format: { "variant": "canonical", "variant2": "canonical", ... }
+   * Call this once at startup (e.g. from orchestrator.initialize()).
+   */
+  async loadAliases() {
+    const aliasPath = path.join(this.baseDir, "config", "aliases.json");
+    try {
+      const raw = await readFile(aliasPath, "utf-8");
+      const parsed = JSON.parse(raw);
+      if (typeof parsed === "object" && parsed !== null) {
+        userAliases = parsed;
+        log.debug(`loaded ${Object.keys(userAliases).length} entity aliases from ${aliasPath}`);
+      }
+    } catch {
+      log.debug("no config/aliases.json found \u2014 using built-in aliases only");
+    }
+  }
+  async ensureDirectories() {
+    const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+    await mkdir(path.join(this.factsDir, today), { recursive: true });
+    await mkdir(this.correctionsDir, { recursive: true });
+    await mkdir(this.entitiesDir, { recursive: true });
+    await mkdir(this.stateDir, { recursive: true });
+    await mkdir(this.questionsDir, { recursive: true });
+    await mkdir(this.artifactsDir, { recursive: true });
+    await mkdir(this.identityDir, { recursive: true });
+    await mkdir(this.identityIncidentsDir, { recursive: true });
+    await mkdir(this.identityAuditsWeeklyDir, { recursive: true });
+    await mkdir(this.identityAuditsMonthlyDir, { recursive: true });
+    await mkdir(path.join(this.baseDir, "config"), { recursive: true });
+  }
+  async writeMemory(category, content, options = {}) {
+    await this.ensureDirectories();
+    const now = /* @__PURE__ */ new Date();
+    const today = now.toISOString().slice(0, 10);
+    const id = `${category}-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`;
+    const conf = options.confidence ?? 0.8;
+    const tier = confidenceTier(conf);
+    let expiresAt;
+    if (typeof options.expiresAt === "string" && options.expiresAt.length > 0) {
+      expiresAt = options.expiresAt;
+    } else if (tier === "speculative") {
+      const expiry = new Date(now.getTime() + SPECULATIVE_TTL_DAYS * 24 * 60 * 60 * 1e3);
+      expiresAt = expiry.toISOString();
+    }
+    const fm = {
+      id,
+      category,
+      created: now.toISOString(),
+      updated: now.toISOString(),
+      source: options.source ?? "extraction",
+      confidence: conf,
+      confidenceTier: tier,
+      tags: options.tags ?? [],
+      entityRef: options.entityRef,
+      supersedes: options.supersedes,
+      expiresAt,
+      lineage: options.lineage,
+      importance: options.importance,
+      links: options.links,
+      intentGoal: options.intentGoal,
+      intentActionType: options.intentActionType,
+      intentEntityTypes: options.intentEntityTypes,
+      artifactType: options.artifactType,
+      sourceMemoryId: options.sourceMemoryId,
+      sourceTurnId: options.sourceTurnId,
+      memoryKind: options.memoryKind,
+      structuredAttributes: options.structuredAttributes
+    };
+    let enrichedContent = content;
+    if (options.structuredAttributes && Object.keys(options.structuredAttributes).length > 0) {
+      const attrLines = Object.entries(options.structuredAttributes).map(([k, v]) => `${k}: ${v}`).join("; ");
+      enrichedContent = `${content}
+[Attributes: ${attrLines}]`;
+    }
+    const sanitized = sanitizeMemoryContent(enrichedContent);
+    if (!sanitized.clean) {
+      log.warn(`memory content sanitized for ${id}; violations=${sanitized.violations.join(", ")}`);
+    }
+    const fileContent = `${serializeFrontmatter(fm)}
+
+${sanitized.text}
+`;
+    let filePath;
+    if (category === "correction") {
+      filePath = path.join(this.correctionsDir, `${id}.md`);
+    } else {
+      filePath = path.join(this.factsDir, today, `${id}.md`);
+    }
+    await writeFile(filePath, fileContent, "utf-8");
+    this.invalidateAllMemoriesCache();
+    await this.appendGeneratedMemoryLifecycleEventFailOpen("storage.writeMemory", {
+      memoryId: id,
+      eventType: "created",
+      timestamp: fm.created,
+      actor: options.actor ?? "storage.writeMemory",
+      after: this.summarizeLifecycleState(fm, filePath),
+      relatedMemoryIds: [
+        ...options.supersedes ? [options.supersedes] : [],
+        ...(options.lineage ?? []).filter(Boolean)
+      ]
+    });
+    if (category === "fact") {
+      try {
+        const factHashIndex = await this.getFactHashIndex();
+        factHashIndex.add(sanitized.text);
+        await factHashIndex.save();
+      } catch (err) {
+        log.warn(`storage.writeMemory completed but failed to update fact hash index: ${err}`);
+      }
+    }
+    log.debug(`wrote memory ${id} to ${filePath}`);
+    return id;
+  }
+  async hasFactContentHash(content) {
+    await this.ensureFactHashIndexAuthoritative();
+    const factHashIndex = await this.getFactHashIndex();
+    const sanitized = sanitizeMemoryContent(content);
+    return factHashIndex.has(sanitized.text);
+  }
+  async isFactContentHashAuthoritative() {
+    await this.ensureFactHashIndexAuthoritative();
+    return true;
+  }
+  async writeArtifact(quote, options = {}) {
+    await this.ensureDirectories();
+    const now = /* @__PURE__ */ new Date();
+    const day = now.toISOString().slice(0, 10);
+    const dir = path.join(this.artifactsDir, day);
+    await mkdir(dir, { recursive: true });
+    const id = `artifact-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`;
+    const fm = {
+      id,
+      category: "fact",
+      created: now.toISOString(),
+      updated: now.toISOString(),
+      source: "artifact",
+      confidence: options.confidence ?? 0.9,
+      confidenceTier: confidenceTier(options.confidence ?? 0.9),
+      tags: options.tags ?? [],
+      artifactType: options.artifactType ?? "fact",
+      sourceMemoryId: options.sourceMemoryId,
+      sourceTurnId: options.sourceTurnId,
+      intentGoal: options.intentGoal,
+      intentActionType: options.intentActionType,
+      intentEntityTypes: options.intentEntityTypes
+    };
+    const sanitized = sanitizeMemoryContent(quote);
+    if (!sanitized.clean) {
+      log.warn(`artifact content rejected for ${id}; violations=${sanitized.violations.join(", ")}`);
+      return "";
+    }
+    const filePath = path.join(dir, `${id}.md`);
+    await writeFile(filePath, `${serializeFrontmatter(fm)}
+
+${sanitized.text}
+`, "utf-8");
+    const actor = typeof options.actor === "string" && options.actor.length > 0 ? options.actor : "storage.writeArtifact";
+    await this.appendGeneratedMemoryLifecycleEventFailOpen("storage.writeArtifact", {
+      memoryId: id,
+      eventType: "created",
+      timestamp: fm.created,
+      actor,
+      after: this.summarizeLifecycleState(fm, filePath),
+      relatedMemoryIds: options.sourceMemoryId ? [options.sourceMemoryId] : []
+    });
+    this.bumpArtifactWriteVersion();
+    this.artifactIndexCache = null;
+    return id;
+  }
+  async readAllArtifactsCached() {
+    if (this.artifactIndexCache && Date.now() - this.artifactIndexCache.loadedAtMs <= _StorageManager.ARTIFACT_INDEX_CACHE_TTL_MS && this.artifactIndexCache.writeVersion === this.getArtifactWriteVersion()) {
+      return this.artifactIndexCache.memories;
+    }
+    const scanArtifacts = async () => {
+      const artifacts = [];
+      const readDir = async (dir) => {
+        try {
+          const entries = await readdir(dir, { withFileTypes: true });
+          for (const entry of entries) {
+            const fullPath = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+              await readDir(fullPath);
+              continue;
+            }
+            if (!entry.name.endsWith(".md")) continue;
+            const memory = await this.readMemoryByPath(fullPath);
+            if (!memory) continue;
+            artifacts.push(memory);
+          }
+        } catch {
+        }
+      };
+      await readDir(this.artifactsDir);
+      return artifacts;
+    };
+    const MAX_REBUILD_RETRIES = 2;
+    let latestArtifacts = [];
+    for (let attempt = 0; attempt <= MAX_REBUILD_RETRIES; attempt += 1) {
+      const versionBefore = this.getArtifactWriteVersion();
+      const artifacts = await scanArtifacts();
+      const versionAfter = this.getArtifactWriteVersion();
+      latestArtifacts = artifacts;
+      if (versionAfter === versionBefore) {
+        this.artifactIndexCache = { memories: artifacts, loadedAtMs: Date.now(), writeVersion: versionAfter };
+        return artifacts;
+      }
+    }
+    this.artifactIndexCache = null;
+    return latestArtifacts;
+  }
+  async searchArtifacts(query, maxResults) {
+    const tokens = tokenizeArtifactSearchText(query);
+    if (tokens.length === 0) return [];
+    const artifacts = await this.readAllArtifactsCached();
+    const hits = [];
+    for (const memory of artifacts) {
+      const indexedTokens = new Set(
+        tokenizeArtifactSearchText(`${memory.content} ${(memory.frontmatter.tags ?? []).join(" ")}`)
+      );
+      const score = tokens.reduce((sum, t) => sum + (indexedTokens.has(t) ? 1 : 0), 0);
+      if (score > 0) {
+        hits.push({ score, memory });
+      }
+    }
+    hits.sort((a, b) => b.score - a.score);
+    return hits.slice(0, maxResults).map((h) => h.memory);
+  }
+  async writeEntity(name, type, facts) {
+    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) ? facts.filter((f) => typeof f === "string") : [];
+    let normalized = normalizeEntityName(name, type);
+    const match = await this.findMatchingEntity(name, type);
+    if (match && match !== normalized) {
+      log.debug(`fuzzy match: "${normalized}" \u2192 existing "${match}"`);
+      normalized = match;
+    }
+    const filePath = path.join(this.entitiesDir, `${normalized}.md`);
+    let entity = {
+      name,
+      type,
+      updated: (/* @__PURE__ */ new Date()).toISOString(),
+      facts: [],
+      summary: void 0,
+      relationships: [],
+      activity: [],
+      aliases: []
+    };
+    try {
+      const existing = await readFile(filePath, "utf-8");
+      entity = parseEntityFile(existing);
+    } catch {
+    }
+    entity.facts = [.../* @__PURE__ */ new Set([...entity.facts, ...safeFacts])];
+    entity.name = name;
+    entity.type = type;
+    entity.updated = (/* @__PURE__ */ new Date()).toISOString();
+    await writeFile(filePath, serializeEntityFile(entity), "utf-8");
+    this.invalidateKnowledgeIndexCache();
+    this.bumpMemoryStatusVersion();
+    log.debug(`wrote entity ${normalized}`);
+    return normalized;
+  }
+  async readProfile() {
+    try {
+      return await readFile(this.profilePath, "utf-8");
+    } catch {
+      return "";
+    }
+  }
+  async writeProfile(content) {
+    await this.ensureDirectories();
+    await writeFile(this.profilePath, content, "utf-8");
+    log.debug("updated profile.md");
+  }
+  /**
+   * Normalize a string for fuzzy profile dedup: lowercase, strip punctuation, collapse whitespace.
+   */
+  static normalizeForDedup(s) {
+    if (typeof s !== "string") return "";
+    return s.toLowerCase().replace(/[^a-z0-9\s]/g, " ").replace(/\s+/g, " ").trim();
+  }
+  /**
+   * Check if a new bullet is a fuzzy duplicate of any existing bullet.
+   * Returns true if the new bullet should be skipped.
+   */
+  static isFuzzyDuplicate(newNorm, existingNorms) {
+    for (const existing of existingNorms) {
+      if (newNorm === existing) return true;
+      const shorter = newNorm.length <= existing.length ? newNorm : existing;
+      const longer = newNorm.length > existing.length ? newNorm : existing;
+      if (shorter.length > 20 && shorter.length / longer.length > 0.6 && longer.includes(shorter)) {
+        return true;
+      }
+    }
+    return false;
+  }
+  async appendToProfile(updates) {
+    updates = updates.filter((u) => typeof u === "string" && u.trim().length > 0);
+    if (updates.length === 0) return;
+    const existing = await this.readProfile();
+    const lines = existing ? existing.split("\n") : [];
+    const existingBulletRaw = lines.filter((l) => l.startsWith("- ")).map((l) => l.slice(2).trim());
+    const existingNorms = existingBulletRaw.map(_StorageManager.normalizeForDedup);
+    const newBullets = updates.filter((u) => {
+      const norm = _StorageManager.normalizeForDedup(u);
+      return !_StorageManager.isFuzzyDuplicate(norm, existingNorms);
+    });
+    if (newBullets.length === 0) return;
+    if (!existing) {
+      const content = [
+        "# Behavioral Profile",
+        "",
+        `*Last updated: ${(/* @__PURE__ */ new Date()).toISOString()}*`,
+        "",
+        ...newBullets.map((b) => `- ${b}`),
+        ""
+      ].join("\n");
+      await this.writeProfile(content);
+    } else {
+      const updatedTimestamp = existing.replace(
+        /\*Last updated:.*\*/,
+        `*Last updated: ${(/* @__PURE__ */ new Date()).toISOString()}*`
+      );
+      const withBullets = updatedTimestamp.trimEnd() + "\n" + newBullets.map((b) => `- ${b}`).join("\n") + "\n";
+      await this.writeProfile(withBullets);
+    }
+  }
+  /** Check if profile.md exceeds the max line cap and needs LLM consolidation */
+  async profileNeedsConsolidation(triggerLines) {
+    const profile = await this.readProfile();
+    if (!profile) return false;
+    const lineCount = profile.split("\n").length;
+    const threshold = typeof triggerLines === "number" ? Math.max(0, Math.floor(triggerLines)) : _StorageManager.PROFILE_MAX_LINES;
+    return lineCount > threshold;
+  }
+  async readAllMemories() {
+    const inFlight = _StorageManager.allMemoriesInFlight.get(this.baseDir);
+    if (inFlight) return inFlight;
+    const readPromise = this._readAllMemoriesFromDisk();
+    _StorageManager.allMemoriesInFlight.set(this.baseDir, readPromise);
+    try {
+      return await readPromise;
+    } finally {
+      if (_StorageManager.allMemoriesInFlight.get(this.baseDir) === readPromise) {
+        _StorageManager.allMemoriesInFlight.delete(this.baseDir);
+      }
+    }
+  }
+  /** Invalidate the readAllMemories() cache after writes that add/remove memories. */
+  /** Public cache invalidation for callers that need authoritative disk reads
+   *  (e.g. projection verify/rebuild). */
+  invalidateAllMemoriesCacheForDir() {
+    this.invalidateAllMemoriesCache();
+  }
+  /** Clear ALL static caches. Use in tests that write files directly
+   *  (bypassing StorageManager.writeMemory) to avoid stale reads. */
+  static clearAllStaticCaches() {
+    _StorageManager.allMemoriesInFlight.clear();
+    _StorageManager.questionsCache.clear();
+  }
+  /** Cancel any in-flight concurrent read so the next readAllMemories()
+   *  starts a fresh disk scan and sees the just-written data. */
+  invalidateAllMemoriesCache() {
+    _StorageManager.allMemoriesInFlight.delete(this.baseDir);
+  }
+  normalizeMemoryReadBatchSize(batchSize) {
+    if (typeof batchSize !== "number" || !Number.isFinite(batchSize)) {
+      return 50;
+    }
+    return Math.max(1, Math.floor(batchSize));
+  }
+  async collectActiveMemoryPaths() {
+    const filePaths = [];
+    const collectPaths = async (dir) => {
+      try {
+        const entries = await readdir(dir, { withFileTypes: true });
+        const subdirs = [];
+        for (const entry of entries) {
+          const fullPath = path.join(dir, entry.name);
+          if (entry.isDirectory()) {
+            subdirs.push(fullPath);
+          } else if (entry.name.endsWith(".md")) {
+            filePaths.push(fullPath);
+          }
+        }
+        for (const subdir of subdirs) {
+          await collectPaths(subdir);
+        }
+      } catch {
+      }
+    };
+    await collectPaths(this.factsDir);
+    await collectPaths(this.correctionsDir);
+    return filePaths;
+  }
+  async readParsedMemoriesFromPaths(filePaths, batchSize) {
+    if (filePaths.length === 0) return [];
+    const normalizedBatchSize = this.normalizeMemoryReadBatchSize(batchSize);
+    const memories = [];
+    for (let i = 0; i < filePaths.length; i += normalizedBatchSize) {
+      const batch = filePaths.slice(i, i + normalizedBatchSize);
+      const results = await Promise.all(
+        batch.map(async (fullPath) => {
+          try {
+            const raw = await readFile(fullPath, "utf-8");
+            const parsed = parseFrontmatter(raw);
+            if (!parsed) return null;
+            return {
+              path: fullPath,
+              frontmatter: normalizeFrontmatterForPath(
+                parsed.frontmatter,
+                toMemoryPathRel(this.baseDir, fullPath)
+              ),
+              content: parsed.content
+            };
+          } catch {
+            return null;
+          }
+        })
+      );
+      for (const memory of results) {
+        if (memory !== null) memories.push(memory);
+      }
+    }
+    return memories;
+  }
+  async readWindowUpdatedMs(filePath) {
+    try {
+      const raw = await readFile(filePath, "utf-8");
+      const match = raw.match(/^---\n([\s\S]*?)\n---\n?/);
+      if (!match) return null;
+      const frontmatterBlock = match[1];
+      const rawUpdated = frontmatterBlock.match(/^updated:\s*"?([^"\n]*)"?/m)?.[1] ?? frontmatterBlock.match(/^created:\s*"?([^"\n]*)"?/m)?.[1] ?? null;
+      const updatedMs = rawUpdated ? Date.parse(rawUpdated) : Number.NaN;
+      return Number.isFinite(updatedMs) ? updatedMs : null;
+    } catch {
+      return null;
+    }
+  }
+  async filterWindowPathsByUpdatedAfter(filePaths, updatedAfterMs) {
+    const results = await Promise.all(filePaths.map(async (filePath) => {
+      const updatedMs = await this.readWindowUpdatedMs(filePath);
+      if (updatedMs !== null) {
+        return updatedMs >= updatedAfterMs ? filePath : null;
+      }
+      try {
+        const fileStat = await stat(filePath);
+        return fileStat.mtimeMs >= updatedAfterMs ? filePath : null;
+      } catch {
+        return filePath;
+      }
+    }));
+    return results.filter((filePath) => filePath !== null);
+  }
+  orderWindowPaths(filePaths) {
+    const correctionPaths = [];
+    const factPaths = [];
+    for (const filePath of filePaths) {
+      if (filePath === this.correctionsDir || filePath.startsWith(`${this.correctionsDir}${path.sep}`)) {
+        correctionPaths.push(filePath);
+      } else {
+        factPaths.push(filePath);
+      }
+    }
+    correctionPaths.sort((left, right) => right.localeCompare(left));
+    factPaths.sort((left, right) => right.localeCompare(left));
+    if (correctionPaths.length === 0) return factPaths;
+    if (factPaths.length === 0) return correctionPaths;
+    const ordered = [];
+    const maxLength = Math.max(correctionPaths.length, factPaths.length);
+    for (let i = 0; i < maxLength; i += 1) {
+      const correctionPath = correctionPaths[i];
+      if (correctionPath) ordered.push(correctionPath);
+      const factPath = factPaths[i];
+      if (factPath) ordered.push(factPath);
+    }
+    return ordered;
+  }
+  async readWindowBoundedBatch(candidateBatchPaths, remainingSlots, remainingInspectionBudget, readBatchSize) {
+    const memories = [];
+    const filePaths = [];
+    const normalizedReadBatchSize = this.normalizeMemoryReadBatchSize(readBatchSize);
+    for (let index = 0; index < candidateBatchPaths.length; ) {
+      if (memories.length >= remainingSlots || filePaths.length >= remainingInspectionBudget) break;
+      const availableSlots = remainingSlots - memories.length;
+      const availableInspectionBudget = remainingInspectionBudget - filePaths.length;
+      const parallelWindow = availableSlots >= 4 && availableInspectionBudget >= 4 ? Math.min(normalizedReadBatchSize, 4) : 1;
+      const candidatePaths = candidateBatchPaths.slice(
+        index,
+        index + Math.min(parallelWindow, availableInspectionBudget)
+      );
+      index += candidatePaths.length;
+      if (candidatePaths.length === 0) break;
+      filePaths.push(...candidatePaths);
+      const parsedMemories = await this.readParsedMemoriesFromPaths(candidatePaths, candidatePaths.length);
+      if (parsedMemories.length === 0) continue;
+      memories.push(...parsedMemories.slice(0, availableSlots));
+    }
+    return { memories, filePaths };
+  }
+  async readMemoriesWindow(options = {}) {
+    const allPaths = await this.collectActiveMemoryPaths();
+    const sortedPaths = this.orderWindowPaths(allPaths);
+    const maxMemories = typeof options.maxMemories === "number" && Number.isFinite(options.maxMemories) ? Math.max(1, Math.floor(options.maxMemories)) : void 0;
+    const maxCandidatePaths = maxMemories === void 0 ? void 0 : maxMemories * 2;
+    const updatedAfterMs = options.updatedAfter?.getTime();
+    const normalizedBatchSize = this.normalizeMemoryReadBatchSize(options.batchSize);
+    const memories = [];
+    const selectedPaths = [];
+    for (let i = 0; i < sortedPaths.length; i += normalizedBatchSize) {
+      if (maxMemories !== void 0 && (memories.length >= maxMemories || maxCandidatePaths !== void 0 && selectedPaths.length >= maxCandidatePaths)) {
+        return { memories, filePaths: selectedPaths };
+      }
+      const batchPaths = sortedPaths.slice(i, i + normalizedBatchSize);
+      const candidateBatchPaths = updatedAfterMs === void 0 ? batchPaths : await this.filterWindowPathsByUpdatedAfter(batchPaths, updatedAfterMs);
+      const remainingSlots = maxMemories === void 0 ? void 0 : Math.max(0, maxMemories - memories.length);
+      const remainingInspectionBudget = maxCandidatePaths === void 0 ? void 0 : Math.max(0, maxCandidatePaths - selectedPaths.length);
+      const { memories: batchMemories, filePaths: parsedCandidatePaths } = remainingSlots === void 0 ? {
+        memories: await this.readParsedMemoriesFromPaths(candidateBatchPaths, normalizedBatchSize),
+        filePaths: candidateBatchPaths
+      } : await this.readWindowBoundedBatch(
+        candidateBatchPaths,
+        remainingSlots,
+        remainingInspectionBudget ?? remainingSlots,
+        normalizedBatchSize
+      );
+      selectedPaths.push(...parsedCandidatePaths);
+      for (const memory of batchMemories) {
+        memories.push(memory);
+        if (maxMemories !== void 0 && memories.length >= maxMemories) {
+          return { memories, filePaths: selectedPaths };
+        }
+      }
+    }
+    return { memories, filePaths: selectedPaths };
+  }
+  async _readAllMemoriesFromDisk() {
+    const filePaths = await this.collectActiveMemoryPaths();
+    return this.readParsedMemoriesFromPaths(filePaths, 50);
+  }
+  /**
+   * Read archived memory markdown files under archive/.
+   * Used by long-term recall fallback when hot recall has no hits.
+   */
+  async readArchivedMemories() {
+    const memories = [];
+    const root = this.archiveDir;
+    const readDir = async (dir) => {
+      try {
+        const entries = await readdir(dir, { withFileTypes: true });
+        for (const entry of entries) {
+          const fullPath = path.join(dir, entry.name);
+          if (entry.isDirectory()) {
+            await readDir(fullPath);
+          } else if (entry.name.endsWith(".md")) {
+            try {
+              const raw = await readFile(fullPath, "utf-8");
+              const parsed = parseFrontmatter(raw);
+              if (parsed) {
+                memories.push({
+                  path: fullPath,
+                  frontmatter: normalizeFrontmatterForPath(
+                    parsed.frontmatter,
+                    toMemoryPathRel(this.baseDir, fullPath)
+                  ),
+                  content: parsed.content
+                });
+              }
+            } catch {
+            }
+          }
+        }
+      } catch {
+      }
+    };
+    await readDir(root);
+    return memories;
+  }
+  /** Read a single memory file by its absolute path. Returns null if unreadable. */
+  async readMemoryByPath(filePath) {
+    try {
+      const raw = await readFile(filePath, "utf-8");
+      const parsed = parseFrontmatter(raw);
+      if (parsed) {
+        return {
+          path: filePath,
+          frontmatter: normalizeFrontmatterForPath(
+            parsed.frontmatter,
+            toMemoryPathRel(this.baseDir, filePath)
+          ),
+          content: parsed.content
+        };
+      }
+      const normalizedPath = filePath.split(path.sep).join("/");
+      if (normalizedPath.includes("/entities/") && filePath.endsWith(".md")) {
+        const entity = parseEntityFile(raw);
+        if (!entity.name) return null;
+        const nameWithoutExt = path.basename(filePath, ".md");
+        const fileMtime = entity.updated || await stat(filePath).then((s) => s.mtime.toISOString()).catch(() => (/* @__PURE__ */ new Date(0)).toISOString());
+        return {
+          path: filePath,
+          frontmatter: {
+            id: nameWithoutExt,
+            category: "entity",
+            created: fileMtime,
+            updated: fileMtime,
+            source: "entity_extraction",
+            confidence: 0.9,
+            confidenceTier: confidenceTier(0.9),
+            tags: entity.type ? [entity.type] : []
+          },
+          content: raw
+        };
+      }
+      return null;
+    } catch {
+      return null;
+    }
+  }
+  resolveTierRootDir(tier) {
+    return tier === "cold" ? path.join(this.baseDir, "cold") : this.baseDir;
+  }
+  resolveMemoryDateDir(memory) {
+    const preferred = memory.frontmatter.created || memory.frontmatter.updated;
+    const dateToken = (preferred ?? "").slice(0, 10);
+    return /^\d{4}-\d{2}-\d{2}$/.test(dateToken) ? dateToken : (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+  }
+  isArtifactMemory(memory) {
+    if (memory.frontmatter.source === "artifact") return true;
+    if (memory.frontmatter.artifactType !== void 0) return true;
+    return /[\\/]artifacts[\\/]/.test(memory.path);
+  }
+  buildTierMemoryPath(memory, tier) {
+    const root = this.resolveTierRootDir(tier);
+    if (this.isArtifactMemory(memory)) {
+      return path.join(root, "artifacts", this.resolveMemoryDateDir(memory), `${memory.frontmatter.id}.md`);
+    }
+    if (memory.frontmatter.category === "correction") {
+      return path.join(root, "corrections", `${memory.frontmatter.id}.md`);
+    }
+    return path.join(root, "facts", this.resolveMemoryDateDir(memory), `${memory.frontmatter.id}.md`);
+  }
+  async writeMemoryFileAtomic(targetPath, memory) {
+    const fileContent = `${serializeFrontmatter(memory.frontmatter)}
+
+${memory.content}
+`;
+    await mkdir(path.dirname(targetPath), { recursive: true });
+    const tempPath = `${targetPath}.tmp-${process.pid}-${Date.now()}`;
+    try {
+      await writeFile(tempPath, fileContent, "utf-8");
+      await rename(tempPath, targetPath);
+      this.invalidateAllMemoriesCache();
+    } catch (err) {
+      try {
+        await unlink(tempPath);
+      } catch {
+      }
+      throw err;
+    }
+  }
+  async moveMemoryToPath(memory, targetPath) {
+    await this.writeMemoryFileAtomic(targetPath, memory);
+    const sourcePath = path.resolve(memory.path);
+    const destPath = path.resolve(targetPath);
+    if (sourcePath !== destPath) {
+      try {
+        await unlink(memory.path);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (!message.includes("ENOENT")) {
+          throw err;
+        }
+      }
+      this.invalidateAllMemoriesCache();
+    }
+  }
+  async migrateMemoryToTier(memory, targetTier) {
+    const targetPath = this.buildTierMemoryPath(memory, targetTier);
+    const sourcePath = path.resolve(memory.path);
+    const destPath = path.resolve(targetPath);
+    if (sourcePath === destPath) {
+      return { changed: false, targetPath };
+    }
+    const existing = await this.readMemoryByPath(targetPath);
+    if (existing?.frontmatter.id === memory.frontmatter.id) {
+      try {
+        await unlink(memory.path);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (!message.includes("ENOENT")) {
+          throw err;
+        }
+      }
+      this.bumpMemoryStatusVersion();
+      return { changed: false, targetPath };
+    }
+    await this.moveMemoryToPath(memory, targetPath);
+    this.invalidateAllMemoriesCache();
+    this.bumpMemoryStatusVersion();
+    return { changed: true, targetPath };
+  }
+  get archiveDir() {
+    return path.join(this.baseDir, "archive");
+  }
+  /**
+   * Archive a memory by moving it from facts/ to archive/YYYY-MM-DD/.
+   * Updates frontmatter with archived status before moving.
+   * Returns the new file path on success, null on failure.
+   */
+  async archiveMemory(memory, lifecycle) {
+    try {
+      const now = lifecycle?.at ?? /* @__PURE__ */ new Date();
+      const today = now.toISOString().slice(0, 10);
+      const destDir = path.join(this.archiveDir, today);
+      await mkdir(destDir, { recursive: true });
+      const updatedFm = {
+        ...memory.frontmatter,
+        status: "archived",
+        archivedAt: now.toISOString(),
+        updated: now.toISOString()
+      };
+      const fileContent = `${serializeFrontmatter(updatedFm)}
+
+${memory.content}
+`;
+      const destPath = path.join(destDir, path.basename(memory.path));
+      await writeFile(destPath, fileContent, "utf-8");
+      await unlink(memory.path);
+      this.invalidateAllMemoriesCache();
+      await this.appendGeneratedMemoryLifecycleEventFailOpen(
+        "storage.archiveMemory",
+        {
+          memoryId: memory.frontmatter.id,
+          eventType: "archived",
+          timestamp: updatedFm.archivedAt ?? updatedFm.updated,
+          actor: lifecycle?.actor ?? "storage.archiveMemory",
+          reasonCode: lifecycle?.reasonCode,
+          before: this.summarizeLifecycleState(memory.frontmatter, memory.path),
+          after: this.summarizeLifecycleState(updatedFm, destPath),
+          relatedMemoryIds: lifecycle?.relatedMemoryIds,
+          correlationId: lifecycle?.correlationId
+        },
+        lifecycle?.ruleVersion
+      );
+      this.bumpMemoryStatusVersion();
+      log.debug(`archived memory ${memory.frontmatter.id} \u2192 ${destPath}`);
+      return destPath;
+    } catch (err) {
+      log.warn(`failed to archive memory ${memory.frontmatter.id}: ${err}`);
+      return null;
+    }
+  }
+  async readEntities() {
+    try {
+      const entries = await readdir(this.entitiesDir);
+      return entries.filter((e) => e.endsWith(".md")).map((e) => e.replace(".md", ""));
+    } catch {
+      return [];
+    }
+  }
+  async readEntity(name) {
+    try {
+      return await readFile(path.join(this.entitiesDir, `${name}.md`), "utf-8");
+    } catch {
+      return "";
+    }
+  }
+  /** Return sorted list of entity filenames (without .md extension) */
+  async listEntityNames() {
+    try {
+      const entries = await readdir(this.entitiesDir);
+      return entries.filter((e) => e.endsWith(".md")).map((e) => e.replace(".md", "")).sort();
+    } catch {
+      return [];
+    }
+  }
+  /**
+   * Find an existing entity that fuzzy-matches the proposed name.
+   * Returns the existing entity filename (without .md) or null if no match.
+   *
+   * Matching priority:
+   * 1. Exact normalized match (handled by normalizeEntityName already)
+   * 2. Dehyphenated match: "jane-doe" vs "janedoe"
+   * 3. Substring containment: "handle-janedoe" contains "janedoe"
+   * 4. Levenshtein ≤ 2 on dehyphenated names
+   */
+  async findMatchingEntity(proposedName, type) {
+    const existing = await this.listEntityNames();
+    if (existing.length === 0) return null;
+    const typePrefix = `${type.toLowerCase()}-`;
+    const proposedFull = normalizeEntityName(proposedName, type);
+    const proposedNamePart = proposedFull.startsWith(typePrefix) ? proposedFull.slice(typePrefix.length) : proposedFull;
+    const proposedDehyph = dehyphenate(proposedNamePart);
+    const sameType = existing.filter((e) => e.startsWith(typePrefix));
+    for (const entity of sameType) {
+      const entityNamePart = entity.slice(typePrefix.length);
+      const entityDehyph = dehyphenate(entityNamePart);
+      if (entity === proposedFull) return entity;
+      if (entityDehyph === proposedDehyph) return entity;
+      const shorter = proposedDehyph.length <= entityDehyph.length ? proposedDehyph : entityDehyph;
+      const longer = proposedDehyph.length > entityDehyph.length ? proposedDehyph : entityDehyph;
+      if (shorter.length > 3 && shorter.length / longer.length > 0.6 && longer.includes(shorter)) {
+        return entity;
+      }
+      if (proposedDehyph.length >= 4 && entityDehyph.length >= 4) {
+        const dist = levenshtein(proposedDehyph, entityDehyph);
+        if (dist <= 2) return entity;
+      }
+    }
+    return null;
+  }
+  async invalidateMemory(id) {
+    const memories = await this.readAllMemories();
+    const memory = memories.find((m) => m.frontmatter.id === id);
+    if (!memory) return false;
+    try {
+      await unlink(memory.path);
+      this.invalidateAllMemoriesCache();
+      this.bumpMemoryStatusVersion();
+      log.debug(`invalidated memory ${id}`);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  async updateMemory(id, newContent, options) {
+    const memories = await this.readAllMemories();
+    const memory = memories.find((m) => m.frontmatter.id === id);
+    if (!memory) return false;
+    const mergedLineage = [
+      ...memory.frontmatter.lineage ?? [],
+      ...options?.lineage ?? []
+    ].filter((v, i, a) => a.indexOf(v) === i);
+    const updated = {
+      ...memory.frontmatter,
+      updated: (/* @__PURE__ */ new Date()).toISOString(),
+      supersedes: options?.supersedes ?? memory.frontmatter.supersedes,
+      lineage: mergedLineage.length > 0 ? mergedLineage : void 0
+    };
+    const sanitized = sanitizeMemoryContent(newContent);
+    if (!sanitized.clean) {
+      log.warn(`updated memory content sanitized for ${id}; violations=${sanitized.violations.join(", ")}`);
+    }
+    const fileContent = `${serializeFrontmatter(updated)}
+
+${sanitized.text}
+`;
+    await writeFile(memory.path, fileContent, "utf-8");
+    this.invalidateAllMemoriesCache();
+    await this.appendGeneratedMemoryLifecycleEventFailOpen("storage.updateMemory", {
+      memoryId: id,
+      eventType: "updated",
+      timestamp: updated.updated,
+      actor: options?.actor ?? "storage.updateMemory",
+      before: this.summarizeLifecycleState(memory.frontmatter, memory.path),
+      after: this.summarizeLifecycleState(updated, memory.path),
+      relatedMemoryIds: [
+        ...updated.supersedes ? [updated.supersedes] : [],
+        ...(updated.lineage ?? []).filter(Boolean)
+      ]
+    });
+    log.debug(`updated memory ${id}`);
+    return true;
+  }
+  /**
+   * Update frontmatter fields without changing memory content.
+   * Returns false when the memory is not found.
+   */
+  async writeMemoryFrontmatter(memory, patch, lifecycle) {
+    const beforeStatus = memory.frontmatter.status ?? "active";
+    const updated = {
+      ...memory.frontmatter,
+      ...patch
+    };
+    const afterStatus = updated.status ?? "active";
+    const fileContent = `${serializeFrontmatter(updated)}
+
+${memory.content}
+`;
+    await writeFile(memory.path, fileContent, "utf-8");
+    this.invalidateAllMemoriesCache();
+    await this.appendGeneratedMemoryLifecycleEventFailOpen(
+      "storage.writeMemoryFrontmatter",
+      {
+        memoryId: updated.id,
+        eventType: this.frontmatterPatchEventType(memory.frontmatter, updated),
+        timestamp: updated.updated ?? (/* @__PURE__ */ new Date()).toISOString(),
+        actor: lifecycle?.actor ?? "storage.writeMemoryFrontmatter",
+        reasonCode: lifecycle?.reasonCode,
+        before: this.summarizeLifecycleState(memory.frontmatter, memory.path),
+        after: this.summarizeLifecycleState(updated, memory.path),
+        relatedMemoryIds: [
+          ...lifecycle?.relatedMemoryIds ?? [],
+          ...updated.supersededBy ? [updated.supersededBy] : [],
+          ...updated.supersedes ? [updated.supersedes] : []
+        ],
+        correlationId: lifecycle?.correlationId
+      },
+      lifecycle?.ruleVersion
+    );
+    if (beforeStatus !== afterStatus) {
+      this.bumpMemoryStatusVersion();
+    }
+    return true;
+  }
+  /**
+   * Update frontmatter by memory ID.
+   * Prefer writeMemoryFrontmatter(memory, patch) in batch loops to avoid full-corpus rescans.
+   */
+  async updateMemoryFrontmatter(id, patch) {
+    const memories = await this.readAllMemories();
+    const memory = memories.find((m) => m.frontmatter.id === id);
+    if (!memory) return false;
+    return this.writeMemoryFrontmatter(memory, patch);
+  }
+  /** Remove memories past their TTL expiresAt date */
+  async cleanExpiredTTL() {
+    const memories = await this.readAllMemories();
+    const now = Date.now();
+    const deleted = [];
+    for (const m of memories) {
+      if (!m.frontmatter.expiresAt) continue;
+      const expiresAt = new Date(m.frontmatter.expiresAt).getTime();
+      if (expiresAt < now) {
+        try {
+          await unlink(m.path);
+          deleted.push(m);
+          log.debug(`cleaned expired memory ${m.frontmatter.id} (TTL expired)`);
+        } catch {
+        }
+      }
+    }
+    if (deleted.length > 0) {
+      this.invalidateAllMemoriesCache();
+      this.bumpMemoryStatusVersion();
+    }
+    return deleted;
+  }
+  async loadBuffer() {
+    const bufferPath = path.join(this.stateDir, "buffer.json");
+    try {
+      const raw = await readFile(bufferPath, "utf-8");
+      return JSON.parse(raw);
+    } catch {
+      return { turns: [], lastExtractionAt: null, extractionCount: 0 };
+    }
+  }
+  async saveBuffer(state) {
+    await this.ensureDirectories();
+    const bufferPath = path.join(this.stateDir, "buffer.json");
+    await writeFile(bufferPath, JSON.stringify(state, null, 2), "utf-8");
+  }
+  async loadMeta() {
+    const metaPath = path.join(this.stateDir, "meta.json");
+    try {
+      const raw = await readFile(metaPath, "utf-8");
+      return JSON.parse(raw);
+    } catch {
+      return {
+        extractionCount: 0,
+        lastExtractionAt: null,
+        lastConsolidationAt: null,
+        totalMemories: 0,
+        totalEntities: 0
+      };
+    }
+  }
+  async saveMeta(state) {
+    await this.ensureDirectories();
+    const metaPath = path.join(this.stateDir, "meta.json");
+    await writeFile(metaPath, JSON.stringify(state, null, 2), "utf-8");
+  }
+  async appendMemoryActionEvents(events) {
+    if (events.length === 0) return 0;
+    await this.ensureDirectories();
+    const nowIso = (/* @__PURE__ */ new Date()).toISOString();
+    const payload = events.map((event) => {
+      const normalized = {
+        ...event,
+        timestamp: event.timestamp && event.timestamp.length > 0 ? event.timestamp : nowIso
+      };
+      return `${JSON.stringify(normalized)}
+`;
+    }).join("");
+    await appendFile(this.memoryActionsPath, payload, "utf-8");
+    return events.length;
+  }
+  async appendMemoryLifecycleEvents(events) {
+    if (events.length === 0) return 0;
+    await this.ensureDirectories();
+    const nowIso = (/* @__PURE__ */ new Date()).toISOString();
+    const payload = events.map((event) => {
+      const normalized = {
+        ...event,
+        timestamp: event.timestamp && event.timestamp.length > 0 ? event.timestamp : nowIso
+      };
+      return `${JSON.stringify(normalized)}
+`;
+    }).join("");
+    await appendFile(this.memoryLifecycleLedgerPath, payload, "utf-8");
+    return events.length;
+  }
+  async appendBehaviorSignals(events) {
+    if (events.length === 0) return 0;
+    await this.ensureDirectories();
+    let existingKeys = /* @__PURE__ */ new Set();
+    try {
+      const raw = await readFile(this.behaviorSignalsPath, "utf-8");
+      const lines = raw.split("\n");
+      for (const line of lines) {
+        const row = line.trim();
+        if (!row) continue;
+        try {
+          const parsed = JSON.parse(row);
+          if (typeof parsed.memoryId === "string" && typeof parsed.signalHash === "string") {
+            existingKeys.add(`${parsed.memoryId}:${parsed.signalHash}`);
+          }
+        } catch {
+        }
+      }
+    } catch {
+      existingKeys = /* @__PURE__ */ new Set();
+    }
+    const nowIso = (/* @__PURE__ */ new Date()).toISOString();
+    const deduped = [];
+    for (const event of events) {
+      const key = `${event.memoryId}:${event.signalHash}`;
+      if (existingKeys.has(key)) continue;
+      existingKeys.add(key);
+      deduped.push({
+        ...event,
+        timestamp: event.timestamp && event.timestamp.length > 0 ? event.timestamp : nowIso
+      });
+    }
+    if (deduped.length === 0) return 0;
+    const payload = deduped.map((event) => `${JSON.stringify(event)}
+`).join("");
+    await appendFile(this.behaviorSignalsPath, payload, "utf-8");
+    return deduped.length;
+  }
+  async appendReextractJobs(events) {
+    if (events.length === 0) return 0;
+    await this.ensureDirectories();
+    const filePath = path.join(this.stateDir, "reextract-jobs.jsonl");
+    const lines = events.map((event) => JSON.stringify(event)).join("\n") + "\n";
+    try {
+      await appendFile(filePath, lines, "utf-8");
+      return events.length;
+    } catch {
+      return 0;
+    }
+  }
+  async readReextractJobs(limit = 200) {
+    const safeLimit = Number.isFinite(limit) ? Math.max(1, Math.min(1e3, Math.floor(limit))) : 200;
+    const filePath = path.join(this.stateDir, "reextract-jobs.jsonl");
+    try {
+      const raw = await readFile(filePath, "utf-8");
+      const lines = raw.split("\n").filter((line) => line.trim().length > 0);
+      const parsed = [];
+      for (const line of lines) {
+        try {
+          const record = JSON.parse(line);
+          if (typeof record.memoryId !== "string" || record.memoryId.length === 0 || typeof record.model !== "string" || record.model.length === 0 || typeof record.requestedAt !== "string" || record.requestedAt.length === 0 || record.source !== "cli-migrate") {
+            continue;
+          }
+          parsed.push({
+            memoryId: record.memoryId,
+            model: record.model,
+            requestedAt: record.requestedAt,
+            source: "cli-migrate"
+          });
+        } catch {
+          continue;
+        }
+      }
+      return parsed.slice(-safeLimit);
+    } catch {
+      return [];
+    }
+  }
+  async readBehaviorSignals(limit = 200) {
+    const cappedLimit = Math.max(0, Math.floor(limit));
+    if (cappedLimit === 0) return [];
+    try {
+      const raw = await readFile(this.behaviorSignalsPath, "utf-8");
+      const out = [];
+      const lines = raw.split("\n");
+      for (let i = lines.length - 1; i >= 0 && out.length < cappedLimit; i -= 1) {
+        const row = lines[i]?.trim();
+        if (!row) continue;
+        try {
+          const parsed = JSON.parse(row);
+          if (typeof parsed.timestamp === "string" && typeof parsed.namespace === "string" && typeof parsed.memoryId === "string" && typeof parsed.category === "string" && typeof parsed.signalType === "string" && typeof parsed.direction === "string" && typeof parsed.confidence === "number" && typeof parsed.signalHash === "string" && typeof parsed.source === "string") {
+            out.push(parsed);
+          }
+        } catch {
+        }
+      }
+      return out.reverse();
+    } catch {
+      return [];
+    }
+  }
+  async readMemoryActionEvents(limit = 200) {
+    const cappedLimit = Math.max(0, Math.floor(limit));
+    if (cappedLimit === 0) return [];
+    try {
+      const raw = await readFile(this.memoryActionsPath, "utf-8");
+      const out = [];
+      const lines = raw.split("\n");
+      for (let i = lines.length - 1; i >= 0 && out.length < cappedLimit; i -= 1) {
+        const line = lines[i]?.trim();
+        if (!line) continue;
+        try {
+          const parsed = JSON.parse(line);
+          if (typeof parsed.timestamp === "string" && typeof parsed.action === "string" && typeof parsed.outcome === "string") {
+            out.push(parsed);
+          }
+        } catch {
+        }
+      }
+      return out.reverse();
+    } catch {
+      return [];
+    }
+  }
+  async readAllMemoryLifecycleEvents() {
+    try {
+      const raw = await readFile(this.memoryLifecycleLedgerPath, "utf-8");
+      const out = [];
+      const lines = raw.split("\n");
+      for (const line of lines) {
+        const row = line.trim();
+        if (!row) continue;
+        try {
+          const parsed = JSON.parse(row);
+          if (typeof parsed.eventId === "string" && typeof parsed.memoryId === "string" && typeof parsed.eventType === "string" && typeof parsed.timestamp === "string" && typeof parsed.actor === "string" && typeof parsed.ruleVersion === "string") {
+            out.push(parsed);
+          }
+        } catch {
+        }
+      }
+      return sortMemoryLifecycleEvents(out);
+    } catch {
+      return [];
+    }
+  }
+  async readMemoryLifecycleEvents(limit = 200) {
+    const cappedLimit = Math.max(0, Math.floor(limit));
+    if (cappedLimit === 0) return [];
+    const events = await this.readAllMemoryLifecycleEvents();
+    return events.slice(-cappedLimit);
+  }
+  async writeCompressionGuidelines(content) {
+    await this.ensureDirectories();
+    await writeFile(this.compressionGuidelinesPath, content, "utf-8");
+  }
+  async readCompressionGuidelines() {
+    try {
+      return await readFile(this.compressionGuidelinesPath, "utf-8");
+    } catch {
+      return null;
+    }
+  }
+  async writeCompressionGuidelineDraft(content) {
+    await this.ensureDirectories();
+    await writeFile(this.compressionGuidelineDraftPath, content, "utf-8");
+  }
+  async readCompressionGuidelineDraft() {
+    try {
+      return await readFile(this.compressionGuidelineDraftPath, "utf-8");
+    } catch {
+      return null;
+    }
+  }
+  async writeCompressionGuidelineOptimizerState(state) {
+    await this.ensureDirectories();
+    await writeFile(this.compressionGuidelineStatePath, `${JSON.stringify(state, null, 2)}
+`, "utf-8");
+  }
+  async writeCompressionGuidelineDraftState(state) {
+    await this.ensureDirectories();
+    await writeFile(this.compressionGuidelineDraftStatePath, `${JSON.stringify(state, null, 2)}
+`, "utf-8");
+  }
+  async readCompressionGuidelineOptimizerState() {
+    return this.readCompressionGuidelineStateFile(this.compressionGuidelineStatePath);
+  }
+  async readCompressionGuidelineDraftState() {
+    return this.readCompressionGuidelineStateFile(this.compressionGuidelineDraftStatePath);
+  }
+  async activateCompressionGuidelineDraft(options) {
+    const [draftContent, draftState] = await Promise.all([
+      this.readCompressionGuidelineDraft(),
+      this.readCompressionGuidelineDraftState()
+    ]);
+    if (!draftContent || !draftState) return false;
+    if (typeof options?.expectedContentHash === "string" && options.expectedContentHash.length > 0 && draftState.contentHash !== options.expectedContentHash) {
+      return false;
+    }
+    if (typeof options?.expectedGuidelineVersion === "number" && Number.isFinite(options.expectedGuidelineVersion) && draftState.guidelineVersion !== options.expectedGuidelineVersion) {
+      return false;
+    }
+    if (draftState.contentHash) {
+      const contentHash = createHash("sha256").update(draftContent).digest("hex");
+      if (contentHash !== draftState.contentHash) return false;
+    }
+    await this.writeCompressionGuidelines(draftContent);
+    await this.writeCompressionGuidelineOptimizerState({
+      ...draftState,
+      activationState: "active"
+    });
+    await Promise.all([
+      unlink(this.compressionGuidelineDraftPath).catch(() => void 0),
+      unlink(this.compressionGuidelineDraftStatePath).catch(() => void 0)
+    ]);
+    return true;
+  }
+  async readCompressionGuidelineStateFile(filePath) {
+    const isFiniteNonNegativeInteger = (value) => typeof value === "number" && Number.isFinite(value) && Number.isInteger(value) && value >= 0;
+    const isValidActionSummary = (value) => {
+      if (!value || typeof value !== "object") return false;
+      const summary = value;
+      return typeof summary.action === "string" && isFiniteNonNegativeInteger(summary.total) && summary.outcomes !== null && typeof summary.outcomes === "object" && isFiniteNonNegativeInteger(summary.outcomes.applied) && isFiniteNonNegativeInteger(summary.outcomes.skipped) && isFiniteNonNegativeInteger(summary.outcomes.failed) && summary.quality !== null && typeof summary.quality === "object" && isFiniteNonNegativeInteger(summary.quality.good) && isFiniteNonNegativeInteger(summary.quality.poor) && isFiniteNonNegativeInteger(summary.quality.unknown);
+    };
+    const isValidRuleUpdate = (value) => {
+      if (!value || typeof value !== "object") return false;
+      const rule = value;
+      return typeof rule.action === "string" && typeof rule.delta === "number" && Number.isFinite(rule.delta) && (rule.direction === "increase" || rule.direction === "decrease" || rule.direction === "hold") && (rule.confidence === "low" || rule.confidence === "medium" || rule.confidence === "high") && Array.isArray(rule.notes) && rule.notes.every((note) => typeof note === "string");
+    };
+    try {
+      const raw = await readFile(filePath, "utf-8");
+      const parsed = JSON.parse(raw);
+      const sourceWindow = parsed?.sourceWindow;
+      const eventCounts = parsed?.eventCounts;
+      const activationState = parsed?.activationState === "draft" || parsed?.activationState === "active" ? parsed.activationState : void 0;
+      const contentHash = typeof parsed?.contentHash === "string" && parsed.contentHash.length > 0 ? parsed.contentHash : void 0;
+      const actionSummaries = Array.isArray(parsed?.actionSummaries) ? parsed.actionSummaries.filter(isValidActionSummary) : void 0;
+      const ruleUpdates = Array.isArray(parsed?.ruleUpdates) ? parsed.ruleUpdates.filter(isValidRuleUpdate) : void 0;
+      if (!isFiniteNonNegativeInteger(parsed?.version) || typeof parsed?.updatedAt !== "string" || parsed.updatedAt.length === 0 || !sourceWindow || typeof sourceWindow.from !== "string" || sourceWindow.from.length === 0 || typeof sourceWindow.to !== "string" || sourceWindow.to.length === 0 || !eventCounts || !isFiniteNonNegativeInteger(eventCounts.total) || !isFiniteNonNegativeInteger(eventCounts.applied) || !isFiniteNonNegativeInteger(eventCounts.skipped) || !isFiniteNonNegativeInteger(eventCounts.failed) || !isFiniteNonNegativeInteger(parsed?.guidelineVersion)) {
+        return null;
+      }
+      return {
+        version: parsed.version,
+        updatedAt: parsed.updatedAt,
+        sourceWindow: {
+          from: sourceWindow.from,
+          to: sourceWindow.to
+        },
+        eventCounts: {
+          total: eventCounts.total,
+          applied: eventCounts.applied,
+          skipped: eventCounts.skipped,
+          failed: eventCounts.failed
+        },
+        guidelineVersion: parsed.guidelineVersion,
+        ...contentHash ? { contentHash } : {},
+        ...activationState ? { activationState } : {},
+        ...actionSummaries ? { actionSummaries } : {},
+        ...ruleUpdates ? { ruleUpdates } : {}
+      };
+    } catch {
+      return null;
+    }
+  }
+  async writeIdentityAnchor(content) {
+    await this.ensureDirectories();
+    await writeFile(this.identityAnchorPath, content, "utf-8");
+  }
+  async readIdentityAnchor() {
+    try {
+      return await readFile(this.identityAnchorPath, "utf-8");
+    } catch {
+      return null;
+    }
+  }
+  async appendContinuityIncident(input) {
+    await this.ensureDirectories();
+    const now = /* @__PURE__ */ new Date();
+    const nowIso = now.toISOString();
+    const date = nowIso.slice(0, 10);
+    const id = this.generateId("incident");
+    const incident = createContinuityIncidentRecord(id, input, nowIso);
+    const filePath = path.join(this.identityIncidentsDir, `${date}-${id}.md`);
+    await writeFile(filePath, serializeContinuityIncident(incident), "utf-8");
+    return { ...incident, filePath };
+  }
+  async readContinuityIncidents(limit = 200, state = "all") {
+    const normalizedLimit = Number.isFinite(limit) ? Math.floor(limit) : 0;
+    const cappedLimit = Math.max(0, normalizedLimit);
+    if (cappedLimit === 0) return [];
+    try {
+      const candidates = await this.readContinuityIncidentFileNames();
+      const incidents = [];
+      for (const file of candidates) {
+        if (incidents.length >= cappedLimit) break;
+        const filePath = path.join(this.identityIncidentsDir, file);
+        try {
+          const raw = await readFile(filePath, "utf-8");
+          const parsed = parseContinuityIncident(raw);
+          if (!parsed) continue;
+          if (state !== "all" && parsed.state !== state) continue;
+          incidents.push({ ...parsed, filePath });
+        } catch {
+        }
+      }
+      return incidents;
+    } catch {
+      return [];
+    }
+  }
+  async closeContinuityIncident(id, closure) {
+    const directFilePath = await this.findContinuityIncidentFilePathById(id);
+    const target = directFilePath ? await this.readContinuityIncidentFile(directFilePath) : null;
+    if (!target || !directFilePath) return null;
+    if (target.state === "closed") return target;
+    const closed = closeContinuityIncidentRecord(target, closure, (/* @__PURE__ */ new Date()).toISOString());
+    await writeFile(directFilePath, serializeContinuityIncident(closed), "utf-8");
+    return { ...closed, filePath: directFilePath };
+  }
+  async writeIdentityAudit(period, key, content) {
+    await this.ensureDirectories();
+    const safeKey = this.sanitizeIdentityAuditKey(key);
+    const dir = period === "weekly" ? this.identityAuditsWeeklyDir : this.identityAuditsMonthlyDir;
+    const filePath = path.join(dir, `${safeKey}.md`);
+    await writeFile(filePath, content, "utf-8");
+    return filePath;
+  }
+  async readIdentityAudit(period, key) {
+    try {
+      const safeKey = this.sanitizeIdentityAuditKey(key);
+      const dir = period === "weekly" ? this.identityAuditsWeeklyDir : this.identityAuditsMonthlyDir;
+      return await readFile(path.join(dir, `${safeKey}.md`), "utf-8");
+    } catch {
+      return null;
+    }
+  }
+  async writeIdentityImprovementLoops(content) {
+    await this.ensureDirectories();
+    await writeFile(this.identityImprovementLoopsPath, content, "utf-8");
+  }
+  async readIdentityImprovementLoops() {
+    try {
+      return await readFile(this.identityImprovementLoopsPath, "utf-8");
+    } catch {
+      return null;
+    }
+  }
+  async readIdentityImprovementLoopRegister() {
+    const raw = await this.readIdentityImprovementLoops();
+    if (!raw) return [];
+    return parseContinuityImprovementLoops(raw);
+  }
+  async upsertIdentityImprovementLoop(input) {
+    const nowIso = (/* @__PURE__ */ new Date()).toISOString();
+    const raw = await this.readIdentityImprovementLoops();
+    const { markdown, loop } = upsertContinuityLoopInMarkdown(raw, input, nowIso);
+    await this.writeIdentityImprovementLoops(markdown);
+    return loop;
+  }
+  async reviewIdentityImprovementLoop(id, input) {
+    const raw = await this.readIdentityImprovementLoops();
+    const { markdown, loop } = reviewContinuityLoopInMarkdown(raw, id, input, (/* @__PURE__ */ new Date()).toISOString());
+    if (!loop) return null;
+    await this.writeIdentityImprovementLoops(markdown);
+    return loop;
+  }
+  // ---------------------------------------------------------------------------
+  // Question storage
+  // ---------------------------------------------------------------------------
+  generateId(prefix = "m") {
+    const ts = Date.now().toString(36);
+    const rand = Math.random().toString(36).slice(2, 4);
+    return `${prefix}-${ts}-${rand}`;
+  }
+  async readContinuityIncidentFileNames() {
+    const files = await readdir(this.identityIncidentsDir);
+    return files.filter((file) => file.endsWith(".md")).sort().reverse();
+  }
+  async readContinuityIncidentFile(filePath) {
+    try {
+      const raw = await readFile(filePath, "utf-8");
+      const parsed = parseContinuityIncident(raw);
+      return parsed ? { ...parsed, filePath } : null;
+    } catch {
+      return null;
+    }
+  }
+  async findContinuityIncidentFilePathById(id) {
+    const fileNames = await this.readContinuityIncidentFileNames();
+    const directMatch = fileNames.find((name) => name.endsWith(`-${id}.md`));
+    if (directMatch) {
+      const directPath = path.join(this.identityIncidentsDir, directMatch);
+      const parsed = await this.readContinuityIncidentFile(directPath);
+      if (parsed?.id === id) return directPath;
+    }
+    for (const fileName of fileNames) {
+      const filePath = path.join(this.identityIncidentsDir, fileName);
+      const parsed = await this.readContinuityIncidentFile(filePath);
+      if (parsed?.id === id) return filePath;
+    }
+    return null;
+  }
+  sanitizeIdentityAuditKey(key) {
+    const trimmed = key.trim();
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(trimmed) || trimmed.includes("..")) {
+      throw new Error("Invalid identity audit key");
+    }
+    return trimmed;
+  }
+  async writeQuestion(question, context, priority) {
+    await mkdir(this.questionsDir, { recursive: true });
+    const id = this.generateId("q");
+    const frontmatter = {
+      id,
+      created: (/* @__PURE__ */ new Date()).toISOString(),
+      priority,
+      resolved: false
+    };
+    const content = `---
+${Object.entries(frontmatter).map(([k, v]) => `${k}: ${JSON.stringify(v)}`).join("\n")}
+---
+
+${question}
+
+**Context:** ${context}
+`;
+    const filePath = path.join(this.questionsDir, `${id}.md`);
+    await writeFile(filePath, content, "utf-8");
+    log.debug(`wrote question ${id} to ${filePath}`);
+    this.invalidateQuestionsCache();
+    return id;
+  }
+  async readQuestions(opts) {
+    const cacheKey = this.questionsDir;
+    const cached = _StorageManager.questionsCache.get(cacheKey);
+    if (cached && Date.now() - cached.loadedAt < _StorageManager.QUESTIONS_CACHE_TTL_MS) {
+      try {
+        const dirStat = await stat(this.questionsDir);
+        if (dirStat.mtimeMs <= cached.loadedAt) {
+          const all = cached.questions;
+          return opts?.unresolvedOnly ? all.filter((q) => !q.resolved) : all;
+        }
+      } catch {
+      }
+    }
+    try {
+      const files = await readdir(this.questionsDir);
+      const questions = [];
+      for (const file of files) {
+        if (!file.endsWith(".md")) continue;
+        const filePath = path.join(this.questionsDir, file);
+        const raw = await readFile(filePath, "utf-8");
+        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 [];
+    }
+  }
+  /** Invalidate the questions cache (call after writing a question). */
+  invalidateQuestionsCache() {
+    _StorageManager.questionsCache.delete(this.questionsDir);
+  }
+  parseQuestionFile(raw, filePath) {
+    const match = raw.match(/^---\n([\s\S]*?)\n---\n\n([\s\S]*)$/);
+    if (!match) return null;
+    const frontmatterStr = match[1];
+    const body = match[2].trim();
+    const id = this.extractFrontmatterValue(frontmatterStr, "id") ?? path.basename(filePath, ".md");
+    const created = this.extractFrontmatterValue(frontmatterStr, "created") ?? "";
+    const priority = parseFloat(
+      this.extractFrontmatterValue(frontmatterStr, "priority") ?? "0.5"
+    );
+    const resolved = this.extractFrontmatterValue(frontmatterStr, "resolved") === "true";
+    const contextMatch = body.match(/\*\*Context:\*\*\s*(.*)/);
+    const question = contextMatch ? body.slice(0, contextMatch.index).trim() : body;
+    const context = contextMatch ? contextMatch[1].trim() : "";
+    return { id, question, context, priority, resolved, created, filePath };
+  }
+  extractFrontmatterValue(frontmatter, key) {
+    const match = frontmatter.match(
+      new RegExp(`^${key}:\\s*"?([^"\\n]*)"?`, "m")
+    );
+    return match ? match[1] : null;
+  }
+  async resolveQuestion(id) {
+    const questions = await this.readQuestions();
+    const q = questions.find((q2) => q2.id === id);
+    if (!q) return false;
+    let raw = await readFile(q.filePath, "utf-8");
+    raw = raw.replace(/resolved: false/, "resolved: true");
+    raw = raw.replace(
+      /---\n\n/,
+      `resolvedAt: "${(/* @__PURE__ */ new Date()).toISOString()}"
+---
+
+`
+    );
+    await writeFile(q.filePath, raw, "utf-8");
+    log.debug(`resolved question ${id}`);
+    return true;
+  }
+  // ---------------------------------------------------------------------------
+  // Identity file
+  // ---------------------------------------------------------------------------
+  async readIdentity(workspaceDir, namespace) {
+    const identityPath = this.identityFilePath(workspaceDir, namespace);
+    try {
+      return await readFile(identityPath, "utf-8");
+    } catch {
+      return "";
+    }
+  }
+  async writeIdentity(workspaceDir, content, namespace) {
+    const identityPath = this.identityFilePath(workspaceDir, namespace);
+    await writeFile(identityPath, content, "utf-8");
+    log.debug(`wrote consolidated IDENTITY.md (${content.length} chars)`);
+  }
+  /** Max size for IDENTITY.md before we stop appending reflections (15KB leaves room under 20KB gateway limit) */
+  static IDENTITY_MAX_BYTES = 15e3;
+  /** Minimum interval between reflections (1 hour) */
+  static REFLECTION_COOLDOWN_MS = 60 * 60 * 1e3;
+  async appendToIdentity(workspaceDir, reflection, opts) {
+    const identityPath = this.identityFilePath(workspaceDir, opts?.namespace);
+    let existing = "";
+    try {
+      existing = await readFile(identityPath, "utf-8");
+    } catch {
+    }
+    const hygiene = opts?.hygiene;
+    const rotateEnabled = hygiene?.enabled === true && hygiene.rotateEnabled === true && Array.isArray(hygiene.rotatePaths) && hygiene.rotatePaths.includes(path.basename(identityPath));
+    if (rotateEnabled) {
+      const maxBytes = hygiene.rotateMaxBytes;
+      if (existing.length > maxBytes) {
+        const archiveDir = path.join(workspaceDir, hygiene.archiveDir);
+        const { newContent } = await rotateMarkdownFileToArchive({
+          filePath: identityPath,
+          archiveDir,
+          archivePrefix: "IDENTITY",
+          keepTailChars: hygiene.rotateKeepTailChars
+        });
+        await writeFile(identityPath, newContent, "utf-8");
+        existing = newContent;
+        log.info(
+          `rotated IDENTITY.md to archive (size=${existing.length} chars, maxBytes=${maxBytes})`
+        );
+      }
+    } else {
+      if (existing.length > _StorageManager.IDENTITY_MAX_BYTES) {
+        log.debug(`IDENTITY.md is ${existing.length} chars (limit ${_StorageManager.IDENTITY_MAX_BYTES}); skipping reflection`);
+        return;
+      }
+    }
+    const lastMatch = existing.match(/## Reflection — (\S+)\s*$/m);
+    if (lastMatch) {
+      const allMatches = [...existing.matchAll(/## Reflection — (\S+)/g)];
+      if (allMatches.length > 0) {
+        const lastTimestamp = allMatches[allMatches.length - 1][1];
+        const elapsed = Date.now() - new Date(lastTimestamp).getTime();
+        if (elapsed < _StorageManager.REFLECTION_COOLDOWN_MS) {
+          log.debug(`reflection cooldown: ${Math.round(elapsed / 1e3)}s since last (need ${_StorageManager.REFLECTION_COOLDOWN_MS / 1e3}s)`);
+          return;
+        }
+      }
+    }
+    const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+    const section = `
+
+## Reflection \u2014 ${timestamp}
+
+${reflection}
+`;
+    await writeFile(identityPath, existing + section, "utf-8");
+    log.debug(`appended reflection to ${identityPath}`);
+  }
+  async readIdentityReflections() {
+    try {
+      return await readFile(this.identityReflectionsPath, "utf-8");
+    } catch {
+      return null;
+    }
+  }
+  async writeIdentityReflections(content) {
+    await mkdir(this.identityDir, { recursive: true });
+    await writeFile(this.identityReflectionsPath, content, "utf-8");
+  }
+  async appendIdentityReflection(reflection) {
+    let existing = "";
+    try {
+      existing = await readFile(this.identityReflectionsPath, "utf-8");
+    } catch {
+    }
+    if (existing.length > _StorageManager.IDENTITY_MAX_BYTES) {
+      log.debug(
+        `identity/reflections.md is ${existing.length} chars (limit ${_StorageManager.IDENTITY_MAX_BYTES}); skipping reflection`
+      );
+      return;
+    }
+    const allMatches = [...existing.matchAll(/## Reflection — (\S+)/g)];
+    if (allMatches.length > 0) {
+      const lastTimestamp = allMatches[allMatches.length - 1][1];
+      const elapsed = Date.now() - new Date(lastTimestamp).getTime();
+      if (elapsed < _StorageManager.REFLECTION_COOLDOWN_MS) {
+        log.debug(
+          `reflection cooldown: ${Math.round(elapsed / 1e3)}s since last (need ${_StorageManager.REFLECTION_COOLDOWN_MS / 1e3}s)`
+        );
+        return;
+      }
+    }
+    const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+    const section = `${existing.trimEnd().length > 0 ? "\n\n" : ""}## Reflection \u2014 ${timestamp}
+
+${reflection}
+`;
+    await mkdir(this.identityDir, { recursive: true });
+    await writeFile(this.identityReflectionsPath, `${existing.trimEnd()}${section}`, "utf-8");
+    log.debug(`appended namespace-local reflection to ${this.identityReflectionsPath}`);
+  }
+  // ---------------------------------------------------------------------------
+  // Entity mutation helpers (Knowledge Graph v7.0)
+  // ---------------------------------------------------------------------------
+  /**
+   * Add a relationship to an entity file.
+   * Deduplicates by target+label.
+   */
+  async addEntityRelationship(name, rel) {
+    const filePath = path.join(this.entitiesDir, `${name}.md`);
+    let entity;
+    try {
+      const content = await readFile(filePath, "utf-8");
+      entity = parseEntityFile(content);
+    } catch {
+      log.debug(`addEntityRelationship: entity file ${name}.md not found`);
+      return;
+    }
+    const exists = entity.relationships.some(
+      (r) => r.target === rel.target && r.label === rel.label
+    );
+    if (exists) return;
+    entity.relationships.push(rel);
+    entity.updated = (/* @__PURE__ */ new Date()).toISOString();
+    await writeFile(filePath, serializeEntityFile(entity), "utf-8");
+    this.invalidateKnowledgeIndexCache();
+  }
+  /**
+   * Add an activity entry to an entity file.
+   * Prepends to the beginning, prunes oldest entries beyond maxEntries.
+   */
+  async addEntityActivity(name, entry, maxEntries) {
+    const filePath = path.join(this.entitiesDir, `${name}.md`);
+    let entity;
+    try {
+      const content = await readFile(filePath, "utf-8");
+      entity = parseEntityFile(content);
+    } catch {
+      log.debug(`addEntityActivity: entity file ${name}.md not found`);
+      return;
+    }
+    entity.activity.unshift(entry);
+    if (entity.activity.length > maxEntries) {
+      entity.activity = entity.activity.slice(0, maxEntries);
+    }
+    entity.updated = (/* @__PURE__ */ new Date()).toISOString();
+    await writeFile(filePath, serializeEntityFile(entity), "utf-8");
+    this.invalidateKnowledgeIndexCache();
+  }
+  /**
+   * Add an alias to an entity file. Deduplicates.
+   */
+  async addEntityAlias(name, alias) {
+    const filePath = path.join(this.entitiesDir, `${name}.md`);
+    let entity;
+    try {
+      const content = await readFile(filePath, "utf-8");
+      entity = parseEntityFile(content);
+    } catch {
+      log.debug(`addEntityAlias: entity file ${name}.md not found`);
+      return;
+    }
+    if (entity.aliases.includes(alias)) return;
+    entity.aliases.push(alias);
+    entity.updated = (/* @__PURE__ */ new Date()).toISOString();
+    await writeFile(filePath, serializeEntityFile(entity), "utf-8");
+    this.invalidateKnowledgeIndexCache();
+  }
+  /**
+   * Set or update the summary of an entity file.
+   */
+  async updateEntitySummary(name, summary) {
+    const filePath = path.join(this.entitiesDir, `${name}.md`);
+    let entity;
+    try {
+      const content = await readFile(filePath, "utf-8");
+      entity = parseEntityFile(content);
+    } catch {
+      log.debug(`updateEntitySummary: entity file ${name}.md not found`);
+      return;
+    }
+    entity.summary = summary;
+    entity.updated = (/* @__PURE__ */ new Date()).toISOString();
+    await writeFile(filePath, serializeEntityFile(entity), "utf-8");
+    this.invalidateKnowledgeIndexCache();
+    this.bumpMemoryStatusVersion();
+  }
+  // ---------------------------------------------------------------------------
+  // Scoring + Knowledge Index (Knowledge Graph v7.0)
+  // ---------------------------------------------------------------------------
+  /**
+   * Read all entity files and return lightweight EntityFile objects.
+   * Parsing is fast (~50-100ms for ~1,800 files) since entity files are small.
+   */
+  async readAllEntityFiles() {
+    const currentVersion = this.getMemoryStatusVersion();
+    const cached = getCachedEntities(this.baseDir, currentVersion);
+    if (cached) return cached;
+    try {
+      const entries = await readdir(this.entitiesDir);
+      const mdFiles = entries.filter((e) => e.endsWith(".md"));
+      if (mdFiles.length === 0) return [];
+      const BATCH_SIZE = 100;
+      const entities = [];
+      for (let i = 0; i < mdFiles.length; i += BATCH_SIZE) {
+        const batch = mdFiles.slice(i, i + BATCH_SIZE);
+        const results = await Promise.all(
+          batch.map(
+            (entry) => readFile(path.join(this.entitiesDir, entry), "utf-8").catch(() => null)
+          )
+        );
+        for (const content of results) {
+          if (content !== null) entities.push(parseEntityFile(content));
+        }
+      }
+      setCachedEntities(this.baseDir, entities, currentVersion);
+      return entities;
+    } catch {
+      return [];
+    }
+  }
+  /**
+   * Score an entity based on recency, frequency, activity, type priority,
+   * and relationship density.
+   *
+   * score = recency*0.40 + frequency*0.25 + activity*0.15 + typePriority*0.10 + relationshipDensity*0.10
+   */
+  static scoreEntity(entity, now) {
+    const updated = entity.updated ? new Date(entity.updated).getTime() : 0;
+    const daysSince = Math.max(0, (now.getTime() - updated) / (1e3 * 60 * 60 * 24));
+    const recency = 1 / (1 + daysSince / 7);
+    const frequency = Math.min(entity.facts.length / 20, 1);
+    const activityScore = Math.min(entity.activity.length / 10, 1);
+    const TYPE_PRIORITY = {
+      person: 1,
+      project: 0.8,
+      company: 0.7,
+      tool: 0.6,
+      place: 0.5,
+      other: 0.3
+    };
+    const typePriority = TYPE_PRIORITY[entity.type.toLowerCase()] ?? 0.3;
+    const relDensity = Math.min(entity.relationships.length / 8, 1);
+    return recency * 0.4 + frequency * 0.25 + activityScore * 0.15 + typePriority * 0.1 + relDensity * 0.1;
+  }
+  /**
+   * Build the Knowledge Index: a compact markdown table of top-scored entities.
+   * Respects maxEntities and maxChars limits from config.
+   */
+  async buildKnowledgeIndex(config, overrides) {
+    const useDefaultLimits = overrides?.maxEntities === void 0 && overrides?.maxChars === void 0;
+    if (useDefaultLimits && this.knowledgeIndexCache && Date.now() - this.knowledgeIndexCache.builtAt < _StorageManager.KNOWLEDGE_INDEX_CACHE_TTL_MS) {
+      return { result: this.knowledgeIndexCache.result, cached: true };
+    }
+    const entities = await this.readAllEntityFiles();
+    if (entities.length === 0) {
+      if (useDefaultLimits) this.knowledgeIndexCache = { result: "", builtAt: Date.now() };
+      return { result: "", cached: false };
+    }
+    const now = /* @__PURE__ */ new Date();
+    const scored = entities.map((e) => ({
+      name: e.name,
+      type: e.type,
+      score: _StorageManager.scoreEntity(e, now),
+      factCount: e.facts.length,
+      summary: e.summary,
+      topRelationships: e.relationships.slice(0, 3).map((r) => r.target)
+    }));
+    scored.sort((a, b) => b.score - a.score);
+    const maxEntities = typeof overrides?.maxEntities === "number" ? Math.max(0, Math.floor(overrides.maxEntities)) : config.knowledgeIndexMaxEntities;
+    const topN = scored.slice(0, maxEntities);
+    if (topN.length === 0) {
+      if (useDefaultLimits) this.knowledgeIndexCache = { result: "", builtAt: Date.now() };
+      return { result: "", cached: false };
+    }
+    const header = "## Knowledge Index\n\n| Entity | Type | Summary | Connected to |\n|--------|------|---------|-------------|";
+    const rows = [];
+    let totalChars = header.length;
+    const maxChars = typeof overrides?.maxChars === "number" ? Math.max(0, Math.floor(overrides.maxChars)) : config.knowledgeIndexMaxChars;
+    for (const entity of topN) {
+      const summary = entity.summary || `${entity.factCount} facts`;
+      const connected = entity.topRelationships.length > 0 ? entity.topRelationships.join(", ") : "\u2014";
+      const row = `| ${entity.name} | ${entity.type} | ${summary} | ${connected} |`;
+      if (totalChars + row.length + 1 > maxChars) break;
+      rows.push(row);
+      totalChars += row.length + 1;
+    }
+    const result = rows.length === 0 ? "" : `${header}
+${rows.join("\n")}
+`;
+    if (useDefaultLimits) this.knowledgeIndexCache = { result, builtAt: Date.now() };
+    return { result, cached: false };
+  }
+  /** Invalidate the Knowledge Index cache (call after entity mutations). */
+  invalidateKnowledgeIndexCache() {
+    this.knowledgeIndexCache = null;
+  }
+  // ---------------------------------------------------------------------------
+  // Commitment decay
+  // ---------------------------------------------------------------------------
+  /** Max lines for profile.md before LLM consolidation triggers */
+  static PROFILE_MAX_LINES = 300;
+  /**
+   * Merge fragmented entity files that resolve to the same canonical name.
+   * Preserves relationships, activity, aliases, and summary from all fragments.
+   * Returns count of files merged.
+   */
+  async mergeFragmentedEntities() {
+    let merged = 0;
+    try {
+      const entries = await readdir(this.entitiesDir);
+      const mdFiles = entries.filter((e) => e.endsWith(".md"));
+      const groups = /* @__PURE__ */ new Map();
+      for (const file of mdFiles) {
+        const baseName = file.replace(".md", "");
+        const dashIdx = baseName.indexOf("-");
+        if (dashIdx === -1) continue;
+        const type = baseName.slice(0, dashIdx);
+        const restOfName = baseName.slice(dashIdx + 1);
+        const canonical = normalizeEntityName(restOfName, type);
+        if (!groups.has(canonical)) groups.set(canonical, []);
+        groups.get(canonical).push(file);
+      }
+      for (const [canonical, files] of groups) {
+        if (files.length <= 1) continue;
+        const mergedEntity = {
+          name: "",
+          type: "other",
+          updated: "",
+          facts: [],
+          summary: void 0,
+          relationships: [],
+          activity: [],
+          aliases: []
+        };
+        for (const file of files) {
+          const filePath = path.join(this.entitiesDir, file);
+          try {
+            const content = await readFile(filePath, "utf-8");
+            const parsed = parseEntityFile(content);
+            if (!mergedEntity.type || mergedEntity.type === "other") {
+              mergedEntity.type = parsed.type;
+            }
+            if (!mergedEntity.updated || parsed.updated > mergedEntity.updated) {
+              mergedEntity.updated = parsed.updated;
+            }
+            if (parsed.name.length > mergedEntity.name.length) {
+              mergedEntity.name = parsed.name;
+            }
+            if (!mergedEntity.summary && parsed.summary) {
+              mergedEntity.summary = parsed.summary;
+            }
+            mergedEntity.facts.push(...parsed.facts);
+            mergedEntity.relationships.push(...parsed.relationships);
+            mergedEntity.activity.push(...parsed.activity);
+            mergedEntity.aliases.push(...parsed.aliases);
+          } catch {
+          }
+        }
+        mergedEntity.facts = [...new Set(mergedEntity.facts)];
+        const relKeys = /* @__PURE__ */ new Set();
+        mergedEntity.relationships = mergedEntity.relationships.filter((r) => {
+          const key = `${r.target}::${r.label}`;
+          if (relKeys.has(key)) return false;
+          relKeys.add(key);
+          return true;
+        });
+        const actKeys = /* @__PURE__ */ new Set();
+        mergedEntity.activity = mergedEntity.activity.filter((a) => {
+          const key = `${a.date}::${a.note}`;
+          if (actKeys.has(key)) return false;
+          actKeys.add(key);
+          return true;
+        }).sort((a, b) => b.date.localeCompare(a.date));
+        mergedEntity.aliases = [...new Set(mergedEntity.aliases)];
+        if (!mergedEntity.name) {
+          const dashIdx = canonical.indexOf("-");
+          mergedEntity.name = dashIdx !== -1 ? canonical.slice(dashIdx + 1) : canonical;
+        }
+        mergedEntity.updated = mergedEntity.updated || (/* @__PURE__ */ new Date()).toISOString();
+        const canonicalPath = path.join(this.entitiesDir, `${canonical}.md`);
+        await writeFile(canonicalPath, serializeEntityFile(mergedEntity), "utf-8");
+        for (const file of files) {
+          const filePath = path.join(this.entitiesDir, file);
+          if (filePath !== canonicalPath) {
+            try {
+              await unlink(filePath);
+              merged++;
+              log.debug(`merged entity ${file} \u2192 ${canonical}.md`);
+            } catch {
+            }
+          }
+        }
+      }
+    } catch {
+    }
+    return merged;
+  }
+  async cleanExpiredCommitments(decayDays) {
+    const memories = await this.readAllMemories();
+    const cutoff = Date.now() - decayDays * 24 * 60 * 60 * 1e3;
+    const deleted = [];
+    for (const m of memories) {
+      if (m.frontmatter.category !== "commitment") continue;
+      const isResolved = m.frontmatter.tags.some(
+        (t) => t === "fulfilled" || t === "expired"
+      );
+      if (!isResolved) continue;
+      const updatedAt = new Date(m.frontmatter.updated).getTime();
+      if (updatedAt < cutoff) {
+        try {
+          await unlink(m.path);
+          deleted.push(m);
+          log.debug(`cleaned expired commitment ${m.frontmatter.id}`);
+        } catch {
+        }
+      }
+    }
+    if (deleted.length > 0) {
+      this.bumpMemoryStatusVersion();
+    }
+    return deleted;
+  }
+  // ---------------------------------------------------------------------------
+  // Access Tracking (Phase 1A)
+  // ---------------------------------------------------------------------------
+  /**
+   * Flush batched access tracking updates to disk.
+   * Called during consolidation or when buffer exceeds max size.
+   */
+  async flushAccessTracking(entries) {
+    if (entries.length === 0) return 0;
+    const memories = await this.readAllMemories();
+    const memoryMap = new Map(memories.map((m) => [m.frontmatter.id, m]));
+    let updated = 0;
+    for (const entry of entries) {
+      const memory = memoryMap.get(entry.memoryId);
+      if (!memory) continue;
+      const newFm = {
+        ...memory.frontmatter,
+        accessCount: entry.newCount,
+        lastAccessed: entry.lastAccessed
+      };
+      const fileContent = `${serializeFrontmatter(newFm)}
+
+${memory.content}
+`;
+      try {
+        await writeFile(memory.path, fileContent, "utf-8");
+        updated++;
+      } catch (err) {
+        log.debug(`failed to update access tracking for ${entry.memoryId}: ${err}`);
+      }
+    }
+    if (updated > 0) {
+      log.debug(`flushed access tracking for ${updated} memories`);
+    }
+    return updated;
+  }
+  /**
+   * Get a memory by its ID.
+   */
+  async getMemoryById(id) {
+    const memories = await this.readAllMemories();
+    return memories.find((m) => m.frontmatter.id === id) ?? null;
+  }
+  async getProjectedMemoryState(id) {
+    const projected = readProjectedMemoryState(this.baseDir, id);
+    if (projected) return projected;
+    const active = await this.getMemoryById(id);
+    if (active) return this.toProjectedCurrentState(active, "active");
+    const archived = (await this.readArchivedMemories()).find((memory) => memory.frontmatter.id === id);
+    if (!archived) return null;
+    return this.toProjectedCurrentState(archived, "archived");
+  }
+  async browseProjectedMemories(options) {
+    return readProjectedMemoryBrowse(this.baseDir, options);
+  }
+  async getProjectedGovernanceRecord() {
+    return readProjectedGovernanceRecord(this.baseDir);
+  }
+  toProjectedCurrentState(memory, fallbackStatus) {
+    const pathRel = toMemoryPathRel(this.baseDir, memory.path);
+    return {
+      memoryId: memory.frontmatter.id,
+      category: memory.frontmatter.category,
+      status: inferCurrentStateStatus(memory.frontmatter, pathRel, fallbackStatus),
+      lifecycleState: memory.frontmatter.lifecycleState,
+      path: memory.path,
+      pathRel,
+      created: memory.frontmatter.created,
+      updated: memory.frontmatter.updated,
+      archivedAt: memory.frontmatter.archivedAt,
+      supersededAt: memory.frontmatter.supersededAt,
+      entityRef: memory.frontmatter.entityRef,
+      source: memory.frontmatter.source,
+      confidence: memory.frontmatter.confidence,
+      confidenceTier: memory.frontmatter.confidenceTier,
+      memoryKind: memory.frontmatter.memoryKind,
+      accessCount: memory.frontmatter.accessCount,
+      lastAccessed: memory.frontmatter.lastAccessed,
+      tags: normalizeProjectionTags(memory.frontmatter.tags),
+      preview: normalizeProjectionPreview(memory.content)
+    };
+  }
+  async getMemoryTimeline(memoryId, limit = 200) {
+    const cappedLimit = Math.max(0, Math.floor(limit));
+    if (cappedLimit === 0) return [];
+    const projected = readProjectedMemoryTimeline(this.baseDir, memoryId, cappedLimit);
+    if (projected && projected.length > 0) return projected;
+    const events = await this.readAllMemoryLifecycleEvents();
+    return events.filter((event) => event.memoryId === memoryId).slice(-cappedLimit);
+  }
+  // ---------------------------------------------------------------------------
+  // Chunking (Phase 2A)
+  // ---------------------------------------------------------------------------
+  /**
+   * Write a memory chunk with parent reference.
+   * Chunk IDs follow format: {parentId}-chunk-{index}
+   */
+  async writeChunk(parentId, chunkIndex, chunkTotal, category, content, options = {}) {
+    await this.ensureDirectories();
+    const now = /* @__PURE__ */ new Date();
+    const today = now.toISOString().slice(0, 10);
+    const id = `${parentId}-chunk-${chunkIndex}`;
+    const conf = options.confidence ?? 0.8;
+    const tier = confidenceTier(conf);
+    const fm = {
+      id,
+      category,
+      created: now.toISOString(),
+      updated: now.toISOString(),
+      source: options.source ?? "chunking",
+      confidence: conf,
+      confidenceTier: tier,
+      tags: options.tags ?? [],
+      entityRef: options.entityRef,
+      importance: options.importance,
+      parentId,
+      chunkIndex,
+      chunkTotal,
+      intentGoal: options.intentGoal,
+      intentActionType: options.intentActionType,
+      intentEntityTypes: options.intentEntityTypes,
+      memoryKind: options.memoryKind
+    };
+    const sanitized = sanitizeMemoryContent(content);
+    if (!sanitized.clean) {
+      log.warn(`chunk content sanitized for ${id}; violations=${sanitized.violations.join(", ")}`);
+    }
+    const fileContent = `${serializeFrontmatter(fm)}
+
+${sanitized.text}
+`;
+    let filePath;
+    if (category === "correction") {
+      filePath = path.join(this.correctionsDir, `${id}.md`);
+    } else {
+      filePath = path.join(this.factsDir, today, `${id}.md`);
+    }
+    await writeFile(filePath, fileContent, "utf-8");
+    log.debug(`wrote chunk ${id} (${chunkIndex + 1}/${chunkTotal}) to ${filePath}`);
+    return id;
+  }
+  /**
+   * Get all chunks for a given parent memory ID.
+   * Returns chunks sorted by chunkIndex.
+   */
+  async getChunksForParent(parentId) {
+    const memories = await this.readAllMemories();
+    return memories.filter((m) => m.frontmatter.parentId === parentId).sort((a, b) => (a.frontmatter.chunkIndex ?? 0) - (b.frontmatter.chunkIndex ?? 0));
+  }
+  // ---------------------------------------------------------------------------
+  // Contradiction Detection (Phase 2B)
+  // ---------------------------------------------------------------------------
+  /**
+   * Mark a memory as superseded by another.
+   * Updates the old memory's status and adds the supersededBy link.
+   */
+  async supersedeMemory(oldMemoryId, newMemoryId, reason) {
+    const memories = await this.readAllMemories();
+    const oldMemory = memories.find((m) => m.frontmatter.id === oldMemoryId);
+    if (!oldMemory) return false;
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const updatedFm = {
+      ...oldMemory.frontmatter,
+      status: "superseded",
+      supersededBy: newMemoryId,
+      supersededAt: now,
+      updated: now
+    };
+    const fileContent = `${serializeFrontmatter(updatedFm)}
+
+${oldMemory.content}
+`;
+    try {
+      await writeFile(oldMemory.path, fileContent, "utf-8");
+      await this.appendGeneratedMemoryLifecycleEventFailOpen("storage.supersedeMemory", {
+        memoryId: oldMemoryId,
+        eventType: "superseded",
+        timestamp: now,
+        actor: "storage.supersedeMemory",
+        reasonCode: reason,
+        before: this.summarizeLifecycleState(oldMemory.frontmatter, oldMemory.path),
+        after: this.summarizeLifecycleState(updatedFm, oldMemory.path),
+        relatedMemoryIds: [newMemoryId]
+      });
+      this.bumpMemoryStatusVersion();
+      log.debug(`superseded memory ${oldMemoryId} by ${newMemoryId}: ${reason}`);
+      await this.writeMemory("correction", `Superseded: ${oldMemory.content}
+
+Reason: ${reason}`, {
+        confidence: 1,
+        tags: ["supersession", "auto-resolved"],
+        source: "contradiction-detection",
+        lineage: [oldMemoryId, newMemoryId]
+      });
+      return true;
+    } catch (err) {
+      log.error(`failed to supersede memory ${oldMemoryId}:`, err);
+      return false;
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // Memory Summarization (Phase 4A)
+  // ---------------------------------------------------------------------------
+  get summariesDir() {
+    return path.join(this.baseDir, "summaries");
+  }
+  /**
+   * Write a memory summary.
+   */
+  async writeSummary(summary) {
+    await mkdir(this.summariesDir, { recursive: true });
+    const filePath = path.join(this.summariesDir, `${summary.id}.json`);
+    await writeFile(filePath, JSON.stringify(summary, null, 2), "utf-8");
+    log.debug(`wrote summary ${summary.id}`);
+  }
+  /**
+   * Get all summaries.
+   */
+  async readSummaries() {
+    try {
+      const files = await readdir(this.summariesDir);
+      const summaries = [];
+      for (const file of files) {
+        if (!file.endsWith(".json")) continue;
+        const filePath = path.join(this.summariesDir, file);
+        const raw = await readFile(filePath, "utf-8");
+        summaries.push(JSON.parse(raw));
+      }
+      return summaries;
+    } catch {
+      return [];
+    }
+  }
+  /**
+   * Archive memories (mark as archived, not delete).
+   */
+  async archiveMemories(memoryIds, summaryId) {
+    const memories = await this.readAllMemories();
+    const memoryMap = new Map(memories.map((m) => [m.frontmatter.id, m]));
+    let archived = 0;
+    for (const id of memoryIds) {
+      const memory = memoryMap.get(id);
+      if (!memory) continue;
+      const now = (/* @__PURE__ */ new Date()).toISOString();
+      const updatedFm = {
+        ...memory.frontmatter,
+        status: "archived",
+        archivedAt: now,
+        updated: now
+      };
+      const fileContent = `${serializeFrontmatter(updatedFm)}
+
+${memory.content}
+`;
+      try {
+        await writeFile(memory.path, fileContent, "utf-8");
+        await this.appendGeneratedMemoryLifecycleEventFailOpen("storage.archiveMemories", {
+          memoryId: id,
+          eventType: "archived",
+          timestamp: updatedFm.archivedAt ?? updatedFm.updated,
+          actor: "storage.archiveMemories",
+          reasonCode: `summary:${summaryId}`,
+          before: this.summarizeLifecycleState(memory.frontmatter, memory.path),
+          after: this.summarizeLifecycleState(updatedFm, memory.path),
+          relatedMemoryIds: [summaryId]
+        });
+        archived++;
+      } catch {
+      }
+    }
+    if (archived > 0) {
+      this.bumpMemoryStatusVersion();
+      log.debug(`archived ${archived} memories for summary ${summaryId}`);
+    }
+    return archived;
+  }
+  // ---------------------------------------------------------------------------
+  // Topic Extraction (Phase 4B)
+  // ---------------------------------------------------------------------------
+  /**
+   * Save topic scores to meta.json.
+   */
+  async saveTopics(topics) {
+    const metaPath = path.join(this.stateDir, "topics.json");
+    await mkdir(this.stateDir, { recursive: true });
+    await writeFile(metaPath, JSON.stringify({ topics, updatedAt: (/* @__PURE__ */ new Date()).toISOString() }, null, 2), "utf-8");
+    log.debug(`saved ${topics.length} topic scores`);
+  }
+  /**
+   * Load topic scores from meta.json.
+   */
+  async loadTopics() {
+    const metaPath = path.join(this.stateDir, "topics.json");
+    try {
+      const raw = await readFile(metaPath, "utf-8");
+      return JSON.parse(raw);
+    } catch {
+      return { topics: [], updatedAt: null };
+    }
+  }
+  /**
+   * Add links to an existing memory.
+   */
+  async addLinksToMemory(memoryId, links, lifecycle) {
+    const memories = await this.readAllMemories();
+    const memory = memories.find((m) => m.frontmatter.id === memoryId);
+    if (!memory) return false;
+    const existingLinks = memory.frontmatter.links ?? [];
+    const mergedLinks = [...existingLinks];
+    for (const link of links) {
+      if (!mergedLinks.some((l) => l.targetId === link.targetId && l.linkType === link.linkType)) {
+        mergedLinks.push(link);
+      }
+    }
+    try {
+      await this.writeMemoryFrontmatter(
+        memory,
+        {
+          links: mergedLinks,
+          updated: (/* @__PURE__ */ new Date()).toISOString()
+        },
+        lifecycle
+      );
+      log.debug(`added ${links.length} links to memory ${memoryId}`);
+      return true;
+    } catch (err) {
+      log.error(`failed to add links to memory ${memoryId}:`, err);
+      return false;
+    }
+  }
+  summarizeLifecycleState(frontmatter, filePath) {
+    return {
+      category: frontmatter.category,
+      path: filePath,
+      status: frontmatter.status ?? "active",
+      lifecycleState: frontmatter.lifecycleState
+    };
+  }
+  frontmatterPatchEventType(before, after) {
+    const beforeStatus = before.status ?? "active";
+    const afterStatus = after.status ?? "active";
+    if (beforeStatus !== "archived" && afterStatus === "archived") return "archived";
+    if (beforeStatus !== "superseded" && afterStatus === "superseded") return "superseded";
+    if (beforeStatus !== "rejected" && afterStatus === "rejected") return "rejected";
+    if (beforeStatus !== "active" && afterStatus === "active") {
+      return "restored";
+    }
+    return "updated";
+  }
+  async appendGeneratedMemoryLifecycleEvent(input, ruleVersion = "memory-lifecycle-ledger.v1") {
+    await this.appendMemoryLifecycleEvents([
+      {
+        ...input,
+        eventId: this.generateId("mle"),
+        ruleVersion
+      }
+    ]);
+  }
+  async appendGeneratedMemoryLifecycleEventFailOpen(operation, input, ruleVersion) {
+    try {
+      await this.appendGeneratedMemoryLifecycleEvent(input, ruleVersion);
+    } catch (appendErr) {
+      log.warn(`${operation} completed but failed to append lifecycle event: ${appendErr}`);
+    }
+  }
+};
+
+export {
+  normalizeEntityName,
+  ContentHashIndex,
+  parseEntityFile,
+  serializeEntityFile,
+  StorageManager
+};
+//# sourceMappingURL=chunk-QWUUMMIK.js.map