@gethmy/mcp 2.4.6 → 2.5.0

package/src/context-assembly.ts

@@ -1,1175 +0,0 @@
-/**
- * Context Assembly Engine
- *
- * Token-budget-aware context constructor that assembles relevant memories
- * for a given task, producing a manifest of what was included/excluded.
- */
-
-import type { GraphRelation } from "@harmony/memory";
-import { checkPromotion, discoverRelatedContext } from "@harmony/memory";
-import type { HarmonyApiClient } from "./api-client.js";
-
-// Types
-export type MemoryTier = "draft" | "episode" | "reference";
-
-export interface ContextEntity {
-  id: string;
-  type: string;
-  title: string;
-  content: string;
-  confidence: number;
-  tags: string[];
-  memory_tier: MemoryTier;
-  access_count: number;
-  last_accessed_at: string | null;
-  created_at: string;
-  updated_at: string;
-  relevanceScore?: number;
-  metadata?: Record<string, unknown>;
-  // Hybrid search signals (from DB RPC)
-  rrf_score?: number;
-  fts_rank?: number;
-  semantic_rank?: number;
-}
-
-export interface ContextManifestEntry {
-  entityId: string;
-  title: string;
-  type: string;
-  tier: MemoryTier;
-  relevanceScore: number;
-  reasons: string[];
-  tokenCount: number;
-  truncated: boolean;
-}
-
-export interface ContextManifest {
-  assemblyId: string;
-  timestamp: string;
-  included: ContextManifestEntry[];
-  excluded: Array<{
-    entityId: string;
-    title: string;
-    type: string;
-    tier: MemoryTier;
-    relevanceScore: number;
-    reason: string;
-  }>;
-  budgetUsed: number;
-  budgetTotal: number;
-  tierBreakdown: Record<MemoryTier, { count: number; tokens: number }>;
-  procedureBreakdown?: { count: number; tokens: number; budget: number };
-}
-
-export interface AssembleContextOptions {
-  workspaceId: string;
-  projectId?: string;
-  taskContext: string; // Card title + description for relevance matching
-  cardLabels?: string[];
-  cardId?: string;
-  tokenBudget?: number; // Default: 4000 tokens
-  client: HarmonyApiClient;
-  graphWalkEnabled?: boolean; // Default: true — enrich candidates via knowledge graph relations
-  queryExpansionEnabled?: boolean; // Default: true — expand query with synonyms/variations
-  enableLlmReranking?: boolean; // Default: false — LLM re-ranking when scores are clustered
-  rerankFn?: (
-    taskContext: string,
-    candidates: Array<{ id: string; title: string; snippet: string }>,
-  ) => Promise<string[]>; // Custom re-rank function
-}
-
-export interface AssembledContext {
-  context: string;
-  manifest: ContextManifest;
-  memories: ContextEntity[];
-}
-
-// Constants
-const DEFAULT_TOKEN_BUDGET = 4000;
-const MAX_TOKENS_PER_ENTITY = 500;
-const MIN_RELEVANCE_THRESHOLD = 0.15; // raised from 0.1 to filter low-signal entities
-
-// Tier weight multipliers for relevance scoring
-const TIER_WEIGHTS: Record<MemoryTier, number> = {
-  reference: 1.0,
-  episode: 0.7,
-  draft: 0.4,
-};
-
-// Dedicated procedure budget as a fraction of total budget
-const PROCEDURE_BUDGET_FRACTION = 0.15;
-
-// Tier budget allocation percentages (of remaining budget after procedure reservation)
-const TIER_BUDGET_ALLOCATION: Record<MemoryTier, number> = {
-  reference: 0.6,
-  episode: 0.3,
-  draft: 0.1,
-};
-
-// Minimum guaranteed slots per tier (reduced from 3 to avoid filling context with noise)
-const MIN_REFERENCE_SLOTS = 1;
-
-// Graph walk configuration
-const GRAPH_WALK_MAX_DEPTH = 1;
-const GRAPH_WALK_MAX_ENTITIES = 10;
-const GRAPH_WALK_MIN_CONFIDENCE = 0.5;
-const GRAPH_WALK_SEED_COUNT = 5;
-
-// Query expansion configuration
-const MAX_QUERY_VARIATIONS = 4;
-
-// LLM re-ranking configuration
-const RERANK_CLUSTER_THRESHOLD = 0.05;
-const RERANK_TOP_N = 10;
-const RERANK_MIN_CANDIDATES = 5;
-
-// Graph walk relation-type bonuses for relevance scoring
-const RELATION_BONUSES: Record<string, number> = {
-  depends_on: 0.15,
-  resolved_by: 0.2,
-  relates_to: 0.1,
-  implements: 0.15,
-  blocks: 0.15,
-  references: 0.1,
-  extends: 0.1,
-  caused_by: 0.15,
-};
-
-// Synonym map for query expansion (common dev term variations)
-// NOTE: Avoid circular references (auth->login, login->auth) — first synonym
-// is used for replacement, so each key should expand to non-overlapping terms.
-const QUERY_SYNONYMS: Record<string, string[]> = {
-  auth: ["authentication", "authorization", "session"],
-  authentication: ["auth", "session", "sign-in"],
-  login: ["sign-in", "authentication", "session"],
-  bug: ["error", "issue", "defect", "problem"],
-  error: ["exception", "failure", "issue"],
-  fix: ["resolve", "patch", "repair", "correct"],
-  deploy: ["deployment", "release", "ship", "publish"],
-  test: ["testing", "spec", "assertion", "verify"],
-  config: ["configuration", "settings", "setup"],
-  db: ["database", "storage", "persistence"],
-  database: ["storage", "persistence", "data store"],
-  api: ["endpoint", "route", "service"],
-  ui: ["frontend", "component", "view"],
-  perf: ["performance", "speed", "latency"],
-  performance: ["speed", "latency", "optimization"],
-};
-
-/**
- * Estimate token count (rough: 1 token per 4 chars)
- */
-function estimateTokens(text: string): number {
-  return Math.ceil(text.length / 4);
-}
-
-/**
- * Content quality gate: filter out entities that waste token budget.
- * Returns true if the entity passes quality checks.
- */
-function passesQualityGate(entity: ContextEntity): boolean {
-  const content = entity.content.trim();
-
-  // Gate 1: Minimum content length — entities with <50 chars of content
-  // are too shallow to provide value (e.g., "Resolved bug: Fix login button")
-  if (content.length < 50) return false;
-
-  // Gate 2: Title-content similarity — skip entities where content is just
-  // the title restated. Normalize both and check if content adds anything.
-  const normalizedTitle = entity.title
-    .toLowerCase()
-    .replace(/[^a-z0-9\s]/g, "")
-    .trim();
-  const normalizedContent = content
-    .toLowerCase()
-    .replace(/[^a-z0-9\s]/g, "")
-    .trim();
-  if (normalizedContent.length < normalizedTitle.length * 1.5) {
-    // Content is barely longer than the title — likely just a reformulation
-    return false;
-  }
-
-  // Gate 3: Pattern noise detection — skip "Pattern: recurring X (N instances)"
-  // and "Consolidated from N type memories:" entities that are just catalogs
-  if (
-    entity.type === "pattern" &&
-    /recurring .+ \(\d+ instances\)/i.test(entity.title)
-  ) {
-    // Check if content is just a member list (lines starting with "- ")
-    const lines = content.split("\n").filter((l) => l.trim().length > 0);
-    const bulletLines = lines.filter((l) => l.trim().startsWith("- "));
-    if (bulletLines.length > lines.length * 0.6) return false;
-  }
-
-  // Gate 4: Procedure quality — procedures must contain actual steps,
-  // not just a card title wrapped in a template
-  if (entity.type === "procedure") {
-    // Count numbered steps (1. ..., 2. ..., etc.)
-    const stepCount = (content.match(/^\d+\.\s/gm) || []).length;
-    if (stepCount < 3) return false;
-  }
-
-  return true;
-}
-
-/**
- * Generate a unique assembly ID
- */
-function generateAssemblyId(): string {
-  return `ctx_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
-}
-
-/**
- * Truncate entity content to fit within token limit.
- * Keeps first paragraph + bullet points if present.
- */
-function truncateContent(
-  content: string,
-  maxTokens: number,
-): { text: string; truncated: boolean } {
-  const currentTokens = estimateTokens(content);
-  if (currentTokens <= maxTokens) {
-    return { text: content, truncated: false };
-  }
-
-  // Try to keep first paragraph
-  const paragraphs = content.split(/\n\n+/);
-  let result = paragraphs[0];
-
-  // Add bullet points from subsequent paragraphs if they fit
-  for (let i = 1; i < paragraphs.length; i++) {
-    const lines = paragraphs[i]
-      .split("\n")
-      .filter((l) => l.startsWith("- ") || l.startsWith("* "));
-    if (lines.length > 0) {
-      const bulletSection = lines.join("\n");
-      if (estimateTokens(result + "\n\n" + bulletSection) <= maxTokens) {
-        result += "\n\n" + bulletSection;
-      }
-    }
-  }
-
-  // Hard truncate if still too long
-  if (estimateTokens(result) > maxTokens) {
-    const maxChars = maxTokens * 4;
-    result = result.slice(0, maxChars - 3) + "...";
-  }
-
-  return { text: result, truncated: true };
-}
-
-/**
- * Escape regex metacharacters in a string for safe use in RegExp constructor.
- */
-function escapeRegex(str: string): string {
-  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-
-/**
- * Expand a query into multiple search variations using synonym substitution.
- * Returns the original query plus up to 3 additional variations (4 total).
- */
-export function expandQuery(taskContext: string): string[] {
-  const queries = [taskContext];
-  const lowerQueries = [taskContext.toLowerCase()];
-  const words = taskContext
-    .toLowerCase()
-    .split(/\W+/)
-    .filter((w) => w.length > 2);
-
-  // Find words that have synonym expansions
-  const expandableWords = words.filter((w) => QUERY_SYNONYMS[w]);
-
-  for (const word of expandableWords) {
-    const synonyms = QUERY_SYNONYMS[word];
-    if (!synonyms) continue;
-    // Create a variation by replacing the word with its first synonym
-    const variation = taskContext.replace(
-      new RegExp(`\\b${escapeRegex(word)}\\b`, "gi"),
-      synonyms[0],
-    );
-    const lowerVariation = variation.toLowerCase();
-    if (
-      lowerVariation !== taskContext.toLowerCase() &&
-      !lowerQueries.includes(lowerVariation)
-    ) {
-      queries.push(variation);
-      lowerQueries.push(lowerVariation);
-    }
-    if (queries.length >= MAX_QUERY_VARIATIONS) break;
-  }
-
-  // Also extract key noun phrases as a compact query
-  if (words.length >= 3) {
-    const keyPhrases = words
-      .filter(
-        (w) =>
-          ![
-            "the",
-            "and",
-            "for",
-            "with",
-            "this",
-            "that",
-            "from",
-            "into",
-          ].includes(w),
-      )
-      .slice(0, 4)
-      .join(" ");
-    if (!lowerQueries.includes(keyPhrases)) {
-      queries.push(keyPhrases);
-    }
-  }
-
-  return queries.slice(0, MAX_QUERY_VARIATIONS);
-}
-
-/**
- * Compute relevance score for an entity against task context.
- */
-export function computeRelevanceScore(
-  entity: ContextEntity,
-  taskContext: string,
-  cardLabels: string[],
-  graphRelations?: GraphRelation[],
-): { score: number; reasons: string[] } {
-  const reasons: string[] = [];
-  let score = 0;
-
-  // 0. DB hybrid search signal (RRF score from FTS + vector fusion)
-  //    Scaled to 0-0.3 contribution; when present, reduces reliance on word-overlap
-  const hasRrfScore = entity.rrf_score !== undefined && entity.rrf_score > 0;
-  if (hasRrfScore) {
-    // RRF scores are typically 0-0.04; normalize to 0-1 range then scale
-    const normalizedRrf = Math.min(entity.rrf_score! / 0.04, 1.0);
-    const rrfContribution = normalizedRrf * 0.3;
-    score += rrfContribution;
-    reasons.push(`hybrid_search(rrf=${entity.rrf_score!.toFixed(4)})`);
-  }
-
-  // 1. Text match: simple word overlap scoring (reduced weight when RRF available)
-  const textMatchWeight = hasRrfScore ? 0.15 : 0.4;
-  const taskWords = new Set(
-    taskContext
-      .toLowerCase()
-      .split(/\W+/)
-      .filter((w) => w.length > 2),
-  );
-  const entityWords = new Set(
-    `${entity.title} ${entity.content}`
-      .toLowerCase()
-      .split(/\W+/)
-      .filter((w) => w.length > 2),
-  );
-  const overlap = [...taskWords].filter((w) => entityWords.has(w));
-  if (overlap.length > 0) {
-    const textScore =
-      Math.min(overlap.length / Math.max(taskWords.size, 1), 1.0) *
-      textMatchWeight;
-    score += textScore;
-    reasons.push(`text_match(${overlap.length} words)`);
-  }
-
-  // 2. Tag overlap with card labels
-  if (cardLabels.length > 0 && entity.tags.length > 0) {
-    const labelSet = new Set(cardLabels.map((l) => l.toLowerCase()));
-    const tagOverlap = entity.tags.filter((t) => labelSet.has(t.toLowerCase()));
-    if (tagOverlap.length > 0) {
-      const tagScore = (tagOverlap.length / cardLabels.length) * 0.3;
-      score += tagScore;
-      reasons.push(`tag_match(${tagOverlap.join(",")})`);
-    }
-  }
-
-  // 3. Confidence as a quality signal
-  score += entity.confidence * 0.15;
-  if (entity.confidence >= 0.9) {
-    reasons.push("high_confidence");
-  }
-
-  // 4. Recency: decay based on last access with tier-specific half-lives
-  if (entity.last_accessed_at) {
-    const daysSinceAccess =
-      (Date.now() - new Date(entity.last_accessed_at).getTime()) /
-      (1000 * 60 * 60 * 24);
-    const halfLife = { draft: 7, episode: 30, reference: 180 }[
-      entity.memory_tier
-    ];
-    const recencyScore = 0.5 ** (daysSinceAccess / halfLife) * 0.1;
-    score += recencyScore;
-    if (daysSinceAccess < 7) reasons.push("recently_accessed");
-  }
-
-  // 5. Access frequency (log-scaled)
-  if (entity.access_count > 0) {
-    const freqScore = Math.log10(entity.access_count + 1) * 0.05;
-    score += Math.min(freqScore, 0.1);
-    if (entity.access_count >= 5)
-      reasons.push(`frequently_used(${entity.access_count})`);
-  }
-
-  // 6. Usefulness score from feedback loop (0-0.15 weight)
-  const usefulnessScore = (entity.metadata?.usefulness_score as number) ?? 0;
-  if (usefulnessScore >= 3) {
-    const usefulnessBoost = Math.min(usefulnessScore / 20, 0.15);
-    score += usefulnessBoost;
-    reasons.push(`useful(${usefulnessScore})`);
-  } else if (usefulnessScore === 0 && entity.access_count >= 5) {
-    // Accessed many times but never marked useful — slight penalty
-    score -= 0.02;
-    reasons.push("low_usefulness");
-  }
-
-  // Procedure boost: actionable step-by-step instructions are highly valuable
-  if (entity.type === "procedure") {
-    score += 0.1;
-    reasons.push("procedure_boost");
-  }
-
-  // 7. Graph walk relation bonus: boost entities discovered via knowledge graph
-  if (graphRelations && graphRelations.length > 0) {
-    const entityRelations = graphRelations.filter(
-      (r) => r.source_id === entity.id || r.target_id === entity.id,
-    );
-    if (entityRelations.length > 0) {
-      // Take the highest relation bonus (don't stack all of them)
-      let bestBonus = 0;
-      let bestRelType = "";
-      for (const rel of entityRelations) {
-        const bonus = RELATION_BONUSES[rel.relation_type] ?? 0.1;
-        if (bonus > bestBonus) {
-          bestBonus = bonus;
-          bestRelType = rel.relation_type;
-        }
-      }
-      score += bestBonus;
-      reasons.push(`graph_walk(${bestRelType})`);
-    }
-  }
-
-  // Clamp raw score to 0-1 range before applying tier weight
-  score = Math.max(0, Math.min(score, 1.0));
-
-  // Apply tier weight
-  const tierWeight = TIER_WEIGHTS[entity.memory_tier];
-  score *= tierWeight;
-
-  return { score, reasons };
-}
-
-/**
- * Assemble context from knowledge graph entities with token budget management.
- */
-export async function assembleContext(
-  options: AssembleContextOptions,
-): Promise<AssembledContext> {
-  const {
-    workspaceId,
-    projectId,
-    taskContext,
-    cardLabels = [],
-    tokenBudget = DEFAULT_TOKEN_BUDGET,
-    client,
-    graphWalkEnabled = true,
-    queryExpansionEnabled = true,
-    enableLlmReranking = false,
-    rerankFn,
-  } = options;
-
-  const assemblyId = generateAssemblyId();
-  const manifest: ContextManifest = {
-    assemblyId,
-    timestamp: new Date().toISOString(),
-    included: [],
-    excluded: [],
-    budgetUsed: 0,
-    budgetTotal: tokenBudget,
-    tierBreakdown: {
-      draft: { count: 0, tokens: 0 },
-      episode: { count: 0, tokens: 0 },
-      reference: { count: 0, tokens: 0 },
-    },
-  };
-
-  // Fetch candidate entities: search by task context (with query expansion) + list by project
-  const candidates: ContextEntity[] = [];
-
-  // P1: Query expansion — search with multiple query variations to catch synonym mismatches
-  const queries = queryExpansionEnabled
-    ? expandQuery(taskContext)
-    : [taskContext];
-
-  const searchResults = await Promise.allSettled(
-    queries.map((query) =>
-      client.searchMemoryEntities(workspaceId, query, {
-        project_id: projectId,
-        limit: 30,
-      }),
-    ),
-  );
-
-  const candidateIds = new Set<string>();
-  for (const result of searchResults) {
-    if (result.status !== "fulfilled") continue;
-    if (result.value.entities?.length > 0) {
-      for (const raw of result.value.entities) {
-        const entity = mapToContextEntity(raw);
-        if (!candidateIds.has(entity.id)) {
-          candidateIds.add(entity.id);
-          candidates.push(entity);
-        }
-      }
-    }
-  }
-
-  // Also fetch by project scope if we have few candidates
-  if (candidates.length < 10 && projectId) {
-    try {
-      const listResult = await client.listMemoryEntities({
-        workspace_id: workspaceId,
-        project_id: projectId,
-        limit: 30,
-      });
-      if (listResult.entities?.length > 0) {
-        for (const raw of listResult.entities) {
-          const entity = mapToContextEntity(raw);
-          if (!candidateIds.has(entity.id)) {
-            candidateIds.add(entity.id);
-            candidates.push(entity);
-          }
-        }
-      }
-    } catch {
-      // List failed, continue with what we have
-    }
-  }
-
-  // Cross-project memory: fetch workspace-scoped entities only
-  // This ensures shared decisions/patterns are available without leaking project-private data
-  if (candidates.length < 20) {
-    try {
-      const wsResult = await client.listMemoryEntities({
-        workspace_id: workspaceId,
-        scope: "workspace",
-        limit: 20,
-      });
-      if (wsResult.entities?.length > 0) {
-        for (const raw of wsResult.entities) {
-          const entity = mapToContextEntity(raw);
-          if (!candidateIds.has(entity.id)) {
-            candidateIds.add(entity.id);
-            candidates.push(entity);
-          }
-        }
-      }
-    } catch {
-      // Continue with what we have
-    }
-  }
-
-  // P0: Graph walk enrichment — discover related entities via knowledge graph
-  let graphRelations: GraphRelation[] = [];
-  if (graphWalkEnabled && candidates.length > 0) {
-    try {
-      // Take top candidates by RRF score (or first N if no RRF scores)
-      const seedCandidates = [...candidates]
-        .sort((a, b) => (b.rrf_score ?? 0) - (a.rrf_score ?? 0))
-        .slice(0, GRAPH_WALK_SEED_COUNT);
-      const seedIds = seedCandidates.map((c) => c.id);
-
-      const walkResult = await discoverRelatedContext(
-        client,
-        seedIds,
-        GRAPH_WALK_MAX_DEPTH,
-        GRAPH_WALK_MAX_ENTITIES,
-        GRAPH_WALK_MIN_CONFIDENCE,
-      );
-
-      graphRelations = walkResult.relations;
-
-      // Add discovered entities to candidate pool (skip those already present)
-      const newEntityIds = walkResult.entities
-        .filter((e) => !candidateIds.has(e.id))
-        .map((e) => e.id);
-
-      if (newEntityIds.length > 0) {
-        // Fetch full entity data in parallel (graph walk only returns summary fields)
-        const fetchResults = await Promise.allSettled(
-          newEntityIds.map((id) => client.getMemoryEntity(id)),
-        );
-        for (const result of fetchResults) {
-          if (result.status !== "fulfilled" || !result.value.entity) continue;
-          const mapped = mapToContextEntity(result.value.entity);
-          candidateIds.add(mapped.id);
-          candidates.push(mapped);
-        }
-      }
-    } catch {
-      // Graph walk failed, continue with search-only candidates
-    }
-  }
-
-  if (candidates.length === 0) {
-    return {
-      context: "",
-      manifest,
-      memories: [],
-    };
-  }
-
-  // Quality gate: filter out low-value entities before scoring
-  const qualityCandidates = candidates.filter((entity) => {
-    if (passesQualityGate(entity)) return true;
-    manifest.excluded.push({
-      entityId: entity.id,
-      title: entity.title,
-      type: entity.type,
-      tier: entity.memory_tier,
-      relevanceScore: 0,
-      reason: "failed_quality_gate",
-    });
-    return false;
-  });
-
-  if (qualityCandidates.length === 0) {
-    return {
-      context: "",
-      manifest,
-      memories: [],
-    };
-  }
-
-  // Score all candidates (pass graph relations for relation-type bonuses)
-  const scored = qualityCandidates.map((entity) => {
-    const { score, reasons } = computeRelevanceScore(
-      entity,
-      taskContext,
-      cardLabels,
-      graphRelations.length > 0 ? graphRelations : undefined,
-    );
-    return { entity, score, reasons };
-  });
-
-  // Sort by score descending
-  scored.sort((a, b) => b.score - a.score);
-
-  // P2: Optional LLM re-ranking when top scores are clustered
-  if (
-    enableLlmReranking &&
-    rerankFn &&
-    scored.length >= RERANK_MIN_CANDIDATES
-  ) {
-    const topN = scored.slice(0, RERANK_TOP_N);
-    const scoreRange = topN[0].score - topN[topN.length - 1].score;
-    // Only re-rank when scores are tightly clustered
-    if (scoreRange <= RERANK_CLUSTER_THRESHOLD) {
-      try {
-        const rerankCandidates = topN.map((s) => ({
-          id: s.entity.id,
-          title: s.entity.title,
-          snippet: s.entity.content.slice(0, 200),
-        }));
-        const rerankedIds = await rerankFn(taskContext, rerankCandidates);
-        // Reorder based on LLM ranking
-        const idOrder = new Map(rerankedIds.map((id, i) => [id, i]));
-        topN.sort((a, b) => {
-          const aIdx = idOrder.get(a.entity.id) ?? 999;
-          const bIdx = idOrder.get(b.entity.id) ?? 999;
-          return aIdx - bIdx;
-        });
-        // Splice reranked items back in
-        scored.splice(0, topN.length, ...topN);
-      } catch {
-        // Re-ranking failed, continue with static ordering
-      }
-    }
-  }
-
-  // Reserve dedicated procedure budget, allocate remaining to tiers
-  const procedureBudget = Math.floor(tokenBudget * PROCEDURE_BUDGET_FRACTION);
-  const remainingBudget = tokenBudget - procedureBudget;
-
-  const tierBudgets: Record<MemoryTier, number> = {
-    reference: Math.floor(remainingBudget * TIER_BUDGET_ALLOCATION.reference),
-    episode: Math.floor(remainingBudget * TIER_BUDGET_ALLOCATION.episode),
-    draft: Math.floor(remainingBudget * TIER_BUDGET_ALLOCATION.draft),
-  };
-
-  const tierUsed: Record<MemoryTier, number> = {
-    reference: 0,
-    episode: 0,
-    draft: 0,
-  };
-  let procedureUsed = 0;
-  const included: Array<{
-    entity: ContextEntity;
-    score: number;
-    reasons: string[];
-    tokens: number;
-    truncated: boolean;
-  }> = [];
-  let totalUsed = 0;
-
-  // First pass: guarantee minimum reference slots
-  let referenceCount = 0;
-  for (const item of scored) {
-    if (
-      item.entity.memory_tier === "reference" &&
-      item.entity.type !== "procedure" &&
-      referenceCount < MIN_REFERENCE_SLOTS
-    ) {
-      const { text, truncated } = truncateContent(
-        item.entity.content,
-        MAX_TOKENS_PER_ENTITY,
-      );
-      const tokens = estimateTokens(`### ${item.entity.title}\n${text}`);
-      if (totalUsed + tokens <= tokenBudget) {
-        included.push({ ...item, tokens, truncated });
-        item.entity.content = text;
-        totalUsed += tokens;
-        tierUsed.reference += tokens;
-        referenceCount++;
-      }
-    }
-  }
-
-  // Second pass: include procedure entities with dedicated budget
-  const includedIds = new Set(included.map((i) => i.entity.id));
-  const procedureCandidates = scored.filter(
-    (item) =>
-      item.entity.type === "procedure" && !includedIds.has(item.entity.id),
-  );
-  for (const item of procedureCandidates) {
-    if (item.score < MIN_RELEVANCE_THRESHOLD) {
-      manifest.excluded.push({
-        entityId: item.entity.id,
-        title: item.entity.title,
-        type: item.entity.type,
-        tier: item.entity.memory_tier,
-        relevanceScore: item.score,
-        reason: "below_relevance_threshold",
-      });
-      continue;
-    }
-
-    const { text, truncated } = truncateContent(
-      item.entity.content,
-      MAX_TOKENS_PER_ENTITY,
-    );
-    const tokens = estimateTokens(`### ${item.entity.title}\n${text}`);
-
-    // Check dedicated procedure budget, allow overflow to total remaining
-    if (procedureUsed + tokens > procedureBudget) {
-      const totalRemaining = tokenBudget - totalUsed;
-      if (tokens > totalRemaining) {
-        manifest.excluded.push({
-          entityId: item.entity.id,
-          title: item.entity.title,
-          type: item.entity.type,
-          tier: item.entity.memory_tier,
-          relevanceScore: item.score,
-          reason: "procedure_budget_exceeded",
-        });
-        continue;
-      }
-    }
-
-    if (totalUsed + tokens > tokenBudget) {
-      manifest.excluded.push({
-        entityId: item.entity.id,
-        title: item.entity.title,
-        type: item.entity.type,
-        tier: item.entity.memory_tier,
-        relevanceScore: item.score,
-        reason: "total_budget_exceeded",
-      });
-      continue;
-    }
-
-    included.push({ ...item, tokens, truncated });
-    item.entity.content = text;
-    totalUsed += tokens;
-    procedureUsed += tokens;
-    includedIds.add(item.entity.id);
-  }
-
-  // Third pass: fill remaining budget by score (non-procedure entities)
-  for (const item of scored) {
-    if (includedIds.has(item.entity.id)) continue;
-    if (item.entity.type === "procedure") continue; // Already handled
-    if (item.score < MIN_RELEVANCE_THRESHOLD) {
-      manifest.excluded.push({
-        entityId: item.entity.id,
-        title: item.entity.title,
-        type: item.entity.type,
-        tier: item.entity.memory_tier,
-        relevanceScore: item.score,
-        reason: "below_relevance_threshold",
-      });
-      continue;
-    }
-
-    const tier = item.entity.memory_tier;
-    const { text, truncated } = truncateContent(
-      item.entity.content,
-      MAX_TOKENS_PER_ENTITY,
-    );
-    const tokens = estimateTokens(`### ${item.entity.title}\n${text}`);
-
-    // Check tier budget (allow overflow to unused tiers)
-    if (tierUsed[tier] + tokens > tierBudgets[tier]) {
-      // Check if there's unused budget from other tiers
-      const totalRemaining = tokenBudget - totalUsed;
-      if (tokens > totalRemaining) {
-        manifest.excluded.push({
-          entityId: item.entity.id,
-          title: item.entity.title,
-          type: item.entity.type,
-          tier,
-          relevanceScore: item.score,
-          reason: "budget_exceeded",
-        });
-        continue;
-      }
-    }
-
-    if (totalUsed + tokens > tokenBudget) {
-      manifest.excluded.push({
-        entityId: item.entity.id,
-        title: item.entity.title,
-        type: item.entity.type,
-        tier,
-        relevanceScore: item.score,
-        reason: "total_budget_exceeded",
-      });
-      continue;
-    }
-
-    included.push({ ...item, tokens, truncated });
-    item.entity.content = text;
-    totalUsed += tokens;
-    tierUsed[tier] += tokens;
-    includedIds.add(item.entity.id);
-  }
-
-  // Build manifest
-  manifest.budgetUsed = totalUsed;
-  const procedureItems = included.filter((i) => i.entity.type === "procedure");
-  manifest.tierBreakdown = {
-    reference: {
-      count: included.filter(
-        (i) =>
-          i.entity.memory_tier === "reference" && i.entity.type !== "procedure",
-      ).length,
-      tokens: tierUsed.reference,
-    },
-    episode: {
-      count: included.filter(
-        (i) =>
-          i.entity.memory_tier === "episode" && i.entity.type !== "procedure",
-      ).length,
-      tokens: tierUsed.episode,
-    },
-    draft: {
-      count: included.filter(
-        (i) =>
-          i.entity.memory_tier === "draft" && i.entity.type !== "procedure",
-      ).length,
-      tokens: tierUsed.draft,
-    },
-  };
-  manifest.procedureBreakdown = {
-    count: procedureItems.length,
-    tokens: procedureUsed,
-    budget: procedureBudget,
-  };
-
-  for (const item of included) {
-    manifest.included.push({
-      entityId: item.entity.id,
-      title: item.entity.title,
-      type: item.entity.type,
-      tier: item.entity.memory_tier,
-      relevanceScore: item.score,
-      reasons: item.reasons,
-      tokenCount: item.tokens,
-      truncated: item.truncated,
-    });
-  }
-
-  // Build context string — procedures in their own section
-  const contextSections: string[] = [];
-  const nonProcedureItems = included.filter(
-    (i) => i.entity.type !== "procedure",
-  );
-
-  if (included.length > 0) {
-    // Procedure section first (actionable instructions)
-    if (procedureItems.length > 0) {
-      contextSections.push(
-        `## Procedures (${procedureItems.length} loaded, ${procedureUsed}/${procedureBudget} tokens)`,
-      );
-      for (const item of procedureItems) {
-        const tags =
-          item.entity.tags.length > 0
-            ? ` [${item.entity.tags.join(", ")}]`
-            : "";
-        const tierLabel =
-          item.entity.memory_tier !== "reference"
-            ? ` (${item.entity.memory_tier})`
-            : "";
-        contextSections.push(
-          `\n### ${item.entity.title} (confidence: ${item.entity.confidence})${tierLabel}${tags}`,
-        );
-        contextSections.push(item.entity.content);
-      }
-    }
-
-    // Non-procedure memories
-    if (nonProcedureItems.length > 0) {
-      contextSections.push(
-        `\n## Relevant Memories (${nonProcedureItems.length} loaded, ${manifest.excluded.length} excluded)`,
-      );
-      contextSections.push(
-        `*Assembly: ${assemblyId} | Budget: ${totalUsed}/${tokenBudget} tokens*`,
-      );
-
-      for (const item of nonProcedureItems) {
-        const tags =
-          item.entity.tags.length > 0
-            ? ` [${item.entity.tags.join(", ")}]`
-            : "";
-        const tierLabel =
-          item.entity.memory_tier !== "reference"
-            ? ` (${item.entity.memory_tier})`
-            : "";
-        contextSections.push(
-          `\n### ${item.entity.title} (${item.entity.type}, confidence: ${item.entity.confidence})${tierLabel}${tags}`,
-        );
-        contextSections.push(item.entity.content);
-      }
-    }
-  }
-
-  // Increment access_count for included entities (fire-and-forget)
-  incrementAccessCounts(
-    client,
-    included.map((i) => i.entity.id),
-  ).catch(() => {});
-
-  // Auto-promote entities that cross access thresholds after the bump (fire-and-forget)
-  promoteEligibleEntities(
-    client,
-    included.map((i) => i.entity),
-  ).catch(() => {});
-
-  return {
-    context: contextSections.join("\n"),
-    manifest,
-    memories: included.map((i) => i.entity),
-  };
-}
-
-/**
- * Map raw API entity to ContextEntity
- */
-export function mapToContextEntity(raw: unknown): ContextEntity {
-  const e = raw as Record<string, unknown>;
-  return {
-    id: e.id as string,
-    type: e.type as string,
-    title: e.title as string,
-    content: e.content as string,
-    confidence: (e.confidence as number) ?? 1.0,
-    tags: (e.tags as string[]) || [],
-    memory_tier: (e.memory_tier as MemoryTier) || "reference",
-    access_count: (e.access_count as number) || 0,
-    last_accessed_at: (e.last_accessed_at as string) || null,
-    created_at: (e.created_at as string) || "",
-    updated_at: (e.updated_at as string) || "",
-    metadata: (e.metadata as Record<string, unknown>) ?? undefined,
-    // Hybrid search signals (present when results come from RPC)
-    rrf_score: (e.rrf_score as number) ?? undefined,
-    fts_rank: (e.fts_rank as number) ?? undefined,
-    semantic_rank: (e.semantic_rank as number) ?? undefined,
-  };
-}
-
-/**
- * Increment access counts for entities loaded into context.
- * Uses batch_touch_knowledge_entities RPC for a single-roundtrip update.
- * Falls back to individual touches if the batch endpoint is unavailable.
- */
-async function incrementAccessCounts(
-  client: HarmonyApiClient,
-  entityIds: string[],
-): Promise<void> {
-  if (entityIds.length === 0) return;
-  try {
-    await client.batchTouchMemoryEntities(entityIds);
-  } catch {
-    // Fallback: individual touches (e.g. older server version)
-    await Promise.allSettled(
-      entityIds.map((id) => client.touchMemoryEntity(id)),
-    );
-  }
-}
-
-/**
- * Check included entities for promotion eligibility after access count bump.
- * Uses access_count + 1 to reflect the touch that just happened.
- */
-async function promoteEligibleEntities(
-  client: HarmonyApiClient,
-  entities: ContextEntity[],
-): Promise<void> {
-  for (const entity of entities) {
-    if (entity.memory_tier === "reference") continue;
-    if (!entity.created_at) continue;
-
-    // +1 because incrementAccessCounts just bumped it
-    const promotion = checkPromotion(
-      entity.memory_tier,
-      entity.access_count + 1,
-      entity.confidence,
-      entity.created_at,
-    );
-
-    if (promotion.eligible && promotion.targetTier) {
-      try {
-        await client.updateMemoryEntity(entity.id, {
-          memory_tier: promotion.targetTier,
-          metadata: {
-            ...(entity.metadata || {}),
-            promoted_at: new Date().toISOString(),
-            promotion_reason: promotion.reason,
-            promoted_from: entity.memory_tier,
-          },
-        });
-      } catch {
-        // Non-fatal: promotion is best-effort
-      }
-    }
-  }
-}
-
-// In-memory manifest cache (keyed by assemblyId)
-const manifestCache = new Map<string, ContextManifest>();
-const MAX_CACHE_SIZE = 50;
-
-/**
- * Store a manifest for later retrieval.
- */
-export function cacheManifest(manifest: ContextManifest): void {
-  if (manifestCache.size >= MAX_CACHE_SIZE) {
-    // Remove oldest entry
-    const firstKey = manifestCache.keys().next().value;
-    if (firstKey) manifestCache.delete(firstKey);
-  }
-  manifestCache.set(manifest.assemblyId, manifest);
-}
-
-/**
- * Retrieve a cached manifest by assembly ID.
- */
-export function getCachedManifest(
-  assemblyId: string,
-): ContextManifest | undefined {
-  return manifestCache.get(assemblyId);
-}
-
-// --- Feedback-Driven Scoring ---
-
-/** Track which assemblyId was used for which card session */
-const sessionAssemblyMap = new Map<string, string>();
-const MAX_SESSION_MAP_SIZE = 100;
-
-/**
- * Associate an assemblyId with a card session for later feedback.
- * Called when context is assembled during session start or prompt generation.
- */
-export function trackSessionAssembly(cardId: string, assemblyId: string): void {
-  if (sessionAssemblyMap.size >= MAX_SESSION_MAP_SIZE) {
-    const firstKey = sessionAssemblyMap.keys().next().value;
-    if (firstKey) sessionAssemblyMap.delete(firstKey);
-  }
-  sessionAssemblyMap.set(cardId, assemblyId);
-}
-
-/**
- * Get the assemblyId associated with a card session.
- */
-export function getSessionAssemblyId(cardId: string): string | undefined {
-  return sessionAssemblyMap.get(cardId);
-}
-
-/**
- * Record context feedback based on session outcome.
- * Adjusts entity confidence based on whether the session completed successfully.
- *
- * - Completed successfully (status=completed, progress>=100): boost included entities
- * - Paused/blocked: neutral or slight penalty for included entities
- */
-export async function recordContextFeedback(
-  client: HarmonyApiClient,
-  cardId: string,
-  sessionStatus: "completed" | "paused",
-  progressPercent?: number,
-  hadBlockers?: boolean,
-): Promise<{ adjusted: number }> {
-  const assemblyId = sessionAssemblyMap.get(cardId);
-  if (!assemblyId) return { adjusted: 0 };
-
-  const manifest = manifestCache.get(assemblyId);
-  if (!manifest || manifest.included.length === 0) return { adjusted: 0 };
-
-  let adjusted = 0;
-  const isSuccess =
-    sessionStatus === "completed" && (progressPercent ?? 0) >= 100;
-
-  for (const entry of manifest.included) {
-    try {
-      if (isSuccess) {
-        // Boost confidence by +0.05 (max 1.0) and increment usefulness_score
-        const { entity } = await client.getMemoryEntity(entry.entityId);
-        const e = entity as {
-          confidence: number;
-          metadata?: Record<string, unknown>;
-        };
-        const currentUsefulness = (e.metadata?.usefulness_score as number) ?? 0;
-        const newConfidence = Math.min((e.confidence ?? 0.5) + 0.05, 1.0);
-
-        await client.updateMemoryEntity(entry.entityId, {
-          confidence: newConfidence,
-          metadata: {
-            usefulness_score: currentUsefulness + 1,
-            last_feedback_at: new Date().toISOString(),
-          },
-        });
-        adjusted++;
-      } else if (hadBlockers) {
-        // Slight penalty for entities included when session had blockers
-        const { entity } = await client.getMemoryEntity(entry.entityId);
-        const e = entity as { confidence: number };
-        const newConfidence = Math.max((e.confidence ?? 0.5) - 0.02, 0.1);
-
-        await client.updateMemoryEntity(entry.entityId, {
-          confidence: newConfidence,
-          metadata: {
-            last_feedback_at: new Date().toISOString(),
-          },
-        });
-        adjusted++;
-      }
-      // Paused without blockers: no change (neutral signal)
-    } catch {
-      // Non-fatal: individual entity update failure
-    }
-  }
-
-  // Clean up tracking
-  sessionAssemblyMap.delete(cardId);
-
-  return { adjusted };
-}