montycat 1.1.5 → 1.1.7

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: 'Show all Bluetooth devices', 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: 'Show all Bluetooth devices', limitOutput: { start: 0, stop: 5 } });
+const keys = await Sales.semanticSearchGetKeys({ query: 'Show all Bluetooth devices', limitOutput: { start: 0, stop: 5 } });
+
+// Optionally drop weak matches by cosine similarity (range [-1, 1]).
+const strong = await Sales.semanticSearchGetKeys({ query: 'Show all Bluetooth devices', 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,76 @@ 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__}` — the same dunder envelope
+     *         `lookupValuesWhere` returns with `keyIncluded: true`, plus the score.
+     */
+    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.

package/dist/classes/generic.js

@@ -86,7 +86,7 @@ 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.");
@@ -97,7 +97,7 @@ class GenericKV {
                 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) {
@@ -110,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));
@@ -118,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) {
@@ -162,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) };
@@ -171,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) {
@@ -215,6 +215,78 @@ 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__}` — the same dunder envelope
+     *         `lookupValuesWhere` returns with `keyIncluded: true`, plus the score.
+     */
+    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.

package/dist/core/engine.d.ts

@@ -109,11 +109,130 @@ declare class Engine {
             keyspace: string;
         };
     }): Promise<unknown>;
+    /**
+     * Enable semantic (vector similarity) search.
+     *
+     * Without `store`, this is DB-wide: it flips the whole database on, sets the
+     * default embedding model and field, and enrolls every existing keyspace that
+     * has no semantic config yet (each gets a background backfill so its existing
+     * items become searchable). The chosen model is downloaded on demand on first
+     * enable, so this call may take a while the first time.
+     *
+     * With `store`, it is scoped: only that store's un-enrolled keyspaces are
+     * enrolled and backfilled; the DB-wide switch and default model/field are left
+     * untouched. Use this to (re-)enable one store without re-embedding the entire
+     * database.
+     *
+     * @param {Object} options - Options for enabling semantic search.
+     * @param {string} [options.model] - The embedding model key to use by default.
+     *                                   One of 'minilm', 'bge-small', 'bge-base',
+     *                                   'e5-small'. Defaults to the server default
+     *                                   ('bge-small').
+     * @param {string} [options.field] - The JSON field of each value to embed.
+     *                                   Defaults to embedding the whole value.
+     * @param {string} [options.store] - Restrict enrollment/backfill to this store
+     *                                   only. If the DB-wide switch is off, a scoped
+     *                                   enable enrolls but nothing embeds until a
+     *                                   DB-wide enable.
+     * @returns {Promise<unknown>} The server's response describing the enabled
+     *                             model and enrolled keyspaces.
+     */
+    enableSemanticSearch({ model, field, store }?: {
+        model?: string;
+        field?: string;
+        store?: string;
+    }): Promise<unknown>;
+    /**
+     * Disable semantic search.
+     *
+     * Without `store`, this is DB-wide: embedding and semantic queries stop across
+     * the whole database; stored vectors are kept by default so re-enabling
+     * resumes without a full re-embed.
+     *
+     * With `store`, it is scoped: only that store's keyspaces are unenrolled
+     * (their configs and resident graphs dropped); the DB-wide switch and all
+     * other stores are left untouched. This is the surgical way to reset one
+     * store's semantic state instead of nuking and re-backfilling the whole
+     * database.
+     *
+     * @param {Object} options - Options for disabling semantic search.
+     * @param {boolean} [options.dropVectors=false] - If true, also clear stored
+     *                                                vectors — every keyspace's
+     *                                                DB-wide, or the scoped store's
+     *                                                when `store` is set. Required
+     *                                                before switching to a different
+     *                                                embedding model.
+     * @param {string} [options.store] - Restrict the disable to this store only.
+     * @returns {Promise<unknown>} The server's response confirming the disable.
+     */
+    disableSemanticSearch({ dropVectors, store }?: {
+        dropVectors?: boolean;
+        store?: string;
+    }): Promise<unknown>;
     /**
      * Retrieves the structure of the store.
      * @returns {Promise<unknown>} A promise that resolves with the structure of the store
      * */
     getStructureAvailable(): Promise<unknown>;
+    /**
+     * Enable the DB-wide "wait for index" default: writes block until their
+     * secondary indexes are updated before returning, so a write is immediately
+     * visible to index-backed reads (e.g. lookupValuesWhere) at the cost of
+     * higher write latency. Requires superowner credentials.
+     * @returns {Promise<unknown>} The server's response confirming the change.
+     */
+    enableWaitForIndex(): Promise<unknown>;
+    /**
+     * Disable the DB-wide "wait for index" default: writes return as soon as the
+     * data is committed and indexing happens asynchronously in the background
+     * (lower write latency; index-backed reads may briefly lag). This is the
+     * default behavior. Requires superowner credentials.
+     * @returns {Promise<unknown>} The server's response confirming the change.
+     */
+    disableWaitForIndex(): Promise<unknown>;
+    /** Internal helper for no-argument superowner raw commands. */
+    private _adminCommand;
+    /**
+     * Enable server-side operation reporting (logging). Requires superowner credentials.
+     * @returns {Promise<unknown>} The server's response confirming the change.
+     */
+    enableReports(): Promise<unknown>;
+    /**
+     * Disable server-side operation reporting (logging). Requires superowner credentials.
+     * @returns {Promise<unknown>} The server's response confirming the change.
+     */
+    disableReports(): Promise<unknown>;
+    /**
+     * Allow clients to open keyspace subscriptions DB-wide. Requires superowner credentials.
+     * @returns {Promise<unknown>} The server's response confirming the change.
+     */
+    allowSubscriptions(): Promise<unknown>;
+    /**
+     * Restrict (disallow) keyspace subscriptions DB-wide. Requires superowner credentials.
+     * @returns {Promise<unknown>} The server's response confirming the change.
+     */
+    restrictSubscriptions(): Promise<unknown>;
+    /**
+     * Sample the current depth of every background task queue (index, timer,
+     * counting) — an observability probe for whether the background runners are
+     * keeping up with the write rate. Requires superowner credentials.
+     * @returns {Promise<unknown>} The server's response whose payload maps
+     *   "index" | "timer" | "counting" to per-queue depth maps.
+     */
+    queueDepths(): Promise<unknown>;
+    /**
+     * Set the server-wide snapshot rate. Requires superowner credentials.
+     * @param {number} rate - The snapshot rate value (server-defined units).
+     * @returns {Promise<unknown>} The server's response confirming the change.
+     */
+    setSnapshotRate(rate: number): Promise<unknown>;
+    /**
+     * Set how often the server scans for expired keys. Requires superowner credentials.
+     * @param {number} rate - The check period in whole seconds (e.g. rate=10 → a scan
+     *   every 10 seconds). Stored as-is, like the snapshot rate. Defaults to 1 second.
+     * @returns {Promise<unknown>} The server's response confirming the change.
+     */
+    setExpirationCheckRate(rate: number): Promise<unknown>;
 }
 /**
  * Sends a string to the specified host and port, and returns the parsed response.

package/dist/core/engine.js

@@ -206,6 +206,81 @@ class Engine {
         }
         return sendData(this.host, this.port, JSONbig.stringify(query), undefined, this.useTls);
     }
+    /**
+     * Enable semantic (vector similarity) search.
+     *
+     * Without `store`, this is DB-wide: it flips the whole database on, sets the
+     * default embedding model and field, and enrolls every existing keyspace that
+     * has no semantic config yet (each gets a background backfill so its existing
+     * items become searchable). The chosen model is downloaded on demand on first
+     * enable, so this call may take a while the first time.
+     *
+     * With `store`, it is scoped: only that store's un-enrolled keyspaces are
+     * enrolled and backfilled; the DB-wide switch and default model/field are left
+     * untouched. Use this to (re-)enable one store without re-embedding the entire
+     * database.
+     *
+     * @param {Object} options - Options for enabling semantic search.
+     * @param {string} [options.model] - The embedding model key to use by default.
+     *                                   One of 'minilm', 'bge-small', 'bge-base',
+     *                                   'e5-small'. Defaults to the server default
+     *                                   ('bge-small').
+     * @param {string} [options.field] - The JSON field of each value to embed.
+     *                                   Defaults to embedding the whole value.
+     * @param {string} [options.store] - Restrict enrollment/backfill to this store
+     *                                   only. If the DB-wide switch is off, a scoped
+     *                                   enable enrolls but nothing embeds until a
+     *                                   DB-wide enable.
+     * @returns {Promise<unknown>} The server's response describing the enabled
+     *                             model and enrolled keyspaces.
+     */
+    async enableSemanticSearch({ model, field, store } = {}) {
+        const rawQuery = {
+            raw: ['enable-semantic-search'],
+            credentials: [this.username, this.password],
+        };
+        if (model)
+            rawQuery.raw.push('model', model);
+        if (field)
+            rawQuery.raw.push('field', field);
+        if (store)
+            rawQuery.raw.push('store', store);
+        return sendData(this.host, this.port, JSONbig.stringify(rawQuery), undefined, this.useTls);
+    }
+    /**
+     * Disable semantic search.
+     *
+     * Without `store`, this is DB-wide: embedding and semantic queries stop across
+     * the whole database; stored vectors are kept by default so re-enabling
+     * resumes without a full re-embed.
+     *
+     * With `store`, it is scoped: only that store's keyspaces are unenrolled
+     * (their configs and resident graphs dropped); the DB-wide switch and all
+     * other stores are left untouched. This is the surgical way to reset one
+     * store's semantic state instead of nuking and re-backfilling the whole
+     * database.
+     *
+     * @param {Object} options - Options for disabling semantic search.
+     * @param {boolean} [options.dropVectors=false] - If true, also clear stored
+     *                                                vectors — every keyspace's
+     *                                                DB-wide, or the scoped store's
+     *                                                when `store` is set. Required
+     *                                                before switching to a different
+     *                                                embedding model.
+     * @param {string} [options.store] - Restrict the disable to this store only.
+     * @returns {Promise<unknown>} The server's response confirming the disable.
+     */
+    async disableSemanticSearch({ dropVectors = false, store } = {}) {
+        const rawQuery = {
+            raw: ['disable-semantic-search'],
+            credentials: [this.username, this.password],
+        };
+        if (dropVectors)
+            rawQuery.raw.push('drop-vectors');
+        if (store)
+            rawQuery.raw.push('store', store);
+        return sendData(this.host, this.port, JSONbig.stringify(rawQuery), undefined, this.useTls);
+    }
     /**
      * Retrieves the structure of the store.
      * @returns {Promise<unknown>} A promise that resolves with the structure of the store
@@ -218,6 +293,105 @@ class Engine {
         };
         return sendData(this.host, this.port, JSONbig.stringify(rawQuery), undefined, this.useTls);
     }
+    /**
+     * Enable the DB-wide "wait for index" default: writes block until their
+     * secondary indexes are updated before returning, so a write is immediately
+     * visible to index-backed reads (e.g. lookupValuesWhere) at the cost of
+     * higher write latency. Requires superowner credentials.
+     * @returns {Promise<unknown>} The server's response confirming the change.
+     */
+    async enableWaitForIndex() {
+        const rawQuery = {
+            raw: ['enable-wait-for-index'],
+            credentials: [this.username, this.password],
+        };
+        return sendData(this.host, this.port, JSONbig.stringify(rawQuery), undefined, this.useTls);
+    }
+    /**
+     * Disable the DB-wide "wait for index" default: writes return as soon as the
+     * data is committed and indexing happens asynchronously in the background
+     * (lower write latency; index-backed reads may briefly lag). This is the
+     * default behavior. Requires superowner credentials.
+     * @returns {Promise<unknown>} The server's response confirming the change.
+     */
+    async disableWaitForIndex() {
+        const rawQuery = {
+            raw: ['disable-wait-for-index'],
+            credentials: [this.username, this.password],
+        };
+        return sendData(this.host, this.port, JSONbig.stringify(rawQuery), undefined, this.useTls);
+    }
+    /** Internal helper for no-argument superowner raw commands. */
+    async _adminCommand(command) {
+        const rawQuery = {
+            raw: [command],
+            credentials: [this.username, this.password],
+        };
+        return sendData(this.host, this.port, JSONbig.stringify(rawQuery), undefined, this.useTls);
+    }
+    /**
+     * Enable server-side operation reporting (logging). Requires superowner credentials.
+     * @returns {Promise<unknown>} The server's response confirming the change.
+     */
+    async enableReports() {
+        return this._adminCommand('enable-reports');
+    }
+    /**
+     * Disable server-side operation reporting (logging). Requires superowner credentials.
+     * @returns {Promise<unknown>} The server's response confirming the change.
+     */
+    async disableReports() {
+        return this._adminCommand('disable-reports');
+    }
+    /**
+     * Allow clients to open keyspace subscriptions DB-wide. Requires superowner credentials.
+     * @returns {Promise<unknown>} The server's response confirming the change.
+     */
+    async allowSubscriptions() {
+        return this._adminCommand('allow-subscriptions');
+    }
+    /**
+     * Restrict (disallow) keyspace subscriptions DB-wide. Requires superowner credentials.
+     * @returns {Promise<unknown>} The server's response confirming the change.
+     */
+    async restrictSubscriptions() {
+        return this._adminCommand('restrict-subscriptions');
+    }
+    /**
+     * Sample the current depth of every background task queue (index, timer,
+     * counting) — an observability probe for whether the background runners are
+     * keeping up with the write rate. Requires superowner credentials.
+     * @returns {Promise<unknown>} The server's response whose payload maps
+     *   "index" | "timer" | "counting" to per-queue depth maps.
+     */
+    async queueDepths() {
+        return this._adminCommand('queue-depths');
+    }
+    /**
+     * Set the server-wide snapshot rate. Requires superowner credentials.
+     * @param {number} rate - The snapshot rate value (server-defined units).
+     * @returns {Promise<unknown>} The server's response confirming the change.
+     */
+    async setSnapshotRate(rate) {
+        const rawQuery = {
+            raw: ['snapshot-rate', String(rate)],
+            credentials: [this.username, this.password],
+        };
+        return sendData(this.host, this.port, JSONbig.stringify(rawQuery), undefined, this.useTls);
+    }
+    /**
+     * Set how often the server scans for expired keys. Requires superowner credentials.
+     * @param {number} rate - The check period in whole seconds (e.g. rate=10 → a scan
+     *   every 10 seconds). Stored as-is, like the snapshot rate. Defaults to 1 second.
+     * @returns {Promise<unknown>} The server's response confirming the change.
+     */
+    async setExpirationCheckRate(rate) {
+        const rawQuery = {
+            raw: ['expiration-check', String(rate)],
+            credentials: [this.username, this.password],
+        };
+        return sendData(this.host, this.port, JSONbig.stringify(rawQuery), undefined, this.useTls);
+    }
 }
 /**
  * Sends data to a server. Supports one-time request/response or subscription.

package/dist/core/inmemory.d.ts

@@ -32,31 +32,38 @@ declare class InMemory extends GenericKV {
      * @param expireSec - The expiration time in seconds for the value.
      * @return A promise that resolves with the result of the insertion.
      * */
-    static insertValue({ value, expireSec }?: {
+    static insertValue({ value, expireSec, waitForIndex }?: {
         value?: any;
         expireSec?: number;
+        waitForIndex?: boolean | null;
     }): Promise<any>;
     /**
      * Inserts a custom key into the in-memory store.
      * @param customKey - The custom key for the value.
      * @param expireSec - The expiration time in seconds for the value.
+     * @param waitForIndex - Per-request synchronous-index override. No-op for in-memory
+     *   keyspaces (snapshot-driven indexing); present for API symmetry with the persistent
+     *   variant, where it takes effect.
      * @return A promise that resolves with the result of the insertion.
      */
-    static insertCustomKey({ customKey, expireSec }: {
+    static insertCustomKey({ customKey, expireSec, waitForIndex }: {
         customKey: string;
         expireSec?: number;
+        waitForIndex?: boolean | null;
     }): Promise<any>;
     /**
      * Inserts a custom key-value pair into the in-memory store.
      * @param customKey - The custom key for the value.
      * @param value - The value to insert.
      * @param expireSec - The expiration time in seconds for the value.
+     * @param waitForIndex - Per-request synchronous-index override; no-op for in-memory.
      * @return A promise that resolves with the result of the insertion.
      */
-    static insertCustomKeyValue({ customKey, value, expireSec }: {
+    static insertCustomKeyValue({ customKey, value, expireSec, waitForIndex }: {
         customKey: string;
         value?: any;
         expireSec?: number;
+        waitForIndex?: boolean | null;
     }): Promise<any>;
     /**
      * Updates a value in the in-memory store.
@@ -64,23 +71,27 @@ declare class InMemory extends GenericKV {
      * @param customKey - The custom key for the value to update.
      * @param value - The new value to set.
      * @param expireSec - The expiration time in seconds for the value.
+     * @param waitForIndex - Per-request synchronous-index override; no-op for in-memory.
      * @return A promise that resolves with the result of the update.
      */
-    static updateValue({ key, customKey, value, expireSec }?: {
+    static updateValue({ key, customKey, value, expireSec, waitForIndex }?: {
         key?: string;
         customKey?: string | null;
         value?: any;
         expireSec?: number;
+        waitForIndex?: boolean | null;
     }): Promise<any>;
     /**
         * Inserts a bulk of values into the in-memory store.
         * @param bulk - An array of values to insert.
         * @param expireSec - The expiration time in seconds for the values.
+        * @param waitForIndex - Per-request synchronous-index override; no-op for in-memory.
         * @return A promise that resolves with the result of the insertion.
      */
-    static insertBulk({ bulk, expireSec }?: {
+    static insertBulk({ bulk, expireSec, waitForIndex }?: {
         bulk?: any[];
         expireSec?: number;
+        waitForIndex?: boolean | null;
     }): Promise<any>;
     /**
      * Gets keys from the in-memory store.

package/dist/core/inmemory.js

@@ -84,23 +84,26 @@ class InMemory extends GenericKV {
      * @param expireSec - The expiration time in seconds for the value.
      * @return A promise that resolves with the result of the insertion.
      * */
-    static async insertValue({ value = {}, expireSec = 0 } = {}) {
+    static async insertValue({ value = {}, expireSec = 0, waitForIndex = null } = {}) {
         this.command = "insert_value";
-        const query = convertToBinaryQuery(this, { value, expireSec });
+        const query = convertToBinaryQuery(this, { value, expireSec, waitForIndex });
         return runQuery(this, query);
     }
     /**
      * Inserts a custom key into the in-memory store.
      * @param customKey - The custom key for the value.
      * @param expireSec - The expiration time in seconds for the value.
+     * @param waitForIndex - Per-request synchronous-index override. No-op for in-memory
+     *   keyspaces (snapshot-driven indexing); present for API symmetry with the persistent
+     *   variant, where it takes effect.
      * @return A promise that resolves with the result of the insertion.
      */
-    static async insertCustomKey({ customKey, expireSec = 0 }) {
+    static async insertCustomKey({ customKey, expireSec = 0, waitForIndex = null }) {
         if (!customKey) {
             throw new Error("No key provided");
         }
         this.command = "insert_custom_key";
-        const query = convertToBinaryQuery(this, { key: convertCustomKey(customKey), expireSec });
+        const query = convertToBinaryQuery(this, { key: convertCustomKey(customKey), expireSec, waitForIndex });
         return runQuery(this, query);
     }
     /**
@@ -108,11 +111,12 @@ class InMemory extends GenericKV {
      * @param customKey - The custom key for the value.
      * @param value - The value to insert.
      * @param expireSec - The expiration time in seconds for the value.
+     * @param waitForIndex - Per-request synchronous-index override; no-op for in-memory.
      * @return A promise that resolves with the result of the insertion.
      */
-    static async insertCustomKeyValue({ customKey, value = {}, expireSec = 0 }) {
+    static async insertCustomKeyValue({ customKey, value = {}, expireSec = 0, waitForIndex = null }) {
         this.command = "insert_custom_key_value";
-        const query = convertToBinaryQuery(this, { key: convertCustomKey(customKey), value, expireSec });
+        const query = convertToBinaryQuery(this, { key: convertCustomKey(customKey), value, expireSec, waitForIndex });
         return runQuery(this, query);
     }
     /**
@@ -121,29 +125,31 @@ class InMemory extends GenericKV {
      * @param customKey - The custom key for the value to update.
      * @param value - The new value to set.
      * @param expireSec - The expiration time in seconds for the value.
+     * @param waitForIndex - Per-request synchronous-index override; no-op for in-memory.
      * @return A promise that resolves with the result of the update.
      */
-    static async updateValue({ key = "", customKey = null, value = {}, expireSec = 0 } = {}) {
+    static async updateValue({ key = "", customKey = null, value = {}, expireSec = 0, waitForIndex = null } = {}) {
         const effectiveKey = customKey ? convertCustomKey(customKey) : key;
         if (!effectiveKey) {
             throw new Error("No key provided");
         }
         this.command = "update_value";
-        const query = convertToBinaryQuery(this, { key: effectiveKey, value, expireSec });
+        const query = convertToBinaryQuery(this, { key: effectiveKey, value, expireSec, waitForIndex });
         return runQuery(this, query);
     }
     /**
         * Inserts a bulk of values into the in-memory store.
         * @param bulk - An array of values to insert.
         * @param expireSec - The expiration time in seconds for the values.
+        * @param waitForIndex - Per-request synchronous-index override; no-op for in-memory.
         * @return A promise that resolves with the result of the insertion.
      */
-    static async insertBulk({ bulk = [], expireSec = 0 } = {}) {
+    static async insertBulk({ bulk = [], expireSec = 0, waitForIndex = null } = {}) {
         if (!bulk || bulk.length === 0) {
             throw new Error("No values provided");
         }
         this.command = "insert_bulk";
-        const query = convertToBinaryQuery(this, { bulkValues: bulk, expireSec });
+        const query = convertToBinaryQuery(this, { bulkValues: bulk, expireSec, waitForIndex });
         return runQuery(this, query);
     }
     /**

package/dist/core/persistent.d.ts

@@ -18,46 +18,58 @@ declare class Persistent extends GenericKV {
      * @param value - The value to insert.
      * @return A promise that resolves with the result of the insertion.
      */
-    static insertValue({ value }?: {
+    static insertValue({ value, waitForIndex }?: {
         value?: any;
+        waitForIndex?: boolean | null;
     }): Promise<any>;
     /**
      * Inserts a custom key into the persistent store.
      * @param customKey - The custom key to insert.
+     * @param waitForIndex - Per-request synchronous-index override. `true` → the write
+     *   returns only after its secondary indexes are updated (read-your-writes); `false`
+     *   → fire-and-forget indexing; `null` (default) → use the DB-wide default (see
+     *   `Engine.enable/disableWaitForIndex`). Applies to persistent writes.
      * @return A promise that resolves with the result of the insertion.
      */
-    static insertCustomKey({ customKey }: {
+    static insertCustomKey({ customKey, waitForIndex }: {
         customKey: string;
+        waitForIndex?: boolean | null;
     }): Promise<any>;
     /**
      * Inserts a custom key-value pair into the persistent store.
      * @param customKey - The custom key for the value.
      * @param value - The value to insert.
+     * @param waitForIndex - Per-request synchronous-index override; null (default) uses the DB-wide default.
      * @return A promise that resolves with the result of the insertion.
      */
-    static insertCustomKeyValue({ customKey, value }: {
+    static insertCustomKeyValue({ customKey, value, waitForIndex }: {
         customKey: string;
         value?: any;
+        waitForIndex?: boolean | null;
     }): Promise<any>;
     /**
      * Updates a value in the persistent store.
      * @param key - The key for the value to update.
      * @param customKey - The custom key for the value to update.
      * @param value - The new value to set.
+     * @param waitForIndex - Per-request synchronous-index override; null (default) uses the DB-wide default.
      * @return A promise that resolves with the result of the update.
      */
-    static updateValue({ key, customKey, value }?: {
+    static updateValue({ key, customKey, value, waitForIndex }?: {
         key?: string;
         customKey?: string | null;
         value?: any;
+        waitForIndex?: boolean | null;
     }): Promise<any>;
     /**
      * Inserts multiple key-value pairs into the persistent store in bulk.
      * @param bulk - An array of key-value pairs to insert.
+     * @param waitForIndex - Per-request synchronous-index override; null (default) uses the DB-wide default.
      * @return A promise that resolves with the result of the bulk insertion.
      */
-    static insertBulk({ bulk }?: {
+    static insertBulk({ bulk, waitForIndex }?: {
         bulk?: any[];
+        waitForIndex?: boolean | null;
     }): Promise<any>;
     /**
      * Retrieves keys from the persistent store based on provided options.

package/dist/core/persistent.js

@@ -17,36 +17,41 @@ class Persistent extends GenericKV {
      * @param value - The value to insert.
      * @return A promise that resolves with the result of the insertion.
      */
-    static async insertValue({ value = {} } = {}) {
+    static async insertValue({ value = {}, waitForIndex = null } = {}) {
         this.command = "insert_value";
-        const query = convertToBinaryQuery(this, { value });
+        const query = convertToBinaryQuery(this, { value, waitForIndex });
         return runQuery(this, query);
     }
     /**
      * Inserts a custom key into the persistent store.
      * @param customKey - The custom key to insert.
+     * @param waitForIndex - Per-request synchronous-index override. `true` → the write
+     *   returns only after its secondary indexes are updated (read-your-writes); `false`
+     *   → fire-and-forget indexing; `null` (default) → use the DB-wide default (see
+     *   `Engine.enable/disableWaitForIndex`). Applies to persistent writes.
      * @return A promise that resolves with the result of the insertion.
      */
-    static async insertCustomKey({ customKey }) {
+    static async insertCustomKey({ customKey, waitForIndex = null }) {
         if (!customKey) {
             throw new Error("No key provided");
         }
         this.command = "insert_custom_key";
-        const query = convertToBinaryQuery(this, { key: convertCustomKey(customKey) });
+        const query = convertToBinaryQuery(this, { key: convertCustomKey(customKey), waitForIndex });
         return runQuery(this, query);
     }
     /**
      * Inserts a custom key-value pair into the persistent store.
      * @param customKey - The custom key for the value.
      * @param value - The value to insert.
+     * @param waitForIndex - Per-request synchronous-index override; null (default) uses the DB-wide default.
      * @return A promise that resolves with the result of the insertion.
      */
-    static async insertCustomKeyValue({ customKey, value = {} }) {
+    static async insertCustomKeyValue({ customKey, value = {}, waitForIndex = null }) {
         if (!customKey) {
             throw new Error("No key provided");
         }
         this.command = "insert_custom_key_value";
-        const query = convertToBinaryQuery(this, { key: convertCustomKey(customKey), value });
+        const query = convertToBinaryQuery(this, { key: convertCustomKey(customKey), value, waitForIndex });
         return runQuery(this, query);
     }
     /**
@@ -54,28 +59,30 @@ class Persistent extends GenericKV {
      * @param key - The key for the value to update.
      * @param customKey - The custom key for the value to update.
      * @param value - The new value to set.
+     * @param waitForIndex - Per-request synchronous-index override; null (default) uses the DB-wide default.
      * @return A promise that resolves with the result of the update.
      */
-    static async updateValue({ key = "", customKey = null, value = {} } = {}) {
+    static async updateValue({ key = "", customKey = null, value = {}, waitForIndex = null } = {}) {
         const effectiveKey = customKey ? convertCustomKey(customKey) : key;
         if (!effectiveKey) {
             throw new Error("No key provided");
         }
         this.command = "update_value";
-        const query = convertToBinaryQuery(this, { key: effectiveKey, value });
+        const query = convertToBinaryQuery(this, { key: effectiveKey, value, waitForIndex });
         return runQuery(this, query);
     }
     /**
      * Inserts multiple key-value pairs into the persistent store in bulk.
      * @param bulk - An array of key-value pairs to insert.
+     * @param waitForIndex - Per-request synchronous-index override; null (default) uses the DB-wide default.
      * @return A promise that resolves with the result of the bulk insertion.
      */
-    static async insertBulk({ bulk = [] } = {}) {
+    static async insertBulk({ bulk = [], waitForIndex = null } = {}) {
         if (!bulk || bulk.length === 0) {
             throw new Error("No values provided");
         }
         this.command = "insert_bulk";
-        const query = convertToBinaryQuery(this, { bulkValues: bulk });
+        const query = convertToBinaryQuery(this, { bulkValues: bulk, waitForIndex });
         return runQuery(this, query);
     }
     /**

package/dist/functions/storeGenericFunctions.js

@@ -58,12 +58,12 @@ function processBulkKeysValues(bulkKeysValues) {
  * @returns A JSON string representing the binary query.
  * */
 function convertToBinaryQuery(cls, options = {}) {
-    const { key = null, value = {}, expireSec = 0, bulkValues = [], bulkKeys = [], bulkKeysValues = {}, searchCriteria = {}, limitOutput = { start: 0, stop: 0 }, withPointers = false, schema = null, keyIncluded = false, pointersMetadata = false, volumes = [], latestVolume = false, } = options;
+    const { key = null, value = {}, expireSec = 0, bulkValues = [], bulkKeys = [], bulkKeysValues = {}, searchCriteria = {}, limitOutput = { start: 0, stop: 0 }, withPointers = false, schema = null, keyIncluded = false, pointersMetadata = false, volumes = [], latestVolume = false, semanticQuery = null, minScore = null, waitForIndex = null, } = options;
     const { processedValue, foundSchema } = processValue(value);
     const { processedBulkValues, uniqueSchema } = processBulkValues(bulkValues);
     const bulkKeysValuesProcessed = processBulkKeysValues(bulkKeysValues);
     const processedSearchCriteria = processSearchCriteria(searchCriteria);
-    return JSON.stringify({
+    const queryDict = {
         username: cls.username,
         password: cls.password,
         namespace: cls.namespace,
@@ -79,14 +79,27 @@ function convertToBinaryQuery(cls, options = {}) {
         bulk_values: processedBulkValues.map(v => JSON.stringify(v)),
         bulk_keys: bulkKeys,
         bulk_keys_values: bulkKeysValuesProcessed,
-        search_criteria: JSON.stringify(processedSearchCriteria),
+        // `semantic_search` sends the raw query text (the engine trims it as a
+        // plain string); every other command sends a JSON-encoded filter map.
+        search_criteria: semanticQuery !== null ? semanticQuery : JSON.stringify(processedSearchCriteria),
         with_pointers: withPointers,
         schema: foundSchema ? foundSchema : uniqueSchema ? uniqueSchema : schema,
         key_included: keyIncluded,
         pointers_metadata: pointersMetadata,
         volumes,
         latest_volume: latestVolume,
-    });
+    };
+    // Only `semantic_search` honors min_score; omit it otherwise so the wire is
+    // unchanged for existing commands (the engine defaults the field to None).
+    if (minScore !== null) {
+        queryDict.min_score = minScore;
+    }
+    // Per-request wait_for_index override for persistent writes; omit when null
+    // so the server falls back to its DB-wide default (existing wire unchanged).
+    if (waitForIndex !== null) {
+        queryDict.wait_for_index = waitForIndex;
+    }
+    return JSON.stringify(queryDict);
 }
 function processSearchCriteria(searchCriteria) {
     const processedCriteria = {};

package/package.json

@@ -1,20 +1,52 @@
 {
   "name": "montycat",
-  "version": "1.1.5",
-  "description": "A Node.js client for Montycat, NoSQL database utilizing Data Mesh architecture.",
+  "version": "1.1.7",
+  "description": "Self-hosted vector database + NoSQL with built-in AI semantic search — the Node.js & TypeScript client for Montycat. A Rust-powered, AI-native Pinecone / Weaviate / Chroma alternative for RAG, AI agents & LLM memory.",
   "type": "module",
   "main": "dist/index.js",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
+  "homepage": "https://montygovernance.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MontyGovernance/montycat_node.git"
+  },
+  "bugs": {
+    "url": "https://github.com/MontyGovernance/montycat_node/issues"
+  },
   "keywords": [
+    "vector-database",
+    "vector-search",
+    "semantic-search",
+    "embeddings",
+    "similarity-search",
+    "knn",
+    "hnsw",
     "database",
     "nosql",
-    "sql",
+    "database-client",
+    "rag",
+    "retrieval-augmented-generation",
+    "ai",
+    "ai-agents",
+    "agent-memory",
+    "ai-memory",
+    "llm",
+    "mcp",
+    "self-hosted",
+    "embedded-database",
+    "pinecone-alternative",
+    "weaviate-alternative",
+    "chroma-alternative",
+    "qdrant-alternative",
+    "redis-alternative",
     "data-mesh",
-    "cache",
-    "lsm",
-    "key-value",
+    "async",
+    "typescript",
+    "rust",
     "realtime",
+    "key-value",
+    "cache",
     "montycat"
   ],
   "exports": {
@@ -23,8 +55,14 @@
       "types": "./dist/index.d.ts"
     }
   },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "dist"
+  ],
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1",
+    "test": "tsc --noEmit",
     "build": "tsc",
     "start": "node dist/index.js",
     "dev": "tsc --watch"
@@ -39,7 +77,6 @@
   "license": "MIT",
   "dependencies": {
     "json-bigint": "^1.0.0",
-    "xxhash-wasm": "^1.0.2",
     "xxhashjs": "^0.2.2"
   }
 }