kernl 0.6.2 → 0.7.0

package/dist/memory/handle.js

@@ -0,0 +1,128 @@
+/**
+ * Memory index handle with lazy initialization.
+ */
+import { planQuery, } from "@kernl-sdk/retrieval";
+import { getAdapterCodecs } from "./codecs/index.js";
+/**
+ * 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 class MemoryIndexHandle {
+    id;
+    index;
+    schema;
+    caps;
+    codecs;
+    providerOptions;
+    initPromise = null;
+    constructor(config) {
+        this.index = config.index;
+        this.id = config.indexId;
+        this.schema = config.schema;
+        this.caps = this.index.capabilities();
+        this.codecs = getAdapterCodecs(this.index.id);
+        this.providerOptions = config.providerOptions;
+    }
+    /**
+     * Ensure memory index exists (lazy initialization).
+     *
+     * Safe to call multiple times - initialization only runs once.
+     */
+    async ensureInit() {
+        if (!this.initPromise) {
+            this.initPromise = this.createIndex().catch((err) => {
+                this.initPromise = null;
+                throw err;
+            });
+        }
+        await this.initPromise;
+    }
+    /**
+     * Create the memory index if it doesn't exist.
+     */
+    async createIndex() {
+        try {
+            await this.index.createIndex({
+                id: this.id,
+                schema: this.codecs.schema.encode(this.schema),
+                providerOptions: this.providerOptions,
+            });
+        }
+        catch (err) {
+            // (TODO): we should probably enforce a stricter contract w/ tighter error types
+            //
+            // Ignore "already exists" errors
+            if (err.message?.includes("already exists") ||
+                err.message?.includes("AlreadyExists")) {
+                return;
+            }
+            throw err;
+        }
+    }
+    /**
+     * Search for memory records matching the query.
+     *
+     * Adapts the query to backend capabilities, degrading gracefully
+     * when hybrid or multi-signal queries aren't supported.
+     */
+    async query(input) {
+        const { input: planned } = planQuery(input, this.caps);
+        const q = this.codecs.query.encode(planned);
+        const handle = await this.handle();
+        const hits = await handle.query(q);
+        // decode hits back to IndexMemoryRecord format
+        return hits.map((hit) => ({
+            ...hit,
+            document: hit.document
+                ? this.codecs.doc.decode(hit.document)
+                : undefined,
+        }));
+    }
+    /**
+     * Insert or update memory records in the index.
+     */
+    async upsert(docs) {
+        const arr = Array.isArray(docs) ? docs : [docs];
+        const encoded = arr.map((doc) => this.codecs.doc.encode(doc));
+        const handle = await this.handle();
+        return handle.upsert(encoded);
+    }
+    /**
+     * 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.
+     */
+    async patch(patches) {
+        const handle = await this.handle();
+        return handle.patch(patches);
+    }
+    /**
+     * Remove memory records from the index.
+     */
+    async delete(ids) {
+        const handle = await this.handle();
+        return handle.delete(ids);
+    }
+    /**
+     * Add a new field to the index schema.
+     *
+     * @throws Always throws - dynamic schema modification not supported
+     */
+    async addField(_field, _schema) {
+        throw new Error("addField not supported for MemoryIndexHandle");
+    }
+    /**
+     * 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.
+     */
+    async handle() {
+        await this.ensureInit();
+        return this.index.index(this.id);
+    }
+}

package/dist/memory/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Memory module.
+ */
+export { Memory } from "./memory.js";
+export { MemoryByteEncoder } from "./encoder.js";
+export { buildMemoryIndexSchema } from "./schema.js";
+export { MemoryIndexHandle } from "./handle.js";
+export type { MemoryIndexHandleConfig } from "./handle.js";
+export type { TextByte, ImageByte, AudioByte, VideoByte, MemoryByte, IndexableByte, MemoryByteCodec, MemoryScope, MemoryKind, NewMemory, AgentMemoryCreate, MemoryConfig, MemoryReindexParams, MemoryRecord, MemoryRecordUpdate, MemoryFilter, MemoryListOptions, MemorySearchQuery, IndexMemoryRecord, IndexMemoryRecordPatch, WorkingMemorySnapshot, ShortTermMemorySnapshot, } from "./types.js";
+export type { MemoryStore } from "./store.js";
+export type { MemoryIndexBase, MemorySearchIndex, MemoryGraphIndex, MemoryArchiveIndex, GraphTraversalQuery, GraphTraversalResult, ArchiveQuery, ArchiveResult, } from "./indexes.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/memory/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAClD,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAC7C,YAAY,EAAE,uBAAuB,EAAE,MAAM,UAAU,CAAC;AAExD,YAAY,EAEV,QAAQ,EACR,SAAS,EACT,SAAS,EACT,SAAS,EACT,UAAU,EACV,aAAa,EACb,eAAe,EAEf,WAAW,EACX,UAAU,EACV,SAAS,EACT,iBAAiB,EACjB,YAAY,EACZ,mBAAmB,EACnB,YAAY,EACZ,kBAAkB,EAClB,YAAY,EACZ,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EACjB,sBAAsB,EACtB,qBAAqB,EACrB,uBAAuB,GACxB,MAAM,SAAS,CAAC;AAEjB,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAE3C,YAAY,EACV,eAAe,EACf,iBAAiB,EACjB,gBAAgB,EAChB,kBAAkB,EAClB,mBAAmB,EACnB,oBAAoB,EACpB,YAAY,EACZ,aAAa,GACd,MAAM,WAAW,CAAC"}

package/dist/memory/index.js

@@ -0,0 +1,7 @@
+/**
+ * Memory module.
+ */
+export { Memory } from "./memory.js";
+export { MemoryByteEncoder } from "./encoder.js";
+export { buildMemoryIndexSchema } from "./schema.js";
+export { MemoryIndexHandle } from "./handle.js";

package/dist/memory/indexes.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Memory index interfaces.
+ *
+ * Indexes are projections of the primary store (DB) that enable
+ * specialized query patterns (vector search, graph traversal, archival).
+ */
+import type { SearchHit } from "@kernl-sdk/retrieval";
+import type { MemoryRecord, MemoryRecordUpdate, MemorySearchQuery, IndexMemoryRecord } from "./types.js";
+/**
+ * Base interface for memory indexes.
+ *
+ * All indexes share common lifecycle operations (index, patch, delete)
+ * but differ in their query interface.
+ */
+export interface MemoryIndexBase<TQuery, TResult> {
+    readonly id: string;
+    /**
+     * Query the index.
+     */
+    query(query: TQuery): Promise<TResult>;
+    /**
+     * Index one or more memory records (idempotent upsert).
+     */
+    index(memories: MemoryRecord | MemoryRecord[]): Promise<void>;
+    /**
+     * Partially update one or more records' projections.
+     */
+    update(updates: MemoryRecordUpdate | MemoryRecordUpdate[]): Promise<void>;
+    /**
+     * Remove one or more records from this index (DB row remains).
+     */
+    delete(ids: string | string[]): Promise<void>;
+    /**
+     * Index warming (optional).
+     */
+    warm(index: string): Promise<void>;
+}
+/**
+ * Memory search index - vector/semantic search over memories.
+ */
+export interface MemorySearchIndex extends MemoryIndexBase<MemorySearchQuery, SearchHit<IndexMemoryRecord>[]> {
+}
+/**
+ * Graph traversal query (stub).
+ */
+export interface GraphTraversalQuery {
+    depth?: number;
+}
+/**
+ * Graph traversal result (stub).
+ */
+export interface GraphTraversalResult {
+    nodes: Array<{
+        id: string;
+        record?: MemoryRecord;
+    }>;
+    edges: Array<{
+        from: string;
+        to: string;
+        relation: string;
+    }>;
+}
+/**
+ * Memory graph index - relationship/graph traversal over memories (stub).
+ */
+export interface MemoryGraphIndex extends MemoryIndexBase<GraphTraversalQuery, GraphTraversalResult> {
+    /**
+     * Explicit traversal API (alias for query).
+     */
+    traverse(query: GraphTraversalQuery): Promise<GraphTraversalResult>;
+}
+/**
+ * Archive query (stub).
+ */
+export interface ArchiveQuery {
+    before?: number;
+    collections?: string[];
+}
+/**
+ * Archive result (stub).
+ */
+export interface ArchiveResult {
+    id: string;
+    uri: string;
+}
+/**
+ * Memory archive index - cold storage/archival backend (stub).
+ */
+export interface MemoryArchiveIndex extends MemoryIndexBase<ArchiveQuery, ArchiveResult[]> {
+}
+//# sourceMappingURL=indexes.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"indexes.d.ts","sourceRoot":"","sources":["../../src/memory/indexes.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEtD,OAAO,KAAK,EACV,YAAY,EACZ,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,EAClB,MAAM,SAAS,CAAC;AAEjB;;;;;GAKG;AACH,MAAM,WAAW,eAAe,CAAC,MAAM,EAAE,OAAO;IAC9C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAqD;IAExE;;OAEG;IACH,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEvC;;OAEG;IACH,KAAK,CAAC,QAAQ,EAAE,YAAY,GAAG,YAAY,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9D;;OAEG;IACH,MAAM,CAAC,OAAO,EAAE,kBAAkB,GAAG,kBAAkB,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1E;;OAEG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9C;;OAEG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,iBACf,SAAQ,eAAe,CAAC,iBAAiB,EAAE,SAAS,CAAC,iBAAiB,CAAC,EAAE,CAAC;CAAG;AAE/E;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAElC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IAEnC,KAAK,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,YAAY,CAAA;KAAE,CAAC,CAAC;IACpD,KAAK,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC9D;AAED;;GAEG;AACH,MAAM,WAAW,gBACf,SAAQ,eAAe,CAAC,mBAAmB,EAAE,oBAAoB,CAAC;IAClE;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;CACrE;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAE3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAE5B,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;GAEG;AACH,MAAM,WAAW,kBACf,SAAQ,eAAe,CAAC,YAAY,EAAE,aAAa,EAAE,CAAC;CAAG"}

package/dist/memory/indexes.js

@@ -0,0 +1,7 @@
+/**
+ * Memory index interfaces.
+ *
+ * Indexes are projections of the primary store (DB) that enable
+ * specialized query patterns (vector search, graph traversal, archival).
+ */
+export {};

package/dist/memory/memory.d.ts

@@ -0,0 +1,55 @@
+import type { SearchHit } from "@kernl-sdk/retrieval";
+import type { NewMemory, MemoryRecord, MemoryRecordUpdate, MemoryScope, MemoryConfig, MemorySearchQuery, MemoryListOptions, IndexMemoryRecord, WorkingMemorySnapshot, ShortTermMemorySnapshot, MemoryReindexParams } from "./types.js";
+/**
+ * Memory is the primary memory abstraction for agents.
+ *
+ * Sits above storage/index layers + owns cognitive policy, eviction/TTL, consolidation.
+ *
+ *  - L1 / wmem: active working set exposed to the model
+ *  - L2 / smem: bounded recent context with a TTL
+ *  - L3 / lmem: durable, structured long-term store
+ *
+ * Delegates persistence to storage adapters and optional indexes as
+ * _projections_ of the primary memory store.
+ */
+export declare class Memory {
+    private readonly store;
+    private readonly _search;
+    private readonly encoder;
+    private readonly rcodec;
+    constructor(config: MemoryConfig);
+    /**
+     * Create a new memory record.
+     * Writes to primary store first, then indexes if configured.
+     */
+    create(memory: NewMemory): Promise<MemoryRecord>;
+    /**
+     * Update an existing memory record.
+     * Updates primary store, then re-indexes or patches search index.
+     */
+    update(update: MemoryRecordUpdate): Promise<MemoryRecord>;
+    /**
+     * Semantic/metadata search across memories.
+     *
+     * Sends rich query with both text and vector - the index handle
+     * adapts based on backend capabilities (e.g. drops text for pgvector).
+     */
+    search(q: MemorySearchQuery): Promise<SearchHit<IndexMemoryRecord>[]>;
+    /**
+     * List memories matching the filter.
+     */
+    list(options?: MemoryListOptions): Promise<MemoryRecord[]>;
+    /**
+     * Repair indexing for a memory without modifying the DB row.
+     */
+    reindex(params: MemoryReindexParams): Promise<void>;
+    /**
+     * Load working memory (L1) - wmem-pinned memories for the scope.
+     */
+    loadWorkingMemory(scope: MemoryScope): Promise<WorkingMemorySnapshot>;
+    /**
+     * Load short-term memory (L2) - active smem for the scope.
+     */
+    loadShortTermMemory(scope: MemoryScope): Promise<ShortTermMemorySnapshot>;
+}
+//# sourceMappingURL=memory.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../src/memory/memory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAe,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAInE,OAAO,KAAK,EACV,SAAS,EACT,YAAY,EACZ,kBAAkB,EAClB,WAAW,EACX,YAAY,EACZ,iBAAiB,EACjB,iBAAiB,EAEjB,iBAAiB,EACjB,qBAAqB,EACrB,uBAAuB,EACvB,mBAAmB,EACpB,MAAM,SAAS,CAAC;AAGjB;;;;;;;;;;;GAWG;AACH,qBAAa,MAAM;IACjB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAc;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwC;IAEhE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkB;IAC1C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA8C;gBAEzD,MAAM,EAAE,YAAY;IAShC;;;OAGG;IACG,MAAM,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,YAAY,CAAC;IAYtD;;;OAGG;IACG,MAAM,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,YAAY,CAAC;IAe/D;;;;;OAKG;IACG,MAAM,CAAC,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,SAAS,CAAC,iBAAiB,CAAC,EAAE,CAAC;IAc3E;;OAEG;IACG,IAAI,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAIhE;;OAEG;IACG,OAAO,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBzD;;OAEG;IACG,iBAAiB,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAO3E;;OAEG;IACG,mBAAmB,CACvB,KAAK,EAAE,WAAW,GACjB,OAAO,CAAC,uBAAuB,CAAC;CAMpC"}

package/dist/memory/memory.js

@@ -0,0 +1,113 @@
+import { MEMORY_FILTER, PATCH_CODEC, recordCodec } from "./codecs/index.js";
+/**
+ * Memory is the primary memory abstraction for agents.
+ *
+ * Sits above storage/index layers + owns cognitive policy, eviction/TTL, consolidation.
+ *
+ *  - L1 / wmem: active working set exposed to the model
+ *  - L2 / smem: bounded recent context with a TTL
+ *  - L3 / lmem: durable, structured long-term store
+ *
+ * Delegates persistence to storage adapters and optional indexes as
+ * _projections_ of the primary memory store.
+ */
+export class Memory {
+    store;
+    _search;
+    encoder;
+    rcodec;
+    constructor(config) {
+        this.store = config.store;
+        this._search = config.search ?? null;
+        // TODO: default encoder using text-embedding-3-small
+        this.encoder = config.encoder;
+        this.rcodec = recordCodec(config.encoder);
+    }
+    /**
+     * Create a new memory record.
+     * Writes to primary store first, then indexes if configured.
+     */
+    async create(memory) {
+        const record = await this.store.create(memory);
+        // index into search if avail
+        if (this._search) {
+            const indexed = await this.rcodec.encode(record);
+            await this._search.upsert(indexed);
+        }
+        return record;
+    }
+    /**
+     * Update an existing memory record.
+     * Updates primary store, then re-indexes or patches search index.
+     */
+    async update(update) {
+        const record = await this.store.update(update.id, update);
+        if (!this._search)
+            return record;
+        if (update.content) {
+            const indexed = await this.rcodec.encode(record); // content changed → full re-index with new embeddings
+            await this._search.upsert(indexed);
+        }
+        else {
+            const patch = PATCH_CODEC.encode(update); // metadata only → cheap patch
+            await this._search.patch(patch);
+        }
+        return record;
+    }
+    /**
+     * Semantic/metadata search across memories.
+     *
+     * Sends rich query with both text and vector - the index handle
+     * adapts based on backend capabilities (e.g. drops text for pgvector).
+     */
+    async search(q) {
+        if (!this._search) {
+            throw new Error("search index not configured");
+        }
+        const tvec = await this.encoder.embed(q.query);
+        return this._search.query({
+            query: [{ text: q.query, tvec }],
+            filter: q.filter ? MEMORY_FILTER.encode(q.filter) : undefined,
+            topK: q.limit ?? 20,
+        });
+    }
+    /**
+     * List memories matching the filter.
+     */
+    async list(options) {
+        return this.store.list(options);
+    }
+    /**
+     * Repair indexing for a memory without modifying the DB row.
+     */
+    async reindex(params) {
+        const record = await this.store.get(params.id);
+        if (!record) {
+            throw new Error(`memory not found: ${params.id}`);
+        }
+        const indexes = params.indexes ?? ["search", "graph", "archive"];
+        if (indexes.includes("search") && this._search) {
+            const indexed = await this.rcodec.encode(record);
+            await this._search.upsert(indexed);
+        }
+    }
+    /* --- (TODO): unclear what the shape of these should be.. --- */
+    /**
+     * Load working memory (L1) - wmem-pinned memories for the scope.
+     */
+    async loadWorkingMemory(scope) {
+        const records = await this.store.list({
+            filter: { scope, wmem: true },
+        });
+        return { scope, records };
+    }
+    /**
+     * Load short-term memory (L2) - active smem for the scope.
+     */
+    async loadShortTermMemory(scope) {
+        const records = await this.store.list({
+            filter: { scope, smem: true },
+        });
+        return { scope, records };
+    }
+}

package/dist/memory/schema.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Memory index schema builder.
+ */
+import type { FieldSchema } from "@kernl-sdk/retrieval";
+/**
+ * Options for building memory index schema.
+ */
+export interface MemoryIndexSchemaOptions {
+    /**
+     * Vector dimensions for embeddings.
+     * @default 1536 (OpenAI text-embedding-3-small)
+     */
+    dimensions?: number;
+    /**
+     * Similarity metric for vector search.
+     * @default "cosine"
+     */
+    similarity?: "cosine" | "euclidean" | "dot_product";
+}
+/**
+ * Build a canonical memory index schema for vector search.
+ *
+ * Returns a schema Record that can be used with SearchIndex.createIndex().
+ *
+ * Schema includes all fields from IndexMemoryRecord:
+ * - id: primary key
+ * - namespace, entityId, agentId: scope fields (filterable, nullable)
+ * - kind, collection: memory attributes (filterable)
+ * - timestamp, createdAt, updatedAt: timestamps (filterable + sortable)
+ * - text: content text (full-text search)
+ * - tvec, ivec, avec, vvec: vector embeddings for text/image/audio/video
+ * - metadata: structured metadata (object)
+ *
+ * @example
+ * ```ts
+ * const schema = buildMemoryIndexSchema({ dimensions: 1536 });
+ * const handle = new MemoryIndexHandle({ index: vector, indexId: "kernl_memories", schema });
+ * ```
+ */
+export declare function buildMemoryIndexSchema(options?: MemoryIndexSchemaOptions): Record<string, FieldSchema>;
+//# sourceMappingURL=schema.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/memory/schema.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAExD;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,UAAU,CAAC,EAAE,QAAQ,GAAG,WAAW,GAAG,aAAa,CAAC;CACrD;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,GAAE,wBAA6B,GACrC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAgG7B"}

package/dist/memory/schema.js

@@ -0,0 +1,112 @@
+/**
+ * Memory index schema builder.
+ */
+/**
+ * Build a canonical memory index schema for vector search.
+ *
+ * Returns a schema Record that can be used with SearchIndex.createIndex().
+ *
+ * Schema includes all fields from IndexMemoryRecord:
+ * - id: primary key
+ * - namespace, entityId, agentId: scope fields (filterable, nullable)
+ * - kind, collection: memory attributes (filterable)
+ * - timestamp, createdAt, updatedAt: timestamps (filterable + sortable)
+ * - text: content text (full-text search)
+ * - tvec, ivec, avec, vvec: vector embeddings for text/image/audio/video
+ * - metadata: structured metadata (object)
+ *
+ * @example
+ * ```ts
+ * const schema = buildMemoryIndexSchema({ dimensions: 1536 });
+ * const handle = new MemoryIndexHandle({ index: vector, indexId: "kernl_memories", schema });
+ * ```
+ */
+export function buildMemoryIndexSchema(options = {}) {
+    const dimensions = options.dimensions ?? 1536;
+    const similarity = options.similarity ?? "cosine";
+    const schema = {
+        id: {
+            type: "string",
+            pk: true,
+            sortable: true,
+        },
+        // scope fields (filterable, nullable)
+        namespace: {
+            type: "string",
+            filterable: true,
+            optional: true,
+        },
+        entityId: {
+            type: "string",
+            filterable: true,
+            optional: true,
+        },
+        agentId: {
+            type: "string",
+            filterable: true,
+            optional: true,
+        },
+        // memory attributes (filterable)
+        kind: {
+            type: "string",
+            filterable: true,
+        },
+        collection: {
+            type: "string",
+            filterable: true,
+        },
+        // timestamps (filterable + sortable) - store as bigint to safely handle
+        // millisecond Unix epoch values without overflow in SQL backends.
+        timestamp: {
+            type: "bigint",
+            filterable: true,
+            sortable: true,
+        },
+        createdAt: {
+            type: "bigint",
+            filterable: true,
+            sortable: true,
+        },
+        updatedAt: {
+            type: "bigint",
+            filterable: true,
+            sortable: true,
+        },
+        // content fields
+        text: {
+            type: "string",
+            fts: true,
+            optional: true,
+        },
+        // vector fields for different modalities
+        tvec: {
+            type: "vector",
+            dimensions,
+            similarity,
+            optional: true,
+        },
+        ivec: {
+            type: "vector",
+            dimensions,
+            similarity,
+            optional: true,
+        },
+        avec: {
+            type: "vector",
+            dimensions,
+            similarity,
+            optional: true,
+        },
+        vvec: {
+            type: "vector",
+            dimensions,
+            similarity,
+            optional: true,
+        },
+        metadata: {
+            type: "object",
+            optional: true,
+        },
+    };
+    return schema;
+}

package/dist/memory/store.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Memory store interface.
+ */
+import type { MemoryRecord, NewMemory, MemoryRecordUpdate, MemoryListOptions } from "./types.js";
+/**
+ * Memory persistence store.
+ *
+ * Follows the same pattern as ThreadStore - simple CRUD operations.
+ */
+export interface MemoryStore {
+    /**
+     * Get a memory by ID.
+     */
+    get(id: string): Promise<MemoryRecord | null>;
+    /**
+     * List memories matching the filter.
+     */
+    list(options?: MemoryListOptions): Promise<MemoryRecord[]>;
+    /**
+     * Create a new memory.
+     */
+    create(memory: NewMemory): Promise<MemoryRecord>;
+    /**
+     * Update an existing memory.
+     */
+    update(id: string, patch: MemoryRecordUpdate): Promise<MemoryRecord>;
+    /**
+     * Delete a memory.
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Delete multiple memories.
+     */
+    mdelete(ids: string[]): Promise<void>;
+}
+//# sourceMappingURL=store.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/memory/store.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,SAAS,EACT,kBAAkB,EAClB,iBAAiB,EAClB,MAAM,SAAS,CAAC;AAEjB;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B;;OAEG;IACH,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;IAE9C;;OAEG;IACH,IAAI,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;IAE3D;;OAEG;IACH,MAAM,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAEjD;;OAEG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAErE;;OAEG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAElC;;OAEG;IACH,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC"}

package/dist/memory/store.js

@@ -0,0 +1,4 @@
+/**
+ * Memory store interface.
+ */
+export {};