@wiscale/velesdb-sdk 1.15.0 → 1.18.0

package/LICENSE

@@ -1,27 +1,363 @@
-MIT License
+VelesDB Core License 1.0
 
-Copyright (c) 2024-2026 Wiscale France
+Based on the Elastic License 2.0 (ELv2) — Adapted for VelesDB Core
 
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
+Copyright (c) 2024-2026 Wiscale France. All rights reserved.
 
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
+VelesDB® is a registered trademark of Wiscale France.
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+---
+
+## Acceptance
+
+By using the Software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The Licensor grants you a non-exclusive, royalty-free, worldwide, non-sublicensable, non-transferable license to use, copy, distribute, make available, and prepare derivative works of the Software, in each case subject to the limitations and conditions below.
+
+## Limitations
+
+### 1) No Hosted or Managed Service
+
+You may not provide the Software to third parties as a Hosted or Managed Service.
+
+A "Hosted or Managed Service" is any service where You (or a third party acting on Your behalf) host, operate, or make available the Software — directly or indirectly — to third parties who are provided access to a Substantial Set of the Software's features or functionality.
+
+This restriction includes, without limitation:
+
+- offering the Software as a cloud service, hosted service, managed service, or database-as-a-service (DBaaS),
+- operating the Software for third parties, including as a managed service provider (MSP), outsourcer, consultant, hosting provider, or service provider, even if provided to a single customer,
+- exposing the Software's query, administration, indexing, ingestion, storage, graph traversal, knowledge graph, columnar filtering, or management capabilities (or any substantially similar capabilities) to third parties through any interface, including but not limited to: APIs, SDKs, web interfaces, command lines, gateways, middleware, service layers, application wrappers, proxy layers, or any other programmatic or interactive mechanism.
+
+If third parties can store data in, query, manage collections or indexes, traverse or manage graph nodes and edges, filter structured data, administer schemas, or otherwise use the Software as a database, vector database, graph database, knowledge graph engine, columnar store, search engine, or query engine — whether directly or through any intermediary layer — this constitutes a Hosted or Managed Service and requires a separate commercial license from the Licensor.
+
+### 2) No Competitive Offering
+
+You may not use the Software to build, sell, offer, operate, or otherwise make commercially available any product or service that is Substantially Similar to the Software or that competes with the Software as:
+
+- a database,
+- a vector database,
+- a graph database or knowledge graph engine,
+- a columnar store or analytical engine,
+- a search engine,
+- a query engine, or
+- a hybrid search, retrieval, or multi-model data system.
+
+This restriction applies whether the product is offered as software, as a service, or as a component of a larger offering, and regardless of whether the Software's code is modified.
+
+This restriction does NOT prohibit:
+
+- internal use of the Software within your own organization,
+- integration of the Software as a backend component of your own product or service (provided end users receive only the results of your application and are not given access to the Software's core database capabilities),
+- use of the Software to power features such as search, retrieval, ranking, recommendations, or RAG within your own product.
+
+### 3) No Circumvention of Paid Features
+
+You may not move, change, disable, or circumvent any licensing mechanism or functionality that enforces paid features, and you may not remove or obscure any functionality in the Software that is protected by such licensing mechanism.
+
+### 4) No Removal of Notices; Trademarks
+
+You may not alter, remove, or obscure any licensing, copyright, or other notices of the Licensor in the Software. Any use of the Licensor's trademarks is subject to applicable law.
+
+### 5) Benchmarking
+
+You may conduct and publish benchmarks of the Software, provided that any public disclosure of benchmark results includes all of the following:
+
+- the benchmarking methodology used,
+- the dataset(s) used (including size, type, and source),
+- the hardware configuration (CPU, RAM, storage, network),
+- the software version of VelesDB Core tested,
+- the full configuration of the Software as tested (including relevant parameters, tuning, and index settings),
+- any other software or tools used in the benchmark.
+
+The purpose of this requirement is transparency and reproducibility, not restriction. Benchmarks that omit this information may not be published or distributed publicly.
+
+## Redistribution
+
+### Attribution for Public-Facing Applications
+
+If You deploy or make publicly available an Application or Service that uses the Software as a component — including SaaS products, web applications, mobile applications, or browser-based applications — You must include a visible attribution notice containing a hyperlink to https://velesdb.com.
+
+**Placement:** The notice must appear in at least one location that is accessible to end users without requiring a separate action (e.g., not solely in source code or internal documentation). Acceptable placements include, but are not limited to:
+
+- a website footer or sidebar;
+- an application's About, Credits, or Settings page;
+- API documentation or developer portal;
+- a README or landing page for open-source projects that integrate the Software.
+
+**Format:** The notice may take any reasonable form, such as:
+
+- "Powered by [VelesDB](https://velesdb.com)"
+- "Built with [VelesDB](https://velesdb.com)"
+- The VelesDB logo (available at https://velesdb.com/brand) linking to https://velesdb.com
+
+The key requirement is a **clickable link to https://velesdb.com** that is visible to end users.
+
+**Exemptions:** This requirement does not apply to:
+- internal use within your organization;
+- development, testing, or staging environments;
+- holders of a VelesDB Enterprise or Premium license (which may include waived or alternative attribution terms — contact contact@wiscale.fr).
+
+Failure to comply with this attribution requirement constitutes a violation of this license.
+
+### Redistribution Terms
+
+You may redistribute the Software (in original or modified form), including through container images (e.g., Docker), installers, package managers (e.g., Homebrew, apt, cargo), infrastructure-as-code templates (e.g., Terraform, Helm), or any other distribution mechanism, provided that:
+
+1. a complete copy of this license is included with each distribution,
+2. all copyright and licensing notices in the Software are preserved and unmodified,
+3. the redistributed Software remains governed by this license (you may not relicense it under different terms),
+4. if modified, the distribution includes prominent notices stating that you have modified the Software, and
+5. redistribution does not grant recipients any right to provide the Software as a Hosted or Managed Service.
+
+For the avoidance of doubt, redistribution of the Software does not, by itself, constitute a Hosted or Managed Service, provided that the recipient operates the Software for its own internal use and not for the benefit of third parties.
+
+## Permitted Use (Clarification)
+
+You may use the Software in production, including for commercial purposes, and you may embed or integrate the Software into your own products and services, provided that:
+
+- the Software is used only as an internal component of your product or service, and
+- your end users are not provided access to a Substantial Set of the Software's features or functionality.
+
+For example, it is permitted to use the Software internally to power features such as:
+
+- search and retrieval,
+- retrieval-augmented generation (RAG),
+- ranking and recommendations,
+- document indexing and similarity matching,
+- knowledge graph traversal and relationship discovery,
+- structured data filtering and analytics,
+- any other feature where end users receive only the results produced by your application and do not receive access to the Software itself.
+
+**Embedded and local-first use.** The Software is designed to run as an embedded database (in-process, WASM, mobile, desktop, or server). Using the Software in embedded mode within your own application — including in browser-based (WASM), mobile (iOS/Android), desktop (Tauri), or server-side deployments — is expressly permitted under this license, provided the Software serves only as an internal component and end users do not receive direct access to the Software's database capabilities.
+
+## Business Model Clarification
+
+The Licensor offers the Software under a multi-tier model:
+
+- **VelesDB Core** — available under this license (source-available, free for permitted use).
+- **VelesDB Enterprise** — available under a separate commercial license for advanced features, support, and use cases not permitted under this license.
+- **VelesDB Cloud** — the Licensor's proprietary managed database service.
+
+Any use of the Software as a Hosted or Managed Service, as a Competitive Offering, or in any other manner not permitted by this license requires a separate **Enterprise** or **Premium** commercial license from the Licensor.
+
+## Examples (Non-Normative)
+
+### Allowed under this license
+
+- Your application uses VelesDB Core internally to power search, retrieval, or RAG, and customers cannot create or manage collections, indexes, or databases, nor run arbitrary queries against VelesDB Core.
+- You distribute VelesDB Core bundled with a desktop, mobile, or on-premise application for the customer's own internal use.
+- You use VelesDB Core as a backend for your SaaS product, where end users interact only with your application's interface and receive only processed results.
+- You publish benchmark results comparing VelesDB Core to other databases, with full methodology disclosure.
+- You redistribute VelesDB Core via Docker Hub, a package manager, or an infrastructure template, with this license included.
+
+### Requires a commercial (Enterprise/Premium) license
+
+- Offering VelesDB Core (or a derivative) as a hosted, managed, or cloud database service (DBaaS), regardless of whether it is branded as "VelesDB" or under a different name.
+- Operating VelesDB Core for a customer as a managed service provider, outsourcer, or consultant, where the customer has access to the Software's core capabilities.
+- Building and selling a product that competes with VelesDB as a vector database, search engine, or query engine.
+- A cloud provider offering VelesDB as a managed database, managed cluster, hosted indexing/query platform, or vector database as a service.
+- A multi-tenant service where tenants have access to the Software's database-like capabilities (collections, indexes, schemas, queries, ingestion).
+- Any service — regardless of the interface layer or branding — where third parties can effectively use the Software as a database.
+
+## Patents
+
+The Licensor grants you a license, under any patent claims the Licensor can license, or becomes able to license, to make, have made, use, sell, offer for sale, import and have imported the Software, in each case subject to the limitations and conditions in this license.
+
+This license does not cover any patent claims that you cause to be infringed by modifications or additions to the Software.
+
+If you or your company make any written claim that the Software infringes or contributes to infringement of any patent, your patent license for the Software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the Software from you also gets a copy of these terms.
+
+If you modify the Software, you must include in any modified copies of the Software prominent notices stating that you have modified the Software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in these terms.
+
+## Termination
+
+If you use the Software in violation of these terms, such use is not licensed, and your licenses will automatically terminate.
+
+If the Licensor provides you with a notice of your violation, and you cease all violation of this license no later than 30 days after you receive that notice, your licenses will be reinstated retroactively. However, if you violate these terms after such reinstatement, any additional violation of these terms will cause your licenses to terminate automatically and permanently.
+
+## No Liability
+
+As far as the law allows, the Software comes as is, without any warranty or condition, and the Licensor will not be liable to you for any damages arising out of these terms or the use or nature of the Software, under any kind of legal claim.
+
+## Definitions
+
+The **"Licensor"** is Wiscale France.
+
+The **"Software"** is the software the Licensor makes available under these terms, including VelesDB Core and all associated components, libraries, tools, and documentation.
+
+The **"Author"** is Julien Lange.
+
+**"You"** refers to the individual or entity agreeing to these terms.
+
+**"Your company"** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization. "Control" means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise. Control can be direct or indirect.
+
+**"Your licenses"** are all the licenses granted to you for the Software under these terms.
+
+**"Use"** means anything you do with the Software requiring one of your licenses.
+
+**"Hosted or Managed Service"** means any service, platform, or offering where You (or a third party acting on Your behalf) host, operate, or make available the Software for third parties, and those third parties are provided with access — directly or indirectly — to a Substantial Set of the Software's features or functionality. Access includes, without limitation, access through any of the following: APIs, SDKs, web interfaces, command lines, gateways, middleware, service layers, application wrappers, proxy layers, webhooks, message queues, or any other programmatic or interactive mechanism that enables third parties to create, manage, query, administer, index, ingest, store, traverse graphs, manage knowledge graph nodes or edges, filter structured data, or otherwise use the Software's core database, vector, graph, columnar, or hybrid capabilities.
+
+**"Substantial Set of features or functionality"** means access to features or functionality that, taken together, would reasonably allow a third party to use the Software as a general-purpose database, vector database, graph database, knowledge graph engine, columnar store, search engine, query engine, or hybrid/multi-model data system, or as a replacement for the Software, rather than merely receiving the results of your product's or application's features.
+
+**"Substantially Similar"** means a product or service that provides database, vector database, graph database, knowledge graph, columnar store, search engine, query engine, hybrid search, or multi-model data capabilities that overlap in purpose and function with the core capabilities of the Software to a degree that would reasonably be considered competitive. A product is not Substantially Similar merely because it uses the Software internally as a component.
+
+**"Competitive Offering"** means any product or service that is Substantially Similar to the Software and is made commercially available to third parties, whether as software, as a service, or as a component of a larger offering.
+
+**"Cloud Provider"** means any entity that provides cloud computing infrastructure, platform, or software services to third parties, including (without limitation) infrastructure-as-a-service (IaaS), platform-as-a-service (PaaS), and software-as-a-service (SaaS) providers.
+
+---
+
+## Licensing FAQ (VelesDB Core License 1.0)
+
+This FAQ is provided for convenience and developer guidance only. It does not replace, modify, or supplement the license terms above. In case of any conflict, the license terms prevail. If in doubt, contact the Licensor (Wiscale France — contact@wiscale.fr).
+
+### 1) Can I use VelesDB Core in production?
+
+**Yes.** Production use is permitted, including commercial production use, as long as you comply with the license limitations (no Hosted or Managed Service, no Competitive Offering).
+
+### 2) Can I use VelesDB Core inside my own SaaS product?
+
+**Yes.** If VelesDB Core is used only as an internal component of your SaaS and your customers interact only with your application's interface (not with VelesDB directly), this is permitted.
+
+In practice: your customers can use your app's features (search, RAG, recommendations, etc.), but they cannot create collections, manage indexes, run arbitrary queries, or otherwise use VelesDB as a database product.
+
+### 3) Can I use VelesDB Core as a backend for a RAG system?
+
+**Yes.** Using VelesDB Core to index documents, store embeddings, and retrieve results for a RAG pipeline is a typical permitted use case, as long as end users receive only the generated answers from your application and do not have direct database access.
+
+### 4) What is NOT allowed without a commercial license?
+
+- Offering VelesDB Core (or a derivative) as a hosted or managed database service (DBaaS, vector DB as a service, managed cluster, etc.).
+- Operating VelesDB Core for a customer as an MSP, outsourcer, or consultant where the customer has access to VelesDB's core capabilities.
+- Building and selling a competing database, vector database, search engine, or query engine based on VelesDB Core.
+- A cloud provider (e.g., AWS, GCP, Azure, or any other) offering VelesDB as a managed database service.
+
+If you want to do any of the above, you need an **Enterprise or Premium license**.
+
+### 5) Can I expose a public API endpoint that runs vector search against VelesDB Core?
+
+**It depends:**
+
+- **Allowed:** You expose an endpoint like `/search` or `/recommend` that returns results for your product, without giving customers the ability to create/manage collections, ingest vectors, manage indexes, run arbitrary queries, or administer the database.
+- **Not allowed without a commercial license:** You expose VelesDB-like capabilities (collections, ingestion, indexing, querying, admin) to third parties in a way that makes your service effectively "VelesDB as a service."
+
+### 6) Can I let my customers upload documents, and I index them in VelesDB Core for RAG?
+
+**Yes.** As long as customers are using your product's document upload feature and are not given direct access to VelesDB's database capabilities (no collection management, no arbitrary queries, no index administration).
+
+### 7) Can a cloud provider offer VelesDB as a managed service?
+
+**No, not under this license.** Cloud providers (or any third party) offering VelesDB as a managed database, DBaaS, managed cluster, hosted indexing/query platform, or vector database as a service must obtain a commercial license from Wiscale France.
+
+### 8) Can an agency, consultant, or MSP host VelesDB Core for a client?
+
+**Not under this license** if the arrangement constitutes a Hosted or Managed Service (including single-customer managed hosting where the client has access to VelesDB's core capabilities). That scenario requires a commercial license.
+
+### 9) Can I embed VelesDB Core in a desktop, mobile, or on-prem product I sell?
+
+**Yes.** Distributing VelesDB Core bundled with your product is permitted, provided you comply with the license (include the license text and notices), and you are not providing it as a Hosted or Managed Service.
+
+### 10) Can I modify VelesDB Core and keep my changes private?
+
+**Yes.** The license allows modification. If you distribute a modified version, you must include prominent notices stating that you modified it, and you must provide a copy of the license terms to recipients.
+
+### 11) Can I redistribute VelesDB Core?
+
+**Yes.** You may redistribute the Software (as-is or modified) through any mechanism (Docker, package managers, Helm charts, etc.), provided:
+
+- the license text is included,
+- copyright notices are preserved,
+- the software remains under this license,
+- if modified, modifications are prominently marked.
+
+Redistribution does not grant recipients any right to provide the Software as a Hosted or Managed Service.
+
+### 12) Can I publish benchmarks of VelesDB Core?
+
+**Yes.** You are encouraged to benchmark VelesDB Core. However, public benchmark results must include full disclosure of methodology, dataset, hardware, software version, and configuration. This ensures transparency and reproducibility.
+
+### 13) Can I build a competing database product using VelesDB Core?
+
+**No.** The No Competitive Offering clause prohibits using the Software to build, sell, or offer a product that competes with VelesDB as a database, vector database, graph database, columnar store, search engine, or query engine.
+
+However, using VelesDB Core as an internal component of a non-competing product (e.g., a CRM, an e-commerce platform, a content management system) is permitted.
+
+### 14) Can I remove license headers or copyright notices?
+
+**No.** You may not alter, remove, or obscure licensing, copyright, or other notices.
+
+### 15) Can I use the name "VelesDB" for my fork?
+
+**No.** VelesDB® is a registered trademark of Wiscale France. You may not brand your fork, derivative work, or product as "VelesDB" without written permission from Wiscale France. Use of the VelesDB name or logo is subject to applicable trademark law.
+
+### 16) What about a multi-tenant service where each tenant only has limited features?
+
+If tenants (third parties) get access to a Substantial Set of VelesDB's database, vector database, or query capabilities, it is a Hosted or Managed Service and requires a commercial license, regardless of the number of features exposed per tenant.
+
+### 17) What if my service wraps VelesDB behind an API gateway or middleware?
+
+The license explicitly covers indirect access through APIs, SDKs, gateways, middleware, service layers, and application wrappers. If the end result is that third parties can use the Software as a database — regardless of how many layers sit between them and VelesDB — a commercial license is required.
+
+### 18) What if I'm unsure whether my use case is permitted?
+
+**Ask.** Contact Wiscale France (contact@wiscale.fr) for clarification or to discuss a commercial license. We want developers to build great things with VelesDB — we're happy to help you find the right license for your use case.
+
+### 19) How do I get an Enterprise or Premium license?
+
+Contact Wiscale France (contact@wiscale.fr) to discuss licensing for hosted/managed services, Competitive Offerings, cloud provider partnerships, and other premium use cases.
+
+### 20) What is the difference between VelesDB Core, Enterprise, and Cloud?
+
+| Tier | License | Use Case |
+|------|---------|----------|
+| **VelesDB Core** | This license (source-available) | Internal use, embedding, SaaS backend, development, testing |
+| **VelesDB Enterprise** | Commercial license | Advanced features, support, hosted/managed services, competitive offerings |
+| **VelesDB Cloud** | Proprietary SaaS | Fully managed database service operated by Wiscale France |
+
+### 21) Can I use VelesDB's graph engine and knowledge graph features in my product?
+
+**Yes.** You can use the vector, graph, columnar, and hybrid search features internally within your product. The restriction applies only if you expose those capabilities directly to third parties as a database service, or if you build a competing graph/vector/search product.
+
+### 22) Can I embed VelesDB in a browser (WASM), mobile app, or Tauri desktop app?
+
+**Yes.** Embedded and local-first use is expressly permitted. VelesDB is designed to run in-process (WASM, iOS, Android, Tauri, server). As long as the Software serves as an internal component of your application, this is a permitted use.
+
+### 23) Does the license cover the premium features (Hybrid Search, RBAC, SSO, etc.)?
+
+The VelesDB Core license covers VelesDB Core. Premium features (such as RBAC, SSO, GPU Acceleration, Audit Logging, Multi-Tenancy, Encryption at Rest, and Snapshots) are available under VelesDB Enterprise with a separate commercial license. You may not circumvent the licensing mechanism that enforces premium features.
+
+### 24) Can I use VelesDB Core's VelesQL query language in my product?
+
+**Yes.** Using VelesQL to query data internally within your product is permitted. However, exposing a general-purpose VelesQL endpoint to third parties (allowing them to run arbitrary queries) would constitute providing access to a Substantial Set of the Software's capabilities and is not permitted without a commercial license.
+
+### 25) Do I need to display "Powered by VelesDB" on my website or app?
+
+**Yes, if your app is public.** Include a link to velesdb.com somewhere visible — footer, About page, credits, or docs. That's it. No specific size, color, or position required. Just a clickable link that users can find.
+
+Want to remove it? An Enterprise license waives the attribution requirement.
+
+### 26) What counts as a "public-facing application"?
+
+Anything accessible by people outside your organization: a SaaS product, a public website, a mobile app on app stores, a public API. Internal tools and staging environments don't count.
+
+### 27) Can I use the VelesDB logo instead of text?
+
+**Yes.** Logo or text, your choice — as long as it links to velesdb.com. Brand assets are at https://velesdb.com/brand.
 
 ---
 
-Note: This MIT license applies to the TypeScript SDK code only.
-VelesDB Core itself is licensed under the Elastic License 2.0 (ELv2).
-See https://github.com/cyberlife-coder/VelesDB for VelesDB Core licensing.
+## Trademark Notice
+
+VelesDB® is a registered trademark of Wiscale France. All rights reserved.
+
+Use of the VelesDB name, logo, or brand assets is subject to applicable trademark law. You may not use the VelesDB name or logo to imply endorsement, affiliation, or sponsorship by Wiscale France without prior written permission. Forks and derivative works must not be branded as "VelesDB" without explicit authorization from Wiscale France.

package/README.md

@@ -2,11 +2,15 @@
 
 Official TypeScript SDK for [VelesDB](https://github.com/cyberlife-coder/VelesDB) -- the local-first vector database for AI and RAG. Sub-millisecond semantic search in Browser and Node.js.
 
-**v1.15.0** | Node.js >= 18 | Browser (WASM) | MIT License
+**v1.18.0** | Node.js >= 18 | Browser (WASM) | VelesDB Core License 1.0
 
-## What's New in v1.14.2
+## What's New in v1.16.0
 
-- **No SDK source change.** v1.14.2 is a workspace patch focused on the Python Haystack `DocumentStore` (`DuplicatePolicy.SKIP` contract fix) and seven version-drift gaps in the release tooling. The TS SDK ships in lock-step with the workspace and is functionally identical to v1.14.1; the version bump only ensures `npm install @wiscale/velesdb-sdk` resolves to the same release line as `pip install velesdb` and `cargo add velesdb-core@1.14.2`.
+- **First-party embedding helper.** New `OpenAIEmbedder` (plus the `Embedder` interface and `OpenAIEmbedderOptions` type), exported from the package root. It calls any OpenAI-compatible `/embeddings` endpoint via the global `fetch` API — no extra runtime dependency — so you can go from text to vectors without hand-writing the request. See [Embedding helper](#embedding-helper) below. Works in Node.js ≥ 18, browsers, and Deno.
+
+### Previous (v1.14.2)
+
+- **No SDK source change.** v1.14.2 was a workspace patch focused on the Python Haystack `DocumentStore` (`DuplicatePolicy.SKIP` contract fix) and seven version-drift gaps in the release tooling. The TS SDK ships in lock-step with the workspace and was functionally identical to v1.14.1.
 
 ### Previous (v1.14.1)
 
@@ -125,6 +129,7 @@ await db.upsertBatch('documents', [
 ]);
 
 // 5. Search for similar vectors
+const queryVector = new Float32Array(768).fill(0.1);
 const results = await db.search('documents', queryVector, { k: 5 });
 console.log(results);
 // [{ id: 'doc-1', score: 0.95, payload: { title: 'Hello World', ... } }, ...]
@@ -151,6 +156,7 @@ await db.init();
 // Same API as WASM backend
 await db.createCollection('products', { dimension: 1536 });
 await db.upsert('products', { id: 1, vector: embedding });
+const queryVector = new Float32Array(1536).fill(0.1);
 const results = await db.search('products', queryVector, { k: 10 });
 ```
 
@@ -161,6 +167,39 @@ const results = await db.search('products', queryVector, { k: 10 });
 > are accepted for backward compatibility but are deprecated and will be removed
 > in a future major version. Always target `/v1/` in custom HTTP clients.
 
+## Embedding helper
+
+The SDK ships an optional `OpenAIEmbedder` so you can turn text into vectors without
+writing the HTTP call yourself. It targets any OpenAI-compatible `/embeddings`
+endpoint (OpenAI, Azure OpenAI, vLLM, …) using the global `fetch` API, so it adds
+**no extra runtime dependency** and runs in Node.js ≥ 18, browsers, and Deno.
+
+```typescript
+import { VelesDB, OpenAIEmbedder } from '@wiscale/velesdb-sdk';
+
+const embedder = new OpenAIEmbedder({
+  apiKey: process.env.OPENAI_API_KEY!,
+  model: 'text-embedding-3-small', // default; pass `dimensions` to truncate
+});
+
+const db = new VelesDB({ backend: 'wasm' });
+await db.init();
+
+// Embed first so the collection dimension matches the model output.
+const vectors = await embedder.embed(['hello world', 'vector search']);
+await db.createCollection('docs', { dimension: embedder.dimension, metric: 'cosine' });
+await db.upsertBatch('docs', vectors.map((vector, i) => ({ id: `doc-${i}`, vector })));
+
+const [query] = await embedder.embed(['greeting']);
+const results = await db.search('docs', query, { k: 5 });
+```
+
+`embedder.dimension` is `0` until the first `embed()` call (or until you pass
+`dimensions` to the constructor), at which point it is inferred from the model's
+output. To use a different provider, set `baseUrl`. Implement the `Embedder`
+interface (`{ dimension: number; embed(texts: string[]): Promise<number[][]> }`)
+to plug in any other embedding source.
+
 ## API Reference
 
 ### Client
@@ -312,7 +351,7 @@ Vector similarity search.
 ```typescript
 const results = await db.search('docs', queryVector, {
   k: 10,
-  filter: { category: 'tech' },
+  filter: { condition: { type: 'eq', field: 'category', value: 'tech' } },
   includeVectors: true
 });
 // Returns: SearchResult[] = [{ id, score, payload?, vector? }, ...]
@@ -325,7 +364,7 @@ Execute multiple search queries in parallel.
 ```typescript
 const batchResults = await db.searchBatch('docs', [
   { vector: queryA, k: 5 },
-  { vector: queryB, k: 10, filter: { type: 'article' } },
+  { vector: queryB, k: 10, filter: { condition: { type: 'eq', field: 'type', value: 'article' } } },
 ]);
 // Returns: SearchResult[][] (one result array per query)
 ```
@@ -538,7 +577,7 @@ const combined = await db.query('users',
 
 // Fusion strategy
 const fused = await db.query('docs',
-  "SELECT * FROM docs USING FUSION(strategy = 'rrf', k = 60) LIMIT 20"
+  "SELECT * FROM docs LIMIT 20 USING FUSION(strategy = 'rrf', k = 60)"
 );
 ```
 
@@ -733,7 +772,21 @@ const result = await db.trainPq('embeddings', {
 
 ### Agent Memory API
 
-The Agent Memory API provides three memory types for AI agents, built on top of VelesDB's vector and graph storage.
+The Agent Memory API provides three memory types for AI agents, built on top of
+VelesDB's vector storage. In the TypeScript/JavaScript SDK it is accessed **over
+REST** against a running `velesdb-server` (the Python and Rust bindings use the
+embedded engine instead).
+
+> **You must create the collection first.** The TS facade does **not**
+> auto-create a collection for you. Create it with the dimension that matches
+> your embedding model and the metric you want (`'cosine'` is the usual choice
+> for normalized text embeddings), then call `storeFact` / `recordEvent` /
+> `learnProcedure` against that same collection name.
+
+> **Embeddings are caller-supplied.** There is no auto-embedding: every
+> `embedding` you pass must come from your own embedding model (see
+> [Embedding helper](#embedding-helper)) and its length must equal the
+> collection dimension.
 
 ```typescript
 import { VelesDB } from '@wiscale/velesdb-sdk';
@@ -741,13 +794,39 @@ import { VelesDB } from '@wiscale/velesdb-sdk';
 const db = new VelesDB({ backend: 'rest', url: 'http://localhost:8080' });
 await db.init();
 
+// 1. Create the backing collection FIRST (nothing auto-creates it).
+//    The dimension must match your embedding model; cosine is typical.
+await db.createCollection('knowledge', { dimension: 384, metric: 'cosine' });
+
+// 2. Open the agent-memory facade.
 const memory = db.agentMemory({ dimension: 384 });
+
+// 3. Store and recall (embedding is your own model's output, length 384).
+await memory.storeFact('knowledge', {
+  id: 1,
+  text: 'VelesDB uses HNSW for vector indexing',
+  embedding: factEmbedding,
+});
+const facts = await memory.searchFacts('knowledge', queryEmbedding, 5);
+```
+
+Each recall method returns `SearchResult[]`:
+
+```typescript
+// SearchResult = { id: number; score: number; payload?: Record<string, unknown>; vector?: number[] }
 ```
 
+- `score` is the cosine similarity in `[0, 1]` (for a `cosine` collection);
+  higher means more similar.
+- `payload` carries the stored fields (`text`, `event_type`, `name`, `steps`,
+  plus your metadata). The reserved keys `_memory_type` / `text` /
+  `event_type` / `timestamp` / `name` / `steps` always take precedence over
+  caller `metadata`/`data` of the same name, so they cannot be clobbered.
+
 #### Semantic Memory (facts and knowledge)
 
 ```typescript
-// Store a fact
+// Store a fact (id is caller-assigned; reusing an id upserts)
 await memory.storeFact('knowledge', {
   id: 1,
   text: 'VelesDB uses HNSW for vector indexing',
@@ -762,12 +841,11 @@ const facts = await memory.searchFacts('knowledge', queryEmbedding, 5);
 #### Episodic Memory (events and experiences)
 
 ```typescript
-// Record an event
-await memory.recordEvent('events', {
+// Record an event — returns the generated point id
+const eventId = await memory.recordEvent('events', {
   eventType: 'user_query',
   data: { query: 'How does HNSW work?', response: '...' },
   embedding: eventEmbedding,
-  metadata: { timestamp: Date.now() }
 });
 
 // Recall similar events
@@ -777,10 +855,12 @@ const events = await memory.recallEvents('events', queryEmbedding, 5);
 #### Procedural Memory (learned patterns)
 
 ```typescript
-// Store a procedure
-await memory.learnProcedure('procedures', {
+// Store a procedure — embedding is required so the pattern is recallable,
+// and the generated point id is returned
+const procId = await memory.learnProcedure('procedures', {
   name: 'deploy-to-prod',
   steps: ['Run tests', 'Build artifacts', 'Push to registry', 'Deploy'],
+  embedding: procedureEmbedding,
   metadata: { lastUsed: Date.now() }
 });
 
@@ -788,6 +868,22 @@ await memory.learnProcedure('procedures', {
 const procs = await memory.recallProcedures('procedures', queryEmbedding, 3);
 ```
 
+#### Deleting memories
+
+```typescript
+// Works for facts, events, and procedures — returns true if a point was removed
+await memory.deleteMemory('procedures', procId);
+```
+
+> **`dimension` is advisory.** `db.agentMemory({ dimension })` records a hint you
+> can read back via `memory.dimension`, but it does **not** create or size any
+> collection — the collection's own dimension (set at `createCollection`)
+> governs storage and search, and your embeddings must match it.
+
+> **TTL & snapshots.** Per-entry TTL (in **seconds**) and versioned snapshots are
+> exposed by the embedded Rust API only; the REST-backed TypeScript facade does
+> not surface them. See the [Agent Memory guide](../../docs/guides/AGENT_MEMORY.md).
+
 ---
 
 ## Error Handling
@@ -828,6 +924,11 @@ import {
   VelesDB,
   AgentMemoryClient,
 
+  // Embedding helper
+  OpenAIEmbedder,
+  type Embedder,
+  type OpenAIEmbedderOptions,
+
   // Backends (advanced: use VelesDB client instead)
   WasmBackend,
   RestBackend,
@@ -880,6 +981,6 @@ import {
 
 ## License
 
-MIT License -- See [LICENSE](./LICENSE) for details.
+Licensed under the [VelesDB Core License 1.0](./LICENSE) (source-available). The SDK bundles the VelesDB WASM engine and is governed by the Core License.
 
 VelesDB Core and Server are licensed under VelesDB Core License 1.0 (source-available).