@gethmy/mcp 2.15.0 → 2.17.0

package/dist/cli.js

@@ -1826,6 +1826,10 @@ 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 });
+    return { claimed: res.claimed !== false };
+  }
   async moveCard(cardId, columnId, position) {
     return this.request("POST", `/cards/${cardId}/move`, {
       columnId,
@@ -2028,6 +2032,8 @@ class HarmonyApiClient {
       params.set("offset", String(options.offset));
     if (options.include_superseded)
       params.set("include_superseded", "true");
+    if (options.include_episodes)
+      params.set("include_episodes", "true");
     return this.request("GET", `/memory/entities?${params.toString()}`);
   }
   async getMemoryEntity(entityId) {
@@ -2043,7 +2049,8 @@ class HarmonyApiClient {
       const search = await this.searchMemoryEntities(options.workspaceId, options.query, {
         project_id: options.projectId,
         type: options.type?.length === 1 ? options.type[0] : undefined,
-        limit: fetchLimit
+        limit: fetchLimit,
+        include_episodes: options.includeEpisodes
       });
       entities = search.entities ?? [];
     } else {
@@ -2054,7 +2061,8 @@ class HarmonyApiClient {
         type: options.type?.length === 1 ? options.type[0] : undefined,
         tags: options.tags,
         min_confidence: options.minConfidence,
-        limit: fetchLimit
+        limit: fetchLimit,
+        include_episodes: options.includeEpisodes
       });
       entities = list.entities ?? [];
     }
@@ -2115,6 +2123,8 @@ class HarmonyApiClient {
       params.append("tags", tag);
     if (options?.include_superseded)
       params.set("include_superseded", "true");
+    if (options?.include_episodes)
+      params.set("include_episodes", "true");
     return this.request("GET", `/memory/search?${params.toString()}`);
   }
   async getVaultIndex(options) {
@@ -2126,6 +2136,8 @@ class HarmonyApiClient {
       params.set("type", options.type);
     if (options.limit !== undefined)
       params.set("limit", String(options.limit));
+    if (options.include_episodes)
+      params.set("include_episodes", "true");
     return this.request("GET", `/memory/index?${params.toString()}`);
   }
   async getVaultIndexMarkdown(options) {
@@ -2137,6 +2149,8 @@ class HarmonyApiClient {
       params.set("type", options.type);
     if (options.limit !== undefined)
       params.set("limit", String(options.limit));
+    if (options.include_episodes)
+      params.set("include_episodes", "true");
     return this.requestRaw("GET", `/memory/index?${params.toString()}`, undefined, {
       accept: "text/markdown"
     });
@@ -2194,6 +2208,8 @@ class HarmonyApiClient {
       params.set("type", options.type);
     if (options?.limit !== undefined)
       params.set("limit", String(options.limit));
+    if (options?.include_episodes)
+      params.set("include_episodes", "true");
     return this.requestRaw("GET", `/memory/search?${params.toString()}`, undefined, {
       accept: "text/markdown"
     });
@@ -4829,6 +4845,10 @@ var TOOLS = {
         include_superseded: {
           type: "boolean",
           description: "Include rows whose `superseded_at` is set (default false). Use when investigating supersede chains."
+        },
+        include_episodes: {
+          type: "boolean",
+          description: "Include agent-run episodes — the daemon's per-run implement/review captures (default false). Excluded by default so recall surfaces curated, durable memory. Set true to audit the agent's run history."
         }
       }
     }
@@ -5014,7 +5034,11 @@ var TOOLS = {
           type: "string",
           description: "Project ID (optional)"
         },
-        limit: { type: "number", description: "Max results (default: 20)" }
+        limit: { type: "number", description: "Max results (default: 20)" },
+        include_episodes: {
+          type: "boolean",
+          description: "Include agent-run episodes — the daemon's per-run captures (default false). Excluded by default so search surfaces curated memory."
+        }
       },
       required: ["query"]
     }
@@ -5055,6 +5079,10 @@ var TOOLS = {
         limit: {
           type: "number",
           description: "Max entities to return (default: 200)"
+        },
+        include_episodes: {
+          type: "boolean",
+          description: "Include agent-run episodes — the daemon's per-run captures (default false). Excluded by default so the index shows curated vault content, not run noise."
         }
       },
       required: []
@@ -6335,11 +6363,11 @@ async function handleToolCall(name, args, deps) {
     }
     case "harmony_generate_prompt": {
       let cardId;
+      const projectId = args.projectId || deps.getActiveProjectId() || undefined;
       if (args.cardId) {
         cardId = z.string().uuid().parse(args.cardId);
       } else if (args.shortId !== undefined) {
         const shortId = z.number().int().positive().parse(args.shortId);
-        const projectId = args.projectId || deps.getActiveProjectId();
         if (!projectId) {
           throw new Error("Project ID required when using shortId. Use harmony_set_project_context or provide projectId.");
         }
@@ -6348,23 +6376,40 @@ async function handleToolCall(name, args, deps) {
       } else {
         throw new Error("Either cardId or shortId must be provided");
       }
-      let cardTitle = "";
-      let cardDescription = "";
+      const variant = args.variant || undefined;
+      const customConstraints = typeof args.customConstraints === "string" ? args.customConstraints : undefined;
+      const contextOptions = {
+        includeSubtasks: args.includeSubtasks !== false,
+        includeLinks: args.includeLinks !== false,
+        includeDescription: args.includeDescription !== false
+      };
       try {
-        const { card } = await client3.getCard(cardId);
-        const typedCard = card;
-        cardTitle = typedCard.title || "";
-        cardDescription = typedCard.description || "";
-      } catch {}
-      const taskBlock = [cardTitle, cardDescription].filter(Boolean).join(`
+        const result = await client3.generateCardPrompt({
+          cardId,
+          workspaceId: deps.getActiveWorkspaceId() || "",
+          projectId,
+          variant,
+          customConstraints,
+          contextOptions
+        });
+        return { success: true, ...result };
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.debug(`[harmony_generate_prompt] falling back: ${msg}`);
+        let cardTitle = "";
+        let cardDescription = "";
+        try {
+          const { card } = await client3.getCard(cardId);
+          const typedCard = card;
+          cardTitle = typedCard.title || "";
+          cardDescription = typedCard.description || "";
+        } catch {}
+        const taskBlock = [cardTitle, cardDescription].filter(Boolean).join(`
 
 `);
-      const prompt = `Here is the task: ${taskBlock || "(no description available)"}`;
-      return {
-        success: true,
-        prompt,
-        cardId
-      };
+        const prompt = `Here is the task: ${taskBlock || "(no description available)"}`;
+        return { success: true, prompt, cardId };
+      }
     }
     case "harmony_remember": {
       const title = z.string().min(1).max(300).parse(args.title);
@@ -6465,6 +6510,7 @@ async function handleToolCall(name, args, deps) {
       const topK = args.top_k;
       const budgetTokens = args.budget_tokens;
       const includeSuperseded = Boolean(args.include_superseded);
+      const includeEpisodes = Boolean(args.include_episodes);
       const queryText = args.query;
       const fetchLimit = Math.min(Math.max(requestedLimit ?? 20, topK ?? 0, 50), 200);
       const projectId = args.projectId || deps.getActiveProjectId() || undefined;
@@ -6481,7 +6527,8 @@ async function handleToolCall(name, args, deps) {
           type: args.type,
           limit: fetchLimit,
           tags: requestedTags && requestedTags.length > 0 ? requestedTags : undefined,
-          include_superseded: includeSuperseded
+          include_superseded: includeSuperseded,
+          include_episodes: includeEpisodes
         });
         entities = searchResult.entities ?? [];
         const minConfidence = args.minConfidence;
@@ -6504,7 +6551,8 @@ async function handleToolCall(name, args, deps) {
           tags: args.tags,
           min_confidence: args.minConfidence,
           limit: fetchLimit,
-          include_superseded: includeSuperseded
+          include_superseded: includeSuperseded,
+          include_episodes: includeEpisodes
         });
         entities = listed;
         if (excludeSessionFromLongTerm) {
@@ -6724,7 +6772,8 @@ async function handleToolCall(name, args, deps) {
       const markdown = await client3.searchMemoryEntitiesMarkdown(workspaceId, query, {
         project_id: args.projectId || deps.getActiveProjectId() || undefined,
         type: args.type,
-        limit: args.limit
+        limit: args.limit,
+        include_episodes: Boolean(args.include_episodes)
       });
       const searchMemSession = getActiveMemorySession();
       if (searchMemSession) {
@@ -6741,7 +6790,8 @@ async function handleToolCall(name, args, deps) {
         workspace_id: workspaceId,
         project_id: args.projectId || deps.getActiveProjectId() || undefined,
         type: args.type,
-        limit: args.limit
+        limit: args.limit,
+        include_episodes: Boolean(args.include_episodes)
       });
       return markdown || "No entities found.";
     }

package/dist/index.js

@@ -1821,6 +1821,10 @@ 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 });
+    return { claimed: res.claimed !== false };
+  }
   async moveCard(cardId, columnId, position) {
     return this.request("POST", `/cards/${cardId}/move`, {
       columnId,
@@ -2023,6 +2027,8 @@ class HarmonyApiClient {
       params.set("offset", String(options.offset));
     if (options.include_superseded)
       params.set("include_superseded", "true");
+    if (options.include_episodes)
+      params.set("include_episodes", "true");
     return this.request("GET", `/memory/entities?${params.toString()}`);
   }
   async getMemoryEntity(entityId) {
@@ -2038,7 +2044,8 @@ class HarmonyApiClient {
       const search = await this.searchMemoryEntities(options.workspaceId, options.query, {
         project_id: options.projectId,
         type: options.type?.length === 1 ? options.type[0] : undefined,
-        limit: fetchLimit
+        limit: fetchLimit,
+        include_episodes: options.includeEpisodes
       });
       entities = search.entities ?? [];
     } else {
@@ -2049,7 +2056,8 @@ class HarmonyApiClient {
         type: options.type?.length === 1 ? options.type[0] : undefined,
         tags: options.tags,
         min_confidence: options.minConfidence,
-        limit: fetchLimit
+        limit: fetchLimit,
+        include_episodes: options.includeEpisodes
       });
       entities = list.entities ?? [];
     }
@@ -2110,6 +2118,8 @@ class HarmonyApiClient {
       params.append("tags", tag);
     if (options?.include_superseded)
       params.set("include_superseded", "true");
+    if (options?.include_episodes)
+      params.set("include_episodes", "true");
     return this.request("GET", `/memory/search?${params.toString()}`);
   }
   async getVaultIndex(options) {
@@ -2121,6 +2131,8 @@ class HarmonyApiClient {
       params.set("type", options.type);
     if (options.limit !== undefined)
       params.set("limit", String(options.limit));
+    if (options.include_episodes)
+      params.set("include_episodes", "true");
     return this.request("GET", `/memory/index?${params.toString()}`);
   }
   async getVaultIndexMarkdown(options) {
@@ -2132,6 +2144,8 @@ class HarmonyApiClient {
       params.set("type", options.type);
     if (options.limit !== undefined)
       params.set("limit", String(options.limit));
+    if (options.include_episodes)
+      params.set("include_episodes", "true");
     return this.requestRaw("GET", `/memory/index?${params.toString()}`, undefined, {
       accept: "text/markdown"
     });
@@ -2189,6 +2203,8 @@ class HarmonyApiClient {
       params.set("type", options.type);
     if (options?.limit !== undefined)
       params.set("limit", String(options.limit));
+    if (options?.include_episodes)
+      params.set("include_episodes", "true");
     return this.requestRaw("GET", `/memory/search?${params.toString()}`, undefined, {
       accept: "text/markdown"
     });
@@ -4824,6 +4840,10 @@ var TOOLS = {
         include_superseded: {
           type: "boolean",
           description: "Include rows whose `superseded_at` is set (default false). Use when investigating supersede chains."
+        },
+        include_episodes: {
+          type: "boolean",
+          description: "Include agent-run episodes — the daemon's per-run implement/review captures (default false). Excluded by default so recall surfaces curated, durable memory. Set true to audit the agent's run history."
         }
       }
     }
@@ -5009,7 +5029,11 @@ var TOOLS = {
           type: "string",
           description: "Project ID (optional)"
         },
-        limit: { type: "number", description: "Max results (default: 20)" }
+        limit: { type: "number", description: "Max results (default: 20)" },
+        include_episodes: {
+          type: "boolean",
+          description: "Include agent-run episodes — the daemon's per-run captures (default false). Excluded by default so search surfaces curated memory."
+        }
       },
       required: ["query"]
     }
@@ -5050,6 +5074,10 @@ var TOOLS = {
         limit: {
           type: "number",
           description: "Max entities to return (default: 200)"
+        },
+        include_episodes: {
+          type: "boolean",
+          description: "Include agent-run episodes — the daemon's per-run captures (default false). Excluded by default so the index shows curated vault content, not run noise."
         }
       },
       required: []
@@ -6330,11 +6358,11 @@ async function handleToolCall(name, args, deps) {
     }
     case "harmony_generate_prompt": {
       let cardId;
+      const projectId = args.projectId || deps.getActiveProjectId() || undefined;
       if (args.cardId) {
         cardId = z.string().uuid().parse(args.cardId);
       } else if (args.shortId !== undefined) {
         const shortId = z.number().int().positive().parse(args.shortId);
-        const projectId = args.projectId || deps.getActiveProjectId();
         if (!projectId) {
           throw new Error("Project ID required when using shortId. Use harmony_set_project_context or provide projectId.");
         }
@@ -6343,23 +6371,40 @@ async function handleToolCall(name, args, deps) {
       } else {
         throw new Error("Either cardId or shortId must be provided");
       }
-      let cardTitle = "";
-      let cardDescription = "";
+      const variant = args.variant || undefined;
+      const customConstraints = typeof args.customConstraints === "string" ? args.customConstraints : undefined;
+      const contextOptions = {
+        includeSubtasks: args.includeSubtasks !== false,
+        includeLinks: args.includeLinks !== false,
+        includeDescription: args.includeDescription !== false
+      };
       try {
-        const { card } = await client3.getCard(cardId);
-        const typedCard = card;
-        cardTitle = typedCard.title || "";
-        cardDescription = typedCard.description || "";
-      } catch {}
-      const taskBlock = [cardTitle, cardDescription].filter(Boolean).join(`
+        const result = await client3.generateCardPrompt({
+          cardId,
+          workspaceId: deps.getActiveWorkspaceId() || "",
+          projectId,
+          variant,
+          customConstraints,
+          contextOptions
+        });
+        return { success: true, ...result };
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.debug(`[harmony_generate_prompt] falling back: ${msg}`);
+        let cardTitle = "";
+        let cardDescription = "";
+        try {
+          const { card } = await client3.getCard(cardId);
+          const typedCard = card;
+          cardTitle = typedCard.title || "";
+          cardDescription = typedCard.description || "";
+        } catch {}
+        const taskBlock = [cardTitle, cardDescription].filter(Boolean).join(`
 
 `);
-      const prompt = `Here is the task: ${taskBlock || "(no description available)"}`;
-      return {
-        success: true,
-        prompt,
-        cardId
-      };
+        const prompt = `Here is the task: ${taskBlock || "(no description available)"}`;
+        return { success: true, prompt, cardId };
+      }
     }
     case "harmony_remember": {
       const title = z.string().min(1).max(300).parse(args.title);
@@ -6460,6 +6505,7 @@ async function handleToolCall(name, args, deps) {
       const topK = args.top_k;
       const budgetTokens = args.budget_tokens;
       const includeSuperseded = Boolean(args.include_superseded);
+      const includeEpisodes = Boolean(args.include_episodes);
       const queryText = args.query;
       const fetchLimit = Math.min(Math.max(requestedLimit ?? 20, topK ?? 0, 50), 200);
       const projectId = args.projectId || deps.getActiveProjectId() || undefined;
@@ -6476,7 +6522,8 @@ async function handleToolCall(name, args, deps) {
           type: args.type,
           limit: fetchLimit,
           tags: requestedTags && requestedTags.length > 0 ? requestedTags : undefined,
-          include_superseded: includeSuperseded
+          include_superseded: includeSuperseded,
+          include_episodes: includeEpisodes
         });
         entities = searchResult.entities ?? [];
         const minConfidence = args.minConfidence;
@@ -6499,7 +6546,8 @@ async function handleToolCall(name, args, deps) {
           tags: args.tags,
           min_confidence: args.minConfidence,
           limit: fetchLimit,
-          include_superseded: includeSuperseded
+          include_superseded: includeSuperseded,
+          include_episodes: includeEpisodes
         });
         entities = listed;
         if (excludeSessionFromLongTerm) {
@@ -6719,7 +6767,8 @@ async function handleToolCall(name, args, deps) {
       const markdown = await client3.searchMemoryEntitiesMarkdown(workspaceId, query, {
         project_id: args.projectId || deps.getActiveProjectId() || undefined,
         type: args.type,
-        limit: args.limit
+        limit: args.limit,
+        include_episodes: Boolean(args.include_episodes)
       });
       const searchMemSession = getActiveMemorySession();
       if (searchMemSession) {
@@ -6736,7 +6785,8 @@ async function handleToolCall(name, args, deps) {
         workspace_id: workspaceId,
         project_id: args.projectId || deps.getActiveProjectId() || undefined,
         type: args.type,
-        limit: args.limit
+        limit: args.limit,
+        include_episodes: Boolean(args.include_episodes)
       });
       return markdown || "No entities found.";
     }

package/dist/lib/api-client.js

@@ -1273,6 +1273,10 @@ 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 });
+    return { claimed: res.claimed !== false };
+  }
   async moveCard(cardId, columnId, position) {
     return this.request("POST", `/cards/${cardId}/move`, {
       columnId,
@@ -1475,6 +1479,8 @@ class HarmonyApiClient {
       params.set("offset", String(options.offset));
     if (options.include_superseded)
       params.set("include_superseded", "true");
+    if (options.include_episodes)
+      params.set("include_episodes", "true");
     return this.request("GET", `/memory/entities?${params.toString()}`);
   }
   async getMemoryEntity(entityId) {
@@ -1490,7 +1496,8 @@ class HarmonyApiClient {
       const search = await this.searchMemoryEntities(options.workspaceId, options.query, {
         project_id: options.projectId,
         type: options.type?.length === 1 ? options.type[0] : undefined,
-        limit: fetchLimit
+        limit: fetchLimit,
+        include_episodes: options.includeEpisodes
       });
       entities = search.entities ?? [];
     } else {
@@ -1501,7 +1508,8 @@ class HarmonyApiClient {
         type: options.type?.length === 1 ? options.type[0] : undefined,
         tags: options.tags,
         min_confidence: options.minConfidence,
-        limit: fetchLimit
+        limit: fetchLimit,
+        include_episodes: options.includeEpisodes
       });
       entities = list.entities ?? [];
     }
@@ -1562,6 +1570,8 @@ class HarmonyApiClient {
       params.append("tags", tag);
     if (options?.include_superseded)
       params.set("include_superseded", "true");
+    if (options?.include_episodes)
+      params.set("include_episodes", "true");
     return this.request("GET", `/memory/search?${params.toString()}`);
   }
   async getVaultIndex(options) {
@@ -1573,6 +1583,8 @@ class HarmonyApiClient {
       params.set("type", options.type);
     if (options.limit !== undefined)
       params.set("limit", String(options.limit));
+    if (options.include_episodes)
+      params.set("include_episodes", "true");
     return this.request("GET", `/memory/index?${params.toString()}`);
   }
   async getVaultIndexMarkdown(options) {
@@ -1584,6 +1596,8 @@ class HarmonyApiClient {
       params.set("type", options.type);
     if (options.limit !== undefined)
       params.set("limit", String(options.limit));
+    if (options.include_episodes)
+      params.set("include_episodes", "true");
     return this.requestRaw("GET", `/memory/index?${params.toString()}`, undefined, {
       accept: "text/markdown"
     });
@@ -1641,6 +1655,8 @@ class HarmonyApiClient {
       params.set("type", options.type);
     if (options?.limit !== undefined)
       params.set("limit", String(options.limit));
+    if (options?.include_episodes)
+      params.set("include_episodes", "true");
     return this.requestRaw("GET", `/memory/search?${params.toString()}`, undefined, {
       accept: "text/markdown"
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gethmy/mcp",
-  "version": "2.15.0",
+  "version": "2.17.0",
   "description": "MCP server for Harmony Kanban board - enables AI coding agents to manage your boards",
   "publishConfig": {
     "access": "public"

package/src/api-client.ts

@@ -625,6 +625,25 @@ export class HarmonyApiClient {
     return this.request("PATCH", `/cards/${cardId}`, updates);
   }
 
+  /**
+   * 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.
+   */
+  async claimCard(
+    cardId: string,
+    agentId: string,
+  ): Promise<{ claimed: boolean }> {
+    const res = await this.request<{ card?: unknown; claimed?: boolean }>(
+      "PATCH",
+      `/cards/${cardId}`,
+      { assignedAgentId: agentId, ifAssignedAgentNull: true },
+    );
+    // Success body is `{ card }` (no `claimed` key) → won. Lost-race body is
+    // `{ claimed: false }`.
+    return { claimed: res.claimed !== false };
+  }
+
   async moveCard(
     cardId: string,
     columnId: string,
@@ -1166,6 +1185,9 @@ export class HarmonyApiClient {
     limit?: number;
     offset?: number;
     include_superseded?: boolean;
+    // Opt in to agent-run episodes (default excluded, #677). Only the daemon's
+    // own rolling-episode lookup should set this.
+    include_episodes?: boolean;
   }): Promise<{ entities: unknown[]; count: number }> {
     const params = new URLSearchParams();
     params.set("workspace_id", options.workspace_id);
@@ -1182,6 +1204,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.include_episodes) params.set("include_episodes", "true");
     return this.request("GET", `/memory/entities?${params.toString()}`);
   }
 
@@ -1230,6 +1253,9 @@ export class HarmonyApiClient {
     tags?: string[];
     minConfidence?: number;
     topK?: number;
+    // 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;
   }): 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).
@@ -1246,6 +1272,7 @@ export class HarmonyApiClient {
           project_id: options.projectId,
           type: options.type?.length === 1 ? options.type[0] : undefined,
           limit: fetchLimit,
+          include_episodes: options.includeEpisodes,
         },
       );
       entities = (search.entities ?? []) as Array<Record<string, unknown>>;
@@ -1258,6 +1285,7 @@ export class HarmonyApiClient {
         tags: options.tags,
         min_confidence: options.minConfidence,
         limit: fetchLimit,
+        include_episodes: options.includeEpisodes,
       });
       entities = (list.entities ?? []) as Array<Record<string, unknown>>;
     }
@@ -1341,6 +1369,7 @@ export class HarmonyApiClient {
       limit?: number;
       tags?: string[];
       include_superseded?: boolean;
+      include_episodes?: boolean;
     },
   ): Promise<{ entities: unknown[]; count: number }> {
     const params = new URLSearchParams();
@@ -1354,6 +1383,7 @@ 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?.include_episodes) params.set("include_episodes", "true");
     return this.request("GET", `/memory/search?${params.toString()}`);
   }
 
@@ -1364,12 +1394,14 @@ export class HarmonyApiClient {
     project_id?: string;
     type?: string;
     limit?: number;
+    include_episodes?: boolean;
   }): 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.include_episodes) params.set("include_episodes", "true");
     return this.request("GET", `/memory/index?${params.toString()}`);
   }
 
@@ -1378,12 +1410,14 @@ export class HarmonyApiClient {
     project_id?: string;
     type?: string;
     limit?: number;
+    include_episodes?: boolean;
   }): 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.include_episodes) params.set("include_episodes", "true");
     return this.requestRaw(
       "GET",
       `/memory/index?${params.toString()}`,
@@ -1470,6 +1504,7 @@ export class HarmonyApiClient {
       project_id?: string;
       type?: string;
       limit?: number;
+      include_episodes?: boolean;
     },
   ): Promise<string> {
     const params = new URLSearchParams();
@@ -1479,6 +1514,7 @@ export class HarmonyApiClient {
     if (options?.type) params.set("type", options.type);
     if (options?.limit !== undefined)
       params.set("limit", String(options.limit));
+    if (options?.include_episodes) params.set("include_episodes", "true");
     return this.requestRaw(
       "GET",
       `/memory/search?${params.toString()}`,

package/src/server.ts

@@ -1743,6 +1743,11 @@ export const TOOLS = {
           description:
             "Include rows whose `superseded_at` is set (default false). Use when investigating supersede chains.",
         },
+        include_episodes: {
+          type: "boolean",
+          description:
+            "Include agent-run episodes — the daemon's per-run implement/review captures (default false). Excluded by default so recall surfaces curated, durable memory. Set true to audit the agent's run history.",
+        },
       },
     },
   },
@@ -1934,6 +1939,11 @@ export const TOOLS = {
           description: "Project ID (optional)",
         },
         limit: { type: "number", description: "Max results (default: 20)" },
+        include_episodes: {
+          type: "boolean",
+          description:
+            "Include agent-run episodes — the daemon's per-run captures (default false). Excluded by default so search surfaces curated memory.",
+        },
       },
       required: ["query"],
     },
@@ -1978,6 +1988,11 @@ export const TOOLS = {
           type: "number",
           description: "Max entities to return (default: 200)",
         },
+        include_episodes: {
+          type: "boolean",
+          description:
+            "Include agent-run episodes — the daemon's per-run captures (default false). Excluded by default so the index shows curated vault content, not run noise.",
+        },
       },
       required: [],
     },
@@ -3824,17 +3839,16 @@ async function handleToolCall(
     }
 
     // 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;
+      const projectId =
+        (args.projectId as string) || deps.getActiveProjectId() || undefined;
 
       if (args.cardId) {
         cardId = z.string().uuid().parse(args.cardId);
       } else if (args.shortId !== undefined) {
         const shortId = z.number().int().positive().parse(args.shortId);
-        const projectId =
-          (args.projectId as string) || deps.getActiveProjectId();
         if (!projectId) {
           throw new Error(
             "Project ID required when using shortId. Use harmony_set_project_context or provide projectId.",
@@ -3846,29 +3860,58 @@ async function handleToolCall(
         throw new Error("Either cardId or shortId must be provided");
       }
 
-      // 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 = "";
+      const variant =
+        (args.variant as "analysis" | "draft" | "execute") || undefined;
+      const customConstraints =
+        typeof args.customConstraints === "string"
+          ? args.customConstraints
+          : undefined;
+
+      // Context toggles default ON — a card's reference fields (linked cards,
+      // external URLs, attachments) are hydrated inside generateCardPrompt so
+      // the prompt carries the links the agent needs to fetch related content.
+      const contextOptions = {
+        includeSubtasks: args.includeSubtasks !== false,
+        includeLinks: args.includeLinks !== false,
+        includeDescription: args.includeDescription !== false,
+      };
+
       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.
-      }
+        const result = await client.generateCardPrompt({
+          cardId,
+          workspaceId: deps.getActiveWorkspaceId() || "",
+          projectId,
+          variant,
+          customConstraints,
+          contextOptions,
+        });
+        return { success: true, ...result };
+      } catch (err) {
+        // Graceful fallback: if full context assembly fails (e.g. an offline
+        // sub-fetch), still return a usable title/description prompt so the
+        // Harmony command never dead-ends. The reference-link hydration is
+        // best-effort inside generateCardPrompt and won't reach here.
+        const msg = err instanceof Error ? err.message : String(err);
+        console.debug(`[harmony_generate_prompt] falling back: ${msg}`);
+
+        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.
+        }
 
-      const taskBlock = [cardTitle, cardDescription]
-        .filter(Boolean)
-        .join("\n\n");
-      const prompt = `Here is the task: ${taskBlock || "(no description available)"}`;
+        const taskBlock = [cardTitle, cardDescription]
+          .filter(Boolean)
+          .join("\n\n");
+        const prompt = `Here is the task: ${taskBlock || "(no description available)"}`;
 
-      return {
-        success: true,
-        prompt,
-        cardId,
-      };
+        return { success: true, prompt, cardId };
+      }
     }
 
     // Memory / Knowledge Graph operations
@@ -4080,6 +4123,8 @@ async function handleToolCall(
       const topK = args.top_k as number | undefined;
       const budgetTokens = args.budget_tokens as number | undefined;
       const includeSuperseded = Boolean(args.include_superseded);
+      // #677: agent-run episodes are excluded from recall by default; opt in.
+      const includeEpisodes = Boolean(args.include_episodes);
       const queryText = args.query as string | undefined;
 
       // Over-fetch when top_k is smaller than limit so the rescorer has
@@ -4138,6 +4183,7 @@ async function handleToolCall(
                 ? requestedTags
                 : undefined,
             include_superseded: includeSuperseded,
+            include_episodes: includeEpisodes,
           },
         );
         entities = (searchResult.entities ?? []) as any[];
@@ -4171,6 +4217,7 @@ async function handleToolCall(
           min_confidence: args.minConfidence as number | undefined,
           limit: fetchLimit,
           include_superseded: includeSuperseded,
+          include_episodes: includeEpisodes,
         });
         entities = listed as any[];
         if (excludeSessionFromLongTerm) {
@@ -4515,6 +4562,7 @@ async function handleToolCall(
             undefined,
           type: args.type as string | undefined,
           limit: args.limit as number | undefined,
+          include_episodes: Boolean(args.include_episodes),
         },
       );
 
@@ -4542,6 +4590,7 @@ async function handleToolCall(
           (args.projectId as string) || deps.getActiveProjectId() || undefined,
         type: args.type as string | undefined,
         limit: args.limit as number | undefined,
+        include_episodes: Boolean(args.include_episodes),
       });
       return markdown || "No entities found.";
     }