@yugabytedb/meko-mcp 1.0.8 → 1.1.0

package/lib/clients/common.mjs

@@ -1,5 +1,15 @@
 import { execSync } from "node:child_process";
-import { existsSync, mkdirSync, symlinkSync, cpSync, lstatSync, unlinkSync, rmSync } from "node:fs";
+import {
+  existsSync,
+  mkdirSync,
+  symlinkSync,
+  cpSync,
+  lstatSync,
+  unlinkSync,
+  rmSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -131,3 +141,134 @@ export function removePath(targetPath) {
     // no-op
   }
 }
+
+// ---------------------------------------------------------------------------
+// Installer version markers
+// ---------------------------------------------------------------------------
+//
+// Each artifact the installer owns (a deployed skill dir, a built .skill
+// bundle, the Claude Code meko-capture dir, etc.) gets a `.meko-installer`
+// marker file stamped with the installer's version. On re-run we compare the
+// marker's version against the current installer to decide whether we need
+// to force-refresh a managed artifact. Without a marker the artifact is
+// treated as user-managed and left alone — we never clobber a dir we didn't
+// produce ourselves.
+//
+// The marker format is deliberately plain text, one `key=value` per line,
+// so a human inspecting it with `cat` can immediately see what produced
+// the artifact and when.
+
+const MARKER_FILENAME = ".meko-installer";
+
+/**
+ * Read the installer's package.json `version` field. Mirrors the read
+ * performed in bin/create-meko-setup.mjs:56-59 so the marker and the
+ * CLI's --version report agree.
+ *
+ * @returns {string}
+ */
+export function getInstallerVersion() {
+  const libDir = dirname(fileURLToPath(import.meta.url));
+  const pkgPath = resolve(libDir, "..", "..", "package.json");
+  const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+  return pkg.version;
+}
+
+/**
+ * Write a `.meko-installer` marker inside `dir`. Format is one `key=value`
+ * line per field, e.g.
+ *
+ *   version=1.0.8
+ *   installedAt=2026-04-30T14:22:11.123Z
+ *
+ * Extra key/value pairs can be appended via `extra`. `dir` must exist; this
+ * function will not create it (the caller has already done mkdir).
+ *
+ * @param {string} dir
+ * @param {{extra?: Record<string,string>}} [opts]
+ * @returns {{path: string, version: string, installedAt: string}}
+ */
+export function writeInstallerMarker(dir, { extra = {} } = {}) {
+  const version = getInstallerVersion();
+  const installedAt = new Date().toISOString();
+  const lines = [`version=${version}`, `installedAt=${installedAt}`];
+  for (const [key, value] of Object.entries(extra)) {
+    lines.push(`${key}=${value}`);
+  }
+  const markerPath = join(dir, MARKER_FILENAME);
+  writeFileSync(markerPath, lines.join("\n") + "\n", "utf8");
+  return { path: markerPath, version, installedAt };
+}
+
+/**
+ * Parse a `.meko-installer` marker from `dir`. Returns null if the marker
+ * is missing or unreadable. Callers treat null as "not ours / user-managed".
+ *
+ * Marker format evolved across installer versions:
+ *   - pre-1.0.9: a single line containing the word "managed". No version.
+ *   - 1.0.9+:    `key=value` lines, including `version=` and `installedAt=`.
+ *
+ * Both shapes indicate "we own this artifact"; the caller needs to know
+ * which shape it got so it can decide whether to force a refresh. Legacy
+ * markers have no version to compare against, so they are returned with
+ * `legacy: true` and no `version` — `markerIsStale` then treats them as
+ * stale (any current version mismatches) and triggers a refresh. That's
+ * exactly the behavior users hitting the "stale skill" bug from 1.0.8
+ * need on their next re-install.
+ *
+ * @param {string} dir
+ * @returns {{version?: string, installedAt?: string, legacy?: boolean, [k: string]: string|boolean|undefined}|null}
+ */
+export function readInstallerMarker(dir) {
+  const markerPath = join(dir, MARKER_FILENAME);
+  let raw;
+  try {
+    raw = readFileSync(markerPath, "utf8");
+  } catch {
+    return null;
+  }
+  const out = {};
+  for (const line of raw.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    const eq = trimmed.indexOf("=");
+    if (eq <= 0) continue;
+    const key = trimmed.slice(0, eq).trim();
+    const value = trimmed.slice(eq + 1).trim();
+    if (!key) continue;
+    out[key] = value;
+  }
+  if (out.version) return out;
+
+  // Legacy marker path: pre-1.0.9 installs wrote the literal text
+  // `managed\n` (no `=`). Recognize it so we don't mistake an older
+  // managed dir for a user-managed one. Returning a parsed object with
+  // `legacy: true` lets markerIsStale do the right thing (stale → refresh).
+  if (raw.trim() === "managed") {
+    return { legacy: true };
+  }
+  return null;
+}
+
+/**
+ * True when the artifact at `dir` was produced by a different installer
+ * version than `currentVersion`. Also true when the marker is missing or
+ * unparseable — in that case the caller still needs to check whether the
+ * artifact dir exists (missing marker + missing dir = fresh install; missing
+ * marker + existing dir = user-managed, handle separately).
+ *
+ * Strict inequality by design — any version change forces a refresh, even
+ * a downgrade. We don't want to play semver-comparison games when the
+ * artifact content may have changed in either direction.
+ *
+ * @param {string} dir
+ * @param {string} currentVersion
+ * @returns {boolean}
+ */
+export function markerIsStale(dir, currentVersion) {
+  const marker = readInstallerMarker(dir);
+  if (!marker) return true;
+  // Legacy `managed\n` marker has no version recorded — always stale.
+  if (marker.legacy) return true;
+  return marker.version !== currentVersion;
+}

package/lib/clients/cursor.mjs

@@ -2,7 +2,6 @@ import {
   existsSync,
   lstatSync,
   readlinkSync,
-  writeFileSync,
   mkdirSync,
 } from "node:fs";
 import { homedir } from "node:os";
@@ -17,10 +16,14 @@ import {
   writeJsonFile,
 } from "../config.mjs";
 import {
+  getInstallerVersion,
+  markerIsStale,
+  readInstallerMarker,
   resolveHooksRoot,
   resolveSkillSource,
   removePath,
   symlinkOrCopy,
+  writeInstallerMarker,
 } from "./common.mjs";
 
 const SKILLS = [{ name: "meko-mcp-tools" }];
@@ -118,8 +121,10 @@ export function createCursorAdapter(customPaths = {}) {
     },
     installSkills({ dryRun, log, scope, projectRoot }) {
       const skillDir = paths.getSkillsDir(scope, projectRoot);
+      const currentVersion = getInstallerVersion();
       if (dryRun) {
         log.dim(`  Would install skills into ${skillDir}`);
+        log.dim(`  Would write .meko-installer marker (version=${currentVersion})`);
         return { marketplace: "skipped", skills: "dry-run" };
       }
 
@@ -127,10 +132,42 @@ export function createCursorAdapter(customPaths = {}) {
       for (const skill of SKILLS) {
         const source = resolveSkillSource(skill.name);
         const destination = join(skillDir, skill.name);
-        if (existsSync(destination)) continue;
+
+        if (existsSync(destination)) {
+          // Symlinks pointing at our own source directory are already live —
+          // the source tree IS the latest content, so there's nothing to
+          // refresh. Treat them the same as a fresh-current-version install.
+          if (isOwnSymlink(destination, source)) continue;
+
+          const marker = readInstallerMarker(destination);
+          if (!marker) {
+            // No marker AND not a symlink we own — user-managed dir or a
+            // pre-marker install. Leave it alone to avoid clobbering local
+            // edits; the user can delete it themselves for a fresh deploy.
+            log.dim(
+              `  Skipping ${destination}: no .meko-installer marker (user-managed).`,
+            );
+            continue;
+          }
+          if (markerIsStale(destination, currentVersion)) {
+            const from = marker.version ?? "pre-1.0.9";
+            log.dim(
+              `  Upgrading cursor skill from ${from} -> ${currentVersion}`,
+            );
+            removePath(destination);
+          } else {
+            // Same version already deployed — nothing to do.
+            continue;
+          }
+        }
+
         const strategy = symlinkOrCopy(source, destination);
+        // Only stamp a marker when we materialized a real copy. Writing into
+        // a symlinked source dir would mutate the shipped asset tree, which
+        // is confusing at best and a permission error at worst. Symlinks
+        // re-resolve via isOwnSymlink on the next run.
         if (strategy === "copy") {
-          writeFileSync(join(destination, ".meko-installer"), "managed\n", "utf8");
+          writeInstallerMarker(destination);
         }
       }
 
@@ -217,6 +254,20 @@ function installNativeCursorHooks({ scope, projectRoot, url, apiKey, paths }) {
   writeJsonFile(hooksPath, cfg);
 }
 
+// Cursor's claude-compat mode writes absolute-path Meko hook entries into
+// the shared settings.json (on scope=user, the same file Claude Code owns)
+// and de-dupes them via upsertClaudeCompatHook. The Claude Code adapter's
+// pruneMekoHookEntries (issue #60) is narrowed to preserve any entry whose
+// command references the current resolveHooksRoot() — so the entry this
+// function writes survives a subsequent Claude Code install from the
+// SAME install root.
+//
+// TRADE-OFF: if Cursor installed from a different root (e.g. repo clone)
+// than a later Claude Code install (e.g. npx cache), Cursor's entries look
+// byte-identical to the stale Claude Code entries issue #60 targets. They
+// will be pruned; the user must re-run the Cursor installer to restore
+// them. pruneMekoHookEntries emits a warning on any removal so the user
+// has a chance to notice before hooks silently disappear.
 function installClaudeCompatHooks({ scope, projectRoot, url, apiKey, paths }) {
   const settingsPath = paths.getClaudeCompatSettingsPath(scope, projectRoot);
   const cfg = readJsonFile(settingsPath);
@@ -314,6 +365,23 @@ function uninstallCursorHooks({ scope, projectRoot, mode, paths }) {
   }
 }
 
+/**
+ * True when `destination` is a symlink that resolves to `expectedSource`.
+ * Used to recognize in-place symlink installs on re-run: the live source is
+ * the latest content, so there's nothing to refresh.
+ */
+function isOwnSymlink(destination, expectedSource) {
+  try {
+    const stat = lstatSync(destination);
+    if (!stat.isSymbolicLink()) return false;
+    const linkTarget = readlinkSync(destination);
+    const resolvedTarget = resolve(dirname(destination), linkTarget);
+    return resolvedTarget === expectedSource;
+  } catch {
+    return false;
+  }
+}
+
 function uninstallCursorSkills({ scope, projectRoot, paths }) {
   const skillsDir = paths.getSkillsDir(scope, projectRoot);
 

package/lib/clients/index.mjs

@@ -1,5 +1,6 @@
 import { createClaudeCodeAdapter } from "./claude-code.mjs";
 import { createClaudeDesktopAdapter } from "./claude-desktop.mjs";
+import { createCodexAdapter } from "./codex.mjs";
 import { createCursorAdapter } from "./cursor.mjs";
 
 /**
@@ -10,5 +11,6 @@ export function getClientAdapters() {
     "claude-code": createClaudeCodeAdapter(),
     "claude-desktop": createClaudeDesktopAdapter(),
     cursor: createCursorAdapter(),
+    codex: createCodexAdapter(),
   };
 }

package/lib/config.mjs

@@ -96,6 +96,36 @@ export function getClaudeCompatSettingsPath(scope, projectRoot) {
   return getClaudeCodeSettingsPath();
 }
 
+/**
+ * Return path to Codex's user-level config (TOML).
+ * Honors $CODEX_HOME if set, else defaults to ~/.codex/config.toml.
+ * Codex has no project-level config — caller should warn and degrade
+ * if a project scope was requested.
+ * @returns {string}
+ */
+export function getCodexConfigPath() {
+  const codexHome = process.env.CODEX_HOME || join(homedir(), ".codex");
+  return join(codexHome, "config.toml");
+}
+
+/**
+ * Return path to Codex's user-level AGENTS.md.
+ * @returns {string}
+ */
+export function getCodexAgentsMdPath() {
+  const codexHome = process.env.CODEX_HOME || join(homedir(), ".codex");
+  return join(codexHome, "AGENTS.md");
+}
+
+/**
+ * Return path to the shared agent-skills directory used by Codex
+ * (and other agent runtimes that follow the convention).
+ * @returns {string}
+ */
+export function getCodexSkillsRoot() {
+  return join(homedir(), ".agents", "skills");
+}
+
 // ---------------------------------------------------------------------------
 // Read / Write primitives
 // ---------------------------------------------------------------------------

package/lib/detect.mjs

@@ -8,6 +8,10 @@
  */
 
 import { execSync } from "node:child_process";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import { readJsonFile } from "./config.mjs";
 
 // ---------------------------------------------------------------------------
 // Internal helpers
@@ -70,56 +74,60 @@ export function detectClaude() {
 // detectExistingMeko
 // ---------------------------------------------------------------------------
 
+/**
+ * Canonical location of Claude Code's user-scope MCP registry. This is the
+ * file `claude mcp add` writes to — we read it directly rather than shelling
+ * out to `claude mcp list`, which takes 18–28s on real user machines and
+ * was timing out against our 10s guard (issue #80).
+ *
+ * @returns {string}
+ */
+export function getClaudeCodeConfigPath() {
+  return join(homedir(), ".claude.json");
+}
+
 /**
  * Check if a Meko MCP server is already registered in Claude Code.
  *
- * Runs `claude mcp list` and scans the output for the given server name.
- * The output format may vary between Claude CLI versions; we look for a
- * line that starts with `<serverName>:` (e.g. "meko: http://... - Connected")
- * and extract a status keyword from it.
+ * Reads `~/.claude.json` directly and inspects either `mcpServers[serverName]`
+ * (user scope) or `projects[projectRoot].mcpServers[serverName]` (project
+ * scope). This mirrors the approach the Claude Desktop adapter already uses
+ * against its own config (installer/lib/clients/claude-desktop.mjs:detectExisting)
+ * and replaces the previous `claude mcp list` shell-out, which silently
+ * returned `found: false` whenever the CLI exceeded the 10s run() timeout.
+ *
+ * Scope handling: `claude mcp add --scope project` writes under
+ * `projects[<absolute projectRoot>].mcpServers`, not the top-level
+ * `mcpServers`. A project-scope re-install must detect the existing entry
+ * in that nested location, otherwise the overwrite prompt is skipped and
+ * `claude mcp add --scope project` rejects the duplicate with "already
+ * exists". User-scope installs read the top-level `mcpServers` object
+ * (which is where the CLI writes entries added with `--scope user`).
  *
  * @param {string} [serverName="meko"] - The MCP server name to look for.
+ * @param {{ configPath?: string, scope?: "user"|"project", projectRoot?: string }} [options]
+ *   `configPath` — test-only injection point for the config file path; defaults to `~/.claude.json`.
+ *   `scope`      — "user" (default) or "project". Project scope looks under `projects[projectRoot].mcpServers`.
+ *   `projectRoot` — absolute path used as the key into `projects[...]` when `scope === "project"`.
+ *                   Ignored for user scope. Must be supplied by the caller for project scope.
  * @returns {{ found: boolean, status: string }}
- *   `found`  - true if a line matching `serverName` was found.
- *   `status` - the status value from that line (e.g. "Connected", "Failed"),
- *              or "" if not found.
+ *   `found`  - true if a matching MCP entry exists at the scope-appropriate location.
+ *   `status` - "Configured" when found, "" otherwise. (Kept as a string for
+ *              API compatibility with the prior implementation; callers use
+ *              this only for logging, never parsing.)
  */
-export function detectExistingMeko(serverName = "meko") {
-  const result = { found: false, status: "" };
-
-  const output = run("claude mcp list");
-  if (!output) return result;
-
-  // Scan each line for one that begins with the server name.
-  const lines = output.split("\n");
-  for (const line of lines) {
-    const trimmed = line.trim();
-
-    // Match "serverName:" prefix (colon-delimited format) or a table row
-    // where the first whitespace-separated token equals the server name.
-    const isMatch =
-      trimmed.startsWith(`${serverName}:`) ||
-      trimmed.split(/\s+/)[0] === serverName;
-
-    if (!isMatch) continue;
-
-    result.found = true;
-
-    // Extract status from known keywords anywhere on the line.
-    if (/\bConnected\b/i.test(trimmed)) {
-      result.status = "Connected";
-    } else if (/\bFailed\b/i.test(trimmed)) {
-      result.status = "Failed";
-    } else if (/\bError\b/i.test(trimmed)) {
-      result.status = "Error";
-    } else if (/\bDisconnected\b/i.test(trimmed)) {
-      result.status = "Disconnected";
-    } else {
-      result.status = "Unknown";
-    }
-
-    return result;
+export function detectExistingMeko(serverName = "meko", options = {}) {
+  const { scope = "user", projectRoot } = options;
+  const configPath = options.configPath ?? getClaudeCodeConfigPath();
+  const cfg = readJsonFile(configPath);
+
+  const entry =
+    scope === "project"
+      ? cfg?.projects?.[projectRoot]?.mcpServers?.[serverName]
+      : cfg?.mcpServers?.[serverName];
+
+  if (!entry) {
+    return { found: false, status: "" };
   }
-
-  return result;
+  return { found: true, status: "Configured" };
 }

package/lib/installer.mjs

@@ -32,6 +32,7 @@ export async function install(options) {
     name = "meko",
     skipSkills = false,
     skipValidation = false,
+    skipCanary = false,
     dryRun = false,
     verbose = false,
     yes = false,
@@ -107,7 +108,7 @@ export async function install(options) {
 
   if (!skipMcpRegistration) {
     try {
-      adapter.registerServer({
+      await adapter.registerServer({
         name,
         url,
         scope,
@@ -116,6 +117,7 @@ export async function install(options) {
         verbose,
         log: LOG,
         projectRoot,
+        yes,
       });
       stepOk(currentStep, totalSteps, dryRun ? "Registering MCP server (dry-run)." : "MCP server registered.");
     } catch (err) {
@@ -151,6 +153,7 @@ export async function install(options) {
   if (!skipSkills) {
     try {
       const result = adapter.installSkills({
+        name,
         scope,
         dryRun,
         verbose,
@@ -176,7 +179,8 @@ export async function install(options) {
       try {
         const results = await runValidation(url, apiKey, name, {
           validateConfig: async ({ serverName }) =>
-            adapter.validateConfig({ serverName, scope, projectRoot }),
+            adapter.validateConfig({ serverName, scope, projectRoot, url, apiKey }),
+          skipCanary,
         });
 
         const checks = [
@@ -184,6 +188,9 @@ export async function install(options) {
           { label: "Connectivity", ...results.connectivity },
           { label: "Tools", ...results.tools },
         ];
+        if (results.canary) {
+          checks.push({ label: "Canary", ...results.canary });
+        }
         for (const check of checks) {
           if (check.ok) success(`${check.label}: ${check.message}`);
           else warn(`${check.label}: ${check.message}`);

package/lib/mcp-transport.mjs

@@ -29,9 +29,16 @@ export function jsonRpcRequest(url, payload, apiKey, sessionId, opts = {}) {
     const parsed = new URL(url);
     const transport = parsed.protocol === "https:" ? https : http;
 
+    // MCP Streamable HTTP requires the client to advertise both content
+    // types: a non-streaming JSON response uses application/json, a
+    // streaming response (which is what FastMCP returns for `initialize`
+    // and any other call when stateless_http isn't `json_response=True`)
+    // uses text/event-stream. Sending only `application/json` produces a
+    // 406 Not Acceptable from spec-compliant servers (see meko-mcp-server
+    // PR #97 / MEKO-137 which turned this on for prod).
     const headers = {
       "Content-Type": "application/json",
-      Accept: "application/json",
+      Accept: "application/json, text/event-stream",
     };
     if (apiKey) {
       headers["Authorization"] = `Bearer ${apiKey}`;
@@ -56,10 +63,19 @@ export function jsonRpcRequest(url, payload, apiKey, sessionId, opts = {}) {
         const chunks = [];
         res.on("data", (chunk) => chunks.push(chunk));
         res.on("end", () => {
+          const raw = Buffer.concat(chunks).toString("utf8");
+          // If the server answered with text/event-stream (the MCP spec's
+          // streaming response shape), extract the JSON-RPC payload from
+          // the first SSE `data:` field. Callers downstream want a plain
+          // JSON-RPC body — they don't care which framing the wire used.
+          const contentType = String(res.headers["content-type"] ?? "").toLowerCase();
+          const body = contentType.includes("text/event-stream")
+            ? extractSseData(raw)
+            : raw;
           resolve({
             statusCode: res.statusCode,
             headers: res.headers,
-            body: Buffer.concat(chunks).toString("utf8"),
+            body,
           });
         });
       },
@@ -75,6 +91,49 @@ export function jsonRpcRequest(url, payload, apiKey, sessionId, opts = {}) {
   });
 }
 
+/**
+ * Extract the JSON-RPC payload from an SSE-framed response body.
+ *
+ * MCP servers running Streamable HTTP wrap each JSON-RPC response in an
+ * SSE event of the form:
+ *
+ *   event: message
+ *   data: {"jsonrpc":"2.0","id":1,"result":{...}}
+ *
+ * For a single non-streaming JSON-RPC response (initialize, tools/list,
+ * tools/call) there's exactly one event in the body. SSE allows the
+ * payload to span multiple `data:` lines; per the spec they are joined
+ * with `\n`. We concatenate every `data:` line we see in the first event
+ * and return that. Returns the raw body unchanged if no `data:` line is
+ * found (defensive fallback so a misbehaving server still produces a
+ * useful "non-JSON response" error downstream rather than an empty
+ * string).
+ *
+ * @param {string} raw - Raw response body (already utf8-decoded).
+ * @returns {string}
+ */
+function extractSseData(raw) {
+  const dataLines = [];
+  // Split on all three SSE-permitted line terminators per the WHATWG SSE
+  // spec: LF, CRLF, and bare CR. Most servers (including FastMCP) emit
+  // LF or CRLF, but the spec is explicit about CR-only being valid and
+  // we shouldn't break on a producer that uses it.
+  for (const rawLine of raw.split(/\r\n|\r|\n/)) {
+    if (rawLine === "") {
+      // Blank line terminates the event. We only need the first event for
+      // a JSON-RPC response.
+      if (dataLines.length > 0) break;
+      continue;
+    }
+    // `data:` field — capture the value, stripping the optional single
+    // leading space the spec allows after the colon. Anything else
+    // (`event:`, `id:`, `retry:`, comments starting with `:`) we ignore.
+    const match = /^data: ?(.*)$/.exec(rawLine);
+    if (match) dataLines.push(match[1]);
+  }
+  return dataLines.length > 0 ? dataLines.join("\n") : raw;
+}
+
 /**
  * Produce a human-friendly message from a network error.
  *

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

@@ -64,9 +64,9 @@ export async function enumerateMemoryItems(opts) {
         if (!cwd) continue;
         const agentId = agentIdForClaude(cwd);
         const projMd = path.join(cwd, ".claude", "CLAUDE.md");
-        items.push(...readClaudeMd(projMd, agentId, "project"));
+        items.push(...readClaudeMd(projMd, agentId, "project", cwd));
         const memDir = path.join(dir, "memory");
-        items.push(...readMemoryDir(memDir, agentId, "project"));
+        items.push(...readMemoryDir(memDir, agentId, "project", cwd));
       }
     }
   } else {
@@ -74,10 +74,10 @@ export async function enumerateMemoryItems(opts) {
     if (!cwd) return [];
     const agentId = agentIdForClaude(cwd);
     const projMd = path.join(cwd, ".claude", "CLAUDE.md");
-    items.push(...readClaudeMd(projMd, agentId, "project"));
+    items.push(...readClaudeMd(projMd, agentId, "project", cwd));
     const slug = slugifyCwd(cwd);
     const memDir = path.join(home, ".claude", "projects", slug, "memory");
-    items.push(...readMemoryDir(memDir, agentId, "project"));
+    items.push(...readMemoryDir(memDir, agentId, "project", cwd));
   }
 
   return items;
@@ -90,9 +90,13 @@ export async function enumerateMemoryItems(opts) {
  * @param {string} filePath
  * @param {string} agentId
  * @param {"user"|"project"} scope
+ * @param {string|null} [cwd] - Absolute project path. Attached to metadata
+ *   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).
  * @returns {MemoryItem[]}
  */
-export function readClaudeMd(filePath, agentId, scope) {
+export function readClaudeMd(filePath, agentId, scope, cwd = null) {
   let raw;
   try {
     raw = fs.readFileSync(filePath, "utf8");
@@ -115,6 +119,7 @@ export function readClaudeMd(filePath, agentId, scope) {
         source: path.basename(filePath),
         scope,
         sourcePath: filePath,
+        ...(cwd ? { cwd } : {}),
         ...(heading ? { heading } : {}),
       },
     };
@@ -160,9 +165,10 @@ export function splitTopLevelSections(md) {
  * @param {string} memDir
  * @param {string} agentId
  * @param {"user"|"project"} scope
+ * @param {string|null} [cwd] - Absolute project path; attached to metadata.
  * @returns {MemoryItem[]}
  */
-export function readMemoryDir(memDir, agentId, scope) {
+export function readMemoryDir(memDir, agentId, scope, cwd = null) {
   let entries;
   try {
     entries = fs.readdirSync(memDir);
@@ -193,6 +199,7 @@ export function readMemoryDir(memDir, agentId, scope) {
         source: `memory/${entry}`,
         scope,
         sourcePath: full,
+        ...(cwd ? { cwd } : {}),
         ...(frontmatter.name ? { name: frontmatter.name } : {}),
         ...(frontmatter.description ? { description: frontmatter.description } : {}),
         ...(frontmatter.type ? { type: frontmatter.type } : {}),