@gethmy/mcp 2.4.6 → 2.5.0

package/src/lifecycle-maintenance.ts

@@ -1,120 +0,0 @@
-/**
- * Automatic Memory Lifecycle Maintenance
- *
- * Runs at session end to enforce decay/archival rules:
- * - Archive entities with confidence < 0.3
- * - Delete stale drafts (>30 days old with low decay score)
- * - Auto-promote eligible entities (draft→episode, episode→reference)
- *
- * All operations are non-fatal — failures are logged but never block session end.
- */
-
-import { evaluateLifecycle } from "@harmony/memory";
-import type { HarmonyApiClient } from "./api-client.js";
-
-interface MemoryEntity {
-  id: string;
-  title: string;
-  memory_tier: "draft" | "episode" | "reference";
-  confidence: number;
-  access_count: number;
-  last_accessed_at: string | null;
-  created_at: string;
-}
-
-export interface MaintenanceResult {
-  archived: number;
-  pruned: number;
-  promoted: number;
-  reviewed: number;
-  errors: number;
-}
-
-/**
- * Run lifecycle maintenance for a workspace.
- * Called automatically at session end alongside consolidation.
- */
-export async function runLifecycleMaintenance(
-  client: HarmonyApiClient,
-  workspaceId: string,
-  projectId?: string,
-): Promise<MaintenanceResult> {
-  const result: MaintenanceResult = {
-    archived: 0,
-    pruned: 0,
-    promoted: 0,
-    reviewed: 0,
-    errors: 0,
-  };
-
-  let entities: MemoryEntity[];
-  try {
-    const listResult = await client.listMemoryEntities({
-      workspace_id: workspaceId,
-      project_id: projectId,
-      limit: 200,
-    });
-    entities = (listResult.entities || []) as MemoryEntity[];
-  } catch {
-    return result;
-  }
-
-  if (entities.length === 0) return result;
-
-  const now = Date.now();
-  const STALE_DRAFT_MAX_AGE_DAYS = 30;
-
-  for (const entity of entities) {
-    try {
-      const lifecycle = evaluateLifecycle(entity);
-
-      // 1. Archive low-confidence entities (confidence < 0.3)
-      if (lifecycle.shouldArchive) {
-        await client.deleteMemoryEntity(entity.id);
-        result.archived++;
-        continue;
-      }
-
-      // 2. Prune stale drafts (>30 days old with low decay score)
-      if (entity.memory_tier === "draft") {
-        const ageDays =
-          (now - new Date(entity.created_at).getTime()) / (1000 * 60 * 60 * 24);
-        if (ageDays > STALE_DRAFT_MAX_AGE_DAYS && lifecycle.decay.score < 0.3) {
-          await client.deleteMemoryEntity(entity.id);
-          result.pruned++;
-          continue;
-        }
-      }
-
-      // 3. Auto-promote eligible entities
-      if (lifecycle.promotion.eligible && lifecycle.promotion.targetTier) {
-        await client.updateMemoryEntity(entity.id, {
-          memory_tier: lifecycle.promotion.targetTier,
-          metadata: {
-            promoted_at: new Date().toISOString(),
-            promotion_reason: lifecycle.promotion.reason,
-            promoted_from: entity.memory_tier,
-          },
-        });
-        result.promoted++;
-        continue;
-      }
-
-      // 4. Flag stale entities for review (>90 days, <3 accesses)
-      if (lifecycle.shouldFlagForReview) {
-        await client.updateMemoryEntity(entity.id, {
-          metadata: {
-            needs_review: true,
-            review_reason: lifecycle.reviewReason,
-            flagged_at: new Date().toISOString(),
-          },
-        });
-        result.reviewed++;
-      }
-    } catch {
-      result.errors++;
-    }
-  }
-
-  return result;
-}

package/src/memory-audit.ts

@@ -1,578 +0,0 @@
-/**
- * Memory Quality Audit
- *
- * Scores every memory entity against modern quality standards and buckets
- * them into keep / review / archive / delete. Designed to catch legacy
- * memories that pre-date tier/decay/embedding optimizations.
- *
- * Composite score (0-100): confidence (25) + decay (20) + structural (15) +
- * content (15) + tier-age-fit (15) + access (10). Legacy signals (default
- * confidence, missing embedding, stuck draft, no graph presence) are reported
- * but don't change the score — they provide explanation.
- */
-
-import { evaluateLifecycle } from "@harmony/memory";
-import type { HarmonyApiClient } from "./api-client.js";
-
-// Embeddings migration landed 2026-02-18. Entities older than this without
-// embeddings are pre-vector and legacy by construction.
-const EMBEDDINGS_MIGRATION_AT = Date.parse("2026-02-18T00:00:00Z");
-const MS_PER_DAY = 1000 * 60 * 60 * 24;
-const BATCH_SIZE = 100;
-const CONCURRENCY_LIMIT = 5;
-
-interface AuditEntity {
-  id: string;
-  type: string;
-  title: string;
-  content: string;
-  confidence: number;
-  memory_tier: "draft" | "episode" | "reference";
-  access_count: number;
-  last_accessed_at: string | null;
-  created_at: string;
-  updated_at?: string;
-  tags?: string[];
-  metadata?: Record<string, unknown>;
-  embedding?: unknown;
-  promoted_from_id?: string | null;
-}
-
-export type AuditBucket = "keep" | "review" | "archive" | "delete";
-
-export interface AuditOptions {
-  dryRun?: boolean;
-  archiveBelow?: number;
-  deleteBelow?: number;
-  includeLegacyFlag?: boolean;
-  limit?: number;
-  /**
-   * Age threshold (days) for the stale-draft filter. A memory is flagged
-   * stale when `tier=draft AND access_count=0 AND age > staleDraftAgeDays`.
-   * Stale drafts are reported separately — they don't change scoring or
-   * bucketing, just surface promote-or-drop candidates the thresholds miss.
-   * Default: 7.
-   */
-  staleDraftAgeDays?: number;
-}
-
-interface EntityAudit {
-  id: string;
-  title: string;
-  type: string;
-  tier: string;
-  ageDays: number;
-  score: number;
-  bucket: AuditBucket;
-  reasons: string[];
-  legacy: boolean;
-  legacyReasons: string[];
-  staleDraft: boolean;
-  subScores: {
-    confidence: number;
-    decay: number;
-    structural: number;
-    content: number;
-    tierAgeFit: number;
-    access: number;
-  };
-}
-
-export interface AuditReport {
-  success: boolean;
-  dryRun: boolean;
-  timestamp: string;
-  workspace: { id: string; projectId?: string };
-  summary: {
-    totalEntities: number;
-    scanned: number;
-    keep: number;
-    review: number;
-    archive: number;
-    delete: number;
-    legacyCount: number;
-    staleDraftCount: number;
-  };
-  actionsTaken: {
-    flaggedReview: number;
-    archived: number;
-    deleted: number;
-  };
-  distribution: {
-    "0-20": number;
-    "20-40": number;
-    "40-70": number;
-    "70-100": number;
-  };
-  legacyBreakdown: {
-    defaultConfidence: number;
-    missingEmbedding: number;
-    stuckDraft: number;
-    noGraphPresence: number;
-  };
-  lowest: EntityAudit[];
-  staleDrafts: EntityAudit[];
-  errors: Array<{ entityId?: string; step: string; message: string }>;
-  healthReport: string;
-}
-
-// Patterns must stay in sync with:
-//   supabase/functions/_shared/memory-boilerplate.ts (edge function guard)
-//   supabase/migrations/*_harden_memory_cleanup.sql  (cron sweeper)
-//
-// End-anchored where possible to avoid matching legitimate titles like
-// "Placeholder pattern in React" or "Untitled.fig reference". The retired
-// mid-session extractor's "Task transition: ..." prefix is the one open-ended
-// pattern — it was never a user-chosen format.
-const BOILERPLATE_PATTERNS = [
-  /^todo:?$/i,
-  /^placeholder(\s+\d+|:)?$/i,
-  /^\.\.\.$/,
-  /^untitled(\s+\d+|:)?$/i,
-  /^(note|memo|draft)\s+\d+$/i,
-  /^task transition:/i,
-];
-
-/**
- * Title-only check. Used by the audit override — should not delete an entry
- * just because its content is empty (may be a draft the user hasn't finished).
- */
-function isBoilerplateTitle(title: string): boolean {
-  const t = title.trim();
-  for (const pat of BOILERPLATE_PATTERNS) {
-    if (pat.test(t)) return true;
-  }
-  return false;
-}
-
-/**
- * Stricter check used by the content-quality scoring band. Empty content is
- * "boilerplate" for scoring — an empty memory contributes nothing regardless
- * of title — but does not on its own trigger the delete-bucket override.
- */
-function isBoilerplate(title: string, content: string): boolean {
-  if (content.trim().length === 0) return true;
-  return isBoilerplateTitle(title);
-}
-
-function scoreEntity(
-  entity: AuditEntity,
-  relationCount: number,
-  archiveBelow: number,
-  deleteBelow: number,
-  staleDraftAgeDays: number,
-): EntityAudit {
-  const now = Date.now();
-  const ageDays = (now - Date.parse(entity.created_at)) / MS_PER_DAY;
-  // If an entity was never accessed, decay should start from creation time,
-  // not from "now" (which would falsely yield a fresh decay score of 1.0).
-  const effectiveLastAccess = entity.last_accessed_at ?? entity.created_at;
-  const lifecycle = evaluateLifecycle({
-    memory_tier: entity.memory_tier,
-    confidence: entity.confidence,
-    access_count: entity.access_count,
-    last_accessed_at: effectiveLastAccess,
-    created_at: entity.created_at,
-  });
-
-  const reasons: string[] = [];
-  const legacyReasons: string[] = [];
-
-  // Confidence (25)
-  const confidence = Math.max(0, Math.min(1, entity.confidence)) * 25;
-
-  // Decay (20)
-  const decay = Math.max(0, Math.min(1, lifecycle.decay.score)) * 20;
-  if (lifecycle.decay.score < 0.2)
-    reasons.push(`decay score ${lifecycle.decay.score.toFixed(2)}`);
-
-  // Structural completeness (15)
-  const hasEmbedding = entity.embedding != null;
-  const hasTags = (entity.tags?.length || 0) >= 1;
-  const hasRelations = relationCount > 0;
-  let structural = 0;
-  if (hasEmbedding) structural += 6;
-  if (hasTags) structural += 4;
-  if (hasRelations) structural += 5;
-  if (!hasEmbedding) reasons.push("no embedding");
-  if (!hasTags) reasons.push("no tags");
-  if (!hasRelations) reasons.push("no relations");
-
-  // Content quality (15) — boilerplate hard-zeroes the whole band. Auto-captured
-  // noise should never inherit the length/title bonuses it structurally earns.
-  let content = 0;
-  const contentLen = entity.content?.length || 0;
-  const boilerplate = isBoilerplate(entity.title, entity.content);
-  if (boilerplate) {
-    reasons.push("boilerplate title/content");
-  } else {
-    if (contentLen >= 80) content += 8;
-    const titleOk =
-      entity.title.trim().length >= 4 &&
-      !/^(untitled|draft|note)\b/i.test(entity.title.trim());
-    if (titleOk) content += 4;
-    content += 3;
-    if (contentLen < 80) reasons.push(`thin content (${contentLen} chars)`);
-  }
-
-  // Tier-age fit (15)
-  let tierAgeFit = 15;
-  if (
-    entity.memory_tier === "draft" &&
-    ageDays > 60 &&
-    !entity.promoted_from_id
-  ) {
-    tierAgeFit = 0;
-    reasons.push("stuck draft >60d never promoted");
-  } else if (
-    entity.memory_tier === "draft" &&
-    (entity.access_count || 0) === 0 &&
-    ageDays > 2
-  ) {
-    // Young drafts get a 2-day grace window. After that, zero access means
-    // zero signal — strip the tier-age bonus so useless auto-captures fall to archive.
-    tierAgeFit = 5;
-    reasons.push("draft >2d with zero access");
-  }
-  if (entity.promoted_from_id) {
-    tierAgeFit = Math.min(15, tierAgeFit + 5);
-  }
-
-  // Access pattern (10)
-  const access = Math.min(10, Math.log10((entity.access_count || 0) + 1) * 5);
-  if (entity.access_count === 0 && ageDays > 14) reasons.push("never accessed");
-
-  const raw = confidence + decay + structural + content + tierAgeFit + access;
-  const score = Math.round(Math.max(0, Math.min(100, raw)));
-
-  // Legacy detection
-  let legacy = false;
-  if (entity.confidence === 1.0 && entity.access_count === 0 && ageDays > 30) {
-    legacy = true;
-    legacyReasons.push("default confidence never validated");
-  }
-  if (
-    !hasEmbedding &&
-    Date.parse(entity.created_at) < EMBEDDINGS_MIGRATION_AT
-  ) {
-    legacy = true;
-    legacyReasons.push("pre-embeddings migration");
-  }
-  if (
-    entity.memory_tier === "draft" &&
-    ageDays > 60 &&
-    !entity.promoted_from_id
-  ) {
-    legacy = true;
-    legacyReasons.push("stuck draft");
-  }
-  if (!hasTags && !hasRelations) {
-    legacy = true;
-    legacyReasons.push("no graph presence");
-  }
-
-  // Bucket — boilerplate TITLE is a one-way door to delete. High access
-  // counts on noise titles signal re-read churn (recall/dedup loops), not
-  // genuine reuse; letting confidence + tier + decay drag the composite
-  // score back into "keep" leaves promoted-to-reference junk untouched.
-  // Override scoring, except when deleteBelow=0 (the "no deletions" escape
-  // hatch). Title-only on purpose: an empty-content entry with a real title
-  // may be a draft; the user should see it in the audit, not lose it.
-  const boilerplateTitle = isBoilerplateTitle(entity.title);
-  let bucket: AuditBucket;
-  if (boilerplateTitle && deleteBelow > 0) {
-    bucket = "delete";
-    reasons.push("boilerplate title override");
-  } else if (score < deleteBelow) bucket = "delete";
-  else if (score < archiveBelow) bucket = "archive";
-  else if (score < 70) bucket = "review";
-  else bucket = "keep";
-
-  // Stale-draft filter — orthogonal to bucketing. A draft that's aged past
-  // the threshold without a single access is a promote-or-drop candidate
-  // regardless of its composite score.
-  const staleDraft =
-    entity.memory_tier === "draft" &&
-    (entity.access_count || 0) === 0 &&
-    ageDays > staleDraftAgeDays;
-
-  return {
-    id: entity.id,
-    title: entity.title,
-    type: entity.type,
-    tier: entity.memory_tier,
-    ageDays: Math.round(ageDays),
-    score,
-    bucket,
-    reasons,
-    legacy,
-    legacyReasons,
-    staleDraft,
-    subScores: {
-      confidence: Math.round(confidence),
-      decay: Math.round(decay),
-      structural,
-      content,
-      tierAgeFit,
-      access: Math.round(access),
-    },
-  };
-}
-
-export async function runMemoryAudit(
-  client: HarmonyApiClient,
-  workspaceId: string,
-  projectId?: string,
-  options?: AuditOptions,
-): Promise<AuditReport> {
-  const dryRun = options?.dryRun !== false;
-  const archiveBelow = options?.archiveBelow ?? 40;
-  const deleteBelow = options?.deleteBelow ?? 20;
-  const limit = options?.limit ?? 500;
-  const staleDraftAgeDays = options?.staleDraftAgeDays ?? 7;
-
-  const report: AuditReport = {
-    success: true,
-    dryRun,
-    timestamp: new Date().toISOString(),
-    workspace: { id: workspaceId, projectId },
-    summary: {
-      totalEntities: 0,
-      scanned: 0,
-      keep: 0,
-      review: 0,
-      archive: 0,
-      delete: 0,
-      legacyCount: 0,
-      staleDraftCount: 0,
-    },
-    actionsTaken: { flaggedReview: 0, archived: 0, deleted: 0 },
-    distribution: { "0-20": 0, "20-40": 0, "40-70": 0, "70-100": 0 },
-    legacyBreakdown: {
-      defaultConfidence: 0,
-      missingEmbedding: 0,
-      stuckDraft: 0,
-      noGraphPresence: 0,
-    },
-    lowest: [],
-    staleDrafts: [],
-    errors: [],
-    healthReport: "",
-  };
-
-  // Paginate
-  const entities: AuditEntity[] = [];
-  let offset = 0;
-  try {
-    while (entities.length < limit) {
-      const pageSize = Math.min(BATCH_SIZE, limit - entities.length);
-      const result = await client.listMemoryEntities({
-        workspace_id: workspaceId,
-        project_id: projectId,
-        limit: pageSize,
-        offset,
-      });
-      const page = (result.entities || []) as AuditEntity[];
-      if (page.length === 0) break;
-      entities.push(...page);
-      if (page.length < pageSize) break;
-      offset += pageSize;
-    }
-  } catch (err) {
-    report.errors.push({
-      step: "fetch",
-      message: `Failed to fetch entities: ${(err as Error).message}`,
-    });
-    report.success = false;
-    report.healthReport = renderReport(report);
-    return report;
-  }
-
-  report.summary.totalEntities = entities.length;
-
-  // Fetch relation counts concurrently
-  const relationCounts = new Map<string, number>();
-  for (let i = 0; i < entities.length; i += CONCURRENCY_LIMIT) {
-    const batch = entities.slice(i, i + CONCURRENCY_LIMIT);
-    const results = await Promise.allSettled(
-      batch.map(async (e) => {
-        const related = await client.getRelatedEntities(e.id);
-        const count =
-          (related.outgoing?.length || 0) + (related.incoming?.length || 0);
-        return { id: e.id, count };
-      }),
-    );
-    for (const r of results) {
-      if (r.status === "fulfilled") {
-        relationCounts.set(r.value.id, r.value.count);
-      }
-    }
-  }
-
-  // Score each entity
-  const audits: EntityAudit[] = [];
-  for (const entity of entities) {
-    const relCount = relationCounts.get(entity.id) ?? 0;
-    const audit = scoreEntity(
-      entity,
-      relCount,
-      archiveBelow,
-      deleteBelow,
-      staleDraftAgeDays,
-    );
-    audits.push(audit);
-    report.summary.scanned++;
-    report.summary[audit.bucket]++;
-    if (audit.legacy) report.summary.legacyCount++;
-    if (audit.staleDraft) report.summary.staleDraftCount++;
-
-    // Distribution bin
-    if (audit.score < 20) report.distribution["0-20"]++;
-    else if (audit.score < 40) report.distribution["20-40"]++;
-    else if (audit.score < 70) report.distribution["40-70"]++;
-    else report.distribution["70-100"]++;
-
-    // Legacy breakdown
-    for (const reason of audit.legacyReasons) {
-      if (reason.startsWith("default confidence"))
-        report.legacyBreakdown.defaultConfidence++;
-      else if (reason.startsWith("pre-embeddings"))
-        report.legacyBreakdown.missingEmbedding++;
-      else if (reason.startsWith("stuck draft"))
-        report.legacyBreakdown.stuckDraft++;
-      else if (reason.startsWith("no graph"))
-        report.legacyBreakdown.noGraphPresence++;
-    }
-  }
-
-  // Top 10 lowest-scoring
-  report.lowest = [...audits].sort((a, b) => a.score - b.score).slice(0, 10);
-
-  // All stale drafts — oldest first (most overdue for promote-or-drop)
-  report.staleDrafts = audits
-    .filter((a) => a.staleDraft)
-    .sort((a, b) => b.ageDays - a.ageDays);
-
-  // Execute actions
-  if (!dryRun) {
-    for (const audit of audits) {
-      try {
-        if (audit.bucket === "delete") {
-          await client.deleteMemoryEntity(audit.id);
-          report.actionsTaken.deleted++;
-        } else if (audit.bucket === "archive") {
-          await client.updateMemoryEntity(audit.id, {
-            confidence: 0.25,
-            metadata: {
-              audit_archived_at: new Date().toISOString(),
-              audit_score: audit.score,
-              audit_reasons: audit.reasons,
-            },
-          });
-          report.actionsTaken.archived++;
-        } else if (audit.bucket === "review") {
-          await client.updateMemoryEntity(audit.id, {
-            metadata: {
-              needs_review: true,
-              audit_score: audit.score,
-              audit_reasons: audit.reasons,
-              audit_at: new Date().toISOString(),
-            },
-          });
-          report.actionsTaken.flaggedReview++;
-        }
-      } catch (err) {
-        report.errors.push({
-          entityId: audit.id,
-          step: audit.bucket,
-          message: (err as Error).message,
-        });
-      }
-    }
-  }
-
-  report.healthReport = renderReport(report);
-  return report;
-}
-
-function renderReport(report: AuditReport): string {
-  const mode = report.dryRun ? "Dry Run (preview)" : "Executed";
-  const s = report.summary;
-  const lines: string[] = [
-    "# Memory Quality Audit\n",
-    `**Mode:** ${mode} | **Scanned:** ${s.scanned}/${s.totalEntities} | **Legacy:** ${s.legacyCount} | **Stale drafts:** ${s.staleDraftCount}`,
-    "",
-    "## Distribution",
-    `- 70-100 (keep):    ${report.distribution["70-100"]}`,
-    `- 40-69  (review):  ${report.distribution["40-70"]}`,
-    `- 20-39  (archive): ${report.distribution["20-40"]}`,
-    `- 0-19   (delete):  ${report.distribution["0-20"]}`,
-    "",
-    "## Buckets",
-    `- **Keep:**    ${s.keep}`,
-    `- **Review:**  ${s.review}${!report.dryRun ? ` (flagged ${report.actionsTaken.flaggedReview})` : ""}`,
-    `- **Archive:** ${s.archive}${!report.dryRun ? ` (archived ${report.actionsTaken.archived})` : ""}`,
-    `- **Delete:**  ${s.delete}${!report.dryRun ? ` (deleted ${report.actionsTaken.deleted})` : ""}`,
-    "",
-  ];
-
-  const l = report.legacyBreakdown;
-  if (s.legacyCount > 0) {
-    lines.push("## Legacy Breakdown");
-    lines.push(`- Default confidence, never validated: ${l.defaultConfidence}`);
-    lines.push(`- Pre-embeddings migration:            ${l.missingEmbedding}`);
-    lines.push(`- Stuck drafts (>60d, no promotion):   ${l.stuckDraft}`);
-    lines.push(`- No tags + no relations:              ${l.noGraphPresence}`);
-    lines.push("");
-  }
-
-  if (report.staleDrafts.length > 0) {
-    lines.push("## Stale Drafts (promote-or-drop candidates)");
-    lines.push("Filter: `tier=draft AND access=0 AND age>threshold`");
-    lines.push("| Age | Score | Title |");
-    lines.push("|-----|-------|-------|");
-    for (const a of report.staleDrafts.slice(0, 20)) {
-      const titleTrunc =
-        a.title.length > 50 ? `${a.title.slice(0, 47)}...` : a.title;
-      lines.push(`| ${a.ageDays}d | ${a.score} | ${titleTrunc} |`);
-    }
-    lines.push("");
-  }
-
-  if (report.lowest.length > 0) {
-    lines.push("## Lowest-Scoring (top 10)");
-    lines.push("| Score | Bucket | Tier | Age | Title | Reasons |");
-    lines.push("|-------|--------|------|-----|-------|---------|");
-    for (const a of report.lowest) {
-      const reasonStr = a.reasons.slice(0, 3).join(", ") || "—";
-      const titleTrunc =
-        a.title.length > 40 ? `${a.title.slice(0, 37)}...` : a.title;
-      lines.push(
-        `| ${a.score} | ${a.bucket} | ${a.tier} | ${a.ageDays}d | ${titleTrunc} | ${reasonStr} |`,
-      );
-    }
-    lines.push("");
-  }
-
-  if (report.errors.length > 0) {
-    lines.push("## Errors");
-    for (const e of report.errors.slice(0, 10)) {
-      lines.push(
-        `- **${e.step}${e.entityId ? ` ${e.entityId}` : ""}:** ${e.message}`,
-      );
-    }
-    lines.push("");
-  }
-
-  if (report.dryRun) {
-    lines.push("---");
-    lines.push(
-      "*Run with `dryRun: false` to flag review entries, archive low-quality memories, and delete worst offenders.*",
-    );
-  }
-
-  return lines.join("\n");
-}
-
-// Exposed for reuse from memory-cleanup.ts
-export { scoreEntity };