RushDB Agent Setup

Give any AI agent persistent, graph-structured memory — sessions, decisions, tasks, entities, and preferences — stored in RushDB and queryable by meaning.

Unlike flat key-value stores, RushDB memory auto-links nested JSON into a relationship graph, survives across conversations, and lets agents recall context by traversal or semantic similarity: "What did we decide about auth? What's related to that service?"

Step 1 — Connect the MCP Server

Web clients (ChatGPT, Claude.ai) — no install required

Use the hosted OAuth endpoint. No API key in config — you authenticate with your RushDB account.

ChatGPT: Settings → Connectors → Add connector → https://mcp.rushdb.com/mcp

Claude.ai: Settings → Integrations → Add integration → https://mcp.rushdb.com/mcp

Local clients (Claude Desktop, Cursor, VS Code)

Requires a RushDB API key → app.rushdb.com

Claude Desktop — edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "rushdb": {
      "command": "npx",
      "args": ["-y", "@rushdb/mcp-server"],
      "env": { "RUSHDB_API_KEY": "your-api-key-here" }
    }
  }
}

Cursor — add to .cursor/mcp.json:

{
  "mcpServers": {
    "rushdb": {
      "command": "npx",
      "args": ["-y", "@rushdb/mcp-server"],
      "env": { "RUSHDB_API_KEY": "your-api-key-here" }
    }
  }
}

VS Code — add to .vscode/mcp.json:

{
  "servers": {
    "rushdb": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@rushdb/mcp-server"],
      "env": { "RUSHDB_API_KEY": "your-api-key-here" }
    }
  }
}

Step 2 — Install Skills (recommended)

Skills give your agent built-in knowledge of RushDB's query syntax, memory patterns, and data modeling conventions — so you don't have to explain them in every session. They work best alongside the MCP server: skills tell the agent how; the MCP server gives it the tools.

npx skills add rush-db/rushdb --path packages/skills

Or via npm:

npm install @rushdb/skills

Start a new agent session after installation so the skills are discovered.

Skill	What it enables
`rushdb-agent-memory`	Session patterns, memory model, recall strategies
`rushdb-query-builder`	Build `findRecords` filters, aggregations, and semantic searches
`rushdb-data-modeling`	Design labels, properties, relationships, and nested schemas
`rushdb-faceted-search`	Build faceted filter UIs from live property metadata
`rushdb-domain-template`	Design a schema for any domain through guided conversation

Bootstrap Prompt

After the MCP server is connected, paste this prompt to your agent to initialize memory.

You are now connected to RushDB — a graph database for persistent agent memory.
Follow these steps in order without waiting for confirmation between steps.

INSPECT
1. Call getOntologyMarkdown. Note which labels exist and their record counts.
2. If SESSION records exist: call findRecords with
{"labels":["SESSION"],"orderBy":{"startedAt":"desc"},"limit":1}
and summarize the most recent session.
3. If no records exist: note that this is a fresh project and continue.

INITIALIZE
4. Create a SESSION record for this conversation:
{
"label": "SESSION",
"data": {
"startedAt": "<ISO timestamp now>",
"topic": "<infer from context, or 'general'>",
"agentId": "<your agent name>"
}
}
Note the returned $id — use it when linking records to this session.

IMPORT PRIOR CONTEXT
5. If the user has existing notes, preference files, or prior decisions to import,
extract and store them now using a single importJson call with nested labels:
- User preferences → label "PREFERENCE"
- Decisions made → label "DECISION"
- People / services / projects → label "ENTITY"
- Tasks → label "TASK"
Nesting them inside the SESSION data object automatically links everything.

SKILLS
6. Check if any of these skills are active in your context:
rushdb-agent-memory, rushdb-query-builder, rushdb-data-modeling.
If present, use them for query construction, memory patterns,
and schema decisions throughout this session.

CONFIRM
7. Call findRecords with {"labels":["SESSION"],"limit":5} and confirm results return.
8. Report: session ID created, prior context found (if any), skills active (if any),
and that recall is working.

ONGOING BEHAVIOR
During this session, proactively store without being asked:
- Decisions made → DECISION records
- Entities mentioned → ENTITY records (type: "person" | "service" | "project" | "concept")
- Tasks created/updated → TASK records
- Preferences expressed → PREFERENCE records

Use importJson with nested labels to create records and their relationships in one call.
At session end or when asked, update the SESSION record with a summary and ask
whether to save any outstanding context before closing.

RECALL
Use getOntologyMarkdown to inspect what is in memory at any time.
Use findRecords with $contains for keyword recall.
Use semanticSearch for meaning-based recall — this requires a one-time embedding
index per label+property; ask the user before creating one.

Memory Model

RushDB memory is a property graph. Each memory is a Record with a Label (type) and flat JSON properties (primitives and lists of primitives). Nested JSON is automatically normalized: each nested object becomes its own record, and parent → child relationships are created for you.

Recommended Labels

Label	What it stores
`SESSION`	A conversation or work session
`DECISION`	A decision made, with rationale and timestamp
`ENTITY`	A named thing — person, service, project, concept
`TASK`	A work item with status and assignee
`PREFERENCE`	A persistent user preference or constraint
`OBSERVATION`	A raw note or finding
`PLAN`	A proposed sequence of steps
`ARTIFACT`	A produced output — code, doc, design

Auto-linking Example

A single importJson call with nested labels creates a full linked subgraph:

{
  "label": "SESSION",
  "data": [
    {
      "sessionId": "sess_20260514_001",
      "startedAt": "2026-05-14T09:00:00Z",
      "topic": "authentication refactor",
      "DECISION": [
        {
          "topic": "auth provider",
          "decision": "Switch from Auth0 to Clerk",
          "rationale": "Better Next.js App Router integration",
          "decidedAt": "2026-05-14T09:15:00Z",
          "status": "confirmed"
        }
      ],
      "ENTITY": [
        { "name": "Clerk", "type": "service", "role": "new auth provider" },
        { "name": "Auth0", "type": "service", "role": "deprecated" }
      ],
      "TASK": [
        {
          "title": "Remove Auth0 dependency",
          "status": "pending",
          "priority": "high",
          "assignee": "Alice"
        }
      ]
    }
  ]
}

RushDB creates 1 SESSION, 1 DECISION, 2 ENTITY, and 1 TASK record — all linked automatically.

Recall Patterns

"What did we decide about X?"

{
  "labels": ["DECISION"],
  "where": { "topic": { "$contains": "X" } },
  "orderBy": { "decidedAt": "desc" },
  "limit": 10
}

"What sessions have we had?"

{
  "labels": ["SESSION"],
  "orderBy": { "startedAt": "desc" },
  "limit": 20
}

"What do I prefer?"

{
  "labels": ["PREFERENCE"],
  "orderBy": { "createdAt": "desc" }
}

"What happened in the last 7 days?"

{
  "labels": ["SESSION", "DECISION", "TASK"],
  "where": { "createdAt": { "$gte": "<7-days-ago-ISO>" } },
  "orderBy": { "createdAt": "desc" }
}

Semantic Search (Memory by Meaning)

$contains is exact substring match — fast, no setup. Use it for IDs, slugs, and known keywords.

Semantic search finds memories by meaning even when exact words differ — "auth system" matches a record that says "we chose Clerk for login". It requires a one-time index setup per label + property.

Create an index (one-time, per project)

Create a managed embedding index on the DECISION label for the "decision" property.
Monitor it until status is "ready", then confirm semantic search works.

The agent calls createEmbeddingIndex, polls getEmbeddingIndexStats until indexedRecords === totalRecords, then runs a test semanticSearch.

Query by meaning

{
  "tool": "semanticSearch",
  "propertyName": "decision",
  "labels": ["DECISION"],
  "query": "how did we handle authentication",
  "limit": 5
}

Combine with metadata filters

{
  "tool": "semanticSearch",
  "propertyName": "decision",
  "labels": ["DECISION"],
  "query": "database choice",
  "where": {
    "status": "confirmed",
    "decidedAt": { "$gte": "2026-01-01T00:00:00Z" }
  },
  "limit": 5
}

Candidates are narrowed by metadata first, then ranked by similarity.

End-of-Session Pattern

Ask your agent to save the session before closing:

Save this session to RushDB memory. Store all decisions made, entities mentioned,
tasks created or updated, and preferences I expressed. Link everything to today's
SESSION record. Summarize what was stored.

Resources

MCP Server — npx -y @rushdb/mcp-server · npm · GitHub
Agent Memory Skill — detailed patterns and query reference: packages/skills/rushdb-agent-memory/SKILL.md
Query Builder Skill — full SearchQuery syntax: packages/skills/rushdb-query-builder/SKILL.md
Docs — docs.rushdb.com
Dashboard — app.rushdb.com