claude-memory-layer 1.0.40 → 1.0.41

package/dist/services/memory-service.js

@@ -2765,6 +2765,127 @@ var SQLiteEventStore = class {
         updated_at TEXT DEFAULT (datetime('now'))
       );
 
+      -- Memory Operations: facet assignments (derived, rebuildable projection)
+      CREATE TABLE IF NOT EXISTS memory_facets (
+        id TEXT PRIMARY KEY,
+        target_type TEXT NOT NULL,
+        target_id TEXT NOT NULL,
+        dimension TEXT NOT NULL,
+        value TEXT NOT NULL,
+        confidence REAL NOT NULL DEFAULT 1.0,
+        source TEXT NOT NULL DEFAULT 'manual',
+        evidence_event_ids TEXT NOT NULL DEFAULT '[]',
+        project_hash TEXT NOT NULL DEFAULT '',
+        created_at TEXT NOT NULL,
+        updated_at TEXT NOT NULL,
+        UNIQUE(target_type, target_id, dimension, value, source, project_hash)
+      );
+
+      -- Memory Operations: operational action projection
+      CREATE TABLE IF NOT EXISTS memory_actions (
+        action_id TEXT PRIMARY KEY,
+        project_hash TEXT NOT NULL,
+        title TEXT NOT NULL,
+        status TEXT NOT NULL DEFAULT 'pending',
+        priority INTEGER NOT NULL DEFAULT 0,
+        source_event_ids TEXT NOT NULL DEFAULT '[]',
+        related_entity_ids TEXT NOT NULL DEFAULT '[]',
+        current_checkpoint_id TEXT,
+        lease_id TEXT,
+        created_at TEXT NOT NULL,
+        updated_at TEXT NOT NULL
+      );
+
+      -- Memory Operations: action dependency/reference edges
+      CREATE TABLE IF NOT EXISTS memory_action_edges (
+        edge_id TEXT PRIMARY KEY,
+        src_action_id TEXT NOT NULL,
+        rel_type TEXT NOT NULL,
+        dst_type TEXT NOT NULL,
+        dst_id TEXT NOT NULL,
+        confidence REAL NOT NULL DEFAULT 1.0,
+        source TEXT NOT NULL DEFAULT 'manual',
+        created_at TEXT NOT NULL,
+        UNIQUE(src_action_id, rel_type, dst_type, dst_id, source)
+      );
+
+      -- Memory Operations: short-lived leases for operational work
+      CREATE TABLE IF NOT EXISTS memory_leases (
+        lease_id TEXT PRIMARY KEY,
+        target_type TEXT NOT NULL,
+        target_id TEXT NOT NULL,
+        holder TEXT NOT NULL,
+        expires_at TEXT NOT NULL,
+        metadata_json TEXT,
+        created_at TEXT NOT NULL,
+        renewed_at TEXT,
+        released_at TEXT
+      );
+
+      -- Memory Operations: resumable checkpoints for delegated or long-running work
+      CREATE TABLE IF NOT EXISTS memory_checkpoints (
+        checkpoint_id TEXT PRIMARY KEY,
+        project_hash TEXT NOT NULL,
+        action_id TEXT,
+        session_id TEXT,
+        title TEXT NOT NULL,
+        summary TEXT NOT NULL,
+        state_json TEXT NOT NULL,
+        source_event_ids TEXT NOT NULL DEFAULT '[]',
+        created_at TEXT NOT NULL,
+        expires_at TEXT
+      );
+
+      -- Memory Operations: retention lifecycle score projection
+      CREATE TABLE IF NOT EXISTS memory_retention_scores (
+        score_id TEXT PRIMARY KEY,
+        target_type TEXT NOT NULL,
+        target_id TEXT NOT NULL,
+        project_hash TEXT NOT NULL,
+        policy_version TEXT NOT NULL,
+        decision TEXT NOT NULL,
+        lifecycle_score REAL NOT NULL,
+        factors_json TEXT NOT NULL,
+        reasons_json TEXT NOT NULL,
+        dry_run_diff_json TEXT NOT NULL,
+        source_event_ids TEXT NOT NULL DEFAULT '[]',
+        evaluated_at TEXT NOT NULL,
+        created_at TEXT NOT NULL,
+        updated_at TEXT NOT NULL,
+        UNIQUE(target_type, target_id, project_hash, policy_version)
+      );
+
+      -- Memory Operations: procedural lessons derived from successful workflows
+      CREATE TABLE IF NOT EXISTS memory_lessons (
+        lesson_id TEXT PRIMARY KEY,
+        project_hash TEXT NOT NULL DEFAULT '',
+        name TEXT NOT NULL,
+        trigger TEXT NOT NULL,
+        steps_json TEXT NOT NULL,
+        confidence REAL NOT NULL,
+        source_session_ids TEXT NOT NULL DEFAULT '[]',
+        source_event_ids TEXT NOT NULL DEFAULT '[]',
+        failure_modes_json TEXT NOT NULL DEFAULT '[]',
+        skill_candidate INTEGER NOT NULL DEFAULT 0,
+        created_at TEXT NOT NULL,
+        updated_at TEXT NOT NULL,
+        UNIQUE(project_hash, name)
+      );
+
+      -- Memory Operations: governance/audit trail for state-changing operations
+      CREATE TABLE IF NOT EXISTS memory_governance_audit (
+        audit_id TEXT PRIMARY KEY,
+        operation TEXT NOT NULL,
+        actor TEXT NOT NULL,
+        project_hash TEXT,
+        target_type TEXT NOT NULL,
+        target_id TEXT NOT NULL,
+        before_json TEXT,
+        after_json TEXT,
+        source_event_ids TEXT NOT NULL DEFAULT '[]',
+        created_at TEXT NOT NULL
+      );
+
       -- Create indexes
       CREATE INDEX IF NOT EXISTS idx_events_session ON events(session_id);
       CREATE INDEX IF NOT EXISTS idx_events_timestamp ON events(timestamp);
@@ -2791,6 +2912,23 @@ var SQLiteEventStore = class {
       CREATE INDEX IF NOT EXISTS idx_retrieval_traces_created_at ON retrieval_traces(created_at DESC);
       CREATE INDEX IF NOT EXISTS idx_retrieval_traces_project_hash ON retrieval_traces(project_hash);
       CREATE INDEX IF NOT EXISTS idx_retrieval_traces_session_id ON retrieval_traces(session_id);
+      CREATE INDEX IF NOT EXISTS idx_memory_facets_project_dimension_value ON memory_facets(project_hash, dimension, value);
+      CREATE INDEX IF NOT EXISTS idx_memory_facets_target ON memory_facets(target_type, target_id);
+      CREATE INDEX IF NOT EXISTS idx_memory_facets_dimension_value_confidence ON memory_facets(dimension, value, confidence DESC);
+      CREATE INDEX IF NOT EXISTS idx_memory_actions_project_status_priority ON memory_actions(project_hash, status, priority DESC, updated_at DESC);
+      CREATE INDEX IF NOT EXISTS idx_memory_action_edges_src ON memory_action_edges(src_action_id, rel_type);
+      CREATE INDEX IF NOT EXISTS idx_memory_action_edges_dst ON memory_action_edges(dst_type, dst_id);
+      CREATE INDEX IF NOT EXISTS idx_memory_leases_target_expires ON memory_leases(target_type, target_id, expires_at);
+      CREATE INDEX IF NOT EXISTS idx_memory_checkpoints_project_action_created ON memory_checkpoints(project_hash, action_id, created_at DESC);
+      CREATE INDEX IF NOT EXISTS idx_memory_checkpoints_project_session_created ON memory_checkpoints(project_hash, session_id, created_at DESC);
+      CREATE INDEX IF NOT EXISTS idx_memory_retention_scores_project_decision_score ON memory_retention_scores(project_hash, decision, lifecycle_score ASC, evaluated_at DESC);
+      CREATE INDEX IF NOT EXISTS idx_memory_retention_scores_target ON memory_retention_scores(target_type, target_id, project_hash);
+      CREATE INDEX IF NOT EXISTS idx_memory_retention_scores_policy_evaluated ON memory_retention_scores(policy_version, evaluated_at DESC);
+      CREATE INDEX IF NOT EXISTS idx_memory_lessons_project_confidence ON memory_lessons(project_hash, confidence DESC, updated_at DESC);
+      CREATE INDEX IF NOT EXISTS idx_memory_lessons_skill_candidate ON memory_lessons(project_hash, skill_candidate, confidence DESC);
+      CREATE INDEX IF NOT EXISTS idx_memory_lessons_updated ON memory_lessons(updated_at DESC);
+      CREATE INDEX IF NOT EXISTS idx_memory_governance_audit_project_operation ON memory_governance_audit(project_hash, operation, created_at DESC);
+      CREATE INDEX IF NOT EXISTS idx_memory_governance_audit_target ON memory_governance_audit(target_type, target_id, created_at DESC);
 
       -- FTS5 Full-Text Search for fast keyword search
       CREATE VIRTUAL TABLE IF NOT EXISTS events_fts USING fts5(
@@ -2813,6 +2951,48 @@ var SQLiteEventStore = class {
         INSERT INTO events_fts(rowid, content, event_id) VALUES (NEW.rowid, NEW.content, NEW.id);
       END;
     `);
+    try {
+      sqliteExec(this.db, `ALTER TABLE memory_action_edges ADD COLUMN source TEXT NOT NULL DEFAULT 'manual';`);
+    } catch {
+    }
+    try {
+      const edgeIndexes = sqliteAll(this.db, `PRAGMA index_list(memory_action_edges)`, []);
+      const hasSourceAwareUnique = edgeIndexes.some((index) => {
+        if (Number(index.unique) !== 1)
+          return false;
+        if (!/^[A-Za-z0-9_]+$/.test(index.name))
+          return false;
+        const escapedName = index.name.replace(/"/g, '""');
+        const columns = sqliteAll(this.db, 'PRAGMA index_info("' + escapedName + '")', []).map((column) => column.name);
+        return columns.length === 5 && columns[0] === "src_action_id" && columns[1] === "rel_type" && columns[2] === "dst_type" && columns[3] === "dst_id" && columns[4] === "source";
+      });
+      if (!hasSourceAwareUnique) {
+        sqliteExec(this.db, `
+          DROP TABLE IF EXISTS memory_action_edges_v2;
+          CREATE TABLE memory_action_edges_v2 (
+            edge_id TEXT PRIMARY KEY,
+            src_action_id TEXT NOT NULL,
+            rel_type TEXT NOT NULL,
+            dst_type TEXT NOT NULL,
+            dst_id TEXT NOT NULL,
+            confidence REAL NOT NULL DEFAULT 1.0,
+            source TEXT NOT NULL DEFAULT 'manual',
+            created_at TEXT NOT NULL,
+            UNIQUE(src_action_id, rel_type, dst_type, dst_id, source)
+          );
+          INSERT OR IGNORE INTO memory_action_edges_v2 (
+            edge_id, src_action_id, rel_type, dst_type, dst_id, confidence, source, created_at
+          )
+          SELECT edge_id, src_action_id, rel_type, dst_type, dst_id, confidence, source, created_at
+          FROM memory_action_edges;
+          DROP TABLE memory_action_edges;
+          ALTER TABLE memory_action_edges_v2 RENAME TO memory_action_edges;
+          CREATE INDEX IF NOT EXISTS idx_memory_action_edges_src ON memory_action_edges(src_action_id, rel_type);
+          CREATE INDEX IF NOT EXISTS idx_memory_action_edges_dst ON memory_action_edges(dst_type, dst_id);
+        `);
+      }
+    } catch {
+    }
     try {
       sqliteExec(this.db, `ALTER TABLE retrieval_traces ADD COLUMN selected_details_json TEXT;`);
     } catch {
@@ -4881,6 +5061,896 @@ var MemoryQueryService = class {
   }
 };
 
+// src/core/operations/facet-repository.ts
+import { randomUUID as randomUUID7 } from "crypto";
+
+// src/core/operations/facets.ts
+import { z } from "zod";
+var FacetTargetTypeSchema = z.enum([
+  "event",
+  "entity",
+  "edge",
+  "consolidated_memory",
+  "lesson",
+  "action"
+]);
+var BUILT_IN_FACET_DIMENSIONS = [
+  "kind",
+  "workflow",
+  "artifact",
+  "source",
+  "privacy",
+  "quality",
+  "retention",
+  "project"
+];
+var customDimensionPattern = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+var TrimmedStringSchema = z.preprocess(
+  (value) => typeof value === "string" ? value.trim() : value,
+  z.string().min(1)
+);
+var FacetDimensionSchema = z.preprocess(
+  (value) => typeof value === "string" ? value.trim() : value,
+  z.string().min(1).max(64).refine((value) => BUILT_IN_FACET_DIMENSIONS.indexOf(value) !== -1 || customDimensionPattern.test(value), {
+    message: "Facet dimension must be built-in or lowercase kebab-case"
+  })
+);
+var FacetSourceSchema = z.enum(["manual", "imported", "derived", "llm", "system"]).default("manual");
+var EvidenceEventIdsSchema = z.preprocess(
+  (value) => Array.isArray(value) ? value.map((item) => typeof item === "string" ? item.trim() : item).filter(Boolean) : value,
+  z.array(z.string().min(1)).default([])
+);
+var OptionalTrimmedStringSchema = z.preprocess(
+  (value) => typeof value === "string" ? value.trim() : value,
+  z.string().min(1).optional()
+);
+var MemoryFacetAssignmentInputSchema = z.object({
+  targetType: FacetTargetTypeSchema,
+  targetId: TrimmedStringSchema,
+  dimension: FacetDimensionSchema,
+  value: TrimmedStringSchema,
+  confidence: z.number().min(0).max(1).default(1),
+  source: FacetSourceSchema,
+  evidenceEventIds: EvidenceEventIdsSchema,
+  projectHash: OptionalTrimmedStringSchema,
+  actor: OptionalTrimmedStringSchema
+});
+var MemoryFacetAssignmentSchema = MemoryFacetAssignmentInputSchema.extend({
+  id: z.string().min(1),
+  createdAt: z.date(),
+  updatedAt: z.date()
+});
+var FacetRemoveInputSchema = z.object({
+  targetType: FacetTargetTypeSchema,
+  targetId: TrimmedStringSchema,
+  dimension: FacetDimensionSchema,
+  value: TrimmedStringSchema,
+  source: FacetSourceSchema,
+  projectHash: OptionalTrimmedStringSchema,
+  actor: OptionalTrimmedStringSchema
+});
+var FacetQuerySchema = z.object({
+  targetType: FacetTargetTypeSchema.optional(),
+  targetId: OptionalTrimmedStringSchema,
+  dimension: FacetDimensionSchema.optional(),
+  value: OptionalTrimmedStringSchema,
+  source: FacetSourceSchema.optional(),
+  projectHash: OptionalTrimmedStringSchema,
+  limit: z.number().int().positive().max(500).default(100)
+});
+function parseFacetAssignmentInput(input) {
+  return MemoryFacetAssignmentInputSchema.parse(input);
+}
+function parseFacetRemoveInput(input) {
+  return FacetRemoveInputSchema.parse(input);
+}
+function parseFacetQuery(input) {
+  return FacetQuerySchema.parse(input ?? {});
+}
+
+// src/core/operations/governance-audit.ts
+import { randomUUID as randomUUID6 } from "crypto";
+var MEMORY_GOVERNANCE_AUDIT_OPERATIONS = [
+  "facet_tag",
+  "action_update",
+  "lease_acquire",
+  "checkpoint_create",
+  "retention_score",
+  "quarantine",
+  "verify",
+  "lesson_promote"
+];
+function normalizeRequiredString(value, fieldName) {
+  const normalized = value.trim();
+  if (!normalized) {
+    throw new Error(`${fieldName} is required`);
+  }
+  return normalized;
+}
+function normalizeOptionalString(value) {
+  const normalized = value?.trim();
+  return normalized ? normalized : void 0;
+}
+var REDACTED = "[REDACTED]";
+var sensitiveKeyPattern = /(?:api[_-]?key|secret|password|passwd|token|access[_-]?token|client[_-]?secret|crtfc[_-]?key|hashkey|serviceKey)/i;
+var POSIX_ABSOLUTE_PATH_PATTERN = /(^|[^A-Za-z0-9._\/\\-])\/(?!\/)[^\n\r"'<>|`]*/g;
+var WINDOWS_DRIVE_PATH_PATTERN = /(^|[^A-Za-z0-9._\/\\-])(?:[A-Za-z]:[\\/][^\n\r"'<>|`]*)/g;
+var WINDOWS_UNC_PATH_PATTERN = /(^|[^A-Za-z0-9._\/\\-])(?:\\\\[^\\\n\r"'<>|`]+\\[^\n\r"'<>|`]*)/g;
+var credentialQueryPattern = /\b((?:api[_-]?key|token|access[_-]?token|client[_-]?secret|crtfc[_-]?key|hashkey|serviceKey)=)[^&\s`"'<>]+/gi;
+var credentialAssignmentPattern = /\b((?:api[_-]?key|secret|password|passwd|token|access[_-]?token|client[_-]?secret|crtfc[_-]?key|hashkey|serviceKey)\s*[:=]\s*)[^\s`"'<>},]+/gi;
+function redactAbsolutePaths(value) {
+  return value.replace(WINDOWS_UNC_PATH_PATTERN, (_match, prefix) => `${prefix}${REDACTED}`).replace(WINDOWS_DRIVE_PATH_PATTERN, (_match, prefix) => `${prefix}${REDACTED}`).replace(POSIX_ABSOLUTE_PATH_PATTERN, (_match, prefix) => `${prefix}${REDACTED}`);
+}
+function sanitizeAuditString(value) {
+  return redactAbsolutePaths(value).replace(credentialQueryPattern, `$1${REDACTED}`).replace(credentialAssignmentPattern, `$1${REDACTED}`);
+}
+function sanitizeGovernanceAuditValue(value, key) {
+  if (key && sensitiveKeyPattern.test(key)) {
+    return REDACTED;
+  }
+  if (typeof value === "string") {
+    return sanitizeAuditString(value);
+  }
+  if (value instanceof Date) {
+    return sanitizeAuditString(value.toISOString());
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => sanitizeGovernanceAuditValue(item));
+  }
+  if (value && typeof value === "object") {
+    const sanitized = {};
+    for (const [entryKey, entryValue] of Object.entries(value)) {
+      sanitized[sanitizeAuditString(entryKey)] = sanitizeGovernanceAuditValue(entryValue, entryKey);
+    }
+    return sanitized;
+  }
+  return value;
+}
+function sanitizeAuditJson(value) {
+  if (value === void 0)
+    return void 0;
+  return sanitizeGovernanceAuditValue(value);
+}
+function normalizeSourceEventIds(sourceEventIds) {
+  return (sourceEventIds || []).map((sourceEventId) => sanitizeAuditString(sourceEventId.trim())).filter((sourceEventId) => sourceEventId.length > 0);
+}
+function normalizeOperation(operation) {
+  if (MEMORY_GOVERNANCE_AUDIT_OPERATIONS.indexOf(operation) === -1) {
+    throw new Error(`Unsupported governance audit operation: ${operation}`);
+  }
+  return operation;
+}
+async function writeGovernanceAuditEntry(db, input) {
+  const entry = {
+    auditId: randomUUID6(),
+    operation: normalizeOperation(input.operation),
+    actor: sanitizeAuditString(normalizeRequiredString(input.actor, "actor")),
+    projectHash: normalizeOptionalString(input.projectHash),
+    targetType: normalizeRequiredString(input.targetType, "targetType"),
+    targetId: sanitizeAuditString(normalizeRequiredString(input.targetId, "targetId")),
+    beforeJson: sanitizeAuditJson(input.beforeJson),
+    afterJson: sanitizeAuditJson(input.afterJson),
+    sourceEventIds: normalizeSourceEventIds(input.sourceEventIds),
+    createdAt: /* @__PURE__ */ new Date()
+  };
+  sqliteRun(
+    db,
+    `INSERT INTO memory_governance_audit (
+      audit_id, operation, actor, project_hash, target_type, target_id,
+      before_json, after_json, source_event_ids, created_at
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    [
+      entry.auditId,
+      entry.operation,
+      entry.actor,
+      entry.projectHash ?? null,
+      entry.targetType,
+      entry.targetId,
+      entry.beforeJson === void 0 ? null : JSON.stringify(entry.beforeJson),
+      entry.afterJson === void 0 ? null : JSON.stringify(entry.afterJson),
+      JSON.stringify(entry.sourceEventIds),
+      entry.createdAt.toISOString()
+    ]
+  );
+  return entry;
+}
+
+// src/core/operations/facet-repository.ts
+function parseStringArray(value) {
+  if (typeof value !== "string")
+    return [];
+  try {
+    const parsed = JSON.parse(value);
+    if (!Array.isArray(parsed))
+      return [];
+    return parsed.filter((item) => typeof item === "string" && item.length > 0);
+  } catch {
+    return [];
+  }
+}
+function projectHashToStorage(projectHash) {
+  return projectHash ?? "";
+}
+function rowToFacet(row) {
+  const projectHash = typeof row.project_hash === "string" && row.project_hash.length > 0 ? row.project_hash : void 0;
+  return {
+    id: row.id,
+    targetType: FacetTargetTypeSchema.parse(row.target_type),
+    targetId: row.target_id,
+    dimension: row.dimension,
+    value: row.value,
+    confidence: Number(row.confidence),
+    source: FacetSourceSchema.parse(row.source),
+    evidenceEventIds: parseStringArray(row.evidence_event_ids),
+    projectHash,
+    createdAt: toDateFromSQLite(row.created_at),
+    updatedAt: toDateFromSQLite(row.updated_at)
+  };
+}
+function facetToAuditJson(facet) {
+  return {
+    id: facet.id,
+    targetType: facet.targetType,
+    targetId: facet.targetId,
+    dimension: facet.dimension,
+    value: facet.value,
+    confidence: facet.confidence,
+    source: facet.source,
+    evidenceEventIds: facet.evidenceEventIds,
+    projectHash: facet.projectHash,
+    createdAt: facet.createdAt.toISOString(),
+    updatedAt: facet.updatedAt.toISOString()
+  };
+}
+var FacetRepository = class {
+  constructor(db) {
+    this.db = db;
+  }
+  async assign(input) {
+    const assignment = parseFacetAssignmentInput(input);
+    const existing = this.findByUniqueKey(assignment);
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    if (existing) {
+      sqliteRun(
+        this.db,
+        `UPDATE memory_facets
+         SET confidence = ?, evidence_event_ids = ?, project_hash = ?, updated_at = ?
+         WHERE id = ?`,
+        [
+          assignment.confidence,
+          JSON.stringify(assignment.evidenceEventIds),
+          projectHashToStorage(assignment.projectHash),
+          now,
+          existing.id
+        ]
+      );
+      const saved2 = this.getById(existing.id);
+      await this.auditAssignment(assignment, existing, saved2);
+      return saved2;
+    }
+    const id = randomUUID7();
+    sqliteRun(
+      this.db,
+      `INSERT INTO memory_facets (
+        id, target_type, target_id, dimension, value, confidence, source,
+        evidence_event_ids, project_hash, created_at, updated_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      [
+        id,
+        assignment.targetType,
+        assignment.targetId,
+        assignment.dimension,
+        assignment.value,
+        assignment.confidence,
+        assignment.source,
+        JSON.stringify(assignment.evidenceEventIds),
+        projectHashToStorage(assignment.projectHash),
+        now,
+        now
+      ]
+    );
+    const saved = this.getById(id);
+    await this.auditAssignment(assignment, null, saved);
+    return saved;
+  }
+  async remove(input) {
+    const removeInput = parseFacetRemoveInput(input);
+    const { sql, params } = this.removeSql(removeInput);
+    const result = sqliteRun(this.db, sql, params);
+    return result.changes > 0;
+  }
+  async query(input) {
+    const query = parseFacetQuery(input);
+    const { sql, params } = this.querySql(query);
+    const rows = sqliteAll(this.db, sql, params);
+    return rows.map(rowToFacet);
+  }
+  async listForTarget(targetType, targetId) {
+    const parsedTargetType = FacetTargetTypeSchema.parse(targetType);
+    const trimmedTargetId = targetId.trim();
+    if (!trimmedTargetId) {
+      throw new Error("targetId is required");
+    }
+    return this.query({ targetType: parsedTargetType, targetId: trimmedTargetId, limit: 500 });
+  }
+  getById(id) {
+    const row = sqliteGet(this.db, `SELECT * FROM memory_facets WHERE id = ?`, [id]);
+    if (!row) {
+      throw new Error(`Memory facet not found after write: ${id}`);
+    }
+    return rowToFacet(row);
+  }
+  findByUniqueKey(input) {
+    const row = sqliteGet(
+      this.db,
+      `SELECT * FROM memory_facets
+       WHERE target_type = ? AND target_id = ? AND dimension = ? AND value = ? AND source = ? AND project_hash = ?`,
+      [
+        input.targetType,
+        input.targetId,
+        input.dimension,
+        input.value,
+        input.source,
+        projectHashToStorage(input.projectHash)
+      ]
+    );
+    return row ? rowToFacet(row) : null;
+  }
+  async auditAssignment(input, before, after) {
+    await writeGovernanceAuditEntry(this.db, {
+      operation: "facet_tag",
+      actor: input.actor ?? "cml-core",
+      projectHash: input.projectHash,
+      targetType: input.targetType,
+      targetId: input.targetId,
+      beforeJson: before ? facetToAuditJson(before) : void 0,
+      afterJson: facetToAuditJson(after),
+      sourceEventIds: input.evidenceEventIds
+    });
+  }
+  querySql(query) {
+    const clauses = [];
+    const params = [];
+    if (query.targetType) {
+      clauses.push("target_type = ?");
+      params.push(query.targetType);
+    }
+    if (query.targetId) {
+      clauses.push("target_id = ?");
+      params.push(query.targetId);
+    }
+    if (query.dimension) {
+      clauses.push("dimension = ?");
+      params.push(query.dimension);
+    }
+    if (query.value) {
+      clauses.push("value = ?");
+      params.push(query.value);
+    }
+    if (query.source) {
+      clauses.push("source = ?");
+      params.push(query.source);
+    }
+    if (query.projectHash) {
+      clauses.push("project_hash = ?");
+      params.push(query.projectHash);
+    }
+    const where = clauses.length > 0 ? `WHERE ${clauses.join(" AND ")}` : "";
+    params.push(query.limit);
+    return {
+      sql: `SELECT * FROM memory_facets ${where} ORDER BY confidence DESC, updated_at DESC LIMIT ?`,
+      params
+    };
+  }
+  removeSql(input) {
+    const clauses = [
+      "target_type = ?",
+      "target_id = ?",
+      "dimension = ?",
+      "value = ?",
+      "source = ?",
+      "project_hash = ?"
+    ];
+    const params = [
+      input.targetType,
+      input.targetId,
+      input.dimension,
+      input.value,
+      input.source,
+      projectHashToStorage(input.projectHash)
+    ];
+    return {
+      sql: `DELETE FROM memory_facets WHERE ${clauses.join(" AND ")}`,
+      params
+    };
+  }
+};
+
+// src/core/operations/graph-path-service.ts
+var DEFAULT_WEIGHT = 0.5;
+var MAX_HOPS = 2;
+var DEFAULT_MAX_RESULTS = 20;
+var MAX_RESULTS = 100;
+var GraphPathService = class {
+  constructor(db) {
+    this.db = db;
+  }
+  expand(input) {
+    const graph = this.loadGraph(input.direction ?? "both");
+    const effectiveMaxHops = normalizeMaxHops(input.maxHops);
+    const maxResults = normalizeMaxResults(input.maxResults);
+    const startNodes = input.startNodes.map((node) => graph.node(node));
+    const startKeys = new Set(input.startNodes.map(nodeKey));
+    const bestByTarget = /* @__PURE__ */ new Map();
+    const queue = startNodes.map((node) => ({
+      key: nodeKey(node),
+      hops: 0,
+      totalCost: 0,
+      steps: [],
+      visited: /* @__PURE__ */ new Set([nodeKey(node)])
+    }));
+    while (queue.length > 0) {
+      queue.sort((a, b) => a.totalCost - b.totalCost || a.hops - b.hops || a.key.localeCompare(b.key));
+      const current = queue.shift();
+      if (current.hops >= effectiveMaxHops)
+        continue;
+      for (const edge of graph.adjacency.get(current.key) ?? []) {
+        if (current.visited.has(edge.toKey))
+          continue;
+        const nextHops = current.hops + 1;
+        const nextTotalCost = current.totalCost + edge.step.cost;
+        const nextSteps = [...current.steps, edge.step];
+        const nextSignature = pathSignature(nextSteps);
+        const existing = bestByTarget.get(edge.toKey);
+        if (!existing || isBetterPath(nextTotalCost, nextHops, nextSignature, existing)) {
+          if (!startKeys.has(edge.toKey)) {
+            bestByTarget.set(edge.toKey, { hops: nextHops, totalCost: nextTotalCost, signature: nextSignature, steps: nextSteps });
+          }
+          const nextVisited = new Set(current.visited);
+          nextVisited.add(edge.toKey);
+          queue.push({
+            key: edge.toKey,
+            hops: nextHops,
+            totalCost: nextTotalCost,
+            steps: nextSteps,
+            visited: nextVisited
+          });
+        }
+      }
+    }
+    const paths = Array.from(bestByTarget.entries()).map(([key, path11]) => ({
+      target: graph.node(nodeFromKey(key)),
+      hops: path11.hops,
+      totalCost: path11.totalCost,
+      scoreContribution: path11.totalCost > 0 ? 1 / path11.totalCost : 0,
+      steps: path11.steps
+    })).sort((a, b) => b.scoreContribution - a.scoreContribution || a.hops - b.hops || a.target.name.localeCompare(b.target.name)).slice(0, maxResults);
+    return { startNodes, effectiveMaxHops, paths };
+  }
+  loadGraph(direction) {
+    const entityLabels = new Map(
+      sqliteAll(this.db, `SELECT entity_id, title FROM entities WHERE status = 'active'`).map((row) => [row.entity_id, row.title])
+    );
+    const labelNode = (node) => ({
+      ...node,
+      name: node.type === "entity" ? entityLabels.get(node.id) ?? node.id : node.id
+    });
+    const adjacency = /* @__PURE__ */ new Map();
+    const edges = sqliteAll(
+      this.db,
+      `SELECT edge_id, src_type, src_id, rel_type, dst_type, dst_id, meta_json FROM edges`
+    );
+    for (const edge of edges) {
+      const src = labelNode({ type: edge.src_type, id: edge.src_id });
+      const dst = labelNode({ type: edge.dst_type, id: edge.dst_id });
+      const weight = edgeWeight(edge.meta_json);
+      const cost = 1 / weight;
+      const baseStep = {
+        edgeId: edge.edge_id,
+        relationType: edge.rel_type,
+        from: src,
+        to: dst,
+        weight,
+        cost,
+        scoreContribution: weight
+      };
+      if (direction === "outgoing" || direction === "both") {
+        addTraversal(adjacency, nodeKey(src), {
+          toKey: nodeKey(dst),
+          step: { ...baseStep, direction: "outgoing" }
+        });
+      }
+      if (direction === "incoming" || direction === "both") {
+        addTraversal(adjacency, nodeKey(dst), {
+          toKey: nodeKey(src),
+          step: { ...baseStep, direction: "incoming" }
+        });
+      }
+    }
+    return { adjacency, node: labelNode };
+  }
+};
+function addTraversal(adjacency, fromKey, edge) {
+  const edges = adjacency.get(fromKey) ?? [];
+  edges.push(edge);
+  adjacency.set(fromKey, edges);
+}
+function normalizeMaxHops(maxHops) {
+  if (maxHops === void 0)
+    return 1;
+  if (!Number.isFinite(maxHops))
+    return MAX_HOPS;
+  return Math.min(Math.max(0, Math.trunc(maxHops)), MAX_HOPS);
+}
+function normalizeMaxResults(maxResults) {
+  if (maxResults === void 0)
+    return DEFAULT_MAX_RESULTS;
+  if (!Number.isFinite(maxResults))
+    return DEFAULT_MAX_RESULTS;
+  return Math.min(Math.max(0, Math.trunc(maxResults)), MAX_RESULTS);
+}
+function isBetterPath(totalCost, hops, signature, existing) {
+  return totalCost < existing.totalCost || totalCost === existing.totalCost && hops < existing.hops || totalCost === existing.totalCost && hops === existing.hops && signature < existing.signature;
+}
+function pathSignature(steps) {
+  return steps.map((step) => `${step.edgeId}:${step.direction}:${nodeKey(step.from)}>${nodeKey(step.to)}`).join("|");
+}
+function edgeWeight(metaJson) {
+  const meta = parseMeta(metaJson);
+  const raw = meta.weight;
+  if (typeof raw === "number" && Number.isFinite(raw) && raw > 0)
+    return raw;
+  if (typeof raw === "string") {
+    const parsed = Number(raw);
+    if (Number.isFinite(parsed) && parsed > 0)
+      return parsed;
+  }
+  return DEFAULT_WEIGHT;
+}
+function parseMeta(metaJson) {
+  if (!metaJson)
+    return {};
+  try {
+    const parsed = JSON.parse(metaJson);
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+function nodeKey(node) {
+  return `${node.type}:${node.id}`;
+}
+function nodeFromKey(key) {
+  const index = key.indexOf(":");
+  if (index === -1)
+    return { type: "entity", id: key };
+  return { type: key.slice(0, index), id: key.slice(index + 1) };
+}
+
+// src/core/operations/query-entity-extractor.ts
+var DEFAULT_MAX_CANDIDATES = 20;
+var MAX_CANDIDATES = 100;
+var MAX_CANDIDATE_TEXT_LENGTH = 200;
+var SOURCE_PRIORITY = {
+  entity_alias: 0,
+  quoted: 1,
+  file_path: 2,
+  package_identifier: 3,
+  capitalized_term: 4
+};
+var SOURCE_CONFIDENCE = {
+  entity_alias: 0.95,
+  quoted: 0.85,
+  file_path: 0.8,
+  package_identifier: 0.75,
+  capitalized_term: 0.6
+};
+var SENTENCE_START_STOPWORDS = /* @__PURE__ */ new Set([
+  "A",
+  "An",
+  "And",
+  "Are",
+  "Can",
+  "Compare",
+  "Does",
+  "Explain",
+  "Find",
+  "How",
+  "I",
+  "If",
+  "In",
+  "Is",
+  "List",
+  "Please",
+  "Should",
+  "Show",
+  "Tell",
+  "The",
+  "This",
+  "Use",
+  "What",
+  "When",
+  "Where",
+  "Which",
+  "Why",
+  "With"
+]);
+var QueryEntityExtractor = class {
+  constructor(db) {
+    this.db = db;
+  }
+  extract(query, options = {}) {
+    const maxCandidates = normalizeMaxCandidates(options.maxCandidates);
+    const candidates = [];
+    const quotedRanges = this.extractQuoted(query, candidates);
+    if (options.includeAliases !== false) {
+      this.extractKnownAliases(query, candidates);
+    }
+    this.extractFilePaths(query, candidates);
+    this.extractPackageIdentifiers(query, candidates);
+    this.extractCapitalizedTerms(query, candidates, quotedRanges);
+    return {
+      query,
+      candidates: dedupeAndSort(candidates).slice(0, maxCandidates).map(stripPriority)
+    };
+  }
+  extractQuoted(query, candidates) {
+    const ranges = [];
+    const regex = /(["'`])((?:(?!\1)[^\n]){2,200})\1/g;
+    let match;
+    while ((match = regex.exec(query)) !== null) {
+      const text = cleanCandidateText(match[2] ?? "");
+      if (!isUsefulCandidate(text))
+        continue;
+      const start = match.index + 1;
+      const end = start + text.length;
+      ranges.push([match.index, match.index + match[0].length]);
+      pushCandidate(candidates, {
+        text,
+        source: "quoted",
+        start,
+        end
+      });
+    }
+    return ranges;
+  }
+  extractKnownAliases(query, candidates) {
+    if (!this.db)
+      return;
+    const rows = sqliteAll(
+      this.db,
+      `SELECT
+         a.entity_id,
+         a.entity_type,
+         a.canonical_key AS alias_key,
+         e.canonical_key AS entity_canonical_key,
+         e.title
+       FROM entity_aliases a
+       JOIN entities e ON e.entity_id = a.entity_id
+       WHERE e.status = 'active'
+       ORDER BY e.title COLLATE NOCASE, a.canonical_key COLLATE NOCASE`
+    );
+    const normalizedQuery = normalizeForContainment(query);
+    const seenAliases = /* @__PURE__ */ new Set();
+    for (const row of rows) {
+      const aliasLabels = uniqueStrings([
+        row.title,
+        aliasLabelFromCanonicalKey(row.alias_key),
+        aliasLabelFromCanonicalKey(row.entity_canonical_key)
+      ]).filter(isUsefulCandidate);
+      for (const alias of aliasLabels) {
+        const normalizedAlias = normalizeForContainment(alias);
+        if (!normalizedAlias || !containsPhrase(normalizedQuery, normalizedAlias))
+          continue;
+        const aliasKey = `${row.entity_id}:${normalizedAlias}`;
+        if (seenAliases.has(aliasKey))
+          continue;
+        seenAliases.add(aliasKey);
+        const range = findRange(query, alias);
+        pushCandidate(candidates, {
+          text: row.title,
+          source: "entity_alias",
+          start: range.start,
+          end: range.end,
+          entityId: row.entity_id,
+          entityType: row.entity_type,
+          canonicalKey: row.entity_canonical_key,
+          matchedAlias: normalizedAlias
+        });
+      }
+    }
+  }
+  extractFilePaths(query, candidates) {
+    const regex = /(^|[\s([{<])((?:\.{1,2}\/|~\/|\/)?(?:[A-Za-z0-9_.-]+\/)+[A-Za-z0-9_.-]+\.[A-Za-z0-9][A-Za-z0-9._-]*)(?=$|[\s)\]},>`.,;:!?])/g;
+    let match;
+    while ((match = regex.exec(query)) !== null) {
+      const text = cleanCandidateText(match[2] ?? "");
+      if (!isUsefulCandidate(text))
+        continue;
+      const start = match.index + (match[1]?.length ?? 0);
+      pushCandidate(candidates, {
+        text,
+        source: "file_path",
+        start,
+        end: start + text.length
+      });
+    }
+  }
+  extractPackageIdentifiers(query, candidates) {
+    const regex = /(^|[\s([{<`])(@[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._-]*|[a-z0-9][a-z0-9._]*[-_][a-z0-9._-]*)(?=$|[\s)\]},>`.,;:!?])/gi;
+    let match;
+    while ((match = regex.exec(query)) !== null) {
+      const text = cleanCandidateText(match[2] ?? "");
+      if (!isUsefulCandidate(text) || text.includes("/.") || text.includes("./"))
+        continue;
+      const start = match.index + (match[1]?.length ?? 0);
+      pushCandidate(candidates, {
+        text,
+        source: "package_identifier",
+        start,
+        end: start + text.length
+      });
+    }
+  }
+  extractCapitalizedTerms(query, candidates, ignoredRanges) {
+    const tokens = collectCapitalizedTokens(query).filter((token) => !isInsideAnyRange(token.start, ignoredRanges)).filter((token) => !SENTENCE_START_STOPWORDS.has(token.text));
+    const groups = [];
+    let current = [];
+    for (const token of tokens) {
+      const previous = current[current.length - 1];
+      if (previous && query.slice(previous.end, token.start).match(/^\s+$/)) {
+        current.push(token);
+      } else {
+        if (current.length > 0)
+          groups.push(current);
+        current = [token];
+      }
+    }
+    if (current.length > 0)
+      groups.push(current);
+    for (const group of groups) {
+      if (group.length === 1 && !isStrongSingleCapitalized(group[0].text))
+        continue;
+      const start = group[0].start;
+      const end = group[group.length - 1].end;
+      const text = query.slice(start, end);
+      if (!isUsefulCandidate(text))
+        continue;
+      pushCandidate(candidates, {
+        text,
+        source: "capitalized_term",
+        start,
+        end
+      });
+    }
+  }
+};
+function collectCapitalizedTokens(query) {
+  const regex = /\b(?:[A-Z]{2,}[A-Z0-9]*|[A-Z][A-Za-z0-9]*(?:[._-][A-Za-z0-9]+)*)\b/g;
+  const tokens = [];
+  let match;
+  while ((match = regex.exec(query)) !== null) {
+    tokens.push({ text: match[0], start: match.index, end: match.index + match[0].length });
+  }
+  return tokens;
+}
+function pushCandidate(candidates, input) {
+  const text = cleanCandidateText(input.text);
+  if (!isUsefulCandidate(text))
+    return;
+  const source = input.source;
+  candidates.push({
+    ...input,
+    text,
+    normalized: normalizeCandidate(text),
+    confidence: input.confidence ?? SOURCE_CONFIDENCE[source],
+    priority: SOURCE_PRIORITY[source]
+  });
+}
+function dedupeAndSort(candidates) {
+  const sorted = [...candidates].sort(compareCandidates);
+  const seenAliasKeys = /* @__PURE__ */ new Set();
+  const seenNormalized = /* @__PURE__ */ new Set();
+  const result = [];
+  for (const candidate of sorted) {
+    if (candidate.source === "entity_alias") {
+      const aliasKey = `alias:${candidate.entityId ?? ""}:${normalizeCandidate(candidate.matchedAlias ?? candidate.text)}`;
+      if (seenAliasKeys.has(aliasKey))
+        continue;
+      seenAliasKeys.add(aliasKey);
+      seenNormalized.add(candidate.normalized);
+      result.push(candidate);
+      continue;
+    }
+    if (seenNormalized.has(candidate.normalized))
+      continue;
+    seenNormalized.add(candidate.normalized);
+    result.push(candidate);
+  }
+  return result.sort(compareCandidates);
+}
+function compareCandidates(a, b) {
+  return a.priority - b.priority || a.start - b.start || a.end - b.end || compareStrings(a.text, b.text) || compareStrings(a.entityId ?? "", b.entityId ?? "") || compareStrings(a.matchedAlias ?? "", b.matchedAlias ?? "");
+}
+function compareStrings(a, b) {
+  if (a === b)
+    return 0;
+  return a < b ? -1 : 1;
+}
+function stripPriority(candidate) {
+  const { priority: _priority, ...publicCandidate } = candidate;
+  return publicCandidate;
+}
+function normalizeMaxCandidates(maxCandidates) {
+  if (maxCandidates === void 0)
+    return DEFAULT_MAX_CANDIDATES;
+  if (!Number.isFinite(maxCandidates))
+    return DEFAULT_MAX_CANDIDATES;
+  return Math.min(Math.max(0, Math.trunc(maxCandidates)), MAX_CANDIDATES);
+}
+function cleanCandidateText(text) {
+  return text.normalize("NFKC").replace(/\s+/g, " ").trim().replace(/[.,;:!?]+$/g, "");
+}
+function normalizeCandidate(text) {
+  return cleanCandidateText(text).toLowerCase();
+}
+function normalizeForContainment(text) {
+  return text.normalize("NFKC").toLowerCase().replace(/[^\p{L}\p{N}@/._-]+/gu, " ").replace(/[._-]+/g, " ").replace(/\s+/g, " ").trim();
+}
+function containsPhrase(normalizedHaystack, normalizedNeedle) {
+  return ` ${normalizedHaystack} `.includes(` ${normalizedNeedle} `);
+}
+function aliasLabelFromCanonicalKey(canonicalKey) {
+  const raw = canonicalKey.includes(":") ? canonicalKey.slice(canonicalKey.lastIndexOf(":") + 1) : canonicalKey;
+  return raw.replace(/[._-]+/g, " ").replace(/\s+/g, " ").trim();
+}
+function findRange(query, alias) {
+  const normalizedAlias = normalizeForContainment(alias);
+  const directIndex = query.toLowerCase().indexOf(alias.toLowerCase());
+  if (directIndex >= 0)
+    return { start: directIndex, end: directIndex + alias.length };
+  const normalizedQuery = normalizeForContainment(query);
+  const normalizedIndex = normalizedQuery.indexOf(normalizedAlias);
+  if (normalizedIndex < 0)
+    return { start: 0, end: 0 };
+  const queryLower = query.toLowerCase();
+  const words = normalizedAlias.split(" ").filter(Boolean);
+  if (words.length === 0)
+    return { start: 0, end: 0 };
+  const first = queryLower.indexOf(words[0]);
+  const lastWord = words[words.length - 1];
+  const last = queryLower.indexOf(lastWord, first >= 0 ? first : 0);
+  if (first >= 0 && last >= 0)
+    return { start: first, end: last + lastWord.length };
+  return { start: normalizedIndex, end: normalizedIndex + normalizedAlias.length };
+}
+function isUsefulCandidate(text) {
+  const cleaned = cleanCandidateText(text);
+  return cleaned.length >= 2 && cleaned.length <= MAX_CANDIDATE_TEXT_LENGTH && /[\p{L}\p{N}]/u.test(cleaned);
+}
+function isInsideAnyRange(index, ranges) {
+  return ranges.some(([start, end]) => index >= start && index < end);
+}
+function isStrongSingleCapitalized(text) {
+  if (/^[A-Z]{2,}[A-Z0-9]*$/.test(text))
+    return true;
+  if (/^[A-Z][a-z]+[A-Z][A-Za-z0-9]*$/.test(text))
+    return true;
+  return text.length >= 4 && !SENTENCE_START_STOPWORDS.has(text);
+}
+function uniqueStrings(values) {
+  const seen = /* @__PURE__ */ new Set();
+  const result = [];
+  for (const value of values) {
+    const key = normalizeForContainment(value);
+    if (!key || seen.has(key))
+      continue;
+    seen.add(key);
+    result.push(value);
+  }
+  return result;
+}
+
 // src/core/retrieval-quality.ts
 var COMMAND_ARTIFACT_PATTERNS = [
   /<\/?(?:local-command-(?:stdout|stderr)|command-(?:name|message))\b/i,
@@ -5243,6 +6313,7 @@ var Retriever = class {
   sharedVectorStore;
   graduation;
   queryRewriter;
+  queryGraphExpansionEnabled;
   constructor(eventStore, vectorStore, embedder, matcher, sharedOptions) {
     this.eventStore = eventStore;
     this.vectorStore = vectorStore;
@@ -5250,6 +6321,7 @@ var Retriever = class {
     this.matcher = matcher;
     this.sharedStore = sharedOptions?.sharedStore;
     this.sharedVectorStore = sharedOptions?.sharedVectorStore;
+    this.queryGraphExpansionEnabled = sharedOptions?.queryGraphExpansionEnabled === true;
   }
   setGraduationPipeline(graduation) {
     this.graduation = graduation;
@@ -5295,7 +6367,8 @@ var Retriever = class {
       graphHop: opts.graphHop,
       projectScopeMode: opts.projectScopeMode,
       projectHash: opts.projectHash,
-      allowedProjectHashes: opts.allowedProjectHashes
+      allowedProjectHashes: opts.allowedProjectHashes,
+      facets: opts.facets
     });
     fallbackTrace.push(`stage:primary:${primaryStrategy}`);
     if (fallbackEnabled && this.shouldFallback(current.matchResult, current.results) && primaryStrategy !== "deep") {
@@ -5312,7 +6385,8 @@ var Retriever = class {
         graphHop: opts.graphHop,
         projectScopeMode: opts.projectScopeMode,
         projectHash: opts.projectHash,
-        allowedProjectHashes: opts.allowedProjectHashes
+        allowedProjectHashes: opts.allowedProjectHashes,
+        facets: opts.facets
       });
       fallbackTrace.push("fallback:deep");
     }
@@ -5330,7 +6404,8 @@ var Retriever = class {
         graphHop: opts.graphHop,
         projectScopeMode: opts.projectScopeMode,
         projectHash: opts.projectHash,
-        allowedProjectHashes: opts.allowedProjectHashes
+        allowedProjectHashes: opts.allowedProjectHashes,
+        facets: opts.facets
       });
       fallbackTrace.push("fallback:scope-expanded");
     }
@@ -5340,7 +6415,8 @@ var Retriever = class {
         scope: opts.scope,
         projectScopeMode: opts.projectScopeMode,
         projectHash: opts.projectHash,
-        allowedProjectHashes: opts.allowedProjectHashes
+        allowedProjectHashes: opts.allowedProjectHashes,
+        facets: opts.facets
       });
       const filteredSummary = this.applyQualityFilters(scopedSummary, {
         query,
@@ -5361,20 +6437,8 @@ var Retriever = class {
       totalTokens: this.estimateTokens(context),
       context,
       fallbackTrace,
-      selectedDebug: current.results.slice(0, opts.topK).map((r) => ({
-        eventId: r.eventId,
-        score: r.score,
-        semanticScore: r.semanticScore,
-        lexicalScore: r.lexicalScore,
-        recencyScore: r.recencyScore
-      })),
-      candidateDebug: (current.candidateResults || []).slice(0, Math.max(opts.topK * 3, 20)).map((r) => ({
-        eventId: r.eventId,
-        score: r.score,
-        semanticScore: r.semanticScore,
-        lexicalScore: r.lexicalScore,
-        recencyScore: r.recencyScore
-      })),
+      selectedDebug: current.results.slice(0, opts.topK).map((r) => this.debugDetailForResult(r)),
+      candidateDebug: (current.candidateResults || []).slice(0, Math.max(opts.topK * 3, 20)).map((r) => this.debugDetailForResult(r)),
       rawQueryText: current.queryRewriteKind ? query : void 0,
       effectiveQueryText: current.effectiveQueryText,
       queryRewriteKind: current.queryRewriteKind
@@ -5442,7 +6506,9 @@ var Retriever = class {
       }
     }
     const expandedResults = input.graphHop?.enabled === false ? initialResults : await this.expandGraphHops(initialResults, {
-      maxHops: Math.max(1, input.graphHop?.maxHops ?? 1),
+      query,
+      queryGraphEnabled: this.queryGraphExpansionEnabled,
+      maxHops: clampGraphHops(input.graphHop?.maxHops ?? 1),
       hopPenalty: Math.max(0, input.graphHop?.hopPenalty ?? 0.08),
       limit: input.topK * 4
     });
@@ -5451,7 +6517,8 @@ var Retriever = class {
       scope: input.scope,
       projectScopeMode: input.projectScopeMode,
       projectHash: input.projectHash,
-      allowedProjectHashes: input.allowedProjectHashes
+      allowedProjectHashes: input.allowedProjectHashes,
+      facets: input.facets
     });
     const qualityFiltered = this.applyQualityFilters(filtered, {
       query,
@@ -5466,9 +6533,13 @@ var Retriever = class {
     if (isCurrentStateQuery(options.query)) {
       filtered = filtered.filter((result) => !isStaleOrSupersededContent(result.content));
     }
-    filtered = filtered.filter((result) => hasDiscriminativeTermOverlap(options.query, result.content));
+    filtered = filtered.filter(
+      (result) => this.isGraphPathResult(result) || hasDiscriminativeTermOverlap(options.query, result.content)
+    );
     if (shouldApplyTechnicalGuard(options.query)) {
-      filtered = filtered.filter((result) => hasTechnicalTermOverlap(options.query, result.content));
+      filtered = filtered.filter(
+        (result) => this.isGraphPathResult(result) || hasTechnicalTermOverlap(options.query, result.content)
+      );
     }
     if (filtered.length <= 2)
       return filtered;
@@ -5531,7 +6602,61 @@ var Retriever = class {
       if (frontier.length === 0 || byId.size >= opts.limit)
         break;
     }
-    return [...byId.values()].sort((a, b) => b.score - a.score).slice(0, opts.limit);
+    if (opts.queryGraphEnabled) {
+      await this.expandQueryGraphPaths(opts.query, byId, opts);
+    }
+    return [...byId.values()].sort((a, b) => b.score - a.score || compareStable(a.eventId, b.eventId)).slice(0, opts.limit);
+  }
+  async expandQueryGraphPaths(query, byId, opts) {
+    if (!query.trim() || !this.eventStore.getDatabase)
+      return;
+    try {
+      const db = this.eventStore.getDatabase();
+      const extraction = new QueryEntityExtractor(db).extract(query, {
+        maxCandidates: Math.min(8, opts.limit),
+        includeAliases: true
+      });
+      const startCandidates = extraction.candidates.filter((candidate) => candidate.entityId).slice(0, 8);
+      const startNodes = uniqueEntityStartNodes(startCandidates);
+      if (startNodes.length === 0)
+        return;
+      const expansion = new GraphPathService(db).expand({
+        startNodes: startNodes.map((node) => ({ type: "entity", id: node.entityId })),
+        maxHops: opts.maxHops,
+        maxResults: opts.limit,
+        direction: "both"
+      });
+      const titleByEntityId = new Map(startNodes.map((node) => [node.entityId, node.title]));
+      for (const path11 of expansion.paths) {
+        if (path11.target.type !== "event")
+          continue;
+        const target = await this.eventStore.getEvent(path11.target.id);
+        if (!target)
+          continue;
+        const graphPath = toRetrievalGraphPathDebug(path11, titleByEntityId);
+        const score = graphPathScore(path11, opts.hopPenalty);
+        const existing = byId.get(target.id);
+        const graphPaths = mergeGraphPaths(existing?.graphPaths ?? [], [graphPath]);
+        const row = {
+          id: existing?.id ?? `graph-path-${path11.hops}-${target.id}`,
+          eventId: target.id,
+          content: target.content,
+          score: Math.max(existing?.score ?? 0, score),
+          sessionId: target.sessionId,
+          eventType: target.eventType,
+          timestamp: target.timestamp.toISOString(),
+          semanticScore: existing?.semanticScore,
+          lexicalScore: existing?.lexicalScore,
+          recencyScore: existing?.recencyScore,
+          facetMatches: existing?.facetMatches,
+          graphPaths
+        };
+        byId.set(row.eventId, row);
+        if (byId.size >= opts.limit)
+          break;
+      }
+    } catch {
+    }
   }
   shouldFallback(matchResult, results) {
     if (results.length === 0)
@@ -5622,12 +6747,13 @@ var Retriever = class {
   async applyScopeFilters(results, options) {
     const scope = options?.scope;
     const projectScopeMode = options?.projectScopeMode ?? "global";
+    const facetFilters = this.normalizeFacetFilters(options?.facets);
     const allowedProjectHashes = new Set(
       [options?.projectHash, ...options?.allowedProjectHashes || []].filter(
         (value) => typeof value === "string" && value.length > 0
       )
     );
-    if (!scope && projectScopeMode === "global")
+    if (!scope && projectScopeMode === "global" && facetFilters === null)
       return results;
     const normalizedIncludes = (scope?.contentIncludes || []).map((s) => s.toLowerCase());
     const filtered = [];
@@ -5653,14 +6779,83 @@ var Retriever = class {
       const projectHash = this.extractProjectHash(event.metadata);
       filtered.push({ result, projectHash });
     }
+    let scopedResults;
     if (projectScopeMode === "global" || allowedProjectHashes.size === 0) {
-      return filtered.map((x) => x.result);
+      scopedResults = filtered.map((x) => x.result);
+    } else {
+      const projectMatched = filtered.filter((x) => x.projectHash && allowedProjectHashes.has(x.projectHash));
+      scopedResults = projectScopeMode === "strict" ? projectMatched.map((x) => x.result) : (projectMatched.length > 0 ? projectMatched : filtered).map((x) => x.result);
     }
-    const projectMatched = filtered.filter((x) => x.projectHash && allowedProjectHashes.has(x.projectHash));
-    if (projectScopeMode === "strict") {
-      return projectMatched.map((x) => x.result);
+    return this.applyFacetFilters(scopedResults, {
+      facets: facetFilters,
+      projectHash: options?.projectHash
+    });
+  }
+  normalizeFacetFilters(facets) {
+    if (!facets || facets.length === 0)
+      return null;
+    const normalized = [];
+    for (const facet of facets) {
+      const parsedDimension = FacetDimensionSchema.safeParse(facet.dimension);
+      const value = typeof facet.value === "string" ? facet.value.trim() : "";
+      if (!parsedDimension.success || !value)
+        return [];
+      normalized.push({ dimension: parsedDimension.data, value });
     }
-    return (projectMatched.length > 0 ? projectMatched : filtered).map((x) => x.result);
+    return normalized;
+  }
+  async applyFacetFilters(results, options) {
+    if (options.facets === null)
+      return results;
+    if (options.facets.length === 0)
+      return [];
+    if (!options.projectHash)
+      return [];
+    if (!this.eventStore.getDatabase)
+      return [];
+    const repo = new FacetRepository(this.eventStore.getDatabase());
+    const filtered = [];
+    for (const result of results) {
+      const matches = [];
+      let matchedAll = true;
+      for (const facet of options.facets) {
+        const rows = await repo.query({
+          targetType: "event",
+          targetId: result.eventId,
+          dimension: facet.dimension,
+          value: facet.value,
+          projectHash: options.projectHash
+        });
+        if (rows.length === 0) {
+          matchedAll = false;
+          break;
+        }
+        matches.push(facet);
+      }
+      if (matchedAll) {
+        filtered.push({ ...result, facetMatches: matches });
+      }
+    }
+    return filtered;
+  }
+  debugDetailForResult(result) {
+    const detail = {
+      eventId: result.eventId,
+      score: result.score,
+      semanticScore: result.semanticScore,
+      lexicalScore: result.lexicalScore,
+      recencyScore: result.recencyScore
+    };
+    if (result.facetMatches && result.facetMatches.length > 0) {
+      detail.facetMatches = result.facetMatches;
+    }
+    if (result.graphPaths && result.graphPaths.length > 0) {
+      detail.graphPaths = result.graphPaths;
+    }
+    return detail;
+  }
+  isGraphPathResult(result) {
+    return (result.graphPaths || []).length > 0;
   }
   extractProjectHash(metadata) {
     if (!metadata || typeof metadata !== "object")
@@ -5804,8 +6999,60 @@ _Context:_ ${sessionContext}`;
     return Math.ceil(text.length / 4);
   }
 };
-function createRetriever(eventStore, vectorStore, embedder, matcher) {
-  return new Retriever(eventStore, vectorStore, embedder, matcher);
+function uniqueEntityStartNodes(candidates) {
+  const seen = /* @__PURE__ */ new Set();
+  const nodes = [];
+  for (const candidate of candidates) {
+    if (!candidate.entityId || seen.has(candidate.entityId))
+      continue;
+    seen.add(candidate.entityId);
+    nodes.push({ entityId: candidate.entityId, title: candidate.text });
+  }
+  return nodes;
+}
+function toRetrievalGraphPathDebug(path11, titleByEntityId) {
+  const firstStep = path11.steps[0];
+  const startNode = firstStep?.direction === "incoming" ? firstStep.to : firstStep?.from;
+  const startEntityId = startNode?.type === "entity" ? startNode.id : "";
+  return {
+    startEntityId,
+    startEntityTitle: titleByEntityId.get(startEntityId) ?? startNode?.name,
+    targetId: path11.target.id,
+    targetType: path11.target.type,
+    hops: path11.hops,
+    relationPath: path11.steps.map((step) => step.relationType)
+  };
+}
+function graphPathScore(path11, hopPenalty) {
+  const base = Math.min(0.95, Math.max(0, path11.scoreContribution));
+  return Math.max(0.05, base - hopPenalty * Math.max(0, path11.hops - 1));
+}
+function clampGraphHops(maxHops) {
+  if (!Number.isFinite(maxHops))
+    return 2;
+  return Math.min(Math.max(0, Math.trunc(maxHops)), 2);
+}
+function mergeGraphPaths(existing, incoming) {
+  const byKey = /* @__PURE__ */ new Map();
+  for (const path11 of [...existing, ...incoming]) {
+    const key = [path11.startEntityId, path11.targetType, path11.targetId, path11.hops, ...path11.relationPath].join("\0");
+    if (!byKey.has(key))
+      byKey.set(key, path11);
+  }
+  return [...byKey.values()].sort((a, b) => a.hops - b.hops || compareStable(graphPathSignature(a), graphPathSignature(b))).slice(0, 3);
+}
+function graphPathSignature(path11) {
+  return [path11.startEntityId, path11.targetType, path11.targetId, path11.hops, ...path11.relationPath].join("|");
+}
+function compareStable(a, b) {
+  if (a < b)
+    return -1;
+  if (a > b)
+    return 1;
+  return 0;
+}
+function createRetriever(eventStore, vectorStore, embedder, matcher, sharedOptions) {
+  return new Retriever(eventStore, vectorStore, embedder, matcher, sharedOptions);
 }
 
 // src/core/engine/retrieval-analytics-service.ts
@@ -5991,10 +7238,15 @@ var RetrievalDisclosureService = class {
       {
         semanticScore: debug?.semanticScore,
         lexicalScore: debug?.lexicalScore,
-        recencyScore: debug?.recencyScore
+        recencyScore: debug?.recencyScore,
+        ...debug?.facetMatches && debug.facetMatches.length > 0 ? { facetMatches: debug.facetMatches } : {},
+        ...debug?.graphPaths && debug.graphPaths.length > 0 ? { graphPaths: this.sanitizeGraphPaths(debug.graphPaths) } : {}
       }
     );
   }
+  sanitizeGraphPaths(graphPaths) {
+    return sanitizeGovernanceAuditValue(graphPaths ?? []);
+  }
   eventToEnvelope(event, score, reasons, extraMetadata) {
     return {
       id: toDisclosureResultId(event.id),
@@ -6054,6 +7306,10 @@ var RetrievalDisclosureService = class {
       reasons.add("keyword_match");
     if ((debug?.recencyScore ?? 0) > 0)
       reasons.add("recent_relevance");
+    if ((debug?.facetMatches || []).length > 0)
+      reasons.add("facet_match");
+    if ((debug?.graphPaths || []).length > 0)
+      reasons.add("entity_overlap");
     if ((result.fallbackTrace || []).some((step) => step === "fallback:summary"))
       reasons.add("summary_fallback");
     if (memory.sessionContext)
@@ -6181,6 +7437,7 @@ var RetrievalOrchestrator = class {
     const rerankWeights = lightweightFastRead ? void 0 : await this.getRerankWeights(options?.adaptiveRerank === true);
     const projectHash = this.deps.getProjectHash();
     const projectScopeMode = retrieverOptions.projectScopeMode ?? (projectHash ? "strict" : "global");
+    const graphHop = this.resolveGraphHopOptions(retrieverOptions.graphHop);
     let result;
     if (retrieverOptions.includeShared && this.deps.hasSharedStore()) {
       result = await this.deps.retriever.retrieveUnified(query, {
@@ -6188,6 +7445,7 @@ var RetrievalOrchestrator = class {
         intentRewrite: retrieverOptions.intentRewrite === true,
         rerankWeights,
         includeShared: true,
+        graphHop,
         projectHash: projectHash || void 0,
         projectScopeMode,
         allowedProjectHashes: retrieverOptions.allowedProjectHashes
@@ -6197,6 +7455,7 @@ var RetrievalOrchestrator = class {
         ...retrieverOptions,
         intentRewrite: retrieverOptions.intentRewrite === true,
         rerankWeights,
+        graphHop,
         projectHash: projectHash || void 0,
         projectScopeMode,
         allowedProjectHashes: retrieverOptions.allowedProjectHashes
@@ -6258,6 +7517,29 @@ var RetrievalOrchestrator = class {
     await this.deps.initialize();
     await this.deps.accessStore.recordRetrieval(eventId, sessionId, score, query);
   }
+  resolveGraphHopOptions(callerOptions) {
+    const graphExpansion = this.deps.memoryOperationsConfig?.graphExpansion;
+    const durableOptions = graphExpansion?.enabled === true ? { enabled: true, maxHops: graphExpansion.maxHops } : void 0;
+    if (!callerOptions)
+      return durableOptions;
+    if (!graphExpansion)
+      return callerOptions;
+    if (graphExpansion.enabled !== true) {
+      return {
+        ...callerOptions,
+        enabled: false,
+        maxHops: graphExpansion.maxHops ?? callerOptions.maxHops
+      };
+    }
+    return {
+      enabled: callerOptions.enabled === false ? false : true,
+      maxHops: Math.min(
+        graphExpansion.maxHops ?? Number.POSITIVE_INFINITY,
+        callerOptions.maxHops ?? graphExpansion.maxHops ?? 1
+      ),
+      hopPenalty: callerOptions.hopPenalty
+    };
+  }
   async recordAutomaticTrace(query, result, options, projectHash) {
     const selectedEventIds = result.memories.map((memory) => memory.event.id);
     const selectedDetails = (result.selectedDebug || []).map((detail) => ({
@@ -6399,7 +7681,8 @@ function createRetrievalServices(deps) {
     deps.eventStore,
     deps.vectorStore,
     deps.embedder,
-    deps.matcher
+    deps.matcher,
+    { queryGraphExpansionEnabled: deps.memoryOperationsConfig?.graphExpansion?.enabled === true }
   );
   const retrievalOrchestrator = createRetrievalOrchestrator({
     initialize: deps.initialize,
@@ -6407,7 +7690,8 @@ function createRetrievalServices(deps) {
     traceStore: deps.eventStore,
     accessStore: deps.eventStore,
     getProjectHash: deps.getProjectHash,
-    hasSharedStore: deps.hasSharedStore
+    hasSharedStore: deps.hasSharedStore,
+    memoryOperationsConfig: deps.memoryOperationsConfig
   });
   const retrievalDisclosureService = createRetrievalDisclosureService({
     initialize: deps.initialize,
@@ -6426,13 +7710,14 @@ function createRetrievalServices(deps) {
     retrievalAnalyticsService
   };
 }
-function defaultCreateRetriever(eventStore, vectorStore, embedder, matcher) {
+function defaultCreateRetriever(eventStore, vectorStore, embedder, matcher, options) {
   assertDefaultRetrieverStore(eventStore);
   return createRetriever(
     eventStore,
     vectorStore,
     embedder,
-    matcher
+    matcher,
+    options
   );
 }
 function assertDefaultRetrieverStore(eventStore) {
@@ -6478,6 +7763,7 @@ function createMemoryEngineServices(options) {
     matcher,
     getProjectHash: options.getProjectHash,
     hasSharedStore: options.hasSharedStore,
+    memoryOperationsConfig: options.memoryOperationsConfig,
     sharedStore: options.sharedStore
   });
   const ingestService = new MemoryIngestService({
@@ -6964,7 +8250,7 @@ function createSharedEventStore(dbPath) {
 }
 
 // src/core/shared-promoter.ts
-import { randomUUID as randomUUID6 } from "crypto";
+import { randomUUID as randomUUID8 } from "crypto";
 var SharedPromoter = class {
   constructor(sharedStore, sharedVectorStore, embedder, config) {
     this.sharedStore = sharedStore;
@@ -7032,7 +8318,7 @@ var SharedPromoter = class {
       const embeddingContent = this.createEmbeddingContent(input);
       const embedding = await this.embedder.embed(embeddingContent);
       await this.sharedVectorStore.upsert({
-        id: randomUUID6(),
+        id: randomUUID8(),
         entryId,
         entryType: "troubleshooting",
         content: embeddingContent,
@@ -7148,7 +8434,7 @@ function createSharedPromoter(sharedStore, sharedVectorStore, embedder, config)
 }
 
 // src/core/shared-store.ts
-import { randomUUID as randomUUID7 } from "crypto";
+import { randomUUID as randomUUID9 } from "crypto";
 var SharedStore = class {
   constructor(sharedEventStore) {
     this.sharedEventStore = sharedEventStore;
@@ -7160,7 +8446,7 @@ var SharedStore = class {
    * Promote a verified troubleshooting entry to shared storage
    */
   async promoteEntry(input) {
-    const entryId = randomUUID7();
+    const entryId = randomUUID9();
     await dbRun(
       this.db,
       `INSERT INTO shared_troubleshooting (
@@ -7694,6 +8980,7 @@ function createMemoryServiceComposition(options) {
     getProjectHash: options.getProjectHash,
     getProjectPath: options.getProjectPath,
     hasSharedStore: () => sharedMemoryServices?.isEnabled() ?? false,
+    memoryOperationsConfig: options.config.operations,
     sharedStore: {
       get: (entryId) => sharedMemoryServices?.getEntryForDisclosure(entryId) ?? Promise.resolve(null)
     },
@@ -7839,6 +9126,18 @@ var DEFAULT_ENABLED_SHARED_STORE_CONFIG = {
   sharedStoragePath: SHARED_STORAGE_PATH
 };
 var DEFAULT_SHARED_STORAGE_PATH = SHARED_STORAGE_PATH;
+var DISABLED_MEMORY_OPERATIONS_CONFIG = {
+  enabled: false,
+  facets: { enabled: true },
+  actions: { enabled: true },
+  retention: { enabled: false, policyVersion: "v1" },
+  graphExpansion: { enabled: false, maxHops: 1 },
+  lessons: { enabled: false }
+};
+var DEFAULT_ENABLED_MEMORY_OPERATIONS_CONFIG = {
+  ...DISABLED_MEMORY_OPERATIONS_CONFIG,
+  enabled: true
+};
 
 // src/services/memory-service-registry.ts
 import * as path10 from "path";