@mirk/store 0.4.1

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 David Robinson
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,108 @@
+# @mirk/store
+
+Code-split storage **ports** + source **adapters** under one namespace. Import the whole
+namespace, or just the specific subpath you need — the interface ports and their in-memory
+reference implementations are zero-native, and only the SQLite adapter references native
+bindings (as optional peers).
+
+ESM-only (the package exposes `import` entry points; there is no CommonJS build).
+
+## Install
+
+```bash
+npm install @mirk/store
+# Using the SQLite adapter (@mirk/store/sqlite)? Add its peer:
+npm install better-sqlite3
+# Optional: vec0 KNN acceleration (graceful exact-JS fallback without it)
+npm install sqlite-vec
+```
+
+## Subpaths
+
+| Import | What it gives you | Native deps |
+|---|---|---|
+| `@mirk/store` | the ports + their in-memory references + `toAsync` + cosine helpers | none |
+| `@mirk/store/kv` | `SyncStore` port (key-value + collections), `InMemoryKv`, `toAsync` | none |
+| `@mirk/store/vector` | `VectorStore` port, `InMemoryVectorStore`, cosine helpers | none |
+| `@mirk/store/sqlite` | the SQLite **source adapter** — one connection, `.kv` + `.vector` facets | `better-sqlite3` (peer), `sqlite-vec` (optional peer) |
+
+Source adapters are reached **only** through their own subpath (e.g. `/sqlite`) — the root and the
+port subpaths never re-export them, so importing `@mirk/store`, `/kv`, or `/vector` never drags a
+native binding into a consumer bundle.
+
+## Quickstart — zero native deps
+
+The in-memory references implement the same ports as the backends, so you can build against them
+with nothing installed:
+
+```ts
+import { InMemoryKv, toAsync } from "@mirk/store/kv";
+
+const kv = new InMemoryKv();
+kv.set("user:1", { name: "Ada" });
+kv.get<{ name: string }>("user:1");   // { name: "Ada" }
+kv.keys("user:");                      // ["user:1"]
+
+// Lift any SyncStore to a Promise-returning API (one-way: sync ⊂ async):
+const asyncKv = toAsync(kv);
+await asyncKv.get("user:1");
+```
+
+### Collections
+
+A `SyncStore` is also a small document store, keyed by `id`:
+
+```ts
+kv.put("posts", { id: "p1", title: "Hello", pinned: true });
+kv.getById("posts", "p1");                       // { id: "p1", title: "Hello", pinned: true }
+kv.list("posts", { where: { pinned: true }, sortBy: "title", limit: 10 });
+kv.count("posts");                               // 1
+kv.remove("posts", "p1");
+```
+
+## SQLite adapter — one connection, many capabilities
+
+`SqliteAdapter` opens a single `better-sqlite3` database and exposes a `.kv` facet (a `SyncStore`)
+and a `.vector` facet (a `VectorStore`) over it:
+
+```ts
+import { SqliteAdapter } from "@mirk/store/sqlite";
+
+// `dimensions` is required to use the .vector facet; .kv works without it.
+const db = new SqliteAdapter({ path: "data.db", dimensions: 768 });
+
+db.kv.set("user:1", { name: "Ada" });
+
+const embedding = new Float32Array(768); // your real embedding here
+const query = new Float32Array(768);
+db.vector.upsert("docs", { id: "a", vector: embedding });
+const results = db.vector.search("docs", query, { topK: 10 }); // ranked by cosine
+
+db.close();
+```
+
+### `SqliteAdapter` options
+
+| Option | Type | Notes |
+|---|---|---|
+| `path` | `string` | DB file path, or `":memory:"`. |
+| `db` | `Database` | Reuse an existing `better-sqlite3` connection instead of opening one. |
+| `dimensions` | `number` | Embedding dimensionality. Required before using `.vector`; persisted and enforced on reopen. |
+| `forceJsCosine` | `boolean` | Pin the exact JS-cosine path even when `sqlite-vec` is installed (mainly for tests). |
+
+Vectors (`Vector` is a `Float32Array`) are stored as little-endian float32 BLOBs and ranked by
+**exact cosine**. When the optional `sqlite-vec` peer is installed, search is transparently
+accelerated by vec0 using the `cosine` distance metric, so rankings are identical to the JS path;
+without it, the exact JS-cosine fallback runs. `db.vector.meta.accelerated` reports which path is
+live.
+
+## Sync by design
+
+Embedded backends are **synchronous** — `better-sqlite3` is synchronous, and an async-everywhere
+interface would tax every local call with a Promise it doesn't need. A `SyncStore` lifts to an
+async API via `toAsync(store)`; the reverse is impossible. Pick sync for embedded/local, and reach
+for async only where a remote backend genuinely requires it.
+
+## License
+
+Apache-2.0 © David Robinson

package/dist/adapters/sqlite.d.ts

@@ -0,0 +1,27 @@
+import Database from 'better-sqlite3';
+import { b as SyncStore } from '../types-DyQLNtxa.js';
+import { d as VectorStore } from '../types-BqSZEMAB.js';
+
+interface SqliteAdapterOptions {
+    /** Path to the SQLite database file. Use ":memory:" for in-memory. */
+    path: string;
+    /** Existing better-sqlite3 instance to reuse (shares one connection). */
+    db?: Database.Database;
+    /** Embedding dimensions. Required to use the `.vector` facet; KV works without it. */
+    dimensions?: number;
+    /** Force the exact JS-cosine search path even when sqlite-vec is installed.
+     *  Mainly for parity testing; production should leave this off. */
+    forceJsCosine?: boolean;
+}
+/** Multi-capability sqlite source adapter. Open once; use `.kv` and/or `.vector`
+ *  — both ride the same connection. */
+declare class SqliteAdapter {
+    private readonly db;
+    readonly kv: SyncStore;
+    readonly vector: VectorStore;
+    constructor(opts: SqliteAdapterOptions);
+    /** Close the underlying connection (shared by both facets). */
+    close(): void;
+}
+
+export { SqliteAdapter, type SqliteAdapterOptions };

package/dist/adapters/sqlite.js

@@ -0,0 +1,382 @@
+import {
+  assertDimensions,
+  bufferToVector,
+  cosineSimilarity,
+  vectorToBuffer
+} from "../chunk-GC4MYP45.js";
+
+// src/adapters/sqlite.ts
+import Database from "better-sqlite3";
+import { createRequire } from "module";
+var nodeRequire = createRequire(import.meta.url);
+function tryLoadSqliteVec(db) {
+  try {
+    const vec = nodeRequire("sqlite-vec");
+    if (typeof vec.load === "function") {
+      vec.load(db);
+      return true;
+    }
+    if (typeof vec.getLoadablePath === "function") {
+      db.loadExtension(vec.getLoadablePath());
+      return true;
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
+function isUsableVector(v) {
+  let nonZero = false;
+  for (let i = 0; i < v.length; i++) {
+    const x = v[i] ?? 0;
+    if (!Number.isFinite(x)) return false;
+    if (x !== 0) nonZero = true;
+  }
+  return nonZero;
+}
+var SqliteAdapter = class {
+  db;
+  kv;
+  vector;
+  constructor(opts) {
+    const ownsDb = opts.db === void 0;
+    this.db = opts.db ?? new Database(opts.path);
+    try {
+      this.db.pragma("journal_mode = WAL");
+      this.kv = new SqliteKvFacet(this.db);
+      this.vector = new SqliteVectorFacet(this.db, opts.path, opts.dimensions, opts.forceJsCosine);
+    } catch (err) {
+      if (ownsDb) {
+        try {
+          this.db.close();
+        } catch {
+        }
+      }
+      throw err;
+    }
+  }
+  /** Close the underlying connection (shared by both facets). */
+  close() {
+    this.db.close();
+  }
+};
+var SqliteKvFacet = class {
+  constructor(db) {
+    this.db = db;
+    this.db.pragma("foreign_keys = ON");
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS _kv (
+        key TEXT PRIMARY KEY,
+        value TEXT NOT NULL,
+        created_at TEXT DEFAULT (datetime('now')),
+        updated_at TEXT DEFAULT (datetime('now'))
+      )
+    `);
+  }
+  db;
+  meta = { backend: "sqlite" };
+  initializedTables = /* @__PURE__ */ new Set();
+  tableName(collection) {
+    if (collection.length === 0) throw new Error("Invalid collection name");
+    const sanitized = collection.replace(/[^a-zA-Z0-9_]/g, "_");
+    return `c_${sanitized}_${hashName(collection)}`;
+  }
+  ensureTable(collection) {
+    const table = this.tableName(collection);
+    if (this.initializedTables.has(table)) return table;
+    this.db.exec(
+      `CREATE TABLE IF NOT EXISTS ${table} (
+        id TEXT PRIMARY KEY,
+        data JSON NOT NULL,
+        created_at TEXT DEFAULT (datetime('now')),
+        updated_at TEXT DEFAULT (datetime('now'))
+      )`
+    );
+    this.initializedTables.add(table);
+    return table;
+  }
+  get(key) {
+    const row = this.db.prepare("SELECT value FROM _kv WHERE key = ?").get(key);
+    if (!row) return null;
+    return JSON.parse(row.value);
+  }
+  set(key, value) {
+    this.db.prepare(
+      `INSERT INTO _kv (key, value, updated_at) VALUES (?, ?, datetime('now'))
+         ON CONFLICT(key) DO UPDATE SET value = excluded.value, updated_at = datetime('now')`
+    ).run(key, JSON.stringify(value));
+  }
+  has(key) {
+    return this.db.prepare("SELECT 1 FROM _kv WHERE key = ?").get(key) !== void 0;
+  }
+  delete(key) {
+    return this.db.prepare("DELETE FROM _kv WHERE key = ?").run(key).changes > 0;
+  }
+  keys(prefix) {
+    if (prefix) {
+      const escaped = prefix.replace(/[\\%_]/g, (c) => `\\${c}`);
+      const rows2 = this.db.prepare(`SELECT key FROM _kv WHERE key LIKE ? ESCAPE '\\' ORDER BY key`).all(`${escaped}%`);
+      return rows2.map((r) => r.key);
+    }
+    const rows = this.db.prepare("SELECT key FROM _kv ORDER BY key").all();
+    return rows.map((r) => r.key);
+  }
+  list(collection, filter) {
+    const table = this.ensureTable(collection);
+    const where = buildWhereClause(filter);
+    const orderBy = buildOrderBy(filter);
+    const limitOffset = buildLimitOffset(filter);
+    const sql = `SELECT data FROM ${table}${where.clause}${orderBy.clause}${limitOffset}`;
+    const rows = this.db.prepare(sql).all(...where.params, ...orderBy.params);
+    return rows.map((r) => JSON.parse(r.data));
+  }
+  getById(collection, id) {
+    const table = this.ensureTable(collection);
+    const row = this.db.prepare(`SELECT data FROM ${table} WHERE id = ?`).get(id);
+    if (!row) return null;
+    return JSON.parse(row.data);
+  }
+  put(collection, item) {
+    const table = this.ensureTable(collection);
+    this.db.prepare(
+      `INSERT INTO ${table} (id, data, updated_at) VALUES (?, ?, datetime('now'))
+         ON CONFLICT(id) DO UPDATE SET data = excluded.data, updated_at = datetime('now')`
+    ).run(item.id, JSON.stringify(item));
+    return item;
+  }
+  remove(collection, id) {
+    const table = this.ensureTable(collection);
+    return this.db.prepare(`DELETE FROM ${table} WHERE id = ?`).run(id).changes > 0;
+  }
+  count(collection, filter) {
+    const table = this.ensureTable(collection);
+    const where = buildWhereClause(filter);
+    const row = this.db.prepare(`SELECT COUNT(*) as cnt FROM ${table}${where.clause}`).get(...where.params);
+    return row.cnt;
+  }
+};
+var SqliteVectorFacet = class {
+  constructor(db, path, dimensions, forceJsCosine) {
+    this.db = db;
+    this.db.exec(
+      `CREATE TABLE IF NOT EXISTS vectors (
+         collection TEXT NOT NULL,
+         id TEXT NOT NULL,
+         vec BLOB NOT NULL,
+         metadata TEXT,
+         PRIMARY KEY (collection, id)
+       );
+       CREATE INDEX IF NOT EXISTS vectors_collection ON vectors(collection);
+       CREATE TABLE IF NOT EXISTS _vec_meta (key TEXT PRIMARY KEY, value TEXT NOT NULL);`
+    );
+    const stored = this.db.prepare(`SELECT value FROM _vec_meta WHERE key = 'dimensions'`).get();
+    if (stored) {
+      this.dimensions = Number(stored.value);
+      if (dimensions !== void 0 && dimensions !== this.dimensions) {
+        throw new Error(
+          `Vector store at ${path} was created with ${this.dimensions} dimensions, opened with ${dimensions}.`
+        );
+      }
+    } else if (dimensions !== void 0) {
+      this.dimensions = dimensions;
+      this.db.prepare(`INSERT INTO _vec_meta (key, value) VALUES ('dimensions', ?)`).run(String(dimensions));
+    } else {
+      this.dimensions = -1;
+    }
+    this.accelerated = !forceJsCosine && this.dimensions >= 0 && tryLoadSqliteVec(this.db);
+    this.meta = {
+      backend: "sqlite",
+      dimensions: Math.max(this.dimensions, 0),
+      accelerated: this.accelerated
+    };
+  }
+  db;
+  meta;
+  dimensions;
+  /** True when sqlite-vec loaded and the vec0 acceleration path is live. */
+  accelerated;
+  vecTablesEnsured = /* @__PURE__ */ new Set();
+  requireDims(v) {
+    if (this.dimensions < 0) {
+      throw new Error("SqliteAdapter.vector requires `dimensions` \u2014 pass { dimensions } when opening.");
+    }
+    assertDimensions(v, this.dimensions);
+  }
+  // ── vec0 acceleration helpers ───────────────────────────────────────────
+  vecTableName(collection) {
+    return `vectors_vec_${collection.replace(/[^a-zA-Z0-9_]/g, "_")}_${hashName(collection)}`;
+  }
+  ensureVecTable(collection) {
+    const table = this.vecTableName(collection);
+    if (this.vecTablesEnsured.has(table)) return table;
+    this.db.exec(
+      `CREATE VIRTUAL TABLE IF NOT EXISTS ${table} USING vec0(embedding float[${this.dimensions}] distance_metric=cosine)`
+    );
+    this.vecTablesEnsured.add(table);
+    const existing = this.db.prepare(`SELECT rowid, vec FROM vectors WHERE collection = ?`).all(collection);
+    if (existing.length > 0) {
+      const del = this.db.prepare(`DELETE FROM ${table} WHERE rowid = ?`);
+      const ins = this.db.prepare(`INSERT INTO ${table}(rowid, embedding) VALUES (?, ?)`);
+      const backfill = this.db.transaction(() => {
+        for (const r of existing) {
+          const rid = BigInt(r.rowid);
+          del.run(rid);
+          if (isUsableVector(bufferToVector(r.vec))) ins.run(rid, r.vec);
+        }
+      });
+      backfill();
+    }
+    return table;
+  }
+  /** Keep a (collection,id)'s vec0 row in sync. vec0 is keyed by the vectors row's
+   *  rowid (stable under ON CONFLICT DO UPDATE); the rowid binds as BigInt. */
+  syncVec(collection, id, vector) {
+    const table = this.ensureVecTable(collection);
+    const row = this.db.prepare(`SELECT rowid FROM vectors WHERE collection = ? AND id = ?`).get(collection, id);
+    if (!row) return;
+    const rid = BigInt(row.rowid);
+    this.db.prepare(`DELETE FROM ${table} WHERE rowid = ?`).run(rid);
+    if (isUsableVector(vector)) {
+      this.db.prepare(`INSERT INTO ${table}(rowid, embedding) VALUES (?, ?)`).run(rid, vectorToBuffer(vector));
+    }
+  }
+  upsert(collection, doc) {
+    this.requireDims(doc.vector);
+    const write = this.db.transaction(() => {
+      this.db.prepare(
+        `INSERT INTO vectors(collection, id, vec, metadata) VALUES (?, ?, ?, ?)
+           ON CONFLICT(collection, id) DO UPDATE SET vec = excluded.vec, metadata = excluded.metadata`
+      ).run(
+        collection,
+        doc.id,
+        vectorToBuffer(doc.vector),
+        doc.metadata === void 0 ? null : JSON.stringify(doc.metadata)
+      );
+      if (this.accelerated) this.syncVec(collection, doc.id, doc.vector);
+    });
+    write();
+  }
+  upsertMany(collection, docs) {
+    const tx = this.db.transaction((items) => {
+      for (const doc of items) this.upsert(collection, doc);
+    });
+    tx(docs);
+  }
+  get(collection, id) {
+    const row = this.db.prepare(`SELECT id, vec, metadata FROM vectors WHERE collection = ? AND id = ?`).get(collection, id);
+    if (!row) return null;
+    return {
+      id: row.id,
+      vector: bufferToVector(row.vec),
+      metadata: row.metadata === null ? void 0 : JSON.parse(row.metadata)
+    };
+  }
+  remove(collection, id) {
+    if (this.accelerated) {
+      const row = this.db.prepare(`SELECT rowid FROM vectors WHERE collection = ? AND id = ?`).get(collection, id);
+      if (row) {
+        this.db.prepare(`DELETE FROM ${this.ensureVecTable(collection)} WHERE rowid = ?`).run(BigInt(row.rowid));
+      }
+    }
+    return this.db.prepare(`DELETE FROM vectors WHERE collection = ? AND id = ?`).run(collection, id).changes > 0;
+  }
+  count(collection) {
+    const row = this.db.prepare(`SELECT COUNT(*) AS n FROM vectors WHERE collection = ?`).get(collection);
+    return row.n;
+  }
+  search(collection, query, opts) {
+    this.requireDims(query);
+    const topK = opts?.topK ?? 10;
+    const minScore = opts?.minScore;
+    if (this.accelerated && isUsableVector(query)) {
+      try {
+        return this.searchVec(collection, query, topK, minScore);
+      } catch {
+      }
+    }
+    return this.searchJs(collection, query, topK, minScore);
+  }
+  searchVec(collection, query, topK, minScore) {
+    const table = this.ensureVecTable(collection);
+    const rows = this.db.prepare(
+      `SELECT v.id AS id, v.metadata AS metadata, vv.distance AS distance
+         FROM ${table} vv JOIN vectors v ON v.rowid = vv.rowid
+         WHERE vv.embedding MATCH ? ORDER BY vv.distance LIMIT ?`
+    ).all(vectorToBuffer(query), topK);
+    const out = [];
+    for (const r of rows) {
+      if (r.distance === null) continue;
+      const score = 1 - r.distance;
+      if (!Number.isFinite(score)) continue;
+      if (minScore !== void 0 && score < minScore) continue;
+      out.push({
+        id: r.id,
+        score,
+        metadata: r.metadata === null ? void 0 : JSON.parse(r.metadata)
+      });
+    }
+    out.sort((a, b) => b.score - a.score || a.id.localeCompare(b.id));
+    return out;
+  }
+  searchJs(collection, query, topK, minScore) {
+    const rows = this.db.prepare(`SELECT id, vec, metadata FROM vectors WHERE collection = ?`).all(collection);
+    const scored = [];
+    for (const row of rows) {
+      const vec = bufferToVector(row.vec);
+      if (!isUsableVector(vec)) continue;
+      const score = cosineSimilarity(query, vec);
+      if (!Number.isFinite(score)) continue;
+      if (minScore !== void 0 && score < minScore) continue;
+      scored.push({
+        id: row.id,
+        score,
+        metadata: row.metadata === null ? void 0 : JSON.parse(row.metadata)
+      });
+    }
+    scored.sort((a, b) => b.score - a.score || a.id.localeCompare(b.id));
+    return scored.slice(0, topK);
+  }
+};
+function buildWhereClause(filter) {
+  if (!filter?.where || Object.keys(filter.where).length === 0) {
+    return { clause: "", params: [] };
+  }
+  const conditions = [];
+  const params = [];
+  for (const [key, value] of Object.entries(filter.where)) {
+    conditions.push(`json_extract(data, '$.' || ?) = ?`);
+    const bound = typeof value === "boolean" ? value ? 1 : 0 : value;
+    params.push(key, bound);
+  }
+  return { clause: ` WHERE ${conditions.join(" AND ")}`, params };
+}
+function buildOrderBy(filter) {
+  if (!filter?.sortBy) return { clause: "", params: [] };
+  const dir = filter.sortDir === "desc" ? "DESC" : "ASC";
+  return {
+    clause: ` ORDER BY json_extract(data, '$.' || ?) IS NULL, json_extract(data, '$.' || ?) ${dir}`,
+    params: [filter.sortBy, filter.sortBy]
+  };
+}
+function hashName(s) {
+  let h = 2166136261;
+  for (let i = 0; i < s.length; i++) {
+    h ^= s.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return (h >>> 0).toString(36);
+}
+function buildLimitOffset(filter) {
+  let sql = "";
+  if (filter?.limit !== void 0) {
+    sql += ` LIMIT ${Math.max(0, Math.floor(filter.limit))}`;
+  }
+  if (filter?.offset !== void 0 && filter.offset > 0) {
+    if (!sql.includes("LIMIT")) sql += " LIMIT -1";
+    sql += ` OFFSET ${Math.max(0, Math.floor(filter.offset))}`;
+  }
+  return sql;
+}
+export {
+  SqliteAdapter
+};

package/dist/chunk-GC4MYP45.js

@@ -0,0 +1,43 @@
+// src/vector/cosine.ts
+function cosineSimilarity(a, b) {
+  if (a.length !== b.length) return 0;
+  let dot = 0;
+  let an = 0;
+  let bn = 0;
+  for (let i = 0; i < a.length; i++) {
+    const av = a[i] ?? 0;
+    const bv = b[i] ?? 0;
+    dot += av * bv;
+    an += av * av;
+    bn += bv * bv;
+  }
+  if (an === 0 || bn === 0) return 0;
+  return dot / (Math.sqrt(an) * Math.sqrt(bn));
+}
+function vectorToBuffer(vec) {
+  const buf = Buffer.allocUnsafe(vec.length * 4);
+  for (let i = 0; i < vec.length; i++) {
+    buf.writeFloatLE(vec[i] ?? 0, i * 4);
+  }
+  return buf;
+}
+function bufferToVector(buf) {
+  const b = buf instanceof Buffer ? buf : Buffer.from(buf);
+  const out = new Float32Array(Math.floor(b.byteLength / 4));
+  for (let i = 0; i < out.length; i++) {
+    out[i] = b.readFloatLE(i * 4);
+  }
+  return out;
+}
+function assertDimensions(vector, dimensions) {
+  if (vector.length !== dimensions) {
+    throw new Error(`Vector dimension mismatch: expected ${dimensions}, got ${vector.length}`);
+  }
+}
+
+export {
+  cosineSimilarity,
+  vectorToBuffer,
+  bufferToVector,
+  assertDimensions
+};

package/dist/chunk-ZFSKQHBT.js

@@ -0,0 +1,62 @@
+import {
+  assertDimensions,
+  cosineSimilarity
+} from "./chunk-GC4MYP45.js";
+
+// src/vector/memory.ts
+var InMemoryVectorStore = class {
+  meta;
+  dimensions;
+  collections = /* @__PURE__ */ new Map();
+  constructor(opts) {
+    this.dimensions = opts.dimensions;
+    this.meta = { backend: "memory", dimensions: opts.dimensions, accelerated: false };
+  }
+  upsert(collection, doc) {
+    assertDimensions(doc.vector, this.dimensions);
+    this.collectionFor(collection).set(doc.id, doc);
+  }
+  upsertMany(collection, docs) {
+    for (const doc of docs) assertDimensions(doc.vector, this.dimensions);
+    const coll = this.collectionFor(collection);
+    for (const doc of docs) coll.set(doc.id, doc);
+  }
+  get(collection, id) {
+    const doc = this.collections.get(collection)?.get(id);
+    return doc ?? null;
+  }
+  remove(collection, id) {
+    return this.collections.get(collection)?.delete(id) ?? false;
+  }
+  count(collection) {
+    return this.collections.get(collection)?.size ?? 0;
+  }
+  search(collection, query, opts) {
+    assertDimensions(query, this.dimensions);
+    const topK = opts?.topK ?? 10;
+    const minScore = opts?.minScore;
+    const coll = this.collections.get(collection);
+    if (!coll) return [];
+    const scored = [];
+    for (const doc of coll.values()) {
+      const score = cosineSimilarity(query, doc.vector);
+      if (!Number.isFinite(score)) continue;
+      if (minScore !== void 0 && score < minScore) continue;
+      scored.push({ id: doc.id, score, metadata: doc.metadata });
+    }
+    scored.sort((a, b) => b.score - a.score);
+    return scored.slice(0, topK);
+  }
+  collectionFor(name) {
+    let coll = this.collections.get(name);
+    if (!coll) {
+      coll = /* @__PURE__ */ new Map();
+      this.collections.set(name, coll);
+    }
+    return coll;
+  }
+};
+
+export {
+  InMemoryVectorStore
+};

package/dist/chunk-ZI4JA6IU.js

@@ -0,0 +1,148 @@
+// src/to-async.ts
+var AsyncStoreAdapter = class {
+  constructor(sync) {
+    this.sync = sync;
+  }
+  sync;
+  get meta() {
+    return this.sync.meta;
+  }
+  async get(key) {
+    return this.sync.get(key);
+  }
+  async set(key, value) {
+    this.sync.set(key, value);
+  }
+  async has(key) {
+    return this.sync.has(key);
+  }
+  async delete(key) {
+    return this.sync.delete(key);
+  }
+  async keys(prefix) {
+    return this.sync.keys(prefix);
+  }
+  async list(collection, filter) {
+    return this.sync.list(collection, filter);
+  }
+  async getById(collection, id) {
+    return this.sync.getById(collection, id);
+  }
+  async put(collection, item) {
+    return this.sync.put(collection, item);
+  }
+  async remove(collection, id) {
+    return this.sync.remove(collection, id);
+  }
+  async count(collection, filter) {
+    return this.sync.count(collection, filter);
+  }
+};
+function toAsync(store) {
+  return new AsyncStoreAdapter(store);
+}
+
+// src/backends/memory.ts
+var InMemoryStore = class {
+  meta = {
+    backend: "memory"
+  };
+  /** Key-value storage. */
+  kv = /* @__PURE__ */ new Map();
+  /** Collection storage: collection name -> Map of id -> item. */
+  collections = /* @__PURE__ */ new Map();
+  // ── Key-Value ──────────────────────────────────────────────────────
+  get(key) {
+    const value = this.kv.get(key);
+    return value !== void 0 ? value : null;
+  }
+  set(key, value) {
+    this.kv.set(key, value);
+  }
+  has(key) {
+    return this.kv.has(key);
+  }
+  delete(key) {
+    return this.kv.delete(key);
+  }
+  keys(prefix) {
+    const allKeys = [...this.kv.keys()];
+    if (!prefix) return allKeys;
+    return allKeys.filter((k) => k.startsWith(prefix));
+  }
+  // ── Collections ────────────────────────────────────────────────────
+  ensureCollection(name) {
+    let col = this.collections.get(name);
+    if (!col) {
+      col = /* @__PURE__ */ new Map();
+      this.collections.set(name, col);
+    }
+    return col;
+  }
+  list(collection, filter) {
+    const col = this.ensureCollection(collection);
+    let items = [...col.values()];
+    items = applyFilter(items, filter);
+    return items;
+  }
+  getById(collection, id) {
+    const col = this.ensureCollection(collection);
+    const item = col.get(id);
+    return item !== void 0 ? item : null;
+  }
+  put(collection, item) {
+    const col = this.ensureCollection(collection);
+    col.set(item.id, item);
+    return item;
+  }
+  remove(collection, id) {
+    const col = this.ensureCollection(collection);
+    return col.delete(id);
+  }
+  count(collection, filter) {
+    const col = this.ensureCollection(collection);
+    if (!filter?.where) return col.size;
+    const items = [...col.values()];
+    return applyFilter(items, filter).length;
+  }
+};
+function matchesWhere(item, where) {
+  if (typeof item !== "object" || item === null) return false;
+  const record = item;
+  for (const [key, value] of Object.entries(where)) {
+    if (record[key] !== value) return false;
+  }
+  return true;
+}
+function applyFilter(items, filter) {
+  if (!filter) return items;
+  let result = items;
+  if (filter.where) {
+    const where = filter.where;
+    result = result.filter((item) => matchesWhere(item, where));
+  }
+  if (filter.sortBy) {
+    const field = filter.sortBy;
+    const dir = filter.sortDir === "desc" ? -1 : 1;
+    result = [...result].sort((a, b) => {
+      const aVal = a[field];
+      const bVal = b[field];
+      if (aVal === bVal) return 0;
+      if (aVal === void 0 || aVal === null) return 1;
+      if (bVal === void 0 || bVal === null) return -1;
+      return aVal < bVal ? -1 * dir : 1 * dir;
+    });
+  }
+  if (filter.offset !== void 0 && filter.offset > 0) {
+    result = result.slice(filter.offset);
+  }
+  if (filter.limit !== void 0 && filter.limit >= 0) {
+    result = result.slice(0, filter.limit);
+  }
+  return result;
+}
+
+export {
+  toAsync,
+  InMemoryStore
+};

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { A as AsyncStore, S as StoreFilter, a as StoreMeta, b as SyncStore } from './types-DyQLNtxa.js';
+export { InMemoryKv, toAsync } from './kv.js';
+export { V as Vector, a as VectorDocument, b as VectorSearchOptions, c as VectorSearchResult, d as VectorStore, e as VectorStoreMeta } from './types-BqSZEMAB.js';
+export { InMemoryVectorStore, assertDimensions, bufferToVector, cosineSimilarity, vectorToBuffer } from './vector.js';

package/dist/index.js

@@ -0,0 +1,22 @@
+import {
+  InMemoryStore,
+  toAsync
+} from "./chunk-ZI4JA6IU.js";
+import {
+  InMemoryVectorStore
+} from "./chunk-ZFSKQHBT.js";
+import {
+  assertDimensions,
+  bufferToVector,
+  cosineSimilarity,
+  vectorToBuffer
+} from "./chunk-GC4MYP45.js";
+export {
+  InMemoryStore as InMemoryKv,
+  InMemoryVectorStore,
+  assertDimensions,
+  bufferToVector,
+  cosineSimilarity,
+  toAsync,
+  vectorToBuffer
+};

package/dist/kv.d.ts

@@ -0,0 +1,28 @@
+import { b as SyncStore, A as AsyncStore, a as StoreMeta, S as StoreFilter } from './types-DyQLNtxa.js';
+
+/** Lift a synchronous store to the {@link AsyncStore} interface. The bridge only
+ *  goes this direction — sync ⊂ async. */
+declare function toAsync(store: SyncStore): AsyncStore;
+
+declare class InMemoryStore implements SyncStore {
+    readonly meta: StoreMeta;
+    /** Key-value storage. */
+    private kv;
+    /** Collection storage: collection name -> Map of id -> item. */
+    private collections;
+    get<T>(key: string): T | null;
+    set<T>(key: string, value: T): void;
+    has(key: string): boolean;
+    delete(key: string): boolean;
+    keys(prefix?: string): string[];
+    private ensureCollection;
+    list<T>(collection: string, filter?: StoreFilter): T[];
+    getById<T>(collection: string, id: string): T | null;
+    put<T extends {
+        id: string;
+    }>(collection: string, item: T): T;
+    remove(collection: string, id: string): boolean;
+    count(collection: string, filter?: StoreFilter): number;
+}
+
+export { AsyncStore, InMemoryStore as InMemoryKv, StoreFilter, StoreMeta, SyncStore, toAsync };

package/dist/kv.js

@@ -0,0 +1,8 @@
+import {
+  InMemoryStore,
+  toAsync
+} from "./chunk-ZI4JA6IU.js";
+export {
+  InMemoryStore as InMemoryKv,
+  toAsync
+};

package/dist/types-BqSZEMAB.d.ts

@@ -0,0 +1,57 @@
+/** An embedding. Float32Array — compact, and the on-disk encoding is little-endian
+ *  float32 so vectors stay portable across backends. */
+type Vector = Float32Array;
+interface VectorStoreMeta {
+    /** Backend identifier (e.g. "memory", "sqlite"). */
+    backend: string;
+    /** Embedding dimensions this store is configured for. */
+    dimensions: number;
+    /** True when a native acceleration path (sqlite-vec) is active; false when the
+     *  store does exact JS-side cosine search. Informational — results are the same
+     *  ranking either way, only the speed differs. */
+    accelerated: boolean;
+}
+interface VectorDocument<M extends Record<string, unknown> = Record<string, unknown>> {
+    /** Unique id within the collection. */
+    id: string;
+    /** The embedding. Length must equal the store's configured dimensions. */
+    vector: Vector;
+    /** Typed context stored alongside the vector. Persisted as JSON by disk-backed
+     *  backends, so it must be JSON-serializable; values JSON can't represent
+     *  (`undefined`, functions) are dropped on persistence — don't rely on them. */
+    metadata?: M;
+}
+interface VectorSearchResult<M extends Record<string, unknown> = Record<string, unknown>> {
+    id: string;
+    /** Cosine similarity in [-1, 1]. Higher is more similar. */
+    score: number;
+    metadata?: M;
+}
+interface VectorSearchOptions {
+    /** Maximum results to return. Default: 10. */
+    topK?: number;
+    /** Minimum cosine similarity; results below are excluded. Default: no floor. */
+    minScore?: number;
+}
+/** A synchronous vector similarity store with per-collection documents.
+ *
+ *  All operations are synchronous. Construction may be async for backends that
+ *  load native bindings (see each backend's static `open`); once opened, every
+ *  call is pure sync. */
+interface VectorStore {
+    readonly meta: VectorStoreMeta;
+    /** Insert or replace a document by (collection, id). Throws on dimension mismatch. */
+    upsert<M extends Record<string, unknown> = Record<string, unknown>>(collection: string, doc: VectorDocument<M>): void;
+    /** Insert or replace many documents in one collection. */
+    upsertMany<M extends Record<string, unknown> = Record<string, unknown>>(collection: string, docs: ReadonlyArray<VectorDocument<M>>): void;
+    /** Fetch a document by id, or null. */
+    get<M extends Record<string, unknown> = Record<string, unknown>>(collection: string, id: string): VectorDocument<M> | null;
+    /** Remove a document by id. Returns true if it existed. */
+    remove(collection: string, id: string): boolean;
+    /** Number of documents in a collection. */
+    count(collection: string): number;
+    /** k-nearest-neighbour search by cosine similarity, highest score first. */
+    search<M extends Record<string, unknown> = Record<string, unknown>>(collection: string, query: Vector, opts?: VectorSearchOptions): VectorSearchResult<M>[];
+}
+
+export type { Vector as V, VectorDocument as a, VectorSearchOptions as b, VectorSearchResult as c, VectorStore as d, VectorStoreMeta as e };

package/dist/types-DyQLNtxa.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Metadata about a store instance.
+ */
+interface StoreMeta {
+    /** Backend identifier (e.g., "memory", "sqlite", "surrealdb"). */
+    backend: string;
+}
+/**
+ * Structured filter for collection queries.
+ */
+interface StoreFilter {
+    /** Exact match on fields within the stored item. */
+    where?: Record<string, unknown>;
+    /** Field to sort by. */
+    sortBy?: string;
+    /** Sort direction. Default: 'asc'. */
+    sortDir?: 'asc' | 'desc';
+    /** Maximum number of results. */
+    limit?: number;
+    /** Number of results to skip. */
+    offset?: number;
+}
+/**
+ * A typed key-value + collection store. **Synchronous.**
+ *
+ * Embedded backends (in-memory, sqlite) implement this directly — better-sqlite3
+ * is synchronous, so wrapping it in Promises buys nothing and forecloses sync
+ * consumers. A SyncStore can always be lifted to {@link AsyncStore} via
+ * {@link toAsync}; the reverse is impossible (you can't block on a network call),
+ * which is exactly why sync is the base interface and async is derived from it.
+ */
+interface SyncStore {
+    readonly meta: StoreMeta;
+    /** Get a value by key. Returns null if not found. */
+    get<T>(key: string): T | null;
+    /** Set a value by key. Overwrites if exists. */
+    set<T>(key: string, value: T): void;
+    /** Check if a key exists. */
+    has(key: string): boolean;
+    /** Delete a key. Returns true if the key existed. */
+    delete(key: string): boolean;
+    /** List all keys, optionally filtered by prefix. */
+    keys(prefix?: string): string[];
+    /** Get all items in a collection, with optional filter. */
+    list<T>(collection: string, filter?: StoreFilter): T[];
+    /** Get a single item by ID within a collection. */
+    getById<T>(collection: string, id: string): T | null;
+    /** Create or update an item in a collection. */
+    put<T extends {
+        id: string;
+    }>(collection: string, item: T): T;
+    /** Remove an item from a collection by ID. Returns true if it existed. */
+    remove(collection: string, id: string): boolean;
+    /** Count items in a collection, with optional filter. */
+    count(collection: string, filter?: StoreFilter): number;
+}
+/**
+ * The async face of the same store. **Remote** backends (a future SurrealDB / HTTP
+ * store) implement this natively; embedded sync backends reach it via
+ * {@link toAsync}.
+ *
+ * Hand-written rather than derived from SyncStore via a mapped type, because a
+ * mapped type cannot preserve the per-method generics (`get<T>`, `list<T>`, …) —
+ * `infer` collapses them to `unknown`. The duplication is the price of keeping
+ * the async side fully typed.
+ */
+interface AsyncStore {
+    readonly meta: StoreMeta;
+    get<T>(key: string): Promise<T | null>;
+    set<T>(key: string, value: T): Promise<void>;
+    has(key: string): Promise<boolean>;
+    delete(key: string): Promise<boolean>;
+    keys(prefix?: string): Promise<string[]>;
+    list<T>(collection: string, filter?: StoreFilter): Promise<T[]>;
+    getById<T>(collection: string, id: string): Promise<T | null>;
+    put<T extends {
+        id: string;
+    }>(collection: string, item: T): Promise<T>;
+    remove(collection: string, id: string): Promise<boolean>;
+    count(collection: string, filter?: StoreFilter): Promise<number>;
+}
+
+export type { AsyncStore as A, StoreFilter as S, StoreMeta as a, SyncStore as b };

package/dist/vector.d.ts

@@ -0,0 +1,35 @@
+import { V as Vector, d as VectorStore, e as VectorStoreMeta, a as VectorDocument, b as VectorSearchOptions, c as VectorSearchResult } from './types-BqSZEMAB.js';
+
+/** Cosine similarity in [-1, 1]. Exact. Shared by the in-memory backend and the
+ *  sqlite backend's search path. Returns 0 for length mismatch or a zero vector
+ *  (undefined direction). */
+declare function cosineSimilarity(a: Vector, b: Vector): number;
+/** Encode a vector as a little-endian float32 BLOB. Writes explicit LE (matching
+ *  bufferToVector's readFloatLE), so it is portable across host byte order — and
+ *  into a fresh buffer, so the result never aliases the source's backing memory. */
+declare function vectorToBuffer(vec: Vector): Buffer;
+/** Inverse of vectorToBuffer. */
+declare function bufferToVector(buf: Buffer | Uint8Array): Vector;
+/** Throw if a vector's length doesn't match the store's configured dimensions.
+ *  Shared by every backend so the check and its message live in one place. */
+declare function assertDimensions(vector: Vector, dimensions: number): void;
+
+interface InMemoryVectorStoreOptions {
+    /** Embedding dimensions. All vectors must match this length. */
+    dimensions: number;
+}
+declare class InMemoryVectorStore implements VectorStore {
+    readonly meta: VectorStoreMeta;
+    private readonly dimensions;
+    private readonly collections;
+    constructor(opts: InMemoryVectorStoreOptions);
+    upsert<M extends Record<string, unknown> = Record<string, unknown>>(collection: string, doc: VectorDocument<M>): void;
+    upsertMany<M extends Record<string, unknown> = Record<string, unknown>>(collection: string, docs: ReadonlyArray<VectorDocument<M>>): void;
+    get<M extends Record<string, unknown> = Record<string, unknown>>(collection: string, id: string): VectorDocument<M> | null;
+    remove(collection: string, id: string): boolean;
+    count(collection: string): number;
+    search<M extends Record<string, unknown> = Record<string, unknown>>(collection: string, query: Vector, opts?: VectorSearchOptions): VectorSearchResult<M>[];
+    private collectionFor;
+}
+
+export { InMemoryVectorStore, Vector, VectorDocument, VectorSearchOptions, VectorSearchResult, VectorStore, VectorStoreMeta, assertDimensions, bufferToVector, cosineSimilarity, vectorToBuffer };

package/dist/vector.js

@@ -0,0 +1,16 @@
+import {
+  InMemoryVectorStore
+} from "./chunk-ZFSKQHBT.js";
+import {
+  assertDimensions,
+  bufferToVector,
+  cosineSimilarity,
+  vectorToBuffer
+} from "./chunk-GC4MYP45.js";
+export {
+  InMemoryVectorStore,
+  assertDimensions,
+  bufferToVector,
+  cosineSimilarity,
+  vectorToBuffer
+};

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "@mirk/store",
+  "version": "0.4.1",
+  "type": "module",
+  "description": "Code-split storage ports + source adapters under one namespace. KV + collection store and vector similarity store as interface subpaths; the sqlite source-adapter implements both over one connection.",
+  "license": "Apache-2.0",
+  "author": "David Robinson <dr@monetise.io>",
+  "keywords": [
+    "storage",
+    "key-value",
+    "collection-store",
+    "vector",
+    "vector-search",
+    "similarity",
+    "cosine",
+    "sqlite",
+    "sqlite-vec",
+    "embeddings"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nightwork-dev/mirk.git",
+    "directory": "packages/store"
+  },
+  "homepage": "https://github.com/nightwork-dev/mirk/tree/main/packages/store#readme",
+  "bugs": "https://github.com/nightwork-dev/mirk/issues",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./kv": {
+      "import": "./dist/kv.js",
+      "types": "./dist/kv.d.ts"
+    },
+    "./vector": {
+      "import": "./dist/vector.js",
+      "types": "./dist/vector.d.ts"
+    },
+    "./sqlite": {
+      "import": "./dist/adapters/sqlite.js",
+      "types": "./dist/adapters/sqlite.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "better-sqlite3": "^11.0.0 || ^12.0.0",
+    "sqlite-vec": "^0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "better-sqlite3": {
+      "optional": true
+    },
+    "sqlite-vec": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.0",
+    "better-sqlite3": "^11.0.0",
+    "sqlite-vec": "0.1.9",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0",
+    "tsup": "^8.0.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "build": "rm -rf dist && tsup src/index.ts src/kv.ts src/vector.ts src/adapters/sqlite.ts --format esm --dts --external better-sqlite3 --external sqlite-vec"
+  },
+  "types": "./dist/index.d.ts"
+}