@kernl-sdk/storage 0.1.11 → 0.1.12

package/.turbo/turbo-build.log

@@ -1,4 +1,4 @@
 
-> @kernl-sdk/storage@0.1.10 build /Users/andjones/Documents/projects/kernl/packages/storage/core
+> @kernl-sdk/storage@0.1.11 build /Users/andjones/Documents/projects/kernl/packages/storage/core
 > tsc && tsc-alias --resolve-full-paths
 

package/.turbo/turbo-check-types.log

@@ -0,0 +1,4 @@
+
+> @kernl-sdk/storage@0.1.11 check-types /Users/andjones/Documents/projects/kernl/packages/storage/core
+> tsc --noEmit
+

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @kernl/storage
 
+## 0.1.12
+
+### Patch Changes
+
+- Updated dependencies [a7d6138]
+  - kernl@0.6.3
+
 ## 0.1.11
 
 ### Patch Changes

package/dist/index.d.ts

@@ -3,6 +3,8 @@
  */
 export * from "./base.js";
 export * from "./thread/index.js";
+export * from "./memory/index.js";
 export * from "./serde/thread.js";
+export * from "./serde/memory.js";
 export * from "./table.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,QAAQ,CAAC;AACvB,cAAc,UAAU,CAAC;AACzB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,QAAQ,CAAC;AACvB,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,SAAS,CAAC"}

package/dist/index.js

@@ -3,5 +3,7 @@
  */
 export * from "./base.js";
 export * from "./thread/index.js";
+export * from "./memory/index.js";
 export * from "./serde/thread.js";
+export * from "./serde/memory.js";
 export * from "./table.js";

package/dist/memory/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Memory storage types and schema.
+ */
+export { TABLE_MEMORIES, MemoryDBRecordSchema, type MemoryDBRecord, } from "./schema.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,EACL,cAAc,EACd,oBAAoB,EACpB,KAAK,cAAc,GACpB,MAAM,UAAU,CAAC"}

package/dist/memory/index.js

@@ -0,0 +1,4 @@
+/**
+ * Memory storage types and schema.
+ */
+export { TABLE_MEMORIES, MemoryDBRecordSchema, } from "./schema.js";

package/dist/memory/schema.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Memory table definition and record schema.
+ */
+import { z } from "zod";
+export declare const TABLE_MEMORIES: import("../table.js").Table<"memories", {
+    readonly metadata: import("../table.js").Column<unknown>;
+    readonly created_at: import("../table.js").Column<number>;
+    readonly updated_at: import("../table.js").Column<number>;
+    readonly id: import("../table.js").Column<string>;
+    readonly namespace: import("../table.js").Column<string>;
+    readonly entity_id: import("../table.js").Column<string>;
+    readonly agent_id: import("../table.js").Column<string>;
+    readonly kind: import("../table.js").Column<string>;
+    readonly collection: import("../table.js").Column<string>;
+    readonly content: import("../table.js").Column<unknown>;
+    readonly wmem: import("../table.js").Column<boolean>;
+    readonly smem_expires_at: import("../table.js").Column<number>;
+    readonly timestamp: import("../table.js").Column<number>;
+}>;
+export declare const MemoryDBRecordSchema: z.ZodObject<{
+    id: z.ZodString;
+    namespace: z.ZodNullable<z.ZodString>;
+    entity_id: z.ZodNullable<z.ZodString>;
+    agent_id: z.ZodNullable<z.ZodString>;
+    kind: z.ZodEnum<{
+        episodic: "episodic";
+        semantic: "semantic";
+    }>;
+    collection: z.ZodString;
+    content: z.ZodObject<{
+        text: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodObject<{
+            data: z.ZodUnion<readonly [z.ZodCustom<Uint8Array<ArrayBufferLike>, Uint8Array<ArrayBufferLike>>, z.ZodString]>;
+            mime: z.ZodString;
+            alt: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        audio: z.ZodOptional<z.ZodObject<{
+            data: z.ZodUnion<readonly [z.ZodCustom<Uint8Array<ArrayBufferLike>, Uint8Array<ArrayBufferLike>>, z.ZodString]>;
+            mime: z.ZodString;
+        }, z.core.$strip>>;
+        video: z.ZodOptional<z.ZodObject<{
+            data: z.ZodUnion<readonly [z.ZodCustom<Uint8Array<ArrayBufferLike>, Uint8Array<ArrayBufferLike>>, z.ZodString]>;
+            mime: z.ZodString;
+        }, z.core.$strip>>;
+        object: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>;
+    wmem: z.ZodBoolean;
+    smem_expires_at: z.ZodNullable<z.ZodCoercedNumber<unknown>>;
+    timestamp: z.ZodCoercedNumber<unknown>;
+    created_at: z.ZodCoercedNumber<unknown>;
+    updated_at: z.ZodCoercedNumber<unknown>;
+    metadata: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export type MemoryDBRecord = z.infer<typeof MemoryDBRecordSchema>;
+//# 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,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB,eAAO,MAAM,cAAc;;;;;;;;;;;;;;EA0B1B,CAAC;AAyCF,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAc/B,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC"}

package/dist/memory/schema.js

@@ -0,0 +1,74 @@
+/**
+ * Memory table definition and record schema.
+ */
+import { z } from "zod";
+import { text, bigint, boolean, jsonb, timestamps, defineTable } from "../table.js";
+/* ---- Table Definition ---- */
+export const TABLE_MEMORIES = defineTable("memories", {
+    id: text().primaryKey(),
+    namespace: text().nullable(),
+    entity_id: text().nullable(),
+    agent_id: text().nullable(),
+    kind: text(), // "episodic" | "semantic"
+    collection: text(),
+    content: jsonb(),
+    wmem: boolean().default(false),
+    smem_expires_at: bigint().nullable(),
+    timestamp: bigint(),
+    ...timestamps,
+    metadata: jsonb().nullable(),
+}, [
+    { kind: "index", columns: ["namespace"] },
+    { kind: "index", columns: ["entity_id"] },
+    { kind: "index", columns: ["agent_id"] },
+    { kind: "index", columns: ["kind"] },
+    { kind: "index", columns: ["collection"] },
+    { kind: "index", columns: ["wmem"] },
+    { kind: "index", columns: ["timestamp"] },
+    { kind: "index", columns: ["created_at"] },
+]);
+/* ---- Record Schema ---- */
+const TextByteSchema = z.string();
+// Binary data can be Uint8Array or base64/URI string
+const BinaryDataSchema = z.union([
+    z.custom((val) => val instanceof Uint8Array),
+    z.string(),
+]);
+const ImageByteSchema = z.object({
+    data: BinaryDataSchema,
+    mime: z.string(),
+    alt: z.string().optional(),
+});
+const AudioByteSchema = z.object({
+    data: BinaryDataSchema,
+    mime: z.string(),
+});
+const VideoByteSchema = z.object({
+    data: BinaryDataSchema,
+    mime: z.string(),
+});
+const MemoryByteSchema = z.object({
+    text: TextByteSchema.optional(),
+    image: ImageByteSchema.optional(),
+    audio: AudioByteSchema.optional(),
+    video: VideoByteSchema.optional(),
+    object: z.record(z.string(), z.unknown()).optional(),
+});
+const MemoryKindSchema = z.enum(["episodic", "semantic"]);
+// pg returns BIGINT as string, so we coerce to number
+const pgBigint = z.coerce.number().int();
+export const MemoryDBRecordSchema = z.object({
+    id: z.string(),
+    namespace: z.string().nullable(),
+    entity_id: z.string().nullable(),
+    agent_id: z.string().nullable(),
+    kind: MemoryKindSchema,
+    collection: z.string(),
+    content: MemoryByteSchema,
+    wmem: z.boolean(),
+    smem_expires_at: pgBigint.nullable(),
+    timestamp: pgBigint,
+    created_at: pgBigint,
+    updated_at: pgBigint,
+    metadata: z.record(z.string(), z.unknown()).nullable(),
+});

package/dist/serde/__tests__/memory.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=memory.test.d.ts.map

package/dist/serde/__tests__/memory.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.test.d.ts","sourceRoot":"","sources":["../../../src/serde/__tests__/memory.test.ts"],"names":[],"mappings":""}

package/dist/serde/__tests__/memory.test.js

@@ -0,0 +1,244 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import { MemoryRecordCodec, NewMemoryCodec } from "../memory.js";
+describe("NewMemoryCodec", () => {
+    beforeEach(() => {
+        vi.useFakeTimers();
+        vi.setSystemTime(new Date("2024-01-01T00:00:00.000Z"));
+    });
+    describe("encode", () => {
+        it("should apply default values", () => {
+            const memory = {
+                id: "mem-1",
+                scope: { namespace: "test" },
+                kind: "episodic",
+                collection: "facts",
+                content: { text: "Hello world" },
+            };
+            const record = NewMemoryCodec.encode(memory);
+            expect(record.wmem).toBe(false);
+            expect(record.smem_expires_at).toBeNull();
+            expect(record.metadata).toBeNull();
+        });
+        it("should preserve provided values", () => {
+            const memory = {
+                id: "mem-2",
+                scope: { namespace: "test", entityId: "user-1", agentId: "agent-1" },
+                kind: "semantic",
+                collection: "preferences",
+                content: { object: { key: "value" } },
+                wmem: true,
+                smem: { expiresAt: 1704153600000 },
+                timestamp: 1704067200000,
+                metadata: { source: "user" },
+            };
+            const record = NewMemoryCodec.encode(memory);
+            expect(record.namespace).toBe("test");
+            expect(record.entity_id).toBe("user-1");
+            expect(record.agent_id).toBe("agent-1");
+            expect(record.kind).toBe("semantic");
+            expect(record.collection).toBe("preferences");
+            expect(record.content).toEqual({ object: { key: "value" } });
+            expect(record.wmem).toBe(true);
+            expect(record.smem_expires_at).toBe(1704153600000);
+            expect(record.timestamp).toBe(1704067200000);
+            expect(record.metadata).toEqual({ source: "user" });
+        });
+        it("should apply current timestamp when not provided", () => {
+            const now = Date.now();
+            const memory = {
+                id: "mem-3",
+                scope: { namespace: "test" },
+                kind: "episodic",
+                collection: "facts",
+                content: { text: "Test" },
+            };
+            const record = NewMemoryCodec.encode(memory);
+            expect(record.timestamp).toBe(now);
+            expect(record.created_at).toBe(now);
+            expect(record.updated_at).toBe(now);
+        });
+        it("should handle null scope fields", () => {
+            const memory = {
+                id: "mem-4",
+                scope: {},
+                kind: "episodic",
+                collection: "facts",
+                content: { text: "Test" },
+            };
+            const record = NewMemoryCodec.encode(memory);
+            expect(record.namespace).toBeNull();
+            expect(record.entity_id).toBeNull();
+            expect(record.agent_id).toBeNull();
+        });
+    });
+    describe("decode", () => {
+        it("should decode MemoryDBRecord to NewMemory", () => {
+            const record = {
+                id: "mem-1",
+                namespace: "test",
+                entity_id: "user-1",
+                agent_id: "agent-1",
+                kind: "episodic",
+                collection: "facts",
+                content: { text: "Hello" },
+                wmem: true,
+                smem_expires_at: 1704153600000,
+                timestamp: 1704067200000,
+                created_at: 1704067200000,
+                updated_at: 1704067200000,
+                metadata: { key: "value" },
+            };
+            const memory = NewMemoryCodec.decode(record);
+            expect(memory.id).toBe("mem-1");
+            expect(memory.scope.namespace).toBe("test");
+            expect(memory.scope.entityId).toBe("user-1");
+            expect(memory.scope.agentId).toBe("agent-1");
+            expect(memory.kind).toBe("episodic");
+            expect(memory.collection).toBe("facts");
+            expect(memory.content).toEqual({ text: "Hello" });
+            expect(memory.wmem).toBe(true);
+            expect(memory.smem?.expiresAt).toBe(1704153600000);
+            expect(memory.timestamp).toBe(1704067200000);
+            expect(memory.metadata).toEqual({ key: "value" });
+        });
+        it("should handle null values", () => {
+            const record = {
+                id: "mem-2",
+                namespace: null,
+                entity_id: null,
+                agent_id: null,
+                kind: "semantic",
+                collection: "facts",
+                content: { text: "Test" },
+                wmem: false,
+                smem_expires_at: null,
+                timestamp: 1704067200000,
+                created_at: 1704067200000,
+                updated_at: 1704067200000,
+                metadata: null,
+            };
+            const memory = NewMemoryCodec.decode(record);
+            expect(memory.scope.namespace).toBeUndefined();
+            expect(memory.scope.entityId).toBeUndefined();
+            expect(memory.scope.agentId).toBeUndefined();
+            expect(memory.smem).toBeUndefined();
+            expect(memory.metadata).toBeNull();
+        });
+    });
+});
+describe("MemoryRecordCodec", () => {
+    describe("encode", () => {
+        it("should encode MemoryRecord to MemoryDBRecord", () => {
+            const record = {
+                id: "mem-1",
+                scope: { namespace: "test", entityId: "user-1", agentId: "agent-1" },
+                kind: "episodic",
+                collection: "facts",
+                content: { text: "Hello" },
+                wmem: true,
+                smem: { expiresAt: 1704153600000 },
+                timestamp: 1704067200000,
+                createdAt: 1704067200000,
+                updatedAt: 1704070800000,
+                metadata: { source: "test" },
+            };
+            const dbRecord = MemoryRecordCodec.encode(record);
+            expect(dbRecord.id).toBe("mem-1");
+            expect(dbRecord.namespace).toBe("test");
+            expect(dbRecord.entity_id).toBe("user-1");
+            expect(dbRecord.agent_id).toBe("agent-1");
+            expect(dbRecord.kind).toBe("episodic");
+            expect(dbRecord.collection).toBe("facts");
+            expect(dbRecord.content).toEqual({ text: "Hello" });
+            expect(dbRecord.wmem).toBe(true);
+            expect(dbRecord.smem_expires_at).toBe(1704153600000);
+            expect(dbRecord.timestamp).toBe(1704067200000);
+            expect(dbRecord.created_at).toBe(1704067200000);
+            expect(dbRecord.updated_at).toBe(1704070800000);
+            expect(dbRecord.metadata).toEqual({ source: "test" });
+        });
+        it("should handle undefined scope fields as null", () => {
+            const record = {
+                id: "mem-2",
+                scope: {},
+                kind: "semantic",
+                collection: "facts",
+                content: { text: "Test" },
+                wmem: false,
+                smem: { expiresAt: null },
+                timestamp: 1704067200000,
+                createdAt: 1704067200000,
+                updatedAt: 1704067200000,
+                metadata: null,
+            };
+            const dbRecord = MemoryRecordCodec.encode(record);
+            expect(dbRecord.namespace).toBeNull();
+            expect(dbRecord.entity_id).toBeNull();
+            expect(dbRecord.agent_id).toBeNull();
+        });
+    });
+    describe("decode", () => {
+        it("should decode MemoryDBRecord to MemoryRecord", () => {
+            const dbRecord = {
+                id: "mem-1",
+                namespace: "test",
+                entity_id: "user-1",
+                agent_id: "agent-1",
+                kind: "semantic",
+                collection: "facts",
+                content: { object: { foo: "bar" } },
+                wmem: false,
+                smem_expires_at: null,
+                timestamp: 1704067200000,
+                created_at: 1704067200000,
+                updated_at: 1704070800000,
+                metadata: null,
+            };
+            const record = MemoryRecordCodec.decode(dbRecord);
+            expect(record.id).toBe("mem-1");
+            expect(record.scope.namespace).toBe("test");
+            expect(record.scope.entityId).toBe("user-1");
+            expect(record.scope.agentId).toBe("agent-1");
+            expect(record.kind).toBe("semantic");
+            expect(record.collection).toBe("facts");
+            expect(record.content).toEqual({ object: { foo: "bar" } });
+            expect(record.wmem).toBe(false);
+            expect(record.smem.expiresAt).toBeNull();
+            expect(record.timestamp).toBe(1704067200000);
+            expect(record.createdAt).toBe(1704067200000);
+            expect(record.updatedAt).toBe(1704070800000);
+            expect(record.metadata).toBeNull();
+        });
+    });
+    describe("round-trip encoding/decoding", () => {
+        it("should preserve data through encode -> decode cycle", () => {
+            const original = {
+                id: "mem-rt",
+                scope: { namespace: "test", entityId: "user-1" },
+                kind: "episodic",
+                collection: "conversations",
+                content: { text: "Round trip test" },
+                wmem: true,
+                smem: { expiresAt: 1704153600000 },
+                timestamp: 1704067200000,
+                createdAt: 1704067200000,
+                updatedAt: 1704070800000,
+                metadata: { roundTrip: true },
+            };
+            const encoded = MemoryRecordCodec.encode(original);
+            const decoded = MemoryRecordCodec.decode(encoded);
+            expect(decoded.id).toBe(original.id);
+            expect(decoded.scope.namespace).toBe(original.scope.namespace);
+            expect(decoded.scope.entityId).toBe(original.scope.entityId);
+            expect(decoded.kind).toBe(original.kind);
+            expect(decoded.collection).toBe(original.collection);
+            expect(decoded.content).toEqual(original.content);
+            expect(decoded.wmem).toBe(original.wmem);
+            expect(decoded.smem.expiresAt).toBe(original.smem.expiresAt);
+            expect(decoded.timestamp).toBe(original.timestamp);
+            expect(decoded.createdAt).toBe(original.createdAt);
+            expect(decoded.updatedAt).toBe(original.updatedAt);
+            expect(decoded.metadata).toEqual(original.metadata);
+        });
+    });
+});

package/dist/serde/memory.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Memory serialization - codecs for converting between domain types and database records.
+ */
+import type { MemoryRecord, NewMemory } from "kernl";
+import { type Codec } from "@kernl-sdk/shared/lib";
+export declare const MemoryRecordCodec: Codec<MemoryRecord, {
+    id: string;
+    namespace: string | null;
+    entity_id: string | null;
+    agent_id: string | null;
+    kind: "episodic" | "semantic";
+    collection: string;
+    content: {
+        text?: string | undefined;
+        image?: {
+            data: string | Uint8Array<ArrayBufferLike>;
+            mime: string;
+            alt?: string | undefined;
+        } | undefined;
+        audio?: {
+            data: string | Uint8Array<ArrayBufferLike>;
+            mime: string;
+        } | undefined;
+        video?: {
+            data: string | Uint8Array<ArrayBufferLike>;
+            mime: string;
+        } | undefined;
+        object?: Record<string, unknown> | undefined;
+    };
+    wmem: boolean;
+    smem_expires_at: number | null;
+    timestamp: number;
+    created_at: number;
+    updated_at: number;
+    metadata: Record<string, unknown> | null;
+}>;
+export declare const NewMemoryCodec: Codec<NewMemory, {
+    id: string;
+    namespace: string | null;
+    entity_id: string | null;
+    agent_id: string | null;
+    kind: "episodic" | "semantic";
+    collection: string;
+    content: {
+        text?: string | undefined;
+        image?: {
+            data: string | Uint8Array<ArrayBufferLike>;
+            mime: string;
+            alt?: string | undefined;
+        } | undefined;
+        audio?: {
+            data: string | Uint8Array<ArrayBufferLike>;
+            mime: string;
+        } | undefined;
+        video?: {
+            data: string | Uint8Array<ArrayBufferLike>;
+            mime: string;
+        } | undefined;
+        object?: Record<string, unknown> | undefined;
+    };
+    wmem: boolean;
+    smem_expires_at: number | null;
+    timestamp: number;
+    created_at: number;
+    updated_at: number;
+    metadata: Record<string, unknown> | null;
+}>;
+//# sourceMappingURL=memory.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../src/serde/memory.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAA0B,MAAM,OAAO,CAAC;AAE7E,OAAO,EAAE,KAAK,KAAK,EAAmB,MAAM,uBAAuB,CAAC;AAoDpE,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAG5B,CAAC;AA8CH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAGzB,CAAC"}

package/dist/serde/memory.js

@@ -0,0 +1,99 @@
+/**
+ * Memory serialization - codecs for converting between domain types and database records.
+ */
+import { neapolitanCodec } from "@kernl-sdk/shared/lib";
+import { MemoryDBRecordSchema } from "../memory/schema.js";
+/* ---- Codecs ---- */
+/**
+ * MemoryRecord codec - converts between domain MemoryRecord and MemoryDBRecord.
+ */
+const rawMemoryRecordCodec = {
+    encode(record) {
+        return {
+            id: record.id,
+            namespace: record.scope.namespace ?? null,
+            entity_id: record.scope.entityId ?? null,
+            agent_id: record.scope.agentId ?? null,
+            kind: record.kind,
+            collection: record.collection,
+            content: record.content,
+            wmem: record.wmem,
+            smem_expires_at: record.smem.expiresAt,
+            timestamp: record.timestamp,
+            created_at: record.createdAt,
+            updated_at: record.updatedAt,
+            metadata: record.metadata,
+        };
+    },
+    decode(row) {
+        const base = {
+            id: row.id,
+            scope: {
+                namespace: row.namespace ?? undefined,
+                entityId: row.entity_id ?? undefined,
+                agentId: row.agent_id ?? undefined,
+            },
+            collection: row.collection,
+            content: row.content,
+            wmem: row.wmem,
+            smem: {
+                expiresAt: row.smem_expires_at ? Number(row.smem_expires_at) : null,
+            },
+            timestamp: Number(row.timestamp),
+            createdAt: Number(row.created_at),
+            updatedAt: Number(row.updated_at),
+            metadata: row.metadata,
+        };
+        return { ...base, kind: row.kind };
+    },
+};
+export const MemoryRecordCodec = neapolitanCodec({
+    codec: rawMemoryRecordCodec,
+    schema: MemoryDBRecordSchema,
+});
+/**
+ * NewMemory codec - converts NewMemory input to MemoryDBRecord for insertion.
+ */
+const rawNewMemoryCodec = {
+    encode(memory) {
+        const now = Date.now();
+        return {
+            id: memory.id,
+            namespace: memory.scope.namespace ?? null,
+            entity_id: memory.scope.entityId ?? null,
+            agent_id: memory.scope.agentId ?? null,
+            kind: memory.kind,
+            collection: memory.collection,
+            content: memory.content,
+            wmem: memory.wmem ?? false,
+            smem_expires_at: memory.smem?.expiresAt ?? null,
+            timestamp: memory.timestamp ?? now,
+            created_at: now,
+            updated_at: now,
+            metadata: memory.metadata ?? null,
+        };
+    },
+    decode(row) {
+        return {
+            id: row.id,
+            scope: {
+                namespace: row.namespace ?? undefined,
+                entityId: row.entity_id ?? undefined,
+                agentId: row.agent_id ?? undefined,
+            },
+            kind: row.kind,
+            collection: row.collection,
+            content: row.content,
+            wmem: row.wmem,
+            smem: row.smem_expires_at
+                ? { expiresAt: Number(row.smem_expires_at) }
+                : undefined,
+            timestamp: Number(row.timestamp),
+            metadata: row.metadata,
+        };
+    },
+};
+export const NewMemoryCodec = neapolitanCodec({
+    codec: rawNewMemoryCodec,
+    schema: MemoryDBRecordSchema,
+});

package/dist/table.d.ts

@@ -1,7 +1,7 @@
 /**
  * Schema name for all kernl tables.
  */
-export declare const SCHEMA_NAME = "kernl";
+export declare const KERNL_SCHEMA_NAME = "kernl";
 /**
  * Table definition with name, columns, and optional constraints.
  */
@@ -14,7 +14,7 @@ export interface Table<Name extends string, Cols extends Record<string, Column>>
  * Define a table with name, columns, and optional constraints.
  */
 export declare function defineTable<const Name extends string, const Cols extends Record<string, Column>>(name: Name, columns: Cols, constraints?: TableConstraint[]): Table<Name, Cols>;
-export type ColumnType = "text" | "integer" | "bigint" | "jsonb";
+export type ColumnType = "text" | "integer" | "bigint" | "boolean" | "jsonb";
 export type OnDeleteAction = "CASCADE" | "SET NULL" | "RESTRICT";
 /**
  * Column definition with type and constraints.
@@ -45,6 +45,7 @@ export interface Column<T = unknown> {
 export declare const text: () => Column<string>;
 export declare const integer: () => Column<number>;
 export declare const bigint: () => Column<number>;
+export declare const boolean: () => Column<boolean>;
 export declare const jsonb: <T = unknown>() => Column<T>;
 export declare const timestamps: {
     created_at: Column<number>;

package/dist/table.d.ts.map

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

package/dist/table.js

@@ -1,7 +1,7 @@
 /**
  * Schema name for all kernl tables.
  */
-export const SCHEMA_NAME = "kernl";
+export const KERNL_SCHEMA_NAME = "kernl";
 /**
  * Define a table with name, columns, and optional constraints.
  */
@@ -16,6 +16,7 @@ export function defineTable(name, columns, constraints) {
 export const text = () => col("text");
 export const integer = () => col("integer");
 export const bigint = () => col("bigint");
+export const boolean = () => col("boolean");
 export const jsonb = () => col("jsonb");
 export const timestamps = {
     created_at: bigint(),
@@ -60,6 +61,8 @@ function col(type) {
                 case "integer":
                 case "bigint":
                     return String(val);
+                case "boolean":
+                    return val ? "TRUE" : "FALSE";
                 case "jsonb":
                     return `'${JSON.stringify(val)}'`;
             }
@@ -71,6 +74,8 @@ function col(type) {
                 case "integer":
                 case "bigint":
                     return Number.parseInt(val, 10);
+                case "boolean":
+                    return (val === "t" || val === "true" || val === "TRUE");
                 case "jsonb":
                     return JSON.parse(val);
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kernl-sdk/storage",
-  "version": "0.1.11",
+  "version": "0.1.12",
   "description": "Core storage abstractions for kernl",
   "keywords": [
     "kernl",
@@ -36,9 +36,9 @@
   },
   "dependencies": {
     "zod": "^4.1.12",
-    "kernl": "0.6.2",
     "@kernl-sdk/protocol": "0.2.5",
-    "@kernl-sdk/shared": "0.1.6"
+    "@kernl-sdk/shared": "0.1.6",
+    "kernl": "0.6.3"
   },
   "scripts": {
     "build": "tsc && tsc-alias --resolve-full-paths",

package/src/index.ts

@@ -4,5 +4,7 @@
 
 export * from "./base";
 export * from "./thread";
+export * from "./memory";
 export * from "./serde/thread";
+export * from "./serde/memory";
 export * from "./table";

package/src/memory/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Memory storage types and schema.
+ */
+
+export {
+  TABLE_MEMORIES,
+  MemoryDBRecordSchema,
+  type MemoryDBRecord,
+} from "./schema";

package/src/memory/schema.ts

@@ -0,0 +1,93 @@
+/**
+ * Memory table definition and record schema.
+ */
+
+import { z } from "zod";
+import { text, bigint, boolean, jsonb, timestamps, defineTable } from "@/table";
+
+/* ---- Table Definition ---- */
+
+export const TABLE_MEMORIES = defineTable(
+  "memories",
+  {
+    id: text().primaryKey(),
+    namespace: text().nullable(),
+    entity_id: text().nullable(),
+    agent_id: text().nullable(),
+    kind: text(), // "episodic" | "semantic"
+    collection: text(),
+    content: jsonb(),
+    wmem: boolean().default(false),
+    smem_expires_at: bigint().nullable(),
+    timestamp: bigint(),
+    ...timestamps,
+    metadata: jsonb().nullable(),
+  },
+  [
+    { kind: "index", columns: ["namespace"] },
+    { kind: "index", columns: ["entity_id"] },
+    { kind: "index", columns: ["agent_id"] },
+    { kind: "index", columns: ["kind"] },
+    { kind: "index", columns: ["collection"] },
+    { kind: "index", columns: ["wmem"] },
+    { kind: "index", columns: ["timestamp"] },
+    { kind: "index", columns: ["created_at"] },
+  ],
+);
+
+/* ---- Record Schema ---- */
+
+const TextByteSchema = z.string();
+
+// Binary data can be Uint8Array or base64/URI string
+const BinaryDataSchema = z.union([
+  z.custom<Uint8Array>((val) => val instanceof Uint8Array),
+  z.string(),
+]);
+
+const ImageByteSchema = z.object({
+  data: BinaryDataSchema,
+  mime: z.string(),
+  alt: z.string().optional(),
+});
+
+const AudioByteSchema = z.object({
+  data: BinaryDataSchema,
+  mime: z.string(),
+});
+
+const VideoByteSchema = z.object({
+  data: BinaryDataSchema,
+  mime: z.string(),
+});
+
+const MemoryByteSchema = z.object({
+  text: TextByteSchema.optional(),
+  image: ImageByteSchema.optional(),
+  audio: AudioByteSchema.optional(),
+  video: VideoByteSchema.optional(),
+  object: z.record(z.string(), z.unknown()).optional(),
+});
+
+const MemoryKindSchema = z.enum(["episodic", "semantic"]);
+
+// pg returns BIGINT as string, so we coerce to number
+const pgBigint = z.coerce.number().int();
+
+export const MemoryDBRecordSchema = z.object({
+  id: z.string(),
+  namespace: z.string().nullable(),
+  entity_id: z.string().nullable(),
+  agent_id: z.string().nullable(),
+  kind: MemoryKindSchema,
+  collection: z.string(),
+  content: MemoryByteSchema,
+  wmem: z.boolean(),
+  smem_expires_at: pgBigint.nullable(),
+  timestamp: pgBigint,
+  created_at: pgBigint,
+  updated_at: pgBigint,
+  metadata: z.record(z.string(), z.unknown()).nullable(),
+});
+
+export type MemoryDBRecord = z.infer<typeof MemoryDBRecordSchema>;

package/src/serde/__tests__/memory.test.ts

@@ -0,0 +1,277 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+
+import { MemoryRecordCodec, NewMemoryCodec } from "../memory";
+
+describe("NewMemoryCodec", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2024-01-01T00:00:00.000Z"));
+  });
+
+  describe("encode", () => {
+    it("should apply default values", () => {
+      const memory = {
+        id: "mem-1",
+        scope: { namespace: "test" },
+        kind: "episodic" as const,
+        collection: "facts",
+        content: { text: "Hello world" },
+      };
+
+      const record = NewMemoryCodec.encode(memory);
+
+      expect(record.wmem).toBe(false);
+      expect(record.smem_expires_at).toBeNull();
+      expect(record.metadata).toBeNull();
+    });
+
+    it("should preserve provided values", () => {
+      const memory = {
+        id: "mem-2",
+        scope: { namespace: "test", entityId: "user-1", agentId: "agent-1" },
+        kind: "semantic" as const,
+        collection: "preferences",
+        content: { object: { key: "value" } },
+        wmem: true,
+        smem: { expiresAt: 1704153600000 },
+        timestamp: 1704067200000,
+        metadata: { source: "user" },
+      };
+
+      const record = NewMemoryCodec.encode(memory);
+
+      expect(record.namespace).toBe("test");
+      expect(record.entity_id).toBe("user-1");
+      expect(record.agent_id).toBe("agent-1");
+      expect(record.kind).toBe("semantic");
+      expect(record.collection).toBe("preferences");
+      expect(record.content).toEqual({ object: { key: "value" } });
+      expect(record.wmem).toBe(true);
+      expect(record.smem_expires_at).toBe(1704153600000);
+      expect(record.timestamp).toBe(1704067200000);
+      expect(record.metadata).toEqual({ source: "user" });
+    });
+
+    it("should apply current timestamp when not provided", () => {
+      const now = Date.now();
+
+      const memory = {
+        id: "mem-3",
+        scope: { namespace: "test" },
+        kind: "episodic" as const,
+        collection: "facts",
+        content: { text: "Test" },
+      };
+
+      const record = NewMemoryCodec.encode(memory);
+
+      expect(record.timestamp).toBe(now);
+      expect(record.created_at).toBe(now);
+      expect(record.updated_at).toBe(now);
+    });
+
+    it("should handle null scope fields", () => {
+      const memory = {
+        id: "mem-4",
+        scope: {},
+        kind: "episodic" as const,
+        collection: "facts",
+        content: { text: "Test" },
+      };
+
+      const record = NewMemoryCodec.encode(memory);
+
+      expect(record.namespace).toBeNull();
+      expect(record.entity_id).toBeNull();
+      expect(record.agent_id).toBeNull();
+    });
+  });
+
+  describe("decode", () => {
+    it("should decode MemoryDBRecord to NewMemory", () => {
+      const record = {
+        id: "mem-1",
+        namespace: "test",
+        entity_id: "user-1",
+        agent_id: "agent-1",
+        kind: "episodic" as const,
+        collection: "facts",
+        content: { text: "Hello" },
+        wmem: true,
+        smem_expires_at: 1704153600000,
+        timestamp: 1704067200000,
+        created_at: 1704067200000,
+        updated_at: 1704067200000,
+        metadata: { key: "value" },
+      };
+
+      const memory = NewMemoryCodec.decode(record);
+
+      expect(memory.id).toBe("mem-1");
+      expect(memory.scope.namespace).toBe("test");
+      expect(memory.scope.entityId).toBe("user-1");
+      expect(memory.scope.agentId).toBe("agent-1");
+      expect(memory.kind).toBe("episodic");
+      expect(memory.collection).toBe("facts");
+      expect(memory.content).toEqual({ text: "Hello" });
+      expect(memory.wmem).toBe(true);
+      expect(memory.smem?.expiresAt).toBe(1704153600000);
+      expect(memory.timestamp).toBe(1704067200000);
+      expect(memory.metadata).toEqual({ key: "value" });
+    });
+
+    it("should handle null values", () => {
+      const record = {
+        id: "mem-2",
+        namespace: null,
+        entity_id: null,
+        agent_id: null,
+        kind: "semantic" as const,
+        collection: "facts",
+        content: { text: "Test" },
+        wmem: false,
+        smem_expires_at: null,
+        timestamp: 1704067200000,
+        created_at: 1704067200000,
+        updated_at: 1704067200000,
+        metadata: null,
+      };
+
+      const memory = NewMemoryCodec.decode(record);
+
+      expect(memory.scope.namespace).toBeUndefined();
+      expect(memory.scope.entityId).toBeUndefined();
+      expect(memory.scope.agentId).toBeUndefined();
+      expect(memory.smem).toBeUndefined();
+      expect(memory.metadata).toBeNull();
+    });
+  });
+});
+
+describe("MemoryRecordCodec", () => {
+  describe("encode", () => {
+    it("should encode MemoryRecord to MemoryDBRecord", () => {
+      const record = {
+        id: "mem-1",
+        scope: { namespace: "test", entityId: "user-1", agentId: "agent-1" },
+        kind: "episodic" as const,
+        collection: "facts",
+        content: { text: "Hello" },
+        wmem: true,
+        smem: { expiresAt: 1704153600000 },
+        timestamp: 1704067200000,
+        createdAt: 1704067200000,
+        updatedAt: 1704070800000,
+        metadata: { source: "test" },
+      };
+
+      const dbRecord = MemoryRecordCodec.encode(record);
+
+      expect(dbRecord.id).toBe("mem-1");
+      expect(dbRecord.namespace).toBe("test");
+      expect(dbRecord.entity_id).toBe("user-1");
+      expect(dbRecord.agent_id).toBe("agent-1");
+      expect(dbRecord.kind).toBe("episodic");
+      expect(dbRecord.collection).toBe("facts");
+      expect(dbRecord.content).toEqual({ text: "Hello" });
+      expect(dbRecord.wmem).toBe(true);
+      expect(dbRecord.smem_expires_at).toBe(1704153600000);
+      expect(dbRecord.timestamp).toBe(1704067200000);
+      expect(dbRecord.created_at).toBe(1704067200000);
+      expect(dbRecord.updated_at).toBe(1704070800000);
+      expect(dbRecord.metadata).toEqual({ source: "test" });
+    });
+
+    it("should handle undefined scope fields as null", () => {
+      const record = {
+        id: "mem-2",
+        scope: {},
+        kind: "semantic" as const,
+        collection: "facts",
+        content: { text: "Test" },
+        wmem: false,
+        smem: { expiresAt: null },
+        timestamp: 1704067200000,
+        createdAt: 1704067200000,
+        updatedAt: 1704067200000,
+        metadata: null,
+      };
+
+      const dbRecord = MemoryRecordCodec.encode(record);
+
+      expect(dbRecord.namespace).toBeNull();
+      expect(dbRecord.entity_id).toBeNull();
+      expect(dbRecord.agent_id).toBeNull();
+    });
+  });
+
+  describe("decode", () => {
+    it("should decode MemoryDBRecord to MemoryRecord", () => {
+      const dbRecord = {
+        id: "mem-1",
+        namespace: "test",
+        entity_id: "user-1",
+        agent_id: "agent-1",
+        kind: "semantic" as const,
+        collection: "facts",
+        content: { object: { foo: "bar" } },
+        wmem: false,
+        smem_expires_at: null,
+        timestamp: 1704067200000,
+        created_at: 1704067200000,
+        updated_at: 1704070800000,
+        metadata: null,
+      };
+
+      const record = MemoryRecordCodec.decode(dbRecord);
+
+      expect(record.id).toBe("mem-1");
+      expect(record.scope.namespace).toBe("test");
+      expect(record.scope.entityId).toBe("user-1");
+      expect(record.scope.agentId).toBe("agent-1");
+      expect(record.kind).toBe("semantic");
+      expect(record.collection).toBe("facts");
+      expect(record.content).toEqual({ object: { foo: "bar" } });
+      expect(record.wmem).toBe(false);
+      expect(record.smem.expiresAt).toBeNull();
+      expect(record.timestamp).toBe(1704067200000);
+      expect(record.createdAt).toBe(1704067200000);
+      expect(record.updatedAt).toBe(1704070800000);
+      expect(record.metadata).toBeNull();
+    });
+  });
+
+  describe("round-trip encoding/decoding", () => {
+    it("should preserve data through encode -> decode cycle", () => {
+      const original = {
+        id: "mem-rt",
+        scope: { namespace: "test", entityId: "user-1" },
+        kind: "episodic" as const,
+        collection: "conversations",
+        content: { text: "Round trip test" },
+        wmem: true,
+        smem: { expiresAt: 1704153600000 },
+        timestamp: 1704067200000,
+        createdAt: 1704067200000,
+        updatedAt: 1704070800000,
+        metadata: { roundTrip: true },
+      };
+
+      const encoded = MemoryRecordCodec.encode(original);
+      const decoded = MemoryRecordCodec.decode(encoded);
+
+      expect(decoded.id).toBe(original.id);
+      expect(decoded.scope.namespace).toBe(original.scope.namespace);
+      expect(decoded.scope.entityId).toBe(original.scope.entityId);
+      expect(decoded.kind).toBe(original.kind);
+      expect(decoded.collection).toBe(original.collection);
+      expect(decoded.content).toEqual(original.content);
+      expect(decoded.wmem).toBe(original.wmem);
+      expect(decoded.smem.expiresAt).toBe(original.smem.expiresAt);
+      expect(decoded.timestamp).toBe(original.timestamp);
+      expect(decoded.createdAt).toBe(original.createdAt);
+      expect(decoded.updatedAt).toBe(original.updatedAt);
+      expect(decoded.metadata).toEqual(original.metadata);
+    });
+  });
+});

package/src/serde/memory.ts

@@ -0,0 +1,111 @@
+/**
+ * Memory serialization - codecs for converting between domain types and database records.
+ */
+
+import type { MemoryRecord, NewMemory, MemoryByte, MemoryKind } from "kernl";
+import type { JSONObject } from "@kernl-sdk/protocol";
+import { type Codec, neapolitanCodec } from "@kernl-sdk/shared/lib";
+
+import { MemoryDBRecordSchema, type MemoryDBRecord } from "@/memory/schema";
+
+/* ---- Codecs ---- */
+
+/**
+ * MemoryRecord codec - converts between domain MemoryRecord and MemoryDBRecord.
+ */
+const rawMemoryRecordCodec: Codec<MemoryRecord, MemoryDBRecord> = {
+  encode(record: MemoryRecord): MemoryDBRecord {
+    return {
+      id: record.id,
+      namespace: record.scope.namespace ?? null,
+      entity_id: record.scope.entityId ?? null,
+      agent_id: record.scope.agentId ?? null,
+      kind: record.kind,
+      collection: record.collection,
+      content: record.content,
+      wmem: record.wmem,
+      smem_expires_at: record.smem.expiresAt,
+      timestamp: record.timestamp,
+      created_at: record.createdAt,
+      updated_at: record.updatedAt,
+      metadata: record.metadata,
+    };
+  },
+
+  decode(row: MemoryDBRecord): MemoryRecord {
+    const base = {
+      id: row.id,
+      scope: {
+        namespace: row.namespace ?? undefined,
+        entityId: row.entity_id ?? undefined,
+        agentId: row.agent_id ?? undefined,
+      },
+      collection: row.collection,
+      content: row.content as MemoryByte,
+      wmem: row.wmem,
+      smem: {
+        expiresAt: row.smem_expires_at ? Number(row.smem_expires_at) : null,
+      },
+      timestamp: Number(row.timestamp),
+      createdAt: Number(row.created_at),
+      updatedAt: Number(row.updated_at),
+      metadata: row.metadata as JSONObject | null,
+    };
+
+    return { ...base, kind: row.kind as MemoryKind } as MemoryRecord;
+  },
+};
+
+export const MemoryRecordCodec = neapolitanCodec({
+  codec: rawMemoryRecordCodec,
+  schema: MemoryDBRecordSchema,
+});
+
+/**
+ * NewMemory codec - converts NewMemory input to MemoryDBRecord for insertion.
+ */
+const rawNewMemoryCodec: Codec<NewMemory, MemoryDBRecord> = {
+  encode(memory: NewMemory): MemoryDBRecord {
+    const now = Date.now();
+    return {
+      id: memory.id,
+      namespace: memory.scope.namespace ?? null,
+      entity_id: memory.scope.entityId ?? null,
+      agent_id: memory.scope.agentId ?? null,
+      kind: memory.kind,
+      collection: memory.collection,
+      content: memory.content,
+      wmem: memory.wmem ?? false,
+      smem_expires_at: memory.smem?.expiresAt ?? null,
+      timestamp: memory.timestamp ?? now,
+      created_at: now,
+      updated_at: now,
+      metadata: memory.metadata ?? null,
+    };
+  },
+
+  decode(row: MemoryDBRecord): NewMemory {
+    return {
+      id: row.id,
+      scope: {
+        namespace: row.namespace ?? undefined,
+        entityId: row.entity_id ?? undefined,
+        agentId: row.agent_id ?? undefined,
+      },
+      kind: row.kind as MemoryKind,
+      collection: row.collection,
+      content: row.content as MemoryByte,
+      wmem: row.wmem,
+      smem: row.smem_expires_at
+        ? { expiresAt: Number(row.smem_expires_at) }
+        : undefined,
+      timestamp: Number(row.timestamp),
+      metadata: row.metadata as JSONObject | null | undefined,
+    };
+  },
+};
+
+export const NewMemoryCodec = neapolitanCodec({
+  codec: rawNewMemoryCodec,
+  schema: MemoryDBRecordSchema,
+});

package/src/table.ts

@@ -1,7 +1,7 @@
 /**
  * Schema name for all kernl tables.
  */
-export const SCHEMA_NAME = "kernl";
+export const KERNL_SCHEMA_NAME = "kernl";
 
 /**
  * Table definition with name, columns, and optional constraints.
@@ -37,7 +37,7 @@ export function defineTable<
 
 /* ---- Column Types ---- */
 
-export type ColumnType = "text" | "integer" | "bigint" | "jsonb";
+export type ColumnType = "text" | "integer" | "bigint" | "boolean" | "jsonb";
 export type OnDeleteAction = "CASCADE" | "SET NULL" | "RESTRICT";
 
 /**
@@ -78,6 +78,7 @@ export interface Column<T = unknown> {
 export const text = (): Column<string> => col("text");
 export const integer = (): Column<number> => col("integer");
 export const bigint = (): Column<number> => col("bigint");
+export const boolean = (): Column<boolean> => col("boolean");
 export const jsonb = <T = unknown>(): Column<T> => col("jsonb");
 
 export const timestamps = {
@@ -130,6 +131,8 @@ function col<T>(type: ColumnType): Column<T> {
         case "integer":
         case "bigint":
           return String(val);
+        case "boolean":
+          return val ? "TRUE" : "FALSE";
         case "jsonb":
           return `'${JSON.stringify(val)}'`;
       }
@@ -142,6 +145,8 @@ function col<T>(type: ColumnType): Column<T> {
         case "integer":
         case "bigint":
           return Number.parseInt(val, 10) as T;
+        case "boolean":
+          return (val === "t" || val === "true" || val === "TRUE") as T;
         case "jsonb":
           return JSON.parse(val) as T;
       }

package/tsconfig.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["./src/base.ts","./src/index.ts","./src/table.ts","./src/types.ts","./src/__tests__/table.test.ts","./src/memory/index.ts","./src/memory/schema.ts","./src/serde/memory.ts","./src/serde/thread.ts","./src/serde/__tests__/memory.test.ts","./src/serde/__tests__/thread.test.ts","./src/thread/index.ts","./src/thread/schema.ts","./src/thread/store.ts","./src/thread/types.ts"],"version":"5.9.2"}