@gethmy/mcp 2.4.7 → 2.5.0

package/src/server.ts

@@ -1,10 +1,4 @@
-import {
-  discoverRelatedContext,
-  evaluateLifecycle,
-  syncFull,
-  syncPull,
-  syncPush,
-} from "@harmony/memory";
+import { syncFull, syncPull, syncPush } from "@harmony/memory";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import {
@@ -14,12 +8,6 @@ import {
   ReadResourceRequestSchema,
 } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
-import {
-  detectContradictions,
-  extractLearnings,
-  extractMidSessionLearnings,
-  type SessionContext,
-} from "./active-learning.js";
 import {
   getClient,
   type HarmonyApiClient,
@@ -46,26 +34,20 @@ import {
   setActiveProject,
   setActiveWorkspace,
 } from "./config.js";
-import { consolidateMemories } from "./consolidation.js";
-import {
-  assembleContext,
-  cacheManifest,
-  computeRelevanceScore,
-  getCachedManifest,
-  mapToContextEntity,
-  recordContextFeedback,
-  trackSessionAssembly,
-} from "./context-assembly.js";
 import { autoExpandGraph } from "./graph-expansion.js";
-import { runLifecycleMaintenance } from "./lifecycle-maintenance.js";
-import { runMemoryAudit } from "./memory-audit.js";
+import { validateMemoryQuality } from "./memory-floor.js";
+import {
+  fitToBudget,
+  type ParkInput,
+  relevanceFromRank,
+  rescore,
+} from "./memory-park.js";
 import {
-  type PurgeFilters,
-  purgeMemories,
-  runMemoryCleanup,
-} from "./memory-cleanup.js";
+  isSessionScope,
+  resolveSessionScope,
+  sessionScopeFor,
+} from "./memory-session.js";
 import { onboardNewUser } from "./onboard.js";
-import type { PromptVariant } from "./prompt-builder.js";
 
 /**
  * Dependencies injected into tool handlers.
@@ -92,6 +74,11 @@ interface MemorySessionState {
   cardId: string;
   agentIdentifier: string;
   agentName: string;
+  // Identifier of the live `card_agent_context` row for this card. Captured on
+  // session start so memory tools can scope working-memory writes to it
+  // without a round-trip. May be undefined if the start endpoint did not
+  // return an id (older clients) — `scope: 'session'` will then refuse.
+  agentSessionId?: string;
   memoryReadCount: number;
   pendingActions: { action: string; ts: string }[];
   allActions: { action: string; ts: string }[];
@@ -143,11 +130,13 @@ function initMemorySession(
   cardId: string,
   agentIdentifier: string,
   agentName: string,
+  agentSessionId?: string,
 ): void {
   memorySessions.set(cardId, {
     cardId,
     agentIdentifier,
     agentName,
+    agentSessionId,
     memoryReadCount: 0,
     pendingActions: [],
     allActions: [],
@@ -274,7 +263,7 @@ function cleanupMemorySession(cardId: string): void {
 }
 
 // Tool definitions
-const TOOLS = {
+export const TOOLS = {
   // Card operations
   harmony_create_card: {
     description: "Create a new card in a Kanban column",
@@ -837,25 +826,6 @@ const TOOLS = {
     },
   },
 
-  harmony_get_agent_profile: {
-    description:
-      "Get aggregate performance profile for an agent. Shows total sessions, completion rate, average duration, and more. Defaults to the current agent if no identifier provided.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        agentIdentifier: {
-          type: "string",
-          description:
-            "Agent identifier (e.g., 'claude-code'). Defaults to current agent.",
-        },
-        workspaceId: {
-          type: "string",
-          description: "Workspace ID (optional if context set)",
-        },
-      },
-    },
-  },
-
   // Prompt generation
   harmony_generate_prompt: {
     description:
@@ -939,9 +909,12 @@ const TOOLS = {
         },
         scope: {
           type: "string",
-          enum: ["private", "project", "workspace", "global"],
+          enum: ["private", "project", "workspace", "global", "session"],
           description:
-            "Visibility scope (default: project). Private = only creator can see.",
+            "Visibility scope (default: project). Private = only creator can see. " +
+            "Use 'session' for ephemeral working memory bound to the active agent " +
+            "session — auto-expires ~24h after the session ends and is excluded from " +
+            "the long-term vault.",
         },
         tier: {
           type: "string",
@@ -958,6 +931,16 @@ const TOOLS = {
           type: "number",
           description: "Confidence score 0-1 (default: 1.0)",
         },
+        importance: {
+          type: "number",
+          description:
+            "Importance score 1-10 for Park-style retrieval ranking (plan §6.2). If omitted, falls back to per-type default (preference=9, lesson/decision=8, pattern/solution/procedure=7, error/context=5).",
+        },
+        auto_score_importance: {
+          type: "boolean",
+          description:
+            "If true and `importance` is not provided, run an LLM-based rating instead of the per-type default. Costs ~500ms-2s + tokens. Default false (plan §7.1).",
+        },
         metadata: {
           type: "object",
           description: "Additional structured metadata",
@@ -1007,8 +990,11 @@ const TOOLS = {
         },
         scope: {
           type: "string",
-          enum: ["private", "project", "workspace", "global"],
-          description: "Filter by scope",
+          enum: ["private", "project", "workspace", "global", "session"],
+          description:
+            "Filter by scope. 'session' returns only working memory for the " +
+            "active agent session. When omitted and a session is active, " +
+            "session memories are prepended to the long-term result.",
         },
         query: {
           type: "string",
@@ -1027,6 +1013,21 @@ const TOOLS = {
           description: "Project ID (optional)",
         },
         limit: { type: "number", description: "Max results (default: 20)" },
+        top_k: {
+          type: "number",
+          description:
+            "After Park rescoring (relevance × recency × importance per plan §6), keep this many top entries. Defaults to `limit`. Useful when you want to over-fetch (large `limit`) so the rescorer has more candidates and then trim to a tight top-k.",
+        },
+        budget_tokens: {
+          type: "number",
+          description:
+            "If set, after rescoring + top-k, greedy-fill into a token budget (each entity = title + first 200 chars of content). Returns the prefix that fits.",
+        },
+        include_superseded: {
+          type: "boolean",
+          description:
+            "Include rows whose `superseded_at` is set (default false). Use when investigating supersede chains.",
+        },
       },
     },
   },
@@ -1397,130 +1398,6 @@ const TOOLS = {
     },
   },
 
-  // Memory lifecycle
-  harmony_prune_draft: {
-    description:
-      "Remove stale draft memories that haven't been accessed recently. Runs in dry-run mode by default to preview what would be pruned.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        workspaceId: {
-          type: "string",
-          description: "Workspace ID (optional if context set)",
-        },
-        projectId: {
-          type: "string",
-          description: "Project ID (optional)",
-        },
-        dryRun: {
-          type: "boolean",
-          description:
-            "Preview what would be pruned without deleting (default: true)",
-        },
-        maxAgeDays: {
-          type: "number",
-          description:
-            "Maximum age in days for draft memories to keep (default: 30)",
-        },
-      },
-      required: [],
-    },
-  },
-
-  harmony_consolidate_memories: {
-    description:
-      "Consolidate similar draft/episode memories into reference entities. Groups similar memories by embedding similarity and merges clusters. Use dryRun to preview before executing.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        workspaceId: {
-          type: "string",
-          description: "Workspace ID (optional if context set)",
-        },
-        projectId: {
-          type: "string",
-          description: "Project ID (optional)",
-        },
-        dryRun: {
-          type: "boolean",
-          description:
-            "Preview what would be consolidated without creating entities (default: true)",
-        },
-        minClusterSize: {
-          type: "number",
-          description:
-            "Minimum number of similar entities to form a cluster (default: 2)",
-        },
-      },
-      required: [],
-    },
-  },
-
-  // Context assembly
-  harmony_get_context_manifest: {
-    description:
-      "Retrieve the context assembly manifest for a given assembly ID to debug what memories were loaded or excluded and why.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        assemblyId: {
-          type: "string",
-          description:
-            "Assembly ID from a previous harmony_generate_prompt call",
-        },
-      },
-      required: ["assemblyId"],
-    },
-  },
-
-  // Debug & visualization
-  harmony_debug_context: {
-    description:
-      "Explain why a specific memory was or wasn't included in context assembly for a given task. Returns relevance score breakdown.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        entityId: {
-          type: "string",
-          description: "Memory entity ID to analyze",
-        },
-        taskContext: {
-          type: "string",
-          description:
-            "Task context (card title + description) to score against",
-        },
-        cardLabels: {
-          type: "array",
-          items: { type: "string" },
-          description: "Card labels for tag matching",
-        },
-      },
-      required: ["entityId", "taskContext"],
-    },
-  },
-  harmony_export_memory_graph: {
-    description:
-      "Export the knowledge graph as DOT format for Graphviz visualization. Nodes are colored by tier (draft=yellow, episode=blue, reference=green).",
-    inputSchema: {
-      type: "object",
-      properties: {
-        workspaceId: {
-          type: "string",
-          description: "Workspace ID (optional if context set)",
-        },
-        projectId: {
-          type: "string",
-          description: "Project ID (optional)",
-        },
-        limit: {
-          type: "number",
-          description: "Max entities to include (default: 50)",
-        },
-      },
-      required: [],
-    },
-  },
-
   // ============ ONBOARDING TOOLS ============
   harmony_signup: {
     description:
@@ -1641,299 +1518,47 @@ const TOOLS = {
       required: ["email", "password", "fullName"],
     },
   },
+};
 
-  // Memory tier promotion
-  harmony_promote_memory: {
-    description:
-      "Promote a memory entity to a higher tier: draft→episode or episode→reference. Tracks promotion reason and source.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        entityId: {
-          type: "string",
-          description: "Memory entity ID to promote",
-        },
-        targetTier: {
-          type: "string",
-          enum: ["episode", "reference"],
-          description: "Target tier to promote to",
-        },
-        reason: {
-          type: "string",
-          description:
-            "Reason for promotion (e.g., 'proven useful across 5+ sessions')",
-        },
-      },
-      required: ["entityId", "targetTier", "reason"],
-    },
+// Resource URIs
+export const RESOURCES = [
+  {
+    uri: "harmony://context",
+    name: "Current Context",
+    description: "Current active workspace and project",
+    mimeType: "application/json",
   },
+];
 
-  // Vector embeddings
-  harmony_backfill_embeddings: {
-    description:
-      "Generate vector embeddings for knowledge entities that are missing them. Run this after importing memories or when semantic search isn't finding expected results. Idempotent — only processes entities without embeddings.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        workspaceId: {
-          type: "string",
-          description: "Workspace ID (optional if context set)",
-        },
-        batchSize: {
-          type: "number",
-          description: "Number of entities to process per batch (default: 50)",
-        },
-      },
-      required: [],
-    },
-  },
-  harmony_backfill_relations: {
-    description:
-      "Retroactively create semantic relations across all existing memory entities. Iterates entities and runs graph expansion on each. Run after harmony_backfill_embeddings to connect a disconnected knowledge graph.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        workspaceId: {
-          type: "string",
-          description: "Workspace ID (optional if context set)",
-        },
-        projectId: {
-          type: "string",
-          description: "Project ID (optional, limits to project)",
-        },
-        maxRelationsPerEntity: {
-          type: "number",
-          description: "Maximum relations to create per entity (default: 3)",
-        },
-      },
-      required: [],
-    },
-  },
-
-  harmony_cleanup_memories: {
-    description:
-      "Run a unified memory cleanup: prune stale drafts, consolidate similar memories, detect orphans and duplicates, backfill embeddings, and optionally run a quality audit. Returns a health report. Dry-run by default — run with dryRun=false to execute.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        workspaceId: {
-          type: "string",
-          description: "Workspace ID (optional if context set)",
-        },
-        projectId: {
-          type: "string",
-          description: "Project ID (optional)",
-        },
-        dryRun: {
-          type: "boolean",
-          description:
-            "Preview cleanup without executing changes (default: true)",
-        },
-        steps: {
-          type: "array",
-          items: {
-            type: "string",
-            enum: [
-              "prune",
-              "consolidate",
-              "orphans",
-              "duplicates",
-              "backfill",
-              "audit",
-            ],
-          },
-          description:
-            "Which cleanup steps to run (default: all). Options: prune, consolidate, orphans, duplicates, backfill, audit.",
-        },
-        maxAgeDays: {
-          type: "number",
-          description: "Max age in days for stale draft pruning (default: 30)",
-        },
-        minClusterSize: {
-          type: "number",
-          description: "Min cluster size for consolidation (default: 3)",
-        },
-        orphanAgeDays: {
-          type: "number",
-          description: "Min age in days for orphan detection (default: 14)",
-        },
-        auditArchiveBelow: {
-          type: "number",
-          description:
-            "Audit: archive entities scoring below this (default: 40)",
-        },
-        auditDeleteBelow: {
-          type: "number",
-          description:
-            "Audit: delete entities scoring below this (default: 20)",
-        },
-      },
-      required: [],
-    },
-  },
-  harmony_audit_memories: {
-    description:
-      "Rate every memory against state-of-the-art quality standards (confidence, decay, structural completeness, content, tier-age fit, access). Flags legacy entities from before recent optimizations (default confidence, missing embeddings, stuck drafts). Buckets: keep (≥70), review (40-69), archive (20-39), delete (<20). Dry-run by default.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        workspaceId: {
-          type: "string",
-          description: "Workspace ID (optional if context set)",
-        },
-        projectId: {
-          type: "string",
-          description: "Project ID (optional)",
-        },
-        dryRun: {
-          type: "boolean",
-          description:
-            "Preview audit without flagging/archiving/deleting (default: true)",
-        },
-        archiveBelow: {
-          type: "number",
-          description:
-            "Score threshold below which entities are archived (confidence set to 0.25). Default: 40",
-        },
-        deleteBelow: {
-          type: "number",
-          description:
-            "Score threshold below which entities are hard-deleted. Default: 20. Set to 0 to never delete.",
-        },
-        limit: {
-          type: "number",
-          description:
-            "Max number of entities to audit (default: 500). Paginated fetch.",
-        },
-        staleDraftAgeDays: {
-          type: "number",
-          description:
-            "Age threshold (days) for the stale-draft filter: flags drafts with 0 accesses older than this. Reported separately from bucket scoring — surfaces promote-or-drop candidates the thresholds miss. Default: 7.",
-        },
-      },
-      required: [],
-    },
-  },
-  harmony_purge_memories: {
-    description:
-      "Bulk-delete memory entities matching filters within a project. Requires at least one narrowing filter (tier, scope, type, olderThanDays, maxConfidence, tags). Dry-run by default — preview what would be deleted before executing.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        workspaceId: {
-          type: "string",
-          description: "Workspace ID (optional if context set)",
-        },
-        projectId: {
-          type: "string",
-          description:
-            "Project ID (required — purge is project-scoped). Falls back to active project context.",
-        },
-        dryRun: {
-          type: "boolean",
-          description:
-            "Preview what would be deleted without executing (default: true)",
-        },
-        tier: {
-          type: "string",
-          enum: ["draft", "episode", "reference"],
-          description: 'Filter by memory tier (e.g. "draft")',
-        },
-        scope: {
-          type: "string",
-          description:
-            'Filter by scope (e.g. "private", "project", "workspace")',
-        },
-        type: {
-          type: "string",
-          description:
-            'Filter by entity type (e.g. "error", "pattern", "lesson", "decision")',
-        },
-        olderThanDays: {
-          type: "number",
-          description:
-            "Only include entities not accessed in at least this many days",
-        },
-        maxConfidence: {
-          type: "number",
-          description:
-            "Only include entities with confidence at or below this value (e.g. 0.3 for low-confidence junk)",
-        },
-        tags: {
-          type: "array",
-          items: { type: "string" },
-          description: "Only include entities matching these tags",
-        },
-      },
-      required: [],
-    },
-  },
-};
-
-// Resource URIs
-const RESOURCES = [
-  {
-    uri: "harmony://context",
-    name: "Current Context",
-    description: "Current active workspace and project",
-    mimeType: "application/json",
-  },
-];
-
-/**
- * Reusable end-session pipeline: learning extraction, feedback scoring, lifecycle maintenance.
- * Called by both explicit harmony_end_agent_session and auto-session timeout/card-switch.
- */
-export async function runEndSessionPipeline(
-  client: HarmonyApiClient,
-  deps: ToolDeps,
-  cardId: string,
-  sessionStatus: "completed" | "paused",
-  endProgressPercent?: number,
-  sessionData?: {
-    agent_identifier?: string;
-    agent_name?: string;
-    current_task?: string;
-    blockers?: string[];
-    progress_percent?: number;
-    created_at?: string;
-  },
-): Promise<{
-  learningsExtracted: number;
-  feedbackAdjusted: number;
-  maintenance?: {
-    archived: number;
-    pruned: number;
-    promoted: number;
-    reviewed: number;
-  };
-}> {
-  let learningsExtracted = 0;
-  let feedbackAdjusted = 0;
-  let maintenanceResult:
-    | { archived: number; pruned: number; promoted: number; reviewed: number }
-    | undefined;
-
-  // Fetch card details for learning extraction
-  let cardTitle = "";
-  let cardLabels: string[] = [];
-  let cardDescription = "";
-  let cardSubtasks: Array<{ title: string; done: boolean }> = [];
-  try {
-    const { card } = await client.getCard(cardId);
-    const typedCard = card as {
-      title?: string;
-      description?: string;
-      labels?: Array<{ id: string; name: string }>;
-      subtasks?: Array<{ title: string; done: boolean }>;
-    };
-    cardTitle = typedCard.title || "";
-    cardLabels = (typedCard.labels || []).map((l) => l.name);
-    cardDescription = typedCard.description || "";
-    cardSubtasks = (typedCard.subtasks || []).map((s) => ({
-      title: s.title,
-      done: s.done,
-    }));
+/**
+ * Reusable end-session pipeline.
+ * Called by both explicit harmony_end_agent_session and auto-session timeout/card-switch.
+ *
+ * Phase 0 (memory architecture v2): AGP-specific steps (active learning extraction,
+ * recordContextFeedback, runLifecycleMaintenance, auto-consolidation) have been
+ * removed. Only the agent label cleanup remains.
+ * Feedback writes (last_accessed_at + confidence per §10.3 of
+ * docs/superpowers/plans/2026-05-07-memory-architecture-v2.md) will be reintroduced
+ * in Phase 2 when the rebuilt context-assembly pipeline lands.
+ */
+export async function runEndSessionPipeline(
+  client: HarmonyApiClient,
+  _deps: ToolDeps,
+  cardId: string,
+  sessionStatus: "completed" | "paused",
+): Promise<{
+  learningsExtracted: number;
+  feedbackAdjusted: number;
+}> {
+  // Fetch card details so we can clean up the "agent" label on completion.
+  try {
+    const { card } = await client.getCard(cardId);
+    const typedCard = card as {
+      title?: string;
+      description?: string;
+      labels?: Array<{ id: string; name: string }>;
+      subtasks?: Array<{ title: string; done: boolean }>;
+    };
 
     // Remove "agent" label when session is completed (not paused)
     if (sessionStatus === "completed" && typedCard.labels?.length) {
@@ -1945,166 +1570,12 @@ export async function runEndSessionPipeline(
       }
     }
   } catch {
-    // Card fetch failed, continue with defaults
-  }
-
-  // Active learning: extract memories from session
-  try {
-    let sessionDurationMs: number | undefined;
-    if (sessionData?.created_at) {
-      const startTime = new Date(sessionData.created_at).getTime();
-      if (!Number.isNaN(startTime)) {
-        sessionDurationMs = Date.now() - startTime;
-      }
-    }
-
-    const sessionContext: SessionContext = {
-      cardId,
-      cardTitle,
-      cardLabels,
-      agentIdentifier: sessionData?.agent_identifier || "unknown",
-      agentName: sessionData?.agent_name || "Unknown Agent",
-      status: sessionStatus,
-      progressPercent: endProgressPercent,
-      blockers: sessionData?.blockers || undefined,
-      currentTask: sessionData?.current_task || undefined,
-      sessionDurationMs,
-      cardDescription: cardDescription || undefined,
-      cardSubtasks: cardSubtasks.length > 0 ? cardSubtasks : undefined,
-    };
-
-    const learningResult = await extractLearnings(client, sessionContext);
-    learningsExtracted = learningResult.count;
-  } catch {
-    // Learning extraction failed, non-fatal
-  }
-
-  // Agent performance profile: refresh materialized view + upsert knowledge entity
-  try {
-    const workspaceId = deps.getActiveWorkspaceId();
-    const agentId = sessionData?.agent_identifier || "unknown";
-    if (workspaceId && agentId !== "unknown") {
-      // Fire-and-forget: refresh + upsert agent profile entity
-      (async () => {
-        try {
-          await client.refreshAgentProfiles(workspaceId);
-          const { profile } = await client.getAgentProfile(
-            workspaceId,
-            agentId,
-          );
-          if (profile) {
-            const p = profile as Record<string, unknown>;
-            const title = `Agent Profile: ${agentId}`;
-            const content = [
-              `## ${agentId} Performance Profile`,
-              "",
-              `- **Total sessions:** ${p.total_sessions}`,
-              `- **Completed:** ${p.completed_sessions} (${p.completion_rate_pct}%)`,
-              `- **Paused:** ${p.paused_sessions}`,
-              `- **Blocked:** ${p.blocked_sessions}`,
-              `- **Avg duration:** ${Math.round(Number(p.avg_active_duration_ms || 0) / 1000)}s`,
-              `- **Avg progress:** ${p.avg_completion_progress}%`,
-              `- **First session:** ${p.first_session_at}`,
-              `- **Last session:** ${p.last_session_at}`,
-            ].join("\n");
-
-            // Find existing agent entity to update, or create new
-            const existing = await client.listMemoryEntities({
-              workspace_id: workspaceId,
-              type: "agent",
-              limit: 50,
-            });
-            const entities = (existing.entities || []) as Array<{
-              id: string;
-              title: string;
-              agent_identifier?: string;
-            }>;
-            const match = entities.find(
-              (e) => e.title === title || e.agent_identifier === agentId,
-            );
-
-            if (match) {
-              await client.updateMemoryEntity(match.id, {
-                content,
-                confidence: 1.0,
-                metadata: p,
-              });
-            } else {
-              await client.createMemoryEntity({
-                workspace_id: workspaceId,
-                type: "agent",
-                scope: "workspace",
-                memory_tier: "reference",
-                title,
-                content,
-                confidence: 1.0,
-                tags: ["agent-profile", agentId],
-                agent_identifier: agentId,
-                metadata: p,
-              });
-            }
-          }
-        } catch {
-          // Non-fatal: profile upsert failed
-        }
-      })();
-    }
-  } catch {
-    // Non-fatal: agent profile refresh failed
-  }
-
-  // Feedback-driven scoring
-  try {
-    const feedbackResult = await recordContextFeedback(
-      client,
-      cardId,
-      sessionStatus,
-      endProgressPercent,
-      (sessionData?.blockers?.length ?? 0) > 0,
-    );
-    feedbackAdjusted = feedbackResult.adjusted;
-  } catch {
-    // Feedback recording failed, non-fatal
-  }
-
-  // Lifecycle maintenance
-  try {
-    const workspaceId = deps.getActiveWorkspaceId();
-    if (workspaceId) {
-      const projectId = deps.getActiveProjectId() || undefined;
-
-      maintenanceResult = await runLifecycleMaintenance(
-        client,
-        workspaceId,
-        projectId,
-      );
-
-      // Auto-consolidation: if workspace has many draft/episode entities
-      const listResult = await client.listMemoryEntities({
-        workspace_id: workspaceId,
-        project_id: projectId,
-        limit: 100,
-      });
-      const draftEpisodeCount = (
-        (listResult.entities || []) as Array<{ memory_tier?: string }>
-      ).filter(
-        (e) => e.memory_tier === "draft" || e.memory_tier === "episode",
-      ).length;
-      if (draftEpisodeCount > 50) {
-        consolidateMemories(client, workspaceId, projectId, {
-          dryRun: false,
-          minClusterSize: 2,
-        }).catch(() => {});
-      }
-    }
-  } catch {
-    // Lifecycle maintenance failed, non-fatal
+    // Card fetch failed, continue
   }
 
   return {
-    learningsExtracted,
-    feedbackAdjusted,
-    ...(maintenanceResult && { maintenance: maintenanceResult }),
+    learningsExtracted: 0,
+    feedbackAdjusted: 0,
   };
 }
 
@@ -2752,72 +2223,18 @@ async function handleToolCall(
       // Mark as explicit so auto-session won't interfere
       markExplicit(cardId, { agentIdentifier, agentName });
 
-      // Initialize memory session tracking for action visibility
-      initMemorySession(cardId, agentIdentifier, agentName);
-
-      // Prefetch relevant context (non-blocking, best-effort)
-      let prefetchedMemoryIds: string[] = [];
-      try {
-        const workspaceId = deps.getActiveWorkspaceId();
-        if (workspaceId) {
-          // Get card details for context
-          const { card } = await client.getCard(cardId);
-          const typedCard = card as {
-            title?: string;
-            description?: string;
-            labels?: Array<{ name: string }>;
-          };
-          const cardLabels = (typedCard.labels || []).map((l) => l.name);
-          const taskContext = [
-            typedCard.title || "",
-            typedCard.description || "",
-          ]
-            .filter(Boolean)
-            .join(" ");
-
-          // Assemble context to find seed entities
-          const assembled = await assembleContext({
-            workspaceId,
-            projectId: getActiveProjectId() || undefined,
-            taskContext,
-            cardLabels,
-            cardId,
-            tokenBudget: 2000, // Smaller budget for prefetch
-            client,
-          });
-
-          prefetchedMemoryIds = assembled.memories.map((m) => m.id);
-
-          // Track assembly for feedback loop
-          if (assembled.manifest.assemblyId) {
-            cacheManifest(assembled.manifest);
-            trackSessionAssembly(cardId, assembled.manifest.assemblyId);
-          }
-
-          // Walk graph from seed entities to discover more context
-          if (prefetchedMemoryIds.length > 0) {
-            const graphResult = await discoverRelatedContext(
-              client,
-              prefetchedMemoryIds.slice(0, 5), // Limit seeds
-              2, // 2 hops
-              10, // Max 10 entities
-            );
-            const additionalIds = graphResult.entities
-              .map((e) => e.id)
-              .filter((id) => !prefetchedMemoryIds.includes(id));
-            prefetchedMemoryIds.push(...additionalIds);
-          }
-        }
-      } catch {
-        // Prefetch failed, non-fatal
-      }
+      // Initialize memory session tracking for action visibility. Capture the
+      // backend session id so working-memory writes (`scope: 'session'`) bind
+      // to the same `card_agent_context` row that progress/end calls target.
+      const agentSessionId = (result.session as { id?: string } | null)?.id;
+      initMemorySession(cardId, agentIdentifier, agentName, agentSessionId);
 
       return {
         success: true,
         assignedTo,
         movedTo,
         labelsAdded,
-        prefetchedMemoryCount: prefetchedMemoryIds.length,
+        prefetchedMemoryCount: 0,
         ...result,
       };
     }
@@ -2875,34 +2292,8 @@ async function handleToolCall(
         ...(mergedRecentActions && { recentActions: mergedRecentActions }),
       });
 
-      // Mid-session learning extraction (fire-and-forget)
-      let midSessionLearnings = 0;
-      try {
-        const { card } = await client.getCard(cardId);
-        const typedCard = card as {
-          title?: string;
-        };
-        const midResult = await extractMidSessionLearnings(client, {
-          cardId,
-          cardTitle: typedCard.title || "",
-          agentIdentifier,
-          agentName,
-          currentTask: args.currentTask as string | undefined,
-          status: args.status as
-            | "working"
-            | "blocked"
-            | "waiting"
-            | "paused"
-            | undefined,
-          blockers: args.blockers as string[] | undefined,
-          progressPercent,
-        });
-        midSessionLearnings = midResult.count;
-      } catch {
-        // Non-fatal: mid-session learning extraction failure
-      }
-
-      return { success: true, midSessionLearnings, ...result };
+      // Phase 0 (memory architecture v2): mid-session learning extraction removed.
+      return { success: true, midSessionLearnings: 0, ...result };
     }
 
     case "harmony_end_agent_session": {
@@ -2969,21 +2360,11 @@ async function handleToolCall(
       }
 
       // Run shared end-session pipeline (learning, feedback, maintenance)
-      const sessionObj = result.session as {
-        agent_identifier?: string;
-        agent_name?: string;
-        current_task?: string;
-        blockers?: string[];
-        progress_percent?: number;
-        created_at?: string;
-      };
       const pipelineResult = await runEndSessionPipeline(
         client,
         deps,
         cardId,
         sessionStatus,
-        endProgressPercent,
-        sessionObj,
       );
 
       return {
@@ -2992,12 +2373,6 @@ async function handleToolCall(
         movedTo,
         learningsExtracted: pipelineResult.learningsExtracted,
         feedbackAdjusted: pipelineResult.feedbackAdjusted,
-        ...(pipelineResult.maintenance &&
-          (pipelineResult.maintenance.archived > 0 ||
-            pipelineResult.maintenance.pruned > 0 ||
-            pipelineResult.maintenance.promoted > 0) && {
-            maintenance: pipelineResult.maintenance,
-          }),
         ...result,
       };
     }
@@ -3011,21 +2386,8 @@ async function handleToolCall(
       return { success: true, ...result };
     }
 
-    case "harmony_get_agent_profile": {
-      const workspaceId = args.workspaceId || deps.getActiveWorkspaceId();
-      if (!workspaceId) {
-        return {
-          success: false,
-          error: "No workspace context. Provide workspaceId or set context.",
-        };
-      }
-      const agentIdentifier = args.agentIdentifier || "claude-code";
-
-      const result = await client.getAgentProfile(workspaceId, agentIdentifier);
-      return { success: true, ...result };
-    }
-
     // Prompt generation
+    // TODO Phase 1: rebuild full context assembly per docs/superpowers/plans/2026-05-07-memory-architecture-v2.md §10
     case "harmony_generate_prompt": {
       // Resolve card ID — either directly or via short ID
       let cardId: string;
@@ -3047,41 +2409,28 @@ async function handleToolCall(
         throw new Error("Either cardId or shortId must be provided");
       }
 
-      // Parse MCP-specific context options
-      const contextOptions: Record<string, boolean> = {};
-      if (args.includeSubtasks !== undefined) {
-        contextOptions.includeSubtasks =
-          args.includeSubtasks === true || args.includeSubtasks === "true";
-      }
-      if (args.includeLinks !== undefined) {
-        contextOptions.includeLinks =
-          args.includeLinks === true || args.includeLinks === "true";
-      }
-      if (args.includeDescription !== undefined) {
-        contextOptions.includeDescription =
-          args.includeDescription === true ||
-          args.includeDescription === "true";
+      // Phase 0: minimal placeholder prompt with no context assembly.
+      // Fetch just the card title/description so the agent has the basics.
+      let cardTitle = "";
+      let cardDescription = "";
+      try {
+        const { card } = await client.getCard(cardId);
+        const typedCard = card as { title?: string; description?: string };
+        cardTitle = typedCard.title || "";
+        cardDescription = typedCard.description || "";
+      } catch {
+        // Card fetch failed; return an empty task description.
       }
 
-      // Delegate to the shared prompt generation pipeline
-      const result = await client.generateCardPrompt({
-        cardId,
-        workspaceId: deps.getActiveWorkspaceId() || "",
-        projectId:
-          (args.projectId as string) || getActiveProjectId() || undefined,
-        variant: (args.variant as PromptVariant) || "execute",
-        customConstraints: args.customConstraints as string | undefined,
-        contextOptions,
-      });
-
-      // MCP-specific: cache the assembly manifest for the feedback loop
-      if (result.assemblyId) {
-        trackSessionAssembly(cardId, result.assemblyId);
-      }
+      const taskBlock = [cardTitle, cardDescription]
+        .filter(Boolean)
+        .join("\n\n");
+      const prompt = `Here is the task: ${taskBlock || "(no description available)"}`;
 
       return {
         success: true,
-        ...result,
+        prompt,
+        cardId,
       };
     }
 
@@ -3098,14 +2447,52 @@ async function handleToolCall(
       }
       const entityType = (args.type as string) || "context";
       const entityTags = (args.tags as string[]) || [];
-      // Use session's agent identifier if available, otherwise null
+
+      // Working-memory binding (plan §12 Phase 1, §13.1 D3). The caller may
+      // pass `scope: 'session'` as an alias; resolve it to the active
+      // `card_agent_context` id so the row carries `session:<uuid>` on disk.
+      // Other scope values pass through unchanged.
       const activeMemSession = getActiveMemorySession();
+      const entityScope =
+        resolveSessionScope(
+          args.scope as string | undefined,
+          activeMemSession?.agentSessionId,
+        ) || "project";
+
+      // Utility Floor (plan §4.5.1) — write admission control.
+      // Rejects tag-concat slop, frequency-meta titles, self-referential
+      // operational notes, bare type prefixes, under-specific titles, and
+      // operational data dumps. Session-scope memories are exempt.
+      const floorRejection = validateMemoryQuality({
+        title,
+        content,
+        type: entityType,
+        scope: entityScope,
+        source_trust: args.source_trust as string | undefined,
+        tags: entityTags,
+      });
+      if (floorRejection) {
+        throw new Error(
+          `Memory rejected by Utility Floor [${floorRejection.rule}]: ${floorRejection.message}`,
+        );
+      }
+
+      // Importance: caller-provided > per-type default (plan §7.1).
+      // auto_score_importance is documented as an LLM-rating opt-in but the
+      // actual LLM call is deferred to a follow-up commit; currently it falls
+      // through to the type default, same as omission.
+      const callerImportance =
+        args.importance !== undefined
+          ? z.number().int().min(1).max(10).parse(args.importance)
+          : undefined;
+
+      // Use session's agent identifier if available, otherwise null
       const result = await client.createMemoryEntity({
         workspace_id: workspaceId,
         project_id:
           (args.projectId as string) || deps.getActiveProjectId() || undefined,
         type: entityType,
-        scope: (args.scope as string) || "project",
+        scope: entityScope,
         memory_tier: (args.tier as string) || undefined,
         title,
         content,
@@ -3114,6 +2501,7 @@ async function handleToolCall(
           args.confidence !== undefined
             ? z.number().min(0).max(1).parse(args.confidence)
             : undefined,
+        importance: callerImportance,
         tags: entityTags.length > 0 ? entityTags : undefined,
         agent_identifier: activeMemSession?.agentIdentifier || undefined,
       });
@@ -3132,32 +2520,8 @@ async function handleToolCall(
         ).catch(() => {});
       }
 
-      // Semantic contradiction detection (uses hybrid search instead of naive type+tag matching)
-      let potentialContradictions: Array<{
-        entityId: string;
-        title: string;
-        type: string;
-        tags: string[];
-      }> = [];
-      const newEntityId = (result.entity as any)?.id;
-      if (newEntityId) {
-        try {
-          potentialContradictions = await detectContradictions(
-            client,
-            newEntityId,
-            entityType,
-            title,
-            content,
-            entityTags,
-            workspaceId,
-            (args.projectId as string) ||
-              deps.getActiveProjectId() ||
-              undefined,
-          );
-        } catch {
-          // Don't block creation if contradiction detection fails
-        }
-      }
+      // Phase 0 (memory architecture v2): semantic contradiction detection removed
+      // along with the active-learning module. Will be revisited in Phase 2.
 
       // Track memory write action and flush (fire-and-forget)
       if (activeMemSession) {
@@ -3168,14 +2532,6 @@ async function handleToolCall(
       return {
         success: true,
         ...result,
-        ...(potentialContradictions.length > 0 && {
-          potentialContradictions: potentialContradictions.map((c) => ({
-            id: c.entityId,
-            title: c.title,
-            tags: c.tags,
-          })),
-          contradictionNote: `Found ${potentialContradictions.length} semantically similar memor${potentialContradictions.length === 1 ? "y" : "ies"} of same type that may contradict. 'contradicts' relations created automatically. Review these to resolve or confirm.`,
-        }),
       };
     }
 
@@ -3187,74 +2543,212 @@ async function handleToolCall(
           "No workspace specified. Use harmony_set_workspace_context or provide workspaceId.",
         );
       }
-      const queryOpts = {
-        workspace_id: workspaceId,
-        project_id:
-          (args.projectId as string) || deps.getActiveProjectId() || undefined,
-        type: args.type as string | undefined,
-        scope: args.scope as string | undefined,
-        tags: args.tags as string[] | undefined,
-        min_confidence: args.minConfidence as number | undefined,
-        q: args.query as string | undefined,
-        limit: args.limit as number | undefined,
-      };
+      const requestedLimit = args.limit as number | undefined;
+      const topK = args.top_k as number | undefined;
+      const budgetTokens = args.budget_tokens as number | undefined;
+      const includeSuperseded = Boolean(args.include_superseded);
+      const queryText = args.query as string | undefined;
+
+      // Over-fetch when top_k is smaller than limit so the rescorer has
+      // more candidates to choose from. Cap at 200 to keep the round-trip
+      // bounded.
+      const fetchLimit = Math.min(
+        Math.max(requestedLimit ?? 20, topK ?? 0, 50),
+        200,
+      );
+
+      const projectId =
+        (args.projectId as string) || deps.getActiveProjectId() || undefined;
+
+      // Resolve the working-memory alias before anything else: callers pass
+      // `scope: 'session'` and we bind it to the active session id. When the
+      // scope was implicit (undefined) we will instead prepend session
+      // memories on top of the long-term result below.
+      const recallMemSession = getActiveMemorySession();
+      const explicitScope = resolveSessionScope(
+        args.scope as string | undefined,
+        recallMemSession?.agentSessionId,
+      );
+
+      // When the caller asked for a specific scope (resolved or otherwise),
+      // honor it exactly. Without a caller scope we default to "all
+      // long-term scopes" — i.e. exclude any working-memory rows from the
+      // long-term mix because they get prepended separately below.
+      const userScopeFilter = explicitScope;
+      const excludeSessionFromLongTerm = explicitScope === undefined;
+
+      // Hybrid retrieval (plan §6.2): when a free-text query is provided,
+      // route through /memory/search which fuses pgvector cosine + Postgres
+      // FTS via the hybrid_search_knowledge_entities RPC (RRF, k=50). The
+      // returned ranking becomes the relevance signal feeding Park's
+      // rescorer. When no query is given, fall back to filter-only listing
+      // with neutral 0.5 relevance — recency + importance still differentiate.
+      let entities: any[];
+      let relevanceMap: Map<string, number>;
+
+      if (queryText) {
+        const searchResult = await client.searchMemoryEntities(
+          workspaceId,
+          queryText,
+          {
+            project_id: projectId,
+            type: args.type as string | undefined,
+            limit: fetchLimit,
+          },
+        );
+        entities = (searchResult.entities ?? []) as any[];
+
+        // Post-filter the rest of the params client-side. Hybrid search RPC
+        // exposes only project_id + type; tags / scope / minConfidence /
+        // include_superseded are applied here on the rank-ordered set.
+        const requestedTags = args.tags as string[] | undefined;
+        const minConfidence = args.minConfidence as number | undefined;
+        if (userScopeFilter) {
+          entities = entities.filter((e) => e?.scope === userScopeFilter);
+        } else if (excludeSessionFromLongTerm) {
+          // Working-memory rows are surfaced via the prepend pass; keep them
+          // out of the long-term mix so the same row never shows twice.
+          entities = entities.filter((e) => !isSessionScope(e?.scope));
+        }
+        if (requestedTags && requestedTags.length > 0) {
+          const wanted = new Set(requestedTags);
+          entities = entities.filter((e) =>
+            (e?.tags ?? []).some((t: string) => wanted.has(t)),
+          );
+        }
+        if (typeof minConfidence === "number") {
+          entities = entities.filter(
+            (e) =>
+              typeof e?.confidence === "number" &&
+              e.confidence >= minConfidence,
+          );
+        }
+        if (!includeSuperseded) {
+          entities = entities.filter((e) => !e?.superseded_at);
+        }
+
+        relevanceMap = relevanceFromRank(entities as Array<{ id: string }>);
+      } else {
+        const { entities: listed } = await client.listMemoryEntities({
+          workspace_id: workspaceId,
+          project_id: projectId,
+          type: args.type as string | undefined,
+          scope: userScopeFilter,
+          tags: args.tags as string[] | undefined,
+          min_confidence: args.minConfidence as number | undefined,
+          limit: fetchLimit,
+          include_superseded: includeSuperseded,
+        });
+        entities = listed as any[];
+        if (excludeSessionFromLongTerm) {
+          // Match the with-query branch: prevent working memory from
+          // double-appearing once we prepend the session pool.
+          entities = entities.filter((e) => !isSessionScope(e?.scope));
+        }
+        relevanceMap = new Map(); // neutral baseline; rescore uses 0.5
+      }
+
+      // Park rescore (plan §6.2 step 4). When the hybrid path supplied a
+      // relevance map, top-ranked entities dominate the relevance term;
+      // otherwise the neutral 0.5 baseline lets recency + importance
+      // differentiate.
+      const scored = rescore(entities as ParkInput[], {
+        relevance: relevanceMap,
+      });
 
-      // Fetch both markdown (for display) and JSON (for lifecycle evaluation) in parallel
-      const [markdown, { entities }] = await Promise.all([
-        client.listMemoryEntitiesMarkdown(queryOpts),
-        client.listMemoryEntities(queryOpts),
-      ]);
+      // Trim to top_k (or the original limit if top_k was not provided).
+      const finalCount = topK ?? requestedLimit ?? 20;
+      let trimmed = scored.slice(0, finalCount);
 
-      // Evaluate lifecycle and auto-promote eligible entities (fire-and-forget)
-      if (entities.length > 0) {
+      // Token budget pass.
+      if (typeof budgetTokens === "number" && budgetTokens > 0) {
+        trimmed = fitToBudget(trimmed, budgetTokens);
+      }
+
+      // Touch access timestamps for the entities we returned (basic Park
+      // recency trail). Non-blocking.
+      if (trimmed.length > 0) {
         Promise.all(
-          entities.map(async (entity: any) => {
-            if (!entity.memory_tier || !entity.created_at) return;
+          trimmed.map(async ({ entity }: { entity: any }) => {
             try {
-              // Touch access count via API (triggers server-side touch_knowledge_entity)
               await client.updateMemoryEntity(entity.id, {
                 metadata: {
                   ...(entity.metadata || {}),
                   _last_recall: new Date().toISOString(),
                 },
               });
-
-              const lifecycle = evaluateLifecycle({
-                memory_tier: entity.memory_tier,
-                confidence: entity.confidence ?? 1.0,
-                access_count: entity.access_count ?? 0,
-                last_accessed_at: entity.last_accessed_at,
-                created_at: entity.created_at,
-              });
-
-              if (
-                lifecycle.promotion.eligible &&
-                lifecycle.promotion.targetTier
-              ) {
-                await client.updateMemoryEntity(entity.id, {
-                  memory_tier: lifecycle.promotion.targetTier,
-                  metadata: {
-                    ...(entity.metadata || {}),
-                    promoted_at: new Date().toISOString(),
-                    promotion_reason: lifecycle.promotion.reason,
-                  },
-                });
-              }
             } catch (_) {
-              // Non-critical: don't fail recall if promotion check fails
+              // Non-critical
             }
           }),
         ).catch(() => {});
       }
 
+      // Working-memory prepend (plan §12 Phase 1). When a session is active
+      // and the caller did not pin a scope, fetch session-scoped memories for
+      // the current `card_agent_context` row and surface them ahead of the
+      // long-term Park-rescored set. Skipped when the caller explicitly
+      // asked for any other scope so the result honors the request.
+      let sessionEntities: any[] = [];
+      if (excludeSessionFromLongTerm && recallMemSession?.agentSessionId) {
+        try {
+          const { entities: sessionListed } = await client.listMemoryEntities({
+            workspace_id: workspaceId,
+            project_id: projectId,
+            scope: sessionScopeFor(recallMemSession.agentSessionId),
+            limit: 50,
+            include_superseded: includeSuperseded,
+          });
+          sessionEntities = (sessionListed ?? []) as any[];
+        } catch (_) {
+          // Session pool is best-effort; long-term recall must still succeed.
+          sessionEntities = [];
+        }
+      }
+
       // Track memory read (batched on flush)
-      const recallMemSession = getActiveMemorySession();
       if (recallMemSession) {
         incrementMemoryReads(recallMemSession.cardId);
       }
 
-      return markdown || "No memories found.";
-    }
+      if (trimmed.length === 0 && sessionEntities.length === 0) {
+        return "No memories found.";
+      }
+
+      // Render rescored entities as markdown, including the score breakdown
+      // for debuggability. Session memories render first under their own
+      // heading so consumers can tell working memory from long-term recall.
+      const lines: string[] = [];
+
+      if (sessionEntities.length > 0) {
+        lines.push("## Working memory (session)\n");
+        for (const e of sessionEntities) {
+          const tagStr = e.tags?.length ? ` \`${e.tags.join(", ")}\`` : "";
+          lines.push(
+            `### ${e.title}\n` +
+              `- **type:** ${e.type} · **scope:** ${e.scope} · **tier:** ${e.memory_tier}${tagStr}\n\n` +
+              `${(e.content ?? "").slice(0, 400)}${(e.content ?? "").length > 400 ? "…" : ""}\n`,
+          );
+        }
+      }
+
+      if (trimmed.length > 0) {
+        if (sessionEntities.length > 0) {
+          lines.push("## Long-term memory\n");
+        }
+        for (const s of trimmed) {
+          const e = s.entity as any;
+          const tagStr = e.tags?.length ? ` \`${e.tags.join(", ")}\`` : "";
+          lines.push(
+            `### ${e.title}\n` +
+              `- **type:** ${e.type} · **scope:** ${e.scope} · **tier:** ${e.memory_tier}\n` +
+              `- **score:** ${s.score.toFixed(3)} (relevance ${s.relevance.toFixed(2)}, recency ${s.recency.toFixed(2)}, importance ${s.importance.toFixed(2)})${tagStr}\n\n` +
+              `${(e.content ?? "").slice(0, 400)}${(e.content ?? "").length > 400 ? "…" : ""}\n`,
+          );
+        }
+      }
+      return lines.join("\n---\n");
+    }
 
     case "harmony_update_memory": {
       const entityId = z.string().uuid().parse(args.entityId);
@@ -3619,16 +3113,7 @@ async function handleToolCall(
               workspaceId,
               plan.project_id,
             ).catch(() => {});
-            detectContradictions(
-              client,
-              results.memoryEntityId,
-              "lesson",
-              title,
-              summary,
-              tags,
-              workspaceId,
-              plan.project_id,
-            ).catch(() => {});
+            // Phase 0 (memory architecture v2): contradiction detection removed.
           }
         } catch (_) {
           /* best-effort */
@@ -3642,400 +3127,6 @@ async function handleToolCall(
       };
     }
 
-    case "harmony_debug_context": {
-      const entityId = z.string().uuid().parse(args.entityId);
-      const taskContext = z.string().min(1).max(2000).parse(args.taskContext);
-      const cardLabels = (args.cardLabels as string[]) || [];
-
-      // Fetch the entity
-      const entityResult = await client.getMemoryEntity(entityId);
-      const entity = mapToContextEntity(entityResult.entity);
-
-      // Compute relevance score
-      const { score, reasons } = computeRelevanceScore(
-        entity,
-        taskContext,
-        cardLabels,
-      );
-
-      // Compute lifecycle status
-      const lifecycle = evaluateLifecycle({
-        memory_tier: entity.memory_tier as "draft" | "episode" | "reference",
-        confidence: entity.confidence,
-        access_count: entity.access_count,
-        last_accessed_at: entity.last_accessed_at,
-        created_at: entity.updated_at, // using updated_at as proxy
-      });
-
-      return {
-        success: true,
-        entity: {
-          id: entity.id,
-          title: entity.title,
-          type: entity.type,
-          tier: entity.memory_tier,
-          confidence: entity.confidence,
-          accessCount: entity.access_count,
-        },
-        relevance: {
-          score: Math.round(score * 1000) / 1000,
-          reasons,
-          wouldBeIncluded: score >= 0.1,
-          threshold: 0.1,
-        },
-        lifecycle: {
-          decayScore: Math.round(lifecycle.decay.score * 1000) / 1000,
-          daysSinceAccess: Math.round(lifecycle.decay.daysSinceAccess),
-          promotionEligible: lifecycle.promotion.eligible,
-          promotionTarget: lifecycle.promotion.targetTier,
-          shouldArchive: lifecycle.shouldArchive,
-          shouldFlagForReview: lifecycle.shouldFlagForReview,
-        },
-        suggestions: [
-          ...(lifecycle.promotion.eligible
-            ? [
-                `Eligible for promotion to ${lifecycle.promotion.targetTier}: ${lifecycle.promotion.reason}`,
-              ]
-            : []),
-          ...(lifecycle.shouldArchive
-            ? [`Consider archiving: ${lifecycle.archiveReason}`]
-            : []),
-          ...(lifecycle.shouldFlagForReview
-            ? [`Flagged for review: ${lifecycle.reviewReason}`]
-            : []),
-          ...(score < 0.1
-            ? [
-                "Below relevance threshold - consider adding more specific tags or updating content",
-              ]
-            : []),
-        ],
-      };
-    }
-
-    case "harmony_export_memory_graph": {
-      const workspaceId =
-        (args.workspaceId as string) || deps.getActiveWorkspaceId();
-      if (!workspaceId) {
-        throw new Error(
-          "No workspace specified. Use harmony_set_workspace_context or provide workspaceId.",
-        );
-      }
-      const projectId =
-        (args.projectId as string) || deps.getActiveProjectId() || undefined;
-      const limit = (args.limit as number) || 50;
-
-      // Fetch entities
-      const result = await client.listMemoryEntities({
-        workspace_id: workspaceId,
-        project_id: projectId,
-        limit,
-      });
-
-      const entities = (result.entities || []) as Array<{
-        id: string;
-        title: string;
-        type: string;
-        memory_tier?: string;
-        confidence: number;
-      }>;
-
-      // Build DOT graph
-      const tierColors: Record<string, string> = {
-        draft: "#FFEB3B", // yellow
-        episode: "#2196F3", // blue
-        reference: "#4CAF50", // green
-      };
-
-      const typeShapes: Record<string, string> = {
-        error: "octagon",
-        solution: "diamond",
-        pattern: "hexagon",
-        decision: "house",
-        lesson: "ellipse",
-        preference: "parallelogram",
-      };
-
-      const lines: string[] = [
-        "digraph KnowledgeGraph {",
-        "  rankdir=LR;",
-        "  node [style=filled, fontsize=10];",
-        "",
-      ];
-
-      // Add nodes
-      for (const entity of entities) {
-        const tier = entity.memory_tier || "reference";
-        const color = tierColors[tier] || "#9E9E9E";
-        const shape = typeShapes[entity.type] || "box";
-        const label =
-          entity.title.length > 40
-            ? entity.title.slice(0, 37) + "..."
-            : entity.title;
-        const safeLabel = label.replace(/"/g, '\\"');
-        lines.push(
-          `  "${entity.id.slice(0, 8)}" [label="${safeLabel}\\n(${entity.type}, ${tier})", fillcolor="${color}", shape=${shape}];`,
-        );
-      }
-
-      // Fetch relations for each entity and add edges
-      const entityIds = new Set(entities.map((e) => e.id));
-      const addedEdges = new Set<string>();
-
-      for (const entity of entities.slice(0, 20)) {
-        // Limit graph API calls
-        try {
-          const related = await client.getRelatedEntities(entity.id);
-
-          // Outgoing relations: { id, relation_type, target: { id, ... } }
-          for (const raw of related.outgoing || []) {
-            const rel = raw as {
-              id: string;
-              relation_type: string;
-              source_id?: string;
-              target_id?: string;
-              target?: { id: string };
-              source?: { id: string };
-            };
-            const sourceId = rel.source_id || entity.id;
-            const targetId = rel.target_id || rel.target?.id;
-            if (
-              targetId &&
-              entityIds.has(sourceId) &&
-              entityIds.has(targetId)
-            ) {
-              const edgeKey = `${sourceId}-${targetId}-${rel.relation_type}`;
-              if (!addedEdges.has(edgeKey)) {
-                addedEdges.add(edgeKey);
-                lines.push(
-                  `  "${sourceId.slice(0, 8)}" -> "${targetId.slice(0, 8)}" [label="${rel.relation_type}"];`,
-                );
-              }
-            }
-          }
-
-          // Incoming relations: { id, relation_type, source: { id, ... } }
-          for (const raw of related.incoming || []) {
-            const rel = raw as {
-              id: string;
-              relation_type: string;
-              source_id?: string;
-              target_id?: string;
-              target?: { id: string };
-              source?: { id: string };
-            };
-            const sourceId = rel.source_id || rel.source?.id;
-            const targetId = rel.target_id || entity.id;
-            if (
-              sourceId &&
-              entityIds.has(sourceId) &&
-              entityIds.has(targetId)
-            ) {
-              const edgeKey = `${sourceId}-${targetId}-${rel.relation_type}`;
-              if (!addedEdges.has(edgeKey)) {
-                addedEdges.add(edgeKey);
-                lines.push(
-                  `  "${sourceId.slice(0, 8)}" -> "${targetId.slice(0, 8)}" [label="${rel.relation_type}"];`,
-                );
-              }
-            }
-          }
-        } catch {
-          // Relation fetch failed, continue
-        }
-      }
-
-      lines.push("}");
-      const dotGraph = lines.join("\n");
-
-      return {
-        success: true,
-        format: "dot",
-        entityCount: entities.length,
-        edgeCount: addedEdges.size,
-        graph: dotGraph,
-        message: `Exported ${entities.length} entities and ${addedEdges.size} relations as DOT graph. Use Graphviz to render: echo '<graph>' | dot -Tpng -o graph.png`,
-      };
-    }
-
-    case "harmony_prune_draft": {
-      const workspaceId =
-        (args.workspaceId as string) || deps.getActiveWorkspaceId();
-      if (!workspaceId) {
-        throw new Error(
-          "No workspace specified. Use harmony_set_workspace_context or provide workspaceId.",
-        );
-      }
-      const projectId =
-        (args.projectId as string) || deps.getActiveProjectId() || undefined;
-      const dryRun = args.dryRun !== false; // default true
-      const maxAgeDays = (args.maxAgeDays as number) || 30;
-
-      // Fetch draft entities
-      const result = await client.listMemoryEntities({
-        workspace_id: workspaceId,
-        project_id: projectId,
-        limit: 100,
-      });
-
-      const drafts = (result.entities || []).filter((e: unknown) => {
-        const entity = e as { memory_tier?: string };
-        return entity.memory_tier === "draft";
-      });
-
-      const now = Date.now();
-      const stale: Array<{
-        id: string;
-        title: string;
-        ageDays: number;
-        decayScore: number;
-      }> = [];
-
-      for (const raw of drafts) {
-        const entity = raw as {
-          id: string;
-          title: string;
-          memory_tier: "draft" | "episode" | "reference";
-          confidence: number;
-          access_count: number;
-          last_accessed_at: string | null;
-          created_at: string;
-          updated_at: string;
-        };
-
-        const ageDays =
-          (now - new Date(entity.created_at).getTime()) / (1000 * 60 * 60 * 24);
-        if (ageDays < maxAgeDays) continue;
-
-        const lifecycle = evaluateLifecycle(entity);
-        stale.push({
-          id: entity.id,
-          title: entity.title,
-          ageDays: Math.round(ageDays),
-          decayScore: Math.round(lifecycle.decay.score * 100) / 100,
-        });
-      }
-
-      if (!dryRun) {
-        for (const item of stale) {
-          try {
-            await client.deleteMemoryEntity(item.id);
-          } catch {
-            // Non-fatal
-          }
-        }
-      }
-
-      return {
-        success: true,
-        dryRun,
-        totalDrafts: drafts.length,
-        staleDrafts: stale.length,
-        pruned: dryRun ? 0 : stale.length,
-        items: stale,
-        message: dryRun
-          ? `Found ${stale.length} stale drafts (>${maxAgeDays} days old). Run with dryRun=false to delete.`
-          : `Pruned ${stale.length} stale draft memories.`,
-      };
-    }
-
-    case "harmony_consolidate_memories": {
-      const workspaceId =
-        (args.workspaceId as string) || deps.getActiveWorkspaceId();
-      if (!workspaceId) {
-        throw new Error(
-          "No workspace specified. Use harmony_set_workspace_context or provide workspaceId.",
-        );
-      }
-      const projectId =
-        (args.projectId as string) || deps.getActiveProjectId() || undefined;
-      const dryRun = args.dryRun !== false; // default true
-      const minClusterSize = (args.minClusterSize as number) || 2;
-
-      const consolidationResult = await consolidateMemories(
-        client,
-        workspaceId,
-        projectId,
-        { dryRun, minClusterSize },
-      );
-
-      return {
-        success: true,
-        dryRun,
-        ...consolidationResult,
-        message: dryRun
-          ? `Found ${consolidationResult.clustersFound} clusters across ${consolidationResult.entitiesProcessed} entities. Run with dryRun=false to consolidate.`
-          : `Consolidated ${consolidationResult.consolidated} clusters from ${consolidationResult.entitiesProcessed} entities.`,
-      };
-    }
-
-    case "harmony_get_context_manifest": {
-      const assemblyId = z.string().min(1).max(100).parse(args.assemblyId);
-      const manifest = getCachedManifest(assemblyId);
-      if (!manifest) {
-        throw new Error(
-          `Manifest not found for assembly '${assemblyId}'. Manifests are cached in-memory and expire after server restart.`,
-        );
-      }
-      return {
-        success: true,
-        manifest,
-        summary: {
-          totalIncluded: manifest.included.length,
-          totalExcluded: manifest.excluded.length,
-          budgetUsed: `${manifest.budgetUsed}/${manifest.budgetTotal} tokens`,
-          tierBreakdown: manifest.tierBreakdown,
-          procedureBreakdown: manifest.procedureBreakdown,
-        },
-      };
-    }
-
-    case "harmony_promote_memory": {
-      const entityId = z.string().uuid().parse(args.entityId);
-      const targetTier = z
-        .enum(["episode", "reference"])
-        .parse(args.targetTier);
-      const reason = z.string().min(1).max(500).parse(args.reason);
-
-      // Fetch current entity to validate promotion path
-      const entityResult = await client.getMemoryEntity(entityId);
-      const entity = entityResult.entity as {
-        id: string;
-        memory_tier?: string;
-        title: string;
-      };
-      const currentTier = entity.memory_tier || "reference";
-
-      // Validate promotion path: draft→episode→reference
-      const tierOrder = { draft: 0, episode: 1, reference: 2 };
-      if (
-        (tierOrder[targetTier] || 0) <=
-        (tierOrder[currentTier as keyof typeof tierOrder] || 0)
-      ) {
-        throw new Error(
-          `Cannot promote from '${currentTier}' to '${targetTier}'. Must promote to a higher tier.`,
-        );
-      }
-
-      const result = await client.updateMemoryEntity(entityId, {
-        memory_tier: targetTier,
-        metadata: {
-          promoted_from_tier: currentTier,
-          promotion_reason: reason,
-          promoted_at: new Date().toISOString(),
-        },
-      });
-
-      return {
-        success: true,
-        promoted: {
-          from: currentTier,
-          to: targetTier,
-          reason,
-        },
-        ...result,
-      };
-    }
-
     // ============ ONBOARDING TOOLS ============
     case "harmony_signup": {
       const email = z.string().email().max(254).parse(args.email);
@@ -4136,213 +3227,6 @@ async function handleToolCall(
       };
     }
 
-    case "harmony_backfill_embeddings": {
-      const workspaceId =
-        (args.workspaceId as string) || deps.getActiveWorkspaceId();
-      if (!workspaceId) {
-        throw new Error(
-          "No workspace specified. Use harmony_set_workspace_context or provide workspaceId.",
-        );
-      }
-      const result = await client.backfillEmbeddings(
-        workspaceId,
-        args.batchSize as number | undefined,
-      );
-      return {
-        success: true,
-        ...result,
-        message:
-          result.remaining > 0
-            ? `Processed ${result.processed} entities. ${result.remaining} still need embeddings — run again to continue.`
-            : `All embeddings up to date. Processed ${result.processed} entities.`,
-      };
-    }
-
-    case "harmony_backfill_relations": {
-      const workspaceId =
-        (args.workspaceId as string) || deps.getActiveWorkspaceId();
-      if (!workspaceId) {
-        throw new Error(
-          "No workspace specified. Use harmony_set_workspace_context or provide workspaceId.",
-        );
-      }
-      const projectId =
-        (args.projectId as string) || deps.getActiveProjectId() || undefined;
-      const maxRelationsPerEntity = (args.maxRelationsPerEntity as number) || 3;
-
-      // Fetch all entities
-      const { entities: allEntities } = await client.listMemoryEntities({
-        workspace_id: workspaceId,
-        project_id: projectId,
-        limit: 200,
-      });
-
-      let entitiesProcessed = 0;
-      let relationsCreated = 0;
-
-      for (const raw of allEntities as Array<{
-        id: string;
-        title: string;
-        content: string;
-        tags?: string[];
-      }>) {
-        try {
-          const result = await autoExpandGraph(
-            client,
-            raw.id,
-            raw.title,
-            raw.content || "",
-            raw.tags || [],
-            workspaceId,
-            projectId,
-            maxRelationsPerEntity,
-          );
-          entitiesProcessed++;
-          relationsCreated += result.relationsCreated;
-        } catch {
-          // Non-fatal: continue with remaining entities
-        }
-      }
-
-      return {
-        success: true,
-        entitiesProcessed,
-        relationsCreated,
-        message: `Processed ${entitiesProcessed} entities, created ${relationsCreated} new relations.`,
-      };
-    }
-
-    case "harmony_audit_memories": {
-      const workspaceId =
-        (args.workspaceId as string) || deps.getActiveWorkspaceId();
-      if (!workspaceId) {
-        throw new Error(
-          "No workspace specified. Use harmony_set_workspace_context or provide workspaceId.",
-        );
-      }
-      const projectId =
-        (args.projectId as string) || deps.getActiveProjectId() || undefined;
-
-      const report = await runMemoryAudit(client, workspaceId, projectId, {
-        dryRun: args.dryRun as boolean | undefined,
-        archiveBelow: args.archiveBelow as number | undefined,
-        deleteBelow: args.deleteBelow as number | undefined,
-        limit: args.limit as number | undefined,
-        staleDraftAgeDays: args.staleDraftAgeDays as number | undefined,
-      });
-
-      return {
-        success: report.success,
-        dryRun: report.dryRun,
-        summary: report.summary,
-        distribution: report.distribution,
-        legacyBreakdown: report.legacyBreakdown,
-        actionsTaken: report.actionsTaken,
-        lowest: report.lowest,
-        staleDrafts: report.staleDrafts,
-        errors: report.errors,
-        healthReport: report.healthReport,
-      };
-    }
-
-    case "harmony_cleanup_memories": {
-      const workspaceId =
-        (args.workspaceId as string) || deps.getActiveWorkspaceId();
-      if (!workspaceId) {
-        throw new Error(
-          "No workspace specified. Use harmony_set_workspace_context or provide workspaceId.",
-        );
-      }
-      const projectId =
-        (args.projectId as string) || deps.getActiveProjectId() || undefined;
-
-      const validSteps = [
-        "prune",
-        "consolidate",
-        "orphans",
-        "duplicates",
-        "backfill",
-        "audit",
-      ];
-      const rawSteps = args.steps as string[] | undefined;
-      const steps = rawSteps?.filter((s) => validSteps.includes(s));
-      if (rawSteps && steps && steps.length < rawSteps.length) {
-        const invalid = rawSteps.filter((s) => !validSteps.includes(s));
-        // Will appear in report.errors via the healthReport
-        console.warn(`Unknown cleanup steps ignored: ${invalid.join(", ")}`);
-      }
-
-      const report = await runMemoryCleanup(client, workspaceId, projectId, {
-        dryRun: args.dryRun as boolean | undefined,
-        steps: steps as
-          | (
-              | "prune"
-              | "consolidate"
-              | "orphans"
-              | "duplicates"
-              | "backfill"
-              | "audit"
-            )[]
-          | undefined,
-        maxAgeDays: args.maxAgeDays as number | undefined,
-        minClusterSize: args.minClusterSize as number | undefined,
-        orphanAgeDays: args.orphanAgeDays as number | undefined,
-        auditArchiveBelow: args.auditArchiveBelow as number | undefined,
-        auditDeleteBelow: args.auditDeleteBelow as number | undefined,
-      });
-
-      return {
-        success: report.success,
-        dryRun: report.dryRun,
-        summary: report.summary,
-        errors: report.errors,
-        healthReport: report.healthReport,
-      };
-    }
-
-    case "harmony_purge_memories": {
-      const workspaceId =
-        (args.workspaceId as string) || deps.getActiveWorkspaceId();
-      if (!workspaceId) {
-        throw new Error(
-          "No workspace specified. Use harmony_set_workspace_context or provide workspaceId.",
-        );
-      }
-      const projectId = (args.projectId as string) || deps.getActiveProjectId();
-      if (!projectId) {
-        throw new Error(
-          "No project specified. Purge requires a project scope. Use harmony_set_project_context or provide projectId.",
-        );
-      }
-
-      const filters: PurgeFilters = {};
-      if (args.tier) filters.tier = args.tier as PurgeFilters["tier"];
-      if (args.scope) filters.scope = args.scope as string;
-      if (args.type) filters.type = args.type as string;
-      if (args.olderThanDays !== undefined)
-        filters.olderThanDays = args.olderThanDays as number;
-      if (args.maxConfidence !== undefined)
-        filters.maxConfidence = args.maxConfidence as number;
-      if (args.tags) filters.tags = args.tags as string[];
-
-      const report = await purgeMemories(client, workspaceId, projectId, {
-        dryRun: args.dryRun as boolean | undefined,
-        filters,
-      });
-
-      return {
-        success: report.success,
-        dryRun: report.dryRun,
-        matched: report.matched,
-        purged: report.purged,
-        items: report.items,
-        errors: report.errors,
-        message: report.dryRun
-          ? `Found ${report.matched} entities matching filters. Run with dryRun=false to delete.`
-          : `Purged ${report.purged} of ${report.matched} matching entities.`,
-      };
-    }
-
     default:
       throw new Error(`Unknown tool: ${name}`);
   }