@kernl-sdk/pg 0.1.10 → 0.1.12

package/dist/pgvector/sql/query.js

@@ -0,0 +1,54 @@
+/**
+ * Convert QueryOptions to SQL codec inputs.
+ *
+ * pgvector constraints:
+ * - Only single vector signal supported (no multi-signal fusion)
+ * - No hybrid (vector + text) in same signal
+ * - Filter-only and orderBy-only queries are allowed
+ */
+export function sqlize(query, config) {
+    const signals = query.query ?? query.max ?? [];
+    // Validate pgvector constraints
+    if (signals.length > 1) {
+        throw new Error("pgvector does not support multi-signal fusion. " +
+            "Use a single vector signal, or run multiple queries and fuse client-side.");
+    }
+    if (signals.length === 1) {
+        const { weight, ...fields } = signals[0];
+        let vectorCount = 0;
+        let textCount = 0;
+        for (const value of Object.values(fields)) {
+            if (value === undefined)
+                continue;
+            if (Array.isArray(value))
+                vectorCount++;
+            else if (typeof value === "string")
+                textCount++;
+        }
+        if (vectorCount > 1) {
+            throw new Error("pgvector does not support multi-vector fusion. " +
+                "Use a single vector signal, or run multiple queries and fuse client-side.");
+        }
+        if (vectorCount > 0 && textCount > 0) {
+            throw new Error("pgvector does not support hybrid (vector + text) fusion. " +
+                "Use a single vector signal, or run multiple queries and fuse client-side.");
+        }
+    }
+    return {
+        select: {
+            pkey: config.pkey,
+            signals,
+            binding: config.binding,
+            include: query.include,
+        },
+        where: { filter: query.filter },
+        order: {
+            signals,
+            orderBy: query.orderBy,
+            binding: config.binding,
+            schema: config.schema,
+            table: config.table,
+        },
+        limit: { topK: query.topK ?? 10, offset: query.offset ?? 0 },
+    };
+}

package/dist/pgvector/sql/schema.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Schema conversion codecs for pgvector.
+ */
+import type { Codec } from "@kernl-sdk/shared/lib";
+import type { FieldSchema, VectorFieldSchema } from "@kernl-sdk/retrieval";
+type Similarity = VectorFieldSchema["similarity"];
+/**
+ * Codec for converting FieldSchema to Postgres column type.
+ */
+export declare const FIELD_TYPE: Codec<FieldSchema, string>;
+/**
+ * Codec for converting similarity metric to pgvector HNSW operator class.
+ */
+export declare const SIMILARITY: Codec<Similarity | undefined, string>;
+export {};
+//# sourceMappingURL=schema.d.ts.map

package/dist/pgvector/sql/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/pgvector/sql/schema.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,KAAK,EACV,WAAW,EACX,iBAAiB,EAElB,MAAM,sBAAsB,CAAC;AAG9B,KAAK,UAAU,GAAG,iBAAiB,CAAC,YAAY,CAAC,CAAC;AAgBlD;;GAEG;AACH,eAAO,MAAM,UAAU,EAAE,KAAK,CAAC,WAAW,EAAE,MAAM,CAUjD,CAAC;AAWF;;GAEG;AACH,eAAO,MAAM,UAAU,EAAE,KAAK,CAAC,UAAU,GAAG,SAAS,EAAE,MAAM,CAK5D,CAAC"}

package/dist/pgvector/sql/schema.js

@@ -0,0 +1,47 @@
+/**
+ * Schema conversion codecs for pgvector.
+ */
+/**
+ * Mapping from kernl scalar types to Postgres column types.
+ */
+const SCALAR_TO_PG = {
+    string: "TEXT",
+    int: "INTEGER",
+    bigint: "BIGINT",
+    float: "DOUBLE PRECISION",
+    boolean: "BOOLEAN",
+    date: "TIMESTAMPTZ",
+    object: "JSONB",
+    geopoint: "POINT",
+};
+/**
+ * Codec for converting FieldSchema to Postgres column type.
+ */
+export const FIELD_TYPE = {
+    encode: (schema) => {
+        if (schema.type === "vector") {
+            return `vector(${schema.dimensions})`;
+        }
+        return SCALAR_TO_PG[schema.type] ?? "TEXT";
+    },
+    decode: () => {
+        throw new Error("FIELD_TYPE.decode not implemented");
+    },
+};
+/**
+ * Mapping from similarity metric to pgvector operator class.
+ */
+const SIMILARITY_TO_OPCLASS = {
+    cosine: "vector_cosine_ops",
+    euclidean: "vector_l2_ops",
+    dot_product: "vector_ip_ops",
+};
+/**
+ * Codec for converting similarity metric to pgvector HNSW operator class.
+ */
+export const SIMILARITY = {
+    encode: (similarity) => SIMILARITY_TO_OPCLASS[similarity ?? "cosine"],
+    decode: () => {
+        throw new Error("SIMILARITY.decode not implemented");
+    },
+};

package/dist/pgvector/sql/select.d.ts

@@ -0,0 +1,11 @@
+import type { Codec } from "@kernl-sdk/shared/lib";
+import type { SelectInput } from "./query.js";
+export interface SQLClause {
+    sql: string;
+    params: unknown[];
+}
+/**
+ * Codec for building SELECT clause with score expression.
+ */
+export declare const SQL_SELECT: Codec<SelectInput, SQLClause>;
+//# sourceMappingURL=select.d.ts.map

package/dist/pgvector/sql/select.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"select.d.ts","sourceRoot":"","sources":["../../../src/pgvector/sql/select.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAE3C,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,OAAO,EAAE,CAAC;CACnB;AAWD;;GAEG;AACH,eAAO,MAAM,UAAU,EAAE,KAAK,CAAC,WAAW,EAAE,SAAS,CA+EpD,CAAC"}

package/dist/pgvector/sql/select.js

@@ -0,0 +1,87 @@
+/**
+ * pgvector distance operators by similarity metric.
+ */
+const DISTANCE_OPS = {
+    cosine: "<=>",
+    euclidean: "<->",
+    dot_product: "<#>",
+};
+/**
+ * Codec for building SELECT clause with score expression.
+ */
+export const SQL_SELECT = {
+    encode({ pkey, signals, binding, include }) {
+        const parts = [`"${pkey}" as id`];
+        const params = [];
+        // find vector signal for scoring
+        const vsig = signals.find((s) => {
+            for (const [key, val] of Object.entries(s)) {
+                if (key !== "weight" && Array.isArray(val))
+                    return true;
+            }
+            return false;
+        });
+        if (vsig) {
+            // Extract vector field and value
+            let vecField = null;
+            let vecValue = null;
+            for (const [key, val] of Object.entries(vsig)) {
+                if (key !== "weight" && Array.isArray(val)) {
+                    vecField = key;
+                    vecValue = val;
+                    break;
+                }
+            }
+            if (vecField && vecValue) {
+                const col = binding?.fields[vecField]?.column ?? vecField;
+                const similarity = binding?.fields[vecField]?.similarity ?? "cosine";
+                const op = DISTANCE_OPS[similarity];
+                params.push(JSON.stringify(vecValue));
+                // score expression varies by metric
+                switch (similarity) {
+                    case "cosine":
+                        parts.push(`1 - ("${col}" ${op} $1::vector) as score`);
+                        break;
+                    case "euclidean":
+                        parts.push(`1 / (1 + ("${col}" ${op} $1::vector)) as score`);
+                        break;
+                    case "dot_product":
+                        parts.push(`-("${col}" ${op} $1::vector) as score`);
+                        break;
+                }
+            }
+        }
+        else {
+            parts.push("1 as score");
+        }
+        // Select columns based on include
+        // Note: We always select a calculated "score", so skip any document field named "score"
+        // to avoid ambiguity and ensure hit.score is always the similarity score.
+        if (binding && include !== false) {
+            const fields = Object.entries(binding.fields);
+            if (Array.isArray(include)) {
+                // Select only specified fields
+                for (const fieldName of include) {
+                    if (fieldName === "score")
+                        continue; // Skip to avoid overriding calculated score
+                    const field = binding.fields[fieldName];
+                    if (field) {
+                        parts.push(`"${field.column}"`);
+                    }
+                }
+            }
+            else {
+                // include: true or undefined → select all (except score)
+                for (const [fieldName, field] of fields) {
+                    if (fieldName === "score")
+                        continue; // Skip to avoid overriding calculated score
+                    parts.push(`"${field.column}"`);
+                }
+            }
+        }
+        return { sql: parts.join(", "), params };
+    },
+    decode() {
+        throw new Error("SQL_SELECT.decode not implemented");
+    },
+};

package/dist/pgvector/sql/where.d.ts

@@ -0,0 +1,8 @@
+import type { Codec } from "@kernl-sdk/shared/lib";
+import type { WhereInput } from "./query.js";
+import type { SQLClause } from "./select.js";
+/**
+ * Codec for building WHERE clause from MongoDB-style filter.
+ */
+export declare const SQL_WHERE: Codec<WhereInput, SQLClause>;
+//# sourceMappingURL=where.d.ts.map

package/dist/pgvector/sql/where.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"where.d.ts","sourceRoot":"","sources":["../../../src/pgvector/sql/where.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AAEnD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAC1C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAE1C;;GAEG;AACH,eAAO,MAAM,SAAS,EAAE,KAAK,CAAC,UAAU,EAAE,SAAS,CAWlD,CAAC"}

package/dist/pgvector/sql/where.js

@@ -0,0 +1,137 @@
+/**
+ * Codec for building WHERE clause from MongoDB-style filter.
+ */
+export const SQL_WHERE = {
+    encode({ filter, startIdx }) {
+        if (!filter) {
+            return { sql: "", params: [] };
+        }
+        return encodeFilter(filter, startIdx);
+    },
+    decode() {
+        throw new Error("SQL_WHERE.decode not implemented");
+    },
+};
+/**
+ * Encode a filter to SQL (recursive).
+ */
+function encodeFilter(filter, startIdx) {
+    const conditions = [];
+    const params = [];
+    let idx = startIdx;
+    for (const [key, value] of Object.entries(filter)) {
+        if (value === undefined)
+            continue;
+        // $and
+        if (key === "$and" && Array.isArray(value)) {
+            const parts = [];
+            for (const sub of value) {
+                const clause = encodeFilter(sub, idx);
+                if (clause.sql) {
+                    parts.push(`(${clause.sql})`);
+                    params.push(...clause.params);
+                    idx += clause.params.length;
+                }
+            }
+            if (parts.length > 0) {
+                conditions.push(`(${parts.join(" AND ")})`);
+            }
+            continue;
+        }
+        // $or
+        if (key === "$or" && Array.isArray(value)) {
+            const parts = [];
+            for (const sub of value) {
+                const clause = encodeFilter(sub, idx);
+                if (clause.sql) {
+                    parts.push(`(${clause.sql})`);
+                    params.push(...clause.params);
+                    idx += clause.params.length;
+                }
+            }
+            if (parts.length > 0) {
+                conditions.push(`(${parts.join(" OR ")})`);
+            }
+            continue;
+        }
+        // $not
+        if (key === "$not" && typeof value === "object" && !Array.isArray(value)) {
+            const clause = encodeFilter(value, idx);
+            if (clause.sql) {
+                conditions.push(`NOT (${clause.sql})`);
+                params.push(...clause.params);
+                idx += clause.params.length;
+            }
+            continue;
+        }
+        // field operators
+        if (isFieldOps(value)) {
+            const ops = value;
+            if (ops.$eq !== undefined) {
+                conditions.push(`"${key}" = $${idx++}`);
+                params.push(ops.$eq);
+            }
+            if (ops.$neq !== undefined) {
+                conditions.push(`"${key}" != $${idx++}`);
+                params.push(ops.$neq);
+            }
+            if (ops.$gt !== undefined) {
+                conditions.push(`"${key}" > $${idx++}`);
+                params.push(ops.$gt);
+            }
+            if (ops.$gte !== undefined) {
+                conditions.push(`"${key}" >= $${idx++}`);
+                params.push(ops.$gte);
+            }
+            if (ops.$lt !== undefined) {
+                conditions.push(`"${key}" < $${idx++}`);
+                params.push(ops.$lt);
+            }
+            if (ops.$lte !== undefined) {
+                conditions.push(`"${key}" <= $${idx++}`);
+                params.push(ops.$lte);
+            }
+            if (ops.$in !== undefined) {
+                conditions.push(`"${key}" = ANY($${idx++})`);
+                params.push(ops.$in);
+            }
+            if (ops.$nin !== undefined) {
+                conditions.push(`"${key}" != ALL($${idx++})`);
+                params.push(ops.$nin);
+            }
+            if (ops.$contains !== undefined) {
+                conditions.push(`"${key}" ILIKE $${idx++}`);
+                params.push(`%${ops.$contains}%`);
+            }
+            if (ops.$startsWith !== undefined) {
+                conditions.push(`"${key}" ILIKE $${idx++}`);
+                params.push(`${ops.$startsWith}%`);
+            }
+            if (ops.$endsWith !== undefined) {
+                conditions.push(`"${key}" ILIKE $${idx++}`);
+                params.push(`%${ops.$endsWith}`);
+            }
+            if (ops.$exists !== undefined) {
+                conditions.push(ops.$exists ? `"${key}" IS NOT NULL` : `"${key}" IS NULL`);
+            }
+            continue;
+        }
+        // Equality shorthand: { status: "active" }
+        if (value === null) {
+            conditions.push(`"${key}" IS NULL`);
+        }
+        else {
+            conditions.push(`"${key}" = $${idx++}`);
+            params.push(value);
+        }
+    }
+    return { sql: conditions.join(" AND "), params };
+}
+/**
+ * Check if value is an operator object (has $-prefixed keys).
+ */
+function isFieldOps(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    return Object.keys(value).some((k) => k.startsWith("$"));
+}

package/dist/pgvector/types.d.ts

@@ -0,0 +1,20 @@
+import type { FieldSchema } from "@kernl-sdk/retrieval";
+/**
+ * Mapping from a logical field name to a Postgres column.
+ */
+export interface PGFieldBinding {
+    column: string;
+    type: FieldSchema["type"];
+    dimensions?: number;
+    similarity?: "cosine" | "euclidean" | "dot_product";
+}
+/**
+ * Configuration for binding a Postgres table as a search index.
+ */
+export interface PGIndexConfig {
+    schema: string;
+    table: string;
+    pkey: string;
+    fields: Record<string, PGFieldBinding>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/pgvector/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/pgvector/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAExD;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,QAAQ,GAAG,WAAW,GAAG,aAAa,CAAC;CACrD;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;CACxC"}

package/dist/pgvector/types.js

@@ -0,0 +1 @@
+export {};

package/dist/pgvector/utils.d.ts

@@ -0,0 +1,18 @@
+/**
+ * pgvector utility functions.
+ */
+/**
+ * Parse index id into schema and table.
+ *
+ * - "docs" → { schema: "public", table: "docs" }
+ * - "analytics.events" → { schema: "analytics", table: "events" }
+ */
+export declare function parseIndexId(id: string): {
+    schema: string;
+    table: string;
+};
+/**
+ * Check if a value is a numeric array (vector).
+ */
+export declare function isVector(val: unknown): val is number[];
+//# sourceMappingURL=utils.d.ts.map

package/dist/pgvector/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/pgvector/utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAM1E;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,MAAM,EAAE,CAEtD"}

package/dist/pgvector/utils.js

@@ -0,0 +1,22 @@
+/**
+ * pgvector utility functions.
+ */
+/**
+ * Parse index id into schema and table.
+ *
+ * - "docs" → { schema: "public", table: "docs" }
+ * - "analytics.events" → { schema: "analytics", table: "events" }
+ */
+export function parseIndexId(id) {
+    const parts = id.split(".");
+    if (parts.length === 2) {
+        return { schema: parts[0], table: parts[1] };
+    }
+    return { schema: "public", table: id };
+}
+/**
+ * Check if a value is a numeric array (vector).
+ */
+export function isVector(val) {
+    return Array.isArray(val) && val.length > 0 && typeof val[0] === "number";
+}

package/dist/postgres.d.ts

@@ -1,9 +1,19 @@
 import { Pool } from "pg";
 import type { KernlStorage } from "kernl";
+import { type PGVectorConfig } from "./storage.js";
+import { PGSearchIndex } from "./pgvector/search.js";
 /**
- * PostgreSQL connection configuration.
+ * Create a PostgreSQL storage adapter for Kernl.
  */
-export type PostgresConfig = {
+export declare function postgres(config: PostgresConfig): KernlStorage;
+/**
+ * Create a pgvector-backed search index.
+ */
+export declare function pgvector(config: ConnectionConfig): PGSearchIndex;
+/**
+ * Connection options for PostgreSQL.
+ */
+export type ConnectionConfig = {
     pool: Pool;
 } | {
     connstr: string;
@@ -15,29 +25,12 @@ export type PostgresConfig = {
     password: string;
 };
 /**
- * Create a PostgreSQL storage adapter for Kernl.
- *
- * @param config - Connection configuration (pool, connection string, or credentials)
- * @returns KernlStorage instance backed by PostgreSQL
- *
- * @example
- * ```ts
- * // with connection string
- * const storage = postgres({ connstr: "postgresql://localhost/mydb" });
- *
- * // with connection options
- * const storage = postgres({
- *   host: "localhost",
- *   port: 5432,
- *   database: "mydb",
- *   user: "user",
- *   password: "password"
- * });
- *
- * // existing pool
- * const pool = new Pool({ ... });
- * const storage = postgres({ pool });
- * ```
+ * PostgreSQL storage configuration.
  */
-export declare function postgres(config: PostgresConfig): KernlStorage;
+export type PostgresConfig = ConnectionConfig & {
+    /**
+     * Enable pgvector support for semantic search.
+     */
+    vector?: boolean | PGVectorConfig;
+};
 //# sourceMappingURL=postgres.d.ts.map

package/dist/postgres.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"postgres.d.ts","sourceRoot":"","sources":["../src/postgres.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,IAAI,CAAC;AAC1B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC;AAI1C;;GAEG;AACH,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,IAAI,CAAA;CAAE,GACd;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,GACnB;IACE,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEN;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,YAAY,CAkB7D"}
+{"version":3,"file":"postgres.d.ts","sourceRoot":"","sources":["../src/postgres.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,IAAI,CAAC;AAC1B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC;AAE1C,OAAO,EAAa,KAAK,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3D,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAElD;;GAEG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,YAAY,CAG7D;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,gBAAgB,iBAGhD;AAED;;GAEG;AACH,MAAM,MAAM,gBAAgB,GACxB;IAAE,IAAI,EAAE,IAAI,CAAA;CAAE,GACd;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,GACnB;IACE,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEN;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,gBAAgB,GAAG;IAC9C;;OAEG;IACH,MAAM,CAAC,EAAE,OAAO,GAAG,cAAc,CAAC;CACnC,CAAC"}

package/dist/postgres.js

@@ -1,40 +1,29 @@
 import { Pool } from "pg";
 import { PGStorage } from "./storage.js";
+import { PGSearchIndex } from "./pgvector/search.js";
 /**
  * Create a PostgreSQL storage adapter for Kernl.
- *
- * @param config - Connection configuration (pool, connection string, or credentials)
- * @returns KernlStorage instance backed by PostgreSQL
- *
- * @example
- * ```ts
- * // with connection string
- * const storage = postgres({ connstr: "postgresql://localhost/mydb" });
- *
- * // with connection options
- * const storage = postgres({
- *   host: "localhost",
- *   port: 5432,
- *   database: "mydb",
- *   user: "user",
- *   password: "password"
- * });
- *
- * // existing pool
- * const pool = new Pool({ ... });
- * const storage = postgres({ pool });
- * ```
  */
 export function postgres(config) {
-    let pool;
+    const p = pool(config);
+    return new PGStorage({ pool: p, vector: config.vector });
+}
+/**
+ * Create a pgvector-backed search index.
+ */
+export function pgvector(config) {
+    const p = pool(config);
+    return new PGSearchIndex({ pool: p });
+}
+function pool(config) {
     if ("pool" in config) {
-        pool = config.pool;
+        return config.pool;
     }
     else if ("connstr" in config) {
-        pool = new Pool({ connectionString: config.connstr });
+        return new Pool({ connectionString: config.connstr });
     }
     else {
-        pool = new Pool({
+        return new Pool({
             host: config.host,
             port: config.port,
             database: config.database,
@@ -42,5 +31,4 @@ export function postgres(config) {
             password: config.password,
         });
     }
-    return new PGStorage({ pool });
 }

package/dist/storage.d.ts

@@ -1,6 +1,41 @@
 import type { Pool } from "pg";
 import type { AgentRegistry, ModelRegistry, KernlStorage, Transaction } from "kernl";
 import { PGThreadStore } from "./thread/store.js";
+import { PGMemoryStore } from "./memory/store.js";
+/**
+ * Vector similarity metric for pgvector.
+ */
+export type VectorSimilarity = "cosine" | "euclidean" | "dot_product";
+/**
+ * pgvector configuration options.
+ */
+export interface PGVectorConfig {
+    /**
+     * Vector dimensions.
+     * @default 1536 (OpenAI text-embedding-3-small)
+     */
+    dimensions?: number;
+    /**
+     * Distance metric for similarity search.
+     * @default "cosine"
+     */
+    similarity?: VectorSimilarity;
+}
+/**
+ * Resolved vector configuration with defaults applied.
+ */
+export interface ResolvedVectorConfig {
+    dimensions: number;
+    similarity: VectorSimilarity;
+}
+/**
+ * Default vector configuration.
+ */
+export declare const DEFAULT_VECTOR_CONFIG: ResolvedVectorConfig;
+/**
+ * Resolve vector config, applying defaults.
+ */
+export declare function resolveVectorConfig(config: boolean | PGVectorConfig | undefined): ResolvedVectorConfig | undefined;
 /**
  * PostgreSQL storage configuration.
  */
@@ -9,14 +44,41 @@ export interface PGStorageConfig {
      * Pool instance for database connections.
      */
     pool: Pool;
+    /**
+     * Enable pgvector support for semantic search.
+     *
+     * - `true`: Use default config (1536 dimensions, cosine similarity)
+     * - `PGVectorConfig`: Custom dimensions and similarity metric
+     *
+     * Requires pgvector extension to be installed by superuser:
+     * ```sql
+     * CREATE EXTENSION IF NOT EXISTS vector;
+     * ```
+     */
+    vector?: boolean | PGVectorConfig;
 }
 /**
  * PostgreSQL storage adapter.
+ *
+ * Storage is lazily initialized on first use via `ensureInit()`. This means
+ * callers don't need to explicitly call `init()` - it happens automatically.
+ *
+ * NOTE: If the number of store methods grows significantly, consider replacing
+ * the manual `ensureInit()` calls with a Proxy-based wrapper for foolproof
+ * auto-initialization.
  */
 export declare class PGStorage implements KernlStorage {
     private pool;
+    private initPromise;
     threads: PGThreadStore;
+    memories: PGMemoryStore;
     constructor(config: PGStorageConfig);
+    /**
+     * Ensure storage is initialized before any operation.
+     *
+     * Safe to call multiple times - initialization only runs once.
+     */
+    private ensureInit;
     /**
      * Bind runtime registries to storage.
      */

package/dist/storage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAc,MAAM,IAAI,CAAC;AAK3C,OAAO,KAAK,EACV,aAAa,EACb,aAAa,EACb,YAAY,EACZ,WAAW,EACZ,MAAM,OAAO,CAAC;AAIf,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAI/C;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B;;OAEG;IACH,IAAI,EAAE,IAAI,CAAC;CACZ;AAED;;GAEG;AACH,qBAAa,SAAU,YAAW,YAAY;IAC5C,OAAO,CAAC,IAAI,CAAO;IAEnB,OAAO,EAAE,aAAa,CAAC;gBAEX,MAAM,EAAE,eAAe;IAKnC;;OAEG;IACH,IAAI,CAAC,UAAU,EAAE;QAAE,MAAM,EAAE,aAAa,CAAC;QAAC,MAAM,EAAE,aAAa,CAAA;KAAE,GAAG,IAAI;IAIxE;;OAEG;IACG,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAIrE;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAM3B;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAyC9B;;OAEG;YACW,WAAW;IAUzB;;OAEG;YACW,YAAY;IA6F1B;;OAEG;YACW,UAAU;IAMxB;;OAEG;YACW,UAAU;IAIxB;;OAEG;YACW,SAAS;IAIvB;;OAEG;YACW,WAAW;CAkB1B"}
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAc,MAAM,IAAI,CAAC;AAG3C,OAAO,KAAK,EACV,aAAa,EACb,aAAa,EACb,YAAY,EACZ,WAAW,EACZ,MAAM,OAAO,CAAC;AAMf,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAI/C;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,WAAW,GAAG,aAAa,CAAC;AAEtE;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,UAAU,CAAC,EAAE,gBAAgB,CAAC;CAC/B;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,gBAAgB,CAAC;CAC9B;AAED;;GAEG;AACH,eAAO,MAAM,qBAAqB,EAAE,oBAGnC,CAAC;AAEF;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,OAAO,GAAG,cAAc,GAAG,SAAS,GAC3C,oBAAoB,GAAG,SAAS,CAOlC;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B;;OAEG;IACH,IAAI,EAAE,IAAI,CAAC;IAEX;;;;;;;;;;OAUG;IACH,MAAM,CAAC,EAAE,OAAO,GAAG,cAAc,CAAC;CACnC;AAED;;;;;;;;;GASG;AACH,qBAAa,SAAU,YAAW,YAAY;IAC5C,OAAO,CAAC,IAAI,CAAO;IACnB,OAAO,CAAC,WAAW,CAA8B;IAEjD,OAAO,EAAE,aAAa,CAAC;IACvB,QAAQ,EAAE,aAAa,CAAC;gBAEZ,MAAM,EAAE,eAAe;IAMnC;;;;OAIG;YACW,UAAU;IAUxB;;OAEG;IACH,IAAI,CAAC,UAAU,EAAE;QAAE,MAAM,EAAE,aAAa,CAAC;QAAC,MAAM,EAAE,aAAa,CAAA;KAAE,GAAG,IAAI;IAIxE;;OAEG;IACG,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAIrE;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAM3B;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAyC9B;;OAEG;YACW,WAAW;IAUzB;;OAEG;YACW,YAAY;IA6F1B;;OAEG;YACW,UAAU;IAMxB;;OAEG;YACW,UAAU;IAIxB;;OAEG;YACW,SAAS;IAIvB;;OAEG;YACW,WAAW;CAkB1B"}