@kernl-sdk/pg 0.1.10 → 0.1.12

package/src/__tests__/integration.test.ts

@@ -10,11 +10,110 @@ import {
   type ModelRegistry,
 } from "kernl";
 import { Thread } from "kernl/internal";
+import type { LanguageModel } from "@kernl-sdk/protocol";
 
 const TEST_DB_URL = process.env.KERNL_PG_TEST_URL;
 
-type TestLanguageModel =
-  ModelRegistry extends { get(key: string): infer T | undefined } ? T : never;
+describe.sequential("PGStorage auto-initialization", () => {
+  if (!TEST_DB_URL) {
+    it.skip("requires KERNL_PG_TEST_URL to be set", () => {});
+    return;
+  }
+
+  /**
+   * Verifies that ALL store methods auto-initialize without explicit init() call.
+   *
+   * This is critical for DX - users should not need to remember to call init().
+   * Each method must internally call ensureInit() before any DB operation.
+   *
+   * Methods covered: get, list, insert, update, delete, history, append
+   */
+  it("auto-initializes on first store operation (no explicit init required)", async () => {
+    const pool = new Pool({ connectionString: TEST_DB_URL });
+    const storage = new PGStorage({ pool });
+
+    // Clean slate - drop schema to prove init runs automatically
+    await pool.query('DROP SCHEMA IF EXISTS "kernl" CASCADE');
+
+    // Bind minimal registries
+    const model = {
+      spec: "1.0" as const,
+      provider: "test",
+      modelId: "auto-init-model",
+    } as unknown as LanguageModel;
+
+    const agent = new Agent({
+      id: "auto-init-agent",
+      name: "Auto Init Agent",
+      instructions: () => "test",
+      model,
+    });
+
+    const agents: AgentRegistry = new Map([["auto-init-agent", agent]]);
+    const models: ModelRegistry = new Map([
+      ["test/auto-init-model", model],
+    ]) as unknown as ModelRegistry;
+
+    storage.bind({ agents, models });
+    const store = storage.threads;
+    const tid = "auto-init-thread";
+
+    // 1) list() - should auto-init
+    const threads = await store.list();
+    expect(threads).toEqual([]);
+
+    // 2) get() - should work (returns null for non-existent)
+    const got = await store.get(tid);
+    expect(got).toBeNull();
+
+    // 3) insert() - should work
+    const inserted = await store.insert({
+      id: tid,
+      namespace: "kernl",
+      agentId: "auto-init-agent",
+      model: "test/auto-init-model",
+    });
+    expect(inserted.tid).toBe(tid);
+
+    // 4) update() - should work
+    await store.update(tid, { tick: 1 });
+    const tickResult = await pool.query<{ tick: number }>(
+      `SELECT tick FROM "kernl"."threads" WHERE id = $1`,
+      [tid],
+    );
+    expect(tickResult.rows[0]?.tick).toBe(1);
+
+    // 5) history() - should work (empty)
+    const hist = await store.history(tid);
+    expect(hist).toEqual([]);
+
+    // 6) append() - should work
+    await store.append([
+      {
+        id: "evt-1",
+        tid,
+        seq: 0,
+        kind: "message",
+        timestamp: new Date(),
+        data: { role: "user", text: "test" },
+        metadata: null,
+      } as any,
+    ]);
+
+    // 7) delete() - should work
+    await store.delete(tid);
+    const afterDelete = await store.get(tid);
+    expect(afterDelete).toBeNull();
+
+    // Verify schema was created
+    const schemaResult = await pool.query(
+      `SELECT schema_name FROM information_schema.schemata WHERE schema_name = 'kernl'`,
+    );
+    expect(schemaResult.rows).toHaveLength(1);
+
+    await storage.close();
+  });
+});
 
 describe.sequential("PGStorage integration", () => {
   if (!TEST_DB_URL) {
@@ -71,7 +170,7 @@ describe.sequential("PGStorage integration", () => {
       `SELECT id FROM "kernl".migrations ORDER BY applied_at ASC`,
     );
     const appliedMigrationIds = migrationsResult.rows.map((row) => row.id);
-    expect(appliedMigrationIds).toEqual(["0001_initial"]);
+    expect(appliedMigrationIds).toEqual(["001_threads", "002_memories"]);
 
     // ---- verify indexes created by table definitions ----
     const indexesResult = await pool.query<{
@@ -206,7 +305,7 @@ describe.sequential("PGStorage integration", () => {
       spec: "1.0" as const,
       provider: "test",
       modelId: "test-model",
-    } as unknown as TestLanguageModel;
+    } as unknown as LanguageModel;
 
     const agent = new Agent({
       id: "agent-1",
@@ -216,7 +315,7 @@ describe.sequential("PGStorage integration", () => {
     });
 
     const agents: AgentRegistry = new Map<string, Agent>([["agent-1", agent]]);
-    const models: ModelRegistry = new Map<string, TestLanguageModel>([
+    const models: ModelRegistry = new Map<string, LanguageModel>([
       ["provider/model", model],
     ]) as unknown as ModelRegistry;
 
@@ -402,7 +501,7 @@ describe.sequential("PGStorage integration", () => {
       spec: "1.0" as const,
       provider: "test",
       modelId: "test-model",
-    } as unknown as TestLanguageModel;
+    } as unknown as LanguageModel;
 
     const agent = new Agent({
       id: "agent-1",
@@ -412,7 +511,7 @@ describe.sequential("PGStorage integration", () => {
     });
 
     const agents: AgentRegistry = new Map<string, Agent>([["agent-1", agent]]);
-    const models: ModelRegistry = new Map<string, TestLanguageModel>([
+    const models: ModelRegistry = new Map<string, LanguageModel>([
       ["provider/model", model],
     ]) as unknown as ModelRegistry;
 
@@ -475,7 +574,7 @@ describe.sequential("PGStorage integration", () => {
       modelId: "test-model",
       // generate/stream are not used in this test - we only advance stream
       // far enough to trigger the first checkpoint.
-    } as unknown as TestLanguageModel;
+    } as unknown as LanguageModel;
 
     const agent = new Agent({
       id: "agent-1",
@@ -485,7 +584,7 @@ describe.sequential("PGStorage integration", () => {
     });
 
     const agents: AgentRegistry = new Map<string, Agent>([["agent-1", agent]]);
-    const models: ModelRegistry = new Map<string, TestLanguageModel>([
+    const models: ModelRegistry = new Map<string, LanguageModel>([
       ["provider/model", model],
     ]) as unknown as ModelRegistry;
 
@@ -533,7 +632,7 @@ describe.sequential("PGStorage integration", () => {
       spec: "1.0" as const,
       provider: "test",
       modelId: "test-model",
-    } as unknown as TestLanguageModel;
+    } as unknown as LanguageModel;
 
     const agent = new Agent({
       id: "agent-1",
@@ -543,7 +642,7 @@ describe.sequential("PGStorage integration", () => {
     });
 
     const agents: AgentRegistry = new Map<string, Agent>([["agent-1", agent]]);
-    const models: ModelRegistry = new Map<string, TestLanguageModel>([
+    const models: ModelRegistry = new Map<string, LanguageModel>([
       ["provider/model", model],
     ]) as unknown as ModelRegistry;
 
@@ -595,7 +694,7 @@ describe.sequential("PGStorage integration", () => {
       spec: "1.0" as const,
       provider: "test",
       modelId: "test-model",
-    } as unknown as TestLanguageModel;
+    } as unknown as LanguageModel;
 
     const agent1 = new Agent({
       id: "agent-1",
@@ -615,7 +714,7 @@ describe.sequential("PGStorage integration", () => {
       ["agent-1", agent1],
       ["agent-2", agent2],
     ]);
-    const models: ModelRegistry = new Map<string, TestLanguageModel>([
+    const models: ModelRegistry = new Map<string, LanguageModel>([
       ["provider/model", model],
     ]) as unknown as ModelRegistry;
 
@@ -719,7 +818,7 @@ describe.sequential("PGStorage integration", () => {
       spec: "1.0" as const,
       provider: "test",
       modelId: "test-model",
-    } as unknown as TestLanguageModel;
+    } as unknown as LanguageModel;
 
     const agent = new Agent({
       id: "agent-1",
@@ -729,7 +828,7 @@ describe.sequential("PGStorage integration", () => {
     });
 
     const agents: AgentRegistry = new Map<string, Agent>([["agent-1", agent]]);
-    const models: ModelRegistry = new Map<string, TestLanguageModel>([
+    const models: ModelRegistry = new Map<string, LanguageModel>([
       ["provider/model", model],
     ]) as unknown as ModelRegistry;
 

package/src/__tests__/memory-integration.test.ts

@@ -0,0 +1,355 @@
+import { describe, it, expect, beforeAll, afterAll, beforeEach } from "vitest";
+import { Pool } from "pg";
+import { Kernl, Agent } from "kernl";
+import type { LanguageModel } from "@kernl-sdk/protocol";
+import "@kernl-sdk/ai/openai"; // Register OpenAI embedding provider
+
+import { postgres, pgvector } from "../index";
+
+const TEST_DB_URL = process.env.KERNL_PG_TEST_URL;
+
+describe.sequential(
+  "Memory Integration with PGVector",
+  { timeout: 30000 },
+  () => {
+    if (!TEST_DB_URL) {
+      it.skip("requires KERNL_PG_TEST_URL environment variable", () => {});
+      return;
+    }
+
+    if (!process.env.OPENAI_API_KEY) {
+      it.skip("requires OPENAI_API_KEY environment variable", () => {});
+      return;
+    }
+
+    let pool: Pool;
+    let kernl: Kernl;
+
+    beforeAll(async () => {
+      pool = new Pool({ connectionString: TEST_DB_URL });
+
+      // Clean slate
+      await pool.query('DROP SCHEMA IF EXISTS "kernl" CASCADE');
+
+      // Create Kernl with PG + pgvector
+      kernl = new Kernl({
+        storage: {
+          db: postgres({ pool }),
+          vector: pgvector({ pool }),
+        },
+        memory: {
+          embeddingModel: "openai/text-embedding-3-small",
+          dimensions: 1536,
+        },
+      });
+
+      // Register a dummy agent for test scope
+      const model = {
+        spec: "1.0" as const,
+        provider: "test",
+        modelId: "test-model",
+      } as unknown as LanguageModel;
+
+      const agent = new Agent({
+        id: "test-agent",
+        name: "Test Agent",
+        instructions: () => "test instructions",
+        model,
+      });
+
+      kernl.register(agent);
+
+      // Initialize storage (creates "kernl" schema and tables)
+      await kernl.storage.init();
+    });
+
+    afterAll(async () => {
+      if (kernl) {
+        await kernl.storage.close();
+      }
+    });
+
+    beforeEach(async () => {
+      // Clean memories between tests
+      await pool.query('DELETE FROM "kernl"."memories"');
+
+      // Vector index table may not exist yet (created lazily on first memory operation)
+      try {
+        await pool.query('DELETE FROM "kernl"."memories_sindex"');
+      } catch (err: any) {
+        if (!err.message?.includes("does not exist")) {
+          throw err;
+        }
+      }
+    });
+
+    it("creates memory and indexes it in pgvector on first operation", async () => {
+      const memory = await kernl.memories.create({
+        id: "m1",
+        scope: { namespace: "test", agentId: "test-agent" },
+        kind: "semantic",
+        collection: "facts",
+        content: { text: "The user loves TypeScript programming" },
+      });
+
+      expect(memory.id).toBe("m1");
+      expect(memory.content.text).toBe("The user loves TypeScript programming");
+
+      // Verify memory exists in DB
+      const dbResult = await pool.query(
+        'SELECT * FROM "kernl"."memories" WHERE id = $1',
+        ["m1"],
+      );
+      expect(dbResult.rows).toHaveLength(1);
+
+      // Verify memory was indexed in pgvector
+      const vectorResult = await pool.query(
+        'SELECT * FROM "kernl"."memories_sindex" WHERE id = $1',
+        ["m1"],
+      );
+      expect(vectorResult.rows).toHaveLength(1);
+      expect(vectorResult.rows[0].text).toBe(
+        "The user loves TypeScript programming",
+      );
+      expect(vectorResult.rows[0].tvec).toBeTruthy(); // vector embedding exists
+    });
+
+    it("searches memories using vector similarity", async () => {
+      // Create several memories
+      await kernl.memories.create({
+        id: "m1",
+        scope: { namespace: "test" },
+        kind: "semantic",
+        collection: "facts",
+        content: { text: "The user loves TypeScript programming" },
+      });
+
+      await kernl.memories.create({
+        id: "m2",
+        scope: { namespace: "test" },
+        kind: "semantic",
+        collection: "facts",
+        content: { text: "The user enjoys cooking Italian food" },
+      });
+
+      await kernl.memories.create({
+        id: "m3",
+        scope: { namespace: "test" },
+        kind: "semantic",
+        collection: "facts",
+        content: { text: "TypeScript has excellent type safety" },
+      });
+
+      // Search for TypeScript-related memories
+      const results = await kernl.memories.search({
+        query: "programming languages",
+        limit: 10,
+      });
+
+      expect(results.length).toBeGreaterThan(0);
+
+      // Should find TypeScript-related memories with higher scores
+      const ids = results.map((r) => r.document?.id);
+      expect(ids).toContain("m1"); // Direct match
+      expect(ids).toContain("m3"); // Related to TypeScript
+    });
+
+    it("returns no results when filters exclude all matches", async () => {
+      await kernl.memories.create({
+        id: "m1",
+        scope: { namespace: "ns1", agentId: "test-agent" },
+        kind: "semantic",
+        collection: "facts",
+        content: { text: "User likes hiking" },
+      });
+
+      // Filter for a different namespace that has no memories
+      const results = await kernl.memories.search({
+        query: "hiking",
+        filter: { scope: { namespace: "ns2" } },
+        limit: 10,
+      });
+
+      expect(results.length).toBe(0);
+    });
+
+    it("filters search results by scope", async () => {
+      await kernl.memories.create({
+        id: "m1",
+        scope: { namespace: "user1", agentId: "test-agent" },
+        kind: "semantic",
+        collection: "facts",
+        content: { text: "User 1 likes cats" },
+      });
+
+      await kernl.memories.create({
+        id: "m2",
+        scope: { namespace: "user2", agentId: "test-agent" },
+        kind: "semantic",
+        collection: "facts",
+        content: { text: "User 2 likes cats" },
+      });
+
+      // Search only in user1 namespace
+      const results = await kernl.memories.search({
+        query: "cats",
+        filter: { scope: { namespace: "user1" } },
+        limit: 10,
+      });
+
+      expect(results.length).toBe(1);
+      expect(results[0].document?.id).toBe("m1");
+    });
+
+    it("respects topK limit", async () => {
+      await kernl.memories.create({
+        id: "m1",
+        scope: { namespace: "test" },
+        kind: "semantic",
+        collection: "facts",
+        content: { text: "The user likes TypeScript" },
+      });
+
+      await kernl.memories.create({
+        id: "m2",
+        scope: { namespace: "test" },
+        kind: "semantic",
+        collection: "facts",
+        content: { text: "The user likes JavaScript" },
+      });
+
+      await kernl.memories.create({
+        id: "m3",
+        scope: { namespace: "test" },
+        kind: "semantic",
+        collection: "facts",
+        content: { text: "The user likes Rust" },
+      });
+
+      const results = await kernl.memories.search({
+        query: "programming languages",
+        limit: 1,
+      });
+
+      expect(results.length).toBe(1);
+    });
+
+    it("handles index creation idempotently across Kernl instances", async () => {
+      // Create memory with first Kernl instance
+      await kernl.memories.create({
+        id: "m1",
+        scope: { namespace: "test" },
+        kind: "semantic",
+        collection: "facts",
+        content: { text: "First instance memory" },
+      });
+
+      // Close first instance (also closes the pool)
+      await kernl.storage.close();
+
+      // Create new pool and Kernl instance - reassign both so afterAll and beforeEach work
+      pool = new Pool({ connectionString: TEST_DB_URL });
+      kernl = new Kernl({
+        storage: {
+          db: postgres({ pool }),
+          vector: pgvector({ pool }),
+        },
+        memory: {
+          embeddingModel: "openai/text-embedding-3-small",
+          dimensions: 1536,
+        },
+      });
+
+      // Should be able to search without errors (index already exists)
+      const results = await kernl.memories.search({
+        query: "memory",
+        limit: 10,
+      });
+
+      expect(results.length).toBeGreaterThan(0);
+      expect(results[0].document?.id).toBe("m1");
+    });
+
+    it("updates memory content and re-indexes", async () => {
+      await kernl.memories.create({
+        id: "m1",
+        scope: { namespace: "test" },
+        kind: "semantic",
+        collection: "facts",
+        content: { text: "Original content about dogs" },
+      });
+
+      // Update content
+      await kernl.memories.update({
+        id: "m1",
+        content: { text: "Updated content about cats" },
+      });
+
+      // Search should find updated content
+      const results = await kernl.memories.search({
+        query: "cats",
+        limit: 10,
+      });
+
+      expect(results.length).toBeGreaterThan(0);
+      const match = results.find((r) => r.document?.id === "m1");
+      expect(match).toBeDefined();
+      expect(match?.document?.text).toBe("Updated content about cats");
+    });
+
+    it("patches memory metadata without re-indexing", async () => {
+      await kernl.memories.create({
+        id: "m1",
+        scope: { namespace: "test" },
+        kind: "semantic",
+        collection: "facts",
+        content: { text: "Cats are great pets" },
+        metadata: { version: 1 },
+      });
+
+      // Update only metadata (should patch, not full re-index)
+      await kernl.memories.update({
+        id: "m1",
+        metadata: { version: 2, updated: true },
+      });
+
+      // Verify metadata updated in vector index
+      const vectorResult = await pool.query(
+        'SELECT metadata FROM "kernl"."memories_sindex" WHERE id = $1',
+        ["m1"],
+      );
+
+      expect(vectorResult.rows[0].metadata).toEqual({
+        version: 2,
+        updated: true,
+      });
+    });
+
+    it("creates memories with multimodal content", async () => {
+      await kernl.memories.create({
+        id: "m1",
+        scope: { namespace: "test" },
+        kind: "semantic",
+        collection: "media",
+        content: {
+          text: "A beautiful sunset",
+          image: {
+            data: "base64encodedimage",
+            mime: "image/png",
+            alt: "Sunset over the ocean",
+          },
+        },
+      });
+
+      // Should be searchable by text
+      const results = await kernl.memories.search({
+        query: "sunset",
+        limit: 10,
+      });
+
+      expect(results.length).toBeGreaterThan(0);
+      const match = results.find((r) => r.document?.id === "m1");
+      expect(match).toBeDefined();
+    });
+  },
+);