@kernl-sdk/libsql 0.1.36 → 0.1.39

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

@@ -0,0 +1,186 @@
+import { describe, it, expect } from "vitest";
+
+import { SQL_WHERE, ORDER, SQL_UPDATE } from "../sql";
+
+describe("LibSQL memory SQL codecs", () => {
+  describe("SQL_WHERE", () => {
+    it("returns empty clause when no filters", () => {
+      const result = SQL_WHERE.encode({ filter: undefined });
+      expect(result.sql).toBe("");
+      expect(result.params).toEqual([]);
+    });
+
+    it("encodes scope namespace filter", () => {
+      const result = SQL_WHERE.encode({
+        filter: { scope: { namespace: "default" } },
+      });
+      expect(result.sql).toBe("namespace = ?");
+      expect(result.params).toEqual(["default"]);
+    });
+
+    it("encodes scope entityId filter", () => {
+      const result = SQL_WHERE.encode({
+        filter: { scope: { entityId: "user-1" } },
+      });
+      expect(result.sql).toBe("entity_id = ?");
+      expect(result.params).toEqual(["user-1"]);
+    });
+
+    it("encodes scope agentId filter", () => {
+      const result = SQL_WHERE.encode({
+        filter: { scope: { agentId: "agent-1" } },
+      });
+      expect(result.sql).toBe("agent_id = ?");
+      expect(result.params).toEqual(["agent-1"]);
+    });
+
+    it("encodes full scope filter", () => {
+      const result = SQL_WHERE.encode({
+        filter: {
+          scope: {
+            namespace: "default",
+            entityId: "user-1",
+            agentId: "agent-1",
+          },
+        },
+      });
+      expect(result.sql).toBe("namespace = ? AND entity_id = ? AND agent_id = ?");
+      expect(result.params).toEqual(["default", "user-1", "agent-1"]);
+    });
+
+    it("encodes collections filter with IN clause", () => {
+      const result = SQL_WHERE.encode({
+        filter: { collections: ["facts", "preferences"] },
+      });
+      expect(result.sql).toBe("collection IN (?, ?)");
+      expect(result.params).toEqual(["facts", "preferences"]);
+    });
+
+    it("encodes wmem filter", () => {
+      const result = SQL_WHERE.encode({ filter: { wmem: true } });
+      expect(result.sql).toBe("wmem = ?");
+      expect(result.params).toEqual([1]); // SQLite boolean
+    });
+
+    it("encodes smem filter (has valid expiration)", () => {
+      const before = Date.now();
+      const result = SQL_WHERE.encode({ filter: { smem: true } });
+      const after = Date.now();
+
+      // smem=true means has expiration AND not expired
+      expect(result.sql).toBe("(smem_expires_at IS NOT NULL AND smem_expires_at > ?)");
+      expect(result.params.length).toBe(1);
+      expect(result.params[0]).toBeGreaterThanOrEqual(before);
+      expect(result.params[0]).toBeLessThanOrEqual(after);
+    });
+
+    it("encodes smem=false filter (no expiration or expired)", () => {
+      const before = Date.now();
+      const result = SQL_WHERE.encode({ filter: { smem: false } });
+      const after = Date.now();
+
+      // smem=false means no expiration OR already expired
+      expect(result.sql).toBe("(smem_expires_at IS NULL OR smem_expires_at <= ?)");
+      expect(result.params.length).toBe(1);
+      expect(result.params[0]).toBeGreaterThanOrEqual(before);
+      expect(result.params[0]).toBeLessThanOrEqual(after);
+    });
+
+    it("encodes timestamp range filters", () => {
+      const result = SQL_WHERE.encode({
+        filter: { after: 1700000000000, before: 1700100000000 },
+      });
+      expect(result.sql).toBe("timestamp > ? AND timestamp < ?");
+      expect(result.params).toEqual([1700000000000, 1700100000000]);
+    });
+
+    it("combines multiple filters with AND", () => {
+      const result = SQL_WHERE.encode({
+        filter: {
+          scope: { namespace: "default" },
+          wmem: true,
+          collections: ["facts"],
+        },
+      });
+
+      expect(result.sql).toContain("namespace = ?");
+      expect(result.sql).toContain("wmem = ?");
+      expect(result.sql).toContain("collection IN (?)");
+      expect(result.sql.match(/AND/g)?.length).toBe(2);
+    });
+  });
+
+  describe("ORDER", () => {
+    it("returns default ordering (desc)", () => {
+      const result = ORDER.encode({ order: undefined });
+      expect(result).toBe("timestamp DESC");
+    });
+
+    it("encodes asc order", () => {
+      const result = ORDER.encode({ order: "asc" });
+      expect(result).toBe("timestamp ASC");
+    });
+
+    it("encodes desc order", () => {
+      const result = ORDER.encode({ order: "desc" });
+      expect(result).toBe("timestamp DESC");
+    });
+  });
+
+  describe("SQL_UPDATE", () => {
+    it("encodes content update with JSON stringify", () => {
+      const content = { text: "Updated content" };
+      const result = SQL_UPDATE.encode({ patch: { id: "m1", content } });
+      expect(result.sql).toContain("content = ?");
+      expect(result.params).toContain(JSON.stringify(content));
+    });
+
+    it("encodes wmem flag update", () => {
+      const result = SQL_UPDATE.encode({ patch: { id: "m1", wmem: true } });
+      expect(result.sql).toContain("wmem = ?");
+      expect(result.params).toContain(1); // SQLite boolean
+    });
+
+    it("encodes smem expiration update", () => {
+      const result = SQL_UPDATE.encode({
+        patch: { id: "m1", smem: { expiresAt: 1700100000000 } },
+      });
+      expect(result.sql).toContain("smem_expires_at = ?");
+      expect(result.params).toContain(1700100000000);
+    });
+
+    it("encodes metadata update", () => {
+      const metadata = { confidence: 0.95 };
+      const result = SQL_UPDATE.encode({ patch: { id: "m1", metadata } });
+      expect(result.sql).toContain("metadata = ?");
+      expect(result.params).toContain(JSON.stringify(metadata));
+    });
+
+    it("always includes updated_at", () => {
+      const before = Date.now();
+      const result = SQL_UPDATE.encode({ patch: { id: "m1", wmem: false } });
+      const after = Date.now();
+
+      expect(result.sql).toContain("updated_at = ?");
+      const updatedAt = result.params.find(
+        (p) => typeof p === "number" && p >= before && p <= after,
+      );
+      expect(updatedAt).toBeDefined();
+    });
+
+    it("combines multiple updates", () => {
+      const result = SQL_UPDATE.encode({
+        patch: {
+          id: "m1",
+          content: { text: "New" },
+          wmem: true,
+          metadata: { edited: true },
+        },
+      });
+      expect(result.sql).toContain("content = ?");
+      expect(result.sql).toContain("wmem = ?");
+      expect(result.sql).toContain("metadata = ?");
+      expect(result.sql).toContain("updated_at = ?");
+    });
+  });
+});

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

@@ -0,0 +1,148 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import type { Client } from "@libsql/client";
+
+import { create_client, create_storage, testid } from "../../__tests__/helpers";
+import { LibSQLStorage } from "../../storage";
+
+describe("LibSQLMemoryStore update", () => {
+  let client: Client;
+  let storage: LibSQLStorage;
+  let memId: string;
+
+  beforeEach(async () => {
+    client = create_client();
+    storage = create_storage(client);
+    await storage.memories.list(); // init
+
+    memId = testid("mem");
+    await storage.memories.create({
+      id: memId,
+      scope: { namespace: "default", entityId: "user-1" },
+      kind: "semantic",
+      collection: "facts",
+      content: { text: "Original content" },
+      wmem: false,
+      metadata: { version: 1 },
+    });
+  });
+
+  afterEach(() => {
+    client.close();
+  });
+
+  it("updates content and bumps updated_at", async () => {
+    const before = await storage.memories.get(memId);
+    const originalUpdatedAt = before!.updatedAt;
+
+    // Small delay to ensure timestamp difference
+    await new Promise((r) => setTimeout(r, 10));
+
+    const updated = await storage.memories.update(memId, {
+      id: memId,
+      content: { text: "Updated content" },
+    });
+
+    expect(updated.content).toEqual({ text: "Updated content" });
+    expect(updated.updatedAt).toBeGreaterThan(originalUpdatedAt);
+
+    // Verify persisted
+    const found = await storage.memories.get(memId);
+    expect(found?.content).toEqual({ text: "Updated content" });
+  });
+
+  it("updates wmem flag", async () => {
+    const updated = await storage.memories.update(memId, {
+      id: memId,
+      wmem: true,
+    });
+
+    expect(updated.wmem).toBe(true);
+
+    const found = await storage.memories.get(memId);
+    expect(found?.wmem).toBe(true);
+  });
+
+  it("updates smem expiration", async () => {
+    const expiresAt = Date.now() + 7200000;
+
+    const updated = await storage.memories.update(memId, {
+      id: memId,
+      smem: { expiresAt },
+    });
+
+    expect(updated.smem.expiresAt).toBe(expiresAt);
+
+    const found = await storage.memories.get(memId);
+    expect(found?.smem.expiresAt).toBe(expiresAt);
+  });
+
+  it("clears smem expiration", async () => {
+    // First set an expiration
+    await storage.memories.update(memId, {
+      id: memId,
+      smem: { expiresAt: Date.now() + 3600000 },
+    });
+
+    // Then clear it
+    const updated = await storage.memories.update(memId, {
+      id: memId,
+      smem: { expiresAt: null },
+    });
+
+    expect(updated.smem.expiresAt).toBeNull();
+  });
+
+  it("updates metadata", async () => {
+    const newMetadata = { version: 2, source: "api", edited: true };
+
+    const updated = await storage.memories.update(memId, {
+      id: memId,
+      metadata: newMetadata,
+    });
+
+    expect(updated.metadata).toEqual(newMetadata);
+
+    const found = await storage.memories.get(memId);
+    expect(found?.metadata).toEqual(newMetadata);
+  });
+
+  it("updates multiple fields at once", async () => {
+    const updated = await storage.memories.update(memId, {
+      id: memId,
+      content: { text: "New content" },
+      wmem: true,
+      metadata: { version: 3 },
+    });
+
+    expect(updated.content).toEqual({ text: "New content" });
+    expect(updated.wmem).toBe(true);
+    expect(updated.metadata).toEqual({ version: 3 });
+  });
+
+  it("throws when memory does not exist", async () => {
+    await expect(
+      storage.memories.update("nonexistent", {
+        id: "nonexistent",
+        content: { text: "test" },
+      }),
+    ).rejects.toThrow(/not found/i);
+  });
+
+  it("preserves unchanged fields", async () => {
+    const before = await storage.memories.get(memId);
+
+    await storage.memories.update(memId, {
+      id: memId,
+      wmem: true,
+    });
+
+    const after = await storage.memories.get(memId);
+
+    // Content should be unchanged
+    expect(after?.content).toEqual(before?.content);
+    expect(after?.kind).toBe(before?.kind);
+    expect(after?.collection).toBe(before?.collection);
+    // wmem should be updated
+    expect(after?.wmem).toBe(true);
+  });
+});

package/src/memory/row.ts

@@ -0,0 +1,36 @@
+/**
+ * LibSQL row codecs for memory data.
+ */
+
+import type { Row } from "@libsql/client";
+import type { Codec } from "@kernl-sdk/shared/lib";
+import type { MemoryDBRecord } from "@kernl-sdk/storage";
+
+import { parsejson } from "../utils";
+
+/**
+ * Codec for converting LibSQL rows to MemoryDBRecord.
+ */
+export const RowToMemoryRecord: Codec<Row, MemoryDBRecord> = {
+  encode(row: Row): MemoryDBRecord {
+    return {
+      id: row.id as string,
+      namespace: row.namespace as string | null,
+      entity_id: row.entity_id as string | null,
+      agent_id: row.agent_id as string | null,
+      kind: row.kind as "episodic" | "semantic",
+      collection: row.collection as string | null,
+      content: parsejson<Record<string, unknown>>(row.content) ?? {},
+      wmem: Boolean(row.wmem), // Convert SQLite 0/1 to boolean
+      smem_expires_at: row.smem_expires_at as number | null,
+      timestamp: row.timestamp as number,
+      created_at: row.created_at as number,
+      updated_at: row.updated_at as number,
+      metadata: parsejson<Record<string, unknown>>(row.metadata),
+    };
+  },
+
+  decode(): Row {
+    throw new Error("RowToMemoryRecord.decode not implemented");
+  },
+};

package/src/memory/sql.ts

@@ -0,0 +1,142 @@
+/**
+ * Memory SQL conversion codecs for LibSQL.
+ *
+ * Uses ? placeholders instead of PostgreSQL's $1, $2, etc.
+ */
+
+import type { Codec } from "@kernl-sdk/shared/lib";
+import type { MemoryFilter, MemoryRecordUpdate } from "kernl";
+
+import { type SQLClause, expandarray } from "../sql";
+
+export interface WhereInput {
+  filter?: MemoryFilter;
+}
+
+/**
+ * Encode MemoryFilter to SQL WHERE clause with ? placeholders.
+ */
+export const SQL_WHERE: Codec<WhereInput, SQLClause> = {
+  encode({ filter }) {
+    if (!filter) {
+      return { sql: "", params: [] };
+    }
+
+    const conditions: string[] = [];
+    const params: unknown[] = [];
+
+    if (filter.scope?.namespace !== undefined) {
+      conditions.push(`namespace = ?`);
+      params.push(filter.scope.namespace);
+    }
+    if (filter.scope?.entityId !== undefined) {
+      conditions.push(`entity_id = ?`);
+      params.push(filter.scope.entityId);
+    }
+    if (filter.scope?.agentId !== undefined) {
+      conditions.push(`agent_id = ?`);
+      params.push(filter.scope.agentId);
+    }
+    if (filter.collections && filter.collections.length > 0) {
+      const { placeholders, params: collectionParams } = expandarray(
+        filter.collections,
+      );
+      conditions.push(`collection IN (${placeholders})`);
+      params.push(...collectionParams);
+    }
+    if (filter.wmem !== undefined) {
+      conditions.push(`wmem = ?`);
+      params.push(filter.wmem ? 1 : 0); // SQLite uses 0/1 for boolean
+    }
+    if (filter.smem === true) {
+      conditions.push(`(smem_expires_at IS NOT NULL AND smem_expires_at > ?)`);
+      params.push(Date.now());
+    } else if (filter.smem === false) {
+      conditions.push(`(smem_expires_at IS NULL OR smem_expires_at <= ?)`);
+      params.push(Date.now());
+    }
+    if (filter.after !== undefined) {
+      conditions.push(`timestamp > ?`);
+      params.push(filter.after);
+    }
+    if (filter.before !== undefined) {
+      conditions.push(`timestamp < ?`);
+      params.push(filter.before);
+    }
+
+    return {
+      sql: conditions.length > 0 ? conditions.join(" AND ") : "",
+      params,
+    };
+  },
+
+  decode() {
+    throw new Error("SQL_WHERE.decode not implemented");
+  },
+};
+
+type OrderDirection = "asc" | "desc";
+
+export interface OrderInput {
+  order?: OrderDirection;
+  defaultColumn?: string;
+  defaultDirection?: OrderDirection;
+}
+
+/**
+ * Encode order options to SQL ORDER BY clause.
+ */
+export const ORDER: Codec<OrderInput, string> = {
+  encode({ order, defaultColumn = "timestamp", defaultDirection = "desc" }) {
+    const dir = (order ?? defaultDirection).toUpperCase();
+    return `${defaultColumn} ${dir}`;
+  },
+
+  decode() {
+    throw new Error("ORDER.decode not implemented");
+  },
+};
+
+export interface PatchInput {
+  patch: MemoryRecordUpdate;
+}
+
+/**
+ * Encode MemoryRecordUpdate to SQL SET clause with ? placeholders.
+ */
+export const SQL_UPDATE: Codec<PatchInput, SQLClause> = {
+  encode({ patch }) {
+    const sets: string[] = [];
+    const params: unknown[] = [];
+
+    if (patch.content !== undefined) {
+      sets.push(`content = ?`);
+      params.push(JSON.stringify(patch.content));
+    }
+    if (patch.wmem !== undefined) {
+      sets.push(`wmem = ?`);
+      params.push(patch.wmem ? 1 : 0); // SQLite uses 0/1 for boolean
+    }
+    if (patch.smem !== undefined) {
+      sets.push(`smem_expires_at = ?`);
+      params.push(patch.smem.expiresAt);
+    }
+    if (patch.metadata !== undefined) {
+      sets.push(`metadata = ?`);
+      params.push(patch.metadata ? JSON.stringify(patch.metadata) : null);
+    }
+
+    // always update updated_at
+    sets.push(`updated_at = ?`);
+    params.push(Date.now());
+
+    return {
+      sql: sets.join(", "),
+      params,
+    };
+  },
+
+  decode() {
+    throw new Error("SQL_UPDATE.decode not implemented");
+  },
+};

package/src/memory/store.ts

@@ -0,0 +1,173 @@
+/**
+ * LibSQL Memory store implementation.
+ */
+
+import type { Client, InValue } from "@libsql/client";
+
+import type {
+  MemoryStore,
+  MemoryRecord,
+  NewMemory,
+  MemoryRecordUpdate,
+  MemoryListOptions,
+} from "kernl";
+import {
+  KERNL_SCHEMA_NAME,
+  MemoryRecordCodec,
+  NewMemoryCodec,
+} from "@kernl-sdk/storage";
+
+import { SQL_WHERE, ORDER, SQL_UPDATE } from "./sql";
+import { RowToMemoryRecord } from "./row";
+import { expandarray } from "../sql";
+
+// SQLite doesn't support schemas, so we use table name prefix
+const MEMORIES_TABLE = `${KERNL_SCHEMA_NAME}_memories`;
+
+/**
+ * LibSQL memory store implementation.
+ *
+ * All async methods call `ensureInit()` before database operations
+ * to ensure schema/tables exist.
+ */
+export class LibSQLMemoryStore implements MemoryStore {
+  private db: Client;
+  private ensureInit: () => Promise<void>;
+
+  constructor(db: Client, ensureInit: () => Promise<void>) {
+    this.db = db;
+    this.ensureInit = ensureInit;
+  }
+
+  /**
+   * Get a memory by ID.
+   */
+  async get(id: string): Promise<MemoryRecord | null> {
+    await this.ensureInit();
+
+    const result = await this.db.execute({
+      sql: `SELECT * FROM ${MEMORIES_TABLE} WHERE id = ?`,
+      args: [id],
+    });
+
+    if (result.rows.length === 0) {
+      return null;
+    }
+
+    return MemoryRecordCodec.decode(RowToMemoryRecord.encode(result.rows[0]));
+  }
+
+  /**
+   * List memories matching optional filter criteria.
+   */
+  async list(options?: MemoryListOptions): Promise<MemoryRecord[]> {
+    await this.ensureInit();
+
+    const { sql: where, params } = SQL_WHERE.encode({
+      filter: options?.filter,
+    });
+
+    let query = `SELECT * FROM ${MEMORIES_TABLE}`;
+
+    // build where + order by
+    if (where) query += ` WHERE ${where}`;
+    query += ` ORDER BY ${ORDER.encode({ order: options?.order })}`;
+
+    const args = [...params] as InValue[];
+
+    // add limit + offset
+    // SQLite requires LIMIT when using OFFSET, so use -1 for unlimited
+    if (options?.limit || options?.offset) {
+      query += ` LIMIT ?`;
+      args.push(options?.limit ?? -1);
+    }
+    if (options?.offset) {
+      query += ` OFFSET ?`;
+      args.push(options.offset);
+    }
+
+    const result = await this.db.execute({ sql: query, args });
+    return result.rows.map((row) =>
+      MemoryRecordCodec.decode(RowToMemoryRecord.encode(row)),
+    );
+  }
+
+  /**
+   * Create a new memory record.
+   */
+  async create(memory: NewMemory): Promise<MemoryRecord> {
+    await this.ensureInit();
+
+    const row = NewMemoryCodec.encode(memory);
+
+    const result = await this.db.execute({
+      sql: `INSERT INTO ${MEMORIES_TABLE}
+       (id, namespace, entity_id, agent_id, kind, collection, content, wmem, smem_expires_at, timestamp, created_at, updated_at, metadata)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+       RETURNING *`,
+      args: [
+        row.id,
+        row.namespace,
+        row.entity_id,
+        row.agent_id,
+        row.kind,
+        row.collection,
+        JSON.stringify(row.content),
+        row.wmem ? 1 : 0, // SQLite uses 0/1 for boolean
+        row.smem_expires_at,
+        row.timestamp,
+        row.created_at,
+        row.updated_at,
+        row.metadata ? JSON.stringify(row.metadata) : null,
+      ],
+    });
+
+    return MemoryRecordCodec.decode(RowToMemoryRecord.encode(result.rows[0]));
+  }
+
+  /**
+   * Update a memory record.
+   */
+  async update(id: string, patch: MemoryRecordUpdate): Promise<MemoryRecord> {
+    await this.ensureInit();
+
+    const { sql: updates, params } = SQL_UPDATE.encode({ patch });
+    const args = [...params, id] as InValue[];
+
+    const result = await this.db.execute({
+      sql: `UPDATE ${MEMORIES_TABLE} SET ${updates} WHERE id = ? RETURNING *`,
+      args,
+    });
+
+    if (result.rows.length === 0) {
+      throw new Error(`memory not found: ${id}`);
+    }
+
+    return MemoryRecordCodec.decode(RowToMemoryRecord.encode(result.rows[0]));
+  }
+
+  /**
+   * Delete a memory by ID.
+   */
+  async delete(id: string): Promise<void> {
+    await this.ensureInit();
+    await this.db.execute({
+      sql: `DELETE FROM ${MEMORIES_TABLE} WHERE id = ?`,
+      args: [id],
+    });
+  }
+
+  /**
+   * Delete multiple memories by ID.
+   */
+  async mdelete(ids: string[]): Promise<void> {
+    if (ids.length === 0) return;
+    await this.ensureInit();
+
+    const { placeholders, params } = expandarray(ids);
+    await this.db.execute({
+      sql: `DELETE FROM ${MEMORIES_TABLE} WHERE id IN (${placeholders})`,
+      args: params as InValue[],
+    });
+  }
+}