@mongodb-js/agent-engine-sdk-memory 0.11.3

package/dist/memory.d.ts

@@ -0,0 +1,221 @@
+/**
+ * Transport-free public Memory facade (TypeScript port).
+ *
+ * `Memory` is the surface platform users interact with. It delegates the
+ * high-level workflow operations to an injected `MemoryRuntime` and the CRUD
+ * conveniences to an injected `MemoryCrudClient`. Identity is resolved per call;
+ * tenancy never appears in any public signature. Methods are async: the
+ * underlying transport is HTTP.
+ */
+import { SearchSource, type ContextResponse, type CreateEpisodicResult, type CreateProceduralResult, type CreateSemanticResult, type CreateTaxonomicResult, type CustomMemoryRetrieveResult, type CustomMemorySaveResult, type MemoryChunk, type WriteTurnResult } from "./models.js";
+import { type TagMap } from "./tag_syntax.js";
+import { type FetchLike, type MemoryCrudClient, type MemoryRequestContext, type MemoryRuntime } from "./transport.js";
+export type MemoryOptions = {
+    /** Auth: a service-account access token minted at POST /api/v1/oauth/token. */
+    serviceAccountToken?: string | null;
+    /**
+     * @deprecated Use `serviceAccountToken` (or the
+     * AGENTIC_MEMORY_SERVICE_ACCOUNT_TOKEN env var). Still accepted as an
+     * alias; emits a DeprecationWarning.
+     */
+    apiKey?: string | null;
+    baseUrl?: string | null;
+    projectId?: string | null;
+    /** Injectable fetch, primarily for tests. */
+    fetchImpl?: FetchLike;
+} | {
+    runtime: MemoryRuntime;
+    client?: MemoryCrudClient | null;
+};
+/** Public, transport-free memory facade. */
+export declare class Memory {
+    private readonly runtime;
+    private readonly client;
+    private boundCtx;
+    private ownsRuntime;
+    private crudUnsupportedReason;
+    constructor(opts?: MemoryOptions);
+    private static resolveUrl;
+    /** Return a new Memory scoped to `ctx` without mutating this handle. */
+    bind(ctx: MemoryRequestContext): Memory;
+    /** Release the underlying transport(s) when this handle owns them. */
+    close(): Promise<void>;
+    private requireClient;
+    private runtimeCtx;
+    private resolve;
+    /** Record a single conversation turn (write-accepted semantics). */
+    recordTurn(args: {
+        role: string;
+        content?: string | null;
+        sessionId?: string | null;
+        toolCalls?: Array<Record<string, unknown>> | null;
+        toolCallId?: string | null;
+        toolName?: string | null;
+        isError?: boolean;
+        modelName?: string | null;
+        idempotencyKey?: string | null;
+    }): Promise<WriteTurnResult>;
+    saveSemantic(args: {
+        text: string;
+        label: string;
+        userId?: string | null;
+        source?: string;
+        visibility?: string;
+        metadata?: Record<string, unknown> | null;
+        upsert?: boolean;
+        agentId?: string | null;
+    }): Promise<CreateSemanticResult>;
+    searchSemantic(args: {
+        query: string;
+        userId?: string | null;
+        visibility?: string | null;
+        topK?: number;
+    }): Promise<MemoryChunk[]>;
+    getSemantic(args: {
+        label: string;
+        userId?: string | null;
+        visibility?: string | null;
+    }): Promise<unknown | null>;
+    saveEpisode(args: {
+        title: string;
+        content: string;
+        userId?: string | null;
+        summary?: string | null;
+        sessionId?: string | null;
+        participants?: string[] | null;
+        tags?: string[] | null;
+        visibility?: string;
+        metadata?: Record<string, unknown> | null;
+        agentId?: string | null;
+    }): Promise<CreateEpisodicResult>;
+    searchEpisodes(args: {
+        query: string;
+        userId?: string | null;
+        visibility?: string | null;
+        sessionId?: string | null;
+        topK?: number;
+    }): Promise<MemoryChunk[]>;
+    listEpisodes(args?: {
+        userId?: string | null;
+        visibility?: string | null;
+        sessionId?: string | null;
+        limit?: number;
+    }): Promise<unknown[]>;
+    saveTaxonomic(args: {
+        domain: string;
+        term: string;
+        definition: string;
+        relatedTerms?: string[] | null;
+        visibility?: string;
+        userId?: string | null;
+    }): Promise<CreateTaxonomicResult>;
+    searchTaxonomic(args: {
+        query: string;
+        userId?: string | null;
+        domain?: string | null;
+        visibility?: string | null;
+        topK?: number;
+    }): Promise<MemoryChunk[]>;
+    getTaxonomicTerm(args: {
+        domain: string;
+        term: string;
+        userId?: string | null;
+        visibility?: string | null;
+    }): Promise<unknown | null>;
+    listDomains(args?: {
+        visibility?: string | null;
+    }): Promise<string[]>;
+    discoverProcedures(args: {
+        query: string;
+        userId?: string | null;
+        visibility?: string | null;
+        tags?: string[] | null;
+        topK?: number;
+        similarityThreshold?: number;
+        metadataFilter?: Record<string, unknown> | null;
+    }): Promise<Array<Record<string, unknown>>>;
+    getProcedure(args: {
+        procedureName: string;
+        userId?: string | null;
+        visibility?: string | null;
+        includeDeleted?: boolean;
+    }): Promise<unknown | null>;
+    saveProcedure(args: {
+        procedure: string;
+        description: string;
+        content: string;
+        userId?: string | null;
+        steps?: Array<Record<string, unknown>> | null;
+        resources?: Array<Record<string, unknown>> | null;
+        allowedTools?: string[] | null;
+        compatibility?: string | null;
+        license?: string | null;
+        triggerConditions?: string[] | null;
+        tags?: string[] | null;
+        visibility?: string;
+        agentId?: string | null;
+        extractionSource?: string | null;
+        sourceFormat?: string | null;
+        sourcePath?: string | null;
+        updateExisting?: boolean;
+    }): Promise<CreateProceduralResult>;
+    /**
+     * Save a memory of a declared custom type.
+     *
+     * The platform stamps identity (org, project, user) and enforces the
+     * type's declared tag schema; this method validates only tag syntax
+     * client-side so mistakes fail fast with server-matching messages.
+     * Built-in types (semantic, episodic, taxonomic, procedural) are
+     * rejected — use their dedicated methods.
+     */
+    save(memoryType: string, content: string, options?: {
+        tags?: TagMap | null;
+        contextualMetadata?: Record<string, unknown> | null;
+    }): Promise<CustomMemorySaveResult>;
+    /**
+     * Retrieve memories of a declared custom type by semantic query.
+     *
+     * Filters are exact-match equality on declared tag keys; result ordering
+     * may improve between releases and is not contractual. One type per call.
+     */
+    retrieve(memoryType: string, query: string, options?: {
+        tags?: TagMap | null;
+        topK?: number;
+    }): Promise<CustomMemoryRetrieveResult>;
+    /** Build a unified memory context across memory types. */
+    buildContext(args: {
+        query: string;
+        userId?: string | null;
+        sessionId?: string | null;
+        visibility?: string | null;
+        metadataFilter?: Record<string, unknown> | null;
+        enabledSources?: Set<string> | null;
+        /** Deprecated alias for `sessionId`; a non-blank `sessionId` wins. */
+        threadId?: string | null;
+        /**
+         * Optional gross context-construction budget. Omitted preserves prior
+         * behavior. Non-positive, non-integer, and non-finite values raise
+         * before runtime delegation. After retrieval and ranking, the server
+         * subtracts a 500-token formatting reserve, then greedily selects whole
+         * memory chunks that fit in the remainder. Positive values at or below 500
+         * leave no budget for memories. Values above 500 can still
+         * yield empty context when no chunk fits. `metadata.token_count` reports
+         * formatted output only and excludes the reserve.
+         */
+        maxTokens?: number;
+    }): Promise<ContextResponse>;
+    /** Search one or more memory sources and return a single ranked list. */
+    search(args: {
+        query: string;
+        sources?: SearchSource | string | ReadonlyArray<SearchSource | string> | null;
+        topK?: number;
+        userId?: string | null;
+        visibility?: string | null;
+        sessionId?: string | null;
+        domain?: string | null;
+        tags?: string[] | null;
+        similarityThreshold?: number;
+        metadataFilter?: Record<string, unknown> | null;
+    }): Promise<MemoryChunk[]>;
+}
+//# sourceMappingURL=memory.d.ts.map

package/dist/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../src/memory.ts"],"names":[],"mappings":"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"}