@kernl-sdk/libsql 0.1.38 → 0.1.39

package/src/client.ts

@@ -0,0 +1,71 @@
+/**
+ * LibSQL client configuration and factory.
+ */
+
+import type { KernlStorage } from "kernl";
+import { createClient, type Client, type Config } from "@libsql/client";
+
+import { LibSQLStorage } from "./storage";
+
+/**
+ * LibSQL connection configuration.
+ *
+ * Supports:
+ * - Local SQLite files: `file:./data.db` or `file:/path/to/data.db`
+ * - In-memory: `:memory:`
+ * - Remote Turso: `libsql://your-db.turso.io`
+ */
+export type LibSQLConnectionConfig =
+  | { client: Client }
+  | { url: string; authToken?: string };
+
+/**
+ * LibSQL storage configuration.
+ */
+export type LibSQLConfig = LibSQLConnectionConfig;
+
+/**
+ * Create a LibSQL storage adapter for Kernl.
+ *
+ * @example Local file
+ * ```ts
+ * const storage = libsql({ url: 'file:./kernl.db' });
+ * ```
+ *
+ * @example In-memory (for testing)
+ * ```ts
+ * const storage = libsql({ url: ':memory:' });
+ * ```
+ *
+ * @example Remote Turso
+ * ```ts
+ * const storage = libsql({
+ *   url: 'libsql://your-db.turso.io',
+ *   authToken: process.env.TURSO_AUTH_TOKEN
+ * });
+ * ```
+ */
+export function libsql(config: LibSQLConfig): KernlStorage {
+  const client = createLibSQLClient(config);
+  const url = "url" in config ? config.url : undefined;
+  return new LibSQLStorage({ client, url });
+}
+
+/**
+ * Create a LibSQL client from configuration.
+ */
+function createLibSQLClient(config: LibSQLConnectionConfig): Client {
+  if ("client" in config) {
+    return config.client;
+  }
+
+  const clientConfig: Config = {
+    url: config.url,
+  };
+
+  if (config.authToken) {
+    clientConfig.authToken = config.authToken;
+  }
+
+  return createClient(clientConfig);
+}

package/src/index.ts

@@ -1,3 +1,13 @@
 /**
  * @kernl/libsql - LibSQL storage adapter for Kernl
  */
+
+export { LibSQLStorage, type LibSQLStorageConfig } from "./storage";
+export { LibSQLThreadStore } from "./thread/store";
+export { LibSQLMemoryStore } from "./memory/store";
+export {
+  libsql,
+  type LibSQLConfig,
+  type LibSQLConnectionConfig,
+} from "./client";
+export { MIGRATIONS, REQUIRED_SCHEMA_VERSION } from "./migrations";

package/src/memory/__tests__/create-get.test.ts

@@ -0,0 +1,161 @@
+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 create/get", () => {
+  let client: Client;
+  let storage: LibSQLStorage;
+
+  beforeEach(async () => {
+    client = create_client();
+    storage = create_storage(client);
+    await storage.memories.list(); // init
+  });
+
+  afterEach(() => {
+    client.close();
+  });
+
+  it("creates and reads text memory", async () => {
+    const id = testid("mem");
+
+    const created = await storage.memories.create({
+      id,
+      scope: { namespace: "default", entityId: "user-1", agentId: "agent-1" },
+      kind: "semantic",
+      collection: "facts",
+      content: { text: "User prefers dark mode" },
+    });
+
+    expect(created.id).toBe(id);
+    expect(created.content).toEqual({ text: "User prefers dark mode" });
+    expect(created.kind).toBe("semantic");
+
+    const found = await storage.memories.get(id);
+    expect(found).not.toBeNull();
+    expect(found?.content).toEqual({ text: "User prefers dark mode" });
+    expect(found?.scope.namespace).toBe("default");
+    expect(found?.scope.entityId).toBe("user-1");
+  });
+
+  it("creates and reads object memory", async () => {
+    const id = testid("mem");
+    const objectContent = {
+      object: {
+        preferences: {
+          theme: "dark",
+          language: "en",
+          notifications: true,
+        },
+      },
+    };
+
+    const created = await storage.memories.create({
+      id,
+      scope: { namespace: "default" },
+      kind: "semantic",
+      content: objectContent,
+    });
+
+    expect(created.content).toEqual(objectContent);
+
+    const found = await storage.memories.get(id);
+    expect(found?.content).toEqual(objectContent);
+  });
+
+  it("creates working memory (wmem=true)", async () => {
+    const id = testid("mem");
+
+    const created = await storage.memories.create({
+      id,
+      scope: { namespace: "default" },
+      kind: "episodic",
+      content: { text: "Current task context" },
+      wmem: true,
+    });
+
+    expect(created.wmem).toBe(true);
+
+    const found = await storage.memories.get(id);
+    expect(found?.wmem).toBe(true);
+  });
+
+  it("creates short-term memory with expiration", async () => {
+    const id = testid("mem");
+    const expiresAt = Date.now() + 3600000; // 1 hour from now
+
+    const created = await storage.memories.create({
+      id,
+      scope: { namespace: "default" },
+      kind: "episodic",
+      content: { text: "Temporary note" },
+      smem: { expiresAt },
+    });
+
+    expect(created.smem.expiresAt).toBe(expiresAt);
+
+    const found = await storage.memories.get(id);
+    expect(found?.smem.expiresAt).toBe(expiresAt);
+  });
+
+  it("gets by id and returns null when missing", async () => {
+    const found = await storage.memories.get("nonexistent");
+    expect(found).toBeNull();
+  });
+
+  it("handles null scope fields", async () => {
+    const id = testid("mem");
+
+    const created = await storage.memories.create({
+      id,
+      scope: {}, // All scope fields null
+      kind: "semantic",
+      content: { text: "Global memory" },
+    });
+
+    expect(created.scope.namespace).toBeUndefined();
+    expect(created.scope.entityId).toBeUndefined();
+    expect(created.scope.agentId).toBeUndefined();
+
+    const found = await storage.memories.get(id);
+    expect(found?.scope.namespace).toBeUndefined();
+  });
+
+  it("stores and retrieves metadata", async () => {
+    const id = testid("mem");
+    const metadata = { confidence: 0.95, source: "user_input", version: 2 };
+
+    const created = await storage.memories.create({
+      id,
+      scope: { namespace: "default" },
+      kind: "semantic",
+      content: { text: "Test" },
+      metadata,
+    });
+
+    expect(created.metadata).toEqual(metadata);
+
+    const found = await storage.memories.get(id);
+    expect(found?.metadata).toEqual(metadata);
+  });
+
+  it("sets timestamps on create", async () => {
+    const before = Date.now();
+
+    const created = await storage.memories.create({
+      id: testid("mem"),
+      scope: { namespace: "default" },
+      kind: "semantic",
+      content: { text: "Test" },
+    });
+
+    const after = Date.now();
+
+    expect(created.timestamp).toBeGreaterThanOrEqual(before);
+    expect(created.timestamp).toBeLessThanOrEqual(after);
+    expect(created.createdAt).toBeGreaterThanOrEqual(before);
+    expect(created.updatedAt).toBeGreaterThanOrEqual(before);
+  });
+});

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

@@ -0,0 +1,124 @@
+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 delete", () => {
+  let client: Client;
+  let storage: LibSQLStorage;
+
+  beforeEach(async () => {
+    client = create_client();
+    storage = create_storage(client);
+    await storage.memories.list(); // init
+  });
+
+  afterEach(() => {
+    client.close();
+  });
+
+  it("deletes by id", async () => {
+    const id = testid("mem");
+
+    await storage.memories.create({
+      id,
+      scope: { namespace: "default" },
+      kind: "semantic",
+      content: { text: "To be deleted" },
+    });
+
+    // Verify exists
+    const before = await storage.memories.get(id);
+    expect(before).not.toBeNull();
+
+    // Delete
+    await storage.memories.delete(id);
+
+    // Verify gone
+    const after = await storage.memories.get(id);
+    expect(after).toBeNull();
+  });
+
+  it("delete is idempotent (no error for missing)", async () => {
+    // Should not throw
+    await storage.memories.delete("nonexistent");
+  });
+
+  it("mdelete removes multiple ids", async () => {
+    const ids = [testid("m1"), testid("m2"), testid("m3")];
+
+    // Create memories
+    for (const id of ids) {
+      await storage.memories.create({
+        id,
+        scope: { namespace: "default" },
+        kind: "semantic",
+        content: { text: `Memory ${id}` },
+      });
+    }
+
+    // Verify all exist
+    for (const id of ids) {
+      expect(await storage.memories.get(id)).not.toBeNull();
+    }
+
+    // Delete all
+    await storage.memories.mdelete(ids);
+
+    // Verify all gone
+    for (const id of ids) {
+      expect(await storage.memories.get(id)).toBeNull();
+    }
+  });
+
+  it("mdelete handles partial matches", async () => {
+    const existing = testid("existing");
+
+    await storage.memories.create({
+      id: existing,
+      scope: { namespace: "default" },
+      kind: "semantic",
+      content: { text: "Exists" },
+    });
+
+    // Delete mix of existing and non-existing
+    await storage.memories.mdelete([existing, "nonexistent-1", "nonexistent-2"]);
+
+    // Existing should be deleted
+    expect(await storage.memories.get(existing)).toBeNull();
+  });
+
+  it("mdelete handles empty array", async () => {
+    // Create a memory to ensure it's not affected
+    const id = testid("mem");
+    await storage.memories.create({
+      id,
+      scope: { namespace: "default" },
+      kind: "semantic",
+      content: { text: "Should remain" },
+    });
+
+    // Should not throw and not affect anything
+    await storage.memories.mdelete([]);
+
+    // Memory should still exist
+    const found = await storage.memories.get(id);
+    expect(found).not.toBeNull();
+  });
+
+  it("mdelete with single id", async () => {
+    const id = testid("mem");
+
+    await storage.memories.create({
+      id,
+      scope: { namespace: "default" },
+      kind: "semantic",
+      content: { text: "Single" },
+    });
+
+    await storage.memories.mdelete([id]);
+
+    expect(await storage.memories.get(id)).toBeNull();
+  });
+});

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

@@ -0,0 +1,198 @@
+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 list", () => {
+  let client: Client;
+  let storage: LibSQLStorage;
+
+  beforeEach(async () => {
+    client = create_client();
+    storage = create_storage(client);
+    await storage.memories.list(); // init
+
+    // Seed test data
+    const now = Date.now();
+    await storage.memories.create({
+      id: "m1",
+      scope: { namespace: "ns1", entityId: "user-1", agentId: "agent-1" },
+      kind: "semantic",
+      collection: "facts",
+      content: { text: "Fact 1" },
+      wmem: true,
+      timestamp: now,
+    });
+    await storage.memories.create({
+      id: "m2",
+      scope: { namespace: "ns1", entityId: "user-1", agentId: "agent-1" },
+      kind: "semantic",
+      collection: "preferences",
+      content: { text: "Preference 1" },
+      wmem: false,
+      smem: { expiresAt: now + 3600000 },
+      timestamp: now + 100,
+    });
+    await storage.memories.create({
+      id: "m3",
+      scope: { namespace: "ns1", entityId: "user-2", agentId: "agent-1" },
+      kind: "episodic",
+      collection: "facts",
+      content: { text: "Fact 2" },
+      wmem: true,
+      timestamp: now + 200,
+    });
+    await storage.memories.create({
+      id: "m4",
+      scope: { namespace: "ns2", entityId: "user-1", agentId: "agent-2" },
+      kind: "semantic",
+      collection: "facts",
+      content: { text: "Fact 3" },
+      timestamp: now + 300,
+    });
+  });
+
+  afterEach(() => {
+    client.close();
+  });
+
+  it("lists all memories without filter", async () => {
+    const memories = await storage.memories.list();
+    expect(memories.length).toBe(4);
+  });
+
+  it("filters by namespace", async () => {
+    const memories = await storage.memories.list({
+      filter: { scope: { namespace: "ns1" } },
+    });
+    expect(memories.length).toBe(3);
+    expect(memories.every((m) => m.scope.namespace === "ns1")).toBe(true);
+  });
+
+  it("filters by entityId", async () => {
+    const memories = await storage.memories.list({
+      filter: { scope: { entityId: "user-1" } },
+    });
+    expect(memories.length).toBe(3);
+    expect(memories.every((m) => m.scope.entityId === "user-1")).toBe(true);
+  });
+
+  it("filters by agentId", async () => {
+    const memories = await storage.memories.list({
+      filter: { scope: { agentId: "agent-1" } },
+    });
+    expect(memories.length).toBe(3);
+  });
+
+  it("filters by multiple scope fields", async () => {
+    const memories = await storage.memories.list({
+      filter: {
+        scope: { namespace: "ns1", entityId: "user-1" },
+      },
+    });
+    expect(memories.length).toBe(2);
+  });
+
+  it("filters by collection", async () => {
+    const memories = await storage.memories.list({
+      filter: { collections: ["facts"] },
+    });
+    expect(memories.length).toBe(3);
+    expect(memories.every((m) => m.collection === "facts")).toBe(true);
+  });
+
+  it("filters by multiple collections", async () => {
+    const memories = await storage.memories.list({
+      filter: { collections: ["facts", "preferences"] },
+    });
+    expect(memories.length).toBe(4);
+  });
+
+  it("filters by wmem", async () => {
+    const wmemTrue = await storage.memories.list({
+      filter: { wmem: true },
+    });
+    expect(wmemTrue.length).toBe(2);
+    expect(wmemTrue.every((m) => m.wmem === true)).toBe(true);
+
+    const wmemFalse = await storage.memories.list({
+      filter: { wmem: false },
+    });
+    expect(wmemFalse.length).toBe(2);
+  });
+
+  it("filters by smem (has expiration)", async () => {
+    const hasSmem = await storage.memories.list({
+      filter: { smem: true },
+    });
+    expect(hasSmem.length).toBe(1);
+    expect(hasSmem[0].id).toBe("m2");
+
+    const noSmem = await storage.memories.list({
+      filter: { smem: false },
+    });
+    expect(noSmem.length).toBe(3);
+  });
+
+  it("filters by timestamp range", async () => {
+    const now = Date.now();
+    const m1 = await storage.memories.get("m1");
+    const m2 = await storage.memories.get("m2");
+
+    const memories = await storage.memories.list({
+      filter: {
+        after: m1!.timestamp - 1,
+        before: m2!.timestamp + 1,
+      },
+    });
+
+    expect(memories.length).toBe(2);
+    expect(memories.map((m) => m.id).sort()).toEqual(["m1", "m2"]);
+  });
+
+  it("orders by timestamp desc (default)", async () => {
+    const memories = await storage.memories.list();
+
+    // Should be in desc order by default
+    for (let i = 1; i < memories.length; i++) {
+      expect(memories[i - 1].timestamp).toBeGreaterThanOrEqual(memories[i].timestamp);
+    }
+  });
+
+  it("orders by timestamp asc", async () => {
+    const memories = await storage.memories.list({ order: "asc" });
+
+    for (let i = 1; i < memories.length; i++) {
+      expect(memories[i - 1].timestamp).toBeLessThanOrEqual(memories[i].timestamp);
+    }
+  });
+
+  it("applies limit", async () => {
+    const memories = await storage.memories.list({ limit: 2 });
+    expect(memories.length).toBe(2);
+  });
+
+  it("applies offset", async () => {
+    const all = await storage.memories.list({ order: "asc" });
+    const offset = await storage.memories.list({ order: "asc", offset: 2 });
+
+    expect(offset.length).toBe(2);
+    expect(offset[0].id).toBe(all[2].id);
+  });
+
+  it("combines filters, order, limit, and offset", async () => {
+    const memories = await storage.memories.list({
+      filter: {
+        scope: { namespace: "ns1" },
+        collections: ["facts"],
+      },
+      order: "asc",
+      limit: 1,
+      offset: 1,
+    });
+
+    expect(memories.length).toBe(1);
+    expect(memories[0].id).toBe("m3");
+  });
+});