AI & Semantic Search
RushDB is a self-aware memory layer for agents, humans, and apps. It continuously understands its own structure — labels, fields, value distributions, relationships — and exposes that knowledge so that agents can reason over real data without hallucinating schema details, and apps can retrieve semantically relevant context on demand.
The db.ai namespace covers three capabilities:
| Capability | Description |
|---|---|
| Graph Ontology | Self-describing schema discovery: label names, field types, value ranges, and the relationship map — always up to date |
| Embedding Indexes | Per-label vector policies that turn string properties into long-term semantic memory |
| Semantic Search | Cosine/euclidean similarity retrieval over indexed properties, for agents and apps alike |
How it fits together
┌─────────────────────────────────────────────────────┐
│ Your data (records + relationships) │
│ │
│ BOOK { title: "...", description: "..." } │
└────────────────────┬────────────────────────────────┘
│
db.ai.indexes.create()
│
▼
┌─────────────────────────────────────────────────────┐
│ Embedding index policy │
│ label: BOOK property: description dims: 1536 │
│ sourceType: managed | external │
└────────────────────┬────────────────────────────────┘
│
Backfill (managed) / inline vectors (external)
│
▼
┌─────────────────────────────────────────────────────┐
│ Vector stored on VALUE relationship │
│ rel._emb_managed_cosine_1536 = [0.1, 0.2, ...] │
└────────────────────┬────────────────────────────────┘
│
db.ai.search({ query / queryVector })
│
▼
┌─────────────────────────────────────────────────────┐
│ DBRecordsArrayInstance — records ranked by score │
│ result.data.__score = 0.94 (cosine similarity) │
└─────────────────────────────────────────────────────┘
Quick links
| Topic | Description |
|---|---|
| Ontology | Schema discovery with getOntology / getOntologyMarkdown |
| Indexing | Create and manage managed embedding indexes |
| Advanced indexing — BYOV | Bring Your Own Vectors: external indexes, inline writes |
| Semantic search | Query by meaning with db.ai.search() |
| Writing with vectors | Attach vectors at create / upsert / importJson time |
| Agent Skills | Installable skills that teach any compatible agent to use RushDB |
Graph Ontology
The ontology endpoints expose a live snapshot of your database structure — without any manual schema definitions.
Get Ontology as Markdown
db.ai.getOntologyMarkdown()
Returns the full schema as compact Markdown — the recommended format for LLM context injection.
db.ai.getOntologyMarkdown(
params?: { labels?: string[]; force?: boolean },
transaction?: Transaction | string
): Promise<ApiResponse<string>>
// Inject into LLM at session start
const { data: schema } = await db.ai.getOntologyMarkdown();
const messages = [
{ role: "system", content: `You are a data assistant.\n\n${schema}` },
{ role: "user", content: "How many paid orders are there?" },
];
// Scope to specific labels
const { data: orderSchema } = await db.ai.getOntologyMarkdown({
labels: ["Order"],
});
// Bypass the 1-hour cache and force a fresh recalculation
const { data: freshSchema } = await db.ai.getOntologyMarkdown({ force: true });
Example output
# Graph Ontology
## Labels
| Label | Count |
|-----------|------:|
| `Order` | 1840 |
| `User` | 312 |
| `Product` | 95 |
---
## `Order` (1840 records)
### Properties
| Property | Type | Values / Range | Semantic Search |
|-------------|----------|----------------------------------------|--------------------------------|
| `status` | string | `pending`, `paid`, `shipped` (+2 more) | — |
| `total` | number | `4.99`..`2499.00` | — |
| `name` | string | `Widget A`, `Widget B` (+8 more) | `managed` cosine 1536d [ready] |
| `createdAt` | datetime | `2024-01-03`..`2026-02-27` | — |
### Relationships
| Type | Direction | Other Label |
|-------------|-----------|-------------|
| `PLACED_BY` | out | `User` |
| `CONTAINS` | out | `Product` |
Get Ontology (raw)
db.ai.getOntology()
Returns the same ontology as a structured JSON array — useful for schema UIs, auto-complete, or looking up property IDs for db.properties.values().
db.ai.getOntology(
params?: { labels?: string[]; force?: boolean },
transaction?: Transaction | string
): Promise<ApiResponse<OntologyItem[]>>
// List all labels with counts
const { data: ontology } = await db.ai.getOntology();
for (const item of ontology) {
console.log(`${item.label}: ${item.count} records`);
}
// Get property ID for value enumeration
const {
data: [bookSchema],
} = await db.ai.getOntology({ labels: ["Book"] });
const genreProp = bookSchema.properties.find((p) => p.name === "genre");
const { data: genres } = await db.properties.values({ id: genreProp.id });
// Identify semantically-searchable properties
const indexed = bookSchema.properties.filter((p) => p.vectorIndexes?.length);
// indexed[0].vectorIndexes[0].status === 'ready' → queryable with db.ai.search()
// Bypass the 1-hour cache
const { data: fresh } = await db.ai.getOntology({ force: true });
type OntologyItem = {
label: string;
count: number;
properties: OntologyProperty[];
relationships: OntologyRelationship[];
};
type OntologyVectorIndex = {
id: string;
sourceType: string; // 'managed' | 'external'
similarityFunction: string; // 'cosine' | 'euclidean'
dimensions: number;
status: string; // 'pending' | 'indexing' | 'ready' | 'error'
modelKey: string;
};
type OntologyProperty = {
id: string; // use with db.properties.values()
name: string;
type: string; // 'string' | 'number' | 'boolean' | 'datetime'
values?: Array<string | number>; // up to 10 samples (string/boolean only)
min?: number | string; // number/datetime only
max?: number | string;
/** Non-empty when embedding indexes exist — property is queryable with db.ai.search() */
vectorIndexes?: OntologyVectorIndex[];
};
type OntologyRelationship = {
label: string;
type: string;
direction: "in" | "out";
};
Both methods share a 1-hour cache per project. The first call after TTL expiry triggers a full graph scan; all subsequent calls within the hour are instant. Pass { force: true } to bypass the cache and trigger an immediate recalculation.
Call db.ai.getOntologyMarkdown() first in every AI session. Without it, models will hallucinate field and label names.
Agent Skills
@rushdb/skills is a collection of Agent Skills — installable instructions that teach any skills-compatible AI agent (Claude, GitHub Copilot, Cursor, Windsurf, and others) to use RushDB efficiently, without manual system prompt engineering.
npx skills add rush-db/rushdb --path packages/skills
| Skill | What it teaches |
|---|---|
rushdb-query-builder | Discovery-first workflow, SearchQuery syntax, aggregation, relationship traversal, and semantic search |
rushdb-agent-memory | Using RushDB as persistent structured memory — store, link, and semantically recall sessions, decisions, and entities |
rushdb-data-modeling | LMPG model design, label/property naming conventions, nested JSON import, and schema evolution |
rushdb-faceted-search | Build faceted filter UIs — discover properties and types, enumerate distinct values, map to widgets, assemble a live where clause |
Each skill bundles a SKILL.md with concise instructions and optional reference files (like the full SearchQuery spec) that the agent loads on demand.
The MCP server gives agents direct tool access to RushDB at runtime. Agent Skills teach agents how to use those tools correctly — they complement each other.