@maximem/synap-js-sdk 0.5.4 → 0.5.6

package/dist/index.d.cts

@@ -60,6 +60,11 @@ declare const ENDPOINTS: {
         readonly path: "/api/v1/memories/{memory_id}";
         readonly idempotent: true;
     };
+    readonly memories_forget: {
+        readonly method: "POST";
+        readonly path: "/api/v1/memories/forget";
+        readonly idempotent: false;
+    };
     readonly context_fetch_user: {
         readonly method: "POST";
         readonly path: "/v1/context/user/fetch";
@@ -372,6 +377,12 @@ interface RawContextItem {
     valid_until?: string | null;
     temporal_category?: string | null;
     temporal_confidence?: number;
+    /**
+     * The search queries of the fetch that found this item, in the order they
+     * were sent. Absent from a server that predates the field, and on an item
+     * served from the prefetch cache.
+     */
+    matched_queries?: string[];
     [key: string]: unknown;
 }
 interface RawConversationContext {
@@ -402,7 +413,15 @@ interface TemporalFields {
     temporalCategory: string | null;
     temporalConfidence: number;
 }
-interface Fact extends TemporalFields {
+/**
+ * Which of the fetch's search queries found an item. A fetch can carry several
+ * and returns one set for all of them. Always an array: empty when the fetch
+ * named no query or the server predates the field.
+ */
+interface QueryAttribution {
+    matchedQueries: string[];
+}
+interface Fact extends TemporalFields, QueryAttribution {
     id: string;
     content: string;
     confidence: number;
@@ -410,7 +429,7 @@ interface Fact extends TemporalFields {
     extractedAt: string | null;
     metadata: Json;
 }
-interface Preference extends TemporalFields {
+interface Preference extends TemporalFields, QueryAttribution {
     id: string;
     category: string;
     content: string;
@@ -419,7 +438,7 @@ interface Preference extends TemporalFields {
     extractedAt: string | null;
     metadata: Json;
 }
-interface Episode extends TemporalFields {
+interface Episode extends TemporalFields, QueryAttribution {
     id: string;
     summary: string;
     occurredAt: string | null;
@@ -427,7 +446,7 @@ interface Episode extends TemporalFields {
     participants: unknown[];
     metadata: Json;
 }
-interface Emotion extends TemporalFields {
+interface Emotion extends TemporalFields, QueryAttribution {
     id: string;
     emotionType: string;
     intensity: number;
@@ -435,7 +454,7 @@ interface Emotion extends TemporalFields {
     context: string;
     metadata: Json;
 }
-interface TemporalEvent {
+interface TemporalEvent extends QueryAttribution {
     id: string;
     content: string;
     eventDate: string | null;
@@ -516,6 +535,18 @@ interface FetchOptions {
      */
     query_date?: string;
     queryDate?: string;
+    /**
+     * How many items each search query may contribute when `search_query` holds
+     * more than one, so a query with many strong matches cannot take every
+     * place. `max_results` stays the ceiling on the whole response: three
+     * queries at five each under `max_results: 10` return ten.
+     *
+     * Sent only when provided, like `query_date`. Left out, or with one query,
+     * the response is the best `max_results` items overall, as before. `0` is
+     * treated as left out.
+     */
+    max_results_per_query?: number;
+    maxResultsPerQuery?: number;
     /** Sent only when explicitly false, matching the Python controllers. */
     include_conversation_context?: boolean;
     /**
@@ -664,6 +695,44 @@ interface BatchCreateOptions {
     fail_fast?: boolean;
     failFast?: boolean;
 }
+/** Mirrors the Python ForgetMode enum. */
+declare const FORGET_MODES: readonly ["preview", "direct"];
+type ForgetMode = (typeof FORGET_MODES)[number];
+interface ForgetOptions {
+    /** What to forget, in the user's own words (3 to 500 characters). */
+    description: string;
+    user_id?: string | null;
+    userId?: string | null;
+    customer_id?: string | null;
+    customerId?: string | null;
+    /**
+     * The level to search, named in full, one entry per level down to it:
+     * `{ customer: "acme", team: "payments", user: "dana" }`. Only needed when
+     * your scope ladder has a level between customer and user.
+     */
+    scope?: Record<string, string> | null;
+    /** `"preview"` (default) or `"direct"`. See `MemoriesInterface.forget`. */
+    mode?: ForgetMode | string;
+}
+/** A memory the description matched. Mirrors Python's `ForgetCandidate`. */
+interface ForgetCandidate {
+    memory_id: string;
+    content: string;
+    memory_type?: string | null;
+    /** `"memory"`, or where a copy lives: chunk, sentence, entity, triple, profile, candidate. */
+    store?: string;
+}
+type ForgetStatus = 'nothing_matches' | 'preview' | 'deleted' | 'partial';
+/** Result of `memories.forget`. Mirrors Python's `ForgetResponse`. */
+interface ForgetResult {
+    status: ForgetStatus;
+    request_id: string | null;
+    candidates: ForgetCandidate[];
+    deleted_ids: string[];
+    failed_ids: string[];
+    still_present_in: string[];
+    may_be_incomplete: boolean;
+}
 interface MemoriesInterface {
     create(options: CreateMemoryOptions): Promise<CreateMemoryResult>;
     batch_create(options: BatchCreateOptions): Promise<BatchCreateResult>;
@@ -671,6 +740,35 @@ interface MemoriesInterface {
     get(memoryId: string): Promise<Json>;
     update(options: UpdateMemoryOptions): Promise<Json>;
     delete(memoryId: string): Promise<Json>;
+    /**
+     * Forget memories by describing them in the user's own words. Use it when
+     * you do not hold memory ids; to delete one memory by id, use `delete()`.
+     *
+     * The call must be scoped to exactly one user: pass `user_id`, plus
+     * `customer_id` on a B2B instance. Otherwise the server answers 400, raised
+     * as `InvalidInputError`.
+     *
+     * Modes:
+     * - `"preview"` (default): files a pending request that a person approves in
+     *   the dashboard under Deletion requests. Deletes nothing. `candidates`
+     *   lists what matched.
+     * - `"direct"`: finds and soft-deletes in one call. Not idempotent as a
+     *   request: a repeat is harmless and finds nothing new, but it is a new
+     *   request.
+     *
+     * `status` is `"nothing_matches"`, `"preview"`, `"deleted"` or `"partial"`.
+     * `"partial"` means the memories are hidden but a store named in
+     * `still_present_in` may still hold the text, so do not tell an end user it
+     * was removed unless `status === "deleted"`. `failed_ids` lists memories that
+     * could not be deleted; `may_be_incomplete` is true when the match may not
+     * have covered everything.
+     *
+     * Errors: `InvalidInputError` for 400/422 or a bad `description`/`mode`
+     * caught before sending; `ServiceUnavailableError` for 503 (the matcher was
+     * unavailable and nothing was deleted, so trying again is safe; the
+     * transport applies its normal retry policy first); `RateLimitError` for 429.
+     */
+    forget(options: ForgetOptions): Promise<ForgetResult>;
     status(ingestionId: string): Promise<Json>;
     wait_for_completion(ingestionId: string, options?: WaitOptions): Promise<Json>;
 }
@@ -1384,6 +1482,8 @@ interface UnifiedFetchOptions {
     precision_level?: string;
     /** The moment the question is being asked. See FetchOptions.query_date. */
     query_date?: string;
+    /** A share of the response per search query. See FetchOptions.max_results_per_query. */
+    max_results_per_query?: number;
     include_conversation_context?: boolean;
     scopes?: string[];
     include_scope_labels?: boolean;
@@ -1554,7 +1654,7 @@ declare class SynapClient {
  * build when the two disagree, which is the only thing that makes a manual
  * publish safe.
  */
-declare const SDK_VERSION = "0.5.4";
+declare const SDK_VERSION = "0.5.6";
 
 /**
  * BM25 scorer for the anticipation cache.
@@ -1710,4 +1810,4 @@ interface SynapSdkLike {
     };
 }
 
-export { type AnthropicToolDefinition, AnticipationCacheSnapshot, type AsToolOptions, BM25, type BatchCreateResult, COMPACTION_LEVELS, CONTRACT, type CacheNamespace, type CacheStats, type CompactOptions, type CompactionCallback, type CompactionLevel, type ConfigureOptions, type ContextMetadata, type ConversationContext, type ConversationNamespace, type CreateFromFileOptions, type CreateMemoryOptions, type CreateMemoryResult, type Credentials, type CreditBalance, type CreditBucket, type CreditEstimate, type CreditLedgerEntry, type CreditLedgerPage, type CreditsNamespace, DEFAULT_BASE_URL, DEFAULT_DOCUMENT_TYPE, DEFAULT_INGEST_MODE, DEFAULT_RETRY_POLICY, DEFAULT_TIMEOUTS, DOCUMENT_TYPES, type DocumentType, ENDPOINTS, type Emotion, type EndpointName, type EndpointSpec, type Episode, type EstimateOptions, type Fact, type FetchOptions, type FlatMemory, type FormatOptions, HttpTransport, type HttpTransportOptions, INGEST_MODES, ITEM_COLLECTIONS, type IngestMode, type IngestTranscriptOptions, type InstanceNamespace, type ItemCollection, type Json, type LedgerOptions, type ListenOptions, type MemoriesInterface, type NormalisedContext, type OpenAiToolDefinition, type Preference, type RawContext, type RawContextItem, type RawConversationContext, type RecordMessageOptions, type RecordThinkingOptions, type RedeemResult, type RequestOptions, type RetryPolicy, SDK_VERSION, type Scope, type SendMessageOptions, SynapClient, type SynapClientOptions, type SynapLogLevel, type SynapLogger, type SynapSdkLike, THRESHOLDS, type TemporalEvent, type TemporalFields, type TimeoutConfig, type ToolDefinition, type ToolHandler, type ToolScope, type ToolStyle, type TranscriptIngestResult, type TranscriptTurn, type UnifiedContext, type UnifiedFetchOptions, type UpdateMemoryOptions, type UserNamespace, type WaitOptions, type WriteInvalidator, flattenContextItems, formatForPrompt, isOutcomeUnknown, isRecallQuery, mergeScopeResults, resolvePath, shouldRetry, stem, tokenize };
+export { type AnthropicToolDefinition, AnticipationCacheSnapshot, type AsToolOptions, BM25, type BatchCreateResult, COMPACTION_LEVELS, CONTRACT, type CacheNamespace, type CacheStats, type CompactOptions, type CompactionCallback, type CompactionLevel, type ConfigureOptions, type ContextMetadata, type ConversationContext, type ConversationNamespace, type CreateFromFileOptions, type CreateMemoryOptions, type CreateMemoryResult, type Credentials, type CreditBalance, type CreditBucket, type CreditEstimate, type CreditLedgerEntry, type CreditLedgerPage, type CreditsNamespace, DEFAULT_BASE_URL, DEFAULT_DOCUMENT_TYPE, DEFAULT_INGEST_MODE, DEFAULT_RETRY_POLICY, DEFAULT_TIMEOUTS, DOCUMENT_TYPES, type DocumentType, ENDPOINTS, type Emotion, type EndpointName, type EndpointSpec, type Episode, type EstimateOptions, FORGET_MODES, type Fact, type FetchOptions, type FlatMemory, type ForgetCandidate, type ForgetMode, type ForgetOptions, type ForgetResult, type ForgetStatus, type FormatOptions, HttpTransport, type HttpTransportOptions, INGEST_MODES, ITEM_COLLECTIONS, type IngestMode, type IngestTranscriptOptions, type InstanceNamespace, type ItemCollection, type Json, type LedgerOptions, type ListenOptions, type MemoriesInterface, type NormalisedContext, type OpenAiToolDefinition, type Preference, type RawContext, type RawContextItem, type RawConversationContext, type RecordMessageOptions, type RecordThinkingOptions, type RedeemResult, type RequestOptions, type RetryPolicy, SDK_VERSION, type Scope, type SendMessageOptions, SynapClient, type SynapClientOptions, type SynapLogLevel, type SynapLogger, type SynapSdkLike, THRESHOLDS, type TemporalEvent, type TemporalFields, type TimeoutConfig, type ToolDefinition, type ToolHandler, type ToolScope, type ToolStyle, type TranscriptIngestResult, type TranscriptTurn, type UnifiedContext, type UnifiedFetchOptions, type UpdateMemoryOptions, type UserNamespace, type WaitOptions, type WriteInvalidator, flattenContextItems, formatForPrompt, isOutcomeUnknown, isRecallQuery, mergeScopeResults, resolvePath, shouldRetry, stem, tokenize };

package/dist/index.d.ts

@@ -60,6 +60,11 @@ declare const ENDPOINTS: {
         readonly path: "/api/v1/memories/{memory_id}";
         readonly idempotent: true;
     };
+    readonly memories_forget: {
+        readonly method: "POST";
+        readonly path: "/api/v1/memories/forget";
+        readonly idempotent: false;
+    };
     readonly context_fetch_user: {
         readonly method: "POST";
         readonly path: "/v1/context/user/fetch";
@@ -372,6 +377,12 @@ interface RawContextItem {
     valid_until?: string | null;
     temporal_category?: string | null;
     temporal_confidence?: number;
+    /**
+     * The search queries of the fetch that found this item, in the order they
+     * were sent. Absent from a server that predates the field, and on an item
+     * served from the prefetch cache.
+     */
+    matched_queries?: string[];
     [key: string]: unknown;
 }
 interface RawConversationContext {
@@ -402,7 +413,15 @@ interface TemporalFields {
     temporalCategory: string | null;
     temporalConfidence: number;
 }
-interface Fact extends TemporalFields {
+/**
+ * Which of the fetch's search queries found an item. A fetch can carry several
+ * and returns one set for all of them. Always an array: empty when the fetch
+ * named no query or the server predates the field.
+ */
+interface QueryAttribution {
+    matchedQueries: string[];
+}
+interface Fact extends TemporalFields, QueryAttribution {
     id: string;
     content: string;
     confidence: number;
@@ -410,7 +429,7 @@ interface Fact extends TemporalFields {
     extractedAt: string | null;
     metadata: Json;
 }
-interface Preference extends TemporalFields {
+interface Preference extends TemporalFields, QueryAttribution {
     id: string;
     category: string;
     content: string;
@@ -419,7 +438,7 @@ interface Preference extends TemporalFields {
     extractedAt: string | null;
     metadata: Json;
 }
-interface Episode extends TemporalFields {
+interface Episode extends TemporalFields, QueryAttribution {
     id: string;
     summary: string;
     occurredAt: string | null;
@@ -427,7 +446,7 @@ interface Episode extends TemporalFields {
     participants: unknown[];
     metadata: Json;
 }
-interface Emotion extends TemporalFields {
+interface Emotion extends TemporalFields, QueryAttribution {
     id: string;
     emotionType: string;
     intensity: number;
@@ -435,7 +454,7 @@ interface Emotion extends TemporalFields {
     context: string;
     metadata: Json;
 }
-interface TemporalEvent {
+interface TemporalEvent extends QueryAttribution {
     id: string;
     content: string;
     eventDate: string | null;
@@ -516,6 +535,18 @@ interface FetchOptions {
      */
     query_date?: string;
     queryDate?: string;
+    /**
+     * How many items each search query may contribute when `search_query` holds
+     * more than one, so a query with many strong matches cannot take every
+     * place. `max_results` stays the ceiling on the whole response: three
+     * queries at five each under `max_results: 10` return ten.
+     *
+     * Sent only when provided, like `query_date`. Left out, or with one query,
+     * the response is the best `max_results` items overall, as before. `0` is
+     * treated as left out.
+     */
+    max_results_per_query?: number;
+    maxResultsPerQuery?: number;
     /** Sent only when explicitly false, matching the Python controllers. */
     include_conversation_context?: boolean;
     /**
@@ -664,6 +695,44 @@ interface BatchCreateOptions {
     fail_fast?: boolean;
     failFast?: boolean;
 }
+/** Mirrors the Python ForgetMode enum. */
+declare const FORGET_MODES: readonly ["preview", "direct"];
+type ForgetMode = (typeof FORGET_MODES)[number];
+interface ForgetOptions {
+    /** What to forget, in the user's own words (3 to 500 characters). */
+    description: string;
+    user_id?: string | null;
+    userId?: string | null;
+    customer_id?: string | null;
+    customerId?: string | null;
+    /**
+     * The level to search, named in full, one entry per level down to it:
+     * `{ customer: "acme", team: "payments", user: "dana" }`. Only needed when
+     * your scope ladder has a level between customer and user.
+     */
+    scope?: Record<string, string> | null;
+    /** `"preview"` (default) or `"direct"`. See `MemoriesInterface.forget`. */
+    mode?: ForgetMode | string;
+}
+/** A memory the description matched. Mirrors Python's `ForgetCandidate`. */
+interface ForgetCandidate {
+    memory_id: string;
+    content: string;
+    memory_type?: string | null;
+    /** `"memory"`, or where a copy lives: chunk, sentence, entity, triple, profile, candidate. */
+    store?: string;
+}
+type ForgetStatus = 'nothing_matches' | 'preview' | 'deleted' | 'partial';
+/** Result of `memories.forget`. Mirrors Python's `ForgetResponse`. */
+interface ForgetResult {
+    status: ForgetStatus;
+    request_id: string | null;
+    candidates: ForgetCandidate[];
+    deleted_ids: string[];
+    failed_ids: string[];
+    still_present_in: string[];
+    may_be_incomplete: boolean;
+}
 interface MemoriesInterface {
     create(options: CreateMemoryOptions): Promise<CreateMemoryResult>;
     batch_create(options: BatchCreateOptions): Promise<BatchCreateResult>;
@@ -671,6 +740,35 @@ interface MemoriesInterface {
     get(memoryId: string): Promise<Json>;
     update(options: UpdateMemoryOptions): Promise<Json>;
     delete(memoryId: string): Promise<Json>;
+    /**
+     * Forget memories by describing them in the user's own words. Use it when
+     * you do not hold memory ids; to delete one memory by id, use `delete()`.
+     *
+     * The call must be scoped to exactly one user: pass `user_id`, plus
+     * `customer_id` on a B2B instance. Otherwise the server answers 400, raised
+     * as `InvalidInputError`.
+     *
+     * Modes:
+     * - `"preview"` (default): files a pending request that a person approves in
+     *   the dashboard under Deletion requests. Deletes nothing. `candidates`
+     *   lists what matched.
+     * - `"direct"`: finds and soft-deletes in one call. Not idempotent as a
+     *   request: a repeat is harmless and finds nothing new, but it is a new
+     *   request.
+     *
+     * `status` is `"nothing_matches"`, `"preview"`, `"deleted"` or `"partial"`.
+     * `"partial"` means the memories are hidden but a store named in
+     * `still_present_in` may still hold the text, so do not tell an end user it
+     * was removed unless `status === "deleted"`. `failed_ids` lists memories that
+     * could not be deleted; `may_be_incomplete` is true when the match may not
+     * have covered everything.
+     *
+     * Errors: `InvalidInputError` for 400/422 or a bad `description`/`mode`
+     * caught before sending; `ServiceUnavailableError` for 503 (the matcher was
+     * unavailable and nothing was deleted, so trying again is safe; the
+     * transport applies its normal retry policy first); `RateLimitError` for 429.
+     */
+    forget(options: ForgetOptions): Promise<ForgetResult>;
     status(ingestionId: string): Promise<Json>;
     wait_for_completion(ingestionId: string, options?: WaitOptions): Promise<Json>;
 }
@@ -1384,6 +1482,8 @@ interface UnifiedFetchOptions {
     precision_level?: string;
     /** The moment the question is being asked. See FetchOptions.query_date. */
     query_date?: string;
+    /** A share of the response per search query. See FetchOptions.max_results_per_query. */
+    max_results_per_query?: number;
     include_conversation_context?: boolean;
     scopes?: string[];
     include_scope_labels?: boolean;
@@ -1554,7 +1654,7 @@ declare class SynapClient {
  * build when the two disagree, which is the only thing that makes a manual
  * publish safe.
  */
-declare const SDK_VERSION = "0.5.4";
+declare const SDK_VERSION = "0.5.6";
 
 /**
  * BM25 scorer for the anticipation cache.
@@ -1710,4 +1810,4 @@ interface SynapSdkLike {
     };
 }
 
-export { type AnthropicToolDefinition, AnticipationCacheSnapshot, type AsToolOptions, BM25, type BatchCreateResult, COMPACTION_LEVELS, CONTRACT, type CacheNamespace, type CacheStats, type CompactOptions, type CompactionCallback, type CompactionLevel, type ConfigureOptions, type ContextMetadata, type ConversationContext, type ConversationNamespace, type CreateFromFileOptions, type CreateMemoryOptions, type CreateMemoryResult, type Credentials, type CreditBalance, type CreditBucket, type CreditEstimate, type CreditLedgerEntry, type CreditLedgerPage, type CreditsNamespace, DEFAULT_BASE_URL, DEFAULT_DOCUMENT_TYPE, DEFAULT_INGEST_MODE, DEFAULT_RETRY_POLICY, DEFAULT_TIMEOUTS, DOCUMENT_TYPES, type DocumentType, ENDPOINTS, type Emotion, type EndpointName, type EndpointSpec, type Episode, type EstimateOptions, type Fact, type FetchOptions, type FlatMemory, type FormatOptions, HttpTransport, type HttpTransportOptions, INGEST_MODES, ITEM_COLLECTIONS, type IngestMode, type IngestTranscriptOptions, type InstanceNamespace, type ItemCollection, type Json, type LedgerOptions, type ListenOptions, type MemoriesInterface, type NormalisedContext, type OpenAiToolDefinition, type Preference, type RawContext, type RawContextItem, type RawConversationContext, type RecordMessageOptions, type RecordThinkingOptions, type RedeemResult, type RequestOptions, type RetryPolicy, SDK_VERSION, type Scope, type SendMessageOptions, SynapClient, type SynapClientOptions, type SynapLogLevel, type SynapLogger, type SynapSdkLike, THRESHOLDS, type TemporalEvent, type TemporalFields, type TimeoutConfig, type ToolDefinition, type ToolHandler, type ToolScope, type ToolStyle, type TranscriptIngestResult, type TranscriptTurn, type UnifiedContext, type UnifiedFetchOptions, type UpdateMemoryOptions, type UserNamespace, type WaitOptions, type WriteInvalidator, flattenContextItems, formatForPrompt, isOutcomeUnknown, isRecallQuery, mergeScopeResults, resolvePath, shouldRetry, stem, tokenize };
+export { type AnthropicToolDefinition, AnticipationCacheSnapshot, type AsToolOptions, BM25, type BatchCreateResult, COMPACTION_LEVELS, CONTRACT, type CacheNamespace, type CacheStats, type CompactOptions, type CompactionCallback, type CompactionLevel, type ConfigureOptions, type ContextMetadata, type ConversationContext, type ConversationNamespace, type CreateFromFileOptions, type CreateMemoryOptions, type CreateMemoryResult, type Credentials, type CreditBalance, type CreditBucket, type CreditEstimate, type CreditLedgerEntry, type CreditLedgerPage, type CreditsNamespace, DEFAULT_BASE_URL, DEFAULT_DOCUMENT_TYPE, DEFAULT_INGEST_MODE, DEFAULT_RETRY_POLICY, DEFAULT_TIMEOUTS, DOCUMENT_TYPES, type DocumentType, ENDPOINTS, type Emotion, type EndpointName, type EndpointSpec, type Episode, type EstimateOptions, FORGET_MODES, type Fact, type FetchOptions, type FlatMemory, type ForgetCandidate, type ForgetMode, type ForgetOptions, type ForgetResult, type ForgetStatus, type FormatOptions, HttpTransport, type HttpTransportOptions, INGEST_MODES, ITEM_COLLECTIONS, type IngestMode, type IngestTranscriptOptions, type InstanceNamespace, type ItemCollection, type Json, type LedgerOptions, type ListenOptions, type MemoriesInterface, type NormalisedContext, type OpenAiToolDefinition, type Preference, type RawContext, type RawContextItem, type RawConversationContext, type RecordMessageOptions, type RecordThinkingOptions, type RedeemResult, type RequestOptions, type RetryPolicy, SDK_VERSION, type Scope, type SendMessageOptions, SynapClient, type SynapClientOptions, type SynapLogLevel, type SynapLogger, type SynapSdkLike, THRESHOLDS, type TemporalEvent, type TemporalFields, type TimeoutConfig, type ToolDefinition, type ToolHandler, type ToolScope, type ToolStyle, type TranscriptIngestResult, type TranscriptTurn, type UnifiedContext, type UnifiedFetchOptions, type UpdateMemoryOptions, type UserNamespace, type WaitOptions, type WriteInvalidator, flattenContextItems, formatForPrompt, isOutcomeUnknown, isRecallQuery, mergeScopeResults, resolvePath, shouldRetry, stem, tokenize };

package/dist/index.js

@@ -49,6 +49,7 @@ var ENDPOINTS = {
   memories_get: { method: "GET", path: "/api/v1/memories/{memory_id}", idempotent: true },
   memories_update: { method: "PATCH", path: "/api/v1/memories/{memory_id}", idempotent: false },
   memories_delete: { method: "DELETE", path: "/api/v1/memories/{memory_id}", idempotent: true },
+  memories_forget: { method: "POST", path: "/api/v1/memories/forget", idempotent: false },
   context_fetch_user: { method: "POST", path: "/v1/context/user/fetch", idempotent: true },
   context_fetch_customer: { method: "POST", path: "/v1/context/customer/fetch", idempotent: true },
   context_fetch_client: { method: "POST", path: "/v1/context/client/fetch", idempotent: true },
@@ -537,6 +538,7 @@ function buildFetchRequest(scope, options) {
   const maxResults = opt(options, "max_results", "maxResults") ?? 10;
   const precisionLevel = opt(options, "precision_level", "precisionLevel") ?? "high";
   const queryDate = opt(options, "query_date", "queryDate");
+  const perQuery = opt(options, "max_results_per_query", "maxResultsPerQuery");
   const mode = options.mode ?? "fast";
   if (searchQuery !== void 0 && !Array.isArray(searchQuery)) {
     throw new InvalidInputError("search_query must be an array when provided");
@@ -553,6 +555,7 @@ function buildFetchRequest(scope, options) {
   };
   if (precisionLevel !== "high") body["precision_level"] = precisionLevel;
   if (queryDate) body["query_date"] = queryDate;
+  if (perQuery) body["max_results_per_query"] = perQuery;
   if (options.include_conversation_context === false) {
     body["include_conversation_context"] = false;
   }
@@ -628,6 +631,10 @@ function pick(...values) {
   return pickDefined(...values);
 }
 var obj = (v) => v ?? {};
+function matchedQueries(item = {}) {
+  const raw = item["matchedQueries"] ?? item.matched_queries;
+  return Array.isArray(raw) ? raw : [];
+}
 function normalizeTemporalFields(item = {}) {
   return {
     eventDate: pick(item["eventDate"], item.event_date, null),
@@ -644,7 +651,8 @@ function normalizeFact(item = {}) {
     source: item.source || "",
     extractedAt: pick(item["extractedAt"], item.extracted_at, null),
     metadata: obj(item.metadata),
-    ...normalizeTemporalFields(item)
+    ...normalizeTemporalFields(item),
+    matchedQueries: matchedQueries(item)
   };
 }
 function normalizePreference(item = {}) {
@@ -656,7 +664,8 @@ function normalizePreference(item = {}) {
     source: item.source || "",
     extractedAt: pick(item["extractedAt"], item.extracted_at, null),
     metadata: obj(item.metadata),
-    ...normalizeTemporalFields(item)
+    ...normalizeTemporalFields(item),
+    matchedQueries: matchedQueries(item)
   };
 }
 function normalizeEpisode(item = {}) {
@@ -667,7 +676,8 @@ function normalizeEpisode(item = {}) {
     significance: pick(item["significance"], item.confidence, 0),
     participants: item["participants"] || [],
     metadata: obj(item.metadata),
-    ...normalizeTemporalFields(item)
+    ...normalizeTemporalFields(item),
+    matchedQueries: matchedQueries(item)
   };
 }
 function normalizeEmotion(item = {}) {
@@ -678,7 +688,8 @@ function normalizeEmotion(item = {}) {
     detectedAt: pick(item["detectedAt"], item["detected_at"], null),
     context: item["context"] || "",
     metadata: obj(item.metadata),
-    ...normalizeTemporalFields(item)
+    ...normalizeTemporalFields(item),
+    matchedQueries: matchedQueries(item)
   };
 }
 function normalizeTemporalEvent(item = {}) {
@@ -692,7 +703,8 @@ function normalizeTemporalEvent(item = {}) {
     confidence: pick(item.confidence, 0),
     source: item.source || "",
     extractedAt: pick(item["extractedAt"], item.extracted_at, null),
-    metadata: obj(item.metadata)
+    metadata: obj(item.metadata),
+    matchedQueries: matchedQueries(item)
   };
 }
 function normalizeContextMetadata(metadata = {}) {
@@ -866,8 +878,33 @@ function buildCreateBody(options) {
     metadata: options.metadata ?? {}
   };
 }
+var FORGET_MODES = ["preview", "direct"];
+var FORGET_DESCRIPTION_MIN = 3;
+var FORGET_DESCRIPTION_MAX = 500;
+function buildForgetBody(options) {
+  const description = options.description;
+  if (typeof description !== "string" || description.length < FORGET_DESCRIPTION_MIN || description.length > FORGET_DESCRIPTION_MAX) {
+    throw new InvalidInputError(
+      `description must be between ${FORGET_DESCRIPTION_MIN} and ${FORGET_DESCRIPTION_MAX} characters`
+    );
+  }
+  const mode = options.mode ?? "preview";
+  if (!FORGET_MODES.includes(mode)) {
+    throw new InvalidInputError(
+      `Invalid mode '${mode}'. Expected one of: ${FORGET_MODES.join(", ")}`
+    );
+  }
+  const o2 = options;
+  return {
+    description,
+    user_id: either(o2, "user_id", "userId") ?? null,
+    customer_id: either(o2, "customer_id", "customerId") ?? null,
+    scope: options.scope ?? null,
+    mode
+  };
+}
 var TERMINAL_STATUSES = /* @__PURE__ */ new Set(["completed", "failed", "error", "cancelled"]);
-function createMemoriesInterface(transport) {
+function createMemoriesInterface(transport, onForgotten) {
   return {
     async create(options) {
       const o2 = options;
@@ -953,6 +990,23 @@ function createMemoriesInterface(transport) {
       }
       return transport.request("memories_delete", { pathParams: { memory_id: memoryId } });
     },
+    async forget(options) {
+      const o2 = options;
+      transport.checkCustomerId(o2["customer_id"] ?? o2["customerId"], "memories.forget");
+      const body = buildForgetBody(options);
+      const result = await transport.request("memories_forget", { body });
+      const removed = !!result?.deleted_ids?.length || result?.status === "deleted" || result?.status === "partial";
+      if (removed && onForgotten) {
+        try {
+          onForgotten({
+            userId: body["user_id"] ?? null,
+            customerId: body["customer_id"] ?? null
+          });
+        } catch {
+        }
+      }
+      return result;
+    },
     async status(ingestionId) {
       if (!ingestionId) throw new InvalidInputError("ingestion_id is required");
       return transport.request("memories_status", {
@@ -1457,7 +1511,7 @@ function createInstanceNamespace(credentials, cache, onTurn) {
       if (client !== null) {
         throw new ListeningAlreadyActiveError("Listening is already active on this instance");
       }
-      const { GrpcStreamClient } = await import("./stream-client-5CGJNTH4.js");
+      const { GrpcStreamClient } = await import("./stream-client-Y5NFAMIH.js");
       const onContext = options.on_context ?? options.onContext;
       const onDisconnect = options.on_disconnect ?? options.onDisconnect;
       const onReconnect = options.on_reconnect ?? options.onReconnect;
@@ -1629,7 +1683,7 @@ function createInstanceNamespace(credentials, cache, onTurn) {
 }
 
 // src/version.ts
-var SDK_VERSION = "0.5.4";
+var SDK_VERSION = "0.5.6";
 
 // src/registry.ts
 var instances = /* @__PURE__ */ new Map();
@@ -2132,6 +2186,10 @@ function tryServeFromCache(cache, scope, params, maxItems) {
     return { response: null, hit: null };
   }
 }
+function distinctQueryCount(searchQuery) {
+  if (!Array.isArray(searchQuery)) return 0;
+  return new Set(searchQuery.filter((q) => typeof q === "string" && q.length > 0)).size;
+}
 
 // src/context/assembled.ts
 var COLLECTIONS2 = ["facts", "preferences", "episodes", "emotions", "temporal_events"];
@@ -2629,6 +2687,7 @@ var SynapClient = class {
       beforeFetch: (scope, options2) => {
         const o2 = options2;
         if (o2["query_date"] ?? o2["queryDate"]) return null;
+        if (o2["max_results_per_query"] ?? o2["maxResultsPerQuery"]) return null;
         const attempt = tryServeFromCache(
           this.#anticipationCache,
           scope,
@@ -2699,7 +2758,11 @@ var SynapClient = class {
         compacted: (conversationId, format) => this.#localCompacted(conversationId, format)
       }
     );
-    this.memories = createMemoriesInterface(this.#transport);
+    this.memories = createMemoriesInterface(this.#transport, ({ userId, customerId }) => {
+      for (const id of /* @__PURE__ */ new Set([userId, customerId])) {
+        if (id) this.#anticipationCache.dropEntity(id);
+      }
+    });
     this.credits = createCreditsNamespace(this.#transport);
     this.cache = createCacheNamespace(this.#anticipationCache);
     this.instance = createInstanceNamespace(
@@ -2898,6 +2961,7 @@ var SynapClient = class {
       mode = "fast",
       precision_level: precisionLevel = "high",
       query_date: queryDate,
+      max_results_per_query: maxResultsPerQuery,
       include_conversation_context: includeConversationContext = true,
       scopes,
       include_scope_labels: includeScopeLabels = false,
@@ -2916,7 +2980,8 @@ var SynapClient = class {
       // In `shared` so it reaches all four branches at once. The Python edit
       // threaded three call sites by hand and missed the client branch, which
       // sits one indent deeper; spreading removes that whole class of miss.
-      query_date: queryDate
+      query_date: queryDate,
+      max_results_per_query: maxResultsPerQuery
     };
     const labels = [];
     const tasks = [];
@@ -3026,7 +3091,12 @@ var SynapClient = class {
         served_item_ids: served.servedItemIds,
         scope,
         source_bundle_ids: served.bundleId ? [served.bundleId] : [],
-        timestamp_ms: Date.now()
+        timestamp_ms: Date.now(),
+        // How many distinct search queries the fetch carried. A hit never
+        // reaches the fetch route, so this event is how the server learns it
+        // happened and what it is charged by. The count only: this event must
+        // not carry the caller's words.
+        query_count: distinctQueryCount(options["search_query"] ?? options["searchQuery"])
       });
     } catch {
     }
@@ -3165,6 +3235,7 @@ export {
   DEFAULT_TIMEOUTS,
   DOCUMENT_TYPES,
   ENDPOINTS,
+  FORGET_MODES,
   HttpTransport,
   INGEST_MODES,
   ITEM_COLLECTIONS,