@kernl-sdk/pg 0.1.10 → 0.1.12

package/.turbo/turbo-build.log

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

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

@@ -0,0 +1,36 @@
+
+> @kernl-sdk/pg@0.1.11 check-types /Users/andjones/Documents/projects/kernl/packages/storage/pg
+> tsc --noEmit
+
+src/search/__tests__/hit.test.ts(75,55): error TS2345: Argument of type '{ schema: string; table: string; fields: { title: { column: string; type: "string"; }; content: { column: string; type: "string"; }; embedding: { column: string; type: "vector"; dimensions: number; }; }; }' is not assignable to parameter of type 'PGIndexConfig'.
+  Property 'pkey' is missing in type '{ schema: string; table: string; fields: { title: { column: string; type: "string"; }; content: { column: string; type: "string"; }; embedding: { column: string; type: "vector"; dimensions: number; }; }; }' but required in type 'PGIndexConfig'.
+src/search/__tests__/hit.test.ts(93,55): error TS2345: Argument of type '{ schema: string; table: string; fields: { title: { column: string; type: "string"; }; content: { column: string; type: "string"; }; embedding: { column: string; type: "vector"; dimensions: number; }; }; }' is not assignable to parameter of type 'PGIndexConfig'.
+  Property 'pkey' is missing in type '{ schema: string; table: string; fields: { title: { column: string; type: "string"; }; content: { column: string; type: "string"; }; embedding: { column: string; type: "vector"; dimensions: number; }; }; }' but required in type 'PGIndexConfig'.
+src/search/__tests__/hit.test.ts(110,55): error TS2345: Argument of type '{ schema: string; table: string; fields: { title: { column: string; type: "string"; }; content: { column: string; type: "string"; }; embedding: { column: string; type: "vector"; dimensions: number; }; }; }' is not assignable to parameter of type 'PGIndexConfig'.
+  Property 'pkey' is missing in type '{ schema: string; table: string; fields: { title: { column: string; type: "string"; }; content: { column: string; type: "string"; }; embedding: { column: string; type: "vector"; dimensions: number; }; }; }' but required in type 'PGIndexConfig'.
+src/search/__tests__/hit.test.ts(124,55): error TS2345: Argument of type '{ schema: string; table: string; fields: { title: { column: string; type: "string"; }; content: { column: string; type: "string"; }; embedding: { column: string; type: "vector"; dimensions: number; }; }; }' is not assignable to parameter of type 'PGIndexConfig'.
+  Property 'pkey' is missing in type '{ schema: string; table: string; fields: { title: { column: string; type: "string"; }; content: { column: string; type: "string"; }; embedding: { column: string; type: "vector"; dimensions: number; }; }; }' but required in type 'PGIndexConfig'.
+src/search/sql/__tests__/order.test.ts(58,11): error TS2741: Property 'pkey' is missing in type '{ schema: string; table: string; fields: { embedding: { column: string; type: "vector"; dimensions: number; similarity: "cosine"; }; }; }' but required in type 'PGIndexConfig'.
+src/search/sql/__tests__/order.test.ts(77,11): error TS2741: Property 'pkey' is missing in type '{ schema: string; table: string; fields: { embedding: { column: string; type: "vector"; dimensions: number; similarity: "euclidean"; }; }; }' but required in type 'PGIndexConfig'.
+src/search/sql/__tests__/order.test.ts(96,11): error TS2741: Property 'pkey' is missing in type '{ schema: string; table: string; fields: { embedding: { column: string; type: "vector"; dimensions: number; similarity: "dot_product"; }; }; }' but required in type 'PGIndexConfig'.
+src/search/sql/__tests__/order.test.ts(134,11): error TS2741: Property 'pkey' is missing in type '{ schema: string; table: string; fields: { other_field: { column: string; type: "vector"; dimensions: number; similarity: "euclidean"; }; }; }' but required in type 'PGIndexConfig'.
+src/search/sql/__tests__/query.test.ts(110,21): error TS2741: Property 'pkey' is missing in type '{ schema: string; table: string; fields: { embedding: { column: string; type: "vector"; dimensions: number; similarity: "cosine"; }; }; }' but required in type 'PGIndexConfig'.
+src/search/sql/__tests__/query.test.ts(196,23): error TS2741: Property 'pkey' is missing in type '{ schema: string; table: string; fields: { embedding: { column: string; type: "vector"; dimensions: number; similarity: "cosine"; }; }; }' but required in type 'PGIndexConfig'.
+src/search/sql/__tests__/query.test.ts(258,27): error TS2741: Property 'pkey' is missing in type '{ schema: string; table: string; fields: { embedding: { column: string; type: "vector"; dimensions: number; similarity: "euclidean"; }; }; }' but required in type 'PGIndexConfig'.
+src/search/sql/__tests__/query.test.ts(324,25): error TS2741: Property 'pkey' is missing in type '{ schema: string; table: string; fields: { embedding: { column: string; type: "vector"; dimensions: number; similarity: "cosine"; }; }; }' but required in type 'PGIndexConfig'.
+src/search/sql/__tests__/query.test.ts(462,21): error TS2741: Property 'pkey' is missing in type '{ schema: string; table: string; fields: { embedding: { column: string; type: "vector"; dimensions: number; similarity: "euclidean"; }; }; }' but required in type 'PGIndexConfig'.
+src/search/sql/__tests__/query.test.ts(492,21): error TS2741: Property 'pkey' is missing in type '{ schema: string; table: string; fields: { embedding: { column: string; type: "vector"; dimensions: number; similarity: "dot_product"; }; }; }' but required in type 'PGIndexConfig'.
+src/search/sql/__tests__/select.test.ts(43,9): error TS2741: Property 'pkey' is missing in type '{ schema: string; table: string; fields: { embedding: { column: string; type: "vector"; dimensions: number; similarity: "cosine"; }; }; }' but required in type 'PGIndexConfig'.
+src/search/sql/__tests__/select.test.ts(67,9): error TS2741: Property 'pkey' is missing in type '{ schema: string; table: string; fields: { embedding: { column: string; type: "vector"; dimensions: number; similarity: "euclidean"; }; }; }' but required in type 'PGIndexConfig'.
+src/search/sql/__tests__/select.test.ts(91,9): error TS2741: Property 'pkey' is missing in type '{ schema: string; table: string; fields: { embedding: { column: string; type: "vector"; dimensions: number; similarity: "dot_product"; }; }; }' but required in type 'PGIndexConfig'.
+src/search/sql/__tests__/select.test.ts(155,11): error TS2741: Property 'pkey' is missing in type '{ schema: string; table: string; fields: { other_field: { column: string; type: "vector"; dimensions: number; similarity: "cosine"; }; }; }' but required in type 'PGIndexConfig'.
+src/search/sql/__tests__/select.test.ts(300,9): error TS2741: Property 'pkey' is missing in type '{ schema: string; table: string; fields: { title: { column: string; type: "string"; }; content: { column: string; type: "string"; }; embedding: { column: string; type: "vector"; dimensions: number; similarity: "cosine"; }; }; }' but required in type 'PGIndexConfig'.
+src/search/sql/__tests__/select.test.ts(312,9): error TS2741: Property 'pkey' is missing in type '{ schema: string; table: string; fields: { title: { column: string; type: "string"; }; content: { column: string; type: "string"; }; embedding: { column: string; type: "vector"; dimensions: number; similarity: "cosine"; }; }; }' but required in type 'PGIndexConfig'.
+src/search/sql/__tests__/select.test.ts(325,9): error TS2741: Property 'pkey' is missing in type '{ schema: string; table: string; fields: { title: { column: string; type: "string"; }; content: { column: string; type: "string"; }; embedding: { column: string; type: "vector"; dimensions: number; similarity: "cosine"; }; }; }' but required in type 'PGIndexConfig'.
+src/search/sql/__tests__/select.test.ts(336,9): error TS2741: Property 'pkey' is missing in type '{ schema: string; table: string; fields: { title: { column: string; type: "string"; }; content: { column: string; type: "string"; }; embedding: { column: string; type: "vector"; dimensions: number; similarity: "cosine"; }; }; }' but required in type 'PGIndexConfig'.
+src/search/sql/__tests__/select.test.ts(347,9): error TS2741: Property 'pkey' is missing in type '{ schema: string; table: string; fields: { title: { column: string; type: "string"; }; content: { column: string; type: "string"; }; embedding: { column: string; type: "vector"; dimensions: number; similarity: "cosine"; }; }; }' but required in type 'PGIndexConfig'.
+src/search/sql/__tests__/where.test.ts(357,28): error TS2322: Type 'string' is not assignable to type 'Filter'.
+  Type 'string' is not assignable to type '{ [field: string]: Filter | ScalarValue | FieldOps | Filter[] | undefined; }'.
+src/search/sql/__tests__/where.test.ts(357,33): error TS2322: Type 'string' is not assignable to type 'Filter'.
+  Type 'string' is not assignable to type '{ [field: string]: Filter | ScalarValue | FieldOps | Filter[] | undefined; }'.
+ ELIFECYCLE  Command failed with exit code 2.

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # @kernl/pg
 
+## 0.1.12
+
+### Patch Changes
+
+- a7d6138: Add agent.memories API and memory integration with vector backends
+
+  **@kernl-sdk/retrieval**
+  - Add `planQuery()` for adapting queries based on backend capabilities
+  - Add `SearchCapabilities` interface to describe backend features
+  - Gracefully degrade hybrid queries when not supported
+
+  **@kernl-sdk/pg**
+  - Add `capabilities()` method to PGVectorSearchIndex
+  - Fix hit decoding to include id in document
+
+  **@kernl-sdk/turbopuffer**
+  - Add `capabilities()` method describing supported search modes
+  - Add bigint type mapping for timestamps
+  - Fix hit decoding to include id in document
+  - Add memory integration tests
+
+  **kernl**
+  - Add `agent.memories.create()` with simplified syntax (auto-generated IDs, flattened scope)
+  - Add `agent.memories.search()` scoped to agent
+  - Add backend-aware codecs for Turbopuffer field mapping (tvec → vector)
+  - Default `include: true` for Turbopuffer queries to return all attributes
+
+- Updated dependencies [a7d6138]
+  - @kernl-sdk/retrieval@0.1.0
+  - kernl@0.6.3
+  - @kernl-sdk/storage@0.1.12
+
+## 0.1.11
+
+### Patch Changes
+
+- c5a5fcf: Storage now auto-initializes on first operation - no need to call init() manually
+- Updated dependencies [c5a5fcf]
+  - kernl@0.6.2
+  - @kernl-sdk/storage@0.1.11
+
 ## 0.1.10
 
 ### Patch Changes

package/README.md

@@ -0,0 +1,124 @@
+# @kernl-sdk/pg
+
+PostgreSQL storage adapter for kernl.
+
+## Prerequisites
+
+Vector search requires the [pgvector](https://github.com/pgvector/pgvector) extension. This must be installed by a superuser before enabling `vector: true`:
+
+```sql
+CREATE EXTENSION IF NOT EXISTS vector;
+```
+
+The storage adapter will automatically create the embedding column and index when `vector` is configured.
+
+## Installation
+
+```bash
+pnpm i @kernl-sdk/pg
+```
+
+## Usage
+
+```typescript
+import { postgres } from "@kernl-sdk/pg";
+
+// :a: connection string
+const storage = postgres({ connstr: process.env.DATABASE_URL });
+
+// :b: individual credentials
+const storage = postgres({
+  host: "localhost",
+  port: 5432,
+  database: "mydb",
+  user: "user",
+  password: "password",
+});
+
+// :c: existing pool
+import { Pool } from "pg";
+const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+const storage = postgres({ pool });
+```
+
+## Configuration
+
+Connection options (one of):
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `connstr` | `string` | PostgreSQL connection string |
+| `pool` | `Pool` | Existing pg Pool instance |
+| `host`, `port`, `database`, `user`, `password` | `string`/`number` | Individual connection credentials |
+
+Additional options:
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `vector` | `boolean \| PGVectorConfig` | `undefined` | Enable pgvector support |
+
+### Vector Configuration
+
+When `vector: true`, defaults are applied:
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `dimensions` | `number` | `1536` | Vector dimensions (matches OpenAI text-embedding-3-small) |
+| `similarity` | `"cosine" \| "euclidean" \| "dot_product"` | `"cosine"` | Distance metric |
+
+```ts
+// Use defaults (1536 dimensions, cosine similarity)
+const storage = postgres({ pool, vector: true });
+
+// Custom configuration
+const storage = postgres({ pool, vector: { dimensions: 768, similarity: "dot_product" } });
+```
+
+## pgvector
+
+kernl follows simple conventions so most indexes “just work” without extra configuration:
+
+```ts
+const pgvec = pgvector({ pool });
+const docs = pgvec.index<Doc>("docs"); // "public.docs"
+await docs.upsert({ id: "doc-1", title: "Hello", embedding: [/* ... */] });
+await docs.query({ title: "Hello" });
+```
+
+### Index id = table name
+
+By default, `index(name)` refers to the "public" schema and the name would be the table name. So:
+
+  - `search.index("docs")` refers to the table `public.docs`.
+  - `search.index("analytics.events")` refers to the table `analytics.events`.
+
+
+### Field conventions
+
+  - field names map directly to column names,
+      - `title` → `"title"`,
+      - `content` → `"content"`,
+      - `embedding` → `"embedding"`, etc.
+  - any field you pass a `number[]` for is used as a pgvector `vector` column with the same name.
+
+
+### Primary key column
+
+  - kernl assumes PK column is `id` by default,
+  - Upserts use `INSERT ... ON CONFLICT ("id") DO UPDATE ...`.
+  - If your table uses a different key name, you must explicitly bind the index:
+
+```ts
+const pgvec = pgvector({ pool });
+
+pgvec.bindIndex("docs", {
+  schema: "public",
+  table: "articles", // ← table name differs from passed schema name (atypical)
+  pkey: "article_id", // ← primary key is not "id"
+  fields: {
+    embedding: { column: "embed_vec", type: "vector", dimensions: 1536, similarity: "cosine" },
+    title:     { column: "article_title", type: "string" },
+    // ...
+  },
+});
+```

package/dist/__tests__/integration.test.js

@@ -4,6 +4,86 @@ import { PGStorage } from "../storage.js";
 import { Agent, Context, } from "kernl";
 import { Thread } from "kernl/internal";
 const TEST_DB_URL = process.env.KERNL_PG_TEST_URL;
+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",
+            provider: "test",
+            modelId: "auto-init-model",
+        };
+        const agent = new Agent({
+            id: "auto-init-agent",
+            name: "Auto Init Agent",
+            instructions: () => "test",
+            model,
+        });
+        const agents = new Map([["auto-init-agent", agent]]);
+        const models = new Map([
+            ["test/auto-init-model", model],
+        ]);
+        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(`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,
+            },
+        ]);
+        // 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) {
         it.skip("requires KERNL_PG_TEST_URL to be set", () => {
@@ -39,7 +119,7 @@ describe.sequential("PGStorage integration", () => {
         // ---- verify migrations recorded ----
         const migrationsResult = await pool.query(`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(`
         SELECT indexname, tablename

package/dist/__tests__/memory-integration.test.d.ts

@@ -0,0 +1,2 @@
+import "@kernl-sdk/ai/openai";
+//# sourceMappingURL=memory-integration.test.d.ts.map

package/dist/__tests__/memory-integration.test.d.ts.map

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

package/dist/__tests__/memory-integration.test.js

@@ -0,0 +1,287 @@
+import { describe, it, expect, beforeAll, afterAll, beforeEach } from "vitest";
+import { Pool } from "pg";
+import { Kernl, Agent } from "kernl";
+import "@kernl-sdk/ai/openai"; // Register OpenAI embedding provider
+import { postgres, pgvector } from "../index.js";
+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;
+    let 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",
+            provider: "test",
+            modelId: "test-model",
+        };
+        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) {
+            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();
+    });
+});

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

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

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

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