@danielsimonjr/memoryjs 2.1.2 → 2.3.0

package/dist/cli/index.js

@@ -6730,7 +6730,30 @@ var init_GraphStorage = __esm({
       // ArtifactEntity extension (types/artifact.ts)
       "artifactType",
       "toolName",
-      "shortId"
+      "shortId",
+      // v2.1.0 subclass-manager record fields (sibling to the v2.1.1
+      // UpdateEntitySchema.passthrough fix — same root cause: subclass managers
+      // attach domain records that the persistence allowlist must also admit,
+      // otherwise the records are silently dropped on save and the managers'
+      // list/match/get operations return empty on next load).
+      "heuristicRecord",
+      // HeuristicEntity
+      "decisionRecord",
+      // DecisionEntity (includes nested lifecycle)
+      "exclusionRule",
+      // ExclusionEntity
+      "projectContextRecord",
+      // ProjectContextEntity
+      "toolAffordanceRecord",
+      // ToolAffordanceEntity
+      "prospectiveRecord",
+      // ProspectiveEntity
+      "failureRecord",
+      // FailureEntity
+      "planRecord",
+      // PlanEntity
+      "reflectionRecord"
+      // ReflectionEntity
     ];
     GraphStorage = class {
       /**
@@ -11245,7 +11268,7 @@ var init_GraphTraversal = __esm({
           Object.entries(options).filter(([, v]) => v !== void 0)
         );
         const opts = { ...DEFAULT_OPTIONS, ...definedOptions };
-        const neighbors = [];
+        const neighbors2 = [];
         let relations = [];
         if (opts.direction === "outgoing" || opts.direction === "both") {
           relations = relations.concat(this.storage.getRelationsFrom(entityName));
@@ -11266,9 +11289,9 @@ var init_GraphTraversal = __esm({
             const typeSet = new Set(opts.entityTypes.map((t) => t.toLowerCase()));
             if (!typeSet.has(entity.entityType.toLowerCase())) continue;
           }
-          neighbors.push({ neighbor, relation });
+          neighbors2.push({ neighbor, relation });
         }
-        return neighbors;
+        return neighbors2;
       }
       /**
        * Breadth-First Search traversal starting from a given entity.
@@ -11294,8 +11317,8 @@ var init_GraphTraversal = __esm({
           if (depth > opts.maxDepth) continue;
           nodes.push(node);
           depths.set(node, depth);
-          const neighbors = this.getNeighborsWithRelations(node, opts);
-          for (const { neighbor } of neighbors) {
+          const neighbors2 = this.getNeighborsWithRelations(node, opts);
+          for (const { neighbor } of neighbors2) {
             if (!visited.has(neighbor)) {
               visited.add(neighbor);
               queue.push({ node: neighbor, depth: depth + 1 });
@@ -11330,8 +11353,8 @@ var init_GraphTraversal = __esm({
           visited.add(node);
           nodes.push(node);
           depths.set(node, depth);
-          const neighbors = this.getNeighborsWithRelations(node, opts);
-          for (const { neighbor } of neighbors) {
+          const neighbors2 = this.getNeighborsWithRelations(node, opts);
+          for (const { neighbor } of neighbors2) {
             if (!visited.has(neighbor)) {
               stack.push({ node: neighbor, depth: depth + 1 });
               if (!parents.has(neighbor)) {
@@ -11378,8 +11401,8 @@ var init_GraphTraversal = __esm({
             }
             return result;
           }
-          const neighbors = this.getNeighborsWithRelations(current, opts);
-          for (const { neighbor, relation } of neighbors) {
+          const neighbors2 = this.getNeighborsWithRelations(current, opts);
+          for (const { neighbor, relation } of neighbors2) {
             if (!visited.has(neighbor)) {
               visited.add(neighbor);
               queue.push(neighbor);
@@ -11453,8 +11476,8 @@ var init_GraphTraversal = __esm({
             });
             return;
           }
-          const neighbors = this.getNeighborsWithRelations(current, opts);
-          for (const { neighbor, relation } of neighbors) {
+          const neighbors2 = this.getNeighborsWithRelations(current, opts);
+          for (const { neighbor, relation } of neighbors2) {
             if (!visited.has(neighbor)) {
               visited.add(neighbor);
               currentPath.push(neighbor);
@@ -11498,8 +11521,8 @@ var init_GraphTraversal = __esm({
             while (queue.length > 0) {
               const current = queue.shift();
               component.push(current);
-              const neighbors = this.getNeighborsWithRelations(current, { direction: "both" });
-              for (const { neighbor } of neighbors) {
+              const neighbors2 = this.getNeighborsWithRelations(current, { direction: "both" });
+              for (const { neighbor } of neighbors2) {
                 if (!visited.has(neighbor)) {
                   visited.add(neighbor);
                   queue.push(neighbor);
@@ -11594,8 +11617,8 @@ var init_GraphTraversal = __esm({
           while (queue.length > 0) {
             const v = queue.shift();
             stack.push(v);
-            const neighbors = this.getNeighborsWithRelations(v, { direction: "both" });
-            for (const { neighbor: w } of neighbors) {
+            const neighbors2 = this.getNeighborsWithRelations(v, { direction: "both" });
+            for (const { neighbor: w } of neighbors2) {
               if (distance.get(w) === -1) {
                 distance.set(w, distance.get(v) + 1);
                 queue.push(w);
@@ -33370,11 +33393,11 @@ var init_CausalReasoner = __esm({
           if (d > depth) return;
           inPath.add(node);
           path6.push(node);
-          const neighbors = this.traversal.getNeighborsWithRelations(node, {
+          const neighbors2 = this.traversal.getNeighborsWithRelations(node, {
             relationTypes: this.causalTypes,
             direction: "outgoing"
           });
-          for (const { neighbor, relation } of neighbors) {
+          for (const { neighbor, relation } of neighbors2) {
             if (inPath.has(neighbor)) {
               const idx = path6.indexOf(neighbor);
               if (idx >= 0) {
@@ -35164,657 +35187,940 @@ var init_ManagerContext = __esm({
   }
 });
 
-// src/cli/interactive.ts
-var interactive_exports = {};
-__export(interactive_exports, {
-  startInteractiveMode: () => startInteractiveMode
-});
-import * as readline from "readline";
-import chalk2 from "chalk";
-async function startInteractiveMode(options) {
-  const ctx = new ManagerContext(options.storage);
-  const interactiveCtx = {
-    ctx,
-    options,
-    history: []
+// src/cli/options.ts
+function parseGlobalOptions(opts) {
+  const rawFormat = opts.outputFormat;
+  const format = rawFormat && ["json", "table", "csv"].includes(rawFormat) ? rawFormat : defaultOptions.format;
+  return {
+    storage: opts.storage || defaultOptions.storage,
+    format,
+    quiet: Boolean(opts.quiet),
+    verbose: Boolean(opts.verbose)
   };
-  const graph = await ctx.storage.loadGraph();
-  const entityNames = graph.entities.map((e) => e.name);
-  const rl = readline.createInterface({
-    input: process.stdin,
-    output: process.stdout,
-    prompt: chalk2.cyan("memory> "),
-    completer: (line) => {
-      const completions = [
-        "entities",
-        "relations",
-        "search",
-        "get",
-        "stats",
-        "tags",
-        "path",
-        "observe",
-        "delete",
-        "export",
-        "help",
-        "exit",
-        "clear",
-        "history",
-        ...entityNames
-      ];
-      const hits = completions.filter((c) => c.toLowerCase().startsWith(line.toLowerCase()));
-      return [hits.length ? hits : completions, line];
-    }
-  });
-  console.log(chalk2.green("MemoryJS Interactive Mode"));
-  console.log(chalk2.gray('Type "help" for commands, "exit" to quit.\n'));
-  rl.prompt();
-  rl.on("line", async (line) => {
-    const trimmed = line.trim();
-    if (!trimmed) {
-      rl.prompt();
-      return;
-    }
-    interactiveCtx.history.push(trimmed);
-    try {
-      await processCommand(trimmed, interactiveCtx, rl);
-    } catch (error) {
-      console.error(chalk2.red(`Error: ${error.message}`));
-    }
-    rl.prompt();
-  });
-  rl.on("close", () => {
-    console.log(chalk2.gray("\nGoodbye!"));
-    process.exit(0);
-  });
 }
-async function processCommand(input, ictx, rl) {
-  const [command, ...args] = input.split(/\s+/);
-  const ctx = ictx.ctx;
-  switch (command.toLowerCase()) {
-    case "help":
-    case ".help":
-      showHelp();
-      break;
-    case "exit":
-    case ".exit":
-    case "quit":
-      rl.close();
-      break;
-    case "clear":
-    case ".clear":
-      console.clear();
-      break;
-    case "entities":
-    case "ls": {
-      const graph = await ctx.storage.loadGraph();
-      const entities = graph.entities;
-      console.log(`
-Entities (${entities.length}):`);
-      for (const e of entities.slice(0, 20)) {
-        console.log(`  ${chalk2.cyan(e.name)} [${e.entityType}]`);
-      }
-      if (entities.length > 20) {
-        console.log(`  ... and ${entities.length - 20} more`);
+function createLogger(options) {
+  return {
+    info: (msg) => !options.quiet && console.log(msg),
+    debug: (msg) => options.verbose && console.log(`[DEBUG] ${msg}`),
+    error: (msg) => console.error(`[ERROR] ${msg}`),
+    warn: (msg) => !options.quiet && console.warn(`[WARN] ${msg}`)
+  };
+}
+var defaultOptions;
+var init_options = __esm({
+  "src/cli/options.ts"() {
+    "use strict";
+    init_esm_shims();
+    defaultOptions = {
+      storage: process.env.MEMORYJS_STORAGE_PATH || "./memory.jsonl",
+      format: process.env.MEMORYJS_OUTPUT_FORMAT || "json",
+      quiet: false,
+      verbose: false
+    };
+  }
+});
+
+// src/cli/config.ts
+import { existsSync as existsSync2, readFileSync } from "fs";
+import { resolve as resolve2, dirname as dirname8 } from "path";
+function findConfigFile(startDir = process.cwd()) {
+  let currentDir = startDir;
+  const root = resolve2("/");
+  while (currentDir !== root) {
+    for (const filename of CONFIG_FILES) {
+      const configPath = resolve2(currentDir, filename);
+      if (existsSync2(configPath)) {
+        return configPath;
       }
-      break;
     }
-    case "get": {
-      const name = args.join(" ");
-      if (!name) {
-        console.log(chalk2.yellow("Usage: get <entity-name>"));
-        break;
-      }
-      const entity = await ctx.entityManager.getEntity(name);
-      if (entity) {
-        console.log(JSON.stringify(entity, null, 2));
-      } else {
-        console.log(chalk2.yellow(`Entity not found: ${name}`));
+    const parentDir = dirname8(currentDir);
+    if (parentDir === currentDir) break;
+    currentDir = parentDir;
+  }
+  return null;
+}
+function loadConfig(configPath) {
+  try {
+    const content = readFileSync(configPath, "utf-8");
+    const config = JSON.parse(content);
+    return validateConfig2(config);
+  } catch (error) {
+    console.warn(`Warning: Failed to load config from ${configPath}`);
+    return {};
+  }
+}
+function validateConfig2(config) {
+  const validated = {};
+  if (typeof config.storage === "string") {
+    validated.storage = config.storage;
+  }
+  if (config.format && ["json", "table", "csv"].includes(config.format)) {
+    validated.format = config.format;
+  }
+  if (typeof config.quiet === "boolean") {
+    validated.quiet = config.quiet;
+  }
+  if (typeof config.verbose === "boolean") {
+    validated.verbose = config.verbose;
+  }
+  return validated;
+}
+function mergeConfig2(fileConfig, cliOptions) {
+  return {
+    storage: cliOptions.storage ?? fileConfig.storage ?? "./memory.jsonl",
+    format: cliOptions.format ?? fileConfig.format ?? "json",
+    quiet: cliOptions.quiet ?? fileConfig.quiet ?? false,
+    verbose: cliOptions.verbose ?? fileConfig.verbose ?? false
+  };
+}
+var CONFIG_FILES;
+var init_config = __esm({
+  "src/cli/config.ts"() {
+    "use strict";
+    init_esm_shims();
+    CONFIG_FILES = [
+      ".memoryjsrc",
+      ".memoryjsrc.json",
+      "memoryjs.config.json"
+    ];
+  }
+});
+
+// src/cli/formatters.ts
+import Table from "cli-table3";
+import chalk from "chalk";
+function getTerminalWidth() {
+  return process.stdout.columns || 80;
+}
+function formatEntities(entities, format) {
+  if (entities.length === 0) {
+    return format === "json" ? "[]" : "No entities found.";
+  }
+  switch (format) {
+    case "json":
+      return JSON.stringify(entities, null, 2);
+    case "table": {
+      const table = new Table({
+        head: [chalk.cyan("Name"), chalk.cyan("Type"), chalk.cyan("Observations"), chalk.cyan("Tags")],
+        colWidths: calculateColWidths(getTerminalWidth(), [0.25, 0.15, 0.4, 0.2]),
+        wordWrap: true
+      });
+      for (const entity of entities) {
+        table.push([
+          entity.name,
+          entity.entityType,
+          (entity.observations || []).slice(0, 3).join("; ") + (entity.observations && entity.observations.length > 3 ? "..." : ""),
+          (entity.tags || []).join(", ")
+        ]);
       }
-      break;
+      return table.toString();
     }
-    case "search": {
-      const query = args.join(" ");
-      if (!query) {
-        console.log(chalk2.yellow("Usage: search <query>"));
-        break;
-      }
-      const result = await ctx.searchManager.searchNodes(query);
-      console.log(`
-Search results for "${query}":`);
-      for (const entity of result.entities.slice(0, 10)) {
-        console.log(`  ${chalk2.cyan(entity.name)} [${entity.entityType}]`);
-        if (entity.observations && entity.observations.length > 0) {
-          const preview = entity.observations[0].substring(0, 60);
-          console.log(`    ${chalk2.gray(preview)}${entity.observations[0].length > 60 ? "..." : ""}`);
-        }
-      }
-      if (result.entities.length > 10) {
-        console.log(`  ... and ${result.entities.length - 10} more`);
-      }
-      break;
+    case "csv": {
+      const header = "name,entityType,observations,tags";
+      const rows = entities.map((e) => [
+        escapeCSV(e.name),
+        escapeCSV(e.entityType),
+        escapeCSV((e.observations || []).join("; ")),
+        escapeCSV((e.tags || []).join(", "))
+      ].join(","));
+      return [header, ...rows].join("\n");
     }
-    case "relations": {
-      const name = args.join(" ");
-      if (!name) {
-        console.log(chalk2.yellow("Usage: relations <entity-name>"));
-        break;
-      }
-      const relations = await ctx.relationManager.getRelations(name);
-      if (relations.length === 0) {
-        console.log(chalk2.yellow(`No relations found for: ${name}`));
-        break;
-      }
-      console.log(`
-Relations for "${name}":`);
+  }
+}
+function formatRelations(relations, format) {
+  if (relations.length === 0) {
+    return format === "json" ? "[]" : "No relations found.";
+  }
+  switch (format) {
+    case "json":
+      return JSON.stringify(relations, null, 2);
+    case "table": {
+      const table = new Table({
+        head: [chalk.cyan("From"), chalk.cyan("Relation"), chalk.cyan("To")],
+        colWidths: calculateColWidths(getTerminalWidth(), [0.35, 0.3, 0.35])
+      });
       for (const rel of relations) {
-        if (rel.from === name) {
-          console.log(`  ${chalk2.cyan(name)} --[${rel.relationType}]--> ${rel.to}`);
-        } else {
-          console.log(`  ${rel.from} --[${rel.relationType}]--> ${chalk2.cyan(name)}`);
-        }
+        table.push([rel.from, rel.relationType, rel.to]);
       }
-      break;
+      return table.toString();
     }
-    case "stats": {
-      const stats = await ctx.analyticsManager.getGraphStats();
-      console.log(`
-Knowledge Graph Statistics:`);
-      console.log(`  Entities: ${stats.totalEntities}`);
-      console.log(`  Relations: ${stats.totalRelations}`);
-      console.log(`  Entity Types: ${Object.keys(stats.entityTypesCounts).length}`);
-      console.log(`  Relation Types: ${Object.keys(stats.relationTypesCounts).length}`);
-      break;
+    case "csv": {
+      const header = "from,relationType,to";
+      const rows = relations.map((r) => [
+        escapeCSV(r.from),
+        escapeCSV(r.relationType),
+        escapeCSV(r.to)
+      ].join(","));
+      return [header, ...rows].join("\n");
     }
-    case "tags": {
-      const tagName = args.join(" ");
-      if (!tagName) {
-        console.log(chalk2.yellow("Usage: tags <entity-name>"));
-        break;
-      }
-      const tagEntity = await ctx.entityManager.getEntity(tagName);
-      if (tagEntity) {
-        const tags = tagEntity.tags || [];
-        console.log(`
-Tags for "${tagName}": ${tags.length > 0 ? tags.join(", ") : "None"}`);
-      } else {
-        console.log(chalk2.yellow(`Entity not found: ${tagName}`));
+  }
+}
+function formatSearchResults(results, format) {
+  if (results.length === 0) {
+    return format === "json" ? "[]" : "No results found.";
+  }
+  switch (format) {
+    case "json":
+      return JSON.stringify(results, null, 2);
+    case "table": {
+      const table = new Table({
+        head: [chalk.cyan("Name"), chalk.cyan("Type"), chalk.cyan("Score"), chalk.cyan("Observations")],
+        colWidths: calculateColWidths(getTerminalWidth(), [0.25, 0.15, 0.1, 0.5]),
+        wordWrap: true
+      });
+      for (const result of results) {
+        table.push([
+          result.entity.name,
+          result.entity.entityType,
+          result.score !== void 0 ? result.score.toFixed(3) : "-",
+          (result.entity.observations || []).slice(0, 2).join("; ") + (result.entity.observations && result.entity.observations.length > 2 ? "..." : "")
+        ]);
       }
-      break;
+      return table.toString();
     }
-    case "path": {
-      if (args.length < 2) {
-        console.log(chalk2.yellow("Usage: path <from> <to>"));
-        break;
-      }
-      const [pathFrom, pathTo] = args;
-      const pathResult = await ctx.graphTraversal.findShortestPath(pathFrom, pathTo);
-      if (pathResult) {
-        console.log(`
-Path (${pathResult.length} hops): ${pathResult.path.join(" -> ")}`);
-        for (const rel of pathResult.relations) {
-          console.log(`  ${rel.from} --[${rel.relationType}]--> ${rel.to}`);
+    case "csv": {
+      const header = "name,entityType,score,observations";
+      const rows = results.map((r) => [
+        escapeCSV(r.entity.name),
+        escapeCSV(r.entity.entityType),
+        r.score !== void 0 ? r.score.toFixed(3) : "",
+        escapeCSV((r.entity.observations || []).join("; "))
+      ].join(","));
+      return [header, ...rows].join("\n");
+    }
+  }
+}
+function formatEntityDetail(entity, format) {
+  if (!entity) {
+    return format === "json" ? "null" : "Entity not found.";
+  }
+  switch (format) {
+    case "json":
+      return JSON.stringify(entity, null, 2);
+    case "table": {
+      const lines = [
+        `${chalk.bold("Name:")} ${entity.name}`,
+        `${chalk.bold("Type:")} ${entity.entityType}`,
+        `${chalk.bold("Importance:")} ${entity.importance ?? "N/A"}`,
+        `${chalk.bold("Tags:")} ${(entity.tags || []).join(", ") || "None"}`,
+        `${chalk.bold("Parent:")} ${entity.parentId || "None"}`,
+        `${chalk.bold("Created:")} ${entity.createdAt || "N/A"}`,
+        `${chalk.bold("Modified:")} ${entity.lastModified || "N/A"}`,
+        "",
+        chalk.bold("Observations:"),
+        ...(entity.observations || []).map((o, i) => `  ${i + 1}. ${o}`)
+      ];
+      return lines.join("\n");
+    }
+    case "csv": {
+      const header = "field,value";
+      const rows = [
+        `name,${escapeCSV(entity.name)}`,
+        `entityType,${escapeCSV(entity.entityType)}`,
+        `importance,${entity.importance ?? ""}`,
+        `tags,${escapeCSV((entity.tags || []).join("; "))}`,
+        `parentId,${escapeCSV(entity.parentId || "")}`,
+        `observations,${escapeCSV((entity.observations || []).join("; "))}`
+      ];
+      return [header, ...rows].join("\n");
+    }
+  }
+}
+function formatSuccess(message) {
+  return chalk.green("\u2713") + " " + message;
+}
+function formatError(message) {
+  return chalk.red("\u2717") + " " + message;
+}
+function formatPath(result, format) {
+  switch (format) {
+    case "json":
+      return JSON.stringify(result, null, 2);
+    case "csv": {
+      const header = "step,entity";
+      const rows = result.path.map((name, i) => `${i},${escapeCSV(name)}`);
+      return [header, ...rows].join("\n");
+    }
+    default: {
+      const lines = [
+        `${chalk.bold("Path")} (${result.length} hops):`,
+        result.path.join(" \u2192 ")
+      ];
+      if (result.relations.length > 0) {
+        lines.push("", chalk.bold("Relations:"));
+        for (const rel of result.relations) {
+          lines.push(`  ${rel.from} --[${rel.relationType}]--> ${rel.to}`);
         }
-      } else {
-        console.log(chalk2.yellow(`No path found between "${pathFrom}" and "${pathTo}"`));
       }
-      break;
+      return lines.join("\n");
+    }
+  }
+}
+function formatCentrality(result, format) {
+  switch (format) {
+    case "json":
+      return JSON.stringify(
+        { algorithm: result.algorithm, topEntities: result.topEntities },
+        null,
+        2
+      );
+    case "csv": {
+      const header = "rank,name,score";
+      const rows = result.topEntities.map(
+        (e, i) => `${i + 1},${escapeCSV(e.name)},${e.score.toFixed(4)}`
+      );
+      return [header, ...rows].join("\n");
+    }
+    default: {
+      const table = new Table({
+        head: [chalk.cyan("Rank"), chalk.cyan("Entity"), chalk.cyan("Score")],
+        colWidths: calculateColWidths(getTerminalWidth(), [0.1, 0.6, 0.3])
+      });
+      result.topEntities.forEach((e, i) => {
+        table.push([String(i + 1), e.name, e.score.toFixed(4)]);
+      });
+      return `${chalk.bold(`Centrality (${result.algorithm})`)}
+${table.toString()}`;
+    }
+  }
+}
+function formatComponents(result, format) {
+  switch (format) {
+    case "json":
+      return JSON.stringify(result, null, 2);
+    case "csv": {
+      const header = "component,size,entities";
+      const rows = result.components.map(
+        (comp, i) => `${i + 1},${comp.length},${escapeCSV(comp.join("; "))}`
+      );
+      return [header, ...rows].join("\n");
     }
-    case "observe": {
-      const obsEntity = args[0];
-      const obsText = args.slice(1).join(" ");
-      if (!obsEntity || !obsText) {
-        console.log(chalk2.yellow("Usage: observe <entity> <observation text>"));
-        break;
-      }
-      await ctx.observationManager.addObservations([{
-        entityName: obsEntity,
-        contents: [obsText]
-      }]);
-      console.log(chalk2.green(`Added observation to ${obsEntity}`));
-      break;
+    default: {
+      const lines = [
+        `${chalk.bold("Connected Components")}: ${result.count} found`,
+        `Largest component size: ${result.largestComponentSize}`,
+        ""
+      ];
+      result.components.forEach((comp, i) => {
+        lines.push(`  Component ${i + 1} (${comp.length} nodes): ${comp.join(", ")}`);
+      });
+      return lines.join("\n");
     }
-    case "delete": {
-      const delName = args.join(" ");
-      if (!delName) {
-        console.log(chalk2.yellow("Usage: delete <entity-name>"));
-        break;
+  }
+}
+function formatValidation(result, format) {
+  switch (format) {
+    case "json":
+      return JSON.stringify(result, null, 2);
+    case "csv": {
+      const header = "type,message";
+      const rows = [];
+      for (const issue of result.issues) {
+        rows.push(`error,${escapeCSV(issue.message)}`);
       }
-      await ctx.entityManager.deleteEntities([delName]);
-      console.log(chalk2.green(`Deleted entity: ${delName}`));
-      break;
+      for (const warn of result.warnings) {
+        rows.push(`warning,${escapeCSV(warn.message)}`);
+      }
+      return [header, ...rows].join("\n");
     }
-    case "export": {
-      const validFormats = ["json", "csv", "graphml", "gexf", "dot", "markdown", "mermaid", "turtle", "rdf-xml", "json-ld"];
-      const fmt = args[0] || "json";
-      if (!validFormats.includes(fmt)) {
-        console.log(chalk2.yellow(`Invalid format: ${fmt}. Use: ${validFormats.join(", ")}`));
-        break;
+    default: {
+      const status = result.isValid ? chalk.green("\u2713 Valid") : chalk.red("\u2717 Invalid");
+      const lines = [
+        `${chalk.bold("Graph Validation")} \u2014 ${status}`,
+        `Errors: ${result.summary.totalErrors}  Warnings: ${result.summary.totalWarnings}`
+      ];
+      for (const issue of result.issues) {
+        lines.push(`  ${chalk.red("ERROR")}: ${issue.message}`);
       }
-      const exportGraph = await ctx.storage.loadGraph();
-      const output = ctx.ioManager.exportGraph(exportGraph, fmt);
-      console.log(output);
-      break;
+      for (const warn of result.warnings) {
+        lines.push(`  ${chalk.yellow("WARN")}: ${warn.message}`);
+      }
+      return lines.join("\n");
     }
-    case "history":
-      console.log("\nCommand history:");
-      ictx.history.slice(-20).forEach((cmd, i) => {
-        console.log(`  ${i + 1}. ${cmd}`);
-      });
-      break;
-    default:
-      console.log(chalk2.yellow(`Unknown command: ${command}. Type "help" for available commands.`));
   }
 }
-function showHelp() {
-  console.log(`
-${chalk2.green("Available Commands:")}
-
-  ${chalk2.cyan("entities")} / ${chalk2.cyan("ls")}    List all entities
-  ${chalk2.cyan("get <name>")}         Get entity details
-  ${chalk2.cyan("search <query>")}     Search entities
-  ${chalk2.cyan("relations <name>")}   Show relations for entity
-  ${chalk2.cyan("tags <name>")}        Show tags for entity
-  ${chalk2.cyan("path <from> <to>")}   Find shortest path
-  ${chalk2.cyan("observe <e> <text>")} Add observation to entity
-  ${chalk2.cyan("delete <name>")}      Delete entity
-  ${chalk2.cyan("export [format]")}    Export graph to stdout
-  ${chalk2.cyan("stats")}              Show graph statistics
-  ${chalk2.cyan("history")}            Show command history
-  ${chalk2.cyan("clear")}              Clear screen
-  ${chalk2.cyan("help")}               Show this help
-  ${chalk2.cyan("exit")}               Exit interactive mode
-
-${chalk2.gray("Tab completion available for entity names.")}
-`);
+function calculateColWidths(totalWidth, ratios) {
+  const padding = 4;
+  const available = totalWidth - padding;
+  return ratios.map((r) => Math.max(10, Math.floor(available * r)));
 }
-var init_interactive = __esm({
-  "src/cli/interactive.ts"() {
+function escapeCSV(value) {
+  if (value.includes(",") || value.includes('"') || value.includes("\n")) {
+    return `"${value.replace(/"/g, '""')}"`;
+  }
+  return value;
+}
+var init_formatters2 = __esm({
+  "src/cli/formatters.ts"() {
     "use strict";
     init_esm_shims();
-    init_ManagerContext();
   }
 });
 
-// src/cli/index.ts
-init_esm_shims();
-import { Command as Command2 } from "commander";
-
-// src/cli/commands/index.ts
-init_esm_shims();
-
-// src/cli/commands/entity.ts
-init_esm_shims();
-
 // src/cli/commands/helpers.ts
-init_esm_shims();
-init_ManagerContext();
-
-// src/cli/options.ts
-init_esm_shims();
-var defaultOptions = {
-  storage: process.env.MEMORYJS_STORAGE_PATH || "./memory.jsonl",
-  format: process.env.MEMORYJS_OUTPUT_FORMAT || "json",
-  quiet: false,
-  verbose: false
-};
-function parseGlobalOptions(opts) {
-  const rawFormat = opts.outputFormat;
-  const format = rawFormat && ["json", "table", "csv"].includes(rawFormat) ? rawFormat : defaultOptions.format;
-  return {
-    storage: opts.storage || defaultOptions.storage,
-    format,
-    quiet: Boolean(opts.quiet),
-    verbose: Boolean(opts.verbose)
-  };
+function getOptions(program2) {
+  const cliOpts = program2.opts();
+  const configPath = findConfigFile();
+  const fileConfig = configPath ? loadConfig(configPath) : {};
+  return mergeConfig2(fileConfig, parseGlobalOptions(cliOpts));
 }
-function createLogger(options) {
+function createContext(options) {
+  return new ManagerContext(options.storage);
+}
+var init_helpers = __esm({
+  "src/cli/commands/helpers.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_ManagerContext();
+    init_options();
+    init_config();
+    init_formatters2();
+  }
+});
+
+// src/cli/commands/inspect.ts
+var inspect_exports = {};
+__export(inspect_exports, {
+  buildSizeReport: () => buildSizeReport,
+  buildTree: () => buildTree,
+  neighbors: () => neighbors,
+  registerInspectCommands: () => registerInspectCommands,
+  renderTreeAscii: () => renderTreeAscii,
+  snapshotEntity: () => snapshotEntity
+});
+import { promises as fs17 } from "fs";
+async function snapshotEntity(ctx, name) {
+  const graph = await ctx.storage.loadGraph();
+  const entity = ctx.storage.getEntityByName(name);
+  if (!entity) throw new Error(`entity not found: ${name}`);
+  const observations = await ctx.observationManager.getObservationsFor(name);
+  const outgoing = graph.relations.filter((r) => r.from === name).map((r) => ({ to: r.to, type: r.relationType }));
+  const incoming = graph.relations.filter((r) => r.to === name).map((r) => ({ from: r.from, type: r.relationType }));
+  const children = (await ctx.hierarchyManager.getChildren(name)).map((c) => c.name);
+  const ancestors = (await ctx.hierarchyManager.getAncestors(name)).map((a) => a.name);
   return {
-    info: (msg) => !options.quiet && console.log(msg),
-    debug: (msg) => options.verbose && console.log(`[DEBUG] ${msg}`),
-    error: (msg) => console.error(`[ERROR] ${msg}`),
-    warn: (msg) => !options.quiet && console.warn(`[WARN] ${msg}`)
+    name: entity.name,
+    entityType: entity.entityType,
+    observations,
+    tags: entity.tags,
+    importance: entity.importance,
+    createdAt: entity.createdAt,
+    lastModified: entity.lastModified,
+    parentId: entity.parentId,
+    children,
+    ancestors,
+    relations: { outgoing, incoming }
   };
 }
-
-// src/cli/config.ts
-init_esm_shims();
-import { existsSync as existsSync2, readFileSync } from "fs";
-import { resolve as resolve2, dirname as dirname8 } from "path";
-var CONFIG_FILES = [
-  ".memoryjsrc",
-  ".memoryjsrc.json",
-  "memoryjs.config.json"
-];
-function findConfigFile(startDir = process.cwd()) {
-  let currentDir = startDir;
-  const root = resolve2("/");
-  while (currentDir !== root) {
-    for (const filename of CONFIG_FILES) {
-      const configPath = resolve2(currentDir, filename);
-      if (existsSync2(configPath)) {
-        return configPath;
-      }
+async function buildTree(ctx, root) {
+  await ctx.storage.loadGraph();
+  const rootEntity = ctx.storage.getEntityByName(root);
+  if (!rootEntity) throw new Error(`entity not found: ${root}`);
+  async function walk(name) {
+    const entity = ctx.storage.getEntityByName(name);
+    const children = await ctx.hierarchyManager.getChildren(name);
+    const childNodes = [];
+    for (const c of children) {
+      childNodes.push(await walk(c.name));
     }
-    const parentDir = dirname8(currentDir);
-    if (parentDir === currentDir) break;
-    currentDir = parentDir;
+    return {
+      name,
+      entityType: entity?.entityType ?? "unknown",
+      children: childNodes
+    };
   }
-  return null;
+  return walk(root);
 }
-function loadConfig(configPath) {
-  try {
-    const content = readFileSync(configPath, "utf-8");
-    const config = JSON.parse(content);
-    return validateConfig2(config);
-  } catch (error) {
-    console.warn(`Warning: Failed to load config from ${configPath}`);
-    return {};
+function renderTreeAscii(node, prefix = "", isRoot = true, isLast = true) {
+  const connector = isRoot ? "" : isLast ? "\u2514\u2500\u2500 " : "\u251C\u2500\u2500 ";
+  let out = `${prefix}${connector}${node.name} (${node.entityType})
+`;
+  const childPrefix = isRoot ? "" : prefix + (isLast ? "    " : "\u2502   ");
+  for (let i = 0; i < node.children.length; i++) {
+    out += renderTreeAscii(node.children[i], childPrefix, false, i === node.children.length - 1);
   }
+  return out;
 }
-function validateConfig2(config) {
-  const validated = {};
-  if (typeof config.storage === "string") {
-    validated.storage = config.storage;
-  }
-  if (config.format && ["json", "table", "csv"].includes(config.format)) {
-    validated.format = config.format;
-  }
-  if (typeof config.quiet === "boolean") {
-    validated.quiet = config.quiet;
-  }
-  if (typeof config.verbose === "boolean") {
-    validated.verbose = config.verbose;
+async function buildSizeReport(ctx, storagePath) {
+  const graph = await ctx.storage.loadGraph();
+  let observationCount = 0;
+  const tagSet = /* @__PURE__ */ new Set();
+  for (const e of graph.entities) {
+    observationCount += e.observations.length;
+    if (e.tags) for (const t of e.tags) tagSet.add(t);
+  }
+  let exists = false;
+  let sizeBytes = 0;
+  let lineCount = 0;
+  try {
+    const stat = await fs17.stat(storagePath);
+    exists = true;
+    sizeBytes = stat.size;
+    if (sizeBytes > 0) {
+      const content = await fs17.readFile(storagePath, "utf8");
+      lineCount = content.split("\n").filter((l) => l.length > 0).length;
+    }
+  } catch {
   }
-  return validated;
-}
-function mergeConfig2(fileConfig, cliOptions) {
   return {
-    storage: cliOptions.storage ?? fileConfig.storage ?? "./memory.jsonl",
-    format: cliOptions.format ?? fileConfig.format ?? "json",
-    quiet: cliOptions.quiet ?? fileConfig.quiet ?? false,
-    verbose: cliOptions.verbose ?? fileConfig.verbose ?? false
+    graph: {
+      entities: graph.entities.length,
+      relations: graph.relations.length,
+      observations: observationCount,
+      distinctTags: tagSet.size,
+      avgObservationsPerEntity: graph.entities.length === 0 ? 0 : Number((observationCount / graph.entities.length).toFixed(2))
+    },
+    storage: {
+      path: storagePath,
+      exists,
+      sizeBytes,
+      lineCount
+    }
   };
 }
-
-// src/cli/formatters.ts
-init_esm_shims();
-import Table from "cli-table3";
-import chalk from "chalk";
-function getTerminalWidth() {
-  return process.stdout.columns || 80;
+async function neighbors(ctx, name) {
+  const graph = await ctx.storage.loadGraph();
+  const entity = ctx.storage.getEntityByName(name);
+  if (!entity) throw new Error(`entity not found: ${name}`);
+  const outgoing = graph.relations.filter((r) => r.from === name).map((r) => ({ to: r.to, type: r.relationType }));
+  const incoming = graph.relations.filter((r) => r.to === name).map((r) => ({ from: r.from, type: r.relationType }));
+  return {
+    entity: name,
+    outgoing,
+    incoming,
+    outDegree: outgoing.length,
+    inDegree: incoming.length
+  };
 }
-function formatEntities(entities, format) {
-  if (entities.length === 0) {
-    return format === "json" ? "[]" : "No entities found.";
-  }
-  switch (format) {
-    case "json":
-      return JSON.stringify(entities, null, 2);
-    case "table": {
-      const table = new Table({
-        head: [chalk.cyan("Name"), chalk.cyan("Type"), chalk.cyan("Observations"), chalk.cyan("Tags")],
-        colWidths: calculateColWidths(getTerminalWidth(), [0.25, 0.15, 0.4, 0.2]),
-        wordWrap: true
-      });
-      for (const entity of entities) {
-        table.push([
-          entity.name,
-          entity.entityType,
-          (entity.observations || []).slice(0, 3).join("; ") + (entity.observations && entity.observations.length > 3 ? "..." : ""),
-          (entity.tags || []).join(", ")
-        ]);
+function registerInspectCommands(program2) {
+  program2.command("show <entity>").description("Verbose snapshot of one entity (observations, relations in/out, tags, hierarchy, timestamps)").action(async (entity) => {
+    const options = getOptions(program2);
+    const logger2 = createLogger(options);
+    const ctx = createContext(options);
+    try {
+      const snap = await snapshotEntity(ctx, entity);
+      console.log(JSON.stringify(snap, null, 2));
+    } catch (e) {
+      logger2.error(formatError(e.message));
+      process.exit(1);
+    }
+  });
+  program2.command("tree [root]").description("Hierarchy tree from a root entity (or all roots when omitted)").option("--ascii", "Render as ASCII tree instead of JSON (overrides --output-format)").action(async (root, opts) => {
+    const options = getOptions(program2);
+    const logger2 = createLogger(options);
+    const ctx = createContext(options);
+    try {
+      let trees;
+      if (root) {
+        trees = [await buildTree(ctx, root)];
+      } else {
+        const roots = await ctx.hierarchyManager.getRootEntities();
+        trees = await Promise.all(roots.map((r) => buildTree(ctx, r.name)));
       }
-      return table.toString();
+      if (opts.ascii) {
+        for (const t of trees) {
+          process.stdout.write(renderTreeAscii(t));
+        }
+      } else {
+        console.log(JSON.stringify(trees, null, 2));
+      }
+    } catch (e) {
+      logger2.error(formatError(e.message));
+      process.exit(1);
     }
-    case "csv": {
-      const header = "name,entityType,observations,tags";
-      const rows = entities.map((e) => [
-        escapeCSV(e.name),
-        escapeCSV(e.entityType),
-        escapeCSV((e.observations || []).join("; ")),
-        escapeCSV((e.tags || []).join(", "))
-      ].join(","));
-      return [header, ...rows].join("\n");
+  });
+  program2.command("neighbors <entity>").description("Incoming + outgoing relations of one entity (with in/out degree counts)").action(async (entity) => {
+    const options = getOptions(program2);
+    const logger2 = createLogger(options);
+    const ctx = createContext(options);
+    try {
+      const report = await neighbors(ctx, entity);
+      console.log(JSON.stringify(report, null, 2));
+    } catch (e) {
+      logger2.error(formatError(e.message));
+      process.exit(1);
     }
-  }
+  });
+  program2.command("size").description("Graph size + storage footprint summary (entity/relation/observation counts, file bytes, line count)").action(async () => {
+    const options = getOptions(program2);
+    const logger2 = createLogger(options);
+    const ctx = createContext(options);
+    try {
+      const report = await buildSizeReport(ctx, options.storage);
+      console.log(JSON.stringify(report, null, 2));
+    } catch (e) {
+      logger2.error(formatError(e.message));
+      process.exit(1);
+    }
+  });
 }
-function formatRelations(relations, format) {
-  if (relations.length === 0) {
-    return format === "json" ? "[]" : "No relations found.";
+var init_inspect = __esm({
+  "src/cli/commands/inspect.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_helpers();
+    init_formatters2();
   }
-  switch (format) {
-    case "json":
-      return JSON.stringify(relations, null, 2);
-    case "table": {
-      const table = new Table({
-        head: [chalk.cyan("From"), chalk.cyan("Relation"), chalk.cyan("To")],
-        colWidths: calculateColWidths(getTerminalWidth(), [0.35, 0.3, 0.35])
-      });
-      for (const rel of relations) {
-        table.push([rel.from, rel.relationType, rel.to]);
-      }
-      return table.toString();
+});
+
+// src/cli/interactive.ts
+var interactive_exports = {};
+__export(interactive_exports, {
+  startInteractiveMode: () => startInteractiveMode
+});
+import * as readline from "readline";
+import chalk2 from "chalk";
+async function startInteractiveMode(options) {
+  const ctx = new ManagerContext(options.storage);
+  const interactiveCtx = {
+    ctx,
+    options,
+    history: []
+  };
+  const graph = await ctx.storage.loadGraph();
+  const entityNames = graph.entities.map((e) => e.name);
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    prompt: chalk2.cyan("memory> "),
+    completer: (line) => {
+      const completions = [
+        "entities",
+        "relations",
+        "search",
+        "get",
+        "stats",
+        "tags",
+        "path",
+        "observe",
+        "delete",
+        "export",
+        "help",
+        "exit",
+        "clear",
+        "history",
+        ...entityNames
+      ];
+      const hits = completions.filter((c) => c.toLowerCase().startsWith(line.toLowerCase()));
+      return [hits.length ? hits : completions, line];
     }
-    case "csv": {
-      const header = "from,relationType,to";
-      const rows = relations.map((r) => [
-        escapeCSV(r.from),
-        escapeCSV(r.relationType),
-        escapeCSV(r.to)
-      ].join(","));
-      return [header, ...rows].join("\n");
+  });
+  console.log(chalk2.green("MemoryJS Interactive Mode"));
+  console.log(chalk2.gray('Type "help" for commands, "exit" to quit.\n'));
+  rl.prompt();
+  rl.on("line", async (line) => {
+    const trimmed = line.trim();
+    if (!trimmed) {
+      rl.prompt();
+      return;
     }
-  }
+    interactiveCtx.history.push(trimmed);
+    try {
+      await processCommand(trimmed, interactiveCtx, rl);
+    } catch (error) {
+      console.error(chalk2.red(`Error: ${error.message}`));
+    }
+    rl.prompt();
+  });
+  rl.on("close", () => {
+    console.log(chalk2.gray("\nGoodbye!"));
+    process.exit(0);
+  });
 }
-function formatSearchResults(results, format) {
-  if (results.length === 0) {
-    return format === "json" ? "[]" : "No results found.";
-  }
-  switch (format) {
-    case "json":
-      return JSON.stringify(results, null, 2);
-    case "table": {
-      const table = new Table({
-        head: [chalk.cyan("Name"), chalk.cyan("Type"), chalk.cyan("Score"), chalk.cyan("Observations")],
-        colWidths: calculateColWidths(getTerminalWidth(), [0.25, 0.15, 0.1, 0.5]),
-        wordWrap: true
-      });
-      for (const result of results) {
-        table.push([
-          result.entity.name,
-          result.entity.entityType,
-          result.score !== void 0 ? result.score.toFixed(3) : "-",
-          (result.entity.observations || []).slice(0, 2).join("; ") + (result.entity.observations && result.entity.observations.length > 2 ? "..." : "")
-        ]);
+async function processCommand(input, ictx, rl) {
+  const [command, ...args] = input.split(/\s+/);
+  const ctx = ictx.ctx;
+  switch (command.toLowerCase()) {
+    case "help":
+    case ".help":
+      showHelp();
+      break;
+    case "exit":
+    case ".exit":
+    case "quit":
+      rl.close();
+      break;
+    case "clear":
+    case ".clear":
+      console.clear();
+      break;
+    case "entities":
+    case "ls": {
+      const graph = await ctx.storage.loadGraph();
+      const entities = graph.entities;
+      console.log(`
+Entities (${entities.length}):`);
+      for (const e of entities.slice(0, 20)) {
+        console.log(`  ${chalk2.cyan(e.name)} [${e.entityType}]`);
       }
-      return table.toString();
+      if (entities.length > 20) {
+        console.log(`  ... and ${entities.length - 20} more`);
+      }
+      break;
     }
-    case "csv": {
-      const header = "name,entityType,score,observations";
-      const rows = results.map((r) => [
-        escapeCSV(r.entity.name),
-        escapeCSV(r.entity.entityType),
-        r.score !== void 0 ? r.score.toFixed(3) : "",
-        escapeCSV((r.entity.observations || []).join("; "))
-      ].join(","));
-      return [header, ...rows].join("\n");
+    case "get": {
+      const name = args.join(" ");
+      if (!name) {
+        console.log(chalk2.yellow("Usage: get <entity-name>"));
+        break;
+      }
+      const entity = await ctx.entityManager.getEntity(name);
+      if (entity) {
+        console.log(JSON.stringify(entity, null, 2));
+      } else {
+        console.log(chalk2.yellow(`Entity not found: ${name}`));
+      }
+      break;
     }
-  }
-}
-function formatEntityDetail(entity, format) {
-  if (!entity) {
-    return format === "json" ? "null" : "Entity not found.";
-  }
-  switch (format) {
-    case "json":
-      return JSON.stringify(entity, null, 2);
-    case "table": {
-      const lines = [
-        `${chalk.bold("Name:")} ${entity.name}`,
-        `${chalk.bold("Type:")} ${entity.entityType}`,
-        `${chalk.bold("Importance:")} ${entity.importance ?? "N/A"}`,
-        `${chalk.bold("Tags:")} ${(entity.tags || []).join(", ") || "None"}`,
-        `${chalk.bold("Parent:")} ${entity.parentId || "None"}`,
-        `${chalk.bold("Created:")} ${entity.createdAt || "N/A"}`,
-        `${chalk.bold("Modified:")} ${entity.lastModified || "N/A"}`,
-        "",
-        chalk.bold("Observations:"),
-        ...(entity.observations || []).map((o, i) => `  ${i + 1}. ${o}`)
-      ];
-      return lines.join("\n");
+    case "search": {
+      const query = args.join(" ");
+      if (!query) {
+        console.log(chalk2.yellow("Usage: search <query>"));
+        break;
+      }
+      const result = await ctx.searchManager.searchNodes(query);
+      console.log(`
+Search results for "${query}":`);
+      for (const entity of result.entities.slice(0, 10)) {
+        console.log(`  ${chalk2.cyan(entity.name)} [${entity.entityType}]`);
+        if (entity.observations && entity.observations.length > 0) {
+          const preview = entity.observations[0].substring(0, 60);
+          console.log(`    ${chalk2.gray(preview)}${entity.observations[0].length > 60 ? "..." : ""}`);
+        }
+      }
+      if (result.entities.length > 10) {
+        console.log(`  ... and ${result.entities.length - 10} more`);
+      }
+      break;
+    }
+    case "relations": {
+      const name = args.join(" ");
+      if (!name) {
+        console.log(chalk2.yellow("Usage: relations <entity-name>"));
+        break;
+      }
+      const relations = await ctx.relationManager.getRelations(name);
+      if (relations.length === 0) {
+        console.log(chalk2.yellow(`No relations found for: ${name}`));
+        break;
+      }
+      console.log(`
+Relations for "${name}":`);
+      for (const rel of relations) {
+        if (rel.from === name) {
+          console.log(`  ${chalk2.cyan(name)} --[${rel.relationType}]--> ${rel.to}`);
+        } else {
+          console.log(`  ${rel.from} --[${rel.relationType}]--> ${chalk2.cyan(name)}`);
+        }
+      }
+      break;
     }
-    case "csv": {
-      const header = "field,value";
-      const rows = [
-        `name,${escapeCSV(entity.name)}`,
-        `entityType,${escapeCSV(entity.entityType)}`,
-        `importance,${entity.importance ?? ""}`,
-        `tags,${escapeCSV((entity.tags || []).join("; "))}`,
-        `parentId,${escapeCSV(entity.parentId || "")}`,
-        `observations,${escapeCSV((entity.observations || []).join("; "))}`
-      ];
-      return [header, ...rows].join("\n");
+    case "stats": {
+      const stats = await ctx.analyticsManager.getGraphStats();
+      console.log(`
+Knowledge Graph Statistics:`);
+      console.log(`  Entities: ${stats.totalEntities}`);
+      console.log(`  Relations: ${stats.totalRelations}`);
+      console.log(`  Entity Types: ${Object.keys(stats.entityTypesCounts).length}`);
+      console.log(`  Relation Types: ${Object.keys(stats.relationTypesCounts).length}`);
+      break;
     }
-  }
-}
-function formatSuccess(message) {
-  return chalk.green("\u2713") + " " + message;
-}
-function formatError(message) {
-  return chalk.red("\u2717") + " " + message;
-}
-function formatPath(result, format) {
-  switch (format) {
-    case "json":
-      return JSON.stringify(result, null, 2);
-    case "csv": {
-      const header = "step,entity";
-      const rows = result.path.map((name, i) => `${i},${escapeCSV(name)}`);
-      return [header, ...rows].join("\n");
+    case "tags": {
+      const tagName = args.join(" ");
+      if (!tagName) {
+        console.log(chalk2.yellow("Usage: tags <entity-name>"));
+        break;
+      }
+      const tagEntity = await ctx.entityManager.getEntity(tagName);
+      if (tagEntity) {
+        const tags = tagEntity.tags || [];
+        console.log(`
+Tags for "${tagName}": ${tags.length > 0 ? tags.join(", ") : "None"}`);
+      } else {
+        console.log(chalk2.yellow(`Entity not found: ${tagName}`));
+      }
+      break;
     }
-    default: {
-      const lines = [
-        `${chalk.bold("Path")} (${result.length} hops):`,
-        result.path.join(" \u2192 ")
-      ];
-      if (result.relations.length > 0) {
-        lines.push("", chalk.bold("Relations:"));
-        for (const rel of result.relations) {
-          lines.push(`  ${rel.from} --[${rel.relationType}]--> ${rel.to}`);
+    case "path": {
+      if (args.length < 2) {
+        console.log(chalk2.yellow("Usage: path <from> <to>"));
+        break;
+      }
+      const [pathFrom, pathTo] = args;
+      const pathResult = await ctx.graphTraversal.findShortestPath(pathFrom, pathTo);
+      if (pathResult) {
+        console.log(`
+Path (${pathResult.length} hops): ${pathResult.path.join(" -> ")}`);
+        for (const rel of pathResult.relations) {
+          console.log(`  ${rel.from} --[${rel.relationType}]--> ${rel.to}`);
         }
+      } else {
+        console.log(chalk2.yellow(`No path found between "${pathFrom}" and "${pathTo}"`));
       }
-      return lines.join("\n");
+      break;
     }
-  }
-}
-function formatCentrality(result, format) {
-  switch (format) {
-    case "json":
-      return JSON.stringify(
-        { algorithm: result.algorithm, topEntities: result.topEntities },
-        null,
-        2
-      );
-    case "csv": {
-      const header = "rank,name,score";
-      const rows = result.topEntities.map(
-        (e, i) => `${i + 1},${escapeCSV(e.name)},${e.score.toFixed(4)}`
-      );
-      return [header, ...rows].join("\n");
+    case "observe": {
+      const obsEntity = args[0];
+      const obsText = args.slice(1).join(" ");
+      if (!obsEntity || !obsText) {
+        console.log(chalk2.yellow("Usage: observe <entity> <observation text>"));
+        break;
+      }
+      await ctx.observationManager.addObservations([{
+        entityName: obsEntity,
+        contents: [obsText]
+      }]);
+      console.log(chalk2.green(`Added observation to ${obsEntity}`));
+      break;
     }
-    default: {
-      const table = new Table({
-        head: [chalk.cyan("Rank"), chalk.cyan("Entity"), chalk.cyan("Score")],
-        colWidths: calculateColWidths(getTerminalWidth(), [0.1, 0.6, 0.3])
-      });
-      result.topEntities.forEach((e, i) => {
-        table.push([String(i + 1), e.name, e.score.toFixed(4)]);
-      });
-      return `${chalk.bold(`Centrality (${result.algorithm})`)}
-${table.toString()}`;
+    case "delete": {
+      const delName = args.join(" ");
+      if (!delName) {
+        console.log(chalk2.yellow("Usage: delete <entity-name>"));
+        break;
+      }
+      await ctx.entityManager.deleteEntities([delName]);
+      console.log(chalk2.green(`Deleted entity: ${delName}`));
+      break;
     }
-  }
-}
-function formatComponents(result, format) {
-  switch (format) {
-    case "json":
-      return JSON.stringify(result, null, 2);
-    case "csv": {
-      const header = "component,size,entities";
-      const rows = result.components.map(
-        (comp, i) => `${i + 1},${comp.length},${escapeCSV(comp.join("; "))}`
-      );
-      return [header, ...rows].join("\n");
+    case "export": {
+      const validFormats = ["json", "csv", "graphml", "gexf", "dot", "markdown", "mermaid", "turtle", "rdf-xml", "json-ld"];
+      const fmt = args[0] || "json";
+      if (!validFormats.includes(fmt)) {
+        console.log(chalk2.yellow(`Invalid format: ${fmt}. Use: ${validFormats.join(", ")}`));
+        break;
+      }
+      const exportGraph = await ctx.storage.loadGraph();
+      const output = ctx.ioManager.exportGraph(exportGraph, fmt);
+      console.log(output);
+      break;
     }
-    default: {
-      const lines = [
-        `${chalk.bold("Connected Components")}: ${result.count} found`,
-        `Largest component size: ${result.largestComponentSize}`,
-        ""
-      ];
-      result.components.forEach((comp, i) => {
-        lines.push(`  Component ${i + 1} (${comp.length} nodes): ${comp.join(", ")}`);
+    case "history":
+      console.log("\nCommand history:");
+      ictx.history.slice(-20).forEach((cmd, i) => {
+        console.log(`  ${i + 1}. ${cmd}`);
       });
-      return lines.join("\n");
-    }
-  }
-}
-function formatValidation(result, format) {
-  switch (format) {
-    case "json":
-      return JSON.stringify(result, null, 2);
-    case "csv": {
-      const header = "type,message";
-      const rows = [];
-      for (const issue of result.issues) {
-        rows.push(`error,${escapeCSV(issue.message)}`);
+      break;
+    case "show": {
+      const name = args.join(" ");
+      if (!name) {
+        console.log(chalk2.yellow("Usage: show <entity-name>"));
+        break;
       }
-      for (const warn of result.warnings) {
-        rows.push(`warning,${escapeCSV(warn.message)}`);
+      const { snapshotEntity: snapshotEntity2 } = await Promise.resolve().then(() => (init_inspect(), inspect_exports));
+      try {
+        const snap = await snapshotEntity2(ctx, name);
+        console.log(JSON.stringify(snap, null, 2));
+      } catch (e) {
+        console.log(chalk2.yellow(e.message));
       }
-      return [header, ...rows].join("\n");
+      break;
     }
-    default: {
-      const status = result.isValid ? chalk.green("\u2713 Valid") : chalk.red("\u2717 Invalid");
-      const lines = [
-        `${chalk.bold("Graph Validation")} \u2014 ${status}`,
-        `Errors: ${result.summary.totalErrors}  Warnings: ${result.summary.totalWarnings}`
-      ];
-      for (const issue of result.issues) {
-        lines.push(`  ${chalk.red("ERROR")}: ${issue.message}`);
+    case "tree": {
+      const root = args[0];
+      const { buildTree: buildTree2, renderTreeAscii: renderTreeAscii2 } = await Promise.resolve().then(() => (init_inspect(), inspect_exports));
+      try {
+        if (root) {
+          const t = await buildTree2(ctx, root);
+          process.stdout.write(renderTreeAscii2(t));
+        } else {
+          const roots = await ctx.hierarchyManager.getRootEntities();
+          for (const r of roots) {
+            const t = await buildTree2(ctx, r.name);
+            process.stdout.write(renderTreeAscii2(t));
+          }
+        }
+      } catch (e) {
+        console.log(chalk2.yellow(e.message));
       }
-      for (const warn of result.warnings) {
-        lines.push(`  ${chalk.yellow("WARN")}: ${warn.message}`);
+      break;
+    }
+    case "neighbors": {
+      const name = args.join(" ");
+      if (!name) {
+        console.log(chalk2.yellow("Usage: neighbors <entity-name>"));
+        break;
       }
-      return lines.join("\n");
+      const { neighbors: neighbors2 } = await Promise.resolve().then(() => (init_inspect(), inspect_exports));
+      try {
+        const report = await neighbors2(ctx, name);
+        console.log(JSON.stringify(report, null, 2));
+      } catch (e) {
+        console.log(chalk2.yellow(e.message));
+      }
+      break;
     }
+    case "diag":
+    case "health": {
+      const graph = await ctx.storage.loadGraph();
+      const names = new Set(graph.entities.map((e) => e.name));
+      const orphans = graph.relations.filter((r) => !names.has(r.from) || !names.has(r.to)).length;
+      const dupNames = graph.entities.length - names.size;
+      console.log(JSON.stringify({
+        entities: graph.entities.length,
+        relations: graph.relations.length,
+        orphan_relations: orphans,
+        duplicate_names: dupNames,
+        storage: ictx.options.storage
+      }, null, 2));
+      break;
+    }
+    case "size": {
+      const { buildSizeReport: buildSizeReport2 } = await Promise.resolve().then(() => (init_inspect(), inspect_exports));
+      const report = await buildSizeReport2(ctx, ictx.options.storage);
+      console.log(JSON.stringify(report, null, 2));
+      break;
+    }
+    default:
+      console.log(chalk2.yellow(`Unknown command: ${command}. Type "help" for available commands.`));
   }
 }
-function calculateColWidths(totalWidth, ratios) {
-  const padding = 4;
-  const available = totalWidth - padding;
-  return ratios.map((r) => Math.max(10, Math.floor(available * r)));
-}
-function escapeCSV(value) {
-  if (value.includes(",") || value.includes('"') || value.includes("\n")) {
-    return `"${value.replace(/"/g, '""')}"`;
-  }
-  return value;
-}
+function showHelp() {
+  console.log(`
+${chalk2.green("Available Commands:")}
 
-// src/cli/commands/helpers.ts
-function getOptions(program2) {
-  const cliOpts = program2.opts();
-  const configPath = findConfigFile();
-  const fileConfig = configPath ? loadConfig(configPath) : {};
-  return mergeConfig2(fileConfig, parseGlobalOptions(cliOpts));
-}
-function createContext(options) {
-  return new ManagerContext(options.storage);
+  ${chalk2.cyan("entities")} / ${chalk2.cyan("ls")}    List all entities
+  ${chalk2.cyan("get <name>")}         Get entity details
+  ${chalk2.cyan("search <query>")}     Search entities
+  ${chalk2.cyan("relations <name>")}   Show relations for entity
+  ${chalk2.cyan("tags <name>")}        Show tags for entity
+  ${chalk2.cyan("path <from> <to>")}   Find shortest path
+  ${chalk2.cyan("observe <e> <text>")} Add observation to entity
+  ${chalk2.cyan("delete <name>")}      Delete entity
+  ${chalk2.cyan("export [format]")}    Export graph to stdout
+  ${chalk2.cyan("stats")}              Show graph statistics
+  ${chalk2.cyan("show <name>")}        Verbose entity snapshot (obs + relations + hierarchy)
+  ${chalk2.cyan("tree [root]")}        ASCII hierarchy tree (all roots if omitted)
+  ${chalk2.cyan("neighbors <name>")}   Incoming + outgoing relations + degree counts
+  ${chalk2.cyan("diag")} / ${chalk2.cyan("health")}     Quick integrity summary
+  ${chalk2.cyan("size")}               Graph + storage footprint
+  ${chalk2.cyan("history")}            Show command history
+  ${chalk2.cyan("clear")}              Clear screen
+  ${chalk2.cyan("help")}               Show this help
+  ${chalk2.cyan("exit")}               Exit interactive mode
+
+${chalk2.gray("Tab completion available for entity names.")}
+`);
 }
+var init_interactive = __esm({
+  "src/cli/interactive.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_ManagerContext();
+  }
+});
+
+// src/cli/index.ts
+init_esm_shims();
+import { Command as Command2 } from "commander";
+
+// src/cli/commands/index.ts
+init_esm_shims();
 
 // src/cli/commands/entity.ts
+init_esm_shims();
+init_helpers();
+init_formatters2();
 function registerEntityCommands(program2) {
   const entity = program2.command("entity").description("Manage entities (create, read, update, delete)");
   entity.command("create <name>").description("Create a new entity").option("-t, --type <type>", "Entity type", "generic").option("-o, --observation <obs...>", "Observations to add").option("--tags <tags...>", "Tags to add").option("-i, --importance <n>", "Importance score (0-10)", parseFloat).action(async (name, opts) => {
@@ -35921,6 +36227,8 @@ function registerEntityCommands(program2) {
 
 // src/cli/commands/relation.ts
 init_esm_shims();
+init_helpers();
+init_formatters2();
 function registerRelationCommands(program2) {
   const relation = program2.command("relation").description("Manage relations between entities");
   relation.command("create <from> <type> <to>").description("Create a new relation").action(async (from, relationType, to) => {
@@ -35973,6 +36281,8 @@ function registerRelationCommands(program2) {
 
 // src/cli/commands/search.ts
 init_esm_shims();
+init_helpers();
+init_formatters2();
 function registerSearchCommands(program2) {
   program2.command("search <query>").description("Search entities and observations").option("-l, --limit <n>", "Limit results", parseInt, 10).option("-t, --type <type>", "Filter by entity type").option("--ranked", "Use TF-IDF/BM25 ranked search").option("--boolean", "Use boolean search (AND/OR/NOT)").option("--fuzzy", "Use fuzzy search").option("--threshold <n>", "Fuzzy search threshold (0-1)", parseFloat, 0.6).option("--suggest", "Get search suggestions instead of results").action(async (query, opts) => {
     const options = getOptions(program2);
@@ -36030,6 +36340,8 @@ function registerSearchCommands(program2) {
 
 // src/cli/commands/observation.ts
 init_esm_shims();
+init_helpers();
+init_formatters2();
 function registerObservationCommands(program2) {
   const observation = program2.command("observation").description("Manage entity observations");
   observation.command("add <entity> <text...>").description("Add observation(s) to an entity").action(async (entity, text) => {
@@ -36102,6 +36414,8 @@ function registerObservationCommands(program2) {
 
 // src/cli/commands/tag.ts
 init_esm_shims();
+init_helpers();
+init_formatters2();
 function registerTagCommands(program2) {
   const tag = program2.command("tag").description("Manage entity tags and aliases");
   tag.command("add <entity> <tags...>").description("Add tags to an entity").action(async (entity, tags) => {
@@ -36176,6 +36490,8 @@ function registerTagCommands(program2) {
 
 // src/cli/commands/hierarchy.ts
 init_esm_shims();
+init_helpers();
+init_formatters2();
 function registerHierarchyCommands(program2) {
   const hierarchy = program2.command("hierarchy").description("Manage entity hierarchy (parent/child relationships)");
   hierarchy.command("set-parent <entity> <parent>").description('Set parent of an entity (use "none" to remove)').action(async (entity, parent) => {
@@ -36247,6 +36563,8 @@ function registerHierarchyCommands(program2) {
 
 // src/cli/commands/graph.ts
 init_esm_shims();
+init_helpers();
+init_formatters2();
 function registerGraphCommands(program2) {
   const graph = program2.command("graph").description("Graph algorithms (shortest path, centrality, components)");
   graph.command("shortest-path <from> <to>").description("Find shortest path between two entities").action(async (from, to) => {
@@ -36317,10 +36635,12 @@ function registerGraphCommands(program2) {
 
 // src/cli/commands/io.ts
 init_esm_shims();
+init_helpers();
+init_formatters2();
+init_entityUtils();
 import { readFileSync as readFileSync2, writeFileSync } from "fs";
 import { resolve as resolve3 } from "path";
 import { Option } from "commander";
-init_entityUtils();
 var IMPORT_FORMATS = ["json", "csv", "graphml"];
 var EXPORT_FORMATS = ["json", "csv", "graphml", "gexf", "dot", "markdown", "mermaid", "turtle", "rdf-xml", "json-ld"];
 function registerIOCommands(program2) {
@@ -36370,6 +36690,8 @@ function registerIOCommands(program2) {
 
 // src/cli/commands/maintenance.ts
 init_esm_shims();
+init_helpers();
+init_formatters2();
 function registerMaintenanceCommands(program2) {
   program2.command("stats").description("Show knowledge graph statistics").action(async () => {
     const options = getOptions(program2);
@@ -36494,6 +36816,8 @@ Tags Used:     ${allTags.size}
 
 // src/cli/commands/exclusion.ts
 init_esm_shims();
+init_helpers();
+init_formatters2();
 function registerExclusionCommands(program2) {
   const exclude = program2.command("exclude").description("Manage do_not_remember exclusion rules");
   exclude.command("add <pattern>").description("Add an exclusion rule (substring match)").option("--scope <scope>", "Rule scope: 'future-only' | 'past-only' | 'both'", "both").option("--entity-type <type>", "Restrict to a single entity type").option("--reason <reason>", "Free-text justification").action(async (pattern2, opts) => {
@@ -36573,6 +36897,8 @@ function registerExclusionCommands(program2) {
 // src/cli/commands/decision.ts
 init_esm_shims();
 init_DecisionManager();
+init_helpers();
+init_formatters2();
 import { readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "fs";
 function registerDecisionCommands(program2) {
   const decision = program2.command("decision").description("Manage decision-rationale records (ADR-equivalent)");
@@ -36727,6 +37053,8 @@ function registerDecisionCommands(program2) {
 
 // src/cli/commands/projectContext.ts
 init_esm_shims();
+init_helpers();
+init_formatters2();
 function registerProjectContextCommands(program2) {
   const pc = program2.command("project-context").description("Manage structured per-project knowledge (facts/conventions/commands/glossary)");
   pc.command("show <projectId>").description("Show the project-context record as rendered prose").action(async (projectId) => {
@@ -36821,6 +37149,8 @@ function registerProjectContextCommands(program2) {
 
 // src/cli/commands/toolAffordance.ts
 init_esm_shims();
+init_helpers();
+init_formatters2();
 function registerToolAffordanceCommands(program2) {
   const ta = program2.command("tool-affordance").description("Inspect per-tool rolling outcome statistics");
   ta.command("list").description("List all tools with affordance records").action(async () => {
@@ -36899,7 +37229,8 @@ function registerToolAffordanceCommands(program2) {
 // src/cli/commands/smoke.ts
 init_esm_shims();
 init_ManagerContext();
-import { promises as fs17 } from "fs";
+init_formatters2();
+import { promises as fs18 } from "fs";
 import { join as join8 } from "path";
 import { tmpdir } from "os";
 import { performance } from "perf_hooks";
@@ -37221,7 +37552,7 @@ function registerSmokeCommand(program2) {
   program2.command("smoke").description("Run a per-category end-to-end smoke test (~30 ops) against a fresh temp graph").option("-s, --storage <path>", "Storage path for the smoke run (default: temp dir)").option("-k, --keep", "Preserve the smoke graph after the run and print its path (default: cleanup)").option("-v, --verbose", "Print each step as it runs (default: print summary only)").action(async (opts) => {
     const verbose = Boolean(opts.verbose);
     const keep = Boolean(opts.keep);
-    const storagePath = opts.storage ? opts.storage : await fs17.mkdtemp(join8(tmpdir(), "memoryjs-smoke-"));
+    const storagePath = opts.storage ? opts.storage : await fs18.mkdtemp(join8(tmpdir(), "memoryjs-smoke-"));
     const graphPath = opts.storage ? storagePath : join8(storagePath, "graph.jsonl");
     if (verbose) console.log(`Smoke storage: ${graphPath}`);
     const ctx = new ManagerContext(graphPath);
@@ -37235,7 +37566,7 @@ function registerSmokeCommand(program2) {
 Keeping smoke graph at: ${graphPath}`);
     } else if (!opts.storage) {
       try {
-        await fs17.rm(storagePath, { recursive: true, force: true });
+        await fs18.rm(storagePath, { recursive: true, force: true });
       } catch {
       }
     }
@@ -37244,6 +37575,555 @@ Keeping smoke graph at: ${graphPath}`);
   });
 }
 
+// src/cli/commands/diag.ts
+init_esm_shims();
+init_helpers();
+init_formatters2();
+import { promises as fs19 } from "fs";
+import { performance as performance2 } from "perf_hooks";
+import { readFileSync as readFileSync4 } from "fs";
+import { fileURLToPath as fileURLToPath3 } from "url";
+import { dirname as dirname9, join as join9 } from "path";
+var ENV_VAR_CATALOG = [
+  // Core
+  { name: "MEMORY_STORAGE_TYPE", defaultValue: "jsonl", description: "jsonl | sqlite \u2014 storage backend selector" },
+  { name: "MEMORY_FILE_PATH", defaultValue: "(repo default)", description: "Custom storage file path" },
+  { name: "SKIP_BENCHMARKS", defaultValue: "false", description: "Skip performance-benchmark tests" },
+  { name: "LOG_LEVEL", defaultValue: "(none)", description: "debug | info | warn | error" },
+  // Embeddings
+  { name: "MEMORY_EMBEDDING_PROVIDER", defaultValue: "local", description: "openai | local | none" },
+  { name: "MEMORY_OPENAI_API_KEY", defaultValue: "(unset)", description: "OpenAI API key (when provider=openai)" },
+  { name: "MEMORY_EMBEDDING_MODEL", defaultValue: "(provider default)", description: "Override embedding model name" },
+  { name: "MEMORY_AUTO_INDEX_EMBEDDINGS", defaultValue: "false", description: "Auto-index new entities for semantic search" },
+  // Read pool / coalescing
+  { name: "MEMORY_SQLITE_READ_POOL_SIZE", defaultValue: "4", description: "SQLite read-connection pool size" },
+  { name: "MEMORY_INDEX_COALESCE_MS", defaultValue: "50", description: "TF-IDF event-sync coalescing window (ms)" },
+  // Governance
+  { name: "MEMORY_GOVERNANCE_ENABLED", defaultValue: "false", description: "Enable governance policy enforcement" },
+  { name: "MEMORY_AUDIT_LOG_FILE", defaultValue: "(unset)", description: "Path for audit JSONL trail" },
+  { name: "MEMORY_FRESHNESS_TTL_DEFAULT_HOURS", defaultValue: "168", description: "Default freshness TTL (hours)" },
+  // Agent role + advanced
+  { name: "MEMORY_AGENT_ROLE", defaultValue: "(unset)", description: "researcher | planner | executor | reviewer | coordinator" },
+  { name: "MEMORY_ENTROPY_FILTER_ENABLED", defaultValue: "false", description: "Enable low-entropy observation filter" },
+  { name: "MEMORY_ENTROPY_THRESHOLD", defaultValue: "0.3", description: "Entropy filter threshold (0\u20131)" },
+  { name: "MEMORY_CONSOLIDATION_SCHEDULER_ENABLED", defaultValue: "false", description: "Enable background consolidation" },
+  { name: "MEMORY_CONSOLIDATION_INTERVAL_MS", defaultValue: "3600000", description: "Consolidation interval (ms)" },
+  { name: "MEMORY_DEFAULT_VISIBILITY", defaultValue: "private", description: "private | team | org | shared | public" },
+  // CLI-only
+  { name: "MEMORYJS_STORAGE_PATH", defaultValue: "./memory.jsonl", description: "CLI: default storage path" },
+  { name: "MEMORYJS_OUTPUT_FORMAT", defaultValue: "json", description: "CLI: json | table | csv" }
+];
+function readPackageVersion() {
+  try {
+    const here = dirname9(fileURLToPath3(import.meta.url));
+    for (const candidate of [
+      join9(here, "../../../package.json"),
+      join9(here, "../../package.json"),
+      join9(here, "../package.json")
+    ]) {
+      try {
+        const raw = readFileSync4(candidate, "utf8");
+        const pkg = JSON.parse(raw);
+        if (pkg.name === "@danielsimonjr/memoryjs" && pkg.version) return pkg.version;
+      } catch {
+      }
+    }
+  } catch {
+  }
+  return "unknown";
+}
+async function buildSnapshot(ctx, storagePath) {
+  let sizeBytes = 0;
+  let exists = false;
+  try {
+    const stat = await fs19.stat(storagePath);
+    exists = true;
+    sizeBytes = stat.size;
+  } catch {
+  }
+  const stats = await ctx.analyticsManager.getGraphStats();
+  return {
+    memoryjs: { version: readPackageVersion() },
+    runtime: {
+      node: process.version,
+      platform: process.platform,
+      arch: process.arch,
+      pid: process.pid
+    },
+    storage: {
+      path: storagePath,
+      type: process.env.MEMORY_STORAGE_TYPE ?? "jsonl",
+      exists,
+      sizeBytes,
+      entities: stats.totalEntities,
+      relations: stats.totalRelations
+    },
+    loadedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+async function runHealthChecks(ctx) {
+  const checks = [];
+  const t1 = performance2.now();
+  let graph;
+  try {
+    graph = await ctx.storage.loadGraph();
+    checks.push({ name: "storage:loadGraph", ok: true, durationMs: performance2.now() - t1 });
+  } catch (e) {
+    checks.push({
+      name: "storage:loadGraph",
+      ok: false,
+      durationMs: performance2.now() - t1,
+      detail: e instanceof Error ? e.message : String(e)
+    });
+    return checks;
+  }
+  const t2 = performance2.now();
+  const names = /* @__PURE__ */ new Set();
+  const dupes = [];
+  for (const e of graph.entities) {
+    if (names.has(e.name)) dupes.push(e.name);
+    else names.add(e.name);
+  }
+  checks.push({
+    name: "entities:distinct-names",
+    ok: dupes.length === 0,
+    durationMs: performance2.now() - t2,
+    detail: dupes.length === 0 ? void 0 : `duplicates: ${dupes.slice(0, 5).join(", ")}${dupes.length > 5 ? "\u2026" : ""}`
+  });
+  const t3 = performance2.now();
+  const orphans = [];
+  for (const r of graph.relations) {
+    if (!names.has(r.from)) orphans.push(`${r.from} \u2192 ${r.to} (from missing)`);
+    else if (!names.has(r.to)) orphans.push(`${r.from} \u2192 ${r.to} (to missing)`);
+  }
+  checks.push({
+    name: "relations:no-orphans",
+    ok: orphans.length === 0,
+    durationMs: performance2.now() - t3,
+    detail: orphans.length === 0 ? void 0 : `${orphans.length} orphan(s); first: ${orphans.slice(0, 3).join("; ")}`
+  });
+  const t4 = performance2.now();
+  const byName = /* @__PURE__ */ new Map();
+  for (const e of graph.entities) byName.set(e.name, e);
+  const cycleIssues = [];
+  for (const e of graph.entities) {
+    if (!e.parentId) continue;
+    const visited = /* @__PURE__ */ new Set();
+    let cur = byName.get(e.parentId);
+    while (cur && cur.parentId) {
+      if (visited.has(cur.name)) {
+        cycleIssues.push(`cycle through ${cur.name}`);
+        break;
+      }
+      visited.add(cur.name);
+      cur = byName.get(cur.parentId);
+    }
+    if (e.parentId && !byName.has(e.parentId)) {
+      cycleIssues.push(`${e.name}.parentId='${e.parentId}' missing`);
+    }
+  }
+  checks.push({
+    name: "hierarchy:no-cycles-no-missing-parents",
+    ok: cycleIssues.length === 0,
+    durationMs: performance2.now() - t4,
+    detail: cycleIssues.length === 0 ? void 0 : cycleIssues.slice(0, 3).join("; ")
+  });
+  return checks;
+}
+function registerDiagCommand(program2) {
+  program2.command("diag").description("One-shot diagnostic snapshot: memoryjs version, runtime, storage, env").action(async () => {
+    const options = getOptions(program2);
+    const logger2 = createLogger(options);
+    const ctx = createContext(options);
+    try {
+      const snapshot = await buildSnapshot(ctx, options.storage);
+      console.log(JSON.stringify(snapshot, null, 2));
+    } catch (e) {
+      logger2.error(formatError(e.message));
+      process.exit(1);
+    }
+  });
+  program2.command("env").description("Print all memoryjs env vars with documented defaults and resolved values").option("--all", "Include vars that are unset and have no documented default override").action(async (opts) => {
+    const showAll = Boolean(opts.all);
+    const rows = ENV_VAR_CATALOG.map((spec) => {
+      const current = process.env[spec.name];
+      return {
+        name: spec.name,
+        value: current ?? null,
+        default: spec.defaultValue,
+        set: current !== void 0,
+        description: spec.description
+      };
+    });
+    const filtered = showAll ? rows : rows.filter((r) => r.set || !r.default.startsWith("("));
+    console.log(JSON.stringify({ count: filtered.length, vars: filtered }, null, 2));
+  });
+  program2.command("health").description("Run fast integrity checks (graph loads, distinct names, no orphan relations, no hierarchy cycles)").action(async () => {
+    const options = getOptions(program2);
+    const logger2 = createLogger(options);
+    const ctx = createContext(options);
+    try {
+      const checks = await runHealthChecks(ctx);
+      const failed = checks.filter((c) => !c.ok).length;
+      const totalMs = checks.reduce((acc, c) => acc + c.durationMs, 0);
+      console.log(JSON.stringify({
+        ok: failed === 0,
+        failed,
+        totalChecks: checks.length,
+        totalMs: Number(totalMs.toFixed(2)),
+        checks
+      }, null, 2));
+      if (failed > 0) process.exit(1);
+    } catch (e) {
+      logger2.error(formatError(e.message));
+      process.exit(1);
+    }
+  });
+  program2.command("version").description("Compact version line: memoryjs, node, platform").action(() => {
+    console.log(JSON.stringify({
+      memoryjs: readPackageVersion(),
+      node: process.version,
+      platform: `${process.platform}/${process.arch}`
+    }));
+  });
+}
+
+// src/cli/commands/index.ts
+init_inspect();
+
+// src/cli/commands/heuristic.ts
+init_esm_shims();
+init_helpers();
+init_formatters2();
+function emitJson(payload) {
+  console.log(JSON.stringify(payload, null, 2));
+}
+function registerHeuristicCommands(program2) {
+  const h = program2.command("heuristic").description("Manage condition\u2192action heuristic guidelines (add, match, reinforce, conflicts)");
+  h.command("add <condition> <action>").description("Add a heuristic guideline. Returns the assigned id.").option("-p, --priority <n>", "Priority (numeric; higher wins ties)", parseFloat).option("-c, --confidence <n>", "Initial confidence 0\u20131", parseFloat).option("-i, --importance <n>", "Importance 0\u201310", parseFloat).option("-a, --agent-id <id>", "Owning agent ID").action(async (condition, action, opts) => {
+    const options = getOptions(program2);
+    const logger2 = createLogger(options);
+    const ctx = createContext(options);
+    try {
+      const id = await ctx.heuristicManager.add({
+        condition,
+        action,
+        priority: opts.priority,
+        initialConfidence: opts.confidence,
+        importance: opts.importance,
+        agentId: opts.agentId
+      });
+      emitJson({ id });
+    } catch (error) {
+      logger2.error(formatError(error.message));
+      process.exit(1);
+    }
+  });
+  h.command("list").description("List all heuristics").action(async () => {
+    const options = getOptions(program2);
+    const logger2 = createLogger(options);
+    const ctx = createContext(options);
+    try {
+      const heuristics = await ctx.heuristicManager.list();
+      emitJson({ heuristics, count: heuristics.length });
+    } catch (error) {
+      logger2.error(formatError(error.message));
+      process.exit(1);
+    }
+  });
+  h.command("count").description("Print the current heuristic count").action(async () => {
+    const options = getOptions(program2);
+    const logger2 = createLogger(options);
+    const ctx = createContext(options);
+    try {
+      const count = await ctx.heuristicManager.size();
+      emitJson({ count });
+    } catch (error) {
+      logger2.error(formatError(error.message));
+      process.exit(1);
+    }
+  });
+  h.command("get <id>").description("Get a heuristic by id").action(async (id) => {
+    const options = getOptions(program2);
+    const logger2 = createLogger(options);
+    const ctx = createContext(options);
+    try {
+      const heuristic = ctx.heuristicManager.get(id);
+      emitJson({ id, heuristic: heuristic ?? null });
+    } catch (error) {
+      logger2.error(formatError(error.message));
+      process.exit(1);
+    }
+  });
+  h.command("match <input...>").description("Match heuristics whose condition fits the given input").option("-l, --limit <n>", "Max matches to return", (v) => parseInt(v, 10)).option("-s, --min-score <n>", "Minimum match score 0\u20131", parseFloat).action(async (inputParts, opts) => {
+    const options = getOptions(program2);
+    const logger2 = createLogger(options);
+    const ctx = createContext(options);
+    const input = inputParts.join(" ");
+    try {
+      const matches2 = await ctx.heuristicManager.match(input, {
+        limit: opts.limit,
+        minScore: opts.minScore
+      });
+      emitJson({ input, matches: matches2, count: matches2.length });
+    } catch (error) {
+      logger2.error(formatError(error.message));
+      process.exit(1);
+    }
+  });
+  h.command("reinforce <id>").description("Reinforce a heuristic (bump confidence toward 1)").action(async (id) => {
+    const options = getOptions(program2);
+    const logger2 = createLogger(options);
+    const ctx = createContext(options);
+    try {
+      const result = await ctx.heuristicManager.reinforce(id);
+      emitJson({ id, result });
+    } catch (error) {
+      logger2.error(formatError(error.message));
+      process.exit(1);
+    }
+  });
+  h.command("contradict <id>").description("Record a contradiction (decreases confidence)").action(async (id) => {
+    const options = getOptions(program2);
+    const logger2 = createLogger(options);
+    const ctx = createContext(options);
+    try {
+      const result = await ctx.heuristicManager.recordContradiction(id);
+      emitJson({ id, result });
+    } catch (error) {
+      logger2.error(formatError(error.message));
+      process.exit(1);
+    }
+  });
+  h.command("conflicts").description("Detect heuristics with conflicting actions for similar conditions").action(async () => {
+    const options = getOptions(program2);
+    const logger2 = createLogger(options);
+    const ctx = createContext(options);
+    try {
+      const conflicts = await ctx.heuristicManager.detectConflicts();
+      emitJson({ conflicts, count: conflicts.length });
+    } catch (error) {
+      logger2.error(formatError(error.message));
+      process.exit(1);
+    }
+  });
+  h.command("remove <id>").description("Remove a heuristic by id").action(async (id) => {
+    const options = getOptions(program2);
+    const logger2 = createLogger(options);
+    const ctx = createContext(options);
+    try {
+      const removed = await ctx.heuristicManager.remove(id);
+      emitJson({ id, removed });
+    } catch (error) {
+      logger2.error(formatError(error.message));
+      process.exit(1);
+    }
+  });
+  h.command("clear").description("Remove all heuristics. Destructive; no --dry-run yet.").action(async () => {
+    const options = getOptions(program2);
+    const logger2 = createLogger(options);
+    const ctx = createContext(options);
+    try {
+      await ctx.heuristicManager.clear();
+      emitJson({ cleared: true });
+    } catch (error) {
+      logger2.error(formatError(error.message));
+      process.exit(1);
+    }
+  });
+}
+
+// src/cli/commands/observationDedup.ts
+init_esm_shims();
+init_helpers();
+init_formatters2();
+function buildFilter(opts) {
+  const filter = {};
+  const entityType = opts.entityType;
+  if (entityType) {
+    filter.entityType = entityType.includes(",") ? entityType.split(",").map((s) => s.trim()).filter(Boolean) : entityType;
+  }
+  if (typeof opts.projectId === "string") filter.projectId = opts.projectId;
+  if (typeof opts.sessionId === "string") filter.sessionId = opts.sessionId;
+  if (typeof opts.minOccurrences === "number" && opts.minOccurrences >= 2) {
+    filter.minOccurrences = opts.minOccurrences;
+  }
+  if (typeof opts.maxGroups === "number" && opts.maxGroups > 0) {
+    filter.maxGroups = opts.maxGroups;
+  }
+  return filter;
+}
+function emitJson2(payload) {
+  console.log(JSON.stringify(payload, null, 2));
+}
+function registerObservationDedupCommands(program2) {
+  const od = program2.command("obs-dedup").description("Cross-entity observation duplicate detection (exact and Jaccard similarity)");
+  od.command("find").description("Find observations that appear verbatim across multiple entities").option("--entity-type <type>", "Filter to one entityType (or comma-separated list)").option("--project-id <id>", "Filter to one projectId").option("--session-id <id>", "Filter to one sessionId").option("--min-occurrences <n>", "Minimum occurrences per group (\u22652)", (v) => parseInt(v, 10)).option("--max-groups <n>", "Maximum groups to return", (v) => parseInt(v, 10)).action(async (opts) => {
+    const options = getOptions(program2);
+    const logger2 = createLogger(options);
+    const ctx = createContext(options);
+    try {
+      const filter = buildFilter(opts);
+      const groups = await ctx.observationDedupManager.findDuplicateObservations(filter);
+      emitJson2({ filter, groups, count: groups.length });
+    } catch (error) {
+      logger2.error(formatError(error.message));
+      process.exit(1);
+    }
+  });
+  od.command("find-jaccard").description("Find near-duplicate observations across entities by Jaccard similarity").option("--entity-type <type>", "Filter to one entityType (or comma-separated list)").option("--project-id <id>", "Filter to one projectId").option("--session-id <id>", "Filter to one sessionId").option("--min-occurrences <n>", "Minimum occurrences per group (\u22652)", (v) => parseInt(v, 10)).option("--max-groups <n>", "Maximum groups to return", (v) => parseInt(v, 10)).action(async (opts) => {
+    const options = getOptions(program2);
+    const logger2 = createLogger(options);
+    const ctx = createContext(options);
+    try {
+      const filter = buildFilter(opts);
+      const groups = await ctx.observationDedupManager.findJaccardDuplicates(filter);
+      emitJson2({ filter, groups, count: groups.length });
+    } catch (error) {
+      logger2.error(formatError(error.message));
+      process.exit(1);
+    }
+  });
+}
+
+// src/cli/commands/spell.ts
+init_esm_shims();
+init_helpers();
+init_formatters2();
+function emitJson3(payload) {
+  console.log(JSON.stringify(payload, null, 2));
+}
+function registerSpellCommands(program2) {
+  const sp = program2.command("spell").description("Spell-suggest queries against the graph vocabulary");
+  sp.command("suggest <query>").description("Suggest corrections for a (possibly misspelled) query").option("-l, --limit <n>", "Max suggestions to return", (v) => parseInt(v, 10)).option("-s, --min-score <n>", "Minimum match score 0\u20131", parseFloat).option("-d, --max-distance <n>", "Maximum Levenshtein distance", parseFloat).action(async (query, opts) => {
+    const options = getOptions(program2);
+    const logger2 = createLogger(options);
+    const ctx = createContext(options);
+    try {
+      const suggestions = await ctx.spellChecker.suggest(query, {
+        limit: opts.limit,
+        minScore: opts.minScore,
+        maxDistance: opts.maxDistance
+      });
+      emitJson3({ query, suggestions, count: suggestions.length });
+    } catch (error) {
+      logger2.error(formatError(error.message));
+      process.exit(1);
+    }
+  });
+  sp.command("rebuild").description("Rebuild the spell-checker vocabulary index from the graph").action(async () => {
+    const options = getOptions(program2);
+    const logger2 = createLogger(options);
+    const ctx = createContext(options);
+    try {
+      await ctx.spellChecker.rebuild();
+      emitJson3({ rebuilt: true, vocabularySize: ctx.spellChecker.vocabularySize() });
+    } catch (error) {
+      logger2.error(formatError(error.message));
+      process.exit(1);
+    }
+  });
+  sp.command("size").description("Print the current vocabulary size").action(async () => {
+    const options = getOptions(program2);
+    const logger2 = createLogger(options);
+    const ctx = createContext(options);
+    try {
+      emitJson3({ vocabularySize: ctx.spellChecker.vocabularySize() });
+    } catch (error) {
+      logger2.error(formatError(error.message));
+      process.exit(1);
+    }
+  });
+}
+
+// src/cli/commands/check.ts
+init_esm_shims();
+init_helpers();
+init_formatters2();
+async function detectIssues(ctx) {
+  const graph = await ctx.storage.loadGraph();
+  const names = new Set(graph.entities.map((e) => e.name));
+  const orphans = [];
+  for (const r of graph.relations) {
+    const fromMissing = !names.has(r.from);
+    const toMissing = !names.has(r.to);
+    if (fromMissing || toMissing) {
+      orphans.push({
+        from: r.from,
+        to: r.to,
+        relationType: r.relationType,
+        reason: fromMissing && toMissing ? "both-missing" : fromMissing ? "from-missing" : "to-missing"
+      });
+    }
+  }
+  const missing = [];
+  const cycles = [];
+  const byName = /* @__PURE__ */ new Map();
+  for (const e of graph.entities) byName.set(e.name, { name: e.name, parentId: e.parentId });
+  for (const e of graph.entities) {
+    if (!e.parentId) continue;
+    if (!byName.has(e.parentId)) {
+      missing.push({ entity: e.name, parentId: e.parentId });
+      continue;
+    }
+    const visited = /* @__PURE__ */ new Set([e.name]);
+    let cur = byName.get(e.parentId);
+    while (cur && cur.parentId) {
+      if (visited.has(cur.name)) {
+        cycles.push({ entityInCycle: e.name, cycleThrough: cur.name });
+        break;
+      }
+      visited.add(cur.name);
+      cur = byName.get(cur.parentId);
+    }
+  }
+  return { orphans, missing, cycles };
+}
+async function applyFixes(ctx, orphans, missing) {
+  let deleted = 0;
+  let cleared = 0;
+  if (orphans.length > 0) {
+    await ctx.relationManager.deleteRelations(
+      orphans.map((o) => ({ from: o.from, to: o.to, relationType: o.relationType }))
+    );
+    deleted = orphans.length;
+  }
+  for (const m of missing) {
+    try {
+      await ctx.hierarchyManager.setEntityParent(m.entity, null);
+      cleared += 1;
+    } catch {
+    }
+  }
+  return { orphanRelationsDeleted: deleted, missingParentsCleared: cleared };
+}
+function registerCheckCommand(program2) {
+  program2.command("check").description("Detect orphan relations + missing parents + hierarchy cycles. Dry-run by default.").option("--apply", "Actually delete orphan relations + clear missing parentIds (cycles always left for human review)").action(async (opts) => {
+    const options = getOptions(program2);
+    const logger2 = createLogger(options);
+    const ctx = createContext(options);
+    try {
+      const { orphans, missing, cycles } = await detectIssues(ctx);
+      const ok = orphans.length === 0 && missing.length === 0 && cycles.length === 0;
+      const report = {
+        ok,
+        applied: Boolean(opts.apply),
+        orphanRelations: orphans,
+        missingParents: missing,
+        hierarchyCycles: cycles
+      };
+      if (opts.apply && (orphans.length > 0 || missing.length > 0)) {
+        report.actions = await applyFixes(ctx, orphans, missing);
+      }
+      console.log(JSON.stringify(report, null, 2));
+      if (!ok && !opts.apply) process.exit(1);
+    } catch (error) {
+      logger2.error(formatError(error.message));
+      process.exit(1);
+    }
+  });
+}
+
 // src/cli/commands/index.ts
 function registerCommands(program2) {
   registerEntityCommands(program2);
@@ -37260,14 +38140,20 @@ function registerCommands(program2) {
   registerProjectContextCommands(program2);
   registerToolAffordanceCommands(program2);
   registerSmokeCommand(program2);
+  registerDiagCommand(program2);
+  registerInspectCommands(program2);
+  registerHeuristicCommands(program2);
+  registerObservationDedupCommands(program2);
+  registerSpellCommands(program2);
+  registerCheckCommand(program2);
 }
 
 // src/cli/index.ts
 init_logger();
-import { readFileSync as readFileSync4 } from "fs";
+import { readFileSync as readFileSync5 } from "fs";
 import { createInterface as createInterface2 } from "readline";
-import { fileURLToPath as fileURLToPath3 } from "url";
-import { dirname as dirname9, join as join9 } from "path";
+import { fileURLToPath as fileURLToPath4 } from "url";
+import { dirname as dirname10, join as join10 } from "path";
 process.on("unhandledRejection", (reason) => {
   logger.error("Unhandled promise rejection:", reason);
 });
@@ -37276,10 +38162,10 @@ process.on("uncaughtException", (err) => {
 });
 function getVersion() {
   try {
-    const __filename2 = fileURLToPath3(import.meta.url);
-    const __dirname2 = dirname9(__filename2);
-    const pkgPath = join9(__dirname2, "..", "..", "package.json");
-    const pkg = JSON.parse(readFileSync4(pkgPath, "utf-8"));
+    const __filename2 = fileURLToPath4(import.meta.url);
+    const __dirname2 = dirname10(__filename2);
+    const pkgPath = join10(__dirname2, "..", "..", "package.json");
+    const pkg = JSON.parse(readFileSync5(pkgPath, "utf-8"));
     return pkg.version;
   } catch {
     return "0.0.0";