@anuma/sdk 6.33.2 → 6.35.0

package/dist/server/index.cjs

@@ -16302,7 +16302,10 @@ __export(index_exports, {
   MAX_HOPS: () => MAX_HOPS,
   MAX_MESSAGES_PER_SUMMARIZATION: () => MAX_MESSAGES_PER_SUMMARIZATION,
   MEDIUM_TTL_MS: () => MEDIUM_TTL_MS,
+  MEMORY_KINDS: () => MEMORY_KINDS,
+  MEMORY_LEVELS: () => MEMORY_LEVELS,
   Media: () => Media,
+  MemoryLevelError: () => MemoryLevelError,
   Message: () => Message,
   ModelPreference: () => ModelPreference,
   NEVER_TTL_MS: () => NEVER_TTL_MS,
@@ -19969,7 +19972,7 @@ async function embedOne(text12, options, outer) {
 }
 var DEFAULT_EMBEDDING_BATCH_SIZE = 100;
 var DEFAULT_EMBEDDING_BATCH_CONCURRENCY = 3;
-async function generateEmbeddingsBatch(texts, headers, baseUrl, model, onUsage, maskInput, timeoutMs) {
+async function generateEmbeddingsBatch(texts, headers, baseUrl, model, onUsage, maskInput, timeoutMs, outer) {
   const response = await withEmbeddingRetry(
     () => withDeadline(
       (signal) => postApiV1Embeddings({
@@ -19979,8 +19982,10 @@ async function generateEmbeddingsBatch(texts, headers, baseUrl, model, onUsage,
         ...signal && { signal }
       }),
       timeoutMs,
-      "embedding batch request"
-    )
+      "embedding batch request",
+      outer
+    ),
+    outer
   );
   if (response.error) {
     throw embeddingErrorFrom(response);
@@ -19998,6 +20003,11 @@ async function generateEmbeddingsBatch(texts, headers, baseUrl, model, onUsage,
 }
 async function generateEmbeddings(texts, options) {
   if (texts.length === 0) return [];
+  const total = options.totalTimeoutMs;
+  if (total === void 0) return embedMany(texts, options, void 0);
+  return withDeadline((signal) => embedMany(texts, options, signal), total, "embedding batch");
+}
+async function embedMany(texts, options, outer) {
   const { baseUrl = BASE_URL, model, batchSize, cache } = options;
   const timeoutMs = options.timeoutMs ?? DEFAULT_EMBEDDING_REQUEST_TIMEOUT_MS;
   const chunkSize = batchSize ?? DEFAULT_EMBEDDING_BATCH_SIZE;
@@ -20018,7 +20028,8 @@ async function generateEmbeddings(texts, options) {
   if (uncachedTexts.length === 0) {
     return results;
   }
-  const headers = await resolveAuthHeaders(options);
+  const headers = await resolveAuthHeaders(options, outer);
+  if (outer?.aborted) throw outer.reason;
   const embeddingModel = model ?? DEFAULT_API_EMBEDDING_MODEL;
   let newEmbeddings;
   if (uncachedTexts.length <= chunkSize) {
@@ -20029,7 +20040,8 @@ async function generateEmbeddings(texts, options) {
       embeddingModel,
       options.onUsage,
       options.maskInput,
-      timeoutMs
+      timeoutMs,
+      outer
     );
   } else {
     const chunks = [];
@@ -20040,6 +20052,7 @@ async function generateEmbeddings(texts, options) {
     let nextIndex = 0;
     const worker = async () => {
       while (nextIndex < chunks.length) {
+        if (outer?.aborted) throw outer.reason;
         const idx = nextIndex++;
         allEmbeddings[idx] = await generateEmbeddingsBatch(
           chunks[idx],
@@ -20048,7 +20061,8 @@ async function generateEmbeddings(texts, options) {
           embeddingModel,
           options.onUsage,
           options.maskInput,
-          timeoutMs
+          timeoutMs,
+          outer
         );
       }
     };
@@ -20059,6 +20073,7 @@ async function generateEmbeddings(texts, options) {
     await Promise.all(workers);
     newEmbeddings = allEmbeddings.flat();
   }
+  if (outer?.aborted) throw outer.reason;
   for (let i = 0; i < uncachedIndices.length; i++) {
     const f32Embedding = Float32Array.from(newEmbeddings[i]);
     results[uncachedIndices[i]] = Array.from(f32Embedding);
@@ -25395,6 +25410,15 @@ __decorateClass([
 __decorateClass([
   (0, import_decorators6.text)("scope")
 ], VaultMemory.prototype, "scope", 2);
+__decorateClass([
+  (0, import_decorators6.field)("kind")
+], VaultMemory.prototype, "kind", 2);
+__decorateClass([
+  (0, import_decorators6.field)("kind_value")
+], VaultMemory.prototype, "kindValue", 2);
+__decorateClass([
+  (0, import_decorators6.field)("level")
+], VaultMemory.prototype, "level", 2);
 __decorateClass([
   (0, import_decorators6.field)("folder_id")
 ], VaultMemory.prototype, "folderId", 2);
@@ -25620,7 +25644,7 @@ __decorateClass([
 ], VaultFolder.prototype, "context", 2);
 
 // src/lib/db/schema.ts
-var SDK_SCHEMA_VERSION = 47;
+var SDK_SCHEMA_VERSION = 48;
 var sdkSchema = (0, import_watermelondb15.appSchema)({
   version: SDK_SCHEMA_VERSION,
   tables: [
@@ -25715,6 +25739,9 @@ var sdkSchema = (0, import_watermelondb15.appSchema)({
       columns: [
         { name: "content", type: "string" },
         { name: "scope", type: "string", isIndexed: true },
+        { name: "kind", type: "string", isOptional: true, isIndexed: true },
+        { name: "kind_value", type: "string", isOptional: true },
+        { name: "level", type: "string", isOptional: true, isIndexed: true },
         { name: "folder_id", type: "string", isOptional: true, isIndexed: true },
         { name: "created_at", type: "number", isIndexed: true },
         { name: "updated_at", type: "number", isIndexed: true },
@@ -26391,6 +26418,22 @@ var sdkMigrations = (0, import_migrations.schemaMigrations)({
           ]
         })
       ]
+    },
+    {
+      toVersion: 48,
+      steps: [
+        (0, import_migrations.addColumns)({
+          table: "memory_vault",
+          columns: [
+            { name: "kind", type: "string", isOptional: true, isIndexed: true },
+            { name: "kind_value", type: "string", isOptional: true },
+            { name: "level", type: "string", isOptional: true, isIndexed: true }
+          ]
+        }),
+        (0, import_migrations.unsafeExecuteSql)(
+          "UPDATE memory_vault SET level = CASE WHEN scope IN ('shared', 'public') THEN 'matching' ELSE 'private' END WHERE level IS NULL;"
+        )
+      ]
     }
   ]
 });
@@ -27546,13 +27589,54 @@ async function decryptVaultMemoryFields(memory, address, signMessage, embeddedWa
     }
   }
   const decryptedContent = await decryptField(memory.content, address);
+  const decryptedKindValue = typeof memory.kindValue === "string" ? await decryptField(memory.kindValue, address) : memory.kindValue;
   return {
     ...memory,
-    content: decryptedContent
+    content: decryptedContent,
+    ...decryptedKindValue !== void 0 && { kindValue: decryptedKindValue }
   };
 }
 
 // src/lib/db/memoryVault/types.ts
+var MEMORY_KINDS = [
+  "display_name",
+  "birth_date",
+  "bio",
+  "occupation",
+  "interest",
+  "gender",
+  "height_cm",
+  "looking_for",
+  "politics",
+  "religion",
+  "ethnicity",
+  "smoking",
+  "drinking",
+  "exercise",
+  "sexuality",
+  "prompt"
+];
+var MEMORY_LEVELS = ["private", "matching", "profile"];
+var MemoryLevelError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "MemoryLevelError";
+  }
+};
+var PUBLISHED_SCOPES = /* @__PURE__ */ new Set(["shared", "public"]);
+function levelFromScope(scope) {
+  return typeof scope === "string" && PUBLISHED_SCOPES.has(scope) ? "matching" : "private";
+}
+function scopeForLevel(level) {
+  return level === "private" ? "private" : "shared";
+}
+function resolveMemoryLevel(level, scope) {
+  return typeof level === "string" && MEMORY_LEVELS.includes(level) ? level : levelFromScope(scope);
+}
+function levelForScopeChange(current, nextScope) {
+  const implied = levelFromScope(nextScope);
+  return implied === "matching" && resolveMemoryLevel(current.level, current.scope) === "profile" ? "profile" : implied;
+}
 function parseMedia(value) {
   if (typeof value !== "string" || value === "") return null;
   try {
@@ -27582,6 +27666,56 @@ function visibilityConditions(requested) {
   if (excluded.length === 0) return [];
   return [import_watermelondb19.Q.or(import_watermelondb19.Q.where("visibility", null), import_watermelondb19.Q.where("visibility", import_watermelondb19.Q.notIn(excluded)))];
 }
+function isKinded(record) {
+  return record.kind !== null && record.kind !== void 0;
+}
+function assertValidKindLevel(kind, level) {
+  const hasKind = kind !== null && kind !== void 0;
+  if (hasKind && !MEMORY_KINDS.includes(kind)) {
+    throw new MemoryLevelError(`Unknown memory kind: ${kind}`);
+  }
+  if (level !== void 0 && !MEMORY_LEVELS.includes(level)) {
+    throw new MemoryLevelError(`Unknown memory level: ${level}`);
+  }
+  if (level === "profile" && !hasKind) {
+    throw new MemoryLevelError("Only a memory with a kind can be at level 'profile'");
+  }
+}
+function resolveCreateLevel(opts) {
+  if (opts.level !== void 0) return { level: opts.level, scope: scopeForLevel(opts.level) };
+  if (opts.scope !== void 0) return { level: levelFromScope(opts.scope), scope: opts.scope };
+  return { level: "private", scope: "private" };
+}
+async function encryptKindValue(ctx, value) {
+  if (typeof value !== "string" || !ctx.walletAddress || !ctx.signMessage) return value;
+  return encryptVaultMemoryContent(
+    value,
+    ctx.walletAddress,
+    ctx.signMessage,
+    ctx.embeddedWalletSigner
+  );
+}
+function levelConditions(requested) {
+  if (!requested?.length) return [];
+  const published = ["shared", "public"];
+  const wantsMatching = requested.includes("matching");
+  const wantsPrivate = requested.includes("private");
+  const unresolved = import_watermelondb19.Q.or(import_watermelondb19.Q.where("level", null), import_watermelondb19.Q.where("level", import_watermelondb19.Q.notIn([...MEMORY_LEVELS])));
+  const byLevel = import_watermelondb19.Q.where("level", import_watermelondb19.Q.oneOf([...requested]));
+  if (wantsMatching && wantsPrivate) return [import_watermelondb19.Q.or(byLevel, unresolved)];
+  if (wantsMatching) {
+    return [import_watermelondb19.Q.or(byLevel, import_watermelondb19.Q.and(unresolved, import_watermelondb19.Q.where("scope", import_watermelondb19.Q.oneOf(published))))];
+  }
+  if (wantsPrivate) {
+    return [
+      import_watermelondb19.Q.or(
+        byLevel,
+        import_watermelondb19.Q.and(unresolved, import_watermelondb19.Q.or(import_watermelondb19.Q.where("scope", null), import_watermelondb19.Q.where("scope", import_watermelondb19.Q.notIn(published))))
+      )
+    ];
+  }
+  return [byLevel];
+}
 function isOwnedByCtxUser(ctx, record) {
   return ctx.userId === void 0 || record.userId === ctx.userId;
 }
@@ -27625,6 +27759,9 @@ function vaultMemoryToStoredRaw(memory) {
     uniqueId: memory.id,
     content: memory.content,
     scope: memory.scope,
+    kind: memory.kind ?? null,
+    kindValue: memory.kindValue ?? null,
+    level: resolveMemoryLevel(memory.level, memory.scope),
     folderId: memory.folderId ?? null,
     userId: memory.userId ?? null,
     embedding: memory.embedding ?? null,
@@ -27663,9 +27800,13 @@ async function vaultMemoryToStored(memory, walletAddress, signMessage, embeddedW
   }
   return raw;
 }
-function populateNewVaultMemory(record, ctx, opts, encryptedContent) {
+function populateNewVaultMemory(record, ctx, opts, encryptedContent, encryptedKindValue) {
+  const { level, scope } = resolveCreateLevel(opts);
   record._setRaw("content", encryptedContent);
-  record._setRaw("scope", opts.scope ?? "private");
+  record._setRaw("scope", scope);
+  record._setRaw("level", level);
+  record._setRaw("kind", opts.kind ?? null);
+  record._setRaw("kind_value", encryptedKindValue ?? null);
   record._setRaw("folder_id", opts.folderId ?? null);
   record._setRaw("user_id", ctx.userId ?? null);
   record._setRaw("is_deleted", false);
@@ -27699,6 +27840,8 @@ function populateNewVaultMemory(record, ctx, opts, encryptedContent) {
   }
 }
 async function createVaultMemoryOp(ctx, opts) {
+  assertValidKindLevel(opts.kind, resolveCreateLevel(opts).level);
+  const encryptedKindValue = await encryptKindValue(ctx, opts.kindValue);
   const encryptedContent = ctx.walletAddress && ctx.signMessage ? await encryptVaultMemoryContent(
     opts.content,
     ctx.walletAddress,
@@ -27709,13 +27852,15 @@ async function createVaultMemoryOp(ctx, opts) {
     if (ctx.canWrite && !await ctx.canWrite())
       throw new Error("Memory source is no longer eligible");
     return ctx.vaultMemoryCollection.create(
-      (record) => populateNewVaultMemory(record, ctx, opts, encryptedContent)
+      (record) => populateNewVaultMemory(record, ctx, opts, encryptedContent, encryptedKindValue)
     );
   });
   return vaultMemoryToStored(created, ctx.walletAddress, ctx.signMessage, ctx.embeddedWalletSigner);
 }
 async function createSupersedingMemoryOp(ctx, opts, targetId) {
   if (!targetId) return { created: null, retired: false };
+  assertValidKindLevel(opts.kind, resolveCreateLevel(opts).level);
+  const encryptedKindValue = await encryptKindValue(ctx, opts.kindValue);
   const encryptedContent = ctx.walletAddress && ctx.signMessage ? await encryptVaultMemoryContent(
     opts.content,
     ctx.walletAddress,
@@ -27732,9 +27877,10 @@ async function createSupersedingMemoryOp(ctx, opts, targetId) {
     } catch {
       return;
     }
-    if (target.isDeleted || target.supersededBy || !isOwnedByCtxUser(ctx, target)) return;
+    if (target.isDeleted || target.supersededBy || isKinded(target) || !isOwnedByCtxUser(ctx, target))
+      return;
     createdRecord = await ctx.vaultMemoryCollection.create(
-      (record) => populateNewVaultMemory(record, ctx, opts, encryptedContent)
+      (record) => populateNewVaultMemory(record, ctx, opts, encryptedContent, encryptedKindValue)
     );
     await target.update((r) => {
       r._setRaw("superseded_by", createdRecord.id);
@@ -27798,6 +27944,10 @@ async function getMemoriesByEventTimeOp(ctx, windowStart, windowEnd) {
 }
 async function createVaultMemoriesBatchOp(ctx, optionsArray) {
   if (optionsArray.length === 0) return [];
+  for (const opts of optionsArray) assertValidKindLevel(opts.kind, resolveCreateLevel(opts).level);
+  const encryptedKindValues = await Promise.all(
+    optionsArray.map((opts) => encryptKindValue(ctx, opts.kindValue))
+  );
   const encryptedContents = await Promise.all(
     optionsArray.map(async (opts) => {
       if (ctx.walletAddress && ctx.signMessage) {
@@ -27816,7 +27966,7 @@ async function createVaultMemoriesBatchOp(ctx, optionsArray) {
       throw new Error("Memory source is no longer eligible");
     const prepared = optionsArray.map(
       (opts, i) => ctx.vaultMemoryCollection.prepareCreate(
-        (record) => populateNewVaultMemory(record, ctx, opts, encryptedContents[i])
+        (record) => populateNewVaultMemory(record, ctx, opts, encryptedContents[i], encryptedKindValues[i])
       )
     );
     await ctx.database.batch(...prepared);
@@ -27859,6 +28009,9 @@ function vaultMemoryRawToStoredRaw(raw) {
     uniqueId: raw.id,
     content: raw.content ?? "",
     scope: raw.scope ?? "",
+    kind: raw.kind ?? null,
+    kindValue: raw.kind_value ?? null,
+    level: resolveMemoryLevel(raw.level, raw.scope),
     folderId: raw.folder_id ?? null,
     userId: raw.user_id ?? null,
     embedding: raw.embedding ?? null,
@@ -27902,6 +28055,8 @@ async function getAllVaultMemoriesOp(ctx, options) {
     ...baseVaultConditions(ctx, options),
     ...options?.scopes?.length ? [import_watermelondb19.Q.where("scope", import_watermelondb19.Q.oneOf(options.scopes))] : [],
     ...visibilityConditions(options?.visibility),
+    ...levelConditions(options?.levels),
+    ...options?.kinds?.length ? [import_watermelondb19.Q.where("kind", import_watermelondb19.Q.oneOf(options.kinds))] : [],
     ...options?.folderId !== void 0 ? [import_watermelondb19.Q.where("folder_id", options.folderId)] : [],
     ...options?.factTypes?.length ? [import_watermelondb19.Q.where("fact_type", import_watermelondb19.Q.oneOf(options.factTypes))] : [],
     import_watermelondb19.Q.sortBy(options?.since ? "updated_at" : "created_at", import_watermelondb19.Q.desc),
@@ -28068,6 +28223,14 @@ async function updateVaultMemoryOp(ctx, id, opts) {
   try {
     const probe = await ctx.vaultMemoryCollection.find(id);
     if (probe.isDeleted || probe.supersededBy || !isOwnedByCtxUser(ctx, probe)) return null;
+    if (opts.freeFormOnly && isKinded(probe)) return null;
+    const levelAfter = (current) => {
+      if (opts.level !== void 0) return opts.level;
+      if (opts.scope === void 0) return resolveMemoryLevel(current.level, current.scope);
+      return levelForScopeChange(current, opts.scope);
+    };
+    assertValidKindLevel(opts.kind !== void 0 ? opts.kind : probe.kind, levelAfter(probe));
+    const encryptedKindValue = await encryptKindValue(ctx, opts.kindValue);
     const encryptedContent = ctx.walletAddress && ctx.signMessage ? await encryptVaultMemoryContent(
       opts.content,
       ctx.walletAddress,
@@ -28080,10 +28243,13 @@ async function updateVaultMemoryOp(ctx, id, opts) {
     await ctx.database.write(async () => {
       if (ctx.canWrite && !await ctx.canWrite())
         throw new Error("Memory source is no longer eligible");
-      if (record.isDeleted || record.supersededBy || !isOwnedByCtxUser(ctx, record)) {
+      if (record.isDeleted || record.supersededBy || !isOwnedByCtxUser(ctx, record) || opts.freeFormOnly && isKinded(record)) {
         stale = true;
         return;
       }
+      const nextKind = opts.kind !== void 0 ? opts.kind : record.kind;
+      const nextLevel = levelAfter(record);
+      assertValidKindLevel(nextKind, nextLevel);
       let observedSources = [];
       let replayedObservation = false;
       if (opts.observationSourceIds?.length) {
@@ -28097,8 +28263,18 @@ async function updateVaultMemoryOp(ctx, id, opts) {
       }
       await record.update((r) => {
         r._setRaw("content", encryptedContent);
-        if (opts.scope !== void 0) {
+        if (opts.level !== void 0) {
+          r._setRaw("level", nextLevel);
+          r._setRaw("scope", scopeForLevel(nextLevel));
+        } else if (opts.scope !== void 0) {
           r._setRaw("scope", opts.scope);
+          r._setRaw("level", nextLevel);
+        }
+        if (opts.kind !== void 0) {
+          r._setRaw("kind", opts.kind);
+        }
+        if (encryptedKindValue !== void 0) {
+          r._setRaw("kind_value", encryptedKindValue);
         }
         if (opts.folderId !== void 0) {
           r._setRaw("folder_id", opts.folderId);
@@ -28157,7 +28333,8 @@ async function updateVaultMemoryOp(ctx, id, opts) {
       ctx.signMessage,
       ctx.embeddedWalletSigner
     );
-  } catch {
+  } catch (err) {
+    if (err instanceof MemoryLevelError) throw err;
     return null;
   }
 }
@@ -28293,6 +28470,7 @@ async function supersedeVaultMemoryOp(ctx, id, supersededById) {
   try {
     const record = await ctx.vaultMemoryCollection.find(id);
     if (record.isDeleted || record.supersededBy || !isOwnedByCtxUser(ctx, record)) return false;
+    if (isKinded(record)) return false;
     let successor;
     try {
       successor = await ctx.vaultMemoryCollection.find(supersededById);
@@ -28593,7 +28771,10 @@ function assertVaultScopeForSweep(ctx) {
 }
 async function getDecayCandidatesRawOp(ctx) {
   assertVaultScopeForSweep(ctx);
-  const results = await ctx.vaultMemoryCollection.query(...baseVaultConditions(ctx, { includeArchived: true, includeQuarantined: true })).unsafeFetchRaw();
+  const results = await ctx.vaultMemoryCollection.query(
+    ...baseVaultConditions(ctx, { includeArchived: true, includeQuarantined: true }),
+    import_watermelondb19.Q.where("kind", null)
+  ).unsafeFetchRaw();
   return results.map((raw) => ({
     uniqueId: raw.id,
     factType: raw.fact_type ?? null,
@@ -28854,6 +29035,7 @@ async function ingestPublishedPhotoMemoriesOp(ctx, rows) {
         record._raw.id = row.memoryId;
         record._setRaw("content", content);
         record._setRaw("scope", "shared");
+        record._setRaw("level", "matching");
         record._setRaw("folder_id", null);
         record._setRaw("user_id", ctx.userId ?? null);
         record._setRaw("is_deleted", false);
@@ -31574,7 +31756,7 @@ async function rankPreparedVaultCandidates(query, prepared, embeddingOptions, se
   if (useFusion && !embeddingsUnavailable && facetQueries) {
     let subEmbeddings;
     try {
-      subEmbeddings = await generateEmbeddings(facetQueries, embeddingOptions);
+      subEmbeddings = prepared.facetEmbeddings ?? await generateEmbeddings(facetQueries, embeddingOptions);
     } catch (err) {
       getLogger().warn(
         "memoryVault: sub-query embedding failed \u2014 falling back to single-query ranking: " + (err instanceof Error ? err.message : String(err))
@@ -31760,6 +31942,35 @@ var DEFAULT_SCOPE = "private";
 var DEFAULT_CONSOLIDATE_THRESHOLD = 0.55;
 var DEFAULT_CONSOLIDATE_TOP_K = 20;
 async function retain(content, ctx, options = {}) {
+  return retainWithPersistence(
+    content,
+    {
+      embeddingOptions: ctx.embeddingOptions,
+      vaultCache: ctx.vaultCache,
+      persistence: {
+        prepare: (query, searchOptions) => prepareVaultCandidates(
+          query,
+          ctx.vaultCtx,
+          ctx.embeddingOptions,
+          ctx.vaultCache,
+          searchOptions
+        ),
+        get: (id) => getVaultMemoryOp(ctx.vaultCtx, id),
+        tombstones: (_embedding, _model, scope, folderId) => getAllVaultMemoriesOp(ctx.vaultCtx, {
+          includeDeleted: true,
+          scopes: [scope],
+          ...folderId !== void 0 && { folderId }
+        }),
+        create: (input) => createVaultMemoryOp(ctx.vaultCtx, input),
+        update: (id, patch) => updateVaultMemoryOp(ctx.vaultCtx, id, patch),
+        supersede: (id, successor) => supersedeVaultMemoryOp(ctx.vaultCtx, id, successor),
+        createSuperseding: (input, target) => createSupersedingMemoryOp(ctx.vaultCtx, input, target)
+      }
+    },
+    options
+  );
+}
+async function retainWithPersistence(content, ctx, options = {}) {
   const trimmed = content.trim();
   if (trimmed.length === 0) {
     throw new Error("retain: content cannot be empty");
@@ -31772,19 +31983,14 @@ async function retain(content, ctx, options = {}) {
   let supersedeContent;
   let prepared;
   if (enableAutoMerge) {
-    prepared = await prepareVaultCandidates(
-      trimmed,
-      ctx.vaultCtx,
-      ctx.embeddingOptions,
-      ctx.vaultCache,
-      {
-        limit: Math.max(options.consolidateTopK ?? DEFAULT_CONSOLIDATE_TOP_K, 1),
-        useFusion: false,
-        scopes: [resolvedScope],
-        includeArchived: true,
-        ...options.folderId !== void 0 && { folderId: options.folderId }
-      }
-    );
+    prepared = await ctx.persistence.prepare(trimmed, {
+      limit: Math.max(options.consolidateTopK ?? DEFAULT_CONSOLIDATE_TOP_K, 1),
+      useFusion: false,
+      scopes: [resolvedScope],
+      includeArchived: true,
+      ...options.folderId !== void 0 && { folderId: options.folderId }
+    });
+    prepared = withoutKindedRows(prepared);
     if (prepared.embeddingFailure || prepared.embeddingsUnavailable) {
       throw new Error(
         "retain: embeddings unavailable \u2014 refusing to auto-merge against an inert cosine lane, which would create a duplicate instead of merging into the existing memory. Retry when embeddings recover, or pass enableAutoMerge: false to force a create."
@@ -31815,7 +32021,7 @@ async function retain(content, ctx, options = {}) {
       );
       if (matches.length > 0) {
         const targetId = matches[0].uniqueId;
-        const existing = await getVaultMemoryOp(ctx.vaultCtx, targetId);
+        const existing = await ctx.persistence.get(targetId);
         if (existing && !existing.supersededBy) {
           const mergedSourceIds = unionStrings(
             existing.sourceChunkIds ?? [],
@@ -31824,8 +32030,9 @@ async function retain(content, ctx, options = {}) {
           const eventTimeUpdate = pickEventTimeUpdate(existing, options.eventTime);
           const factTypeUpdate = pickFactTypeUpdate(existing, options.factType);
           const resurrect = resurrectFields(existing);
-          const updated = await updateVaultMemoryOp(ctx.vaultCtx, targetId, {
+          const updated = await ctx.persistence.update(targetId, {
             content: existing.content,
+            freeFormOnly: true,
             proofCountIncrement: 1,
             observationSourceIds: options.sourceChunkIds,
             sourceChunkIds: mergedSourceIds,
@@ -31851,7 +32058,8 @@ async function retain(content, ctx, options = {}) {
   }
   const contentToWrite = supersedeContent ?? trimmed;
   const reusableQueryEmbedding = supersedeContent === void 0 && prepared && prepared.queryEmbedding.length > 0 ? prepared.queryEmbedding : void 0;
-  const embedding = reusableQueryEmbedding ?? await generateEmbedding(contentToWrite, ctx.embeddingOptions);
+  const generatedEmbedding = reusableQueryEmbedding ?? await generateEmbedding(contentToWrite, ctx.embeddingOptions);
+  const embedding = ctx.normalizeEmbedding?.(generatedEmbedding) ?? generatedEmbedding;
   const embeddingModel = ctx.embeddingOptions.model ?? DEFAULT_API_EMBEDDING_MODEL;
   if (options.respectTombstones) {
     const tombstone = await findTombstoneMatch(embedding, embeddingModel, resolvedScope, ctx, {
@@ -31891,8 +32099,7 @@ async function retain(content, ctx, options = {}) {
   };
   if (supersedeTargetIds.length > 0) {
     const [primaryTargetId, ...restTargetIds] = supersedeTargetIds;
-    const { created: created2, retired } = await createSupersedingMemoryOp(
-      ctx.vaultCtx,
+    const { created: created2, retired } = await ctx.persistence.createSuperseding(
       createOpts,
       primaryTargetId
     );
@@ -31908,11 +32115,11 @@ async function retain(content, ctx, options = {}) {
       for (const staleId of restTargetIds) {
         let ok = false;
         try {
-          ok = await supersedeVaultMemoryOp(ctx.vaultCtx, staleId, created2.uniqueId) === true;
+          ok = await ctx.persistence.supersede(staleId, created2.uniqueId) === true;
         } catch {
         }
         if (ok) continue;
-        const stillLive = await getVaultMemoryOp(ctx.vaultCtx, staleId).catch(() => null);
+        const stillLive = await (ctx.persistence.getFresh ? ctx.persistence.getFresh(staleId) : ctx.persistence.get(staleId)).catch(() => null);
         if (stillLive && !stillLive.supersededBy) liveLeftovers.push(staleId);
       }
       if (liveLeftovers.length > 0) {
@@ -31939,7 +32146,7 @@ async function retain(content, ctx, options = {}) {
       `supersede: primary target ${primaryTargetId} retired or deleted inside the atomic write`
     );
   }
-  const created = await createVaultMemoryOp(ctx.vaultCtx, createOpts);
+  const created = await ctx.persistence.create(createOpts);
   cacheRowVector(
     ctx.vaultCache,
     created.uniqueId,
@@ -31954,15 +32161,22 @@ async function retain(content, ctx, options = {}) {
     ...consolidationDecidedCreate && { consolidation: "create" }
   };
 }
+function withoutKindedRows(prepared) {
+  const kinded = new Set(
+    prepared.memories.filter((m) => m.kind !== null && m.kind !== void 0).map((m) => m.uniqueId)
+  );
+  if (kinded.size === 0) return prepared;
+  return {
+    ...prepared,
+    memories: prepared.memories.filter((m) => !kinded.has(m.uniqueId)),
+    embeddedItems: prepared.embeddedItems.filter((item) => !kinded.has(item.id))
+  };
+}
 function unionStrings(a, b) {
   return [.../* @__PURE__ */ new Set([...a, ...b])];
 }
 async function findTombstoneMatch(embedding, embeddingModel, scope, ctx, opts) {
-  const rows = await getAllVaultMemoriesOp(ctx.vaultCtx, {
-    includeDeleted: true,
-    scopes: [scope],
-    ...opts.folderId !== void 0 && { folderId: opts.folderId }
-  });
+  const rows = await ctx.persistence.tombstones(embedding, embeddingModel, scope, opts.folderId);
   let bestId = null;
   let bestSim = opts.threshold;
   for (const row of rows) {
@@ -32029,7 +32243,7 @@ async function tryConsolidate(trimmed, ctx, options, prepared) {
     if (requestedIds.length === 0) return null;
     const valid = [];
     for (const id of requestedIds) {
-      const existing = await getVaultMemoryOp(ctx.vaultCtx, id);
+      const existing = await ctx.persistence.get(id);
       if (existing && !existing.supersededBy) valid.push(id);
     }
     if (valid.length === 0) {
@@ -32041,7 +32255,7 @@ async function tryConsolidate(trimmed, ctx, options, prepared) {
     return { supersede: valid, content: decision.content };
   }
   if (decision.action === "noop" && decision.targetId) {
-    const existing = await getVaultMemoryOp(ctx.vaultCtx, decision.targetId);
+    const existing = await ctx.persistence.get(decision.targetId);
     if (!existing || existing.supersededBy) {
       return abandonToRace(
         options,
@@ -32055,8 +32269,9 @@ async function tryConsolidate(trimmed, ctx, options, prepared) {
     const eventTimeUpdate = pickEventTimeUpdate(existing, options.eventTime);
     const factTypeUpdate = pickFactTypeUpdate(existing, options.factType);
     const resurrect = resurrectFields(existing);
-    const updated = await updateVaultMemoryOp(ctx.vaultCtx, decision.targetId, {
+    const updated = await ctx.persistence.update(decision.targetId, {
       content: existing.content,
+      freeFormOnly: true,
       proofCountIncrement: 1,
       observationSourceIds: options.sourceChunkIds,
       sourceChunkIds: mergedSourceIds,
@@ -32083,7 +32298,7 @@ async function tryConsolidate(trimmed, ctx, options, prepared) {
     };
   }
   if (decision.action === "update" && decision.targetId && decision.content) {
-    const existing = await getVaultMemoryOp(ctx.vaultCtx, decision.targetId);
+    const existing = await ctx.persistence.get(decision.targetId);
     if (!existing || existing.supersededBy) {
       return abandonToRace(
         options,
@@ -32094,13 +32309,15 @@ async function tryConsolidate(trimmed, ctx, options, prepared) {
       existing.sourceChunkIds ?? [],
       options.sourceChunkIds ?? []
     );
-    const newEmbedding = await generateEmbedding(decision.content, ctx.embeddingOptions);
+    const generatedEmbedding = await generateEmbedding(decision.content, ctx.embeddingOptions);
+    const newEmbedding = ctx.normalizeEmbedding?.(generatedEmbedding) ?? generatedEmbedding;
     const consolidatedModel = ctx.embeddingOptions.model ?? DEFAULT_API_EMBEDDING_MODEL;
     const eventTimeUpdate = pickEventTimeUpdate(existing, options.eventTime);
     const factTypeUpdate = pickFactTypeUpdate(existing, options.factType);
     const resurrect = resurrectFields(existing);
-    const updated = await updateVaultMemoryOp(ctx.vaultCtx, decision.targetId, {
+    const updated = await ctx.persistence.update(decision.targetId, {
       content: decision.content,
+      freeFormOnly: true,
       proofCountIncrement: 1,
       observationSourceIds: options.sourceChunkIds,
       sourceChunkIds: mergedSourceIds,
@@ -32143,8 +32360,8 @@ async function tryConsolidate(trimmed, ctx, options, prepared) {
   return null;
 }
 async function assertMergeTargetGoneOrThrow(ctx, targetId) {
-  const stillExists = await getVaultMemoryOp(ctx.vaultCtx, targetId);
-  if (stillExists) {
+  const stillExists = await (ctx.persistence.getFresh ? ctx.persistence.getFresh(targetId) : ctx.persistence.get(targetId));
+  if (stillExists && (stillExists.kind === null || stillExists.kind === void 0)) {
     throw new Error(`retain: merge into memory ${targetId} failed to persist`);
   }
 }
@@ -33642,7 +33859,7 @@ async function recall(query, ctx, options = {}) {
     if (graphLaneFailed) degraded.push("graph-lane-failed");
     if (temporalLaneFailed) degraded.push("temporal-lane-failed");
     if (chunksScopeRestricted) degraded.push("chunks-scope-restricted");
-    const laneRan = types.includes("fact") && !!ctx.vaultCtx && !!ctx.vaultCache || types.includes("chunk") && !!ctx.storageCtx || chunksScopeRestricted && !!ctx.storageCtx;
+    const laneRan = types.includes("fact") && (!!ctx.factSource || !!ctx.vaultCtx && !!ctx.vaultCache) || types.includes("chunk") && !!ctx.storageCtx || chunksScopeRestricted && !!ctx.storageCtx;
     const scores = admitted.map((m) => m.score);
     const minScoreApplied = factResults.length > 0 ? factFloor : chunkResults.length > 0 ? chunkFloor : factFloor >= 0 ? factFloor : chunkFloor;
     const diagnostics = {
@@ -33684,7 +33901,7 @@ async function recall(query, ctx, options = {}) {
     return { memories: [], usedBudget, reranked: false, candidateCount: 0 };
   }
   const needsChunkEmbedding = types.includes("chunk") && ctx.storageCtx;
-  const wantsTemporal = types.includes("fact") && ctx.vaultCtx;
+  const wantsTemporal = types.includes("fact") && (ctx.factSource || ctx.vaultCtx);
   const graphRefiner = flags.traverse && options.graphRefine && options.decomposeOptions ? createLlmNeighborRefiner(options.decomposeOptions) : void 0;
   const queryEmbedTotalTimeoutMs = options.queryEmbedTotalTimeoutMs ?? DEFAULT_QUERY_EMBED_TOTAL_TIMEOUT_MS;
   const prepStart = nowMs2();
@@ -33714,7 +33931,7 @@ async function recall(query, ctx, options = {}) {
     safeLane(
       "graph",
       () => graphLaneFailed = true,
-      () => buildGraphLaneRanking(query, ctx, flags.traverse, {
+      () => ctx.factSource ? ctx.factSource.graphRanking(query, flags.traverse, options) : buildGraphLaneRanking(query, ctx, flags.traverse, {
         ...options.maxHops !== void 0 && { maxHops: options.maxHops },
         ...options.entityFanout !== void 0 && { entityFanout: options.entityFanout },
         ...options.nodeBudget !== void 0 && { nodeBudget: options.nodeBudget },
@@ -33725,13 +33942,13 @@ async function recall(query, ctx, options = {}) {
     wantsTemporal ? safeLane(
       "temporal",
       () => temporalLaneFailed = true,
-      () => buildTemporalLaneRanking(query, ctx.vaultCtx, options.now)
+      () => ctx.factSource ? ctx.factSource.temporalRanking(query, options.now) : buildTemporalLaneRanking(query, ctx.vaultCtx, options.now)
     ) : Promise.resolve([])
   ]);
   prepMs = nowMs2() - prepStart;
   graphLaneCount = entityRanking.length;
   temporalLaneCount = temporalRanking.length;
-  if (types.includes("fact") && ctx.vaultCtx && ctx.vaultCache) {
+  if (types.includes("fact") && (ctx.factSource || ctx.vaultCtx && ctx.vaultCache)) {
     const factStart = nowMs2();
     const vaultMinScore = options.minScore ?? DEFAULT_FACT_MIN_SCORE;
     factFloor = vaultMinScore;
@@ -33747,50 +33964,50 @@ async function recall(query, ctx, options = {}) {
       rankedOnCosine: factRankedOnCosine,
       decryptLast: factDecryptLast,
       rowsDecrypted: factRowsDecrypted
-    } = await searchVaultMemoriesWithSize(
-      query,
+    } = await (ctx.factSource?.search.bind(ctx.factSource) ?? ((searchQuery, searchOptions) => searchVaultMemoriesWithSize(
+      searchQuery,
       ctx.vaultCtx,
       ctx.embeddingOptions,
       ctx.vaultCache,
-      {
-        limit: types.includes("chunk") ? Math.max(limit * 2, 16) : limit,
-        minSimilarity: vaultMinScore,
-        useFusion: true,
-        rerank: flags.rerank,
-        ...options.rerankTopN !== void 0 && { rerankTopN: options.rerankTopN },
-        ...options.ceWeight !== void 0 && { ceWeight: options.ceWeight },
-        ...options.rerankLoadTimeoutMs !== void 0 && {
-          rerankLoadTimeoutMs: options.rerankLoadTimeoutMs
-        },
-        ...options.recencyAlpha !== void 0 && { recencyAlpha: options.recencyAlpha },
-        ...options.recency && { recency: options.recency },
-        ...options.mmr !== void 0 && { mmr: options.mmr },
-        ...options.supersessionBoost !== void 0 && {
-          supersessionBoost: options.supersessionBoost
-        },
-        ...options.supersessionWindow !== void 0 && {
-          supersessionWindow: options.supersessionWindow
-        },
-        ...options.proofCountAlpha !== void 0 && {
-          proofCountAlpha: options.proofCountAlpha
-        },
-        ...options.bm25AdmissionDivisor !== void 0 && {
-          bm25AdmissionDivisor: options.bm25AdmissionDivisor
-        },
-        ...options.rrfK !== void 0 && { rrfK: options.rrfK },
-        ...options.decryptLast !== void 0 && { decryptLast: options.decryptLast },
-        ...subQueries && { subQueries },
-        ...options.scopes && { scopes: options.scopes },
-        ...options.folderId !== void 0 && { folderId: options.folderId },
-        ...options.factTypes?.length && { factTypes: options.factTypes },
-        ...options.memoryIds !== void 0 && { memoryIds: options.memoryIds },
-        ...options.factTypeWeights && { factTypeWeights: options.factTypeWeights },
-        ...entityRanking.length > 0 && { entityRanking },
-        ...temporalRanking.length > 0 && { temporalRanking },
-        ...needsChunkEmbedding && { queryEmbedding: queryEmbedding ?? [] },
-        queryEmbedTotalTimeoutMs
-      }
-    );
+      searchOptions
+    )))(query, {
+      limit: types.includes("chunk") ? Math.max(limit * 2, 16) : limit,
+      minSimilarity: vaultMinScore,
+      useFusion: true,
+      rerank: flags.rerank,
+      ...options.rerankTopN !== void 0 && { rerankTopN: options.rerankTopN },
+      ...options.ceWeight !== void 0 && { ceWeight: options.ceWeight },
+      ...options.rerankLoadTimeoutMs !== void 0 && {
+        rerankLoadTimeoutMs: options.rerankLoadTimeoutMs
+      },
+      ...options.recencyAlpha !== void 0 && { recencyAlpha: options.recencyAlpha },
+      ...options.recency && { recency: options.recency },
+      ...options.mmr !== void 0 && { mmr: options.mmr },
+      ...options.supersessionBoost !== void 0 && {
+        supersessionBoost: options.supersessionBoost
+      },
+      ...options.supersessionWindow !== void 0 && {
+        supersessionWindow: options.supersessionWindow
+      },
+      ...options.proofCountAlpha !== void 0 && {
+        proofCountAlpha: options.proofCountAlpha
+      },
+      ...options.bm25AdmissionDivisor !== void 0 && {
+        bm25AdmissionDivisor: options.bm25AdmissionDivisor
+      },
+      ...options.rrfK !== void 0 && { rrfK: options.rrfK },
+      ...options.decryptLast !== void 0 && { decryptLast: options.decryptLast },
+      ...subQueries && { subQueries },
+      ...options.scopes && { scopes: options.scopes },
+      ...options.folderId !== void 0 && { folderId: options.folderId },
+      ...options.factTypes?.length && { factTypes: options.factTypes },
+      ...options.memoryIds !== void 0 && { memoryIds: options.memoryIds },
+      ...options.factTypeWeights && { factTypeWeights: options.factTypeWeights },
+      ...entityRanking.length > 0 && { entityRanking },
+      ...temporalRanking.length > 0 && { temporalRanking },
+      ...needsChunkEmbedding && { queryEmbedding: queryEmbedding ?? [] },
+      queryEmbedTotalTimeoutMs
+    });
     factResults.push(
       ...dedupeBy(
         results,
@@ -38547,7 +38764,10 @@ function serverPlatformStorage() {
   MAX_HOPS,
   MAX_MESSAGES_PER_SUMMARIZATION,
   MEDIUM_TTL_MS,
+  MEMORY_KINDS,
+  MEMORY_LEVELS,
   Media,
+  MemoryLevelError,
   Message,
   ModelPreference,
   NEVER_TTL_MS,