@gethmy/mcp 2.16.0 → 2.17.0

package/dist/cli.js

@@ -2032,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) {
@@ -2047,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 {
@@ -2058,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 ?? [];
     }
@@ -2119,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) {
@@ -2130,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) {
@@ -2141,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"
     });
@@ -2198,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"
     });
@@ -4833,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."
         }
       }
     }
@@ -5018,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"]
     }
@@ -5059,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: []
@@ -6486,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;
@@ -6502,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;
@@ -6525,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) {
@@ -6745,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) {
@@ -6762,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

@@ -2027,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) {
@@ -2042,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 {
@@ -2053,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 ?? [];
     }
@@ -2114,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) {
@@ -2125,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) {
@@ -2136,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"
     });
@@ -2193,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"
     });
@@ -4828,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."
         }
       }
     }
@@ -5013,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"]
     }
@@ -5054,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: []
@@ -6481,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;
@@ -6497,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;
@@ -6520,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) {
@@ -6740,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) {
@@ -6757,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

@@ -1479,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) {
@@ -1494,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 {
@@ -1505,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 ?? [];
     }
@@ -1566,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) {
@@ -1577,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) {
@@ -1588,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"
     });
@@ -1645,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.16.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

@@ -1185,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);
@@ -1201,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()}`);
   }
 
@@ -1249,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).
@@ -1265,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>>;
@@ -1277,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>>;
     }
@@ -1360,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();
@@ -1373,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()}`);
   }
 
@@ -1383,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()}`);
   }
 
@@ -1397,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()}`,
@@ -1489,6 +1504,7 @@ export class HarmonyApiClient {
       project_id?: string;
       type?: string;
       limit?: number;
+      include_episodes?: boolean;
     },
   ): Promise<string> {
     const params = new URLSearchParams();
@@ -1498,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: [],
     },
@@ -4108,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
@@ -4166,6 +4183,7 @@ async function handleToolCall(
                 ? requestedTags
                 : undefined,
             include_superseded: includeSuperseded,
+            include_episodes: includeEpisodes,
           },
         );
         entities = (searchResult.entities ?? []) as any[];
@@ -4199,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) {
@@ -4543,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),
         },
       );
 
@@ -4570,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.";
     }