montycat 1.1.4 → 1.1.6

package/README.md

@@ -1,12 +1,33 @@
-# 🚀 Montycat Node.js Client — High-Performance NoSQL for the Async Era
+# 🚀 Montycat for Node.js & TypeScript — The AI-Native NoSQL Database with Semantic Search for RAG & Agents
+
+### Abolish the two-database stack.
+
+The official Node.js & TypeScript SDK for [Montycat](https://montygovernance.com) — a self-hosted **NoSQL + vector database** with AI **semantic search** forged into the core, built for **RAG and AI-agent memory**. One Rust engine, not a sprawl of services. **Your hardware. Your data. Your meaning.**
 
 [![npm version](https://img.shields.io/npm/v/montycat.svg)](https://www.npmjs.com/package/montycat)
 [![npm downloads](https://img.shields.io/npm/dt/montycat.svg)](https://www.npmjs.com/package/montycat)
-[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Docker Pulls](https://img.shields.io/docker/pulls/montygovernance/montycat)](https://hub.docker.com/r/montygovernance/montycat)
 [![Node.js](https://img.shields.io/node/v/montycat.svg)](https://nodejs.org/)
-[![TypeScript](https://img.shields.io/badge/TS-ready-blue.svg)]()
+[![TypeScript](https://img.shields.io/badge/TypeScript-ready-blue.svg)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/MontyGovernance/montycat_node/blob/master/LICENSE)
+
+```typescript
+// Search your data by MEANING — no external APIs, no separate vector database.
+// (already ON by default in the montycat-semantic server edition)
+const hits = await Sales.semanticSearchGetValues({ query: 'something to listen to music without wires', limitOutput: { start: 0, stop: 5 } });
+// → [{ key, score, value: { name: 'Wireless Headphones' } }, ...]  (matched by meaning, not keywords)
+```
+
+> ### 🧩 All-in-one. AI-native. **Zero external dependencies.**
+> The vector-embedding engine runs **inside** the database — **no** separate vector DB, **no** embedding API, **no** API keys, **no** sidecar service. One engine, one binary, your hardware.
+
+## What is Montycat?
+
+For a generation we were told the price of intelligence was two systems: a database for your records, and a separate vector store — with its per-query bill — for their meaning. Montycat rejects that tax. It is a **self-hosted NoSQL + vector database**: one Rust-powered engine with semantic search built in, so **RAG, AI-agent memory, and vector search** live where your data already lives. No cloud lock-in. No ops headache. Decentralized by nature, ultra-fast, and natively async.
 
-Montycat Node.js Client is the official JavaScript and TypeScript SDK for Montycat — the next-generation NoSQL engine built on Data Mesh architecture and written in Rust for blazing-fast performance. It gives Node.js developers the power to work with structured, decentralized, and secure data using a clean, asynchronous API that feels native to JavaScript — not like another bloated driver. Montycat is more than a database — it’s a redefinition of how data should feel in modern, real-time systems.
+Think of it as an **open-source, self-hosted alternative to Pinecone, Weaviate, Chroma, Qdrant, and Redis** — a **vector database _and_ a NoSQL store in a single engine**, so your records and their embeddings live together instead of in two systems you have to keep in sync.
+
+This client gives JavaScript and TypeScript developers structured, decentralized, secure data through a clean async API that feels native to the language — not another bloated driver. Montycat is not an incremental improvement on the databases you know. It is a break with them.
 
 ## 🧭 The Montycat Philosophy
 
@@ -27,6 +48,7 @@ Montycat Node.js Client is the official JavaScript and TypeScript SDK for Montyc
 - 📡 `Real-Time Subscriptions` - Subscribe to keyspace or key changes with live updates.
 - 🔐 `TLS Security` - Encrypted communication and authenticated connections.
 - 🧬 `Schema Support` - Optional schema layer for validation, structure, and type safety.
+- 🧠 `AI Semantic & Vector Search` - Rank stored items by meaning with on-device embeddings. kNN vector search for **RAG, AI agents & LLM apps** — no external API, no separate vector database.
 - 🧱 `Zero Dependencies on ORMs` - No extra abstractions. Just pure, beautiful logic.
 - 🧠 `Easy Integration` - Works with Express, Fastify, Next.js, Deno, and any Node.js runtime.
 
@@ -45,22 +67,37 @@ Montycat Node.js Client is the official JavaScript and TypeScript SDK for Montyc
 
 ## 🏁 The Future Is Structured
 
-Other databases are written in C, C++, or Java.
-`Montycat` was built with Rust — and made accessible to JavaScript / TypeScript.
-No adapters, no legacy baggage — just pure async data flow.
+Other databases were written in C, C++, or Java — for a world that no longer exists.
+`Montycat` was built in Rust and made to speak JavaScript and TypeScript fluently.
+No adapters. No legacy baggage. No permission asked. Just pure async data flow.
+
+The old stack — a database here, a vector store there, an embedding API somewhere in the cloud, and a tangle of sync jobs holding it together — is not an architecture. It is a compromise. Montycat refuses the compromise: **one engine, your hardware, your data, your meaning.**
+
+> **When you use Montycat, you are not querying a database. You are interacting with a living data mesh that speaks your language.**
+
+## 🔍 Example Use Cases
 
-## ⚡ Benchmarks (Node.js)
+- **RAG pipelines & semantic retrieval** for LLM-powered apps
+- **AI agent / chatbot long-term memory** that survives restarts
+- **Semantic product search & recommendations** — match intent, not keywords
+- Real-time dashboards, analytics, and live collaborative apps
+- Microservice data stores and event-driven systems
+- Data products in a decentralized Mesh architecture
 
-| Operation                      | Throughput               |
-| ------------------------------ | ------------------------ |
-| Insert (10k records)           | 40k/sec                  |
-| Lookup (single key)            | 80k/sec                  |
-| Lookup (filtered query)        | 30k/sec                  |
-| Real-Time subscription updates | < 2ms latency per update |
+## 🚀 Get the Engine (30 seconds)
 
-Performance depends on engine deployment, network, and schema complexity, but Node.js client overhead is negligible thanks to Rust core.
+The client talks to a Montycat server. Fastest way — Docker, with AI semantic search built in:
+
+```bash
+docker run -d --name montycat \
+  -p 21210:21210 -p 21211:21211 \
+  -e MONTYCAT_SUPEROWNER="admin" \
+  -e MONTYCAT_PASSWORD="change-me" \
+  -v montycat_data:/app/.montycat \
+  montygovernance/montycat:semantic
+```
 
-## When you use Montycat, you’re NOT querying a database. You’re interacting with a living data mesh that feels native to your language. 👉 Learn more about Montycat Engine https://montygovernance.com
+Prefer the lean edition without the embedding engine? Use the `latest` tag. Prebuilt packages (apt, macOS, Windows) at **https://montygovernance.com**.
 
 ## Installation
 
@@ -74,6 +111,10 @@ or with Yarn:
 yarn add montycat
 ```
 
+> **ESM-only, Node.js 18+.** This package ships native ES modules — use `import`, not
+> `require()`. Works out of the box with TypeScript, Deno, Bun, and any modern Node.js
+> project (`"type": "module"` or `.mjs`).
+
 ## Quick Start
 
 ### TypeScript Example
@@ -151,7 +192,7 @@ const newSale = new SalesSchema({
 
 const newOrder = new ProductionSchema({
     workOrder: 'WO 000012',
-    amount: 100,
+    customer: 'ACME Corp',
 }).serialize();
 
 const res3 = await Sales.insertValue({ value: newSale });
@@ -167,12 +208,12 @@ const res5 = await Sales.lookupValuesWhere({
 });
 
 const res6 = await Production.lookupValuesWhere({
-    searchCriteria: { amount: 100 },
+    searchCriteria: { customer: 'ACME Corp' },
     schema: ProductionSchema,
     keyIncluded: true
 });
 
-console.log('Lookup results:', res3, res4);
+console.log('Lookup results:', res5, res6);
 
 ```
 
@@ -233,7 +274,7 @@ const newSale = new SalesSchema({
 
 const newOrder = new ProductionSchema({
     workOrder: 'WO 000012',
-    amount: 100,
+    customer: 'ACME Corp',
 }).serialize();
 
 const res3 = await Sales.insertValue({ value: newSale });
@@ -249,11 +290,71 @@ const res5 = await Sales.lookupValuesWhere({
 });
 
 const res6 = await Production.lookupValuesWhere({
-    searchCriteria: { amount: 100 },
-    schema: ProductionSchema
+    searchCriteria: { customer: 'ACME Corp' },
+    schema: ProductionSchema,
     keyIncluded: true
 });
 
-console.log('Lookup results:', res3, res4);
+console.log('Lookup results:', res5, res6);
+
+```
+
+## 🧠 AI-Native Semantic Search — Vector Search Built Into Your Database
+
+**Stop bolting a separate vector database onto your stack.** Montycat ranks your data by
+*meaning*, not keywords — an embedded, on-device vector-embedding engine turns every write
+into a searchable vector automatically. It's the retrieval layer for **RAG pipelines, AI
+agents, semantic search, recommendation engines, and LLM-powered apps** — with **zero
+external APIs, zero API keys, and zero extra infrastructure.**
+
+- 🔎 **Semantic / vector search** — kNN similarity over on-device embeddings, not brittle keyword matches.
+- 🤖 **Built for AI** — RAG, semantic retrieval, AI agents, recommendations, dedup, clustering.
+- 🔒 **Private & free** — embeddings never leave your machine. No OpenAI/Cohere bill, no data egress.
+- ⚡ **One system, not two** — your data *and* its vectors live in the same database. No sync jobs, no drift, no second service to run.
+- 🚀 **Zero setup** — no index tuning, no pipeline: `enableSemanticSearch()` and you're ranking by meaning.
+
+> **⚠️ Requires the semantic edition of the server — nothing to compile.** Semantic
+> search runs an embedded ONNX vector-embedding engine that ships only in the
+> **`montycat-semantic`** edition; the default lean `montycat` server does not include it.
+> Get it the way that suits you — pull the **Docker image**
+> (`montygovernance/montycat:semantic`), download the prebuilt **package**, or install
+> `montycat-semantic` from the **apt repository**. The Node.js client API is identical
+> either way; just point it at a semantic-edition server (semantic search is enabled by
+> default there, using the `bge-small` model).
+
+The switch is DB-wide and already on in the semantic edition; every keyspace is embedded
+in the background as data is written (the embedding model is downloaded on demand).
+
+```typescript
+// Semantic search is ON by default in the montycat-semantic edition — just search.
+// Rank stored items by meaning — two flavors:
+//   getValues → each hit is { key, score, value }
+//   getKeys   → each hit is { key, score } (lighter; fetch a page later with getBulk)
+const hits = await Sales.semanticSearchGetValues({ query: 'something to listen to music without wires', limitOutput: { start: 0, stop: 5 } });
+const keys = await Sales.semanticSearchGetKeys({ query: 'something to listen to music without wires', limitOutput: { start: 0, stop: 5 } });
+
+// Optionally drop weak matches by cosine similarity (range [-1, 1]).
+const strong = await Sales.semanticSearchGetKeys({ query: 'something to listen to music without wires', limitOutput: { start: 0, stop: 5 }, minScore: 0.35 });
+
+// Control the DB-wide switch (optional — it's already on):
+// switch the embedding model: 'minilm' | 'bge-small' (default) | 'bge-base' | 'e5-small'
+await engine.enableSemanticSearch({ model: 'bge-base' });
+
+// turn it off (vectors are kept so re-enabling resumes instantly;
+// pass { dropVectors: true } to also clear stored vectors)
+await engine.disableSemanticSearch();
+```
+
+## 🔗 Links
+
+- 🌐 **Website & Docs** — https://montygovernance.com
+- 📦 **npm** — https://www.npmjs.com/package/montycat
+- 🐳 **Docker Hub** — https://hub.docker.com/r/montygovernance/montycat
+- 💻 **Source** — https://github.com/MontyGovernance/montycat_node
+
+## ❓ FAQ
 
-```
+- **Is Montycat a vector database or a NoSQL database?** Both — one engine. Store records and query them by *meaning* (vector / semantic search) or by key/schema, without running two systems.
+- **Do I need OpenAI or an embedding API?** No. Embeddings run on-device in the `montycat-semantic` server. No API keys, no per-query bill, no data egress.
+- **Is it a Pinecone / Weaviate / Chroma / Qdrant alternative?** Yes — self-hosted and open-source, with a NoSQL store built in.
+- **TypeScript support?** First-class — the package ships its own type definitions. Works with Node.js, Deno, Bun, Express, Fastify, and Next.js.

package/dist/classes/generic.d.ts

@@ -52,9 +52,10 @@ declare class GenericKV {
      * @param customKey - The custom key to delete.
      * @return A promise that resolves with the result of the deletion.
      * */
-    static deleteKey({ key, customKey }?: {
+    static deleteKey({ key, customKey, waitForIndex }?: {
         key?: string;
         customKey?: string | null;
+        waitForIndex?: boolean | null;
     }): Promise<any>;
     /**
      * Deletes a bulk of keys from the keyspace.
@@ -62,9 +63,10 @@ declare class GenericKV {
      * @param bulkCustomKeys - An array of custom keys to delete.
      * @return A promise that resolves with the result of the deletion.
      * */
-    static deleteBulk({ bulkKeys, bulkCustomKeys }?: {
+    static deleteBulk({ bulkKeys, bulkCustomKeys, waitForIndex }?: {
         bulkKeys?: string[];
         bulkCustomKeys?: string[];
+        waitForIndex?: boolean | null;
     }): Promise<any>;
     /**
      * Gets bulk values from the keyspace.
@@ -97,13 +99,14 @@ declare class GenericKV {
      * @param bulkCustomKeysValues - An object where custom keys are the keys to update and values are the new values.
      * @return A promise that resolves with the result of the update.
      */
-    static updateBulk({ bulkKeysValues, bulkCustomKeysValues }?: {
+    static updateBulk({ bulkKeysValues, bulkCustomKeysValues, waitForIndex }?: {
         bulkKeysValues?: {
             [key: string]: any;
         };
         bulkCustomKeysValues?: {
             [key: string]: any;
         };
+        waitForIndex?: boolean | null;
     }): Promise<any>;
     /**
      * Looks up keys based on search criteria.
@@ -145,6 +148,74 @@ declare class GenericKV {
         keyIncluded?: boolean;
         pointersMetadata?: boolean;
     }): Promise<any>;
+    /**
+     * Shared core for `semanticSearchGetKeys` / `semanticSearchGetValues`.
+     * The server command is the same either way (`semantic_search`); the two
+     * public methods differ only in which value-inclusion flags they pass,
+     * so the wire call lives here once.
+     */
+    private static semanticSearchCore;
+    /**
+     * Semantic (vector similarity) search returning ranked keys only.
+     *
+     * Ranks stored items by how close their embeddings are to the embedding of
+     * `query` and returns just the matched key and score for each hit — the
+     * lightweight variant when you only need identity + ranking (e.g. to then
+     * `getBulk` a page, or to test membership). Use `semanticSearchGetValues`
+     * when you want the values inline.
+     *
+     * Semantic search must be enabled first (see `Engine.enableSemanticSearch`).
+     * The keyspace is embedded in the background as items are written, so
+     * results reflect whatever has been embedded so far.
+     *
+     * @param query - The natural-language query text to embed and search for.
+     * @param limitOutput - Start/stop over the ranked hits; `{start: 0, stop: 0}`
+     *                      (the default) lets the server apply its default top-k (10).
+     * @param minScore - Drop hits whose cosine similarity (in [-1, 1]) is below
+     *                   this value. Default null (no score filter).
+     * @return A promise resolving with ranked hits, each `{key, score}`.
+     */
+    static semanticSearchGetKeys({ query, limitOutput, minScore }: {
+        query: string;
+        limitOutput?: {
+            start: number;
+            stop: number;
+        };
+        minScore?: number | null;
+    }): Promise<any>;
+    /**
+     * Semantic (vector similarity) search returning ranked hits with their values.
+     *
+     * Ranks stored items by how close their embeddings are to the embedding of
+     * `query` and returns the value inline with each hit — the key is always
+     * included so every value is tagged with its key. Use
+     * `semanticSearchGetKeys` when you only need keys + scores.
+     *
+     * Semantic search must be enabled first (see `Engine.enableSemanticSearch`).
+     * The keyspace is embedded in the background as items are written, so
+     * results reflect whatever has been embedded so far.
+     *
+     * @param query - The natural-language query text to embed and search for.
+     * @param limitOutput - Start/stop over the ranked hits; `{start: 0, stop: 0}`
+     *                      (the default) lets the server apply its default top-k (10).
+     * @param minScore - Drop hits whose cosine similarity (in [-1, 1]) is below
+     *                   this value. Default null (no score filter).
+     * @param withPointers - Whether to include pointers (foreign values) in each
+     *                       returned value.
+     * @param pointersMetadata - Whether to include pointer metadata in each
+     *                           returned value.
+     * @return A promise resolving with ranked hits, each `{key, score, value}`.
+     */
+    static semanticSearchGetValues({ query, limitOutput, minScore, withPointers, pointersMetadata }: {
+        query: string;
+        limitOutput?: {
+            start: number;
+            stop: number;
+        };
+        minScore?: number | null;
+        withPointers?: boolean;
+        pointersMetadata?: boolean;
+    }): Promise<any>;
     /**
      * Gets the length of the keyspace.
      * @returns A promise that resolves with the length of the keyspace.
@@ -173,5 +244,18 @@ declare class GenericKV {
      * @returns The current instance of GenericKV.
      */
     showStoreProperties(): this;
+    /**
+     * Subscribes to changes in the keyspace.
+     * Inherited by InMemory and Persistent - `this.persistent` resolves correctly per subclass.
+     * @param callback - A callback function to handle incoming data.
+     * @param key - A specific key to subscribe to.
+     * @param customKey - A custom key to subscribe to (will be hashed with XXH32).
+     * @returns A promise that resolves with a subscription handle ({ stop() }).
+     */
+    static subscribe({ callback, key, customKey }: {
+        callback?: (data: any) => void;
+        key?: string;
+        customKey?: string;
+    }): Promise<any>;
 }
 export default GenericKV;

package/dist/classes/generic.js

@@ -34,15 +34,15 @@ class GenericKV {
      * @return A promise that resolves with the retrieved value.
      */
     static async getValue({ key = "", customKey = null, withPointers = false, keyIncluded = false, pointersMetadata = false } = {}) {
-        if (pointersMetadata && withPointers) {
-            throw new Error("You select both pointers value and pointers metadata. Choose one");
-        }
         try {
+            if (key && customKey) {
+                throw new Error("Provide either 'key' or 'customKey', not both.");
+            }
+            if (!key && !customKey) {
+                throw new Error("Provide either 'key' or 'customKey'.");
+            }
             if (customKey)
                 key = convertCustomKey(customKey);
-            if (!key) {
-                throw new Error("No key provided");
-            }
             this.command = "get_value";
             const query = convertToBinaryQuery(this, { key, withPointers, keyIncluded, pointersMetadata });
             return runQuery(this, query);
@@ -59,11 +59,14 @@ class GenericKV {
      * */
     static async listAllDependingKeys({ key = "", customKey = null } = {}) {
         try {
+            if (key && customKey) {
+                throw new Error("Provide either 'key' or 'customKey', not both.");
+            }
+            if (!key && !customKey) {
+                throw new Error("Provide either 'key' or 'customKey'.");
+            }
             if (customKey)
                 key = convertCustomKey(customKey);
-            if (!key) {
-                throw new Error("No key provided");
-            }
             this.command = "list_all_depending_keys";
             const query = convertToBinaryQuery(this, { key });
             return runQuery(this, query);
@@ -83,15 +86,18 @@ class GenericKV {
      * @param customKey - The custom key to delete.
      * @return A promise that resolves with the result of the deletion.
      * */
-    static async deleteKey({ key = "", customKey = null } = {}) {
+    static async deleteKey({ key = "", customKey = null, waitForIndex = null } = {}) {
         try {
+            if (key && customKey) {
+                throw new Error("Provide either 'key' or 'customKey', not both.");
+            }
             if (customKey)
                 key = convertCustomKey(customKey);
             if (!key) {
                 throw new Error("No key provided");
             }
             this.command = "delete_key";
-            const query = convertToBinaryQuery(this, { key });
+            const query = convertToBinaryQuery(this, { key, waitForIndex });
             return runQuery(this, query);
         }
         catch (err) {
@@ -104,7 +110,7 @@ class GenericKV {
      * @param bulkCustomKeys - An array of custom keys to delete.
      * @return A promise that resolves with the result of the deletion.
      * */
-    static async deleteBulk({ bulkKeys = [], bulkCustomKeys = [] } = {}) {
+    static async deleteBulk({ bulkKeys = [], bulkCustomKeys = [], waitForIndex = null } = {}) {
         try {
             if (bulkCustomKeys.length)
                 bulkKeys = bulkKeys.concat(convertCustomKeys(bulkCustomKeys));
@@ -112,7 +118,7 @@ class GenericKV {
                 throw new Error("No keys provided");
             }
             this.command = "delete_bulk";
-            const query = convertToBinaryQuery(this, { bulkKeys });
+            const query = convertToBinaryQuery(this, { bulkKeys, waitForIndex });
             return runQuery(this, query);
         }
         catch (err) {
@@ -156,7 +162,7 @@ class GenericKV {
      * @param bulkCustomKeysValues - An object where custom keys are the keys to update and values are the new values.
      * @return A promise that resolves with the result of the update.
      */
-    static async updateBulk({ bulkKeysValues = {}, bulkCustomKeysValues = {} } = {}) {
+    static async updateBulk({ bulkKeysValues = {}, bulkCustomKeysValues = {}, waitForIndex = null } = {}) {
         try {
             if (Object.keys(bulkCustomKeysValues).length) {
                 bulkKeysValues = { ...bulkKeysValues, ...convertCustomKeysValues(bulkCustomKeysValues) };
@@ -165,7 +171,7 @@ class GenericKV {
                 throw new Error("No keys provided");
             }
             this.command = "update_bulk";
-            const query = convertToBinaryQuery(this, { bulkKeysValues });
+            const query = convertToBinaryQuery(this, { bulkKeysValues, waitForIndex });
             return runQuery(this, query);
         }
         catch (err) {
@@ -209,6 +215,76 @@ class GenericKV {
             throw err;
         }
     }
+    /**
+     * Shared core for `semanticSearchGetKeys` / `semanticSearchGetValues`.
+     * The server command is the same either way (`semantic_search`); the two
+     * public methods differ only in which value-inclusion flags they pass,
+     * so the wire call lives here once.
+     */
+    static async semanticSearchCore(query, limitOutput, minScore, withPointers, keyIncluded, pointersMetadata) {
+        if (!query || !query.trim()) {
+            throw new Error("No query text provided for semantic search.");
+        }
+        this.command = "semantic_search";
+        const binaryQuery = convertToBinaryQuery(this, {
+            semanticQuery: query,
+            limitOutput,
+            minScore,
+            withPointers,
+            keyIncluded,
+            pointersMetadata,
+        });
+        return runQuery(this, binaryQuery);
+    }
+    /**
+     * Semantic (vector similarity) search returning ranked keys only.
+     *
+     * Ranks stored items by how close their embeddings are to the embedding of
+     * `query` and returns just the matched key and score for each hit — the
+     * lightweight variant when you only need identity + ranking (e.g. to then
+     * `getBulk` a page, or to test membership). Use `semanticSearchGetValues`
+     * when you want the values inline.
+     *
+     * Semantic search must be enabled first (see `Engine.enableSemanticSearch`).
+     * The keyspace is embedded in the background as items are written, so
+     * results reflect whatever has been embedded so far.
+     *
+     * @param query - The natural-language query text to embed and search for.
+     * @param limitOutput - Start/stop over the ranked hits; `{start: 0, stop: 0}`
+     *                      (the default) lets the server apply its default top-k (10).
+     * @param minScore - Drop hits whose cosine similarity (in [-1, 1]) is below
+     *                   this value. Default null (no score filter).
+     * @return A promise resolving with ranked hits, each `{key, score}`.
+     */
+    static async semanticSearchGetKeys({ query, limitOutput = { start: 0, stop: 0 }, minScore = null }) {
+        return this.semanticSearchCore(query, limitOutput, minScore, false, false, false);
+    }
+    /**
+     * Semantic (vector similarity) search returning ranked hits with their values.
+     *
+     * Ranks stored items by how close their embeddings are to the embedding of
+     * `query` and returns the value inline with each hit — the key is always
+     * included so every value is tagged with its key. Use
+     * `semanticSearchGetKeys` when you only need keys + scores.
+     *
+     * Semantic search must be enabled first (see `Engine.enableSemanticSearch`).
+     * The keyspace is embedded in the background as items are written, so
+     * results reflect whatever has been embedded so far.
+     *
+     * @param query - The natural-language query text to embed and search for.
+     * @param limitOutput - Start/stop over the ranked hits; `{start: 0, stop: 0}`
+     *                      (the default) lets the server apply its default top-k (10).
+     * @param minScore - Drop hits whose cosine similarity (in [-1, 1]) is below
+     *                   this value. Default null (no score filter).
+     * @param withPointers - Whether to include pointers (foreign values) in each
+     *                       returned value.
+     * @param pointersMetadata - Whether to include pointer metadata in each
+     *                           returned value.
+     * @return A promise resolving with ranked hits, each `{key, score, value}`.
+     */
+    static async semanticSearchGetValues({ query, limitOutput = { start: 0, stop: 0 }, minScore = null, withPointers = false, pointersMetadata = false }) {
+        return this.semanticSearchCore(query, limitOutput, minScore, withPointers, true, pointersMetadata);
+    }
     /**
      * Gets the length of the keyspace.
      * @returns A promise that resolves with the length of the keyspace.
@@ -301,5 +377,29 @@ class GenericKV {
     showStoreProperties() {
         return this;
     }
+    /**
+     * Subscribes to changes in the keyspace.
+     * Inherited by InMemory and Persistent - `this.persistent` resolves correctly per subclass.
+     * @param callback - A callback function to handle incoming data.
+     * @param key - A specific key to subscribe to.
+     * @param customKey - A custom key to subscribe to (will be hashed with XXH32).
+     * @returns A promise that resolves with a subscription handle ({ stop() }).
+     */
+    static async subscribe({ callback, key, customKey }) {
+        if (key && customKey) {
+            throw new Error("Provide either 'key' or 'customKey', not both.");
+        }
+        const effectiveKey = customKey ? convertCustomKey(customKey) : (key || null);
+        const queryObj = {
+            subscribe: true,
+            store: this.store,
+            keyspace: this.keyspace,
+            username: this.username,
+            password: this.password,
+            persistent: this.persistent,
+            key: effectiveKey,
+        };
+        return await runQuery(this, JSON.stringify(queryObj), callback, true);
+    }
 }
 export default GenericKV;