kernl 0.6.2 → 0.7.0

package/dist/memory/codecs/domain.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Domain-level memory codecs.
+ *
+ * Codecs for transforming between memory domain types and search/index formats.
+ */
+import type { Codec, AsyncCodec } from "@kernl-sdk/shared/lib";
+import type { Filter as SearchFilter } from "@kernl-sdk/retrieval";
+import type { MemoryFilter, MemoryRecord, MemoryRecordUpdate, IndexMemoryRecord, IndexMemoryRecordPatch, MemoryByteCodec } from "../types.js";
+/**
+ * Codec for converting MemoryFilter to retrieval Filter.
+ *
+ * - scope.namespace → namespace
+ * - scope.entityId → entityId
+ * - scope.agentId → agentId
+ * - collections → collection: { $in: [...] }
+ * - after/before → timestamp: { $gt/$lt }
+ *
+ * Content field filtering (text, metadata, kind) is not currently supported.
+ * Text relevance is handled via vector similarity in the query, not filters.
+ */
+export declare const MEMORY_FILTER: Codec<MemoryFilter, SearchFilter>;
+/**
+ * Create a codec for MemoryRecord -> IndexMemoryRecord.
+ */
+export declare function recordCodec(bytecodec: MemoryByteCodec): AsyncCodec<MemoryRecord, IndexMemoryRecord>;
+/**
+ * Codec for converting MemoryRecordUpdate to IndexMemoryRecordPatch.
+ *
+ * Maps patchable fields from domain update to index patch format.
+ * wmem/smem are store-only fields and are not included.
+ * content changes require full re-index, not a patch.
+ */
+export declare const PATCH_CODEC: Codec<MemoryRecordUpdate, IndexMemoryRecordPatch>;
+//# sourceMappingURL=domain.d.ts.map

package/dist/memory/codecs/domain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"domain.d.ts","sourceRoot":"","sources":["../../../src/memory/codecs/domain.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,KAAK,EAAE,MAAM,IAAI,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEnE,OAAO,KAAK,EACV,YAAY,EACZ,YAAY,EACZ,kBAAkB,EAClB,iBAAiB,EACjB,sBAAsB,EACtB,eAAe,EAChB,MAAM,UAAU,CAAC;AAElB;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,aAAa,EAAE,KAAK,CAAC,YAAY,EAAE,YAAY,CA0B3D,CAAC;AAEF;;GAEG;AACH,wBAAgB,WAAW,CACzB,SAAS,EAAE,eAAe,GACzB,UAAU,CAAC,YAAY,EAAE,iBAAiB,CAAC,CAqB7C;AAED;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,EAAE,KAAK,CAAC,kBAAkB,EAAE,sBAAsB,CAqBzE,CAAC"}

package/dist/memory/codecs/domain.js

@@ -0,0 +1,99 @@
+/**
+ * Domain-level memory codecs.
+ *
+ * Codecs for transforming between memory domain types and search/index formats.
+ */
+/**
+ * Codec for converting MemoryFilter to retrieval Filter.
+ *
+ * - scope.namespace → namespace
+ * - scope.entityId → entityId
+ * - scope.agentId → agentId
+ * - collections → collection: { $in: [...] }
+ * - after/before → timestamp: { $gt/$lt }
+ *
+ * Content field filtering (text, metadata, kind) is not currently supported.
+ * Text relevance is handled via vector similarity in the query, not filters.
+ */
+export const MEMORY_FILTER = {
+    encode(mf) {
+        const sf = {};
+        // scope
+        if (mf.scope?.namespace !== undefined)
+            sf.namespace = mf.scope.namespace;
+        if (mf.scope?.entityId !== undefined)
+            sf.entityId = mf.scope.entityId;
+        if (mf.scope?.agentId !== undefined)
+            sf.agentId = mf.scope.agentId;
+        if (mf.collections && mf.collections.length > 0) {
+            sf.collection = { $in: mf.collections };
+        }
+        if (mf.after !== undefined || mf.before !== undefined) {
+            const ts = {};
+            if (mf.after !== undefined)
+                ts.$gt = mf.after;
+            if (mf.before !== undefined)
+                ts.$lt = mf.before;
+            sf.timestamp = ts;
+        }
+        return sf;
+    },
+    decode(_filter) {
+        throw new Error("MEMORY_FILTER.decode not implemented");
+    },
+};
+/**
+ * Create a codec for MemoryRecord -> IndexMemoryRecord.
+ */
+export function recordCodec(bytecodec) {
+    return {
+        async encode(record) {
+            const indexable = await bytecodec.encode(record.content);
+            return {
+                id: record.id,
+                namespace: record.scope.namespace ?? null,
+                entityId: record.scope.entityId ?? null,
+                agentId: record.scope.agentId ?? null,
+                kind: record.kind,
+                collection: record.collection,
+                timestamp: record.timestamp,
+                createdAt: record.createdAt,
+                updatedAt: record.updatedAt,
+                ...indexable,
+            };
+        },
+        async decode() {
+            throw new Error("recordCodec.decode not implemented");
+        },
+    };
+}
+/**
+ * Codec for converting MemoryRecordUpdate to IndexMemoryRecordPatch.
+ *
+ * Maps patchable fields from domain update to index patch format.
+ * wmem/smem are store-only fields and are not included.
+ * content changes require full re-index, not a patch.
+ */
+export const PATCH_CODEC = {
+    encode(update) {
+        const patch = { id: update.id };
+        if (update.scope?.namespace !== undefined)
+            patch.namespace = update.scope.namespace;
+        if (update.scope?.entityId !== undefined)
+            patch.entityId = update.scope.entityId;
+        if (update.scope?.agentId !== undefined)
+            patch.agentId = update.scope.agentId;
+        if (update.collection !== undefined)
+            patch.collection = update.collection;
+        if (update.timestamp !== undefined)
+            patch.timestamp = update.timestamp;
+        if (update.updatedAt !== undefined)
+            patch.updatedAt = update.updatedAt;
+        if (update.metadata !== undefined)
+            patch.metadata = update.metadata;
+        return patch;
+    },
+    decode(_patch) {
+        throw new Error("PATCH_CODEC.decode not implemented");
+    },
+};

package/dist/memory/codecs/identity.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Identity codecs - pass through unchanged.
+ *
+ * Used for backends that support the full IndexMemoryRecord schema natively.
+ */
+import type { Codec } from "@kernl-sdk/shared/lib";
+import type { FieldSchema, SearchQuery, UnknownDocument } from "@kernl-sdk/retrieval";
+import type { IndexMemoryRecord } from "../types.js";
+export declare const IDENTITY_DOC: Codec<IndexMemoryRecord, UnknownDocument>;
+export declare const IDENTITY_SCHEMA: Codec<Record<string, FieldSchema>, Record<string, FieldSchema>>;
+export declare const IDENTITY_QUERY: Codec<SearchQuery, SearchQuery>;
+//# sourceMappingURL=identity.d.ts.map

package/dist/memory/codecs/identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../../../src/memory/codecs/identity.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAEtF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAElD,eAAO,MAAM,YAAY,EAAE,KAAK,CAAC,iBAAiB,EAAE,eAAe,CAGlE,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,KAAK,CACjC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,EAC3B,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAI5B,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,KAAK,CAAC,WAAW,EAAE,WAAW,CAG1D,CAAC"}

package/dist/memory/codecs/identity.js

@@ -0,0 +1,17 @@
+/**
+ * Identity codecs - pass through unchanged.
+ *
+ * Used for backends that support the full IndexMemoryRecord schema natively.
+ */
+export const IDENTITY_DOC = {
+    encode: (doc) => doc,
+    decode: (row) => row,
+};
+export const IDENTITY_SCHEMA = {
+    encode: (schema) => schema,
+    decode: (schema) => schema,
+};
+export const IDENTITY_QUERY = {
+    encode: (q) => q,
+    decode: (q) => q,
+};

package/dist/memory/codecs/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Memory codecs.
+ *
+ * Re-exports all memory codecs:
+ * - Domain codecs (MEMORY_FILTER, PATCH_CODEC, recordCodec)
+ * - Backend codecs (TPUF_*, IDENTITY_*)
+ * - Backend codec registry (getBackendCodecs)
+ */
+import type { Codec } from "@kernl-sdk/shared/lib";
+import type { FieldSchema, SearchQuery, UnknownDocument } from "@kernl-sdk/retrieval";
+import type { IndexMemoryRecord } from "../types.js";
+export { MEMORY_FILTER, PATCH_CODEC, recordCodec } from "./domain.js";
+export { IDENTITY_DOC, IDENTITY_SCHEMA, IDENTITY_QUERY } from "./identity.js";
+export { TPUF_DOC, TPUF_SCHEMA, TPUF_QUERY } from "./tpuf.js";
+/**
+ * Backend codec set.
+ */
+export interface AdapterCodecs {
+    doc: Codec<IndexMemoryRecord, UnknownDocument>;
+    schema: Codec<Record<string, FieldSchema>, Record<string, FieldSchema>>;
+    query: Codec<SearchQuery, SearchQuery>;
+}
+/**
+ * Registry of backend codecs.
+ */
+export declare const ADAPTER_CODECS: Record<string, AdapterCodecs>;
+/**
+ * Get codecs for a backend, falling back to identity.
+ */
+export declare function getAdapterCodecs(adapterId: string): AdapterCodecs;
+//# sourceMappingURL=index.d.ts.map

package/dist/memory/codecs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/memory/codecs/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,KAAK,EACV,WAAW,EACX,WAAW,EACX,eAAe,EAChB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAKlD,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACnE,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC3E,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAE3D;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,KAAK,CAAC,iBAAiB,EAAE,eAAe,CAAC,CAAC;IAC/C,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC;IACxE,KAAK,EAAE,KAAK,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;CACxC;AAED;;GAEG;AACH,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAOxD,CAAC;AAWF;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,aAAa,CAEjE"}

package/dist/memory/codecs/index.js

@@ -0,0 +1,39 @@
+/**
+ * Memory codecs.
+ *
+ * Re-exports all memory codecs:
+ * - Domain codecs (MEMORY_FILTER, PATCH_CODEC, recordCodec)
+ * - Backend codecs (TPUF_*, IDENTITY_*)
+ * - Backend codec registry (getBackendCodecs)
+ */
+import { IDENTITY_DOC, IDENTITY_SCHEMA, IDENTITY_QUERY } from "./identity.js";
+import { TPUF_DOC, TPUF_SCHEMA, TPUF_QUERY } from "./tpuf.js";
+// re-exports
+export { MEMORY_FILTER, PATCH_CODEC, recordCodec } from "./domain.js";
+export { IDENTITY_DOC, IDENTITY_SCHEMA, IDENTITY_QUERY } from "./identity.js";
+export { TPUF_DOC, TPUF_SCHEMA, TPUF_QUERY } from "./tpuf.js";
+/**
+ * Registry of backend codecs.
+ */
+export const ADAPTER_CODECS = {
+    turbopuffer: { doc: TPUF_DOC, schema: TPUF_SCHEMA, query: TPUF_QUERY },
+    pgvector: {
+        doc: IDENTITY_DOC,
+        schema: IDENTITY_SCHEMA,
+        query: IDENTITY_QUERY,
+    },
+};
+/**
+ * Default codecs (identity) for unknown backends.
+ */
+const DEFAULT_CODECS = {
+    doc: IDENTITY_DOC,
+    schema: IDENTITY_SCHEMA,
+    query: IDENTITY_QUERY,
+};
+/**
+ * Get codecs for a backend, falling back to identity.
+ */
+export function getAdapterCodecs(adapterId) {
+    return ADAPTER_CODECS[adapterId] ?? DEFAULT_CODECS;
+}

package/dist/memory/codecs/tpuf.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Turbopuffer backend codecs.
+ *
+ * Turbopuffer constraints:
+ * - Exactly one ANN vector field named "vector" per namespace.
+ *
+ * Memory model:
+ * - IndexMemoryRecord has modality-specific vectors: tvec, ivec, avec, vvec.
+ *
+ * Mapping:
+ * - tvec (text embedding) → vector
+ * - ivec/avec/vvec are dropped (not indexed in Turbopuffer)
+ */
+import type { Codec } from "@kernl-sdk/shared/lib";
+import type { FieldSchema, SearchQuery, UnknownDocument } from "@kernl-sdk/retrieval";
+import type { IndexMemoryRecord } from "../types.js";
+/**
+ * Turbopuffer document codec.
+ *
+ * Maps tvec → vector, drops ivec/avec/vvec.
+ */
+export declare const TPUF_DOC: Codec<IndexMemoryRecord, UnknownDocument>;
+/**
+ * Turbopuffer schema codec.
+ *
+ * Maps tvec → vector, drops ivec/avec/vvec fields.
+ */
+export declare const TPUF_SCHEMA: Codec<Record<string, FieldSchema>, Record<string, FieldSchema>>;
+/**
+ * Turbopuffer query codec.
+ *
+ * Maps tvec → vector in query signals, drops ivec/avec/vvec.
+ * Operates on normalized SearchQuery (after planQuery).
+ *
+ * Defaults include to true so memory searches return all document attributes.
+ */
+export declare const TPUF_QUERY: Codec<SearchQuery, SearchQuery>;
+//# sourceMappingURL=tpuf.d.ts.map

package/dist/memory/codecs/tpuf.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tpuf.d.ts","sourceRoot":"","sources":["../../../src/memory/codecs/tpuf.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,KAAK,EACV,WAAW,EACX,WAAW,EAEX,eAAe,EAChB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAElD;;;;GAIG;AACH,eAAO,MAAM,QAAQ,EAAE,KAAK,CAAC,iBAAiB,EAAE,eAAe,CAkB9D,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,WAAW,EAAE,KAAK,CAC7B,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,EAC3B,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAmB5B,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU,EAAE,KAAK,CAAC,WAAW,EAAE,WAAW,CA6BtD,CAAC"}

package/dist/memory/codecs/tpuf.js

@@ -0,0 +1,90 @@
+/**
+ * Turbopuffer backend codecs.
+ *
+ * Turbopuffer constraints:
+ * - Exactly one ANN vector field named "vector" per namespace.
+ *
+ * Memory model:
+ * - IndexMemoryRecord has modality-specific vectors: tvec, ivec, avec, vvec.
+ *
+ * Mapping:
+ * - tvec (text embedding) → vector
+ * - ivec/avec/vvec are dropped (not indexed in Turbopuffer)
+ */
+/**
+ * Turbopuffer document codec.
+ *
+ * Maps tvec → vector, drops ivec/avec/vvec.
+ */
+export const TPUF_DOC = {
+    encode(doc) {
+        const { tvec, ivec, avec, vvec, metadata, ...rest } = doc;
+        const row = {
+            ...rest,
+            metadata: metadata, // metadata is JSONObject | null, cast to FieldValue for UnknownDocument
+        };
+        if (tvec)
+            row.vector = tvec;
+        return row;
+    },
+    decode(row) {
+        const { vector, ...rest } = row;
+        return {
+            ...rest,
+            tvec: Array.isArray(vector) ? vector : undefined,
+        };
+    },
+};
+/**
+ * Turbopuffer schema codec.
+ *
+ * Maps tvec → vector, drops ivec/avec/vvec fields.
+ */
+export const TPUF_SCHEMA = {
+    encode(schema) {
+        const result = {};
+        for (const [name, field] of Object.entries(schema)) {
+            if (name === "tvec") {
+                result.vector = field;
+            }
+            else if (name === "ivec" || name === "avec" || name === "vvec") {
+                continue;
+            }
+            else {
+                result[name] = field;
+            }
+        }
+        return result;
+    },
+    decode() {
+        throw new Error("TPUF_SCHEMA.decode not implemented");
+    },
+};
+/**
+ * Turbopuffer query codec.
+ *
+ * Maps tvec → vector in query signals, drops ivec/avec/vvec.
+ * Operates on normalized SearchQuery (after planQuery).
+ *
+ * Defaults include to true so memory searches return all document attributes.
+ */
+export const TPUF_QUERY = {
+    encode(input) {
+        // default include to true for memory search (tpuf only returns id + score without it)
+        const include = input.include ?? true;
+        if (!input.query) {
+            return { ...input, include };
+        }
+        const signals = input.query.map((signal) => {
+            const { tvec, ivec, avec, vvec, ...rest } = signal;
+            if (tvec) {
+                return { ...rest, vector: tvec };
+            }
+            return rest;
+        });
+        return { ...input, query: signals, include };
+    },
+    decode() {
+        throw new Error("TPUF_QUERY.decode not implemented");
+    },
+};

package/dist/memory/encoder.d.ts

@@ -0,0 +1,29 @@
+/**
+ * MemoryByte encoder - converts MemoryByte to IndexableByte with embeddings.
+ */
+import type { EmbeddingModel } from "@kernl-sdk/protocol";
+import type { MemoryByte, IndexableByte, MemoryByteCodec } from "./types.js";
+/**
+ * Encoder that converts MemoryByte to IndexableByte.
+ *
+ * Extracts canonical text from content and computes embeddings.
+ */
+export declare class MemoryByteEncoder implements MemoryByteCodec {
+    private readonly embedder;
+    constructor(embedder: EmbeddingModel<string>);
+    /**
+     * Encode a MemoryByte to IndexableByte.
+     * Extracts text and computes embeddings for each modality.
+     */
+    encode(byte: MemoryByte): Promise<IndexableByte>;
+    /**
+     * Decode is not implemented - IndexableByte cannot be converted back to MemoryByte.
+     */
+    decode(_indexable: IndexableByte): Promise<MemoryByte>;
+    /**
+     * Embed a text string.
+     * Exposed for query embedding.
+     */
+    embed(text: string): Promise<number[]>;
+}
+//# sourceMappingURL=encoder.d.ts.map

package/dist/memory/encoder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encoder.d.ts","sourceRoot":"","sources":["../../src/memory/encoder.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE1E;;;;GAIG;AACH,qBAAa,iBAAkB,YAAW,eAAe;IACvD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAyB;gBAEtC,QAAQ,EAAE,cAAc,CAAC,MAAM,CAAC;IAI5C;;;OAGG;IACG,MAAM,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,aAAa,CAAC;IAgBtD;;OAEG;IACG,MAAM,CAAC,UAAU,EAAE,aAAa,GAAG,OAAO,CAAC,UAAU,CAAC;IAI5D;;;OAGG;IACG,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;CAI7C"}

package/dist/memory/encoder.js

@@ -0,0 +1,45 @@
+/**
+ * MemoryByte encoder - converts MemoryByte to IndexableByte with embeddings.
+ */
+/**
+ * Encoder that converts MemoryByte to IndexableByte.
+ *
+ * Extracts canonical text from content and computes embeddings.
+ */
+export class MemoryByteEncoder {
+    embedder;
+    constructor(embedder) {
+        this.embedder = embedder;
+    }
+    /**
+     * Encode a MemoryByte to IndexableByte.
+     * Extracts text and computes embeddings for each modality.
+     */
+    async encode(byte) {
+        const text = byte.text;
+        const tvec = text ? await this.embed(text) : undefined;
+        // TODO: embed other modalities (image, audio, video)
+        // const ivec = byte.image ? await this.embedImage(byte.image) : undefined;
+        // const avec = byte.audio ? await this.embedAudio(byte.audio) : undefined;
+        // const vvec = byte.video ? await this.embedVideo(byte.video) : undefined;
+        return {
+            text,
+            tvec,
+            metadata: byte.object ?? null,
+        };
+    }
+    /**
+     * Decode is not implemented - IndexableByte cannot be converted back to MemoryByte.
+     */
+    async decode(_indexable) {
+        throw new Error("MemoryByteEncoder.decode not implemented");
+    }
+    /**
+     * Embed a text string.
+     * Exposed for query embedding.
+     */
+    async embed(text) {
+        const result = await this.embedder.embed({ values: [text] });
+        return result.embeddings[0] ?? [];
+    }
+}

package/dist/memory/handle.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Memory index handle with lazy initialization.
+ */
+import { type SearchIndex, type IndexHandle, type QueryInput, type SearchHit, type DocumentPatch, type UpsertResult, type PatchResult, type DeleteResult, type FieldSchema } from "@kernl-sdk/retrieval";
+import type { IndexMemoryRecord } from "./types.js";
+/**
+ * Configuration for MemoryIndexHandle.
+ */
+export interface MemoryIndexHandleConfig {
+    /**
+     * The underlying search index backend.
+     */
+    index: SearchIndex;
+    /**
+     * Index identifier (e.g., "kernl_memories_index").
+     */
+    indexId: string;
+    /**
+     * Field schema for the memory index.
+     */
+    schema: Record<string, FieldSchema>;
+    /**
+     * Backend-specific options passed to SearchIndex.createIndex().
+     */
+    providerOptions?: Record<string, unknown>;
+}
+/**
+ * Domain-aware index handle for memory records with lazy initialization.
+ *
+ * - Wraps a SearchIndex and ensures the memory index is created before any operation.
+ * - Normalizes the idiosyncrasies of search adapters (capabilities, weird rules, ... - e.g. tpuf requires vector fields named
+ * literally 'vector' - dumb shit like this..)
+ */
+export declare class MemoryIndexHandle implements IndexHandle<IndexMemoryRecord> {
+    readonly id: string;
+    private readonly index;
+    private readonly schema;
+    private readonly caps;
+    private readonly codecs;
+    private readonly providerOptions?;
+    private initPromise;
+    constructor(config: MemoryIndexHandleConfig);
+    /**
+     * Ensure memory index exists (lazy initialization).
+     *
+     * Safe to call multiple times - initialization only runs once.
+     */
+    private ensureInit;
+    /**
+     * Create the memory index if it doesn't exist.
+     */
+    private createIndex;
+    /**
+     * Search for memory records matching the query.
+     *
+     * Adapts the query to backend capabilities, degrading gracefully
+     * when hybrid or multi-signal queries aren't supported.
+     */
+    query(input: QueryInput): Promise<SearchHit<IndexMemoryRecord>[]>;
+    /**
+     * Insert or update memory records in the index.
+     */
+    upsert(docs: IndexMemoryRecord | IndexMemoryRecord[]): Promise<UpsertResult>;
+    /**
+     * Partially update memory records without re-indexing vectors.
+     *
+     * Note: Patches don't include vector fields so we cast directly.
+     * Metadata field type mismatch (JSONObject vs FieldValue) is handled at runtime.
+     */
+    patch(patches: DocumentPatch<IndexMemoryRecord> | DocumentPatch<IndexMemoryRecord>[]): Promise<PatchResult>;
+    /**
+     * Remove memory records from the index.
+     */
+    delete(ids: string | string[]): Promise<DeleteResult>;
+    /**
+     * Add a new field to the index schema.
+     *
+     * @throws Always throws - dynamic schema modification not supported
+     */
+    addField(_field: string, _schema: FieldSchema): Promise<void>;
+    /**
+     * Get an initialized underlying index handle.
+     *
+     * Returns a handle typed for UnknownDocument since we encode/decode
+     * through the adapter codecs for backend-specific field mapping.
+     */
+    private handle;
+}
+//# sourceMappingURL=handle.d.ts.map

package/dist/memory/handle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handle.d.ts","sourceRoot":"","sources":["../../src/memory/handle.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAEL,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,SAAS,EACd,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,WAAW,EAGjB,MAAM,sBAAsB,CAAC;AAG9B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAEjD;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC;;OAEG;IACH,KAAK,EAAE,WAAW,CAAC;IAEnB;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAEpC;;OAEG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC3C;AAED;;;;;;GAMG;AACH,qBAAa,iBAAkB,YAAW,WAAW,CAAC,iBAAiB,CAAC;IACtE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAc;IACpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA8B;IACrD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAqB;IAC1C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;IACvC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC,CAA0B;IAE3D,OAAO,CAAC,WAAW,CAA8B;gBAErC,MAAM,EAAE,uBAAuB;IAS3C;;;;OAIG;YACW,UAAU;IAUxB;;OAEG;YACW,WAAW;IAqBzB;;;;;OAKG;IACG,KAAK,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,iBAAiB,CAAC,EAAE,CAAC;IAevE;;OAEG;IACG,MAAM,CACV,IAAI,EAAE,iBAAiB,GAAG,iBAAiB,EAAE,GAC5C,OAAO,CAAC,YAAY,CAAC;IAOxB;;;;;OAKG;IACG,KAAK,CACT,OAAO,EACH,aAAa,CAAC,iBAAiB,CAAC,GAChC,aAAa,CAAC,iBAAiB,CAAC,EAAE,GACrC,OAAO,CAAC,WAAW,CAAC;IAKvB;;OAEG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC,YAAY,CAAC;IAK3D;;;;OAIG;IACG,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAInE;;;;;OAKG;YACW,MAAM;CAIrB"}