@yugabytedb/meko-mcp 2.1.0 → 2.3.0

package/lib/installer.mjs

@@ -67,7 +67,7 @@ export async function install(options) {
 
   info("Checking prerequisites...");
   try {
-    await adapter.detectPrerequisites({ verbose, log: LOG, scope, projectRoot });
+    await adapter.detectPrerequisites({ verbose, log: LOG, scope, projectRoot, dryRun });
   } catch (err) {
     error(err.message);
     throw err;
@@ -134,6 +134,7 @@ export async function install(options) {
 
   try {
     adapter.setHookEnvironment({
+      name,
       url,
       apiKey,
       scope,
@@ -152,6 +153,22 @@ export async function install(options) {
   }
   currentStep++;
 
+  // Runs even when MCP registration was skipped so a rotated key still
+  // reaches the launchd env / shell rc. See yugabyte/meko-mcp-server#337.
+  if (typeof adapter.syncCloudAuthEnvironment === "function") {
+    try {
+      await adapter.syncCloudAuthEnvironment({
+        apiKey,
+        dryRun,
+        verbose,
+        log: LOG,
+        yes,
+      });
+    } catch (err) {
+      warn(`Cloud auth environment sync failed (non-fatal): ${err.message}`);
+    }
+  }
+
   if (!skipSkills) {
     try {
       const result = adapter.installSkills({

package/lib/migrate/adapters/claude-code.mjs

@@ -10,7 +10,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
-import { agentIdForClaude, slugifyCwd } from "../id.mjs";
+import { agentIdForClaude, deriveLegacyAgentId, slugifyCwd } from "../id.mjs";
 import { parseSessionStream, peekSessionMetadata } from "../claude-parser.mjs";
 
 function homeDir() {
@@ -46,6 +46,7 @@ export function userClaudeMdPath(opts = {}) {
  * @property {string} slug
  * @property {string} cwd             Derived from the first session in the slug dir.
  * @property {string} agentId
+ * @property {string} legacyAgentId   Pre-MEKO-590 resume-state alias.
  * @property {number} size
  * @property {number} mtimeMs
  * @property {boolean} likelyInProgress
@@ -96,12 +97,20 @@ export async function listSessions(opts) {
       let stat;
       try { stat = fs.statSync(full); } catch { continue; }
       const sessionUuid = e.name.replace(/\.jsonl$/, "");
+      const legacyAgentId = deriveLegacyAgentId({
+        client: "claude_code",
+        cwd: slugCwd,
+        envOverride: process.env.MEKO_AGENT_ID,
+      });
       out.push({
         sessionUuid,
         path: full,
         slug,
         cwd: slugCwd,
-        agentId: agentIdForClaude(slugCwd),
+        // Historical: `slugCwd` is a cwd recorded in an old transcript (or
+        // reverse-slugged from the project dir name) and may no longer exist.
+        agentId: agentIdForClaude(slugCwd, { historical: true }),
+        legacyAgentId,
         size: stat.size,
         mtimeMs: stat.mtimeMs,
         likelyInProgress: stat.mtimeMs > Date.now() - 60_000,

package/lib/migrate/adapters/codex.mjs

@@ -0,0 +1,497 @@
+/**
+ * adapters/codex.mjs — Enumerate + parse Codex CLI/Desktop session rollouts.
+ *
+ * Codex writes one JSONL "rollout" file per session under:
+ *   <CODEX_HOME|~/.codex>/sessions/<YYYY>/<MM>/<DD>/rollout-<ts>-<uuid>.jsonl
+ *
+ * Each line is `{timestamp, type, payload}`. The shapes we consume:
+ *   - type "session_meta": payload has `session_id` and `cwd` (the project
+ *     root the session ran in — the source of truth for agent_id derivation).
+ *   - type "event_msg", payload.type "user_message": the AUTHORITATIVE marker
+ *     for a real user prompt. Codex also writes `response_item`/`message`
+ *     role=user records for injected context (`<recommended_plugins>`,
+ *     AGENTS.md, the Meko SessionStart block); those have NO mirrored
+ *     user_message event, so we use the event stream to tell a real prompt
+ *     from injected context.
+ *   - type "response_item", payload.type "message", role "assistant": one
+ *     slice of the assistant's reply. A single turn emits several — phase
+ *     "commentary" updates then phase "final_answer" — so we accumulate ALL
+ *     of them into one assistant side and only close the turn at the
+ *     completion boundary (next user prompt or `event_msg` task_complete).
+ *   - type "response_item", payload.type "reasoning" /
+ *     "custom_tool_call" / "custom_tool_call_output": reasoning + tool
+ *     activity, folded into the turn's `reasoning` (parity with the
+ *     Claude Code / Cursor adapters).
+ *
+ * Completion-boundary discriminator (kept consistent with the live parser in
+ * PR #234): assistant `phase: "final_answer"` and/or the `event_msg`
+ * `payload.type: "task_complete"` record close a turn.
+ *
+ * Unknown line/block shapes are skipped, never fatal — Codex's on-disk
+ * schema drifts across CLI versions.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { agentIdForCodex, deriveLegacyAgentId } from "../id.mjs";
+
+// Cap for the first-record read. Codex embeds `base_instructions` in the
+// session_meta line, which routinely exceeds 16 KiB; read generously so the
+// full first record parses. 4 MiB is far above any real header while still
+// bounding a pathological file.
+const HEADER_READ_CAP = 4 * 1024 * 1024;
+
+function homeDir() {
+  return process.env.HOME || os.homedir();
+}
+
+/**
+ * The `.codex` home. Honors `CODEX_HOME` (production sets it to relocate all
+ * Codex state); otherwise `<home>/.codex`. The injectable `opts.home` override
+ * is preserved for tests and only applies to the default location.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.home]
+ * @returns {string}
+ */
+export function codexHome(opts = {}) {
+  const envHome = (process.env.CODEX_HOME || "").trim();
+  if (envHome) return envHome;
+  return path.join(opts.home ?? homeDir(), ".codex");
+}
+
+/**
+ * The sessions root Codex writes rollout files under.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.home]
+ * @returns {string}
+ */
+export function sessionsRoot(opts = {}) {
+  return path.join(codexHome(opts), "sessions");
+}
+
+/**
+ * @typedef {Object} CodexSessionRef
+ * @property {string} sessionUuid     Rollout filename basename (matches
+ *   capture.js::extractSessionId, so migrator + live capture dedup to the
+ *   same conversation container).
+ * @property {string} path            Absolute path to the rollout .jsonl.
+ * @property {string} cwd             Project root from session_meta.
+ * @property {string} agentId         `codex:<repo-basename>`.
+ * @property {string} legacyAgentId   Pre-MEKO-590 resume-state alias.
+ * @property {"codex"} source
+ * @property {number} mtimeMs
+ * @property {boolean} likelyInProgress
+ */
+
+/**
+ * Recursively collect rollout-*.jsonl paths under the date-partitioned tree.
+ *
+ * @param {string} dir
+ * @returns {string[]}
+ */
+function collectRolloutFiles(dir) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const e of entries) {
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) {
+      out.push(...collectRolloutFiles(full));
+    } else if (e.isFile() && e.name.startsWith("rollout-") && e.name.endsWith(".jsonl")) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+/**
+ * Read the COMPLETE first JSONL record (through the first newline) and, if it
+ * is the `session_meta` header, harvest `session_id` + `cwd` + `timestamp`.
+ * Reads in chunks up to HEADER_READ_CAP so a large `base_instructions` block
+ * (>16 KiB, common in current rollouts) still parses — a bounded prefix would
+ * truncate the line, fail to parse, and silently drop the session.
+ *
+ * @param {string} filePath
+ * @returns {{ sessionId: string|null, cwd: string|null, startedAt: string|null }}
+ */
+export function peekSessionMeta(filePath) {
+  const empty = { sessionId: null, cwd: null, startedAt: null };
+  let fd;
+  try {
+    fd = fs.openSync(filePath, "r");
+    const chunkSize = 65536;
+    const chunk = Buffer.alloc(chunkSize);
+    let acc = "";
+    let offset = 0;
+    let newlineIdx = -1;
+    while (offset < HEADER_READ_CAP) {
+      const bytesRead = fs.readSync(fd, chunk, 0, chunkSize, offset);
+      if (bytesRead === 0) break;
+      acc += chunk.toString("utf-8", 0, bytesRead);
+      offset += bytesRead;
+      newlineIdx = acc.indexOf("\n");
+      if (newlineIdx !== -1) break;
+    }
+    const firstLine = (newlineIdx === -1 ? acc : acc.slice(0, newlineIdx)).trim();
+    if (!firstLine) return empty;
+    const obj = JSON.parse(firstLine);
+    if (obj && obj.type === "session_meta" && obj.payload && typeof obj.payload === "object") {
+      const p = obj.payload;
+      const str = (v) => (typeof v === "string" ? v : null);
+      return {
+        sessionId: str(p.session_id) || str(p.id),
+        cwd: str(p.cwd),
+        startedAt: str(p.timestamp) || str(obj.timestamp),
+      };
+    }
+    return empty;
+  } catch {
+    return empty;
+  } finally {
+    if (fd !== undefined) {
+      try { fs.closeSync(fd); } catch { /* FD already gone */ }
+    }
+  }
+}
+
+/**
+ * The session identifier used for conversation dedup. Standardized on the
+ * rollout FILENAME BASENAME so it matches capture.js::extractSessionId
+ * (`path.basename(transcriptPath, ".jsonl")`) — live hook capture and the
+ * migrator then create/reconnect the SAME conversation container instead of
+ * two divergent ones for the same session.
+ *
+ * @param {string} rolloutPath
+ * @returns {string}
+ */
+export function sessionUuidForRollout(rolloutPath) {
+  return path.basename(rolloutPath, ".jsonl");
+}
+
+/**
+ * @param {object} opts
+ * @param {"user"|"project"} opts.scope
+ * @param {string} [opts.projectCwd]
+ * @param {string} [opts.home]
+ * @returns {CodexSessionRef[]}
+ */
+export function listSessions(opts) {
+  const root = sessionsRoot(opts);
+  if (!fs.existsSync(root)) return [];
+
+  const wantedCwd = opts.scope === "project" ? opts.projectCwd : null;
+
+  const out = [];
+  for (const full of collectRolloutFiles(root)) {
+    const meta = peekSessionMeta(full);
+    if (!meta.cwd) continue;
+    if (wantedCwd && meta.cwd !== wantedCwd) continue;
+    let stat;
+    try {
+      stat = fs.statSync(full);
+    } catch {
+      continue;
+    }
+    out.push({
+      sessionUuid: sessionUuidForRollout(full),
+      path: full,
+      cwd: meta.cwd,
+      // Historical: cwd recorded in the rollout, may be gone from disk.
+      agentId: agentIdForCodex(meta.cwd, { historical: true }),
+      legacyAgentId: deriveLegacyAgentId({
+        client: "codex",
+        cwd: meta.cwd,
+        envOverride: process.env.MEKO_AGENT_ID,
+      }),
+      source: "codex",
+      mtimeMs: stat.mtimeMs,
+      likelyInProgress: stat.mtimeMs > Date.now() - 60_000,
+    });
+  }
+  return out;
+}
+
+/**
+ * Parse a rollout file: pair real user prompts with the full assistant reply.
+ *
+ * @param {string} sessionPath
+ * @returns {{
+ *   sessionUuid: string,
+ *   firstUserText: string,
+ *   cwd: string|null,
+ *   startedAt: string|null,
+ *   exchanges: Array<{user_uuid: string, input: string, output: string, reasoning: string, timestamp: string}>,
+ *   partial: boolean,
+ * }}
+ */
+export function parseSession(sessionPath) {
+  const { records, realPrompts, hasUserMessageEvents } = collectRecords(sessionPath);
+
+  let cwd = null;
+  let startedAt = null;
+  let firstUserText = "";
+
+  // Turn assembly. A real user prompt opens a turn; every assistant slice and
+  // reasoning/tool record until the next real prompt (or a task_complete)
+  // belongs to it. `turnIdx` — the positional id fallback for id-less Codex
+  // user records — increments ONLY when a turn is emitted, so a turn that is
+  // held on one run gets the SAME id when it is finally emitted on a later run
+  // (all preceding emitted turns are identical), keeping seed dedup stable.
+  const exchanges = [];
+  let turnIdx = 0;
+  // current: { input, uuid, timestamp, lastTimestamp, outputs, reasoning,
+  //            hasAssistant, sawPhase, sawFinalAnswer, boundaryClosed }
+  let current = null;
+
+  // A turn is safe to emit once it has reached its completion boundary — the
+  // SAME boundary the live parser in PR #234 uses:
+  //   - a `task_complete` event closed it (boundaryClosed), OR
+  //   - an assistant slice with phase `final_answer` arrived, OR
+  //   - it is the legacy/simple shape: assistant content but no phase info at
+  //     all (older rollouts don't tag phases) — complete as soon as any
+  //     assistant message exists, like non-Codex turns.
+  // A turn still streaming commentary with no boundary, or with no assistant
+  // reply yet, is NOT complete and must be held (see the EOF flush below) so
+  // the whole turn is captured once on a later run rather than sent early and
+  // then permanently skipped by lastUuid resume when its final answer arrives.
+  const isComplete = (t) =>
+    t.boundaryClosed || t.sawFinalAnswer || (t.hasAssistant && !t.sawPhase);
+
+  // Emit `current` as an exchange. `allowIncomplete` is true only when a new
+  // real prompt supersedes it (the turn is definitively over — no more content
+  // will ever be appended to it) or a task_complete closed it; at EOF we pass
+  // false so a still-in-progress trailing turn is HELD, not emitted.
+  const flush = (allowIncomplete) => {
+    if (!current) return;
+    const t = current;
+    current = null;
+    if (!allowIncomplete && !isComplete(t)) return; // hold: do not emit or advance turnIdx
+    const output = t.outputs.join("\n\n");
+    const reasoning = t.reasoning.join("\n---\n");
+    if (t.input || output) {
+      exchanges.push({
+        user_uuid: t.uuid || `codex-${turnIdx}`,
+        input: t.input,
+        output,
+        reasoning,
+        timestamp: t.lastTimestamp || t.timestamp || "",
+      });
+      turnIdx++;
+    }
+  };
+
+  for (const rec of records) {
+    if (rec.kind === "meta") {
+      if (!cwd) cwd = rec.cwd;
+      if (!startedAt) startedAt = rec.timestamp;
+      continue;
+    }
+    if (!startedAt && rec.timestamp) startedAt = rec.timestamp;
+
+    if (rec.kind === "user") {
+      // Only real prompts open a turn. When user_message events exist they are
+      // authoritative: a role=user response_item whose text isn't among them is
+      // injected context (plugins/AGENTS.md/Meko block) and is dropped.
+      if (hasUserMessageEvents && !realPrompts.has(rec.text)) continue;
+      // A new real prompt means the previous turn is definitively over — emit
+      // it even if it never saw an explicit boundary (it won't get more).
+      flush(true);
+      if (!firstUserText && rec.text) firstUserText = rec.text.slice(0, 240);
+      current = {
+        input: rec.text,
+        uuid: rec.uuid,
+        timestamp: rec.timestamp,
+        lastTimestamp: rec.timestamp,
+        outputs: [],
+        reasoning: [],
+        hasAssistant: false,
+        sawPhase: false,
+        sawFinalAnswer: false,
+        boundaryClosed: false,
+      };
+    } else if (rec.kind === "assistant") {
+      if (!current) continue; // assistant with no preceding real prompt — skip
+      current.hasAssistant = true;
+      if (rec.phase) current.sawPhase = true;
+      if (rec.phase === "final_answer") current.sawFinalAnswer = true;
+      if (rec.text) current.outputs.push(rec.text);
+      if (rec.timestamp) current.lastTimestamp = rec.timestamp;
+    } else if (rec.kind === "reasoning" || rec.kind === "tool_call" || rec.kind === "tool_result") {
+      if (!current) continue;
+      if (rec.text) current.reasoning.push(rec.text);
+      if (rec.timestamp) current.lastTimestamp = rec.timestamp;
+    } else if (rec.kind === "task_complete") {
+      // Completion boundary: the current turn is finished — emit it.
+      if (current) {
+        current.boundaryClosed = true;
+        if (rec.timestamp) current.lastTimestamp = rec.timestamp;
+      }
+      flush(true);
+    }
+  }
+  // EOF: hold a still-incomplete trailing turn (no boundary / no assistant yet)
+  // so it is captured whole on a later run once its completion is appended.
+  flush(false);
+
+  return {
+    sessionUuid: sessionUuidForRollout(sessionPath),
+    firstUserText,
+    cwd,
+    startedAt,
+    exchanges,
+    // Codex keeps a session's rollout open across turns and writes a
+    // `task_complete` after EACH one, so there is no reliable end-of-session
+    // marker: an interactive session can sit idle for minutes (well past any
+    // mtime window) and then append another prompt. Finalizing from a quiet
+    // period or a trailing task_complete would mark the session done and make
+    // the orchestrator skip it forever, dropping every later turn. So Codex
+    // rollouts stay rescan-capable (`partial: true`) unconditionally; the
+    // orchestrator re-reads them each run, lastUuid resume skips already-sent
+    // turns, and seed dedup (<conv>:<user_uuid>) makes the re-scan a no-op when
+    // nothing new was appended. Combined with the incomplete-trailing-turn hold
+    // above, this guarantees any appended turn is eventually migrated exactly
+    // once.
+    partial: true,
+  };
+}
+
+/**
+ * Read + classify every JSONL record we care about, and collect the set of
+ * authoritative real-prompt texts from `event_msg`/`user_message`.
+ */
+function collectRecords(filePath) {
+  let raw;
+  try {
+    raw = fs.readFileSync(filePath, "utf8");
+  } catch {
+    return { records: [], realPrompts: new Set(), hasUserMessageEvents: false };
+  }
+  const records = [];
+  const realPrompts = new Set();
+  let hasUserMessageEvents = false;
+
+  for (const line of raw.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    let obj;
+    try {
+      obj = JSON.parse(trimmed);
+    } catch {
+      continue;
+    }
+    const payload = obj.payload;
+    if (!payload || typeof payload !== "object") continue;
+    const ts = obj.timestamp || null;
+
+    if (obj.type === "session_meta") {
+      records.push({
+        kind: "meta",
+        cwd: typeof payload.cwd === "string" ? payload.cwd : null,
+        timestamp: ts || (typeof payload.timestamp === "string" ? payload.timestamp : null),
+      });
+      continue;
+    }
+
+    if (obj.type === "event_msg") {
+      if (payload.type === "user_message" && typeof payload.message === "string") {
+        hasUserMessageEvents = true;
+        realPrompts.add(payload.message);
+      } else if (payload.type === "task_complete") {
+        records.push({ kind: "task_complete", timestamp: ts });
+      }
+      continue;
+    }
+
+    if (obj.type !== "response_item") continue;
+
+    if (payload.type === "message") {
+      const role = payload.role;
+      if (role === "user") {
+        records.push({
+          kind: "user", uuid: payload.id || null, timestamp: ts,
+          text: extractTextBlocks(payload.content),
+        });
+      } else if (role === "assistant") {
+        records.push({
+          kind: "assistant",
+          timestamp: ts,
+          phase: payload.phase || null,
+          text: extractTextBlocks(payload.content),
+        });
+      }
+      // developer / system messages are Codex-internal — dropped.
+      continue;
+    }
+
+    if (payload.type === "reasoning") {
+      const text = extractReasoningSummary(payload.summary);
+      if (text) records.push({ kind: "reasoning", timestamp: ts, text: `THINKING:\n${text}` });
+      continue;
+    }
+
+    if (payload.type === "custom_tool_call") {
+      const name = typeof payload.name === "string" ? payload.name : "unknown";
+      const input = typeof payload.input === "string"
+        ? payload.input.slice(0, 500)
+        : (payload.input ? JSON.stringify(payload.input).slice(0, 500) : "");
+      records.push({ kind: "tool_call", timestamp: ts, text: `TOOL CALL: ${name}(${input})` });
+      continue;
+    }
+
+    if (payload.type === "custom_tool_call_output") {
+      const output = typeof payload.output === "string"
+        ? payload.output
+        : (payload.output != null ? JSON.stringify(payload.output) : "");
+      if (output) {
+        records.push({ kind: "tool_result", timestamp: ts, text: `TOOL RESULT:\n${output.slice(0, 3000)}` });
+      }
+      continue;
+    }
+  }
+
+  return { records, realPrompts, hasUserMessageEvents };
+}
+
+/**
+ * Codex message content blocks are `{type:"input_text"|"output_text"|"text",
+ * text}`. Concatenate the text; ignore non-text blocks.
+ */
+function extractTextBlocks(content) {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  const parts = [];
+  for (const b of content) {
+    if (!b) continue;
+    if (typeof b === "string") { parts.push(b); continue; }
+    if (
+      (b.type === "input_text" || b.type === "output_text" || b.type === "text")
+      && typeof b.text === "string"
+    ) {
+      parts.push(b.text);
+    }
+  }
+  return parts.join("\n");
+}
+
+/**
+ * Codex reasoning items carry a `summary` array of `{type:"summary_text",
+ * text}` blocks. Concatenate their text.
+ */
+function extractReasoningSummary(summary) {
+  if (typeof summary === "string") return summary;
+  if (!Array.isArray(summary)) return "";
+  const parts = [];
+  for (const b of summary) {
+    if (!b) continue;
+    if (typeof b === "string") { parts.push(b); continue; }
+    if (typeof b.text === "string") parts.push(b.text);
+  }
+  return parts.join("\n");
+}

package/lib/migrate/adapters/memory-md.mjs

@@ -14,6 +14,7 @@ import os from "node:os";
 import {
   CLAUDE_CODE_USER_AGENT_ID,
   agentIdForClaude,
+  deriveLegacyAgentId,
   memoryHash,
   slugifyCwd,
 } from "../id.mjs";
@@ -26,6 +27,7 @@ function homeDir() {
 /**
  * @typedef {Object} MemoryItem
  * @property {string} agentId
+ * @property {string} [legacyAgentId] Pre-MEKO-590 state alias.
  * @property {string} text
  * @property {string} hash
  * @property {{source: string, scope: "user"|"project", sourcePath: string, heading?: string, name?: string, description?: string, type?: string}} metadata
@@ -62,22 +64,35 @@ export async function enumerateMemoryItems(opts) {
         if (!stat.isDirectory()) continue;
         const cwd = await cwdForSlugDir(dir, slug);
         if (!cwd) continue;
-        const agentId = agentIdForClaude(cwd);
+        // Historical: recorded/reverse-slugged cwd, may be gone from disk.
+        const agentId = agentIdForClaude(cwd, { historical: true });
+        const legacyAgentId = deriveLegacyAgentId({
+          client: "claude_code",
+          cwd,
+          envOverride: process.env.MEKO_AGENT_ID,
+        });
         const projMd = path.join(cwd, ".claude", "CLAUDE.md");
-        items.push(...readClaudeMd(projMd, agentId, "project", cwd));
+        items.push(...readClaudeMd(projMd, agentId, "project", cwd, legacyAgentId));
         const memDir = path.join(dir, "memory");
-        items.push(...readMemoryDir(memDir, agentId, "project", cwd));
+        items.push(...readMemoryDir(memDir, agentId, "project", cwd, legacyAgentId));
       }
     }
   } else {
     const cwd = opts.projectCwd;
     if (!cwd) return [];
-    const agentId = agentIdForClaude(cwd);
+    // Keep project CLAUDE.md and indexed memories in the same bucket as the
+    // historical session adapter, including when the cwd is no longer a repo.
+    const agentId = agentIdForClaude(cwd, { historical: true });
+    const legacyAgentId = deriveLegacyAgentId({
+      client: "claude_code",
+      cwd,
+      envOverride: process.env.MEKO_AGENT_ID,
+    });
     const projMd = path.join(cwd, ".claude", "CLAUDE.md");
-    items.push(...readClaudeMd(projMd, agentId, "project", cwd));
+    items.push(...readClaudeMd(projMd, agentId, "project", cwd, legacyAgentId));
     const slug = slugifyCwd(cwd);
     const memDir = path.join(home, ".claude", "projects", slug, "memory");
-    items.push(...readMemoryDir(memDir, agentId, "project", cwd));
+    items.push(...readMemoryDir(memDir, agentId, "project", cwd, legacyAgentId));
   }
 
   return items;
@@ -94,9 +109,10 @@ export async function enumerateMemoryItems(opts) {
  *   so downstream consumers can correlate even after the agent_id is
  *   sanitized down to a basename. Null for user-scope items (which use the
  *   `meko_agent` common bucket).
+ * @param {string|null} [legacyAgentId] Pre-MEKO-590 compatibility alias.
  * @returns {MemoryItem[]}
  */
-export function readClaudeMd(filePath, agentId, scope, cwd = null) {
+export function readClaudeMd(filePath, agentId, scope, cwd = null, legacyAgentId = null) {
   let raw;
   try {
     raw = fs.readFileSync(filePath, "utf8");
@@ -112,6 +128,7 @@ export function readClaudeMd(filePath, agentId, scope, cwd = null) {
     const name = heading || path.basename(filePath);
     return {
       agentId,
+      ...(legacyAgentId && legacyAgentId !== agentId ? { legacyAgentId } : {}),
       text,
       hash: memoryHash(text, name),
       name,
@@ -166,9 +183,10 @@ export function splitTopLevelSections(md) {
  * @param {string} agentId
  * @param {"user"|"project"} scope
  * @param {string|null} [cwd] - Absolute project path; attached to metadata.
+ * @param {string|null} [legacyAgentId] Pre-MEKO-590 compatibility alias.
  * @returns {MemoryItem[]}
  */
-export function readMemoryDir(memDir, agentId, scope, cwd = null) {
+export function readMemoryDir(memDir, agentId, scope, cwd = null, legacyAgentId = null) {
   let entries;
   try {
     entries = fs.readdirSync(memDir);
@@ -192,6 +210,7 @@ export function readMemoryDir(memDir, agentId, scope, cwd = null) {
     const name = frontmatter.name || entry.replace(/\.md$/, "");
     out.push({
       agentId,
+      ...(legacyAgentId && legacyAgentId !== agentId ? { legacyAgentId } : {}),
       text,
       hash: memoryHash(text, name),
       name,