@withone/cli 1.50.0 → 1.52.0

package/dist/index.js

@@ -32,19 +32,22 @@ import {
   validateActionInput,
   walkSteps,
   writeCache
-} from "./chunk-D6W756DN.js";
+} from "./chunk-K56Z5BTM.js";
 import {
   memSqlCommand
-} from "./chunk-4WWK3GO5.js";
+} from "./chunk-UV4YYDF3.js";
 import {
+  collectIdentityKeys,
   countRecords,
   deleteDatabase,
   deleteRecords,
   dropTable,
   ensureTable,
   evolveSchema,
+  extractSearchableFromPaths,
   generateTemplate,
   getDatabaseSize,
+  getSearchablePaths,
   isSqliteAvailable,
   listBuiltinProfiles,
   listProfiles,
@@ -54,13 +57,15 @@ import {
   openDatabase,
   readProfile,
   rebuildFtsIndex,
+  resolveEntityIdentity,
   resolveProfileConnectionKey,
   sanitizeTableName,
   tableExists,
   upsertRecords,
   writeDraftProfile,
+  writePageToMemory,
   writeProfile
-} from "./chunk-GXOIR3GF.js";
+} from "./chunk-ZOJW6IMU.js";
 import {
   getByDotPath
 } from "./chunk-44CV5IMX.js";
@@ -93,9 +98,8 @@ import {
   getBackendPlugin,
   listBackendPlugins,
   loadBackendFromConfig,
-  updateRecord,
-  upsertRecord
-} from "./chunk-7RV7T5PX.js";
+  updateRecord
+} from "./chunk-Z4KAQGIG.js";
 import {
   DEFAULT_MEMORY_CONFIG,
   defaultSearchableText,
@@ -1033,25 +1037,25 @@ async function loginCommand() {
   let targetScope = "global";
   const existingKey = getApiKey();
   if (existingKey) {
-    const pc15 = (await import("picocolors")).default;
+    const pc16 = (await import("picocolors")).default;
     const resolved2 = resolveConfig();
     const whoami2 = resolved2.config?.whoami;
     const env2 = getEnvFromApiKey(existingKey);
-    const envLabel2 = env2 === "test" ? pc15.yellow("test") : pc15.green("live");
-    const currentScope = resolved2.scope === "project" ? pc15.cyan("local config") : pc15.magenta("global config");
+    const envLabel2 = env2 === "test" ? pc16.yellow("test") : pc16.green("live");
+    const currentScope = resolved2.scope === "project" ? pc16.cyan("local config") : pc16.magenta("global config");
     const lines = ["You are already logged in.", ""];
     if (whoami2) {
       const contextParts2 = [];
       if (whoami2.organization) contextParts2.push(whoami2.organization.name);
       if (whoami2.project) contextParts2.push(whoami2.project.name);
       const scopeDisplay2 = contextParts2.length > 0 ? contextParts2.join(" / ") : "Personal";
-      lines.push(`${pc15.bold(scopeDisplay2)} ${pc15.dim("\xB7")} ${envLabel2}`);
-      lines.push(`${whoami2.user.name} ${pc15.dim(`(${whoami2.user.email})`)}`);
-      if (whoami2.organization) lines.push(`${pc15.dim("Org:")} ${whoami2.organization.name}`);
-      if (whoami2.project) lines.push(`${pc15.dim("Project:")} ${whoami2.project.name}`);
+      lines.push(`${pc16.bold(scopeDisplay2)} ${pc16.dim("\xB7")} ${envLabel2}`);
+      lines.push(`${whoami2.user.name} ${pc16.dim(`(${whoami2.user.email})`)}`);
+      if (whoami2.organization) lines.push(`${pc16.dim("Org:")} ${whoami2.organization.name}`);
+      if (whoami2.project) lines.push(`${pc16.dim("Project:")} ${whoami2.project.name}`);
     }
     lines.push("");
-    lines.push(`${pc15.dim("Stored in")} ${currentScope}`);
+    lines.push(`${pc16.dim("Stored in")} ${currentScope}`);
     p2.note(lines.join("\n"));
     const scopeChoice = await p2.select({
       message: "Where would you like to log in?",
@@ -1074,40 +1078,40 @@ async function loginCommand() {
   if (resolved.config) {
     writeConfig({ ...resolved.config, whoami }, targetScope);
   }
-  const pc14 = (await import("picocolors")).default;
+  const pc15 = (await import("picocolors")).default;
   const env = getEnvFromApiKey(apiKey);
   const contextParts = [];
   if (whoami.organization) contextParts.push(whoami.organization.name);
   if (whoami.project) contextParts.push(whoami.project.name);
   const scopeDisplay = contextParts.length > 0 ? contextParts.join(" / ") : "Personal";
-  const envLabel = env === "test" ? pc14.yellow("test") : pc14.green("live");
-  const configLabel = targetScope === "project" ? pc14.cyan("local config") : pc14.magenta("global config");
+  const envLabel = env === "test" ? pc15.yellow("test") : pc15.green("live");
+  const configLabel = targetScope === "project" ? pc15.cyan("local config") : pc15.magenta("global config");
   const infoLines = [
-    `${pc14.bold(scopeDisplay)} ${pc14.dim("\xB7")} ${envLabel}`,
-    `${whoami.user.name} ${pc14.dim(`(${whoami.user.email})`)}`
+    `${pc15.bold(scopeDisplay)} ${pc15.dim("\xB7")} ${envLabel}`,
+    `${whoami.user.name} ${pc15.dim(`(${whoami.user.email})`)}`
   ];
-  if (whoami.organization) infoLines.push(`${pc14.dim("Org:")} ${whoami.organization.name}`);
-  if (whoami.project) infoLines.push(`${pc14.dim("Project:")} ${whoami.project.name}`);
+  if (whoami.organization) infoLines.push(`${pc15.dim("Org:")} ${whoami.organization.name}`);
+  if (whoami.project) infoLines.push(`${pc15.dim("Project:")} ${whoami.project.name}`);
   infoLines.push("");
-  infoLines.push(`${pc14.dim("Stored in")} ${configLabel}`);
+  infoLines.push(`${pc15.dim("Stored in")} ${configLabel}`);
   p2.note(infoLines.join("\n"), "Logged in");
   console.log();
-  console.log(`  ${pc14.dim("Next steps:")}`);
-  console.log(`  ${pc14.cyan("one add <platform>")}  ${pc14.dim("\u2014")} Connect a platform (e.g. gmail, slack, stripe)`);
+  console.log(`  ${pc15.dim("Next steps:")}`);
+  console.log(`  ${pc15.cyan("one add <platform>")}  ${pc15.dim("\u2014")} Connect a platform (e.g. gmail, slack, stripe)`);
   console.log();
-  console.log(pc14.bold("  Copy-paste this to your AI agent:"));
+  console.log(pc15.bold("  Copy-paste this to your AI agent:"));
   console.log();
-  console.log(pc14.cyan("  \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500"));
-  console.log(pc14.cyan("  \u2502"));
-  console.log(pc14.cyan("  \u2502  The One CLI (`one`) is now installed on this machine. It"));
-  console.log(pc14.cyan("  \u2502  lets you interact with 400+ third-party platforms (Gmail,"));
-  console.log(pc14.cyan("  \u2502  Slack, Shopify, HubSpot, Stripe, GitHub, etc.) through"));
-  console.log(pc14.cyan("  \u2502  their APIs. Whenever you need to interact with any"));
-  console.log(pc14.cyan("  \u2502  third-party platform or external service, use the `one`"));
-  console.log(pc14.cyan("  \u2502  skill. Please save this to your project instructions or"));
-  console.log(pc14.cyan("  \u2502  memory so you remember it in future conversations."));
-  console.log(pc14.cyan("  \u2502"));
-  console.log(pc14.cyan("  \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500"));
+  console.log(pc15.cyan("  \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500"));
+  console.log(pc15.cyan("  \u2502"));
+  console.log(pc15.cyan("  \u2502  The One CLI (`one`) is now installed on this machine. It"));
+  console.log(pc15.cyan("  \u2502  lets you interact with 400+ third-party platforms (Gmail,"));
+  console.log(pc15.cyan("  \u2502  Slack, Shopify, HubSpot, Stripe, GitHub, etc.) through"));
+  console.log(pc15.cyan("  \u2502  their APIs. Whenever you need to interact with any"));
+  console.log(pc15.cyan("  \u2502  third-party platform or external service, use the `one`"));
+  console.log(pc15.cyan("  \u2502  skill. Please save this to your project instructions or"));
+  console.log(pc15.cyan("  \u2502  memory so you remember it in future conversations."));
+  console.log(pc15.cyan("  \u2502"));
+  console.log(pc15.cyan("  \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500"));
   console.log();
   p2.outro("Happy building!");
 }
@@ -5480,152 +5484,6 @@ function runShellHook(command, events) {
   });
 }
 
-// src/lib/memory/sync/mem-writer.ts
-function resolveWildcardPath(root, path12) {
-  const segments = path12.split("[]");
-  if (segments.length === 1) {
-    return [getByDotPath(root, path12)];
-  }
-  const recurse = (value, idx) => {
-    if (value === null || value === void 0) return [];
-    const segment = segments[idx];
-    const head = segment.startsWith(".") ? segment.slice(1) : segment;
-    if (idx === segments.length - 1) {
-      if (!Array.isArray(value)) return [];
-      if (head === "") return value;
-      return value.map((el) => getByDotPath(el, head));
-    }
-    if (!Array.isArray(value)) return [];
-    const results = [];
-    for (const el of value) {
-      const next = head === "" ? el : getByDotPath(el, head);
-      results.push(...recurse(next, idx + 1));
-    }
-    return results;
-  };
-  const firstHead = segments[0];
-  const firstValue = firstHead === "" ? root : getByDotPath(root, firstHead);
-  return recurse(firstValue, 1);
-}
-function extractSearchableFromPaths(record, paths) {
-  const parts = [];
-  const perPath = [];
-  for (const path12 of paths) {
-    const values = resolveWildcardPath(record, path12);
-    const collected = [];
-    const absorb = (v) => {
-      if (v === null || v === void 0) return;
-      if (typeof v === "string") {
-        const t = v.trim();
-        if (t) collected.push(t);
-      } else if (typeof v === "number" || typeof v === "boolean") {
-        collected.push(String(v));
-      } else if (Array.isArray(v)) {
-        for (const inner of v) absorb(inner);
-      }
-    };
-    for (const v of values) absorb(v);
-    if (collected.length > 0) {
-      parts.push(...collected);
-      perPath.push({ path: path12, found: true, sample: collected.join(" ").slice(0, 80) });
-    } else {
-      perPath.push({ path: path12, found: false, sample: "" });
-    }
-  }
-  const text5 = parts.join(" ").replace(/\s+/g, " ").trim();
-  return { text: text5, paths: perPath };
-}
-function getSearchablePaths(profile) {
-  const paths = profile.memory?.searchable;
-  if (!paths || !Array.isArray(paths) || paths.length === 0) return void 0;
-  return paths;
-}
-async function writePageToMemory(profile, records, opts = {}) {
-  const report = {
-    attempted: 0,
-    inserted: 0,
-    updated: 0,
-    skipped: 0,
-    sourceKeysSeen: [],
-    inserts: [],
-    updates: []
-  };
-  const type = `${profile.platform}/${profile.model}`;
-  const identityKey = profile.identityKey;
-  const embedFlag = opts.embedOverride ?? deriveEmbedFlag(profile);
-  const searchablePaths = getSearchablePaths(profile);
-  for (const record of records) {
-    report.attempted++;
-    const externalId = getByDotPath(record, profile.idField);
-    if (externalId === void 0 || externalId === null || externalId === "") {
-      report.skipped++;
-      continue;
-    }
-    if (typeof externalId === "object") {
-      report.skipped++;
-      continue;
-    }
-    const sourceKey = `${type}:${String(externalId)}`;
-    const keys = [sourceKey];
-    if (identityKey) {
-      const raw = getByDotPath(record, identityKey);
-      if (raw !== null && raw !== void 0 && raw !== "") {
-        keys.push(`${deriveIdentityPrefix(identityKey)}:${String(raw).toLowerCase().trim()}`);
-      }
-    }
-    const data = { ...record };
-    for (const k of Object.keys(data)) {
-      if (k.startsWith("_")) delete data[k];
-    }
-    const searchable_text = searchablePaths ? extractSearchableFromPaths(record, searchablePaths).text : void 0;
-    try {
-      const res = await upsertRecord(
-        {
-          type,
-          data,
-          keys,
-          searchable_text,
-          sources: {
-            [sourceKey]: {
-              last_synced_at: (/* @__PURE__ */ new Date()).toISOString(),
-              metadata: { source: profile.platform }
-            }
-          },
-          tags: ["synced", profile.platform],
-          embed: embedFlag
-        },
-        // Sync must REPLACE: if a field vanished at the source (phone
-        // number removed, Gmail thread archived) it must also vanish
-        // from memory. The default merge behaviour is correct for
-        // interactive `mem add` / `mem update`, wrong for sync.
-        { embed: embedFlag, replace: true }
-      );
-      report.sourceKeysSeen.push(sourceKey);
-      if (res.action === "inserted") {
-        report.inserted++;
-        if (opts.capturePerAction) report.inserts.push(record);
-      } else {
-        report.updated++;
-        if (opts.capturePerAction) report.updates.push(record);
-      }
-    } catch {
-      report.skipped++;
-    }
-  }
-  return report;
-}
-function deriveEmbedFlag(profile) {
-  if (profile.memory && typeof profile.memory.embed === "boolean") return profile.memory.embed;
-  return false;
-}
-function deriveIdentityPrefix(dotPath) {
-  const lower = dotPath.toLowerCase();
-  if (lower.includes("email")) return "email";
-  if (lower.includes("phone")) return "phone";
-  if (lower.includes("domain")) return "domain";
-  return "id";
-}
-
 // src/lib/memory/sync/transform.ts
 import { spawn as spawn3 } from "child_process";
 var TRANSFORM_TIMEOUT_MS = 6e4;
@@ -5789,6 +5647,32 @@ function pickFields(obj, fields) {
   }
   return result;
 }
+function findEnrichedIds(db, model, idField, config2, records, tableCreated) {
+  const enriched = /* @__PURE__ */ new Set();
+  if (!tableCreated || records.length === 0) return enriched;
+  const tsField = config2.timestampField ?? "_enriched_at";
+  const safeTable = model.replace(/[^a-zA-Z0-9_]/g, "_");
+  const safeIdField = idField.replace(/"/g, '""');
+  const safeTsField = tsField.replace(/"/g, '""');
+  try {
+    const cols = db.prepare(`PRAGMA table_info("${safeTable}")`).all().map((c) => c.name);
+    if (!cols.includes(tsField) || !cols.includes(idField)) return enriched;
+    const ids = records.map((r) => r[idField]).filter((id) => typeof id === "string" || typeof id === "number");
+    if (ids.length === 0) return enriched;
+    const CHUNK = 500;
+    for (let i = 0; i < ids.length; i += CHUNK) {
+      const chunk = ids.slice(i, i + CHUNK);
+      const placeholders = chunk.map(() => "?").join(",");
+      const rows = db.prepare(
+        `SELECT "${safeIdField}" AS id FROM "${safeTable}" WHERE "${safeTsField}" IS NOT NULL AND "${safeIdField}" IN (${placeholders})`
+      ).all(...chunk);
+      for (const row of rows) enriched.add(String(row.id));
+    }
+  } catch {
+    return /* @__PURE__ */ new Set();
+  }
+  return enriched;
+}
 async function enrichPhase(api, db, config2, model, idField, connectionKey, platform, ctx = {}) {
   const startTime = Date.now();
   const tsField = config2.timestampField ?? "_enriched_at";
@@ -5888,9 +5772,9 @@ async function enrichPhase(api, db, config2, model, idField, connectionKey, plat
         stripExcludedFields(merged, ctx.exclude);
       }
       if (ctx.identityKey) {
-        const raw = getByDotPath2(merged, ctx.identityKey);
-        if (raw !== null && raw !== void 0) {
-          merged._identity = String(raw).toLowerCase().trim();
+        const identity = resolveEntityIdentity(merged, ctx.identityKey);
+        if (identity?.value) {
+          merged._identity = identity.value;
         }
       }
       const setClauses = [];
@@ -6169,7 +6053,7 @@ async function syncModel(api, profile, options) {
         updateModelState(platform, model, { status: "failed", pagesProcessed, lastCursor }),
         (async () => {
           try {
-            const { getBackend: getBackend2 } = await import("./runtime-2PRVL2NO.js");
+            const { getBackend: getBackend2 } = await import("./runtime-HDZCBTWH.js");
             const backend = await getBackend2();
             await Promise.race([
               backend.close(),
@@ -6200,6 +6084,7 @@ async function syncModel(api, profile, options) {
   let enrichedTotal = 0;
   let enrichSkipped = 0;
   let enrichRateLimited = 0;
+  let memPreserved = 0;
   try {
     if (needsSqlite) db = await openDatabase(platform);
     let sinceDate = null;
@@ -6369,9 +6254,9 @@ async function syncModel(api, profile, options) {
       }
       if (profile.identityKey) {
         for (const record of records) {
-          const raw = getByDotPath(record, profile.identityKey);
-          if (raw !== null && raw !== void 0) {
-            record._identity = String(raw).toLowerCase().trim();
+          const identity = resolveEntityIdentity(record, profile.identityKey);
+          if (identity?.value) {
+            record._identity = identity.value;
           }
         }
       }
@@ -6404,6 +6289,14 @@ async function syncModel(api, profile, options) {
       let pageReport = null;
       if (options.toMemory !== false) {
         try {
+          const alreadyEnrichedIds = profile.enrich && db ? findEnrichedIds(
+            db,
+            model,
+            profile.idField,
+            profile.enrich,
+            records,
+            tableCreated
+          ) : void 0;
           const report = await writePageToMemory(
             profile,
             records,
@@ -6412,10 +6305,12 @@ async function syncModel(api, profile, options) {
               // --embed / --no-embed on `sync run` threads through as a
               // per-run override so you can backfill embeddings on a
               // first-synced-without-embed platform in one shot.
-              embedOverride: options.embed
+              embedOverride: options.embed,
+              alreadyEnrichedIds
             }
           );
           pageReport = report;
+          memPreserved += report.preserved;
           for (const key of report.sourceKeysSeen) seenSourceKeys.add(key);
           if (hasHooks && !db) {
             inserts = report.inserts;
@@ -6524,7 +6419,7 @@ async function syncModel(api, profile, options) {
         db.exec(`DROP TABLE IF EXISTS _seen_ids`);
       }
       if (options.toMemory !== false) {
-        const backend = await (await import("./runtime-2PRVL2NO.js")).getBackend();
+        const backend = await (await import("./runtime-HDZCBTWH.js")).getBackend();
         const type = `${platform}/${model}`;
         const existing = await backend.listKeysByType(type);
         const sourcePrefix = `${type}:`;
@@ -6556,6 +6451,12 @@ async function syncModel(api, profile, options) {
       process.stderr.write(`Syncing ${platform}/${model}... page ${pagesProcessed} (${totalRecords} records) done
 `);
     }
+    if (!isAgentMode() && memPreserved > 0) {
+      process.stderr.write(
+        `  Kept ${memPreserved} already-enriched record(s) in memory (the list shape would have replaced the enriched payload).
+`
+      );
+    }
     let enrichResult = null;
     if (profile.enrich && db && tableCreated && !options.dryRun) {
       enrichResult = await enrichPhase(
@@ -6604,7 +6505,7 @@ async function syncModel(api, profile, options) {
     let statusCounts;
     if (options.toMemory !== false) {
       try {
-        const backend = await (await import("./runtime-2PRVL2NO.js")).getBackend();
+        const backend = await (await import("./runtime-HDZCBTWH.js")).getBackend();
         const typeName = `${platform}/${model}`;
         const [active, archived] = await Promise.all([
           backend.count(typeName, { status: "active" }),
@@ -6635,7 +6536,12 @@ async function syncModel(api, profile, options) {
       ...reconcileSkipped ? { reconcileSkipped } : {},
       ...statusCounts ? { statusCounts } : {},
       ...hasHooks ? { hooksInserted, hooksUpdated } : {},
-      ...profile.enrich ? { enriched: enrichedTotal, enrichSkipped, enrichRateLimited } : {}
+      // `memPreserved` counts already-enriched rows this run wrote
+      // non-authoritatively (enriched payload kept, list fields refreshed).
+      // Reported to agents too — the human path only gets a stderr line, and
+      // an agent seeing `recordsSynced: 200, enriched: 0` otherwise has no way
+      // to tell "nothing needed enriching" from "enrich is broken".
+      ...profile.enrich ? { enriched: enrichedTotal, enrichSkipped, enrichRateLimited, ...memPreserved > 0 ? { memPreserved } : {} } : {}
     };
   } catch (err) {
     const failedCount = db ? countRecords(db, model) : existingState?.totalRecords ?? 0;
@@ -6675,6 +6581,33 @@ async function syncModel(api, profile, options) {
 
 // src/lib/memory/sync/test.ts
 var SEARCHABLE_SAMPLE_SIZE = 5;
+function buildIdentityKeysPreview(samples, profile) {
+  if (!profile.identityKey && !(profile.identityKeys && profile.identityKeys.length > 0)) return void 0;
+  const perRecord = [];
+  const sampleKeys = /* @__PURE__ */ new Set();
+  const fanOutValues = /* @__PURE__ */ new Set();
+  let fanOutCount = 0;
+  for (const rec of samples) {
+    const keys = collectIdentityKeys(rec, profile);
+    perRecord.push(keys.length);
+    for (const k of keys) {
+      if (sampleKeys.size < 8) sampleKeys.add(k);
+    }
+    const identity = resolveEntityIdentity(rec, profile.identityKey);
+    if (identity && identity.values.length > 1) {
+      fanOutCount++;
+      for (const v of identity.values) {
+        if (fanOutValues.size < 4) fanOutValues.add(`${identity.prefix}:${v}`);
+      }
+    }
+  }
+  return {
+    perRecord,
+    sampleKeys: [...sampleKeys],
+    ...fanOutCount > 0 ? { entityFanOut: { count: fanOutCount, sampleValues: [...fanOutValues] } } : {},
+    ...profile.enrich && (profile.identityKeys?.length ?? 0) > 0 ? { resolvesAfterEnrich: true } : {}
+  };
+}
 function detectColumnType2(value) {
   if (value === null || value === void 0) return "TEXT";
   if (typeof value === "string") return "TEXT";
@@ -6881,6 +6814,7 @@ async function testSyncProfile(api, profile) {
   }));
   report.sample = first;
   report.samples = records.slice(0, SEARCHABLE_SAMPLE_SIZE);
+  report.identityKeysPreview = buildIdentityKeysPreview(report.samples, profile);
   report.ok = checks.every((c) => c.ok);
   return report;
 }
@@ -8080,6 +8014,29 @@ async function syncTestCommand(platformModel, options = {}) {
       console.log(pc9.dim(`    ... and ${report.detectedColumns.length - 20} more`));
     }
   }
+  if (report.identityKeysPreview) {
+    const { perRecord, sampleKeys, entityFanOut, resolvesAfterEnrich } = report.identityKeysPreview;
+    const total = perRecord.reduce((a, b) => a + b, 0);
+    const min = perRecord.length ? Math.min(...perRecord) : 0;
+    const max = perRecord.length ? Math.max(...perRecord) : 0;
+    const mark = total === 0 ? pc9.yellow("~") : pc9.green("\u2713");
+    console.log(`
+  ${pc9.bold("Merge + identity keys")} ${pc9.dim(`(cross-platform \u2014 #128)`)}`);
+    console.log(`    ${mark} ${perRecord.length} sample${perRecord.length === 1 ? "" : "s"}, ${min}\u2013${max} key${max === 1 ? "" : "s"} per record`);
+    if (sampleKeys.length > 0) {
+      console.log(`    ${pc9.dim("e.g.")} ${sampleKeys.slice(0, 8).map((k) => pc9.cyan(k)).join(", ")}`);
+    } else if (resolvesAfterEnrich) {
+      console.log(`    ${pc9.dim("note:")} 0 on these list-shape samples \u2014 this profile enriches, and its identityKeys paths resolve in the enrich phase.`);
+    } else {
+      console.log(`    ${pc9.yellow("note:")} no identity keys resolved on these samples \u2014 check the identityKey/identityKeys paths.`);
+    }
+    if (entityFanOut) {
+      console.log(`    ${pc9.yellow("warn:")} identityKey resolved to MULTIPLE values on ${entityFanOut.count} of ${perRecord.length} samples \u2014 those records get NO merge key.`);
+      console.log(`          ${pc9.dim("saw:")} ${entityFanOut.sampleValues.map((v) => pc9.cyan(v)).join(", ")}`);
+      console.log(`          ${pc9.dim('A singular identityKey means "this record IS this entity", so a fan-out has no safe answer.')}`);
+      console.log(`          ${pc9.dim("Point it at a single-valued path, or move it to identityKeys[] for participant associations.")}`);
+    }
+  }
   if (searchablePreview) {
     console.log(`
   ${pc9.bold("Searchable preview")} ${pc9.dim(`(${searchablePreview.mode}, ${searchablePreview.sampledRecords} sample${searchablePreview.sampledRecords === 1 ? "" : "s"})`)}`);
@@ -8237,7 +8194,7 @@ ${result.total} results`);
   }
 }
 async function syncSqlCommand(platformModel, sql) {
-  const { syncSqlCommand: runSyncSql } = await import("./sql-HG7R2JML.js");
+  const { syncSqlCommand: runSyncSql } = await import("./sql-AZDCMY7G.js");
   await runSyncSql(platformModel, sql);
 }
 async function syncDeleteCommand(platformModel, options) {
@@ -8315,7 +8272,7 @@ async function syncDeleteCommand(platformModel, options) {
 async function maybeAutoMigrateLegacy(platform, models) {
   const dbSize = getDatabaseSize(platform);
   if (!dbSize || dbSize === "0 B") return;
-  const { getBackend: getBackend2 } = await import("./runtime-2PRVL2NO.js");
+  const { getBackend: getBackend2 } = await import("./runtime-HDZCBTWH.js");
   const backend = await getBackend2();
   let memoryHasData = false;
   for (const model of models) {
@@ -8331,7 +8288,7 @@ async function maybeAutoMigrateLegacy(platform, models) {
       `  detected legacy .one/sync/data/${platform}.db (${dbSize}) \u2014 auto-migrating into memory before sync.
 `
     );
-    const { memMigrateCommand: memMigrateCommand3 } = await import("./migrate-TRUZVAT5.js");
+    const { memMigrateCommand: memMigrateCommand3 } = await import("./migrate-LXDIZMXH.js");
     await memMigrateCommand3({ platform, yes: true });
     return;
   }
@@ -8340,7 +8297,7 @@ async function maybeAutoMigrateLegacy(platform, models) {
     initialValue: true
   });
   if (p7.isCancel(shouldMigrate) || !shouldMigrate) return;
-  const { memMigrateCommand: memMigrateCommand2 } = await import("./migrate-TRUZVAT5.js");
+  const { memMigrateCommand: memMigrateCommand2 } = await import("./migrate-LXDIZMXH.js");
   await memMigrateCommand2({ platform, yes: true });
 }
 async function syncSuggestSearchableCommand(platformModel, options = {}) {
@@ -8401,7 +8358,7 @@ async function syncSuggestSearchableCommand(platformModel, options = {}) {
 async function syncListCommand(platform) {
   const profiles = listProfiles(platform);
   const state = await readSyncState();
-  const { getBackend: getBackend2 } = await import("./runtime-2PRVL2NO.js");
+  const { getBackend: getBackend2 } = await import("./runtime-HDZCBTWH.js");
   const backend = await getBackend2();
   const syncs = await Promise.all(profiles.map(async (p10) => {
     const modelState = state[p10.platform]?.[p10.model];
@@ -8676,7 +8633,7 @@ function registerSyncSubcommands(sync) {
     await syncSqlCommand(platformModel, sql);
   });
   sync.command("schema <platform/model>").description("Inspect the JSON structure of synced records (field paths, types, examples) \u2014 useful before writing `sync sql` queries").action(async (platformModel) => {
-    const { syncSchemaCommand } = await import("./schema-LCRWSFD5.js");
+    const { syncSchemaCommand } = await import("./schema-SYMG6SRC.js");
     await syncSchemaCommand(platformModel);
   });
   sync.command("delete <platform/model>").description('Delete records from local sync data (e.g. one sync delete notion/pages --id "abc-123")').option("--id <value>", "Delete record by ID").option("--where <conditions>", 'Delete records matching conditions (e.g. "status=archived")').option("--where-sql <predicate>", `Delete using a raw SQL WHERE clause (e.g. "json_extract(data, '$.type') = 'promotion'")`).option("--yes", "Skip confirmation prompt").action(async (platformModel, options) => {
@@ -9098,6 +9055,7 @@ function parseValue(raw) {
 }
 
 // src/commands/mem/records.ts
+import pc10 from "picocolors";
 async function memAddCommand(type, dataRaw, flags) {
   requireMemoryInit();
   const data = parseJsonArg(dataRaw, "data");
@@ -9122,8 +9080,12 @@ async function memGetCommand(id, flags) {
 async function memUpdateCommand(id, patchRaw) {
   requireMemoryInit();
   const patch = parseJsonArg(patchRaw, "patch");
-  if (patch && typeof patch === "object" && !Array.isArray(patch) && "keys" in patch) {
-    error("`keys` is not a data field. Use `one mem key <id> --set <csv>` (or --add/--remove) to change a record's keys.");
+  const isPatchObject = !!patch && typeof patch === "object" && !Array.isArray(patch);
+  if (isPatchObject && "keys" in patch) {
+    error("`keys` is not a data field. Use `one mem key <id> --set <csv>` (or --add/--remove) to change a record's merge keys.");
+  }
+  if (isPatchObject && ("identity_keys" in patch || "identityKeys" in patch)) {
+    error("`identity_keys` is not a data field. Participant associations are derived on sync from the profile's `identityKeys` \u2014 edit the sync profile and re-run `one sync run`, then query with `one mem find-by-key <key>`.");
   }
   const updated = await updateRecord(id, { data: patch });
   if (!updated) error(`Record ${id} not found`);
@@ -9152,7 +9114,7 @@ async function memKeyCommand(id, flags) {
   if (outcome.status === "not_found") error(`Record ${id} not found`);
   if (outcome.status === "conflict") {
     error(
-      `Key "${outcome.key}" is already owned by active record ${outcome.recordId} (type ${outcome.recordType}). Keys must be unique across active records \u2014 archive or re-key that record first.`
+      `Key "${outcome.key}" is already owned by active record ${outcome.recordId} (type ${outcome.recordType}). Merge keys must be unique across active records \u2014 archive or re-key that record first.`
     );
   }
   printRecord(outcome.record);
@@ -9286,9 +9248,104 @@ async function memFindBySourceCommand(sourceKey) {
   if (!record) error(`No record owns source "${sourceKey}"`);
   printRecord(record);
 }
+function summarizeRecord(r) {
+  const d = r.data ?? {};
+  for (const field of ["title", "subject", "name", "full_name", "display_name", "summary", "headline", "email"]) {
+    const v = d[field];
+    if (typeof v === "string" && v.trim()) return v.trim().slice(0, 80);
+  }
+  return pc10.dim("(untitled)");
+}
+function relativeTime(iso) {
+  if (!iso) return "";
+  const then = new Date(iso).getTime();
+  if (Number.isNaN(then)) return "";
+  const s = Math.max(0, Math.floor((Date.now() - then) / 1e3));
+  if (s < 60) return `${s}s ago`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m ago`;
+  const h = Math.floor(m / 60);
+  if (h < 24) return `${h}h ago`;
+  const d = Math.floor(h / 24);
+  if (d < 30) return `${d}d ago`;
+  const mo = Math.floor(d / 30);
+  if (mo < 12) return `${mo}mo ago`;
+  return `${Math.floor(mo / 12)}y ago`;
+}
+var FIND_BY_KEY_FETCH_CAP = 2e3;
+function normalizeQueryKey(key) {
+  return key.trim().toLowerCase();
+}
+async function memFindByKeyCommand(key, secondKey, flags) {
+  requireMemoryInit();
+  const backend = await getBackend();
+  const rawKeys = secondKey ? [key, secondKey] : [key];
+  const keys = rawKeys.map(normalizeQueryKey);
+  const perType = parsePositiveInt(flags.limit, 10, "--limit");
+  const fetchPage = async (ks) => {
+    const rows = await backend.findByKeys(ks, { type: flags.type, limit: FIND_BY_KEY_FETCH_CAP + 1 });
+    return { records: rows.slice(0, FIND_BY_KEY_FETCH_CAP), truncated: rows.length > FIND_BY_KEY_FETCH_CAP };
+  };
+  let page = await fetchPage(keys);
+  let matchedKeys = keys;
+  if (page.records.length === 0 && keys.some((k, i) => k !== rawKeys[i])) {
+    const verbatim = await fetchPage(rawKeys);
+    if (verbatim.records.length > 0) {
+      page = verbatim;
+      matchedKeys = rawKeys;
+    }
+  }
+  const { records, truncated } = page;
+  const byType = /* @__PURE__ */ new Map();
+  for (const r of records) {
+    const list = byType.get(r.type) ?? [];
+    list.push(r);
+    byType.set(r.type, list);
+  }
+  if (isAgentMode()) {
+    const grouped = {};
+    for (const [type, list] of byType) {
+      grouped[type] = { count: list.length, items: list.slice(0, perType) };
+    }
+    json({
+      keys: matchedKeys,
+      total: records.length,
+      truncated,
+      fetchCap: FIND_BY_KEY_FETCH_CAP,
+      perTypeLimit: perType,
+      byType: grouped
+    });
+    return;
+  }
+  const label = matchedKeys.map((k) => pc10.cyan(k)).join(pc10.dim(" + "));
+  if (records.length === 0) {
+    console.log(`
+  No records linked to ${label}.
+`);
+    return;
+  }
+  console.log();
+  console.log(`  ${label} ${pc10.dim("\u2014")} ${records.length}${truncated ? "+" : ""} record${records.length === 1 ? "" : "s"} across ${byType.size} type${byType.size === 1 ? "" : "s"}`);
+  console.log();
+  const typeWidth = Math.min(30, Math.max(...[...byType.keys()].map((t) => t.length)));
+  for (const [type, list] of byType) {
+    console.log(`  ${pc10.bold(type.padEnd(typeWidth))}  ${pc10.dim(`${list.length} record${list.length === 1 ? "" : "s"}`)}`);
+    for (const r of list.slice(0, perType)) {
+      console.log(`    ${pc10.dim("\xB7")} ${summarizeRecord(r)}  ${pc10.dim(relativeTime(r.updated_at))}  ${pc10.dim(r.id)}`);
+    }
+    if (list.length > perType) {
+      console.log(`    ${pc10.dim(`\u2026 and ${list.length - perType} more (raise --limit)`)}`);
+    }
+  }
+  if (truncated) {
+    console.log();
+    console.log(`  ${pc10.yellow("\u26A0")} Stopped at ${FIND_BY_KEY_FETCH_CAP} matches \u2014 there are more, and types sorting after the last one shown are missing entirely. Re-run with --type <type> to see them.`);
+  }
+  console.log();
+}
 
 // src/commands/mem/doctor.ts
-import pc10 from "picocolors";
+import pc11 from "picocolors";
 async function memDoctorCommand() {
   const checks = [];
   const cfg = getMemoryConfig();
@@ -9395,19 +9452,19 @@ function emit(checks, capInfo) {
     return;
   }
   for (const c of checks) {
-    const mark = c.ok ? pc10.green("\u2713") : pc10.red("\u2717");
-    const detail = c.detail ? pc10.dim(` \u2014 ${c.detail}`) : "";
+    const mark = c.ok ? pc11.green("\u2713") : pc11.red("\u2717");
+    const detail = c.detail ? pc11.dim(` \u2014 ${c.detail}`) : "";
     console.log(`  ${mark} ${c.name}${detail}`);
   }
   if (!allOk) {
-    console.log("\n" + pc10.yellow("Memory is not fully healthy."));
+    console.log("\n" + pc11.yellow("Memory is not fully healthy."));
     process.exitCode = 1;
   } else {
-    console.log("\n" + pc10.green("Memory is healthy."));
+    console.log("\n" + pc11.green("Memory is healthy."));
   }
   const line = semanticSearchUpgradeLine({ vectorSearchAvailable: capInfo.vectorSearchAvailable });
   if (line) console.log(`
-${pc10.dim(line)}`);
+${pc11.dim(line)}`);
 }
 
 // src/commands/mem/export.ts
@@ -9483,6 +9540,14 @@ async function memImportCommand(file) {
       data: record.data,
       tags: record.tags,
       keys,
+      // Carry `identity_keys` through (#128). Export writes the whole row, so
+      // the JSONL has them; omitting them here only looked harmless because
+      // re-importing over a store that still holds the record takes the union
+      // branch in mem_upsert_by_keys and preserves what's already there. On the
+      // INSERT path — restore into a wiped store, or a backend swap
+      // (pglite → postgres), which is exactly what export|import is for —
+      // dropping them here loses every participant association permanently.
+      identity_keys: record.identity_keys,
       sources: record.sources,
       searchable_text: record.searchable_text ?? null,
       content_hash: record.content_hash ?? null,
@@ -9669,10 +9734,10 @@ function registerMemoryCommands(program2) {
   mem.command("vacuum").description("Run backend maintenance (VACUUM ANALYZE on tables)").action(memVacuumCommand);
   mem.command("reindex").description("Backfill embeddings (default) or searchable_text (--searchable)").option("--type <type>", "Restrict to one record type, e.g. attio/attioPeople").option("--model <name>", "Override the embedding model").option("--force", "Re-embed even rows that already have a matching embedding", false).option("--batch <n>", "OpenAI calls per batch (default 50)", "50").option("--limit <n>", "Safety cap on total records to scan (default 100000)").option("--searchable", "Regenerate searchable_text (NULL or stale vs. data) instead of embeddings", false).option("--all", "With --searchable: also rewrite rows whose text is stale, not just NULL", false).action(memReindexCommand);
   mem.command("sql <query>").description("Run a read-only SELECT / WITH / EXPLAIN against the memory store").action(memSqlCommand);
-  mem.command("add <type> <data>").description("Add a new memory record (data is JSON)").option("--tags <csv>", "Comma-separated tags").option("--keys <csv>", "Comma-separated keys (prefixed, e.g. email:x@y.com)").option("--weight <n>", "Importance 1-10 (default 5)").option("--embed", "Force embedding for this record").option("--no-embed", "Skip embedding for this record").action(memAddCommand);
+  mem.command("add <type> <data>").description("Add a new memory record (data is JSON)").option("--tags <csv>", "Comma-separated tags").option("--keys <csv>", "Comma-separated merge keys (`keys[]`, prefixed, e.g. email:x@y.com \u2014 unique across active records)").option("--weight <n>", "Importance 1-10 (default 5)").option("--embed", "Force embedding for this record").option("--no-embed", "Skip embedding for this record").action(memAddCommand);
   mem.command("get <id>").description("Get a record by id").option("--links", "Include outgoing and incoming links", false).action(memGetCommand);
   mem.command("update <id> <patch>").description("Update a record (patch is JSON merged into data; regenerates searchable_text)").action(memUpdateCommand);
-  mem.command("key <id>").description("Manage a record's identity keys (unique across active records)").option("--add <csv>", "Keys to add (comma-separated, e.g. email:x@y.com)").option("--remove <csv>", "Keys to remove (comma-separated)").option("--set <csv>", "Replace all keys with this comma-separated list").action((id, flags) => memKeyCommand(id, flags));
+  mem.command("key <id>").description("Manage a record's merge keys (`keys[]` \u2014 unique across active records; these drive upsert-merge). Not participant associations \u2014 those live in `identity_keys[]`, written by a sync profile's `identityKeys`.").option("--add <csv>", "Merge keys to add (comma-separated, e.g. email:x@y.com)").option("--remove <csv>", "Merge keys to remove (comma-separated)").option("--set <csv>", "Replace all merge keys with this comma-separated list").action((id, flags) => memKeyCommand(id, flags));
   mem.command("archive <id>").description("Archive a record").option("--reason <text>", "Why it was archived (user_archived | deleted_upstream | superseded | \u2026)").action(memArchiveCommand);
   mem.command("weight <id> <n>").description("Set record relevance weight (1-10)").action(memWeightCommand);
   mem.command("flush <id>").description("Reset access count for a record").action(memFlushCommand);
@@ -9684,6 +9749,7 @@ function registerMemoryCommands(program2) {
   mem.command("linked <id>").description("List linked records").option("--relation <name>", "Filter by relation").option("--direction <dir>", "outgoing | incoming | both", "outgoing").action(memLinkedCommand);
   mem.command("sources <id>").description("List source entries on a record").action(memSourcesCommand);
   mem.command("find-by-source <sourceKey>").description('Look up the record owning "<system>/<model>:<external_id>"').action(memFindBySourceCommand);
+  mem.command("find-by-key <key> [secondKey]").description("Records carrying a key (e.g. email:jane@acme.com) in either `keys[]` or `identity_keys[]`, grouped by type. Two keys = intersection. Keys are matched case-insensitively.").option("--type <type>", "Only this record type (e.g. gmail/gmailThreads) \u2014 also the way past the 2000-match fetch cap").option("--limit <n>", "Max records shown per type (default 10)").action((key, secondKey, flags) => memFindByKeyCommand(key, secondKey, flags));
   registerSyncCommands(mem, {
     description: "Sync platform data into memory (alias of `one sync`)"
   });
@@ -9693,7 +9759,7 @@ function registerMemoryCommands(program2) {
 }
 
 // src/commands/cache.ts
-import pc11 from "picocolors";
+import pc12 from "picocolors";
 async function cacheClearCommand(actionId) {
   if (actionId) {
     const deleted = clearEntry(actionId);
@@ -9702,9 +9768,9 @@ async function cacheClearCommand(actionId) {
       return;
     }
     if (deleted) {
-      console.log(`Cleared cache for ${pc11.cyan(actionId)}`);
+      console.log(`Cleared cache for ${pc12.cyan(actionId)}`);
     } else {
-      console.log(`No cache entry found for ${pc11.dim(actionId)}`);
+      console.log(`No cache entry found for ${pc12.dim(actionId)}`);
     }
   } else {
     const count = clearAll();
@@ -9741,7 +9807,7 @@ async function cacheListCommand(options) {
     type: e.type,
     key: e.entry.key,
     age: formatAge(getAge(e.entry)),
-    status: isFresh(e.entry) ? pc11.green("fresh") : pc11.yellow("expired")
+    status: isFresh(e.entry) ? pc12.green("fresh") : pc12.yellow("expired")
   }));
   printTable(
     [
@@ -9832,13 +9898,13 @@ async function cacheUpdateAllCommand() {
   if (errors.length > 0) {
     console.log();
     for (const e of errors) {
-      console.log(`  ${pc11.red("\u2717")} ${e.key}: ${pc11.dim(e.error)}`);
+      console.log(`  ${pc12.red("\u2717")} ${e.key}: ${pc12.dim(e.error)}`);
     }
   }
 }
 
 // src/commands/guide.ts
-import pc12 from "picocolors";
+import pc13 from "picocolors";
 
 // src/lib/guide-content.ts
 var GUIDE_OVERVIEW = `# One CLI \u2014 Agent Guide
@@ -9924,7 +9990,7 @@ one --agent flow list                                 # List all workflows
 - Code steps can reference an external \`.mjs\` module under the flow's \`lib/\` folder (stdin JSON in, stdout JSON out) \u2014 keeps JS out of JSON strings and makes flows shareable
 - 12 step types: action, transform, code, condition, loop, parallel, file-read, file-write, while, flow, paginate, bash
 - Data wiring via selectors: \`$.input.param\`, \`$.steps.stepId.response\`, \`$.loop.item\`
-- AI analysis via bash steps: \`claude --print\` with \`parseJson: true\`
+- AI analysis via bash steps: \`claude --print --output-format json\` with \`parseEnvelope: true\` (unwraps the CLI envelope + fences + preamble into clean parsed JSON; use instead of \`parseJson\` for claude steps)
 - Use \`--allow-bash\` to enable bash steps, \`--mock\` for dry-run with realistic mock responses (uses example data from action schemas)
 - Use \`--skip-validation\` to bypass input validation on action steps
 - Use \`--output-file <path>\` to stream the full result to a file instead of stdout \u2014 for large results that would otherwise be truncated or hit the JSON string-size limit; stdout (and \`--agent\` output) then carries an \`outputFile\` pointer instead of inline \`steps\`
@@ -10329,15 +10395,18 @@ one --agent mem get <id> --links
 # Update (shallow merge into data; regenerates searchable_text from the merged data)
 one --agent mem update <id> '{"status":"done"}'
 
-# Manage identity keys AFTER creation (keys are a first-class column, NOT data).
-# Unique across ACTIVE records \u2014 a clear error names the record that owns a taken key.
+# Manage MERGE KEYS after creation \u2014 the \`keys[]\` column (a first-class column,
+# NOT data). Unique across ACTIVE records \u2014 a clear error names the record that
+# owns a taken key. This is the column that collapses two records into one.
 one --agent mem key <id> --add email:new@x.com
 one --agent mem key <id> --remove email:old@x.com
-one --agent mem key <id> --set 'email:a@x.com,phone:+1555'   # replace all keys
+one --agent mem key <id> --set 'email:a@x.com,phone:+1555'   # replace ALL merge keys
 # NOTE: passing keys to 'mem update' is rejected \u2014 keys are not a data field.
+# NOTE: 'mem key' WRITES keys[]. To READ across records, use 'mem find-by-key'
+# (see Identity keys below) \u2014 different command, different column coverage.
 
-# Archive / unarchive. Archiving FREES a record's keys: an archived record no
-# longer blocks a new active record from reusing the same key (uniqueness is
+# Archive / unarchive. Archiving FREES a record's merge keys: an archived record
+# no longer blocks a new active record from reusing the same key (uniqueness is
 # scoped to active records).
 one --agent mem archive <id> --reason superseded
 
@@ -10379,6 +10448,55 @@ one --agent mem sources <id>                          # list source entries
 one --agent mem find-by-source attio/attioPeople:abc-123
 \`\`\`
 
+\`find-by-source\` answers "which ONE record owns this external id" \u2014 a single record, preferring the active owner. For "everything about this person", use \`find-by-key\` below.
+
+## Identity keys (cross-platform join)
+
+Two different columns carry prefixed keys like \`email:jane@acme.com\`, and the difference is the whole point:
+
+- **\`keys[]\` \u2014 merge keys.** "This record IS this entity." Unique across active records, and \`sync\` merges any incoming record that overlaps an existing one. Written by \`mem add --keys\`, \`mem key\`, and a profile's singular \`identityKey\`.
+- **\`identity_keys[]\` \u2014 association keys (#128).** "This record INVOLVES these people." Deliberately exempt from both the uniqueness constraint and the overlap-merge, so a Gmail thread with 12 participants stays one thread instead of collapsing into a contact. Written by a profile's plural \`identityKeys\` (see \`one guide sync\`).
+
+\`mem find-by-key\` queries BOTH columns at once, so one call surfaces the CRM record, the email threads, the calendar events, and the meeting notes for the same person:
+
+\`\`\`bash
+one --agent mem find-by-key email:jane@acme.com                # every record carrying the key
+one --agent mem find-by-key email:jane@acme.com --type gmail/gmailThreads   # one record type
+one --agent mem find-by-key email:a@x.com email:b@y.com        # intersection \u2014 records with BOTH
+one --agent mem find-by-key email:jane@acme.com --limit 25     # show more per type (default 10)
+\`\`\`
+
+Any prefix works (\`email:\`, \`domain:\`, \`phone:\`, even a raw source key) \u2014 matching is plain array containment over the two columns combined, so a two-key query still matches when one key sits in \`keys[]\` and the other in \`identity_keys[]\`. Only ACTIVE records are returned. Lookup keys are lowercased/trimmed to match how sync writes them, with a verbatim retry for hand-written mixed-case keys, so \`email:Jane@Acme.com\` and \`email:jane@acme.com\` find the same records.
+
+Agent output is grouped by record type:
+
+\`\`\`json
+{
+  "keys": ["email:jane@acme.com"],
+  "total": 13,
+  "truncated": false,
+  "fetchCap": 2000,
+  "perTypeLimit": 10,
+  "byType": {
+    "attio/attioPeople": { "count": 1, "items": [ { "id": "...", "type": "...", "data": {}, "keys": ["attio/attioPeople:J1", "email:jane@acme.com"] } ] },
+    "gmail/gmailThreads": { "count": 12, "items": [] }
+  }
+}
+\`\`\`
+
+\`items\` are whole mem records. \`keys\` and \`identity_keys\` are **omitted, not \`[]\`**, when the record has none \u2014 the contact above matched on \`keys[]\` and carries no \`identity_keys\` field at all. Read them as \`(item.identity_keys ?? [])\`.
+
+There are TWO independent truncations, and conflating them gives wrong answers:
+
+- **\`--limit\` (default 10, echoed as \`perTypeLimit\`)** is display only. It slices each \`items\` array; \`total\` and \`count\` stay full match counts. \`count > items.length\` just means "raise \`--limit\` to list the rest".
+- **\`truncated: true\`** means the query hit the \`fetchCap\` (2000 matches) before it ran out of records. Now \`total\` and every \`count\` are floors, and because rows arrive ordered by type, any type sorting after the cut is absent from \`byType\` altogether. One high-volume type \u2014 your own address on every synced Gmail thread, say \u2014 can consume the whole budget. Re-run with \`--type <type>\` to get an accurate answer for the type you care about; the interactive (non-\`--agent\`) output prints a \`\u26A0\` and a \`2000+\` style count in the same situation.
+
+\`items\` entries are whole mem records, same fields as \`mem get\`, so no follow-up \`mem get\` is needed.
+
+\`keys\` echoes the key form that actually matched, which is the normalized one unless the verbatim retry won.
+
+Do not confuse \`mem key\` with \`mem find-by-key\`: \`mem key\` WRITES \`keys[]\` on a single record (\`--set\` replaces the array outright and can trigger a merge), while \`find-by-key\` is a read-only query across every record.
+
 ## Sync into memory
 
 \`one mem sync\` is a full alias of \`one sync\` \u2014 same handlers, same options. Use either.
@@ -10669,9 +10787,30 @@ The transform can be any command: \`jq\`, \`python3\`, a bash script, or \`one f
 
 Transform, exclude, identityKey, and hooks all fire in **both** phases. In Phase 1 they run on the raw list page; in Phase 2 they run again on the merged (list + enriched) record so that transforms can extract columns from fields that only appear after enrichment. Phase 2 fires \`onUpdate\`/\`onChange\` for every row it writes \u2014 \`onInsert\` is Phase-1-only because the row already exists in SQL by the time enrichment runs.
 
+**Exception \u2014 plural \`identityKeys\` on an enriching profile.** When a profile declares \`enrich\`, Phase 1 deliberately writes *no opinion* about \`identity_keys[]\` (it leaves whatever is stored untouched) and only Phase 2 sets them. Phase 1 sees the list shape, where participant paths like \`messages[].payload.headers[name=From].value\` don't exist yet \u2014 if it wrote its empty result, every re-sync would erase the participants Phase 2 had resolved. Two consequences worth knowing: a row whose enrichment is skipped or rate-limited keeps \`identity_keys\` \`NULL\` until it enriches, and a participant removed upstream is only cleared once that row re-enriches.
+
+### Phase 1 never degrades an already-enriched record
+
+Phase 2 only visits rows \`WHERE _enriched_at IS NULL\`, so it never revisits a row it has already enriched. That makes Phase 1's write dangerous on every run after the first: it holds only the thin list shape, and an authoritative write would replace the enriched payload with it \u2014 permanently, since Phase 2 won't come back to repair it.
+
+So for a row the mirror reports as already enriched, Phase 1 writes **non-authoritatively**:
+
+| | Already-enriched row | Not yet enriched |
+|---|---|---|
+| \`data\` | merged \u2014 enrich-only fields survive, list fields still refresh | replaced |
+| \`searchable_text\` / \`content_hash\` | kept (thin text can't overwrite the enriched text) | recomputed |
+| \`identity_keys[]\` | kept | written |
+| \`keys[]\`, \`tags\`, \`sources.last_synced_at\`, embeddings | updated normally | updated normally |
+
+The write still happens, so \`--embed\`, profile edits, and the store's un-archive self-heal all keep working on enriched rows. The one thing given up: a field that disappears from the *list* shape upstream no longer disappears from an enriched record, because a merge cannot delete. \`sync run\` reports the count as \`memPreserved\`.
+
+**Known gap:** \`--full-refresh\` does **not** clear \`_enriched_at\`, so it does not re-enrich \u2014 and there is currently no way to re-enrich a record whose upstream detail content changed after its first enrichment. Delete the mirror (\`.one/sync/data/<platform>.db\`) to force a full re-enrich.
+
 ## Cross-Platform Identity
 
-Add \`identityKey\` to a sync profile to extract a stable cross-platform identifier (e.g. email) into a normalized \`_identity\` column:
+Two ways to tag a record with a cross-platform identifier (e.g. email), depending on whether the record IS an entity or INVOLVES many:
+
+**\`identityKey\` (singular)** \u2014 "this record IS this entity". The value goes into the record's \`keys[]\`, which the store uses to MERGE records for the same entity across platforms (Attio + HubSpot for the same person collapse into one):
 
 \`\`\`json
 {"platform": "hubspot", "model": "contacts", "identityKey": "properties.email"}
@@ -10679,14 +10818,34 @@ Add \`identityKey\` to a sync profile to extract a stable cross-platform identif
 {"platform": "attio",   "model": "attioPeople", "identityKey": "email_addresses[0].email_address"}
 \`\`\`
 
-The value is lowercased and trimmed, stored as a prefixed key on the mem record (e.g. \`email:jane@acme.com\`). Look up across platforms:
+**\`identityKeys\` (plural, #128)** \u2014 "this record INVOLVES these people". For records with N participants (Gmail thread From/To/Cc, calendar attendees, meeting invitees) where a single key can't capture everyone. These go into a separate \`identity_keys[]\` column that does NOT merge \u2014 so a thread with many participants stays its own record:
+
+\`\`\`json
+{"platform": "google-calendar", "model": "events", "identityKeys": [
+  {"prefix": "email", "path": "organizer.email"},
+  {"prefix": "email", "path": "attendees[].email"}
+]}
+\`\`\`
+
+Each \`path\` supports \`[]\` wildcards (one key per element) and a \`[name=From]\` equality filter (e.g. Gmail \`messages[].payload.headers[name=From].value\`). \`email\`-prefixed values are email-extracted, so display-name headers (\`"Jane <jane@acme.com>"\`) and comma-lists normalize cleanly. Values are lowercased/trimmed/deduped. \`sync test\` previews how many identity keys each record resolves.
+
+Query everything sharing an identity key, grouped by type:
 
 \`\`\`bash
+one --agent mem find-by-key email:jane@acme.com               # all records carrying this key
+one --agent mem find-by-key email:jane@acme.com --type gmail/gmailThreads
+one --agent mem find-by-key email:jane@acme.com email:bob@acme.com   # intersection (both keys)
+one --agent mem find-by-key email:jane@acme.com --limit 25    # show more records per type
+# Look up the single record owning a source key:
 one --agent mem find-by-source hubspot/contacts:<id>
-# Or via the dotted --where path on the identity key:
-one --agent sync query hubspot/contacts --where 'email=jane@acme.com'
+# Or filter ONE model on the underlying field via the dotted --where path. Note
+# this is the raw data path, NOT the identity key \u2014 for the hubspot profile above
+# that's 'properties.email', the same path its identityKey extracts from.
+one --agent sync query hubspot/contacts --where 'properties.email=jane@acme.com'
 \`\`\`
 
+\`find-by-key\` spans BOTH columns \u2014 entity keys in \`keys[]\` and association keys in \`identity_keys[]\`. \`--limit\` (default 10) caps only how many records are listed per type; the per-type \`count\` and overall \`total\` are still full match counts, so \`count\` exceeding the listed items is the signal to raise it. A separate \`truncated\` flag reports the very different case where the 2000-match fetch cap was hit and whole types are missing \u2014 see \`one guide memory\` for the full response shape.
+
 \`sync sql\` was retired in the unified memory cutover \u2014 a raw-SQL surface can't safely span the embedded Postgres, remote Postgres, and third-party backends without leaking specifics. Use \`mem search\` / \`sync search\` / \`sync query\` with dotted \`--where\` paths instead.
 
 ## Exclude Fields
@@ -10774,7 +10933,8 @@ Every \`sync X\` command is also exposed as \`mem sync X\` \u2014 same handlers,
 | limitLocation | no | "query" (default) or "body" for POST endpoints |
 | enrich | no | Detail endpoint config for record enrichment (actionId, pathVars, concurrency) |
 | transform | no | Shell command to transform records (stdin: JSON array, stdout: JSON array) |
-| identityKey | no | Dot-path to cross-platform identifier (e.g. email) \u2192 stored as \`_identity\` column |
+| identityKey | no | "This record IS this entity" \u2014 dot-path to a cross-platform id (e.g. email) \u2192 \`keys[]\` (drives entity merge) |
+| identityKeys | no | "This record INVOLVES these people" \u2014 \`[{prefix, path}]\` for N participants (#128) \u2192 non-merging \`identity_keys[]\`; query with \`mem find-by-key\` |
 | exclude | no | Dot-path fields to strip before storing (e.g. \`["messages[].body"]\`) |
 | onInsert/onUpdate/onChange | no | Change hooks (shell command, "log", or flow) |
 
@@ -10855,14 +11015,14 @@ async function guideCommand(topic = "all") {
     json({ topic, title, content, availableTopics });
     return;
   }
-  intro(pc12.bgCyan(pc12.black(" One Guide ")));
+  intro(pc13.bgCyan(pc13.black(" One Guide ")));
   console.log();
   console.log(content);
-  console.log(pc12.dim("\u2500".repeat(60)));
+  console.log(pc13.dim("\u2500".repeat(60)));
   console.log(
-    pc12.dim("Available topics: ") + availableTopics.map((t) => pc12.cyan(t.topic)).join(", ")
+    pc13.dim("Available topics: ") + availableTopics.map((t) => pc13.cyan(t.topic)).join(", ")
   );
-  console.log(pc12.dim(`Run ${pc12.cyan("one guide <topic>")} for a specific section.`));
+  console.log(pc13.dim(`Run ${pc13.cyan("one guide <topic>")} for a specific section.`));
 }
 
 // src/lib/platform-meta.ts
@@ -11185,20 +11345,20 @@ function buildWorkflowIdeas(connections) {
 // src/commands/logout.ts
 import fs12 from "fs";
 import * as p9 from "@clack/prompts";
-function formatWhoami(config2, apiKey, pc14) {
+function formatWhoami(config2, apiKey, pc15) {
   const whoami = config2.whoami;
   const env = getEnvFromApiKey(apiKey);
-  const envLabel = env === "test" ? pc14.yellow("test") : pc14.green("live");
+  const envLabel = env === "test" ? pc15.yellow("test") : pc15.green("live");
   const lines = [];
   if (whoami) {
     const contextParts = [];
     if (whoami.organization) contextParts.push(whoami.organization.name);
     if (whoami.project) contextParts.push(whoami.project.name);
     const scopeDisplay = contextParts.length > 0 ? contextParts.join(" / ") : "Personal";
-    lines.push(`${pc14.bold(scopeDisplay)} ${pc14.dim("\xB7")} ${envLabel}`);
-    lines.push(`${whoami.user.name} ${pc14.dim(`(${whoami.user.email})`)}`);
+    lines.push(`${pc15.bold(scopeDisplay)} ${pc15.dim("\xB7")} ${envLabel}`);
+    lines.push(`${whoami.user.name} ${pc15.dim(`(${whoami.user.email})`)}`);
   } else {
-    lines.push(`${pc14.dim("Key:")} ${apiKey.slice(0, 8)}... ${pc14.dim("\xB7")} ${envLabel}`);
+    lines.push(`${pc15.dim("Key:")} ${apiKey.slice(0, 8)}... ${pc15.dim("\xB7")} ${envLabel}`);
   }
   return lines;
 }
@@ -11227,7 +11387,7 @@ async function logoutCommand() {
     json({ status: cleared ? "logged_out" : "not_logged_in", message: cleared ? "Credentials cleared." : "No config found." });
     return;
   }
-  const pc14 = (await import("picocolors")).default;
+  const pc15 = (await import("picocolors")).default;
   const globalConfig = readGlobalConfig();
   const projectConfig = readProjectConfig();
   const hasGlobal = globalConfig?.apiKey != null;
@@ -11236,13 +11396,13 @@ async function logoutCommand() {
   if (hasGlobal && hasProject) {
     const infoLines = ["You are logged in with multiple configs.", ""];
     if (projectConfig) {
-      infoLines.push(`${pc14.cyan("Local config:")}`);
-      infoLines.push(...formatWhoami(projectConfig, projectConfig.apiKey, pc14));
+      infoLines.push(`${pc15.cyan("Local config:")}`);
+      infoLines.push(...formatWhoami(projectConfig, projectConfig.apiKey, pc15));
       infoLines.push("");
     }
     if (globalConfig) {
-      infoLines.push(`${pc14.magenta("Global config:")}`);
-      infoLines.push(...formatWhoami(globalConfig, globalConfig.apiKey, pc14));
+      infoLines.push(`${pc15.magenta("Global config:")}`);
+      infoLines.push(...formatWhoami(globalConfig, globalConfig.apiKey, pc15));
     }
     p9.note(infoLines.join("\n"));
     const choice = await p9.select({
@@ -11260,14 +11420,14 @@ async function logoutCommand() {
     targetScope = choice;
   } else if (hasProject) {
     const infoLines = ["You are logged in.", ""];
-    infoLines.push(`${pc14.dim("Stored in")} ${pc14.cyan("local config")}`);
-    infoLines.push(...formatWhoami(projectConfig, projectConfig.apiKey, pc14));
+    infoLines.push(`${pc15.dim("Stored in")} ${pc15.cyan("local config")}`);
+    infoLines.push(...formatWhoami(projectConfig, projectConfig.apiKey, pc15));
     p9.note(infoLines.join("\n"));
     targetScope = "project";
   } else if (hasGlobal) {
     const infoLines = ["You are logged in.", ""];
-    infoLines.push(`${pc14.dim("Stored in")} ${pc14.magenta("global config")}`);
-    infoLines.push(...formatWhoami(globalConfig, globalConfig.apiKey, pc14));
+    infoLines.push(`${pc15.dim("Stored in")} ${pc15.magenta("global config")}`);
+    infoLines.push(...formatWhoami(globalConfig, globalConfig.apiKey, pc15));
     p9.note(infoLines.join("\n"));
     targetScope = "global";
   } else {
@@ -11304,7 +11464,7 @@ async function logoutCommand() {
 // src/lib/analytics.ts
 import { createRequire as createRequire2 } from "module";
 import { randomUUID, createHash } from "crypto";
-import pc13 from "picocolors";
+import pc14 from "picocolors";
 var require3 = createRequire2(import.meta.url);
 var DEFAULT_POSTHOG_HOST = "https://us.i.posthog.com";
 var DEFAULT_POSTHOG_KEY = "phc_a9ok4w0uxiZcVoSWOISIlin85lHMXQD3vWPaYnuRlRV";
@@ -11550,7 +11710,7 @@ function maybeShowTelemetryNotice() {
   if (telemetryNoticeShown()) return;
   markTelemetryNoticeShown();
   process.stderr.write(
-    pc13.dim(
+    pc14.dim(
       "One CLI collects usage analytics (which commands run, linked to your One account) to improve the product.\nNo arguments, inputs, or secrets are ever collected. Opt out anytime with ONE_NO_TELEMETRY=1.\n"
     )
   );
@@ -11979,21 +12139,21 @@ program.command("whoami").description("Show the user, organization, and project
     });
     return;
   }
-  const pc14 = (await import("picocolors")).default;
+  const pc15 = (await import("picocolors")).default;
   const contextParts = [];
   if (whoami.organization) contextParts.push(whoami.organization.name);
   if (whoami.project) contextParts.push(whoami.project.name);
   const scopeDisplay = contextParts.length > 0 ? contextParts.join(" / ") : "Personal";
-  const envLabel = env === "test" ? pc14.yellow("test") : pc14.green("live");
-  const configLabel = configScope === "project" ? pc14.cyan("project config") : pc14.magenta("global config");
+  const envLabel = env === "test" ? pc15.yellow("test") : pc15.green("live");
+  const configLabel = configScope === "project" ? pc15.cyan("project config") : pc15.magenta("global config");
   console.log();
-  console.log(`  ${pc14.bold(scopeDisplay)} ${pc14.dim("\xB7")} ${envLabel}`);
-  console.log(`  ${whoami.user.name} ${pc14.dim(`(${whoami.user.email})`)}`);
-  if (whoami.organization) console.log(`  ${pc14.dim("Org:")} ${whoami.organization.name} ${pc14.dim(`(${whoami.organization.id})`)}`);
-  if (whoami.project) console.log(`  ${pc14.dim("Project:")} ${whoami.project.name} ${pc14.dim(`(${whoami.project.id})`)}`);
+  console.log(`  ${pc15.bold(scopeDisplay)} ${pc15.dim("\xB7")} ${envLabel}`);
+  console.log(`  ${whoami.user.name} ${pc15.dim(`(${whoami.user.email})`)}`);
+  if (whoami.organization) console.log(`  ${pc15.dim("Org:")} ${whoami.organization.name} ${pc15.dim(`(${whoami.organization.id})`)}`);
+  if (whoami.project) console.log(`  ${pc15.dim("Project:")} ${whoami.project.name} ${pc15.dim(`(${whoami.project.id})`)}`);
   console.log();
-  console.log(`  ${pc14.dim("Using")} ${configLabel}`);
-  console.log(`  ${pc14.dim("API:")} ${apiBase}`);
+  console.log(`  ${pc15.dim("Using")} ${configLabel}`);
+  console.log(`  ${pc15.dim("API:")} ${apiBase}`);
   console.log();
 });
 program.command("add [platform]").description("Shortcut for: connection add").option("--tag <name>", "Tag the new connection (disambiguates multiple connections per platform in sync/flow profiles)").action(async (platform, options) => {