kernl 0.6.2 → 0.6.3

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"}

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,51 @@
+import type { SearchHit } from "@kernl-sdk/retrieval";
+import type { NewMemory, MemoryRecord, MemoryRecordUpdate, MemoryScope, MemoryConfig, MemorySearchQuery, 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>[]>;
+    /**
+     * 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,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,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,107 @@
+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,
+        });
+    }
+    /**
+     * 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"}