@amemhq/core 1.0.1 → 2.0.0

package/dist/cli-migrate.js

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+import {
+  collectionDimRaw,
+  countPointsRaw,
+  getCollection,
+  getEmbeddingDim,
+  getEmbeddingModel,
+  migrateCollection,
+  resolveAliasRaw,
+  scrollIdsRaw,
+  switchToMigrated
+} from "./chunk-K6WZTDM7.js";
+
+// src/cli-migrate.ts
+var USAGE = `amem-migrate \u2014 move a memory store onto a different embedding model
+
+  amem-migrate              what state the store is in, and what comes next
+  amem-migrate --apply      do the next step; safe to interrupt and re-run
+  amem-migrate --switch     put the new store behind the old name (irreversible)
+
+Options
+  --from-collection <name>  the store to migrate. Defaults to AMEM_COLLECTION.
+  --to-collection <name>    where to build it. Derived from the source if omitted.
+  --no-refresh-fields       skip re-extracting keywords for notes that never had
+                            them. Makes the run completely offline.
+  -h, --help
+
+Migrates onto amem's current default unless AMEM_EMBED_MODEL says otherwise:
+
+  AMEM_EMBED_MODEL=Alibaba-NLP/gte-multilingual-base amem-migrate --apply
+
+Nothing before --switch touches the original. If a run looks wrong, delete the
+target and start again.`;
+function parseArgs(argv) {
+  const value = (flag) => {
+    const i = argv.indexOf(flag);
+    return i === -1 ? void 0 : argv[i + 1];
+  };
+  return {
+    help: argv.includes("-h") || argv.includes("--help"),
+    apply: argv.includes("--apply"),
+    switchOver: argv.includes("--switch"),
+    from: value("--from-collection"),
+    to: value("--to-collection"),
+    refreshFields: !argv.includes("--no-refresh-fields")
+  };
+}
+function deriveTarget(source) {
+  const m = source.match(/^(.*)_v(\d+)$/);
+  return m ? `${m[1]}_v${Number(m[2]) + 1}` : `${source}_v2`;
+}
+function carried(args) {
+  return (args.from ? ` --from-collection ${args.from}` : "") + (args.to ? ` --to-collection ${args.to}` : "");
+}
+async function detect(from, to) {
+  const alias = await resolveAliasRaw(from);
+  if (alias !== null) return { kind: "switched", points: await countPointsRaw(from) };
+  const sourceDim = await collectionDimRaw(from);
+  if (sourceDim === null) return { kind: "no-source" };
+  const modelDim = await getEmbeddingDim();
+  if (sourceDim === modelDim) return { kind: "already-current", model: getEmbeddingModel() };
+  const notes = await countPointsRaw(from);
+  const targetDim = await collectionDimRaw(to);
+  if (targetDim === null) return { kind: "not-started", notes };
+  const done = (await scrollIdsRaw(to)).size;
+  return done >= notes ? { kind: "ready-to-switch", notes } : { kind: "partial", done, notes };
+}
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) {
+    console.log(USAGE);
+    return;
+  }
+  const from = args.from ?? getCollection();
+  const to = args.to ?? deriveTarget(from);
+  const flags = carried(args);
+  const phase = await detect(from, to);
+  console.log(`store:  ${from}`);
+  console.log(`model:  ${getEmbeddingModel()}`);
+  switch (phase.kind) {
+    case "no-source":
+      console.error(`
+No collection named "${from}". Nothing to migrate.`);
+      process.exitCode = 1;
+      return;
+    case "switched":
+      console.log(`
+"${from}" is already an alias \u2014 ${phase.points} notes, nothing to do.`);
+      return;
+    case "already-current":
+      console.log(`
+Already on ${phase.model}. Nothing to migrate.`);
+      return;
+    case "not-started":
+      if (!args.apply) {
+        console.log(`
+${phase.notes} notes to rebuild into "${to}".`);
+        console.log(`Run "amem-migrate${flags} --apply" to start. "${from}" is only read.`);
+        return;
+      }
+      break;
+    case "partial":
+      if (!args.apply) {
+        console.log(`
+${phase.done} of ${phase.notes} rebuilt into "${to}".`);
+        console.log(`Run "amem-migrate${flags} --apply" to carry on from there.`);
+        return;
+      }
+      break;
+    case "ready-to-switch":
+      if (!args.switchOver) {
+        console.log(`
+All ${phase.notes} notes are in "${to}". "${from}" is untouched.`);
+        console.log(`Check it, then run "amem-migrate${flags} --switch" to put "${to}" behind the name "${from}".`);
+        console.log(`That drops "${from}" and cannot be undone.`);
+        return;
+      }
+      await switchToMigrated({ name: from, to });
+      console.log(`
+Done. Nothing to change in your config \u2014 "${from}" now resolves to "${to}".`);
+      return;
+  }
+  if (args.switchOver) {
+    console.error(`
+Not finished yet \u2014 run "amem-migrate${flags} --apply" until it is before switching.`);
+    process.exitCode = 1;
+    return;
+  }
+  const result = await migrateCollection({ from, to, dryRun: false, refreshFields: args.refreshFields });
+  console.log(`
+${result.migrated + result.skipped} of ${result.total} rebuilt.`);
+  if (result.migrated + result.skipped >= result.total) {
+    console.log(`Check "${to}", then run "amem-migrate${flags} --switch".`);
+  } else {
+    console.log(`Run "amem-migrate${flags} --apply" again to carry on.`);
+  }
+}
+main().catch((err) => {
+  console.error(`amem-migrate: ${err instanceof Error ? err.message : String(err)}`);
+  process.exitCode = 1;
+});
+export {
+  carried,
+  deriveTarget,
+  parseArgs
+};
+//# sourceMappingURL=cli-migrate.js.map

package/dist/cli-migrate.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/cli-migrate.ts"],"sourcesContent":["#!/usr/bin/env node\n/**\n * amem-migrate — move a memory store onto a different embedding model.\n *\n * Written for the person who got here from an error message, not for someone\n * embedding the engine. A developer using `@amemhq/core` directly has\n * `migrateCollection()` and `switchToMigrated()` and can sequence them however\n * their deployment wants; this is the other audience, who installed a plugin and\n * whose memory has stopped working.\n *\n * So it takes no decisions from the caller that it can take itself. It works out\n * which phase the store is in, does the next safe thing, and prints the one\n * command that comes after. The target collection name is derived; nobody has to\n * know Qdrant has collections at all.\n *\n * Exactly one step is irreversible — dropping the old collection to free its name\n * for the alias — and that one has its own flag rather than being the tail of a\n * run that started out read-only.\n */\nimport { migrateCollection, switchToMigrated } from './migrate.js'\nimport { getCollection, collectionDimRaw, countPointsRaw, scrollIdsRaw, resolveAliasRaw } from './storage.js'\nimport { getEmbeddingModel, getEmbeddingDim } from './embedding.js'\n\nconst USAGE = `amem-migrate — move a memory store onto a different embedding model\n\n  amem-migrate              what state the store is in, and what comes next\n  amem-migrate --apply      do the next step; safe to interrupt and re-run\n  amem-migrate --switch     put the new store behind the old name (irreversible)\n\nOptions\n  --from-collection <name>  the store to migrate. Defaults to AMEM_COLLECTION.\n  --to-collection <name>    where to build it. Derived from the source if omitted.\n  --no-refresh-fields       skip re-extracting keywords for notes that never had\n                            them. Makes the run completely offline.\n  -h, --help\n\nMigrates onto amem's current default unless AMEM_EMBED_MODEL says otherwise:\n\n  AMEM_EMBED_MODEL=Alibaba-NLP/gte-multilingual-base amem-migrate --apply\n\nNothing before --switch touches the original. If a run looks wrong, delete the\ntarget and start again.`\n\nexport interface MigrateArgs {\n  help: boolean\n  apply: boolean\n  switchOver: boolean\n  from?: string\n  to?: string\n  refreshFields: boolean\n}\n\nexport function parseArgs(argv: string[]): MigrateArgs {\n  const value = (flag: string): string | undefined => {\n    const i = argv.indexOf(flag)\n    return i === -1 ? undefined : argv[i + 1]\n  }\n  return {\n    help: argv.includes('-h') || argv.includes('--help'),\n    apply: argv.includes('--apply'),\n    switchOver: argv.includes('--switch'),\n    from: value('--from-collection'),\n    to: value('--to-collection'),\n    refreshFields: !argv.includes('--no-refresh-fields'),\n  }\n}\n\n/**\n * `amem_notes` → `amem_notes_v2`, and `amem_notes_v2` → `amem_notes_v3`.\n *\n * Derived rather than asked for: the name is an implementation detail of a\n * mechanism the user is not supposed to have to learn, and a wrong guess at it is\n * how you end up with two half-migrated stores.\n */\nexport function deriveTarget(source: string): string {\n  const m = source.match(/^(.*)_v(\\d+)$/)\n  return m ? `${m[1]}_v${Number(m[2]) + 1}` : `${source}_v2`\n}\n\n/**\n * The collection flags this run was given, so every \"now run …\" line it prints is\n * copy-pasteable as-is.\n *\n * Without it a mode B operator who passed `--from-collection` would be told to run\n * a bare `amem-migrate --apply`, which falls back to AMEM_COLLECTION and migrates\n * a different store. Only the collection flags are carried: forgetting\n * `--no-refresh-fields` costs an LLM call, forgetting these loses the plot.\n */\nexport function carried(args: MigrateArgs): string {\n  return (args.from ? ` --from-collection ${args.from}` : '') + (args.to ? ` --to-collection ${args.to}` : '')\n}\n\ntype Phase =\n  | { kind: 'no-source' }\n  | { kind: 'already-current'; model: string }\n  | { kind: 'not-started'; notes: number }\n  | { kind: 'partial'; done: number; notes: number }\n  | { kind: 'ready-to-switch'; notes: number }\n  | { kind: 'switched'; points: number }\n\nasync function detect(from: string, to: string): Promise<Phase> {\n  const alias = await resolveAliasRaw(from)\n  if (alias !== null) return { kind: 'switched', points: await countPointsRaw(from) }\n\n  const sourceDim = await collectionDimRaw(from)\n  if (sourceDim === null) return { kind: 'no-source' }\n\n  const modelDim = await getEmbeddingDim()\n  if (sourceDim === modelDim) return { kind: 'already-current', model: getEmbeddingModel() }\n\n  const notes = await countPointsRaw(from)\n  const targetDim = await collectionDimRaw(to)\n  if (targetDim === null) return { kind: 'not-started', notes }\n\n  const done = (await scrollIdsRaw(to)).size\n  return done >= notes ? { kind: 'ready-to-switch', notes } : { kind: 'partial', done, notes }\n}\n\nasync function main(): Promise<void> {\n  const args = parseArgs(process.argv.slice(2))\n  if (args.help) {\n    console.log(USAGE)\n    return\n  }\n\n  const from = args.from ?? getCollection()\n  const to = args.to ?? deriveTarget(from)\n  const flags = carried(args)\n  const phase = await detect(from, to)\n\n  console.log(`store:  ${from}`)\n  console.log(`model:  ${getEmbeddingModel()}`)\n\n  switch (phase.kind) {\n    case 'no-source':\n      console.error(`\\nNo collection named \"${from}\". Nothing to migrate.`)\n      process.exitCode = 1\n      return\n\n    case 'switched':\n      console.log(`\\n\"${from}\" is already an alias — ${phase.points} notes, nothing to do.`)\n      return\n\n    case 'already-current':\n      console.log(`\\nAlready on ${phase.model}. Nothing to migrate.`)\n      return\n\n    case 'not-started':\n      if (!args.apply) {\n        console.log(`\\n${phase.notes} notes to rebuild into \"${to}\".`)\n        console.log(`Run \"amem-migrate${flags} --apply\" to start. \"${from}\" is only read.`)\n        return\n      }\n      break\n\n    case 'partial':\n      if (!args.apply) {\n        console.log(`\\n${phase.done} of ${phase.notes} rebuilt into \"${to}\".`)\n        console.log(`Run \"amem-migrate${flags} --apply\" to carry on from there.`)\n        return\n      }\n      break\n\n    case 'ready-to-switch':\n      if (!args.switchOver) {\n        console.log(`\\nAll ${phase.notes} notes are in \"${to}\". \"${from}\" is untouched.`)\n        console.log(`Check it, then run \"amem-migrate${flags} --switch\" to put \"${to}\" behind the name \"${from}\".`)\n        console.log(`That drops \"${from}\" and cannot be undone.`)\n        return\n      }\n      await switchToMigrated({ name: from, to })\n      console.log(`\\nDone. Nothing to change in your config — \"${from}\" now resolves to \"${to}\".`)\n      return\n  }\n\n  if (args.switchOver) {\n    console.error(`\\nNot finished yet — run \"amem-migrate${flags} --apply\" until it is before switching.`)\n    process.exitCode = 1\n    return\n  }\n\n  const result = await migrateCollection({ from, to, dryRun: false, refreshFields: args.refreshFields })\n  console.log(`\\n${result.migrated + result.skipped} of ${result.total} rebuilt.`)\n  if (result.migrated + result.skipped >= result.total) {\n    console.log(`Check \"${to}\", then run \"amem-migrate${flags} --switch\".`)\n  } else {\n    console.log(`Run \"amem-migrate${flags} --apply\" again to carry on.`)\n  }\n}\n\nmain().catch((err: unknown) => {\n  console.error(`amem-migrate: ${err instanceof Error ? err.message : String(err)}`)\n  process.exitCode = 1\n})\n"],"mappings":"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","names":[]}