@danielsimonjr/memoryjs 2.2.0 → 2.3.0

package/README.md

@@ -1,6 +1,6 @@
 # MemoryJS
 
-[![Version](https://img.shields.io/badge/version-2.2.0-blue.svg)](https://github.com/danielsimonjr/memoryjs)
+[![Version](https://img.shields.io/badge/version-2.3.0-blue.svg)](https://github.com/danielsimonjr/memoryjs)
 [![NPM](https://img.shields.io/npm/v/@danielsimonjr/memoryjs.svg)](https://www.npmjs.com/package/@danielsimonjr/memoryjs)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)

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 {
       /**
@@ -37767,6 +37790,341 @@ function registerDiagCommand(program2) {
 
 // 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);
   registerRelationCommands(program2);
@@ -37784,6 +38142,10 @@ function registerCommands(program2) {
   registerSmokeCommand(program2);
   registerDiagCommand(program2);
   registerInspectCommands(program2);
+  registerHeuristicCommands(program2);
+  registerObservationDedupCommands(program2);
+  registerSpellCommands(program2);
+  registerCheckCommand(program2);
 }
 
 // src/cli/index.ts