diff --git a/README.md b/README.md
index 9b793e66..0be620e9 100644
--- a/README.md
+++ b/README.md
@@ -58,9 +58,20 @@ RUN npm run download-models # Download during build for offline production
## β¨ What is Brainy?
-Imagine a database that thinks like you do - connecting ideas, finding patterns, and getting smarter over time. Brainy
-is the **AI-native database** that brings vector search and knowledge graphs together in one powerful, ridiculously
-easy-to-use package.
+**One API. Every environment. Zero configuration.**
+
+Brainy is the **AI-native database** that combines vector search and knowledge graphs in one unified API. Write your code once, and it runs everywhere - browsers, Node.js, serverless, edge workers - with automatic optimization for each environment.
+
+```javascript
+// This same code works EVERYWHERE
+const brainy = new BrainyData()
+await brainy.init()
+
+// Vector search (like Pinecone) + Graph database (like Neo4j)
+await brainy.add("OpenAI", { type: "company" }) // Nouns
+await brainy.relate(openai, gpt4, "develops") // Verbs
+const results = await brainy.search("AI", 10) // Semantic search
+```
### π NEW: Distributed Mode (v0.38+)
@@ -103,41 +114,40 @@ npm install @soulcraft/brainy
```javascript
import { BrainyData } from '@soulcraft/brainy'
+// Same code works EVERYWHERE - browser, Node.js, cloud, edge
const brainy = new BrainyData()
await brainy.init() // Auto-detects your environment
-// Add some data
-await brainy.add("The quick brown fox jumps over the lazy dog")
-await brainy.add("A fast fox leaps over a sleeping dog")
-await brainy.add("Cats are independent and mysterious animals")
+// 1οΈβ£ Simple vector search (like Pinecone)
+await brainy.add("The quick brown fox jumps over the lazy dog", { type: "sentence" })
+await brainy.add("Cats are independent and mysterious animals", { type: "sentence" })
-// Vector search finds similar content
-const results = await brainy.search("speedy animals jumping", 2)
-console.log(results) // Finds the fox sentences!
+const results = await brainy.search("fast animals", 5)
+// Finds similar content by meaning, not keywords!
+
+// 2οΈβ£ Graph relationships (like Neo4j)
+const openai = await brainy.add("OpenAI", { type: "company", founded: 2015 })
+const gpt4 = await brainy.add("GPT-4", { type: "product", released: 2023 })
+const sam = await brainy.add("Sam Altman", { type: "person", role: "CEO" })
+
+// Create relationships between entities
+await brainy.relate(openai, gpt4, "develops")
+await brainy.relate(sam, openai, "leads")
+await brainy.relate(gpt4, sam, "created_by")
+
+// 3οΈβ£ Combined power: Vector search + Graph traversal
+const similar = await brainy.search("AI language models", 10) // Find by meaning
+const products = await brainy.getVerbsBySource(openai) // Get relationships
+const graph = await brainy.findSimilar(gpt4, { relationType: "develops" })
+
+// 4οΈβ£ Advanced: Search with context
+const contextual = await brainy.search("Who leads AI companies?", 5, {
+ includeVerbs: true, // Include relationships in results
+ nounTypes: ["person"], // Filter to specific entity types
+})
```
-**π― That's it!** You just built semantic search in 4 lines. Works in Angular, React, Vue, Node.js, browsers,
-serverless - everywhere.
-
-## π The Magic: Vector + Graph Database
-
-**Most databases do one thing.** Brainy does both vector similarity AND graph relationships:
-
-```javascript
-// Add entities with relationships
-const companyId = await brainy.addNoun("OpenAI creates powerful AI models", "company")
-const productId = await brainy.addNoun("GPT-4 is a large language model", "product")
-
-// Connect them with relationships
-await brainy.addVerb(companyId, productId, undefined, { type: "develops" })
-
-// Now you can do BOTH:
-const similar = await brainy.search("AI language models") // Vector similarity
-const products = await brainy.getVerbsByType("develops") // Graph traversal
-```
-
-**Why this matters:** Find content by meaning AND follow relationships. It's like having PostgreSQL and Pinecone working
-together seamlessly.
+**π― That's it!** Vector search + graph database + works everywhere. No config needed.
### π Want More Power?
@@ -162,336 +172,146 @@ returns "tiger"
**π Real-Time Collaboration** - Sync vector data across devices. Figma for AI data
**π₯ Medical Diagnosis Tools** - Match symptoms to conditions using embedding similarity
-## π Write-Once, Run-Anywhere Quick Start
+## π Works Everywhere - Same Code
-Brainy uses the same code across all environments with automatic detection. **Framework-optimized** for the best
-developer experience. Choose your environment:
+**Write once, run anywhere.** Brainy auto-detects your environment and optimizes automatically:
-### π °οΈ Angular (Latest)
+### π Browser Frameworks (React, Angular, Vue)
-```bash
-npm install @soulcraft/brainy
+```javascript
+import { BrainyData } from '@soulcraft/brainy'
+
+// SAME CODE in React, Angular, Vue, Svelte, etc.
+const brainy = new BrainyData()
+await brainy.init() // Auto-uses OPFS in browsers
+
+// Add entities and relationships
+const john = await brainy.add("John is a software engineer", { type: "person" })
+const jane = await brainy.add("Jane is a data scientist", { type: "person" })
+const ai = await brainy.add("AI Project", { type: "project" })
+
+await brainy.relate(john, ai, "works_on")
+await brainy.relate(jane, ai, "leads")
+
+// Search by meaning
+const engineers = await brainy.search("software developers", 5)
+
+// Traverse relationships
+const team = await brainy.getVerbsByTarget(ai) // Who works on AI Project?
```
+
+π¦ Full Angular Component Example
+
```typescript
import { Component, signal, OnInit } from '@angular/core'
import { BrainyData } from '@soulcraft/brainy'
@Component({
selector: 'app-search',
- template: `
-