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

package/dist/models.d.ts

@@ -0,0 +1,168 @@
+/**
+ * Canonical models for the Memory API (TypeScript port).
+ *
+ * These zod schemas define the response types the Memory Server returns and the
+ * facade surfaces. They are the TypeScript counterpart of the Python
+ * `agent_engine_sdk_memory.models` module — only the shapes the unified `Memory`
+ * facade actually returns are ported here.
+ */
+import { z } from "zod";
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export declare const WriteTurnResultSchema: z.ZodObject<{
+    id: z.ZodString;
+    session_id: z.ZodString;
+    turn_seq: z.ZodNumber;
+    acknowledged: z.ZodDefault<z.ZodBoolean>;
+    has_embedding: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export type WriteTurnResult = z.infer<typeof WriteTurnResultSchema>;
+export declare const CreateSemanticResultSchema: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodString;
+    has_embedding: z.ZodBoolean;
+    acknowledged: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export type CreateSemanticResult = z.infer<typeof CreateSemanticResultSchema>;
+export declare const CreateEpisodicResultSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    has_embedding: z.ZodBoolean;
+    acknowledged: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export type CreateEpisodicResult = z.infer<typeof CreateEpisodicResultSchema>;
+export declare const CreateTaxonomicResultSchema: z.ZodObject<{
+    id: z.ZodString;
+    domain: z.ZodString;
+    term: z.ZodString;
+    has_embedding: z.ZodBoolean;
+    acknowledged: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export type CreateTaxonomicResult = z.infer<typeof CreateTaxonomicResultSchema>;
+export declare const CreateProceduralResultSchema: z.ZodObject<{
+    id: z.ZodString;
+    procedure: z.ZodString;
+    has_embedding: z.ZodBoolean;
+    acknowledged: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export type CreateProceduralResult = z.infer<typeof CreateProceduralResultSchema>;
+export declare const TagScalarSchema: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+export type TagScalar = z.infer<typeof TagScalarSchema>;
+export declare const CustomMemorySaveResultSchema: z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodString;
+    tags: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+    has_embedding: z.ZodBoolean;
+}, z.core.$strip>;
+export type CustomMemorySaveResult = z.infer<typeof CustomMemorySaveResultSchema>;
+export declare const RetrievedCustomMemorySchema: z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodString;
+    content: z.ZodString;
+    tags: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+    contextual_metadata: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    user_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    agent_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export type RetrievedCustomMemory = z.infer<typeof RetrievedCustomMemorySchema>;
+export declare const CustomMemoryRetrieveResultSchema: z.ZodObject<{
+    results: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodString;
+        content: z.ZodString;
+        tags: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+        contextual_metadata: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        user_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        agent_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>>;
+    count: z.ZodNumber;
+}, z.core.$strip>;
+export type CustomMemoryRetrieveResult = z.infer<typeof CustomMemoryRetrieveResultSchema>;
+/** Source type for memory chunks. */
+export declare const MemorySource: {
+    readonly STM: "stm";
+    readonly EPISODIC: "episodic";
+    readonly SEMANTIC: "semantic";
+    readonly TAXONOMIC: "taxonomic";
+    readonly PROCEDURAL: "procedural";
+};
+export type MemorySource = (typeof MemorySource)[keyof typeof MemorySource];
+/**
+ * A memory source that `Memory.search` can query.
+ *
+ * Mirrors `MemorySource` minus `stm` (short-term turns are not a search target).
+ * Callers may pass either the constant or its string value.
+ */
+export declare const SearchSource: {
+    readonly SEMANTIC: "semantic";
+    readonly EPISODIC: "episodic";
+    readonly TAXONOMIC: "taxonomic";
+    readonly PROCEDURAL: "procedural";
+};
+export type SearchSource = (typeof SearchSource)[keyof typeof SearchSource];
+/** Narrow an arbitrary string to a `SearchSource`, throwing on an unknown value. */
+export declare function toSearchSource(value: string): SearchSource;
+/**
+ * Unified representation of memory from any source (STM, episodic, semantic, …).
+ *
+ * `timestamp` is coerced to a `Date`; a missing value on the wire is a server
+ * contract violation and surfaces as a schema error at parse time.
+ *
+ * `similarity_score` is on the scale of the retrieval mode that produced the
+ * chunk: vector similarity for semantic mode, text relevance for text mode, and
+ * the fused rank-fusion score for hybrid mode. Comparable between chunks
+ * retrieved the same way; not comparable across modes, or across sources
+ * searched differently. Null when the chunk did not come from a search.
+ */
+export declare const MemoryChunkSchema: z.ZodObject<{
+    id: z.ZodString;
+    content: z.ZodString;
+    source: z.ZodEnum<{
+        stm: "stm";
+        episodic: "episodic";
+        semantic: "semantic";
+        taxonomic: "taxonomic";
+        procedural: "procedural";
+    }>;
+    timestamp: z.ZodCoercedDate<unknown>;
+    embedding: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodNumber>>>;
+    similarity_score: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    metadata: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+}, z.core.$strip>;
+export type MemoryChunk = z.infer<typeof MemoryChunkSchema>;
+export declare const ContextMetadataSchema: z.ZodObject<{
+    token_count: z.ZodDefault<z.ZodNumber>;
+    memory_counts: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+    timing: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+}, z.core.$strip>;
+export type ContextMetadata = z.infer<typeof ContextMetadataSchema>;
+/**
+ * Final response model for context building. `formatted_context` is a string or
+ * a list of message dicts depending on the server's format style.
+ */
+export declare const ContextResponseSchema: z.ZodObject<{
+    formatted_context: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>]>;
+    metadata: z.ZodDefault<z.ZodObject<{
+        token_count: z.ZodDefault<z.ZodNumber>;
+        memory_counts: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+        timing: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+    }, z.core.$strip>>;
+    selected_memories: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        content: z.ZodString;
+        source: z.ZodEnum<{
+            stm: "stm";
+            episodic: "episodic";
+            semantic: "semantic";
+            taxonomic: "taxonomic";
+            procedural: "procedural";
+        }>;
+        timestamp: z.ZodCoercedDate<unknown>;
+        embedding: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodNumber>>>;
+        similarity_score: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        metadata: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    }, z.core.$strip>>>>;
+}, z.core.$strip>;
+export type ContextResponse = z.infer<typeof ContextResponseSchema>;
+//# sourceMappingURL=models.d.ts.map

package/dist/models.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"models.d.ts","sourceRoot":"","sources":["../src/models.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,MAAM,SAAS,GACjB,MAAM,GACN,MAAM,GACN,OAAO,GACP,IAAI,GACJ,SAAS,EAAE,GACX;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AAMjC,eAAO,MAAM,qBAAqB;;;;;;iBAMhC,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,eAAO,MAAM,0BAA0B;;;;;iBAKrC,CAAC;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAE9E,eAAO,MAAM,0BAA0B;;;;;iBAKrC,CAAC;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAE9E,eAAO,MAAM,2BAA2B;;;;;;iBAMtC,CAAC;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAEhF,eAAO,MAAM,4BAA4B;;;;;iBAKvC,CAAC;AACH,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAC1C,OAAO,4BAA4B,CACpC,CAAC;AAEF,eAAO,MAAM,eAAe,+DAAiD,CAAC;AAC9E,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAExD,eAAO,MAAM,4BAA4B;;;;;iBAKvC,CAAC;AACH,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAC1C,OAAO,4BAA4B,CACpC,CAAC;AAEF,eAAO,MAAM,2BAA2B;;;;;;;;iBAQtC,CAAC;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAEhF,eAAO,MAAM,gCAAgC;;;;;;;;;;;iBAG3C,CAAC;AACH,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAC9C,OAAO,gCAAgC,CACxC,CAAC;AAMF,qCAAqC;AACrC,eAAO,MAAM,YAAY;;;;;;CAMf,CAAC;AACX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,OAAO,YAAY,CAAC,CAAC;AAE5E;;;;;GAKG;AACH,eAAO,MAAM,YAAY;;;;;CAKf,CAAC;AACX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,OAAO,YAAY,CAAC,CAAC;AAI5E,oFAAoF;AACpF,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,CAK1D;AAcD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;iBAQ5B,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D,eAAO,MAAM,qBAAqB;;;;iBAIhC,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE;;;GAGG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;iBAWhC,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC"}

package/dist/models.js

@@ -0,0 +1,147 @@
+/**
+ * Canonical models for the Memory API (TypeScript port).
+ *
+ * These zod schemas define the response types the Memory Server returns and the
+ * facade surfaces. They are the TypeScript counterpart of the Python
+ * `agent_engine_sdk_memory.models` module — only the shapes the unified `Memory`
+ * facade actually returns are ported here.
+ */
+import { z } from "zod";
+// =============================================================================
+// Result models (operation results)
+// =============================================================================
+export const WriteTurnResultSchema = z.object({
+    id: z.string(),
+    session_id: z.string(),
+    turn_seq: z.number().int(),
+    acknowledged: z.boolean().default(true),
+    has_embedding: z.boolean().default(false),
+});
+export const CreateSemanticResultSchema = z.object({
+    id: z.string(),
+    label: z.string(),
+    has_embedding: z.boolean(),
+    acknowledged: z.boolean().default(true),
+});
+export const CreateEpisodicResultSchema = z.object({
+    id: z.string(),
+    title: z.string(),
+    has_embedding: z.boolean(),
+    acknowledged: z.boolean().default(true),
+});
+export const CreateTaxonomicResultSchema = z.object({
+    id: z.string(),
+    domain: z.string(),
+    term: z.string(),
+    has_embedding: z.boolean(),
+    acknowledged: z.boolean().default(true),
+});
+export const CreateProceduralResultSchema = z.object({
+    id: z.string(),
+    procedure: z.string(),
+    has_embedding: z.boolean(),
+    acknowledged: z.boolean().default(true),
+});
+export const TagScalarSchema = z.union([z.string(), z.number(), z.boolean()]);
+export const CustomMemorySaveResultSchema = z.object({
+    id: z.string(),
+    type: z.string(),
+    tags: z.record(z.string(), TagScalarSchema),
+    has_embedding: z.boolean(),
+});
+export const RetrievedCustomMemorySchema = z.object({
+    id: z.string(),
+    type: z.string(),
+    content: z.string(),
+    tags: z.record(z.string(), TagScalarSchema),
+    contextual_metadata: z.record(z.string(), z.unknown()).nullish(),
+    user_id: z.string().nullish(),
+    agent_id: z.string().nullish(),
+});
+export const CustomMemoryRetrieveResultSchema = z.object({
+    results: z.array(RetrievedCustomMemorySchema),
+    count: z.number(),
+});
+// =============================================================================
+// Retrieval enums
+// =============================================================================
+/** Source type for memory chunks. */
+export const MemorySource = {
+    STM: "stm",
+    EPISODIC: "episodic",
+    SEMANTIC: "semantic",
+    TAXONOMIC: "taxonomic",
+    PROCEDURAL: "procedural",
+};
+/**
+ * A memory source that `Memory.search` can query.
+ *
+ * Mirrors `MemorySource` minus `stm` (short-term turns are not a search target).
+ * Callers may pass either the constant or its string value.
+ */
+export const SearchSource = {
+    SEMANTIC: "semantic",
+    EPISODIC: "episodic",
+    TAXONOMIC: "taxonomic",
+    PROCEDURAL: "procedural",
+};
+const SEARCH_SOURCE_VALUES = new Set(Object.values(SearchSource));
+/** Narrow an arbitrary string to a `SearchSource`, throwing on an unknown value. */
+export function toSearchSource(value) {
+    if (!SEARCH_SOURCE_VALUES.has(value)) {
+        throw new RangeError(`unknown search source: ${value}`);
+    }
+    return value;
+}
+// =============================================================================
+// Retrieval models (memory chunks and context)
+// =============================================================================
+const MemorySourceSchema = z.enum([
+    MemorySource.STM,
+    MemorySource.EPISODIC,
+    MemorySource.SEMANTIC,
+    MemorySource.TAXONOMIC,
+    MemorySource.PROCEDURAL,
+]);
+/**
+ * Unified representation of memory from any source (STM, episodic, semantic, …).
+ *
+ * `timestamp` is coerced to a `Date`; a missing value on the wire is a server
+ * contract violation and surfaces as a schema error at parse time.
+ *
+ * `similarity_score` is on the scale of the retrieval mode that produced the
+ * chunk: vector similarity for semantic mode, text relevance for text mode, and
+ * the fused rank-fusion score for hybrid mode. Comparable between chunks
+ * retrieved the same way; not comparable across modes, or across sources
+ * searched differently. Null when the chunk did not come from a search.
+ */
+export const MemoryChunkSchema = z.object({
+    id: z.string(),
+    content: z.string(),
+    source: MemorySourceSchema,
+    timestamp: z.coerce.date(),
+    embedding: z.array(z.number()).nullish(),
+    similarity_score: z.number().nullish(),
+    metadata: z.record(z.string(), z.unknown()).nullish(),
+});
+export const ContextMetadataSchema = z.object({
+    token_count: z.number().int().default(0),
+    memory_counts: z.record(z.string(), z.number()).default({}),
+    timing: z.record(z.string(), z.number()).default({}),
+});
+/**
+ * Final response model for context building. `formatted_context` is a string or
+ * a list of message dicts depending on the server's format style.
+ */
+export const ContextResponseSchema = z.object({
+    formatted_context: z.union([
+        z.string(),
+        z.array(z.record(z.string(), z.unknown())),
+    ]),
+    metadata: ContextMetadataSchema.default(() => ({
+        token_count: 0,
+        memory_counts: {},
+        timing: {},
+    })),
+    selected_memories: z.array(MemoryChunkSchema).nullish(),
+});

package/dist/tag_syntax.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Syntax-only client-side checks for custom-type names and tag payloads.
+ *
+ * Mirrors the shape rules of the memory-server's tag canonicalization with
+ * byte-identical messages, so a fail-fast client error reads the same as a
+ * server rejection. Deliberately NOT mirrored (server-owned): the int64 range
+ * guard, dotted+nested mixed-form detection, operator-expression detection,
+ * key-count caps, declaration membership — those values reach the platform
+ * intact, so the server's own rejection is the one the caller sees.
+ *
+ * Non-finite numbers are the exception: JSON.stringify rewrites them to null,
+ * so the value never survives the wire for the server to judge. Rejecting here
+ * is what makes the server's rule reachable at all.
+ */
+import type { TagScalar } from "./models.js";
+export type { TagScalar };
+export type TagMap = Record<string, TagScalar | Record<string, TagScalar>>;
+/** Mirror of pkg/memoryconfig/reserved_names.json (parity-tested in Python). */
+export declare const RESERVED_TYPE_NAMES: ReadonlySet<string>;
+export declare function validateMemoryType(memoryType: string): void;
+export declare function validateTagSyntax(tags: Record<string, unknown>): void;
+//# sourceMappingURL=tag_syntax.d.ts.map

package/dist/tag_syntax.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tag_syntax.d.ts","sourceRoot":"","sources":["../src/tag_syntax.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,YAAY,EAAE,SAAS,EAAE,CAAC;AAC1B,MAAM,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC;AAE3E,gFAAgF;AAChF,eAAO,MAAM,mBAAmB,EAAE,WAAW,CAAC,MAAM,CAWlD,CAAC;AAWH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAc3D;AA4ED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAKrE"}

package/dist/tag_syntax.js

@@ -0,0 +1,110 @@
+/**
+ * Syntax-only client-side checks for custom-type names and tag payloads.
+ *
+ * Mirrors the shape rules of the memory-server's tag canonicalization with
+ * byte-identical messages, so a fail-fast client error reads the same as a
+ * server rejection. Deliberately NOT mirrored (server-owned): the int64 range
+ * guard, dotted+nested mixed-form detection, operator-expression detection,
+ * key-count caps, declaration membership — those values reach the platform
+ * intact, so the server's own rejection is the one the caller sees.
+ *
+ * Non-finite numbers are the exception: JSON.stringify rewrites them to null,
+ * so the value never survives the wire for the server to judge. Rejecting here
+ * is what makes the server's rule reachable at all.
+ */
+import { MemoryClientError } from "./errors.js";
+/** Mirror of pkg/memoryconfig/reserved_names.json (parity-tested in Python). */
+export const RESERVED_TYPE_NAMES = new Set([
+    "semantic",
+    "episodic",
+    "taxonomic",
+    "procedural",
+    "snapshot",
+    "entity",
+    "preferences",
+    "turn",
+    "stm",
+    "short_term",
+]);
+const MAX_TAG_KEY_DEPTH = 2;
+/**
+ * Mirror of the name_pattern in pkg/memoryconfig/reserved_names.json. A name
+ * that cannot be declared can never exist, so checking it here turns an
+ * unroutable request into a precise local error.
+ */
+const NAME_RE = /^[a-z][a-z0-9_]{0,63}$/;
+export function validateMemoryType(memoryType) {
+    if (typeof memoryType !== "string" || memoryType.trim() === "") {
+        throw new MemoryClientError("memory_type must be a non-empty string");
+    }
+    if (RESERVED_TYPE_NAMES.has(memoryType)) {
+        throw new MemoryClientError(`'${memoryType}' is a built-in memory type and is not accepted by this operation`);
+    }
+    if (!NAME_RE.test(memoryType)) {
+        throw new MemoryClientError(`custom type name '${memoryType}' must match ${NAME_RE.source}`);
+    }
+}
+function isPlainObject(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value) &&
+        Object.getPrototypeOf(value) === Object.prototype);
+}
+function checkPath(path) {
+    const segments = path.split(".");
+    if (segments.some((segment) => segment === "")) {
+        throw new MemoryClientError(`tag '${path}' must have a non-empty path`);
+    }
+    if (segments.length > MAX_TAG_KEY_DEPTH) {
+        throw new MemoryClientError(`tag '${path}': nesting is at most one level deep`);
+    }
+}
+function checkScalar(path, value) {
+    if (typeof value === "string") {
+        if (value.trim() === "") {
+            throw new MemoryClientError(`tag '${path}' must have a non-empty string value`);
+        }
+    }
+    else if (typeof value === "number") {
+        // JSON.stringify turns NaN and Infinity into null, which would store a
+        // value the server never agreed to. Reject before that silent rewrite.
+        if (!Number.isFinite(value)) {
+            throw new MemoryClientError(`tag '${path}' must be a finite number`);
+        }
+    }
+    else if (typeof value !== "boolean") {
+        throw new MemoryClientError(`tag '${path}' must be a non-empty string, number, or boolean`);
+    }
+}
+/**
+ * Yield [dotted path, value] pairs from either accepted wire form.
+ *
+ * Group-level rules are applied here, so the per-leaf checks that follow run
+ * over one uniform sequence rather than once per wire form.
+ */
+function* flatten(tags) {
+    for (const [key, value] of Object.entries(tags)) {
+        if (!isPlainObject(value)) {
+            yield [key, value];
+            continue;
+        }
+        if (key.includes(".")) {
+            throw new MemoryClientError(`tag '${key}': nesting is at most one level deep`);
+        }
+        if (Object.keys(value).length === 0) {
+            throw new MemoryClientError(`tag group '${key}' must contain at least one key`);
+        }
+        for (const [subkey, subvalue] of Object.entries(value)) {
+            if (subkey.includes(".") || isPlainObject(subvalue)) {
+                throw new MemoryClientError(`tag '${key}': nesting is at most one level deep`);
+            }
+            yield [`${key}.${subkey}`, subvalue];
+        }
+    }
+}
+export function validateTagSyntax(tags) {
+    for (const [path, value] of flatten(tags)) {
+        checkPath(path);
+        checkScalar(path, value);
+    }
+}

package/dist/transport.d.ts

@@ -0,0 +1,191 @@
+/** Seam primitives: the request context and the runtime/CRUD interfaces. */
+import type { ContextResponse, CreateEpisodicResult, CreateProceduralResult, CreateSemanticResult, CreateTaxonomicResult, CustomMemoryRetrieveResult, CustomMemorySaveResult, MemoryChunk, WriteTurnResult } from "./models.js";
+/** A minimal fetch signature so tests can inject a stub. */
+export type FetchLike = (url: string, init: RequestInit) => Promise<Response>;
+/** Extra per-request options a transport implementation can layer in (e.g. mTLS agent). */
+export type RequestExtras = () => RequestInit;
+/** Immutable identity context carried across a memory call. */
+export interface MemoryRequestContext {
+    readonly userId?: string | null;
+    readonly agentId?: string | null;
+    readonly sessionId?: string | null;
+}
+/**
+ * Transport seam every memory backend implements.
+ *
+ * Identity is passed as resolved arguments; tenancy is internal to each runtime.
+ */
+export interface MemoryRuntime {
+    recordTurn(args: {
+        role: string;
+        content?: string | null;
+        sessionId?: string | null;
+        userId?: string | null;
+        agentId?: string | null;
+        toolCalls?: Array<Record<string, unknown>> | null;
+        toolCallId?: string | null;
+        toolName?: string | null;
+        isError?: boolean;
+        modelName?: string | null;
+        idempotencyKey?: string | null;
+    }): Promise<WriteTurnResult>;
+    buildContext(args: {
+        query: string;
+        sessionId?: string | null;
+        userId?: string | null;
+        visibility?: string | null;
+        metadataFilter?: Record<string, unknown> | null;
+        enabledSources?: Set<string> | null;
+        topK?: number;
+        /**
+         * Optional gross context-construction budget. 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.
+         */
+        maxTokens?: number;
+    }): Promise<ContextResponse>;
+    searchSemantic(args: {
+        query: string;
+        userId?: string | null;
+        visibility?: string | null;
+        topK?: number;
+    }): Promise<MemoryChunk[]>;
+    searchEpisodes(args: {
+        query: string;
+        userId?: string | null;
+        visibility?: string | null;
+        sessionId?: string | null;
+        topK?: number;
+    }): Promise<MemoryChunk[]>;
+    searchTaxonomic(args: {
+        query: string;
+        userId?: string | null;
+        domain?: string | null;
+        visibility?: string | null;
+        topK?: number;
+    }): Promise<MemoryChunk[]>;
+    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>>>;
+    /** Optional: release underlying resources. */
+    close?(): void | Promise<void>;
+}
+/**
+ * Optional capability: a runtime that can supply per-call ambient identity.
+ *
+ * Only app-bound runtimes running inside the platform stack have access to
+ * per-request context. This is a separate interface so the facade can detect the
+ * capability without requiring every runtime to implement it.
+ */
+export interface AmbientIdentityRuntime {
+    requestContext(): MemoryRequestContext | null;
+}
+/** Duck-typed check for the {@link AmbientIdentityRuntime} capability. */
+export declare function hasAmbientIdentity(runtime: MemoryRuntime): runtime is MemoryRuntime & AmbientIdentityRuntime;
+/**
+ * CRUD seam the facade's type-specific conveniences delegate to.
+ *
+ * Like `MemoryRuntime`, tenancy is internal to each implementation.
+ */
+export interface MemoryCrudClient {
+    createSemantic(args: {
+        label: string;
+        text: string;
+        userId: string;
+        source?: string;
+        visibility?: string;
+        agentId?: string | null;
+        metadata?: Record<string, unknown> | null;
+        upsert?: boolean;
+    }): Promise<CreateSemanticResult>;
+    getSemantic(args: {
+        label: string;
+        userId?: string | null;
+        visibility?: string | null;
+    }): Promise<unknown | null>;
+    createEpisodic(args: {
+        title: string;
+        content: string;
+        userId: string;
+        sessionId: string;
+        summaryText?: string | null;
+        participants?: string[] | null;
+        tags?: string[] | null;
+        visibility?: string;
+        metadata?: Record<string, unknown> | null;
+        agentId?: string | null;
+    }): Promise<CreateEpisodicResult>;
+    listEpisodic(args: {
+        userId?: string | null;
+        sessionId?: string | null;
+        visibility?: string | null;
+        limit?: number;
+    }): Promise<unknown[]>;
+    createTaxonomic(args: {
+        domain: string;
+        term: string;
+        definition: string;
+        userId: string;
+        relatedTerms?: string[] | null;
+        visibility?: string;
+    }): Promise<CreateTaxonomicResult>;
+    getTaxonomic(args: {
+        domain: string;
+        term?: string | null;
+        userId?: string | null;
+        visibility?: string | null;
+    }): Promise<unknown | null>;
+    getDistinctDomains(args: {
+        visibility?: string | null;
+    }): Promise<string[]>;
+    createProcedural(args: {
+        procedure: string;
+        description: string;
+        content: string;
+        userId: string;
+        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>;
+    getProcedural(args: {
+        procedure?: string | null;
+        userId?: string | null;
+        visibility?: string | null;
+        includeDeleted?: boolean;
+    }): Promise<unknown | null>;
+    /** Identity is stamped by the platform. */
+    createCustom(args: {
+        memoryType: string;
+        content: string;
+        tags?: Record<string, unknown> | null;
+        contextualMetadata?: Record<string, unknown> | null;
+    }): Promise<CustomMemorySaveResult>;
+    /** Identity is stamped by the platform. */
+    retrieveCustom(args: {
+        memoryType: string;
+        query: string;
+        tags?: Record<string, unknown> | null;
+        topK?: number;
+    }): Promise<CustomMemoryRetrieveResult>;
+    /** Optional: release underlying resources. */
+    close?(): void | Promise<void>;
+}
+//# sourceMappingURL=transport.d.ts.map

package/dist/transport.d.ts.map

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

package/dist/transport.js

@@ -0,0 +1,6 @@
+/** Seam primitives: the request context and the runtime/CRUD interfaces. */
+/** Duck-typed check for the {@link AmbientIdentityRuntime} capability. */
+export function hasAmbientIdentity(runtime) {
+    return (typeof runtime.requestContext ===
+        "function");
+}