@anuma/sdk 6.37.0 → 6.39.0

package/dist/expo/index.cjs

@@ -3356,7 +3356,7 @@ function extractUserMessageFromMessages(messages) {
 }
 
 // src/lib/db/chat/operations.ts
-function messageToStoredRaw(message, projection) {
+function messageToStoredRaw(message, projection2) {
   const convId = String(message._getRaw("conversation_id"));
   const parseJsonField = (rawValue) => {
     if (!rawValue) return void 0;
@@ -3370,7 +3370,7 @@ function messageToStoredRaw(message, projection) {
     }
     return rawValue;
   };
-  const skipEmbeddings = projection?.skipEmbeddings === true;
+  const skipEmbeddings = projection2?.skipEmbeddings === true;
   const sourcesRaw = message._getRaw("sources");
   const vectorRaw = skipEmbeddings ? null : message._getRaw("vector");
   const chunksRaw = skipEmbeddings ? null : message._getRaw("chunks");
@@ -3404,8 +3404,8 @@ function messageToStoredRaw(message, projection) {
     origin: message.origin
   };
 }
-async function messageToStored(message, walletAddress, signMessage, embeddedWalletSigner, projection) {
-  const baseMessage = messageToStoredRaw(message, projection);
+async function messageToStored(message, walletAddress, signMessage, embeddedWalletSigner, projection2) {
+  const baseMessage = messageToStoredRaw(message, projection2);
   if (walletAddress) {
     return await decryptMessageFields(
       baseMessage,
@@ -3419,7 +3419,7 @@ async function messageToStored(message, walletAddress, signMessage, embeddedWall
 function rawDate(value) {
   return new Date(typeof value === "number" ? value : 0);
 }
-function messageRawToStoredRaw(raw, projection) {
+function messageRawToStoredRaw(raw, projection2) {
   const parseJsonField = (rawValue) => {
     if (!rawValue) return void 0;
     if (typeof rawValue === "string") {
@@ -3432,7 +3432,7 @@ function messageRawToStoredRaw(raw, projection) {
     }
     return rawValue;
   };
-  const skipEmbeddings = projection?.skipEmbeddings === true;
+  const skipEmbeddings = projection2?.skipEmbeddings === true;
   const vectorRaw = skipEmbeddings ? null : raw.vector;
   const chunksRaw = skipEmbeddings ? null : raw.chunks;
   return {
@@ -3463,8 +3463,8 @@ function messageRawToStoredRaw(raw, projection) {
     origin: raw.origin
   };
 }
-async function messageRawToStored(raw, walletAddress, signMessage, embeddedWalletSigner, projection) {
-  const baseMessage = messageRawToStoredRaw(raw, projection);
+async function messageRawToStored(raw, walletAddress, signMessage, embeddedWalletSigner, projection2) {
+  const baseMessage = messageRawToStoredRaw(raw, projection2);
   if (walletAddress) {
     return await decryptMessageFields(
       baseMessage,
@@ -12997,22 +12997,35 @@ async function vaultMemoryRawToStored(raw, walletAddress, signMessage, embeddedW
   return stored2;
 }
 async function getAllVaultMemoriesOp(ctx, options) {
-  const conditions = [
+  const results = await ctx.vaultMemoryCollection.query(...vaultListConditions(ctx, options), ...vaultListOrder(options)).unsafeFetchRaw();
+  return mapInBatches(
+    results,
+    (raw) => vaultMemoryRawToStored(raw, ctx.walletAddress, ctx.signMessage, ctx.embeddedWalletSigner)
+  );
+}
+function vaultListConditions(ctx, options) {
+  return [
     ...baseVaultConditions(ctx, options),
     ...options?.scopes?.length ? [import_watermelondb20.Q.where("scope", import_watermelondb20.Q.oneOf(options.scopes))] : [],
     ...visibilityConditions(options?.visibility),
     ...levelConditions(options?.levels),
     ...options?.kinds?.length ? [import_watermelondb20.Q.where("kind", import_watermelondb20.Q.oneOf(options.kinds))] : [],
     ...options?.folderId !== void 0 ? [import_watermelondb20.Q.where("folder_id", options.folderId)] : [],
-    ...options?.factTypes?.length ? [import_watermelondb20.Q.where("fact_type", import_watermelondb20.Q.oneOf(options.factTypes))] : [],
+    ...options?.factTypes?.length ? [import_watermelondb20.Q.where("fact_type", import_watermelondb20.Q.oneOf(options.factTypes))] : []
+  ];
+}
+function vaultListOrder(options) {
+  return [
     import_watermelondb20.Q.sortBy(options?.since ? "updated_at" : "created_at", import_watermelondb20.Q.desc),
     ...options?.limit !== null && options?.limit !== void 0 && options.limit > 0 ? [import_watermelondb20.Q.take(options.limit)] : []
   ];
-  const results = await ctx.vaultMemoryCollection.query(...conditions).unsafeFetchRaw();
-  return mapInBatches(
-    results,
-    (raw) => vaultMemoryRawToStored(raw, ctx.walletAddress, ctx.signMessage, ctx.embeddedWalletSigner)
-  );
+}
+async function getVaultMemoryProjectionsOp(ctx, options) {
+  const results = await ctx.vaultMemoryCollection.query(...vaultListConditions(ctx, options), ...vaultListOrder(options)).unsafeFetchRaw();
+  return results.map((raw) => ({
+    ...vaultMemoryRawToRankable(raw),
+    topicsUserManaged: raw.topics_user_managed === true || raw.topics_user_managed === 1
+  }));
 }
 function vaultMemoryRawToRankable(raw) {
   return {
@@ -18692,7 +18705,6 @@ async function recall(query, ctx, options = {}) {
   }
   const needsChunkEmbedding = types.includes("chunk") && ctx.storageCtx;
   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();
   let sharedEmbedMs = 0;
@@ -18721,13 +18733,12 @@ async function recall(query, ctx, options = {}) {
     safeLane(
       "graph",
       () => graphLaneFailed = true,
-      () => 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 },
-        ...options.rrfK !== void 0 && { rrfK: options.rrfK },
-        ...graphRefiner && { refineNeighbors: graphRefiner }
-      })
+      () => ctx.factSource ? ctx.factSource.graphRanking(query, flags.traverse, options) : buildGraphLaneRanking(
+        query,
+        ctx,
+        flags.traverse,
+        graphTraversalOptions(options, flags.traverse)
+      )
     ),
     wantsTemporal ? safeLane(
       "temporal",
@@ -18946,6 +18957,16 @@ function toFactMemory(r, now) {
     updatedAt: r.updatedAt ?? /* @__PURE__ */ new Date(0)
   };
 }
+function graphTraversalOptions(options, traverse) {
+  const refineNeighbors = traverse && options.graphRefine && options.decomposeOptions ? createLlmNeighborRefiner(options.decomposeOptions) : void 0;
+  return {
+    ...options.maxHops !== void 0 && { maxHops: options.maxHops },
+    ...options.entityFanout !== void 0 && { entityFanout: options.entityFanout },
+    ...options.nodeBudget !== void 0 && { nodeBudget: options.nodeBudget },
+    ...options.rrfK !== void 0 && { rrfK: options.rrfK },
+    ...refineNeighbors && { refineNeighbors }
+  };
+}
 async function buildGraphLaneRanking(query, ctx, traverse = false, traversalOptions = {}) {
   const entityCtx = ctx.entityCtx ?? ctx.vaultCtx?.entityCtx;
   if (!entityCtx) return [];
@@ -19111,24 +19132,33 @@ function isDumpQuery(query) {
   return false;
 }
 async function listRecentFacts(ctx, limit, toolOptions) {
+  const store = toolOptions?.memoryStore;
   const vaultCtx = ctx.vaultCtx;
-  if (!vaultCtx) return [];
-  const ordered = await getVaultRankingProjectionsOp(vaultCtx, {
+  if (!vaultCtx && !store) return [];
+  const read = (ids) => store ? store.list({ memoryIds: ids }) : getVaultMemoriesByIdsOp(vaultCtx, ids);
+  const filters = {
     ...toolOptions?.scopes && { scopes: toolOptions.scopes },
-    ...toolOptions?.memoryIds !== void 0 && { memoryIds: toolOptions.memoryIds },
+    ...toolOptions?.memoryIds !== void 0 && { memoryIds: toolOptions.memoryIds }
+  };
+  const project = (size) => store ? store.listProjections({ ...filters, limit: size }) : getVaultRankingProjectionsOp(vaultCtx, {
+    ...filters,
     ...toolOptions?.folderId !== void 0 && { folderId: toolOptions.folderId }
   });
   const readable = [];
-  for (let i = 0; i < ordered.length && readable.length < limit; i += limit) {
-    const batch = ordered.slice(i, i + limit).map((p) => p.uniqueId);
-    const byId = new Map(
-      (await getVaultMemoriesByIdsOp(vaultCtx, batch)).map((m) => [m.uniqueId, m])
-    );
-    for (const id of batch) {
-      const m = byId.get(id);
-      if (m && !isEncrypted(m.content)) readable.push(m);
-      if (readable.length >= limit) break;
+  let start = 0;
+  for (let size = limit; readable.length < limit; size *= 2) {
+    const ordered = await project(size);
+    for (let i = start; i < ordered.length && readable.length < limit; i += limit) {
+      const batch = ordered.slice(i, i + limit).map((p) => p.uniqueId);
+      const byId = new Map((await read(batch)).map((m) => [m.uniqueId, m]));
+      for (const id of batch) {
+        const m = byId.get(id);
+        if (m && !isEncrypted(m.content)) readable.push(m);
+        if (readable.length >= limit) break;
+      }
     }
+    if (!store || ordered.length < size) break;
+    start = ordered.length;
   }
   return readable.map((m) => ({
     id: m.uniqueId,
@@ -19145,6 +19175,8 @@ async function listRecentFacts(ctx, limit, toolOptions) {
   }));
 }
 function createRecallTool(ctx, toolOptions, callbacks) {
+  if (toolOptions?.memoryStore && toolOptions.folderId !== void 0)
+    throw new Error("Folders are not supported with a memoryStore");
   const defaultTypes = toolOptions?.types ?? ["fact", "chunk"];
   const defaultLimit = toolOptions?.limit ?? DEFAULT_LIMIT2;
   const defaultBudget = toolOptions?.budget ?? DEFAULT_BUDGET2;
@@ -19216,7 +19248,7 @@ function createRecallTool(ctx, toolOptions, callbacks) {
       let surfaced = 0;
       try {
         let recallDegraded = [];
-        const wantsRecent = args.sort === "recent" && defaultTypes.includes("fact") && ctx.vaultCtx !== void 0;
+        const wantsRecent = args.sort === "recent" && defaultTypes.includes("fact") && (ctx.vaultCtx !== void 0 || toolOptions?.memoryStore !== void 0);
         let result;
         if (wantsRecent) {
           result = { memories: await listRecentFacts(ctx, effectiveLimit, toolOptions) };
@@ -19693,6 +19725,7 @@ function createLocalMemoryStore(options) {
   };
   const vaultCache = options.vaultCache ?? createVaultEmbeddingCache();
   const ownedBy = userId !== void 0 ? [import_watermelondb23.Q.where("user_id", userId)] : [];
+  const linksOwnedBy = userId === void 0 ? [] : options.allowUnscopedRows ? [import_watermelondb23.Q.or(import_watermelondb23.Q.where("user_id", userId), import_watermelondb23.Q.where("user_id", null))] : [import_watermelondb23.Q.where("user_id", userId)];
   const watchedColumns = [
     "content",
     "scope",
@@ -19725,6 +19758,7 @@ function createLocalMemoryStore(options) {
     });
   };
   return {
+    masksEmbeddingInput: options.embeddingOptions.maskInput !== void 0,
     list: (listOptions) => getAllVaultMemoriesOp(vaultCtx, listOptions),
     get: (id) => getVaultMemoryOp(vaultCtx, id),
     listArchived: async () => {
@@ -19735,6 +19769,29 @@ function createLocalMemoryStore(options) {
     },
     memoriesByTopics: (names) => getMemoriesByEntityNamesOp(entityCtx, names),
     topicsByMemories: (memoryIds) => getEntitiesByMemoryIdsOp(entityCtx, memoryIds),
+    listTopics: async () => {
+      const links = await entityCtx.memoryEntityCollection.query(...linksOwnedBy).fetch();
+      const members = /* @__PURE__ */ new Map();
+      for (const link of links) {
+        const entityId = String(link.entityId);
+        const set = members.get(entityId) ?? /* @__PURE__ */ new Set();
+        set.add(String(link.memoryId));
+        members.set(entityId, set);
+      }
+      const entities = userId === void 0 ? await entityCtx.entityCollection.query().fetch() : members.size ? await entityCtx.entityCollection.query(import_watermelondb23.Q.where("id", import_watermelondb23.Q.oneOf([...members.keys()]))).fetch() : [];
+      const byName = /* @__PURE__ */ new Map();
+      for (const entity of entities) {
+        const count2 = members.get(entity.id)?.size ?? 0;
+        const existing = byName.get(entity.canonicalName);
+        byName.set(entity.canonicalName, {
+          name: entity.canonicalName,
+          kind: existing?.kind ?? entity.kind ?? null,
+          memoryCount: (existing?.memoryCount ?? 0) + count2
+        });
+      }
+      return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+    },
+    listProjections: (listOptions) => getVaultMemoryProjectionsOp(vaultCtx, listOptions),
     create: async (input) => {
       const created = await createVaultMemoryOp(vaultCtx, input);
       if (input.embedding === void 0) embedInBackground(created);
@@ -19783,6 +19840,22 @@ function createLocalMemoryStore(options) {
       { vaultCtx, embeddingOptions: options.embeddingOptions, vaultCache },
       retainOptions
     ),
+    factSource: {
+      search: (query, searchOptions) => searchVaultMemoriesWithSize(
+        query,
+        vaultCtx,
+        options.embeddingOptions,
+        vaultCache,
+        searchOptions
+      ),
+      graphRanking: (query, traverse, recallOptions) => buildGraphLaneRanking(
+        query,
+        { vaultCtx, entityCtx, embeddingOptions: options.embeddingOptions },
+        traverse,
+        graphTraversalOptions(recallOptions, traverse)
+      ),
+      temporalRanking: (query, now) => buildTemporalLaneRanking(query, vaultCtx, now)
+    },
     subscribe: (onChange, subscribeOptions) => {
       const afterFirst = () => {
         let first = true;
@@ -19796,7 +19869,6 @@ function createLocalMemoryStore(options) {
       );
       const subscriptions = [memories.subscribe(afterFirst())];
       if (subscribeOptions?.topics) {
-        const linksOwnedBy = userId === void 0 ? [] : options.allowUnscopedRows ? [import_watermelondb23.Q.or(import_watermelondb23.Q.where("user_id", userId), import_watermelondb23.Q.where("user_id", null))] : [import_watermelondb23.Q.where("user_id", userId)];
         subscriptions.push(
           entityCtx.memoryEntityCollection.query(...linksOwnedBy).observe().subscribe(afterFirst())
         );
@@ -20206,6 +20278,31 @@ async function createRemoteMemoryPersistence(options) {
       throw new Error("Invalid nearby candidate response");
     return result;
   };
+  const fetchQueryPage = async (queryOptions) => {
+    const { signal, ...query } = queryOptions;
+    if (query.limit !== void 0 && (!Number.isInteger(query.limit) || query.limit < 1 || query.limit > 200))
+      throw new Error("Page limit must be 1\u2013200");
+    for (const [key, max] of queryListLimits) {
+      const values = query[key];
+      if (values && values.length > max)
+        throw new Error(`Query ${key} accepts at most ${max} entries (got ${values.length})`);
+    }
+    const page = await request(
+      "/memories/query",
+      {
+        method: "POST",
+        body: JSON.stringify(
+          Object.fromEntries(
+            queryFields.filter((key) => query[key] !== void 0).map((key) => [key, query[key]])
+          )
+        )
+      },
+      signal
+    );
+    if (!record(page) || !Array.isArray(page.items) || page.next_cursor !== void 0 && typeof page.next_cursor !== "string" || page.changes_cursor !== void 0 && typeof page.changes_cursor !== "string")
+      throw new Error("Invalid nearby private-memory page");
+    return page;
+  };
   const candidateSet = async (embedding, candidateOptions = {}) => {
     const result = await fetchCandidates(embedding, candidateOptions, true);
     if (!Number.isSafeInteger(result.total_count) || result.total_count < 0 || !Number.isSafeInteger(result.unavailable_count) || result.unavailable_count < 0)
@@ -20284,34 +20381,27 @@ async function createRemoteMemoryPersistence(options) {
       return Promise.all(result.items.map((item, i) => decodeCommitted(item, prepared[i])));
     },
     query: async (queryOptions = {}) => {
-      const { signal, ...query } = queryOptions;
-      if (query.limit !== void 0 && (!Number.isInteger(query.limit) || query.limit < 1 || query.limit > 200))
-        throw new Error("Page limit must be 1\u2013200");
-      for (const [key, max] of queryListLimits) {
-        const values = query[key];
-        if (values && values.length > max)
-          throw new Error(`Query ${key} accepts at most ${max} entries (got ${values.length})`);
-      }
-      const page = await request(
-        "/memories/query",
-        {
-          method: "POST",
-          body: JSON.stringify(
-            Object.fromEntries(
-              queryFields.filter((key) => query[key] !== void 0).map((key) => [key, query[key]])
-            )
-          )
-        },
-        signal
-      );
-      if (!record(page) || !Array.isArray(page.items) || page.next_cursor !== void 0 && typeof page.next_cursor !== "string" || page.changes_cursor !== void 0 && typeof page.changes_cursor !== "string")
-        throw new Error("Invalid nearby private-memory page");
+      const page = await fetchQueryPage(queryOptions);
       return {
         ...await decodeAll(page.items),
         ...page.next_cursor !== void 0 && { next_cursor: page.next_cursor },
         ...page.changes_cursor !== void 0 && { changes_cursor: page.changes_cursor }
       };
     },
+    queryMetadata: async (queryOptions = {}) => {
+      const page = await fetchQueryPage(queryOptions);
+      return {
+        items: page.items.map((item) => {
+          const {
+            memory: { content: _content, kind_value: _kindValue, ...memory },
+            version,
+            server_updated_at
+          } = memoryRecord(item);
+          return { memory, version, server_updated_at };
+        }),
+        ...page.next_cursor !== void 0 && { next_cursor: page.next_cursor }
+      };
+    },
     candidateSet,
     candidates: async (embedding, candidateOptions = {}) => decodeAll((await fetchCandidates(embedding, candidateOptions, false)).items)
   };
@@ -20653,38 +20743,31 @@ function createRemoteMemoryPipeline(options) {
     };
     return { prepare, port };
   };
-  return {
-    recall: async (query, recallOptions = {}) => {
+  const factSource = {
+    graphRanking: options.graphRanking,
+    temporalRanking: options.temporalRanking,
+    search: async (text13, searchOptions) => {
       const { prepare } = operation("recall");
-      return recall(
-        query,
-        {
-          embeddingOptions,
-          factSource: {
-            graphRanking: options.graphRanking,
-            temporalRanking: options.temporalRanking,
-            search: async (text13, searchOptions) => {
-              const prepared = await prepare(text13, searchOptions);
-              const ranked = await rankPreparedVaultCandidates(
-                text13,
-                prepared,
-                embeddingOptions,
-                searchOptions
-              );
-              return {
-                ...ranked,
-                rankedOnCosine: prepared.memories.length > 0 && !prepared.embeddingsUnavailable,
-                decryptLast: true,
-                rowsDecrypted: prepared.rowsDecrypted,
-                queryEmbedMs: prepared.queryEmbedMs,
-                rowsEmbedded: 0
-              };
-            }
-          }
-        },
-        { ...recallOptions, types: ["fact"] }
+      const prepared = await prepare(text13, searchOptions);
+      const ranked = await rankPreparedVaultCandidates(
+        text13,
+        prepared,
+        embeddingOptions,
+        searchOptions
       );
-    },
+      return {
+        ...ranked,
+        rankedOnCosine: prepared.memories.length > 0 && !prepared.embeddingsUnavailable,
+        decryptLast: true,
+        rowsDecrypted: prepared.rowsDecrypted,
+        queryEmbedMs: prepared.queryEmbedMs,
+        rowsEmbedded: 0
+      };
+    }
+  };
+  return {
+    factSource,
+    recall: async (query, recallOptions = {}) => recall(query, { embeddingOptions, factSource }, { ...recallOptions, types: ["fact"] }),
     retain: async (content, retainOptions) => {
       const { port } = operation("retain");
       return retainWithPersistence(
@@ -20704,6 +20787,19 @@ function createRemoteMemoryPipeline(options) {
 // src/lib/memory/store/remoteStore.ts
 var import_uuid5 = require("uuid");
 init_logger();
+function projection({ memory }) {
+  return {
+    uniqueId: memory.memory_id,
+    scope: memory.scope,
+    folderId: memory.folder_id ?? null,
+    embedding: memory.embedding?.length ? JSON.stringify(memory.embedding) : null,
+    embeddingModel: memory.embedding_model ?? null,
+    createdAt: new Date(memory.created_at),
+    updatedAt: new Date(memory.updated_at),
+    lastObservedAt: memory.last_observed_at ?? null,
+    topicsUserManaged: memory.topics_user_managed ?? false
+  };
+}
 function relevant(change, options) {
   return options.includeDeleted ? change === "membership" : change !== "embedding" || !!options.embeddings;
 }
@@ -20738,6 +20834,9 @@ function bounded(filters, key) {
   if (!values || values.length <= MAX_QUERY_FILTER) return [filters];
   return chunks(values, MAX_QUERY_FILTER).map((chunk) => ({ ...filters, [key]: chunk }));
 }
+function maxOf(options) {
+  return options.limit && options.limit > 0 ? options.limit : Infinity;
+}
 function chunks(values, size) {
   const out = [];
   for (let i = 0; i < values.length; i += size) out.push(values.slice(i, i + size));
@@ -20809,26 +20908,49 @@ function createRemoteMemoryStore(options) {
     for (const subscriber of [...subscribers])
       if (relevant(change, subscriber.options)) safely(subscriber.onChange);
   };
-  const enumerate = async (filters, max = Infinity) => {
+  const pages = async (read, filters, max = Infinity) => {
     const records = [];
     let cursor2;
     do {
-      const page = await persistence.query({
+      const page = await read({
         ...filters,
         limit: Math.min(200, Math.max(1, max - records.length)),
         ...cursor2 && { cursor: cursor2 }
       });
-      warnFailed(page.failed);
+      if (page.failed) warnFailed(page.failed);
       records.push(...page.items);
       cursor2 = page.next_cursor;
     } while (cursor2 && records.length < max);
     return records.slice(0, max);
   };
-  const enumerateIds = async (ids, filters) => (await Promise.all(
+  const decrypted = (options2) => persistence.query(options2);
+  const metadata = (options2) => persistence.queryMetadata(options2);
+  const enumerate = (filters, max = Infinity) => pages(decrypted, filters, max);
+  const enumerateIds = async (read, ids, filters) => (await Promise.all(
     chunks([...new Set(ids)], MAX_QUERY_IDS).map(
-      (memory_ids) => enumerate({ ...filters, memory_ids })
+      (memory_ids) => pages(read, { ...filters, memory_ids })
     )
   )).flat();
+  const listFilters = (listOptions) => ({
+    ...stateFilters(listOptions),
+    include_embeddings: true,
+    order: listOptions.since ? "updated" : "created",
+    ...listOptions.scopes?.length && { scopes: listOptions.scopes },
+    ...listOptions.factTypes?.length && { fact_types: listOptions.factTypes },
+    ...listOptions.visibility?.length && { visibility: listOptions.visibility },
+    ...listOptions.since && { updated_after: listOptions.since.getTime() }
+  });
+  const listRows = async (read, listOptions, filters, max) => {
+    const variants = bounded(filters, "scopes").flatMap((f) => bounded(f, "fact_types"));
+    if (!listOptions.memoryIds && variants.length === 1) return pages(read, filters, max);
+    const fetched = await Promise.all(
+      variants.map(
+        (variant) => listOptions.memoryIds ? enumerateIds(read, listOptions.memoryIds, variant) : pages(read, variant, max)
+      )
+    );
+    const time = (row) => filters.order === "updated" ? row.memory.updated_at : row.memory.created_at;
+    return [...new Map(fetched.flat().map((r) => [r.memory.memory_id, r])).values()].sort((a, b) => time(b) - time(a) || (a.memory.memory_id < b.memory.memory_id ? 1 : -1)).slice(0, max);
+  };
   const queues = /* @__PURE__ */ new Map();
   const serialized = (id, task) => {
     const run = (queues.get(id) ?? Promise.resolve()).then(task, task);
@@ -20870,12 +20992,15 @@ function createRemoteMemoryStore(options) {
   };
   const newRow = (input) => {
     const now = Date.now();
-    const scope = input.scope ?? "private";
+    const { level, scope } = resolveCreateLevel(input);
+    assertValidKindLevel(input.kind, level);
     return {
       memory_id: (0, import_uuid5.v7)(),
       content: input.content,
       scope,
-      level: levelFromScope(scope),
+      level,
+      ...input.kind !== void 0 && input.kind !== null && { kind: input.kind },
+      ...typeof input.kindValue === "string" && { kind_value: input.kindValue },
       created_at: now,
       updated_at: now,
       is_deleted: false,
@@ -20904,6 +21029,30 @@ function createRemoteMemoryStore(options) {
     return records.map((record2) => stored(record2.memory));
   };
   const asStored = (record2) => record2 ? stored(record2.memory) : null;
+  const withKnownKinds = async (topics) => {
+    const unkinded = [
+      ...new Set(topics.filter((t) => !t.kind).map((t) => normalizeEntityName(t.name)))
+    ];
+    if (unkinded.length === 0) return topics;
+    const kinds = /* @__PURE__ */ new Map();
+    for (const names of chunks(unkinded, MAX_QUERY_TOPICS)) {
+      for (const { memory } of await pages(metadata, {
+        topics: names,
+        include_archived: true,
+        include_quarantined: true,
+        include_superseded: true
+      })) {
+        for (const topic of parseTopics(memory.topics) ?? []) {
+          const name = normalizeEntityName(topic.name);
+          if (topic.kind && !kinds.has(name)) kinds.set(name, topic.kind);
+        }
+      }
+    }
+    return topics.map((topic) => {
+      const kind = topic.kind ?? kinds.get(normalizeEntityName(topic.name));
+      return kind ? { ...topic, kind } : topic;
+    });
+  };
   const everyState = {
     include_deleted: true,
     include_archived: true,
@@ -20980,30 +21129,35 @@ function createRemoteMemoryStore(options) {
     });
   };
   return {
-    list: async (listOptions = {}) => {
-      const order = listOptions.since ? "updated" : "created";
-      const filters = {
-        ...stateFilters(listOptions),
-        include_embeddings: true,
-        order,
-        ...listOptions.scopes?.length && { scopes: listOptions.scopes },
-        ...listOptions.factTypes?.length && { fact_types: listOptions.factTypes },
-        ...listOptions.visibility?.length && { visibility: listOptions.visibility },
-        ...listOptions.since && { updated_after: listOptions.since.getTime() }
-      };
-      const max = listOptions.limit && listOptions.limit > 0 ? listOptions.limit : Infinity;
-      const variants = bounded(filters, "scopes").flatMap((f) => bounded(f, "fact_types"));
-      if (!listOptions.memoryIds && variants.length === 1)
-        return (await enumerate(filters, max)).map((r) => stored(r.memory));
-      const fetched = await Promise.all(
-        variants.map(
-          (variant) => listOptions.memoryIds ? enumerateIds(listOptions.memoryIds, variant) : enumerate(variant, max)
-        )
-      );
-      const rows = [...new Map(fetched.flat().map((r) => [r.memory.memory_id, r])).values()].map((record2) => stored(record2.memory)).sort(
-        (a, b) => order === "updated" ? b.updatedAt.getTime() - a.updatedAt.getTime() || (a.uniqueId < b.uniqueId ? 1 : -1) : b.createdAt.getTime() - a.createdAt.getTime() || (a.uniqueId < b.uniqueId ? 1 : -1)
-      );
-      return rows.slice(0, max);
+    masksEmbeddingInput: embeddingOptions.maskInput !== void 0,
+    list: async (listOptions = {}) => (await listRows(decrypted, listOptions, listFilters(listOptions), maxOf(listOptions))).map(
+      (r) => stored(r.memory)
+    ),
+    listProjections: async (listOptions = {}) => (await listRows(metadata, listOptions, listFilters(listOptions), maxOf(listOptions))).map(
+      projection
+    ),
+    listTopics: async () => {
+      const topics = /* @__PURE__ */ new Map();
+      for (const { memory } of await pages(metadata, {
+        include_archived: true,
+        include_quarantined: true,
+        include_superseded: true
+      })) {
+        for (const topic of parseTopics(memory.topics) ?? []) {
+          const name = normalizeEntityName(topic.name);
+          if (!name) continue;
+          const entry = topics.get(name) ?? {
+            name,
+            kind: null,
+            memoryCount: 0,
+            members: /* @__PURE__ */ new Set()
+          };
+          entry.kind ?? (entry.kind = topic.kind ?? null);
+          entry.members.add(memory.memory_id);
+          topics.set(name, entry);
+        }
+      }
+      return [...topics.values()].map(({ members, ...topic }) => ({ ...topic, memoryCount: members.size })).sort((a, b) => a.name.localeCompare(b.name));
     },
     get: async (id) => asStored(await live(id)),
     listArchived: async () => (await enumerate({ archived_only: true, order: "archived", include_embeddings: true })).map(
@@ -21012,10 +21166,10 @@ function createRemoteMemoryStore(options) {
     memoriesByTopics: async (names) => {
       const wanted = new Set(names.map(normalizeEntityName).filter(Boolean));
       const out = /* @__PURE__ */ new Map();
-      const pages = await Promise.all(
+      const pages2 = await Promise.all(
         chunks([...wanted], MAX_QUERY_TOPICS).map((topics) => enumerate({ topics }))
       );
-      for (const { memory } of pages.flat()) {
+      for (const { memory } of pages2.flat()) {
         const matched = [...canonicalTopics(memory)].filter((name) => wanted.has(name));
         if (matched.length) out.set(memory.memory_id, new Set(matched));
       }
@@ -21023,7 +21177,7 @@ function createRemoteMemoryStore(options) {
     },
     topicsByMemories: async (memoryIds) => {
       const out = /* @__PURE__ */ new Map();
-      for (const { memory } of await enumerateIds(memoryIds, {
+      for (const { memory } of await enumerateIds(decrypted, memoryIds, {
         include_archived: true,
         include_superseded: true,
         include_quarantined: true
@@ -21056,15 +21210,26 @@ function createRemoteMemoryStore(options) {
     update: async (id, patch) => {
       const saved = await mutate(id, "edit", (memory) => {
         if (memory.superseded_by) return null;
+        const level = patch.level !== void 0 ? patch.level : patch.scope !== void 0 ? levelForScopeChange({ level: memory.level, scope: memory.scope }, patch.scope) : resolveMemoryLevel(memory.level, memory.scope);
+        const kind = patch.kind !== void 0 ? patch.kind : memory.kind;
+        assertValidKindLevel(kind, level);
         memory.content = patch.content;
         memory.updated_at = Date.now();
-        if (patch.scope !== void 0) {
-          memory.level = levelForScopeChange(
-            { level: memory.level, scope: memory.scope },
-            patch.scope
-          );
+        if (patch.level !== void 0) {
+          memory.level = level;
+          memory.scope = scopeForLevel(level);
+        } else if (patch.scope !== void 0) {
+          memory.level = level;
           memory.scope = patch.scope;
         }
+        if (patch.kind !== void 0) {
+          if (patch.kind === null) delete memory.kind;
+          else memory.kind = patch.kind;
+        }
+        if (patch.kindValue !== void 0) {
+          if (patch.kindValue === null) delete memory.kind_value;
+          else memory.kind_value = patch.kindValue;
+        }
         if (patch.factType !== void 0) memory.fact_type = patch.factType ?? void 0;
         if (patch.eventTime !== void 0) {
           memory.event_time_start = patch.eventTime?.start ?? void 0;
@@ -21119,16 +21284,19 @@ function createRemoteMemoryStore(options) {
       notify("edit", [await persistence.put(memory, record2)]);
       return true;
     }),
-    setTopics: async (memoryId, topics) => asStored(
-      await mutate(memoryId, "edit", (memory) => ({
-        ...memory,
-        topics: serializeTopics(mergeTopics([], topicInputs(topics, "user"))),
-        topics_user_managed: true,
-        topics_updated_at: Date.now()
-      }))
-    ),
+    setTopics: async (memoryId, topics) => {
+      const chosen = await withKnownKinds(topicInputs(topics, "user"));
+      return asStored(
+        await mutate(memoryId, "edit", (memory) => ({
+          ...memory,
+          topics: serializeTopics(mergeTopics([], chosen)),
+          topics_user_managed: true,
+          topics_updated_at: Date.now()
+        }))
+      );
+    },
     addTopics: async (memoryId, topics) => {
-      const added = topicInputs(topics, "auto");
+      const added = await withKnownKinds(topicInputs(topics, "auto"));
       const saved = await mutate(memoryId, "edit", (memory) => ({
         ...memory,
         topics: serializeTopics(mergeTopics(parseTopics(memory.topics) ?? [], added)),
@@ -21157,6 +21325,7 @@ function createRemoteMemoryStore(options) {
       })
     ),
     recall: (query, recallOptions) => pipeline.recall(query, recallOptions),
+    factSource: pipeline.factSource,
     retain: async (content, retainOptions) => {
       const result = await pipeline.retain(content, retainOptions);
       if (result.action === "create" || result.action === "supersede") notify("membership");
@@ -22925,19 +23094,20 @@ function createMemoryVaultSearchTool(vaultCtx, embeddingOptions, cache, searchOp
         const budget = wantsDecompose ? "high" : searchOptions?.rerank ? "mid" : "low";
         const folderId = searchOptions?.folderId ?? argFolderId;
         if (searchOptions?.useFusion === false) {
-          const { results: legacy, embeddingsUnavailable } = await searchVaultMemoriesWithSize(
+          const legacyOptions = {
+            limit: requestLimit,
+            minSimilarity,
+            useFusion: false,
+            ...tuningForward,
+            ...folderId !== void 0 && { folderId },
+            ...searchOptions?.scopes && { scopes: searchOptions.scopes }
+          };
+          const { results: legacy, embeddingsUnavailable } = "retain" in vaultCtx ? await vaultCtx.factSource.search(query, legacyOptions) : await searchVaultMemoriesWithSize(
             query,
             vaultCtx,
             embeddingOptions,
             cache,
-            {
-              limit: requestLimit,
-              minSimilarity,
-              useFusion: false,
-              ...tuningForward,
-              ...folderId !== void 0 && { folderId },
-              ...searchOptions?.scopes && { scopes: searchOptions.scopes }
-            }
+            legacyOptions
           );
           if (legacy.length === 0) {
             return embeddingsUnavailable ? EMBEDDINGS_DEGRADED_EMPTY_NO_LEXICAL : "No relevant memories found in the vault.";
@@ -22956,7 +23126,7 @@ function createMemoryVaultSearchTool(vaultCtx, embeddingOptions, cache, searchOp
         let recallDegraded = [];
         const result = await recall(
           query,
-          { vaultCtx, embeddingOptions, vaultCache: cache },
+          "retain" in vaultCtx ? { factSource: vaultCtx.factSource, embeddingOptions } : { vaultCtx, embeddingOptions, vaultCache: cache },
           {
             onDiagnostics: (d) => {
               recallDegraded = d.degraded;
@@ -23036,8 +23206,10 @@ function describeWriteOutcome(outcome2) {
   }
 }
 function createMemoryVaultTool(vaultCtx, options, embeddingOptions, cache) {
+  const store = "retain" in vaultCtx ? vaultCtx : void 0;
+  const ctx = "retain" in vaultCtx ? void 0 : vaultCtx;
   const hasOnSave = !!options?.onSave;
-  const folderNames = options?.folderMap ? Array.from(options.folderMap.keys()) : [];
+  const folderNames = !store && options?.folderMap ? Array.from(options.folderMap.keys()) : [];
   return {
     type: "function",
     function: {
@@ -23082,7 +23254,7 @@ function createMemoryVaultTool(vaultCtx, options, embeddingOptions, cache) {
         let previousContent;
         const scope = options?.scope ?? "private";
         if (isUpdate) {
-          const existing = await getVaultMemoryOp(vaultCtx, id);
+          const existing = store ? await store.get(id) : await getVaultMemoryOp(ctx, id);
           if (!existing) {
             return `Error: Memory with ID "${id}" not found. Creating a new memory instead would require a separate call without an ID.`;
           }
@@ -23103,9 +23275,18 @@ function createMemoryVaultTool(vaultCtx, options, embeddingOptions, cache) {
             return isUpdate ? `Memory update was cancelled by the user. The memory "${id}" was not modified.` : "Memory save was cancelled by the user. No memory was created.";
           }
         }
-        if (isUpdate) {
+        if (isUpdate && store) {
+          const updated = await store.update(id, {
+            content,
+            ...factType !== void 0 && { factType }
+          });
+          if (!updated) {
+            return `Error: Failed to update memory "${id}".`;
+          }
+          return `Memory updated successfully (ID: ${updated.uniqueId}).`;
+        } else if (isUpdate) {
           const folderId = folderName ? options?.folderMap?.get(folderName) : void 0;
-          const updated = await updateVaultMemoryOp(vaultCtx, id, {
+          const updated = await updateVaultMemoryOp(ctx, id, {
             content,
             embedding: null,
             folderId,
@@ -23120,7 +23301,7 @@ function createMemoryVaultTool(vaultCtx, options, embeddingOptions, cache) {
               content,
               embeddingOptions,
               cache,
-              vaultCtx,
+              ctx,
               id,
               updated.updatedAt
             ).catch(() => {
@@ -23140,18 +23321,22 @@ function createMemoryVaultTool(vaultCtx, options, embeddingOptions, cache) {
             await notifyWritten(options, input, outcome2);
             return describeWriteOutcome(outcome2);
           }
-          const created = await createVaultMemoryOp(vaultCtx, {
+          const created = store ? await store.create({
+            content,
+            scope,
+            ...factType !== void 0 && { factType }
+          }) : await createVaultMemoryOp(ctx, {
             content,
             scope,
             folderId,
             ...factType !== void 0 && { factType }
           });
-          if (embeddingOptions && cache) {
+          if (ctx && embeddingOptions && cache) {
             eagerEmbedContent(
               content,
               embeddingOptions,
               cache,
-              vaultCtx,
+              ctx,
               created.uniqueId,
               created.updatedAt
             ).catch(() => {
@@ -25450,6 +25635,8 @@ onClearAllEncryptionState(resetRecentToolSets);
 // src/expo/useChatStorage.ts
 var CONVERSATION_REDACTOR_LIMIT = 50;
 var NO_CONVERSATION_KEY = "__no_conversation__";
+var NO_STORE_FOLDERS = "Folders are not supported with a memoryStore";
+var NO_STORE_MASK = "piiRedaction needs a memoryStore built with embeddingOptions.maskInput";
 var conversationRedactors = /* @__PURE__ */ new Map();
 var clientToolFilterCache = /* @__PURE__ */ new Map();
 function getConversationRedactor(conversationId, nerDetector) {
@@ -25551,6 +25738,7 @@ function useChatStorage(options) {
     signMessage,
     embeddedWalletSigner,
     getWalletAddress,
+    memoryStore,
     enableQueue = true,
     autoFlushOnKeyAvailable = true,
     extraToolSets,
@@ -25591,6 +25779,7 @@ function useChatStorage(options) {
     [resolvedPiiRedaction]
   );
   const maskEmbeddingInput = isPiiRedactor(resolvedPiiRedaction) ? maskForEmbedding : void 0;
+  const storeMaskMissing = memoryStore !== void 0 && maskEmbeddingInput !== void 0 && !memoryStore.masksEmbeddingInput;
   const messagesCollection = (0, import_react5.useMemo)(() => database.get("history"), [database]);
   const conversationsCollection = (0, import_react5.useMemo)(
     () => database.get("conversations"),
@@ -25839,6 +26028,15 @@ function useChatStorage(options) {
   }, [vaultEmbeddingCache]);
   const retainVaultMemory = (0, import_react5.useCallback)(
     async (input) => {
+      if (memoryStore) {
+        if (storeMaskMissing) throw new Error(NO_STORE_MASK);
+        if (input.folderId !== void 0) throw new Error(NO_STORE_FOLDERS);
+        return memoryStore.retain(input.content, {
+          source: "manual",
+          scope: input.scope,
+          ...input.factType !== void 0 && { factType: input.factType }
+        });
+      }
       if (!getToken) {
         throw new Error("getToken is required to retain a vault memory");
       }
@@ -25862,37 +26060,56 @@ function useChatStorage(options) {
         }
       );
     },
-    [vaultCtx, getToken, baseUrl, embeddingModel, maskEmbeddingInput, vaultEmbeddingCache]
+    [
+      vaultCtx,
+      getToken,
+      baseUrl,
+      embeddingModel,
+      maskEmbeddingInput,
+      vaultEmbeddingCache,
+      memoryStore,
+      storeMaskMissing
+    ]
   );
   const createMemoryVaultTool2 = (0, import_react5.useCallback)(
     (options2) => {
+      if (storeMaskMissing) throw new Error(NO_STORE_MASK);
       return createMemoryVaultTool(
-        vaultCtx,
-        getToken ? { write: retainVaultMemory, ...options2 } : options2
+        memoryStore ?? vaultCtx,
+        getToken || memoryStore ? { write: retainVaultMemory, ...options2 } : options2
       );
     },
-    [vaultCtx, getToken, retainVaultMemory]
+    [vaultCtx, getToken, retainVaultMemory, memoryStore, storeMaskMissing]
   );
   const createRecallTool2 = (0, import_react5.useCallback)(
     (toolOptions, callbacks) => {
-      if (!getToken) {
+      if (!getToken && !memoryStore) {
         throw new Error("getToken is required for recall tool");
       }
       const resolvedToolOptions = toolOptions?.excludeConversationId !== void 0 || !currentConversationId ? toolOptions : { ...toolOptions, excludeConversationId: currentConversationId };
+      if (storeMaskMissing) throw new Error(NO_STORE_MASK);
+      if (memoryStore && resolvedToolOptions?.folderId !== void 0)
+        throw new Error(NO_STORE_FOLDERS);
+      const embeddingOptions = {
+        getToken,
+        baseUrl,
+        model: embeddingModel,
+        maskInput: maskEmbeddingInput
+      };
       return createRecallTool(
-        {
+        memoryStore ? {
+          factSource: memoryStore.factSource,
+          ...getToken && { storageCtx },
+          embeddingOptions,
+          chunkCache: chunkVectorCacheRef.current
+        } : {
           vaultCtx,
           storageCtx,
-          embeddingOptions: {
-            getToken,
-            baseUrl,
-            model: embeddingModel,
-            maskInput: maskEmbeddingInput
-          },
+          embeddingOptions,
           vaultCache: vaultEmbeddingCache,
           chunkCache: chunkVectorCacheRef.current
         },
-        resolvedToolOptions,
+        memoryStore ? { ...resolvedToolOptions, memoryStore } : resolvedToolOptions,
         callbacks
       );
     },
@@ -25904,12 +26121,14 @@ function useChatStorage(options) {
       embeddingModel,
       currentConversationId,
       maskEmbeddingInput,
-      vaultEmbeddingCache
+      vaultEmbeddingCache,
+      memoryStore,
+      storeMaskMissing
     ]
   );
   const recallFn = (0, import_react5.useCallback)(
     async (query, options2) => {
-      if (!getToken) {
+      if (!getToken && !memoryStore) {
         return {
           memories: [],
           usedBudget: options2?.budget ?? "low",
@@ -25918,17 +26137,25 @@ function useChatStorage(options) {
         };
       }
       const resolvedOptions = options2?.excludeConversationId !== void 0 || !currentConversationId ? options2 : { ...options2, excludeConversationId: currentConversationId };
+      if (storeMaskMissing) throw new Error(NO_STORE_MASK);
+      if (memoryStore && resolvedOptions?.folderId !== void 0) throw new Error(NO_STORE_FOLDERS);
+      const embeddingOptions = {
+        getToken,
+        baseUrl,
+        model: embeddingModel,
+        maskInput: maskEmbeddingInput
+      };
       return recall(
         query,
-        {
+        memoryStore ? {
+          factSource: memoryStore.factSource,
+          ...getToken && { storageCtx },
+          embeddingOptions,
+          chunkCache: chunkVectorCacheRef.current
+        } : {
           vaultCtx,
           storageCtx,
-          embeddingOptions: {
-            getToken,
-            baseUrl,
-            model: embeddingModel,
-            maskInput: maskEmbeddingInput
-          },
+          embeddingOptions,
           vaultCache: vaultEmbeddingCache,
           chunkCache: chunkVectorCacheRef.current
         },
@@ -25943,20 +26170,27 @@ function useChatStorage(options) {
       embeddingModel,
       currentConversationId,
       maskEmbeddingInput,
-      vaultEmbeddingCache
+      vaultEmbeddingCache,
+      memoryStore,
+      storeMaskMissing
     ]
   );
   const getVaultMemories = (0, import_react5.useCallback)(
     (options2) => {
-      return getAllVaultMemoriesOp(vaultCtx, options2);
+      if (!memoryStore) return getAllVaultMemoriesOp(vaultCtx, options2);
+      const { folderId, levels, kinds, ...listOptions } = options2 ?? {};
+      if (folderId !== void 0) throw new Error(NO_STORE_FOLDERS);
+      if (levels !== void 0 || kinds !== void 0)
+        throw new Error("level and kind filters are not supported with a memoryStore");
+      return memoryStore.list(listOptions);
     },
-    [vaultCtx]
+    [vaultCtx, memoryStore]
   );
   const deleteVaultMemory = (0, import_react5.useCallback)(
     (id) => {
-      return deleteVaultMemoryOp(vaultCtx, id);
+      return memoryStore ? memoryStore.delete(id) : deleteVaultMemoryOp(vaultCtx, id);
     },
-    [vaultCtx]
+    [vaultCtx, memoryStore]
   );
   const {
     isLoading,