Skip to main content
Learn

Agent Memory Quickstart

Give any agent a persistent, graph-structured memory in under five minutes. Sessions, decisions, tasks, entities, and preferences — stored in RushDB, traversable by meaning.

Prerequisites​

  1. API key — sign up free at app.rushdb.com and copy your project API key.
  2. A running RushDB instance — cloud or self-hosted.

Distribution URL​

Any agent or automation can fetch the full setup guide programmatically:

https://rushdb.com/agent-setup

This URL always serves the canonical setup prompt. Point your agent at it instead of copy-pasting:

Fetch https://rushdb.com/agent-setup and follow the instructions exactly.

Step 1 — Connect the MCP Server​

Add the @rushdb/mcp-server to your agent's MCP config, then restart.

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Restart Claude Desktop. The RushDB tools appear in the tool list automatically.

Step 2 — Install the Agent Skills​

Install the RushDB skills pack so your agent knows how to use the MCP tools for memory, querying, and data modeling:

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

Or install the package with npm:

npm install @rushdb/skills

The pack includes:

SkillWhat it enables
rushdb-agent-memoryStore sessions, decisions, tasks, and preferences; recall prior context
rushdb-query-builderBuild correct filters, traversals, aggregations, and semantic searches
rushdb-data-modelingDesign labels, properties, relationships, and nested memory schemas
MCP server vs. Agent Skills

The MCP server gives your agent RushDB tools at runtime. Agent Skills teach it how to use those tools correctly. Install both, then start a new agent session so the skills are discovered.

For OpenClaw workspace-level installation, see Using RushDB Agent Skills in OpenClaw.

Step 3 — Bootstrap the Agent​

After the MCP server is connected, send this prompt once per new agent / project:

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": "<current topic>",
       "agentId": "<your agent name>"
     }
   }

IMPORT EXISTING IDENTITY (if applicable)
4. Check if any of these files exist and read them:
   - SOUL.md, IDENTITY.md, USER.md, MEMORY.md
   - ~/.openclaw/workspace/memory/ (most recent 30 days of YYYY-MM-DD.md)
   - Any preference or identity files the user points you to.
5. Extract facts and create records:
   - User preferences → label "PREFERENCE"
   - Identity facts → label "ENTITY" with type:"identity"
   - Past decisions → label "DECISION"
   - Ongoing tasks → label "TASK"

CONFIRM
6. Call getOntologyMarkdown again and report what labels exist with record counts.
7. Run a test recall: findRecords with labels:["PREFERENCE"] limit:5

Step 4 — Validate​

Ask the agent:

Search RushDB for any SESSION records. Show me the most recent one.

If it returns a session record, memory is live. From here the agent will:

  • Create a new SESSION at the start of each conversation
  • Write DECISION, TASK, PREFERENCE, and OBSERVATION records as it works
  • Recall past context with structured queries or semantic search
LabelWhat it stores
SESSIONA conversation or work session with timestamp and topic
DECISIONA decision made, with rationale
ENTITYA named thing — person, service, project, concept
TASKWork item with status and assignee
PREFERENCEPersistent user preference or constraint
OBSERVATIONRaw note or finding
PLANProposed sequence of steps
ARTIFACTA produced output — code snippet, doc, design

Nested JSON auto-links records — no manual edge wiring:

{
  "label": "SESSION",
  "data": {
    "topic": "auth refactor",
    "startedAt": "2026-05-31T09:00:00Z",
    "DECISION": [{ "decision": "Switch to Clerk", "rationale": "Better Next.js integration" }],
    "TASK": [{ "title": "Remove Auth0 dependency", "status": "pending" }]
  }
}

One createRecord call creates SESSION → DECISION + TASK, all linked automatically.

Recall Patterns​

Copy these into your agent's system prompt or run them on demand:

Last session summary:

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

What did we decide about X?

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

Semantic recall (meaning-based):

semanticSearch: query="how did we handle auth", labels=["DECISION"], limit=5

→ Requires a one-time embedding index. See Schema Self-Awareness for setup.

Next Steps​