@gethmy/mcp 2.1.2 → 2.2.0

package/src/server.ts

@@ -85,6 +85,155 @@ export interface ToolDeps {
   resetClient: () => void;
 }
 
+// --- Memory Session Tracking ---
+// Tracks memory operations per card session for visibility in AgentCardFooter
+
+interface MemorySessionState {
+  cardId: string;
+  agentIdentifier: string;
+  agentName: string;
+  memoryReadCount: number;
+  pendingActions: { action: string; ts: string }[];
+  allActions: { action: string; ts: string }[];
+  dirty: boolean;
+}
+
+const memorySessions = new Map<string, MemorySessionState>();
+
+function initMemorySession(
+  cardId: string,
+  agentIdentifier: string,
+  agentName: string,
+): void {
+  memorySessions.set(cardId, {
+    cardId,
+    agentIdentifier,
+    agentName,
+    memoryReadCount: 0,
+    pendingActions: [],
+    allActions: [],
+    dirty: false,
+  });
+}
+
+function getMemorySession(cardId: string): MemorySessionState | undefined {
+  return memorySessions.get(cardId);
+}
+
+function appendMemoryAction(cardId: string, action: string): void {
+  const session = memorySessions.get(cardId);
+  if (!session) return;
+  const truncated = action.length > 512 ? action.slice(0, 509) + "..." : action;
+  const entry = { action: truncated, ts: new Date().toISOString() };
+  session.pendingActions.push(entry);
+  session.dirty = true;
+}
+
+function incrementMemoryReads(cardId: string): void {
+  const session = memorySessions.get(cardId);
+  if (!session) return;
+  session.memoryReadCount++;
+  session.dirty = true;
+}
+
+/**
+ * Flush pending memory actions to the backend via updateAgentProgress.
+ * Fire-and-forget: errors are logged but never thrown.
+ */
+async function flushMemoryActions(
+  client: HarmonyApiClient,
+  cardId: string,
+): Promise<void> {
+  const session = memorySessions.get(cardId);
+  if (!session || !session.dirty) return;
+
+  try {
+    // Batch reads into a single summary line
+    if (session.memoryReadCount > 0) {
+      session.allActions.push({
+        action: `Recalled ${session.memoryReadCount} memor${session.memoryReadCount === 1 ? "y" : "ies"}`,
+        ts: new Date().toISOString(),
+      });
+      session.memoryReadCount = 0;
+    }
+
+    // Move pending writes to allActions
+    if (session.pendingActions.length > 0) {
+      session.allActions.push(...session.pendingActions);
+      session.pendingActions = [];
+    }
+
+    // Trim to max 10 (drop oldest)
+    if (session.allActions.length > 10) {
+      session.allActions = session.allActions.slice(-10);
+    }
+
+    await client.updateAgentProgress(cardId, {
+      agentIdentifier: session.agentIdentifier,
+      agentName: session.agentName,
+      recentActions: session.allActions,
+    });
+
+    session.dirty = false;
+  } catch (err) {
+    // Fire-and-forget: log but don't propagate
+    console.error("[memory-session] flush failed:", err);
+  }
+}
+
+/**
+ * Merge memory actions into an existing recentActions array from a progress update.
+ * Returns the merged array (caller's actions first, then memory actions appended).
+ */
+function mergeMemoryActionsInto(
+  cardId: string,
+  callerActions: { action: string; ts: string }[],
+): { action: string; ts: string }[] {
+  const session = memorySessions.get(cardId);
+  if (!session) return callerActions;
+
+  // Flush reads into allActions
+  if (session.memoryReadCount > 0) {
+    session.allActions.push({
+      action: `Recalled ${session.memoryReadCount} memor${session.memoryReadCount === 1 ? "y" : "ies"}`,
+      ts: new Date().toISOString(),
+    });
+    session.memoryReadCount = 0;
+  }
+
+  // Move pending to allActions
+  if (session.pendingActions.length > 0) {
+    session.allActions.push(...session.pendingActions);
+    session.pendingActions = [];
+  }
+
+  // Merge: caller actions + memory actions, trim to 10
+  const merged = [...callerActions, ...session.allActions];
+  const trimmed = merged.length > 10 ? merged.slice(-10) : merged;
+
+  // Update allActions to the merged state
+  session.allActions = trimmed;
+  session.dirty = false;
+
+  return trimmed;
+}
+
+/**
+ * Get the first (and typically only) active memory session.
+ * Memory tools don't carry a cardId, so we find the active session.
+ */
+function getActiveMemorySession(): MemorySessionState | undefined {
+  // Return the first active session (there should be at most one)
+  for (const session of memorySessions.values()) {
+    return session;
+  }
+  return undefined;
+}
+
+function cleanupMemorySession(cardId: string): void {
+  memorySessions.delete(cardId);
+}
+
 // Tool definitions
 const TOOLS = {
   // Card operations
@@ -1838,7 +1987,7 @@ async function handleToolCall(
   if (!unauthenticatedTools.includes(name) && !deps.isConfigured()) {
     throw new Error(
       'Not configured. Run "npx @gethmy/mcp setup" to set your API key.\n' +
-        "You can generate an API key at https://gethmy.com → Settings → API Keys.\n" +
+        "You can generate an API key at https://app.gethmy.com → Settings → API Keys.\n" +
         'Or use "harmony_onboard" to create an account and configure automatically.',
     );
   }
@@ -2267,7 +2416,10 @@ async function handleToolCall(
       });
 
       // Mark as explicit so auto-session won't interfere
-      markExplicit(cardId);
+      markExplicit(cardId, { agentIdentifier, agentName });
+
+      // Initialize memory session tracking for action visibility
+      initMemorySession(cardId, agentIdentifier, agentName);
 
       // Prefetch relevant context (non-blocking, best-effort)
       let prefetchedMemoryIds: string[] = [];
@@ -2348,6 +2500,21 @@ async function handleToolCall(
         args.progressPercent !== undefined
           ? z.number().min(0).max(100).parse(args.progressPercent)
           : undefined;
+      // Merge any pending memory actions into the progress update
+      const callerRecentActions = args.recentActions as
+        | { action: string; ts: string }[]
+        | undefined;
+      const memSession = getMemorySession(cardId);
+      let mergedRecentActions: { action: string; ts: string }[] | undefined;
+      if (memSession?.dirty) {
+        mergedRecentActions = mergeMemoryActionsInto(
+          cardId,
+          callerRecentActions || [],
+        );
+      } else if (callerRecentActions) {
+        mergedRecentActions = callerRecentActions;
+      }
+
       const result = await client.updateAgentProgress(cardId, {
         agentIdentifier,
         agentName,
@@ -2363,6 +2530,7 @@ async function handleToolCall(
         estimatedMinutesRemaining: args.estimatedMinutesRemaining as
           | number
           | undefined,
+        ...(mergedRecentActions && { recentActions: mergedRecentActions }),
       });
 
       // Mid-session learning extraction (fire-and-forget)
@@ -2405,6 +2573,10 @@ async function handleToolCall(
           ? z.number().min(0).max(100).parse(args.progressPercent)
           : undefined;
 
+      // Final flush of any pending memory actions before ending the session
+      await flushMemoryActions(client, cardId);
+      cleanupMemorySession(cardId);
+
       const result = await client.endAgentSession(cardId, {
         status: sessionStatus,
         progressPercent: endProgressPercent,
@@ -2689,6 +2861,8 @@ async function handleToolCall(
       }
       const entityType = (args.type as string) || "context";
       const entityTags = (args.tags as string[]) || [];
+      // Use session's agent identifier if available, otherwise null
+      const activeMemSession = getActiveMemorySession();
       const result = await client.createMemoryEntity({
         workspace_id: workspaceId,
         project_id:
@@ -2704,7 +2878,7 @@ async function handleToolCall(
             ? z.number().min(0).max(1).parse(args.confidence)
             : undefined,
         tags: entityTags.length > 0 ? entityTags : undefined,
-        agent_identifier: "claude-code",
+        agent_identifier: activeMemSession?.agentIdentifier || undefined,
       });
 
       // Fire-and-forget graph expansion: link new entity to semantically similar ones
@@ -2748,6 +2922,12 @@ async function handleToolCall(
         }
       }
 
+      // Track memory write action and flush (fire-and-forget)
+      if (activeMemSession) {
+        appendMemoryAction(activeMemSession.cardId, `Stored memory: ${title}`);
+        flushMemoryActions(client, activeMemSession.cardId).catch(() => {});
+      }
+
       return {
         success: true,
         ...result,
@@ -2830,6 +3010,12 @@ async function handleToolCall(
         ).catch(() => {});
       }
 
+      // Track memory read (batched on flush)
+      const recallMemSession = getActiveMemorySession();
+      if (recallMemSession) {
+        incrementMemoryReads(recallMemSession.cardId);
+      }
+
       return markdown || "No memories found.";
     }
 
@@ -2847,12 +3033,48 @@ async function handleToolCall(
         updates.confidence = z.number().min(0).max(1).parse(args.confidence);
       if (args.metadata !== undefined) updates.metadata = args.metadata;
       const result = await client.updateMemoryEntity(entityId, updates);
+
+      // Track memory write action and flush (fire-and-forget)
+      const updateMemSession = getActiveMemorySession();
+      if (updateMemSession) {
+        const updateTitle =
+          (updates.title as string) || entityId.slice(0, 8);
+        appendMemoryAction(
+          updateMemSession.cardId,
+          `Updated memory: ${updateTitle}`,
+        );
+        flushMemoryActions(client, updateMemSession.cardId).catch(() => {});
+      }
+
       return { success: true, ...result };
     }
 
     case "harmony_forget": {
       const entityId = z.string().uuid().parse(args.entityId);
+
+      // Fetch title before deletion for action tracking
+      let forgetTitle: string | null = null;
+      const forgetMemSession = getActiveMemorySession();
+      if (forgetMemSession) {
+        try {
+          const { entity } = await client.getMemoryEntity(entityId);
+          forgetTitle = (entity as { title?: string })?.title || null;
+        } catch {
+          // Non-fatal: use truncated ID if fetch fails
+        }
+      }
+
       await client.deleteMemoryEntity(entityId);
+
+      // Track memory write action and flush (fire-and-forget)
+      if (forgetMemSession) {
+        appendMemoryAction(
+          forgetMemSession.cardId,
+          `Removed memory: ${forgetTitle || entityId.slice(0, 8)}`,
+        );
+        flushMemoryActions(client, forgetMemSession.cardId).catch(() => {});
+      }
+
       return { success: true };
     }
 
@@ -2880,6 +3102,17 @@ async function handleToolCall(
             ? z.number().min(0).max(1).parse(args.confidence)
             : undefined,
       });
+
+      // Track memory write action and flush (fire-and-forget)
+      const relateMemSession = getActiveMemorySession();
+      if (relateMemSession) {
+        appendMemoryAction(
+          relateMemSession.cardId,
+          `Linked memories: ${relationType}`,
+        );
+        flushMemoryActions(client, relateMemSession.cardId).catch(() => {});
+      }
+
       return { success: true, ...result };
     }
 
@@ -2904,6 +3137,13 @@ async function handleToolCall(
           limit: args.limit as number | undefined,
         },
       );
+
+      // Track memory read (batched on flush)
+      const searchMemSession = getActiveMemorySession();
+      if (searchMemSession) {
+        incrementMemoryReads(searchMemSession.cardId);
+      }
+
       return markdown || "No memories found.";
     }
 
@@ -3039,7 +3279,7 @@ async function handleToolCall(
       });
 
       // Build URL for viewing the plan
-      const planUrl = `https://gethmy.com/plans/${(result.plan as { id: string }).id}`;
+      const planUrl = `https://app.gethmy.com/plans/${(result.plan as { id: string }).id}`;
 
       return {
         success: true,

package/src/skills.ts

@@ -251,7 +251,7 @@ Once you have the plan ID, call \`harmony_get_plan\` to fetch the full plan with
 ## [Plan Title]
 **Status:** draft/active/archived | **Phase:** plan/execute/verify/done
 **Tasks:** N total (X pending, Y in_progress, Z completed)
-**URL:** https://gethmy.com/plans/{id}
+**URL:** https://app.gethmy.com/plans/{id}
 \\\`\\\`\\\`
 
 If plan is in execute phase and tasks already have linked cards, note which tasks have cards and which don't.
@@ -285,7 +285,7 @@ Only offer **(A) Single card**, **(C) Analyze only**, or **(D) Skip**.
 #### Option A — Single card
 1. Call \`harmony_create_card\` with:
    - \`title\`: Plan title
-   - \`description\`: Brief 2-3 sentence summary of the plan + \`\\n\\n[View plan](https://gethmy.com/plans/{planId})\`
+   - \`description\`: Brief 2-3 sentence summary of the plan + \`\\n\\n[View plan](https://app.gethmy.com/plans/{planId})\`
    - \`priority\`: based on plan task priorities (use highest)
 2. Call \`harmony_update_plan\` to set \`status: "active"\`, \`workflowPhase: "execute"\`
 
@@ -407,7 +407,7 @@ Call \`harmony_create_plan\` with:
 ### 2B.5 — User Approval
 
 Show the user:
-- Plan URL: \`https://gethmy.com/plans/{id}\`
+- Plan URL: \`https://app.gethmy.com/plans/{id}\`
 - Number of tasks created
 - Brief summary
 

package/src/tui/setup.ts

@@ -41,7 +41,7 @@ export interface SetupOptions {
 const GLOBAL_SKILLS_DIR = join(homedir(), ".agents", "skills");
 
 // API base URL
-const API_URL = "https://gethmy.com/api";
+const API_URL = "https://app.gethmy.com/api";
 
 /**
  * Register MCP server using Claude CLI
@@ -536,7 +536,7 @@ export async function runSetup(options: SetupOptions = {}): Promise<void> {
   if (!validation.valid) {
     spinner.stop(colors.error("API key validation failed"));
     p.log.error(validation.error || "Could not connect to Harmony API");
-    p.log.info("Get an API key at: https://gethmy.com/user/keys");
+    p.log.info("Get an API key at: https://app.gethmy.com/user/keys");
     process.exit(1);
   }
 
@@ -797,7 +797,9 @@ export async function runSetup(options: SetupOptions = {}): Promise<void> {
   }
 
   if (allFiles.length > 0) {
-    const summary = getWriteSummary(allFiles, { force: options.force });
+    const summary = getWriteSummary(allFiles, {
+      force: options.force || needsSkills,
+    });
 
     if (summary.toCreate.length > 0) {
       console.log("");
@@ -850,8 +852,12 @@ export async function runSetup(options: SetupOptions = {}): Promise<void> {
   console.log("");
 
   // Step 7: Write files
+  // Force-write when user chose to reinstall skills — skill files are
+  // package-generated content that should always match the installed version.
   if (allFiles.length > 0) {
-    await writeFilesWithProgress(allFiles, { force: options.force });
+    await writeFilesWithProgress(allFiles, {
+      force: options.force || needsSkills,
+    });
   }
 
   // Step 8: Create symlinks
@@ -968,7 +974,7 @@ export async function runSetup(options: SetupOptions = {}): Promise<void> {
   console.log("");
   console.log(`  ${colors.dim("Add to new project: npx @gethmy/mcp setup")}`);
   console.log(
-    `  ${colors.dim("Need help? Visit https://gethmy.com/docs/mcp")}`,
+    `  ${colors.dim("Need help? Visit https://app.gethmy.com/docs/mcp")}`,
   );
   console.log("");
 }