@anuma/sdk 6.17.1 → 6.18.0

package/dist/server/index.d.ts

@@ -7792,6 +7792,41 @@ declare function createMemoryEngineTool(storageCtx: StorageOperationsContext, em
  * Each operation can be intercepted by the host app for confirmation/cancellation.
  */
 
+/**
+ * The 7 FactTypes a manual save may self-classify into (PR5). Mirrors the
+ * extractor's `FactType` union in `memory/autoExtract` — kept as a local const
+ * (not imported) to avoid a memoryVault → memory runtime import cycle. Only used
+ * to validate the optional `type` tool argument; an unrecognized value is
+ * dropped (persisted as null, the untyped/medium-decay bucket).
+ */
+declare const MANUAL_FACT_TYPES: readonly ["identity", "preference", "relationship", "plan", "ongoing_context", "constraint", "other"];
+/** A FactType the save tool's optional `type` argument may carry. */
+type ManualFactType = (typeof MANUAL_FACT_TYPES)[number];
+/**
+ * What a {@link VaultMemoryWriter} reports back. The action set mirrors
+ * `RetainResult.action` in `memory/retain` — restated here rather than imported
+ * for the same reason MANUAL_FACT_TYPES is (memoryVault → memory import cycle).
+ */
+type VaultWriteAction = "create" | "merge" | "update" | "supersede" | "suppressed" | "skip";
+interface VaultWriteOutcome {
+    /** The memory the write landed on: the fresh row, or the existing one it merged into. */
+    memoryId: string;
+    action: VaultWriteAction;
+}
+/** A NEW memory the tool wants written — `id`-addressed updates never come here. */
+interface VaultWriteInput {
+    content: string;
+    scope: string;
+    folderId?: string;
+    factType?: ManualFactType;
+}
+/**
+ * The seam through which the tool writes NEW memories when the host supplies one.
+ * `useChatStorage` (react + expo) passes a `retain()`-backed writer so a
+ * model-initiated save gets the same cosine auto-merge the background extractor
+ * gets, instead of a bare insert that trusts the model to have de-duplicated.
+ */
+type VaultMemoryWriter = (input: VaultWriteInput) => Promise<VaultWriteOutcome>;
 /**
  * Describes a pending vault save operation for UI confirmation.
  */
@@ -7830,6 +7865,35 @@ interface MemoryVaultToolOptions {
      * When provided, the LLM can specify a folderName argument.
      */
     folderMap?: Map<string, string>;
+    /**
+     * Writer for NEW memories. When set, a save without an `id` goes through it
+     * instead of a bare `createVaultMemoryOp`, and the tool phrases its reply from
+     * the reported action (a merge reads as "already known", not "saved").
+     *
+     * The hooks supply a `retain()`-backed writer, which is what makes this tool
+     * stop being a dedup bypass: until then the only thing standing between the
+     * model and a duplicate row was the prompt asking it to pass an `id`. Omit it
+     * (as a bare `createMemoryVaultTool(vaultCtx, …)` caller must — retain needs
+     * embeddings) and the direct insert path is unchanged.
+     *
+     * Updates addressed by `id` never come here: the model has already named the
+     * row, so there is nothing to de-duplicate against.
+     */
+    write?: VaultMemoryWriter;
+    /**
+     * Fires after a NEW memory's write settles, with what was asked and what the
+     * writer did. The host's analytics hook: `onSave` runs BEFORE the write and so
+     * cannot tell a fresh create from a merge into an existing memory — and that
+     * split is the one number that says whether model-initiated saves duplicate
+     * the vault. Fires on both write paths (a `write` seam, or the direct insert
+     * when none is supplied — reported as `create`). Not called for
+     * `id`-addressed updates or cancelled saves. A throwing or rejecting listener
+     * is awaited and swallowed so it can never fail the tool call.
+     */
+    onWritten?: (event: {
+        input: VaultWriteInput;
+        outcome: VaultWriteOutcome;
+    }) => void | Promise<void>;
 }
 /**
  * Creates a memory vault tool for use with chat completions.

package/dist/server/index.mjs

@@ -4890,6 +4890,26 @@ var MANUAL_FACT_TYPES = [
 function normalizeManualFactType(value) {
   return typeof value === "string" && MANUAL_FACT_TYPES.includes(value) ? value : void 0;
 }
+async function notifyWritten(options, input, outcome) {
+  try {
+    await options?.onWritten?.({ input, outcome });
+  } catch {
+  }
+}
+function describeWriteOutcome(outcome) {
+  switch (outcome.action) {
+    case "create":
+      return `Memory saved successfully (ID: ${outcome.memoryId}).`;
+    case "update":
+    case "supersede":
+      return `Memory saved successfully (ID: ${outcome.memoryId}); it replaces an earlier version of this fact.`;
+    case "merge":
+    case "skip":
+      return `The vault already holds this fact (ID: ${outcome.memoryId}); it was noted as re-observed. Nothing new was created \u2014 do not save it again.`;
+    case "suppressed":
+      return "Not saved: this matches a memory the user previously deleted. Do not re-save it.";
+  }
+}
 function createMemoryVaultTool(vaultCtx, options, embeddingOptions, cache) {
   const hasOnSave = !!options?.onSave;
   const folderNames = options?.folderMap ? Array.from(options.folderMap.keys()) : [];
@@ -4982,6 +5002,17 @@ function createMemoryVaultTool(vaultCtx, options, embeddingOptions, cache) {
           return `Memory updated successfully (ID: ${updated.uniqueId}).`;
         } else {
           const folderId = folderName ? options?.folderMap?.get(folderName) : void 0;
+          if (options?.write) {
+            const input = {
+              content,
+              scope,
+              ...folderId !== void 0 && { folderId },
+              ...factType !== void 0 && { factType }
+            };
+            const outcome = await options.write(input);
+            await notifyWritten(options, input, outcome);
+            return describeWriteOutcome(outcome);
+          }
           const created = await createVaultMemoryOp(vaultCtx, {
             content,
             scope,
@@ -5001,6 +5032,16 @@ function createMemoryVaultTool(vaultCtx, options, embeddingOptions, cache) {
               }
             );
           }
+          await notifyWritten(
+            options,
+            {
+              content,
+              scope,
+              ...folderId !== void 0 && { folderId },
+              ...factType !== void 0 && { factType }
+            },
+            { memoryId: created.uniqueId, action: "create" }
+          );
           return `Memory saved successfully (ID: ${created.uniqueId}).`;
         }
       } catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anuma/sdk",
-  "version": "6.17.1",
+  "version": "6.18.0",
   "description": "",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
@@ -259,13 +259,14 @@
       "react-dom": ">=19.0.1 <19.1.0 || >=19.1.2 <19.2.0 || >=19.2.1",
       "tar": ">=7.5.16",
       "picomatch": ">=2.3.2 <3.0.0 || >=4.0.4",
-      "@xmldom/xmldom": ">=0.8.13 <0.9.0",
+      "@xmldom/xmldom": ">=0.8.15 <0.9.0",
       "protobufjs": ">=7.6.1 <8.0.0",
       "tmp": ">=0.2.7",
       "ws@6": ">=6.2.4 <7.0.0",
       "ws@7": ">=7.5.11 <8.0.0",
       "ws@8": ">=8.21.0 <9.0.0",
       "shell-quote": ">=1.10.0 <2.0.0",
+      "browserslist": ">=4.28.7 <5.0.0",
       "axios": ">=1.16.0 <2.0.0",
       "hono": ">=4.12.21 <5.0.0",
       "js-cookie": ">=3.0.7 <4.0.0",
@@ -278,8 +279,8 @@
       "undici@>=7 <7.28.0": ">=7.28.0 <8.0.0",
       "vite@>=7 <7.3.5": ">=7.3.5",
       "esbuild@>=0.27.3 <0.28.1": ">=0.28.1",
-      "js-yaml@>=4 <4.3.1": ">=4.3.1 <5.0.0",
-      "js-yaml@>=3 <3.15.1": ">=3.15.1 <4.0.0",
+      "js-yaml@>=4 <4.3.2": ">=4.3.2 <5.0.0",
+      "js-yaml@>=3 <3.15.2": ">=3.15.2 <4.0.0",
       "markdown-it@<14.2.0": ">=14.2.0",
       "brace-expansion@1": ">=1.1.18 <2.0.0",
       "brace-expansion@2": ">=2.1.4 <3.0.0"