rush-db · 1pxone · Mar 17, 2026 · Feb 26, 2026 · Mar 17, 2026
diff --git a/.changeset/poor-starfishes-deliver.md b/.changeset/poor-starfishes-deliver.md
@@ -0,0 +1,10 @@
+---
+'@rushdb/javascript-sdk': minor
+'@rushdb/mcp-server': minor
+'rushdb-dashboard': minor
+'rushdb-core': minor
+'rushdb-website': minor
+'rushdb-docs': minor
+---
+
+Improve separation between os and cloud versions
diff --git a/README.md b/README.md
@@ -4,10 +4,9 @@
 
 # RushDB
 
-### Developer‑first property‑centric graph store
+### Turn Any Data into Intelligence
 
-RushDB lets you push raw JSON/CSV, auto-normalize it into a labeled meta property graph, and query records, schema, relationships, values, vectors and aggregations through one JSON search interface. No upfront schema design, no new query language to learn.
-RushDB transforms how you work with graph data — no schema required, no complex queries, just push your data and go.
+Push any JSON — records, events, AI outputs, configs. RushDB structures it, connects it, and makes it queryable instantly. No upfront schema design, no new query language to learn.
 
 [![GitHub Stars](https://img.shields.io/github/stars/rush-db/rushdb?style=social)](https://github.com/rush-db/rushdb)
 [![Follow on X (Twitter)](https://img.shields.io/twitter/follow/rushdb?style=social)](https://x.com/RushDatabase)
@@ -99,7 +98,7 @@ For deeper architectural exposition see the blog article on [LMPG](https://rushd
 
 ### 1. Get an API Key (Cloud) or Run Locally
 RushDB Cloud: create a project at https://app.rushdb.com → copy API key.
-Self-host (requires Neo4j 5.25.1+ with APOC & GDS):
+Self-host (requires Neo4j 2026.01.4+ with compatible APOC & GDS plugins):
 ```bash
 docker run -p 3000:3000 \
   --name rushdb \
@@ -212,9 +211,9 @@ Benefits:
 ## 🛠️ Self-Hosting
 
 ### Requirements
-- Neo4j 5.25.1+
-- APOC plugin
-- Graph Data Science plugin (for vector similarity & advanced aggregates)
+- Neo4j 2026.01.4+
+- APOC Core plugin (compatible with Neo4j 2026.01.4+)
+- Graph Data Science plugin (compatible with Neo4j 2026.01.4+, for vector similarity & advanced aggregates)
 
 ### Minimal Docker Compose
 ```yaml
@@ -266,7 +265,7 @@ services:
       - NEO4J_USERNAME=neo4j
       - NEO4J_PASSWORD=password
   neo4j:
-    image: neo4j:5.25.1
+    image: neo4j:2026.01.4
     healthcheck:
       test: [ "CMD-SHELL", "wget --no-verbose --tries=1 --spider localhost:7474 || exit 1" ]
       interval: 5s
@@ -278,7 +277,11 @@ services:
     environment:
       - NEO4J_ACCEPT_LICENSE_AGREEMENT=yes
       - NEO4J_AUTH=neo4j/password
-      - NEO4J_PLUGINS=["apoc", "graph-data-science"]
+      # Optional: auto-download plugins from the internet
+      # - NEO4J_PLUGINS=["apoc", "graph-data-science"]
+    volumes:
+      # Optional: mount local plugin jars (required for Neo4j 2026.x where auto-download may not work)
+      - ./neo4j-plugins:/var/lib/neo4j/plugins
 ```
 </details>
 

diff --git a/docs/docs/concepts/billing-model.md b/docs/docs/concepts/billing-model.md
@@ -0,0 +1,66 @@
+---
+sidebar_position: 8
+---
+
+# Billing Model
+
+## Overview
+
+RushDB uses a **Knowledge Units (KU)** billing model. You pay for the structured knowledge RushDB creates and maintains from your data — not for infrastructure, nodes, edges, storage, or compute.
+
+```
+Total KU consumed in billing period × price per KU = your bill
+```
+
+This model aligns cost with value: you pay more only when RushDB is doing more work to organize and serve your data.
+
+## Monthly Billing Cycle
+
+KU consumption resets at the start of each billing period. Your plan includes a base KU allowance. Consumption above the included allowance is billed as overage (Pro and above).
+
+```
+Bill = included KU (flat rate) + overage KU × overage rate
+```
+
+## Plan Comparison
+
+| | Free | Pro | Scale | Enterprise |
+|---|---|---|---|---|
+| Included KU / month | 100,000 | 10,000,000 | Usage-based | Custom |
+| Overage | Not available | Per KU | Per KU | Negotiated |
+| Projects | 2 | Unlimited | Unlimited | Unlimited |
+| Self-hosted support | ✓ | ✓ | ✓ | ✓ |
+| SLA | — | — | ✓ | ✓ |
+| BYOC (own Neo4j / Aura) | ✓ | ✓ | ✓ | ✓ |
+
+## One Metric
+
+KU is the only number that matters for billing. RAM, CPU, storage, node counts, edge counts, and query time are infrastructure concerns — RushDB absorbs them. Your bill reflects the knowledge work done, nothing else.
+
+## Soft and Hard Limits
+
+- **Soft limit**: RushDB sends an alert when you reach 80% of your monthly KU allowance.
+- **Hard limit**: Write operations are blocked when your allowance is exhausted. Read operations continue unaffected.
+- You can configure alerts and caps from the **KU Usage** page in your dashboard.
+
+## Self-Hosted Billing
+
+Self-hosted deployments (`RUSHDB_SELF_HOSTED=true`) have no KU limits and no billing. The OSS engine runs entirely without quota enforcement.
+
+For teams that need the full platform (dashboard, projects, API key management, team members) without usage caps, contact us about an **Enterprise platform license**.
+
+## Changes to Limits Mid-Period
+
+- Upgrading your plan: new KU limit takes effect immediately.
+- Downgrading your plan: new KU limit takes effect at the start of the next billing period.
+- Cancelling: your current allowance remains active until the end of the paid period.
+
+## KU Usage Dashboard
+
+Your KU consumption is visible in real-time on the **KU Usage** page in your workspace dashboard:
+
+- Total KU consumed this month
+- Remaining KU
+- Estimated end-of-month cost
+- Daily consumption trend chart
+- Ingestion and query spike timeline
diff --git a/docs/docs/concepts/knowledge-units.md b/docs/docs/concepts/knowledge-units.md
@@ -0,0 +1,109 @@
+---
+sidebar_position: 7
+---
+
+# Knowledge Units (KU)
+
+## What is a Knowledge Unit?
+
+A **Knowledge Unit (KU)** is the fundamental economic unit of RushDB. It represents a unit of structured knowledge created and maintained by RushDB from your raw data — during ingestion, modeling, or reasoning.
+
+```
+Raw data → RushDB → Structured Knowledge → KU
+```
+
+The more data you push and the richer its structure, the more knowledge RushDB creates, and the more KU are consumed.
+
+## Developer Mental Model
+
+You never need to think about nodes, edges, CPU, RAM, or storage. You simply think:
+
+```
+More data → more knowledge → more KU
+```
+
+RushDB handles all the underlying storage and graph mechanics automatically. You pay only for the knowledge created and maintained on your behalf.
+
+## What Generates KU?
+
+KU is generated by operations that create or maintain structured knowledge in RushDB:
+
+| Activity | Example |
+|---|---|
+| Ingesting records | `db.records.create()`, `records.importJson()` |
+| Building relationships | `db.records.attach()` |
+| Storing vector embeddings | Passing `number[]` arrays during ingestion |
+| **Compute-intensive operations** | Vector similarity search, raw Cypher execution, multi-hop traversals |
+| Maintaining stored knowledge | Ongoing footprint of stored records |
+
+**Standard reads and queries (find, filter, paginate) never consume KU.** Compute-intensive operations do because their cost scales with dataset size rather than the data written — running a vector search across 10M records costs significantly more server compute than fetching a record by ID.
+
+> **Note:** The internal weights assigned to each operation type are not exposed. You interact only with your total KU consumption.
+
+## KU and Plan Limits
+
+Each plan includes a monthly KU allowance:
+
+| Plan | Included KU / month |
+|---|---|
+| Free | 100,000 KU |
+| Pro | 10,000,000 KU |
+| Scale | Usage-based |
+| Enterprise | Custom / platform license |
+
+When your workspace reaches its KU limit, write operations will be blocked until the next billing period or until you upgrade your plan.
+
+## How Nested JSON is Billed
+
+When you ingest nested JSON, RushDB **automatically decomposes it** into separate linked records:
+
+```json
+// Input: one nested object
+{ "user": { "profile": { "name": "Alice", "age": 30 } } }
+
+// RushDB creates:
+// → Record: user     (0 own properties)
+// → Record: profile  (2 properties: name, age)  → ~2 KU
+// → Relationship: user → profile                → ~0.5 KU
+// Total: ~2.5 KU
+```
+
+This means nesting **does not multiply properties** — it creates additional records and relationships, each billed independently.
+
+| Component | Cost |
+|---|---|
+| Each record created | weight per record |
+| Each property stored on a record | weight per property |
+| Each relationship formed between records | fractional weight (< 1×) |
+
+> **Note:** Exact per-operation weights are not publicly exposed. You interact only with your total KU consumption.
+
+## KU Calculator
+
+You can estimate your monthly KU consumption with this approximation:
+
+```
+estimated monthly KU
+  ≈ records_per_day × 30 × (avg_properties + avg_child_records × relationship_weight)
+```
+
+Where:
+- `records_per_day` — average number of top-level records ingested per day
+- `avg_properties` — average number of scalar properties per record
+- `avg_child_records` — average number of nested objects per record (each becomes a separate linked child record)
+- `relationship_weight` — the fractional KU cost per relationship (less than 1×)
+
+For a quick estimate, nesting depth maps approximately to a combined multiplier of `1.0` (flat) → `3.0` (deeply nested) on the base property count. This is an approximation — actual KU depends on the internal weighting of each operation type.
+
+## Storage Footprint
+
+RushDB charges a small daily **storage footprint** KU for every record currently stored in your project. This covers the ongoing infrastructure cost of keeping your data queryable.
+
+- Storage KU is calculated once per day, prorated against your monthly plan allowance.
+- The charge is proportional to your current record count — fewer records, lower footprint.
+- **Deleting records reduces your ongoing footprint** from the next daily cycle onward.
+- KU consumed *at creation time* is never reversed by a later deletion.
+
+## Self-Hosted
+
+When running RushDB in self-hosted mode (`RUSHDB_SELF_HOSTED=true`), KU tracking is disabled and no limits apply. Self-hosted deployments are fully unlimited.
diff --git a/docs/docs/concepts/pricing.md b/docs/docs/concepts/pricing.md
@@ -0,0 +1,95 @@
+---
+sidebar_position: 9
+---
+
+# Pricing
+
+## Simple, Predictable Pricing
+
+RushDB pricing is based on [Knowledge Units (KU)](./knowledge-units.md) — a single unit that represents the structured knowledge created and maintained from your data. No infrastructure tiers, no node counts, no storage pricing.
+
+```
+You pay for knowledge created. Nothing else.
+```
+
+## Plans
+
+### Free
+
+- **100,000 KU / month** included
+- Up to 2 projects
+- Self-hosted support
+- Bring Your Own Cloud (BYOC) — connect to your own Neo4j or Aura instance
+- Community support
+- No credit card required
+
+Perfect for prototypes, side projects, and getting started.
+
+### Pro — $29/month
+
+- **10,000,000 KU / month** included
+- Overage at **$3 per additional million KU** — no hard stop, apps keep running
+- Unlimited projects
+- Priority support
+- Team members (up to 3, then $10/member)
+- Bring Your Own Cloud (BYOC) — connect to your own Neo4j or Aura instance
+
+Ideal for production applications and growing teams. Predictable base cost, pay-as-you-go beyond the included allowance.
+
+### Scale — from $99/month
+
+- **Usage-based** — $99 platform fee + **$2 per million KU** consumed
+- No included KU bundle — cheaper per-KU rate than Pro at volume
+- SLA guarantee
+- Advanced support
+- Unlimited team members
+- Bring Your Own Cloud (BYOC) — connect to your own Neo4j or Aura instance
+
+For high-volume or highly variable workloads where you want the lowest per-KU rate without worrying about tiers. The $2/M KU rate on Scale is 33% cheaper than Pro's overage rate.
+
+### Enterprise
+
+- **Platform license** — flat fee, unlimited KU
+- Bring Your Own Cloud (BYOC)
+- Embedded / OEM use
+- Dedicated support and SLA
+- Custom contract
+
+For organisations embedding RushDB into their products or needing full data sovereignty.
+
+## Estimating Your KU Usage
+
+Use this formula to estimate your monthly KU consumption:
+
+```
+estimated KU ≈ records_per_day × 30 × avg_fields_per_record × nesting_factor
+```
+
+**Example:**
+- 1,000 records/day
+- 10 fields per record on average
+- Flat structure (nesting factor ≈ 1.0)
+
+```
+1,000 × 30 × 10 × 1.0 = 300,000 KU/month → Pro plan
+```
+
+The interactive KU Calculator on the [pricing page](https://rushdb.com/pricing) can help you get a more precise estimate.
+
+## Self-Hosted
+
+Running RushDB on your own infrastructure? Self-hosted mode is **free and unlimited** — no KU limits, no billing. See the [self-hosting guide](../get-started/quick-tutorial) to get started.
+
+## FAQ
+
+**Can I exceed my plan's KU limit?**
+On the Free plan, writes are blocked when the limit is reached — reads always continue. On Pro, overage is billed at $3 per million KU beyond the 10M included. On Scale there is no hard limit — you pay $2 per million KU consumed on top of the $99/month base.
+
+**Does deleting data reduce my KU usage?**
+KU from creation operations is never reversed. However, once data is deleted, its ongoing stored footprint stops contributing to KU from that point forward.
+
+**Do read operations consume KU?**
+Standard read and search operations do not consume KU. Heavy analytical operations (multi-hop traversals, vector similarity search at scale) may consume a small amount of KU.
+
+**Is there a free trial for paid plans?**
+Yes — start on the Free plan with no credit card. Upgrade at any time and your remaining free KU carries over for the rest of the billing period.
diff --git a/docs/docs/concepts/records.md b/docs/docs/concepts/records.md
@@ -7,7 +7,7 @@ In RushDB, Records are fundamental data structures that store meaningful key-val
 
 ## How it works
 
-Records in RushDB can be thought of as nodes in a graph database or rows in a traditional database. While the underlying implementation utilizes complex graph structures, from a user perspective, a Record is simply a key-value object containing properties.
+Records in RushDB are the fundamental units of structured knowledge. While the underlying engine uses a rich graph model to represent and connect data, from a developer perspective a Record is simply a typed key-value object containing properties — like a row in a database or a document in a document store, but with seamless relationship traversal built in.
 
 Each record in RushDB consists of:
 

diff --git a/docs/docs/concepts/storage.md b/docs/docs/concepts/storage.md
@@ -3,7 +3,7 @@ sidebar_position: 3
 ---
 # Storage
 
-RushDB leverages [Neo4j](https://neo4j.com/docs/get-started/get-started-with-neo4j/) (version 5.25.1 or higher) as its underlying storage engine, enhanced with the [APOC](https://neo4j.com/labs/apoc/) (Awesome Procedures On Cypher) and [GDS](https://neo4j.com/docs/graph-data-science/current/) (Graph Data Science) plugins to perform efficient vector similarity searches and advanced graph operations.
+RushDB leverages [Neo4j](https://neo4j.com/docs/get-started/get-started-with-neo4j/) (version 2026.01.4 or higher) as its underlying storage engine, enhanced with the latest [APOC](https://neo4j.com/labs/apoc/) (Awesome Procedures On Cypher) and [GDS](https://neo4j.com/docs/graph-data-science/current/) (Graph Data Science) plugins. This enables efficient vector similarity searches and advanced graph operations, fully compatible with the newest database and plugin releases.
 
 ## Graph Database vs. Traditional Databases
 
@@ -28,7 +28,7 @@ Neo4j provides RushDB with a robust graph database foundation, allowing for:
 - Property graph model flexibility
 - Scalable data storage and retrieval
 
-The integration with [APOC](https://neo4j.com/labs/apoc/4.4/overview/) and [GDS](https://neo4j.com/docs/graph-data-science/current/introduction/) plugins extends Neo4j's native capabilities with vector-based operations critical for machine learning workflows and similarity search functions.
+The integration with [APOC](https://neo4j.com/labs/apoc/) and [GDS](https://neo4j.com/docs/graph-data-science/current/) plugins extends Neo4j's native capabilities with vector-based operations critical for machine learning workflows and similarity search functions. RushDB supports the latest plugin releases for APOC and GDS, ensuring compatibility with Neo4j 2026.01.4 and newer.
 
 ## Data Overhead