@yugabytedb/meko-mcp 1.0.6 → 1.1.0

package/assets/hooks-handlers/lib/capture.js

@@ -12,7 +12,9 @@
  *
  * Environment:
  *   MEKO_MCP_URL       MCP server URL (default: http://localhost:8000/mcp)
- *   MEKO_AGENT_ID      Agent identifier (default: claude_code)
+ *   MEKO_AGENT_ID      Agent identifier override; if unset, derived from the
+ *                      session's cwd as `claude_code:<repo-basename>` (or
+ *                      `meko_agent` if cwd is unknown). See deriveAgentId().
  *   MEKO_API_KEY        API key for Cloud Meko auth (optional, omit for local)
  *   MEKO_API_TIMEOUT   Request timeout in seconds (default: 10)
  *   MEKO_WATERMARK_DIR Watermark directory (default: ~/.claude/meko-capture)
@@ -26,7 +28,58 @@ const https = require("https");
 // --- Config ---
 
 const MEKO_MCP_URL = process.env.MEKO_MCP_URL || "http://localhost:8000/mcp";
-const MEKO_AGENT_ID = process.env.MEKO_AGENT_ID || "claude_code";
+
+// Server-side fallback for empty agent_id; the cross-project common bucket.
+// Mirror of COMMON_BUCKET_AGENT_ID in installer/lib/migrate/id.mjs.
+const COMMON_BUCKET_AGENT_ID = "meko_agent";
+const AGENT_ID_MAX_LEN = 64;
+
+/**
+ * Derive an `agent_id` for a Meko write. Mirror of `deriveAgentId` in
+ * installer/lib/migrate/id.mjs — kept inline because capture.js is published
+ * in a separate package with no module dependencies on the installer.
+ *
+ *   - `envOverride` (typically MEKO_AGENT_ID) wins if non-empty.
+ *   - Coding clients (claude_code, cursor) → `<client>:<repo-basename>`,
+ *     with the basename lowercased and non-`[a-z0-9-]` runs collapsed to `-`.
+ *     Outside a repo → bare client name (keeps coding-agent traffic out of
+ *     the common bucket).
+ *   - Loose clients (claude-desktop) → `claude_desktop`.
+ *   - Anything else → `meko_agent` (common cross-project bucket).
+ */
+function deriveAgentId(opts) {
+  const override = (opts && opts.envOverride ? String(opts.envOverride) : "").trim();
+  if (override) return override;
+  const client = (opts && opts.client ? String(opts.client) : "").trim();
+  if (client === "claude-desktop" || client === "claude_desktop") return "claude_desktop";
+  if (client !== "claude_code" && client !== "cursor") return COMMON_BUCKET_AGENT_ID;
+  const rawBase = opts && opts.cwd ? path.basename(opts.cwd) : "";
+  if (!rawBase || rawBase === "." || rawBase === "/") return client;
+  const project = rawBase.toLowerCase()
+    .replace(/[^a-z0-9-]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, AGENT_ID_MAX_LEN);
+  if (!project) return client;
+  return `${client}:${project}`;
+}
+
+/**
+ * Resolve the agent_id for the current session. Frozen at SessionStart;
+ * subsequent hook invocations re-derive from the watermark + env, not
+ * from a stale module-level cache.
+ *
+ * Resolution order:
+ *   1. MEKO_AGENT_ID env override (verbatim).
+ *   2. cwd from the transcript header (peekTranscriptMetadata).
+ *   3. process.cwd() — last resort if no transcript metadata yet.
+ */
+function resolveSessionAgentId(transcriptPath) {
+  const envOverride = process.env.MEKO_AGENT_ID;
+  if (envOverride && envOverride.trim()) return envOverride.trim();
+  const meta = transcriptPath ? peekTranscriptMetadata(transcriptPath) : null;
+  const cwd = (meta && meta.cwd) || process.cwd();
+  return deriveAgentId({ client: "claude_code", cwd, envOverride });
+}
 const MEKO_API_KEY = process.env.MEKO_API_KEY || "";
 const MEKO_API_TIMEOUT = parseInt(process.env.MEKO_API_TIMEOUT || "10", 10) * 1000;
 const WATERMARK_DIR =
@@ -257,6 +310,20 @@ function writeWatermark(wmPath, convId, lineNum, agentId) {
   );
 }
 
+// note: Subagents cannot auto-discover the parent's watermark today.
+// The watermark dir is flat and keyed by session UUID, and a subagent
+// process has no way to learn its parent's session UUID:
+//   - no CLAUDE_SESSION_ID / CLAUDE_PARENT_SESSION_ID env var
+//   - ~/.claude/session-env/<uuid>/ directories exist but are empty
+//   - cwd is shared with the parent but isn't a unique session key
+//     (parent may have multiple concurrent sessions in one project;
+//     findMostRecentProjectWatermark() keys off transcript_path,
+//     which Agent / Task spawn prompts do not expose)
+// Verified on Claude Code 2.1.126 via issue #49 spike (2026-05-01).
+// Enforcement is shifted to the skill: parents prepend an inherited-
+// context block to every Task / Agent spawn prompt. See
+// skills/skills/meko-mcp-tools/SKILL.md "When spawning subagents".
+
 // --- MCP JSON-RPC client (Streamable HTTP with session init) ---
 
 /**
@@ -274,7 +341,7 @@ function mcpPost(jsonBody) {
       "Content-Length": Buffer.byteLength(body),
     };
     if (MEKO_API_KEY) {
-      headers["API_KEY"] = MEKO_API_KEY;
+      headers["Authorization"] = `Bearer ${MEKO_API_KEY}`;
     }
     if (mcpSessionId) {
       headers["Mcp-Session-Id"] = mcpSessionId;
@@ -398,43 +465,43 @@ function extractToolResult(response) {
 }
 
 /**
- * Discover the user's agent_id namespace from existing Mem0 collections.
- *
- * Mirrors the protocol in skills/skills/meko-mcp-tools/SKILL.md lines 41-49:
- * call `db_summarize_database`, scan for `<agent>_mem0_collection` tables,
- * pick the one with the highest `row_count`. Falls back to "agent" when the
- * user has no prior memories. Never returns null — always returns a usable
- * string.
+ * Peek the first JSONL line of a transcript to harvest `cwd`, `gitBranch`,
+ * and `timestamp`. These are attached as `metadata` on the hook's
+ * `conversation_create` so hook-captured traces match the metadata shape
+ * the migrator emits (see installer/lib/migrate/orchestrator.mjs).
  *
- * Cached in the watermark file so subsequent SessionStart hooks skip the
- * `db_summarize_database` round-trip.
+ * Reads a bounded 4KB prefix, not the whole file — on PreCompact / SessionEnd
+ * the transcript can be several MB, and we only need the first line's JSON
+ * header. If the header happens to exceed 4KB (pathological; a Claude Code
+ * header is usually <1KB), JSON.parse will reject the truncated prefix and
+ * we fall back to empty metadata via the catch. Same graceful degradation
+ * as any other read/parse failure — metadata is best-effort enrichment.
  */
-async function discoverAgentId() {
-  const response = await mcpCall("db_summarize_database", {
-    scope: "read",
-    conversation_id: "00000000-0000-0000-0000-000000000000",
-  });
-  const result = extractToolResult(response);
-  if (!result) return "agent";
-
-  // The tool may return tables in several shapes depending on server version.
-  // Defensive: look for any array of { name, row_count } under common keys.
-  const tables = []
-    .concat(result.tables || [])
-    .concat(result.schemas?.flatMap?.((s) => s.tables || []) || []);
-  if (!Array.isArray(tables) || tables.length === 0) return "agent";
-
-  let best = { agent: "", rows: -1 };
-  for (const t of tables) {
-    const name = t.name || t.table_name || "";
-    const rows = Number(t.row_count ?? t.rows ?? 0);
-    const m = /^(.+)_mem0_collection$/.exec(name);
-    if (!m) continue;
-    if (rows > best.rows) {
-      best = { agent: m[1], rows };
+function peekTranscriptMetadata(transcriptPath) {
+  const empty = { cwd: null, gitBranch: null, startedAt: null };
+  if (!transcriptPath) return empty;
+  let fd;
+  try {
+    fd = fs.openSync(transcriptPath, "r");
+    const buffer = Buffer.alloc(4096);
+    const bytesRead = fs.readSync(fd, buffer, 0, 4096, 0);
+    if (bytesRead === 0) return empty;
+    const content = buffer.toString("utf-8", 0, bytesRead);
+    const firstNewline = content.indexOf("\n");
+    const firstLine = firstNewline === -1 ? content : content.slice(0, firstNewline);
+    const obj = JSON.parse(firstLine);
+    return {
+      cwd: typeof obj.cwd === "string" ? obj.cwd : null,
+      gitBranch: typeof obj.gitBranch === "string" ? obj.gitBranch : null,
+      startedAt: typeof obj.timestamp === "string" ? obj.timestamp : null,
+    };
+  } catch {
+    return empty;
+  } finally {
+    if (fd !== undefined) {
+      try { fs.closeSync(fd); } catch { /* FD already gone; nothing to do */ }
     }
   }
-  return best.rows > 0 ? best.agent : "agent";
 }
 
 /**
@@ -469,23 +536,32 @@ async function fetchRecentMemories(agentId, { limit = 10, budget = 2000 } = {})
   return summaries;
 }
 
-async function createConversation(sessionId) {
-  const response = await mcpCall("conversation_create", {
+async function createConversation(sessionId, agentId, metadata = null) {
+  const payload = {
     scope: "write",
-    agent_id: MEKO_AGENT_ID,
+    agent_id: agentId,
     title: "Claude Code session (auto-captured)",
     session_id: sessionId,
-  });
+  };
+  if (metadata) {
+    payload.metadata = JSON.stringify({
+      source: "hook",
+      cwd: metadata.cwd ?? null,
+      gitBranch: metadata.gitBranch ?? null,
+      startedAt: metadata.startedAt ?? null,
+    });
+  }
+  const response = await mcpCall("conversation_create", payload);
   const result = extractToolResult(response);
   return result && result.id ? result.id : null;
 }
 
-async function addMessage(convId, exchange) {
+async function addMessage(convId, agentId, exchange) {
   const seed = `${convId}:${exchange.user_uuid}`;
   await mcpCall("conversation_add_message", {
     scope: "write",
     conversation_id: convId,
-    agent_id: MEKO_AGENT_ID,
+    agent_id: agentId,
     input: exchange.input,
     output: exchange.output,
     reasoning: exchange.reasoning,
@@ -546,7 +622,7 @@ function findMostRecentProjectWatermark(transcriptPath, currentSessionId) {
 }
 
 function buildSessionStartContext(convId, sessionId, agentId, memories, opts) {
-  const resolvedAgentId = agentId || "claude_code";
+  const resolvedAgentId = agentId || COMMON_BUCKET_AGENT_ID;
   const resumed = Boolean(opts && opts.resumed);
   const opening = resumed
     ? `Resuming Meko conversation **${convId}** from a prior Claude Code session. The watermark file is written — PreCompact and SessionEnd hooks will append this session's new exchanges to the same conversation.`
@@ -568,7 +644,7 @@ ${opening}
 
 ### What you MUST do with Meko tools
 
-- **agent_id**: use "${resolvedAgentId}" (discovered from the user's existing namespace — DO NOT substitute "claude_code" just because you're running in Claude Code; see the meko-mcp-tools skill for why).
+- **agent_id**: use "${resolvedAgentId}" verbatim for every Meko MCP tool call in this session. This was derived from the cwd as \`<client>:<repo-basename>\` so memories stay scoped to this project. For genuinely cross-project facts (user identity, global preferences) pass agent_id="${COMMON_BUCKET_AGENT_ID}" — that's the common bucket any agent can read regardless of project.
 - **conversation_id**: Use "${convId}" for all MCP tool calls that accept it
 - **scope**: Only "read", "write", or "admin"
 
@@ -588,7 +664,8 @@ Before any action that deletes, overwrites, or restructures user content (Write-
 When Meko MCP tools are available, ALWAYS use them instead of local file-based memory (e.g., writing to ~/.claude/projects/.../memory/). If a Meko tool call fails, fall back to local storage and tell the user.${memoryBlock}`;
 }
 
-function buildSessionStartFallbackContext() {
+function buildSessionStartFallbackContext(agentId) {
+  const resolvedAgentId = agentId || COMMON_BUCKET_AGENT_ID;
   return `## Meko Memory Instructions
 
 The SessionStart hook could not reach the Meko MCP server to create a conversation. Automatic capture may not work for this session.
@@ -596,7 +673,7 @@ The SessionStart hook could not reach the Meko MCP server to create a conversati
 ### What you should still do
 
 - **Use Meko MCP tools** for memory_add, memory_search, etc. when available
-- **agent_id**: ALWAYS use "claude_code" (underscore, NEVER hyphens)
+- **agent_id**: use "${resolvedAgentId}" for project-scoped writes; use "${COMMON_BUCKET_AGENT_ID}" for cross-project common facts
 - **conversation_id**: Use nil UUID "00000000-0000-0000-0000-000000000000" as placeholder
 - **scope**: Only "read", "write", or "admin"
 
@@ -660,6 +737,7 @@ async function handleSessionStart(hookInput) {
     : null;
 
   const source = hookInput.source || "";
+  const derivedAgentId = resolveSessionAgentId(transcriptPath);
 
   // Check if watermark already exists (same session ID re-fires SessionStart, e.g. /clear, /compact)
   if (sessionId) {
@@ -667,15 +745,20 @@ async function handleSessionStart(hookInput) {
     const existing = readWatermark(wmPath);
     if (existing.conversation_id) {
       process.stderr.write(`[meko-capture] Session ${sessionId}: reusing existing conversation ${existing.conversation_id}\n`);
-      // Reuse cached agent_id + skip preload on resume (we don't know what's
-      // already in context). The skill still has the discovery protocol as a
-      // safety net.
+      // Prefer the watermark's cached agent_id so a user-set bucket survives
+      // re-fires of SessionStart (e.g. /clear, /compact). The exception is
+      // the legacy literal "agent" left by pre-contract installers — we
+      // override that with the freshly derived `claude_code:<repo>` so
+      // upgraded users stop writing into the ghost namespace.
+      const cached = (existing.agent_id || "").trim();
+      const resumedAgentId = cached && cached !== "agent" ? cached : derivedAgentId;
+      // Skip preload on resume (we don't know what's already in context).
       process.stdout.write(
         hookOutput(
           buildSessionStartContext(
             existing.conversation_id,
             sessionId,
-            existing.agent_id || "",
+            resumedAgentId,
             null,
           ),
         ),
@@ -683,6 +766,7 @@ async function handleSessionStart(hookInput) {
       return;
     }
   }
+  const agentId = derivedAgentId;
 
   // Resume: Claude Code created a new session ID for a resumed thread. Find the most recent
   // prior watermark for this project and reuse its conversation_id so continuity is preserved.
@@ -693,14 +777,23 @@ async function handleSessionStart(hookInput) {
     if (prior && prior.conversation_id) {
       const currentLineCount = fs.existsSync(transcriptPath) ? countLines(transcriptPath) : 0;
       const wmPath = path.join(WATERMARK_DIR, `${sessionId}.watermark.json`);
-      writeWatermark(wmPath, prior.conversation_id, currentLineCount);
+      // Preserve a non-legacy cached agent_id from the prior watermark so a
+      // user-set bucket (e.g. MEKO_AGENT_ID=foo, or a project-scoped
+      // claude_code:<other-repo> from the original session) survives the
+      // resume. Mirrors the same-session reuse branch above. The legacy
+      // literal "agent" is overridden with the freshly derived per-project
+      // bucket so upgraded users stop writing into the ghost namespace.
+      const priorAgentId = (prior.agent_id || "").trim();
+      const resumedAgentId =
+        priorAgentId && priorAgentId !== "agent" ? priorAgentId : agentId;
+      writeWatermark(wmPath, prior.conversation_id, currentLineCount, resumedAgentId);
       process.stderr.write(`[meko-capture] Session ${sessionId}: resuming conversation ${prior.conversation_id} from ${prior.sessionId}, skipping ${currentLineCount} copied lines\n`);
       process.stdout.write(
         hookOutput(
           buildSessionStartContext(
             prior.conversation_id,
             sessionId,
-            prior.agent_id || "",
+            resumedAgentId,
             null,
             { resumed: true },
           ),
@@ -711,55 +804,50 @@ async function handleSessionStart(hookInput) {
     process.stderr.write(`[meko-capture] Session ${sessionId}: source=resume but no prior project watermark found; creating new conversation\n`);
   }
 
-  // Create conversation via MCP
+  // Create conversation via MCP. Attach session metadata (cwd / gitBranch /
+  // startedAt) from the transcript header so hook traces match the migrator.
+  const transcriptMetadata = peekTranscriptMetadata(transcriptPath);
   let convId = null;
   try {
     await mcpInitialize();
-    convId = await createConversation(sessionId || "unknown");
+    convId = await createConversation(sessionId || "unknown", agentId, transcriptMetadata);
   } catch (err) {
     process.stderr.write(`[meko-capture] SessionStart: MCP unavailable (${err.message}). Falling back to agent-driven setup.\n`);
-    process.stdout.write(hookOutput(buildSessionStartFallbackContext()));
+    process.stdout.write(hookOutput(buildSessionStartFallbackContext(agentId)));
     return;
   }
 
   if (!convId) {
     process.stderr.write("[meko-capture] SessionStart: conversation_create returned no ID.\n");
-    process.stdout.write(hookOutput(buildSessionStartFallbackContext()));
+    process.stdout.write(hookOutput(buildSessionStartFallbackContext(agentId)));
     return;
   }
 
-  // Discover agent_id + preload memories with a combined 4s budget (SessionStart
-  // timeout is 15s). Both are enrichment — on timeout/failure we still deliver
-  // the core SessionStart context with the MEKO_AGENT_ID default.
+  // Preload recent memories with a 4s budget (SessionStart timeout is 15s).
+  // Best-effort enrichment — on timeout/failure we still deliver the core
+  // context. agent_id is derived per-session from the cwd; the old
+  // db_summarize_database discovery helper was removed (it depended on a
+  // paid-tier tool and only worked "correctly" via its fallback branch
+  // anyway — see scratch/2026-04-30-multi-tenant-mem0-audit.md Probe 6).
   const PRELOAD_BUDGET_MS = 4000;
-  const preloadResult = await withTimeout(
-    (async () => {
-      const agentId = await discoverAgentId();
-      const memories = await fetchRecentMemories(agentId);
-      return { agentId, memories };
-    })(),
+  const memories = await withTimeout(
+    fetchRecentMemories(agentId),
     PRELOAD_BUDGET_MS,
-    { agentId: MEKO_AGENT_ID, memories: [] },
+    [],
     { onTimeout: abortInflightRequests },
   );
 
-  // Write watermark (now cachinG agent_id too)
   if (sessionId) {
     const wmPath = path.join(WATERMARK_DIR, `${sessionId}.watermark.json`);
-    writeWatermark(wmPath, convId, 0, preloadResult.agentId);
+    writeWatermark(wmPath, convId, 0, agentId);
     process.stderr.write(
-      `[meko-capture] SessionStart: created conversation ${convId}, agent_id=${preloadResult.agentId}, preloaded ${preloadResult.memories.length} memories, watermark at ${wmPath}\n`,
+      `[meko-capture] SessionStart: created conversation ${convId}, agent_id=${agentId}, preloaded ${memories.length} memories, watermark at ${wmPath}\n`,
     );
   }
 
   process.stdout.write(
     hookOutput(
-      buildSessionStartContext(
-        convId,
-        sessionId,
-        preloadResult.agentId,
-        preloadResult.memories,
-      ),
+      buildSessionStartContext(convId, sessionId, agentId, memories),
     ),
   );
 }
@@ -807,6 +895,15 @@ async function main() {
   const lastLine = watermark.last_line_number || 0;
   const currentLines = countLines(transcriptPath);
 
+  // Resolve agent_id for this hook invocation. Prefer the value the
+  // SessionStart hook persisted in the watermark; if it's missing or a
+  // legacy literal ("agent"), fall back to a fresh derivation from the
+  // transcript's cwd so writes land in the right bucket.
+  const cachedAgentId = (watermark.agent_id || "").trim();
+  const agentId = cachedAgentId && cachedAgentId !== "agent"
+    ? cachedAgentId
+    : resolveSessionAgentId(transcriptPath);
+
   // Nothing new
   if (currentLines <= lastLine) {
     process.stdout.write(hookOutput(""));
@@ -839,15 +936,17 @@ async function main() {
 
   for (const exchange of exchanges) {
     try {
-      await addMessage(convId, exchange);
+      await addMessage(convId, agentId, exchange);
       captured++;
     } catch (err) {
       process.stderr.write(`[meko-capture] Failed to add message (uuid=${exchange.user_uuid}): ${err.message}\n`);
     }
   }
 
-  // Update watermark
-  writeWatermark(wmPath, convId, currentLines);
+  // Update watermark with the resolved agent_id. If the cached value was a
+  // legacy literal we now overwrite it so subsequent hooks see the derived
+  // bucket directly.
+  writeWatermark(wmPath, convId, currentLines, agentId);
 
   // Output
   const context =

package/assets/hooks-handlers/lib/package.json

@@ -0,0 +1 @@
+{ "type": "commonjs" }

package/assets/hooks-handlers/test_single_conversation.sh

@@ -17,7 +17,7 @@ set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 CAPTURE_JS="$SCRIPT_DIR/lib/capture.js"
 MCP_URL="${1:-${MEKO_MCP_URL:-http://localhost:8000/mcp}}"
-AGENT_ID="${MEKO_AGENT_ID:-claude_code}"
+AGENT_ID="${MEKO_AGENT_ID:-agent}"
 
 # Temp dirs for isolation
 WATERMARK_DIR="$(mktemp -d -t meko-test-wm-XXXXXX)"