string

# RushDB Agent Setup

Give any AI agent a 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 records into a relationship graph, survives across conversations, and lets agents traverse context the same way humans think: _"What did we decide about auth? What's related to that service?"_

---

## Prompt for Agent

> Copy the block below and send it to your agent (Claude, OpenClaw, Cursor, or any MCP-capable agent) to bootstrap its RushDB memory.

---

````
### Step 1 — Connect the MCP Server

**Add RushDB to your MCP client config and ask your agent:**

```
Connect to RushDB memory. Follow these steps exactly.
```

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

```json
{
  "mcpServers": {
    "rushdb": {
      "command": "npx",
      "args": ["@rushdb/mcp-server"],
      "env": {
        "RUSHDB_API_KEY": "<your-api-key>"
      }
    }
  }
}
```

**VS Code / Cursor** — add to MCP settings:

```json
{
  "mcp.servers": {
    "rushdb": {
      "command": "npx",
      "args": ["@rushdb/mcp-server"],
      "env": {
        "RUSHDB_API_KEY": "<your-api-key>"
      }
    }
  }
}
```

Get your API key at [app.rushdb.com](https://app.rushdb.com).

---

### Step 2 — Agent Bootstrap Prompt

Paste this prompt to your agent after the MCP server is connected:

---

```
Set up RushDB as my persistent memory layer. Follow these steps in order.

INITIALIZE
1. Call getOntologyMarkdown to check existing memory labels and record counts.
2. If SESSION labels already exist, call findRecords with labels:["SESSION"],
   orderBy:{startedAt:"desc"}, limit:1 and summarize the most recent session.
3. Create a SESSION record for this conversation:
   {
     "label": "SESSION",
     "data": {
       "startedAt": "<ISO timestamp now>",
       "topic": "RushDB memory bootstrap",
       "agentId": "<your agent name>",
       "userId": "<user identifier if known>"
     }
   }

IMPORT EXISTING IDENTITY (if applicable)
4. Check if any of these files exist and read them if they do:
   - SOUL.md, IDENTITY.md, USER.md, MEMORY.md (skip AGENTS.md, BOOTSTRAP.md, TOOLS.md)
   - ~/.openclaw/workspace/memory/ (most recent 30 days of YYYY-MM-DD.md files)
   - Any other persistent preference or identity files the user points you to.
5. For each file found, extract facts and create records:
   - User preferences → label "PREFERENCE"
   - Personality / identity facts → label "ENTITY" with type:"identity"
   - Past decisions → label "DECISION"
   - Ongoing tasks → label "TASK"
   Use bulkCreateRecords with nested JSON to auto-link everything to the SESSION.

CONFIRM
6. Call getOntologyMarkdown again and report:
   - Which labels now exist and their record counts
   - A 2–3 sentence summary of what memory was found or created
7. Run a test recall: findRecords with labels:["PREFERENCE"] limit:5
   and show the results to confirm memory is searchable.

Report: session ID created, files imported (if any), total records written, confirmation that recall works.
```

---

## Memory Model

RushDB memory is a property graph. Each memory is a **Record** with a **Label** (type) and arbitrary JSON fields. Nested JSON auto-creates linked records — no manual edge wiring.

### 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 `bulkCreateRecords` call with nested JSON creates a full linked subgraph:

```json
{
  "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

Agents can recall memory at session start or on demand:

**"What did we decide about X?"**

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

**"What sessions have we had?"**

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

**"What do I prefer?"**

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

**"What happened in the last 7 days?"**

```json
{
  "labels": ["SESSION", "DECISION", "TASK"],
  "where": { "createdAt": { "$gte": "2026-05-07T00:00:00Z" } },
  "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.

### When to set it up

Semantic indexes are most valuable on free-text properties:

| Label | Property to index | Why |
|---|---|---|
| `DECISION` | `decision` | Recall decisions by topic even with paraphrasing |
| `DECISION` | `rationale` | Find the reasoning behind past choices |
| `OBSERVATION` | `content` | Retrieve raw notes by meaning |
| `PREFERENCE` | `value` or `content` | Match user preferences loosely |
| `PLAN` | `description` | Find plans related to a concept |

### Create an index (one-time, per project)

Ask the agent:

```
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 will:
1. Call `createEmbeddingIndex` with `{ label: "DECISION", propertyName: "decision" }`
2. Poll `getEmbeddingIndexStats` until `indexedRecords === totalRecords`
3. Run a test `semanticSearch` to confirm

Or do it yourself via the MCP tool directly:
```json
{
  "tool": "createEmbeddingIndex",
  "label": "DECISION",
  "propertyName": "decision"
}
```

`sourceType` defaults to `"managed"` — RushDB embeds every existing and future value automatically, no embedding pipeline needed.

### Query by meaning

Once the index is ready, recall by natural language:

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

Returns records ranked by similarity, each with a `__score` field.

### Combine semantic search with metadata filters (prefilter mode)

Adding a `where` clause activates prefilter mode — candidates are narrowed by metadata first, then ranked by similarity. This is the most useful pattern for memory recall:

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

This finds confirmed decisions from 2026 onward that are semantically related to "database choice" — even if the record says "we went with Postgres for the primary store".

### Ask the agent to recall semantically

```
Search my memory for anything related to [topic] using semantic search.
Combine it with a filter for [label] records from the last [N] days.
```
````

---

## 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 @rushdb/mcp-server` · [npm](https://www.npmjs.com/package/@rushdb/mcp-server) · [GitHub](https://github.com/rush-db/rushdb/tree/main/packages/mcp-server)
- **Agent Memory Skill** — detailed patterns and query reference: [`packages/skills/rushdb-agent-memory/SKILL.md`](packages/skills/rushdb-agent-memory/SKILL.md)
- **Memory Patterns Reference** — concrete JSON structures and naming conventions: [`packages/skills/rushdb-agent-memory/references/memory-patterns.md`](packages/skills/rushdb-agent-memory/references/memory-patterns.md)
- **Query Builder Skill** — full SearchQuery syntax: [`packages/skills/rushdb-query-builder/SKILL.md`](packages/skills/rushdb-query-builder/SKILL.md)
- **Docs** — [docs.rushdb.com](https://docs.rushdb.com) · MCP quickstart: [docs.rushdb.com/mcp-server/quickstart](https://docs.rushdb.com/mcp-server/quickstart)
- **Dashboard** — [app.rushdb.com](https://app.rushdb.com)


Give any AI agent persistent, graph-structured memory using RushDB. Store sessions, decisions, tasks, and preferences — queryable by meaning across conversations.