@gethmy/mcp 2.24.0 → 2.26.0

package/dist/lib/api-client.js

@@ -488,15 +488,7 @@ ${lines.join(`
 `)}`;
 }
 function generatePrompt(options) {
-  const {
-    card,
-    column,
-    variant,
-    customConstraints,
-    memories,
-    assembledContext,
-    assemblyId
-  } = options;
+  const { card, column, variant, customConstraints, memories, assemblyId } = options;
   const contextOpts = {
     includeTitle: true,
     includeDescription: true,
@@ -574,10 +566,7 @@ ${card.description}`);
   roleFraming.outputSuggestions.forEach((s) => {
     sections.push(`- ${s}`);
   });
-  if (assembledContext) {
-    sections.push(`
-${assembledContext}`);
-  } else if (memories && memories.length > 0) {
+  if (memories && memories.length > 0) {
     sections.push(`
 ## Relevant Memories`);
     sections.push(`*${memories.length} memories recalled from knowledge graph:*`);
@@ -588,7 +577,7 @@ ${assembledContext}`);
       sections.push(memory.content);
     }
   }
-  const oneThingLine = synthesizeOneThing(card, subtasks, links, assembledContext);
+  const oneThingLine = synthesizeOneThing(card, subtasks, links);
   if (oneThingLine) {
     sections.push(`
 ## Recommended Next Step
@@ -615,7 +604,7 @@ ${customConstraints}`);
 *Card #${card.short_id} | Generated for ${variant} mode*`);
   const prompt = sections.join(`
 `);
-  const memoryCount = assembledContext ? (assembledContext.match(/^### /gm) || []).length : memories?.length || 0;
+  const memoryCount = memories?.length ?? 0;
   return {
     prompt,
     variant,
@@ -636,40 +625,7 @@ ${customConstraints}`);
     version: PROMPT_TEMPLATE_VERSION
   };
 }
-function extractSessionInsights(assembledContext) {
-  const result = {
-    lastSessionStatus: null,
-    lastSessionTask: null,
-    lastSessionProgress: null,
-    blockers: [],
-    procedureNextStep: null
-  };
-  const sessionMatches = assembledContext.match(/### Session:.*?\n([\s\S]*?)(?=\n###|\n## |\n---|\n\*Assembly|$)/g);
-  if (sessionMatches && sessionMatches.length > 0) {
-    const latest = sessionMatches[0];
-    if (/Completed work on/i.test(latest)) {
-      result.lastSessionStatus = "completed";
-    } else if (/Paused work on|status:\s*paused/i.test(latest)) {
-      result.lastSessionStatus = "paused";
-    }
-    const taskMatch = latest.match(/Final task:\s*(.+)/);
-    if (taskMatch)
-      result.lastSessionTask = taskMatch[1].trim();
-    const progressMatch = latest.match(/Progress:\s*(\d+)%/);
-    if (progressMatch)
-      result.lastSessionProgress = parseInt(progressMatch[1], 10);
-  }
-  const blockerMatches = assembledContext.match(/(?:blocker|blocked by|blocking):\s*(.+)/gi);
-  if (blockerMatches) {
-    result.blockers = blockerMatches.map((m) => m.replace(/(?:blocker|blocked by|blocking):\s*/i, "").trim());
-  }
-  const stepMatches = assembledContext.match(/^\d+\.\s+(?!.*\*\*\[key step\]\*\*.*✓)(.+?)(?:\s*\*\*\[key step\]\*\*)?$/gm);
-  if (stepMatches && stepMatches.length > 0) {
-    result.procedureNextStep = stepMatches[0].replace(/^\d+\.\s+/, "").replace(/\s*\*\*\[key step\]\*\*.*$/, "").trim();
-  }
-  return result;
-}
-function synthesizeOneThing(card, subtasks, links, assembledContext) {
+function synthesizeOneThing(card, subtasks, links) {
   if (card.done)
     return null;
   const blockers = links.filter((l) => l.display_type === "is_blocked_by" && l.direction === "incoming");
@@ -677,14 +633,6 @@ function synthesizeOneThing(card, subtasks, links, assembledContext) {
     const blocker = blockers[0];
     return `Unblock first: resolve #${blocker.target_card.short_id} "${blocker.target_card.title}" which is blocking this card.`;
   }
-  const session = assembledContext ? extractSessionInsights(assembledContext) : null;
-  if (session?.blockers && session.blockers.length > 0) {
-    return `Resolve blocker: ${session.blockers[0]}`;
-  }
-  if (session?.lastSessionStatus === "paused" && session.lastSessionTask) {
-    const progress = session.lastSessionProgress ? ` (was ${session.lastSessionProgress}% complete)` : "";
-    return `Resume previous session${progress}: "${session.lastSessionTask}".`;
-  }
   if (subtasks.length > 0) {
     const completed = subtasks.filter((s) => s.completed).length;
     if (completed === subtasks.length) {
@@ -695,12 +643,6 @@ function synthesizeOneThing(card, subtasks, links, assembledContext) {
       return `Work on next subtask: "${nextSubtask.title}" (${completed}/${subtasks.length} done).`;
     }
   }
-  if (session?.procedureNextStep) {
-    return `Follow procedure: ${session.procedureNextStep}`;
-  }
-  if (session?.lastSessionStatus === "completed" && session.lastSessionTask) {
-    return `Previous session completed ("${session.lastSessionTask}"). Review results and continue with remaining work.`;
-  }
   if (card.due_date && (card.priority === "urgent" || card.priority === "high")) {
     return `High-priority task with deadline ${card.due_date}. Start implementation immediately.`;
   }
@@ -885,6 +827,9 @@ var init_prompt_builder = __esm(() => {
     execute: `EXECUTE MODE: Implement this task completely. Write production-ready code following best practices. Include necessary tests and documentation.`
   };
 });
+
+// src/api-client.ts
+import { randomUUID as randomUUID2 } from "node:crypto";
 // ../harmony-shared/dist/agentStaleness.js
 var AGENT_HEARTBEAT_LIVENESS_MS = 5 * 60 * 1000;
 var AGENT_MILESTONE_LIVENESS_MS = 30 * 60 * 1000;
@@ -1006,6 +951,12 @@ var TIMINGS = {
   QUERY_STALE_TIME: 1000 * 60 * 5,
   QUERY_GC_TIME: 1000 * 60 * 60 * 24
 };
+// ../harmony-shared/dist/fanoutSource.js
+var FANOUT_KEY_MARKER = "harmony:fanout-item";
+var FANOUT_KEY_RE = new RegExp(`^\\[${FANOUT_KEY_MARKER}\\]:\\s*#(\\S+)\\s*$`, "m");
+// ../harmony-shared/dist/gateConfigError.js
+var GATE_CONFIG_ERROR_KEY = "configError";
+var GATE_CONFIG_ERROR_MARK = Object.freeze({ [GATE_CONFIG_ERROR_KEY]: true });
 // ../harmony-shared/dist/playbookStage.js
 var STAGE_DAEMON_OWNED_TOOLS = [
   "mcp__harmony__harmony_end_agent_session",
@@ -1046,6 +997,19 @@ function getRetryDelay(attempt) {
   return Math.round(delay + delay * 0.25 * (Math.random() * 2 - 1));
 }
 var sleep2 = (ms) => new Promise((resolve2) => setTimeout(resolve2, ms));
+function buildMemoryQuery(title, description) {
+  const DESCRIPTION_CAP = 600;
+  const trimmedTitle = title.trim();
+  const trimmedBody = (description ?? "").trim();
+  if (!trimmedTitle && !trimmedBody)
+    return "";
+  if (!trimmedTitle)
+    return trimmedBody.slice(0, DESCRIPTION_CAP);
+  if (!trimmedBody)
+    return trimmedTitle;
+  return `${trimmedTitle}
+${trimmedBody.slice(0, DESCRIPTION_CAP)}`;
+}
 
 class Semaphore {
   permits;
@@ -1351,8 +1315,12 @@ class HarmonyApiClient {
   async updateCard(cardId, updates) {
     return this.request("PATCH", `/cards/${cardId}`, updates);
   }
-  async claimCard(cardId, agentId) {
-    const res = await this.request("PATCH", `/cards/${cardId}`, { assignedAgentId: agentId, ifAssignedAgentNull: true });
+  async claimCard(cardId, agentId, opts) {
+    const res = await this.request("PATCH", `/cards/${cardId}`, {
+      assignedAgentId: agentId,
+      ifAssignedAgentNull: true,
+      ...opts?.requireUnassigned ? { ifAssigneeNull: true } : {}
+    });
     return { claimed: res.claimed !== false };
   }
   async moveCard(cardId, columnId, position) {
@@ -1516,6 +1484,14 @@ class HarmonyApiClient {
     params.set("sinceSeq", String(sinceSeq));
     return this.request("GET", `/cards/${cardId}/agent-messages?${params.toString()}`);
   }
+  async postBudgetDecision(cardId, data) {
+    return this.request("POST", `/cards/${cardId}/budget-decisions`, data);
+  }
+  async getBudgetDecisions(cardId, sinceIso) {
+    const params = new URLSearchParams;
+    params.set("sinceIso", sinceIso);
+    return this.request("GET", `/cards/${cardId}/budget-decisions?${params.toString()}`);
+  }
   async updateAgentProgress(cardId, data) {
     return this.request("POST", `/cards/${cardId}/agent-context`, data);
   }
@@ -1561,6 +1537,8 @@ class HarmonyApiClient {
       params.set("offset", String(options.offset));
     if (options.include_superseded)
       params.set("include_superseded", "true");
+    if (options.consumer)
+      params.set("consumer", options.consumer);
     if (options.include_episodes)
       params.set("include_episodes", "true");
     return this.request("GET", `/memory/entities?${params.toString()}`);
@@ -1616,6 +1594,12 @@ class HarmonyApiClient {
     if (options.topK !== undefined) {
       entities = entities.slice(0, options.topK);
     }
+    if (options.consumer) {
+      const deliveredIds = entities.map((e) => e.id).filter((id) => typeof id === "string");
+      if (deliveredIds.length > 0) {
+        this.batchTouchMemoryEntities(deliveredIds, options.consumer).catch(() => {});
+      }
+    }
     return { entities };
   }
   async deleteMemoryEntity(entityId) {
@@ -1624,9 +1608,10 @@ class HarmonyApiClient {
   async touchMemoryEntity(entityId) {
     return this.request("POST", `/memory/entities/${entityId}/touch`);
   }
-  async batchTouchMemoryEntities(entityIds) {
+  async batchTouchMemoryEntities(entityIds, consumer) {
     return this.request("POST", "/memory/entities/batch-touch", {
-      entity_ids: entityIds
+      entity_ids: entityIds,
+      ...consumer ? { consumer } : {}
     });
   }
   async createMemoryRelation(data) {
@@ -1652,8 +1637,12 @@ class HarmonyApiClient {
       params.append("tags", tag);
     if (options?.include_superseded)
       params.set("include_superseded", "true");
+    if (options?.consumer)
+      params.set("consumer", options.consumer);
     if (options?.include_episodes)
       params.set("include_episodes", "true");
+    if (options?.assembly_id)
+      params.set("assembly_id", options.assembly_id);
     return this.request("GET", `/memory/search?${params.toString()}`);
   }
   async getVaultIndex(options) {
@@ -1665,6 +1654,8 @@ class HarmonyApiClient {
       params.set("type", options.type);
     if (options.limit !== undefined)
       params.set("limit", String(options.limit));
+    if (options.consumer)
+      params.set("consumer", options.consumer);
     if (options.include_episodes)
       params.set("include_episodes", "true");
     return this.request("GET", `/memory/index?${params.toString()}`);
@@ -1678,6 +1669,8 @@ class HarmonyApiClient {
       params.set("type", options.type);
     if (options.limit !== undefined)
       params.set("limit", String(options.limit));
+    if (options.consumer)
+      params.set("consumer", options.consumer);
     if (options.include_episodes)
       params.set("include_episodes", "true");
     return this.requestRaw("GET", `/memory/index?${params.toString()}`, undefined, {
@@ -1737,6 +1730,8 @@ class HarmonyApiClient {
       params.set("type", options.type);
     if (options?.limit !== undefined)
       params.set("limit", String(options.limit));
+    if (options?.consumer)
+      params.set("consumer", options.consumer);
     if (options?.include_episodes)
       params.set("include_episodes", "true");
     return this.requestRaw("GET", `/memory/search?${params.toString()}`, undefined, {
@@ -1842,14 +1837,15 @@ class HarmonyApiClient {
       } catch {}
     }
     const variant = options.variant || "execute";
-    const assembledContextStr = undefined;
-    const assemblyId = undefined;
+    const assemblyId = randomUUID2();
     let memories;
     try {
       if (options.workspaceId && cardData.title) {
-        const memoryResult = await this.searchMemoryEntities(options.workspaceId, cardData.title, {
+        const memoryResult = await this.searchMemoryEntities(options.workspaceId, buildMemoryQuery(cardData.title, cardData.description), {
           project_id: options.projectId,
-          limit: 5
+          limit: 5,
+          consumer: "agent-prompt",
+          assembly_id: assemblyId
         });
         if (memoryResult.entities?.length > 0) {
           memories = memoryResult.entities.map((e) => ({
@@ -1873,7 +1869,6 @@ class HarmonyApiClient {
       contextOptions: options.contextOptions,
       customConstraints: options.customConstraints,
       memories,
-      assembledContext: assembledContextStr,
       assemblyId
     });
     try {
@@ -1983,6 +1978,7 @@ export {
   resetClient,
   requestWithBearer,
   getClient,
+  buildMemoryQuery,
   HarmonyUnauthorizedError,
   HarmonyApiClient
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gethmy/mcp",
-  "version": "2.24.0",
+  "version": "2.26.0",
   "description": "MCP server for Harmony, the shared surface for human–agent teams — agents claim cards, report progress, and move work on your board.",
   "publishConfig": {
     "access": "public"

package/src/api-client.ts

@@ -1,3 +1,4 @@
+import { randomUUID } from "node:crypto";
 import {
   type AgentRunEventDraft,
   type Comment,
@@ -9,6 +10,7 @@ import {
   type WorkspaceAgent,
 } from "@harmony/shared";
 import { getApiKey, getApiUrl } from "./config.js";
+import type { ReadConsumer } from "./read-consumer.js";
 
 export interface ApiResponse<T = unknown> {
   success?: boolean;
@@ -49,6 +51,27 @@ function getRetryDelay(attempt: number): number {
 
 const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
 
+/**
+ * Build the recall query for a card. The title alone was the whole query, which
+ * is too thin to rank against. The description is capped because a card body
+ * runs to 10,000 characters, the embedding truncates at END, and an uncapped
+ * body drowns the title it is meant to sharpen.
+ */
+export function buildMemoryQuery(
+  title: string,
+  description: string | null | undefined,
+): string {
+  const DESCRIPTION_CAP = 600;
+  const trimmedTitle = title.trim();
+  const trimmedBody = (description ?? "").trim();
+
+  if (!trimmedTitle && !trimmedBody) return "";
+  if (!trimmedTitle) return trimmedBody.slice(0, DESCRIPTION_CAP);
+  if (!trimmedBody) return trimmedTitle;
+
+  return `${trimmedTitle}\n${trimmedBody.slice(0, DESCRIPTION_CAP)}`;
+}
+
 // Semaphore for concurrency control
 class Semaphore {
   private permits: number;
@@ -532,7 +555,17 @@ export class HarmonyApiClient {
   /** Register/upsert this daemon's virtual agent. Idempotent by (workspace, identifier). */
   async registerWorkspaceAgent(
     workspaceId: string,
-    data: { identifier: string; name: string; color?: string },
+    data: {
+      identifier: string;
+      name: string;
+      color?: string;
+      /**
+       * Gate metric NAMES the daemon declares under `agent.playbooks.metrics`
+       * (#922) — names only, never the commands behind them. Omit to leave the
+       * stored report untouched.
+       */
+      declaredGateMetrics?: string[];
+    },
   ): Promise<{ agent: WorkspaceAgent }> {
     return this.request("POST", `/workspaces/${workspaceId}/agents`, data);
   }
@@ -691,15 +724,27 @@ export class HarmonyApiClient {
    * Compare-and-set claim of a card for a virtual agent: sets assigned_agent_id
    * only if it is currently NULL (server-side guard). Returns `{ claimed: false }`
    * when another daemon already owns it. Used by the agent-agnostic review pickup.
+   *
+   * `requireUnassigned` additionally guards `assignee_id IS NULL`, so the claim
+   * also loses to a PERSON who took the card. Self-selection (sweep, card #978)
+   * needs it: this write clears `assignee_id` as a side effect, so the agent-only
+   * guard does not merely let the daemon co-own a person's card — it lets the
+   * daemon erase their assignment. Default false keeps the review-strand claim
+   * (which reaches only cards no one holds) byte-unchanged.
    */
   async claimCard(
     cardId: string,
     agentId: string,
+    opts?: { requireUnassigned?: boolean },
   ): Promise<{ claimed: boolean }> {
     const res = await this.request<{ card?: unknown; claimed?: boolean }>(
       "PATCH",
       `/cards/${cardId}`,
-      { assignedAgentId: agentId, ifAssignedAgentNull: true },
+      {
+        assignedAgentId: agentId,
+        ifAssignedAgentNull: true,
+        ...(opts?.requireUnassigned ? { ifAssigneeNull: true } : {}),
+      },
     );
     // Success body is `{ card }` (no `claimed` key) → won. Lost-race body is
     // `{ claimed: false }`.
@@ -1097,6 +1142,15 @@ export class HarmonyApiClient {
        * working); the MCP tool dispatch defaults to `interactive`.
        */
       driver?: "daemon" | "interactive" | "script";
+      /**
+       * When a human budget decision is pending on this session, as an ISO
+       * timestamp (card #915). A run START passes `null` explicitly: the route
+       * REUSES a live session row, so a card whose previous run parked would
+       * otherwise inherit that park's deadline — the panel offering Continue
+       * over a run that is already going again, and the sweep exemption
+       * masking a genuinely dead run for the rest of the window.
+       */
+      awaitingDecisionUntil?: string | null;
     },
   ): Promise<{
     session: unknown;
@@ -1147,6 +1201,53 @@ export class HarmonyApiClient {
     );
   }
 
+  /**
+   * Post a human's durable answer to a parked run's budget question (card
+   * #915): grant more turns and continue, or stop and hand the card back.
+   *
+   * Unlike pause/resume/stop — an ephemeral Realtime broadcast nothing hears
+   * once the daemon is offline — this MUST survive a daemon restart hours
+   * later, so it lands as a `budget_decision` row rather than a broadcast.
+   * The server resolves which run to decide for from the card's one active
+   * session; the caller does not (and, deciding from the board, cannot) name
+   * a session id.
+   */
+  async postBudgetDecision(
+    cardId: string,
+    data: {
+      decision: "continue" | "stop";
+      extraTurns: number;
+      message?: string;
+    },
+  ): Promise<{ id: string; seq: number; createdAt: string }> {
+    return this.request("POST", `/cards/${cardId}/budget-decisions`, data);
+  }
+
+  /**
+   * Drain `budget_decision` events for a card since `sinceIso` (card #915).
+   * Keyed on card + time, not session + seq like `getPendingMessages`: the
+   * daemon asking on startup may not know the session id of a run it parked
+   * hours or days earlier, but it always knows the card.
+   */
+  async getBudgetDecisions(
+    cardId: string,
+    sinceIso: string,
+  ): Promise<{
+    decisions: Array<{
+      decision: "continue" | "stop";
+      extraTurns: number;
+      message?: string;
+      createdAt: string;
+    }>;
+  }> {
+    const params = new URLSearchParams();
+    params.set("sinceIso", sinceIso);
+    return this.request(
+      "GET",
+      `/cards/${cardId}/budget-decisions?${params.toString()}`,
+    );
+  }
+
   async updateAgentProgress(
     cardId: string,
     data: {
@@ -1205,6 +1306,16 @@ export class HarmonyApiClient {
        * deferred the respawn by 10 minutes (#770). Reply carries `stopped: true`.
        */
       implicitCreate?: boolean;
+      /**
+       * Set while the session waits for a human budget decision (#915),
+       * cleared (null) once one arrives. Exempts the row from the daemon's
+       * stale-session sweep until this instant — a parked run's deliberate
+       * silence would otherwise read as abandonment well before a person can
+       * answer. ISO timestamp string; the daemon-side mirror
+       * (`StateStore.parkRun`'s `awaitingDecisionUntil`) is the same instant
+       * in epoch ms, not this string.
+       */
+      awaitingDecisionUntil?: string | null;
     },
   ): Promise<{
     session: unknown;
@@ -1351,6 +1462,9 @@ export class HarmonyApiClient {
     // Opt in to agent-run episodes (default excluded, #677). Only the daemon's
     // own rolling-episode lookup should set this.
     include_episodes?: boolean;
+    /** Read-accounting label (task 4) — omitted means the read is not
+     * recorded. Callers that know their own identity should pass it. */
+    consumer?: ReadConsumer;
   }): Promise<{ entities: unknown[]; count: number }> {
     const params = new URLSearchParams();
     params.set("workspace_id", options.workspace_id);
@@ -1367,6 +1481,7 @@ export class HarmonyApiClient {
     if (options.offset !== undefined)
       params.set("offset", String(options.offset));
     if (options.include_superseded) params.set("include_superseded", "true");
+    if (options.consumer) params.set("consumer", options.consumer);
     if (options.include_episodes) params.set("include_episodes", "true");
     return this.request("GET", `/memory/entities?${params.toString()}`);
   }
@@ -1419,9 +1534,17 @@ export class HarmonyApiClient {
     // Opt in to agent-run episodes (default excluded server-side, #677). The
     // daemon sets this when looking up its own rolling implement/review episode.
     includeEpisodes?: boolean;
+    /** Read-accounting label (task 4) — omitted means the read is not
+     * recorded. Callers that know their own identity should pass it. */
+    consumer?: ReadConsumer;
   }): Promise<{ entities: unknown[] }> {
     // Over-fetch beyond topK so client-side filters (multi-type, memory_tier,
     // tags) have headroom — matches the MCP server's recall path (server.ts).
+    // `consumer` is deliberately NOT forwarded on this over-fetch: the server
+    // would record read-accounting for every over-fetched row, not just the
+    // ones actually delivered. Instead we record the delivered set below,
+    // after client-side filtering and the topK trim (mirrors the mcp-tool
+    // path in server.ts).
     const fetchLimit = Math.max(options.topK ?? 3, 50);
     let entities: Array<Record<string, unknown>> = [];
 
@@ -1483,6 +1606,21 @@ export class HarmonyApiClient {
       entities = entities.slice(0, options.topK);
     }
 
+    // Read accounting: record only the entities actually delivered to the
+    // caller, after all client-side filtering and the topK trim — never the
+    // larger over-fetched candidate pool the calls above deliberately left
+    // unrecorded. Best-effort; a recording failure must not fail the recall.
+    if (options.consumer) {
+      const deliveredIds = entities
+        .map((e) => e.id)
+        .filter((id): id is string => typeof id === "string");
+      if (deliveredIds.length > 0) {
+        this.batchTouchMemoryEntities(deliveredIds, options.consumer).catch(
+          () => {},
+        );
+      }
+    }
+
     return { entities };
   }
 
@@ -1496,9 +1634,16 @@ export class HarmonyApiClient {
 
   async batchTouchMemoryEntities(
     entityIds: string[],
+    /** Read-accounting label (task 4, fix round 1). Omitted → the route keeps
+     * its original increment-only `batch_touch_knowledge_entities` behaviour
+     * (legacy context-assembly callers). Given → the route instead records
+     * through `record_entity_reads`, the same path the search chokepoint
+     * uses, so this touch is properly attributed rather than anonymous. */
+    consumer?: ReadConsumer,
   ): Promise<{ success: boolean; count: number }> {
     return this.request("POST", "/memory/entities/batch-touch", {
       entity_ids: entityIds,
+      ...(consumer ? { consumer } : {}),
     });
   }
 
@@ -1533,6 +1678,16 @@ export class HarmonyApiClient {
       tags?: string[];
       include_superseded?: boolean;
       include_episodes?: boolean;
+      /** Read-accounting label (task 4) — omitted means the read is not
+       * recorded (there is deliberately no server-side default: it used to
+       * default to "search" and inflated access_count on every
+       * `harmony_remember` write-side probe). Callers that know their own
+       * identity (harmony_recall) should pass it explicitly. */
+      consumer?: ReadConsumer;
+      /** Per-prompt-build id (task 6b) — shared by every read row recorded
+       * during one `generateCardPrompt` call, so a card can later show which
+       * memories shaped its prompt. */
+      assembly_id?: string;
     },
   ): Promise<{ entities: unknown[]; count: number }> {
     const params = new URLSearchParams();
@@ -1546,7 +1701,9 @@ export class HarmonyApiClient {
     // matches against the canonical `tags_normalized` column (#299).
     for (const tag of options?.tags ?? []) params.append("tags", tag);
     if (options?.include_superseded) params.set("include_superseded", "true");
+    if (options?.consumer) params.set("consumer", options.consumer);
     if (options?.include_episodes) params.set("include_episodes", "true");
+    if (options?.assembly_id) params.set("assembly_id", options.assembly_id);
     return this.request("GET", `/memory/search?${params.toString()}`);
   }
 
@@ -1558,12 +1715,16 @@ export class HarmonyApiClient {
     type?: string;
     limit?: number;
     include_episodes?: boolean;
+    /** Read-accounting label (task 4) — omitted means the read is not
+     * recorded. Callers that know their own identity should pass it. */
+    consumer?: ReadConsumer;
   }): Promise<{ entities: unknown[]; count: number }> {
     const params = new URLSearchParams();
     params.set("workspace_id", options.workspace_id);
     if (options.project_id) params.set("project_id", options.project_id);
     if (options.type) params.set("type", options.type);
     if (options.limit !== undefined) params.set("limit", String(options.limit));
+    if (options.consumer) params.set("consumer", options.consumer);
     if (options.include_episodes) params.set("include_episodes", "true");
     return this.request("GET", `/memory/index?${params.toString()}`);
   }
@@ -1574,12 +1735,16 @@ export class HarmonyApiClient {
     type?: string;
     limit?: number;
     include_episodes?: boolean;
+    /** Read-accounting label (task 4) — omitted means the read is not
+     * recorded. Callers that know their own identity should pass it. */
+    consumer?: ReadConsumer;
   }): Promise<string> {
     const params = new URLSearchParams();
     params.set("workspace_id", options.workspace_id);
     if (options.project_id) params.set("project_id", options.project_id);
     if (options.type) params.set("type", options.type);
     if (options.limit !== undefined) params.set("limit", String(options.limit));
+    if (options.consumer) params.set("consumer", options.consumer);
     if (options.include_episodes) params.set("include_episodes", "true");
     return this.requestRaw(
       "GET",
@@ -1668,6 +1833,9 @@ export class HarmonyApiClient {
       type?: string;
       limit?: number;
       include_episodes?: boolean;
+      /** Read-accounting label (task 4) — omitted means the read is not
+       * recorded. Callers that know their own identity should pass it. */
+      consumer?: ReadConsumer;
     },
   ): Promise<string> {
     const params = new URLSearchParams();
@@ -1677,6 +1845,7 @@ export class HarmonyApiClient {
     if (options?.type) params.set("type", options.type);
     if (options?.limit !== undefined)
       params.set("limit", String(options.limit));
+    if (options?.consumer) params.set("consumer", options.consumer);
     if (options?.include_episodes) params.set("include_episodes", "true");
     return this.requestRaw(
       "GET",
@@ -1978,18 +2147,22 @@ export class HarmonyApiClient {
     // Phase 0 (memory architecture v2): full context assembly removed.
     // Use the basic memory search path so callers still get _some_ memory
     // hints. Phase 1 will reintroduce a session-scoped working memory layer.
-    const assembledContextStr: string | undefined = undefined;
-    const assemblyId: string | undefined = undefined;
+
+    // One id per prompt build. Every read row recorded during this build carries
+    // it, which is what lets a card show the memories that shaped its prompt.
+    const assemblyId = randomUUID();
     let memories: MemoryItem[] | undefined;
 
     try {
       if (options.workspaceId && cardData.title) {
         const memoryResult = await this.searchMemoryEntities(
           options.workspaceId,
-          cardData.title,
+          buildMemoryQuery(cardData.title, cardData.description),
           {
             project_id: options.projectId,
             limit: 5,
+            consumer: "agent-prompt",
+            assembly_id: assemblyId,
           },
         );
         if (memoryResult.entities?.length > 0) {
@@ -2015,7 +2188,6 @@ export class HarmonyApiClient {
       contextOptions: options.contextOptions,
       customConstraints: options.customConstraints,
       memories,
-      assembledContext: assembledContextStr,
       assemblyId,
     });