Surrealdb

Name: Surrealdb
Author: 24601

24601/surreal-skills

229 installs
34 repo stars
Updated June 17, 2026
24601/surreal-skills

surrealdb is a Claude Code skill that gives an agent expert SurrealDB 3 knowledge for SurrealQL, multi-model data modeling, schema design, security, deployment, performance tuning, and SDK integration.

About

surrealdb is a Claude Code skill that provides expert-level SurrealDB 3 architecture, development, and operations knowledge. It covers SurrealQL, multi-model data modeling, graph traversal, vector search, security, deployment, performance tuning, and SDK integration for many languages. It ships scripts to health-check a live instance, introspect its schema, and emit an agent capabilities manifest. A developer uses it to design SurrealDB schemas, write queries, and integrate the database into an application.

Expert SurrealDB 3 skill covering SurrealQL, multi-model data modeling (document, graph, vector, time-series, geospatial
SDK integration across JS, Python, Go, Rust, Java, .NET, C, PHP, Swift, Kotlin and Ruby
Ships doctor.py health-check, schema.py introspection, and onboard.py agent-manifest scripts plus 20+ rule references

Surrealdb by the numbers

229 all-time installs (skills.sh)
Ranked #214 of 911 Databases skills by installs in the Skillselion catalog
Data as of Aug 2, 2026 (Skillselion catalog sync)

At a glance

surrealdb capabilities & compatibility

Free; open-source SurrealDB CLI plus Python/uv. Scripts connect to a user-specified SurrealDB endpoint with SURREAL_USER/SURREAL_PASS.

Capabilities: database schema design · surrealql queries · vector search · graph queries · schema introspection · sdk integration
Works with: docker · github
Use cases: database · api development · devops
Platforms: macOS
IDEs: vscode · jetbrains · neovim · zed
Pricing: Free

From the docs

What surrealdb says it does

Expert-level SurrealDB 3 architecture, development, and operations.

SKILL.md

SurrealQL mastery, multi-model data modeling (document, graph, vector, time-series, geospatial), schema design, security, deployment, performance tuning

SKILL.md

npx skills add https://github.com/24601/surreal-skills --skill surrealdb

Add your badge

Show developers this skill is listed on Skillselion. Paste this into your README.

[![Listed on Skillselion](https://skillselion.com/badge/skills/24601/surreal-skills/surrealdb.svg)](https://skillselion.com/skills/24601/surreal-skills/surrealdb)

Installs	229
repo stars	★ 34
Last updated	June 17, 2026
Repository	24601/surreal-skills ↗

What it does

A developer designs a SurrealDB schema, writes SurrealQL queries, and integrates the database via an SDK while health-checking a running instance.

Who is it for?

Developers designing schemas, writing SurrealQL, and integrating SurrealDB 3 into applications across many language SDKs

Skip if: Projects not using SurrealDB, or teams needing a different database system

When should I use this skill?

The user works with SurrealDB, SurrealQL, multi-model or graph/vector data modeling, or SurrealDB SDK/ecosystem integration

What you get

Correct SurrealDB 3 schemas, queries, security, and SDK integrations grounded in current (v3.1.4+) behavior.

SurrealDB schema designs
SurrealQL queries
schema introspection output

By the numbers

version 1.7.1
SDKs for 11 languages
20+ rule reference files

Files

.github/
- ISSUE_TEMPLATE/
- skills/
  - surrealdb/
- workflows/
notes/
references/
rules/
scripts/

.github/skills/surrealdb/SKILL.mdMarkdownGitHub ↗

SurrealDB 3 Expert Skill

Expert-level SurrealDB 3 architecture, development, and operations for GitHub Copilot.

When Copilot Should Use This Skill

Activate automatically when the user:

Writes or asks about SurrealQL queries
Works with .surql files
Designs database schemas for SurrealDB
Configures SurrealDB deployment or Docker
Uses SurrealDB SDKs (JavaScript, Python, Go, Rust, Java, Kotlin, .NET, C, PHP, Swift, Ruby)
Works with graph relationships (RELATE, traversal)
Implements vector search or RAG patterns
Configures security, permissions, or access control
Builds Surrealism WASM extensions
Migrates data to SurrealDB from other databases
Connects SurrealDB to MCP hosts, n8n, AI frameworks, or custom editors

Rules Reference

This skill contains 18 detailed rule files. Read the relevant rule file when the user's request matches its domain:

Rule File	When to Load	Domain
surrealql.md	Writing or debugging SurrealQL queries	Full SurrealQL language reference
data-modeling.md	Designing schemas, choosing field types, record IDs	Multi-model schema design patterns
graph-queries.md	RELATE, graph traversal, path expressions	Graph edge and traversal patterns
vector-search.md	HNSW indexes, similarity search, embeddings	Vector search and RAG pipelines
security.md	Permissions, auth, JWT, access control	Row-level security and auth flows
deployment.md	Installing, configuring, running SurrealDB	Storage engines, Docker, Kubernetes
performance.md	Slow queries, index strategy, EXPLAIN	Performance tuning and optimization
sdks.md	Using SurrealDB from application code	JS, Python, Go, Rust, Java, Kotlin, .NET, C, PHP, Swift, Ruby patterns
surrealism.md	Writing WASM extensions	Rust to WASM extension development
surrealml.md	Working near SurrealML	Preview .surml boundary and native dependency warning
surrealmcp.md	Connecting AI hosts	MCP tool catalog and deployment
editor-tooling.md	Editor / IDE support	LSP, tree-sitter, CodeMirror, editor extensions
langchain.md	LangChain RAG	Python vector store API
ecosystem-integrations.md	n8n / framework pointers	n8n, AI framework docs, Spectron boundary, Agent Skills
surrealist.md	Using the Surrealist IDE/GUI	IDE features and schema designer
surreal-sync.md	Migrating from other databases	CDC sync from Postgres, Mongo, etc.
surrealfs.md	AI agent filesystem operations	Virtual FS backed by SurrealDB
surrealkit.md	Schema sync, rollouts, seeds, and declarative tests	Desired-state schema management for SurrealDB apps

Quick Reference

SurrealQL Essentials

-- Create records
CREATE person:alice SET name = 'Alice', age = 30;

-- Graph edges
RELATE person:alice->follows->person:bob SET since = time::now();

-- Traverse graph
SELECT ->follows->person.name AS following FROM person:alice;

-- Vector search (HNSW)
DEFINE INDEX idx_embed ON document FIELDS embedding HNSW DIMENSION 1536 DIST COSINE;
SELECT * FROM document WHERE embedding <|10,40|> $query_vector;

-- Row-level permissions
DEFINE TABLE post SCHEMALESS PERMISSIONS
  FOR select WHERE published = true OR user = $auth.id
  FOR create, update WHERE user = $auth.id;

-- Live queries
LIVE SELECT * FROM person WHERE age > 25;

Key Concepts

Record IDs: table:id (e.g., person:alice) -- first-class citizens, no JOINs needed
Multi-model: Document + Graph + Vector + Time-series + Geospatial in one DB
Graph operators: -> (outgoing), <- (incoming), <-> (bidirectional)
KNN operator: <|K,EF|> where K=neighbors, EF=search parameter (NOT distance metric)
Storage engines: memory, RocksDB, SurrealKV (time-travel), TiKV (distributed)
WASM extensions: New in v3 -- write Rust, compile to WASM, register with DEFINE MODULE

Scripts

# Health check
uv run scripts/doctor.py

# Schema introspection
uv run scripts/schema.py introspect

# Check upstream for updates
uv run scripts/check_upstream.py

Security Notes

Examples use root/root for local development only. Use scoped credentials in production.
Scripts connect to user-specified endpoints only. No third-party network calls.
Table names are validated against [a-zA-Z_][a-zA-Z0-9_]* before query interpolation.
Prefer package-manager or container installs over remote shell installers.

Describe the Bug

A clear and concise description of what the bug is.

Steps to Reproduce

1. Run ... 2. Use rule file ... 3. See error

Expected Behavior

A clear description of what you expected to happen.

Actual Behavior

What actually happened, including any error messages or incorrect output.

Environment

SurrealDB version: (surreal version)
Python version: (python3 --version)
Operating system:
AI coding agent (if applicable): (e.g., Claude Code, Cursor, Windsurf, Cline)
Skill version:

Relevant Log Output

Paste any relevant log output here.

Additional Context

Add any other context about the problem here, such as related rule files or script arguments used.

blank_issues_enabled: true
contact_links:
  - name: SurrealDB Documentation
    url: https://surrealdb.com/docs
    about: Official SurrealDB documentation
  - name: SurrealDB Discord
    url: https://discord.gg/surrealdb
    about: Community support

name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

permissions:
  contents: read

jobs:
  validate:
    name: Validate Skill
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v6.0.2

      - name: Set up Python
        uses: actions/setup-python@v6.2.0
        with:
          python-version: "3.12"

      - name: Install uv
        uses: astral-sh/setup-uv@v8.1.0
        with:
          enable-cache: false

      - name: Validate SKILL.md frontmatter
        run: |
          echo "Checking SKILL.md exists and has frontmatter..."
          if [ ! -f SKILL.md ]; then
            echo "ERROR: SKILL.md not found"
            exit 1
          fi
          head -1 SKILL.md | grep -q "^---" || { echo "ERROR: SKILL.md missing frontmatter delimiter"; exit 1; }
          grep -q "^name:" SKILL.md || { echo "ERROR: SKILL.md missing 'name' field"; exit 1; }
          grep -q "^description:" SKILL.md || { echo "ERROR: SKILL.md missing 'description' field"; exit 1; }
          echo "SKILL.md frontmatter is valid."

      - name: Python syntax check
        run: |
          echo "Checking Python script syntax..."
          for script in scripts/*.py; do
            echo "  Checking $script"
            python3 -m py_compile "$script"
          done
          echo "All Python scripts compile successfully."

      - name: Smoke test onboard script
        run: |
          uv run scripts/onboard.py --help

      - name: Validate version consistency
        run: |
          python3 - <<'PY'
          import json
          import re
          from pathlib import Path

          version_re = re.compile(r'(?m)^  version:\s*"([^"]+)"$')

          def extract_version(path: Path) -> str:
              match = version_re.search(path.read_text())
              if not match:
                  raise SystemExit(f"missing metadata.version in {path}")
              return match.group(1)

          root_version = extract_version(Path("SKILL.md"))

          for path in sorted(Path("skills").glob("*/SKILL.md")):
              subskill_version = extract_version(path)
              if subskill_version != root_version:
                  raise SystemExit(f"{path} version {subskill_version} != root version {root_version}")

          sources = json.loads(Path("SOURCES.json").read_text())
          if sources.get("skill_version") != root_version:
              raise SystemExit(
                  f"SOURCES.json skill_version {sources.get('skill_version')} != root version {root_version}"
              )
          PY

      - name: Smoke test script entrypoints
        run: |
          uv run scripts/onboard.py --agent >/tmp/onboard.json
          uv run scripts/schema.py --help >/dev/null
          uv run scripts/doctor.py --help >/dev/null

      - name: Verify rule files exist
        run: |
          echo "Checking required rule files..."
          expected_rules=(
            "rules/surrealql.md"
            "rules/data-modeling.md"
            "rules/graph-queries.md"
            "rules/vector-search.md"
            "rules/security.md"
            "rules/performance.md"
            "rules/sdks.md"
            "rules/deployment.md"
            "rules/surrealism.md"
            "rules/surreal-sync.md"
            "rules/surrealist.md"
            "rules/surrealfs.md"
            "rules/surrealkit.md"
            "rules/surrealml.md"
            "rules/surrealmcp.md"
            "rules/editor-tooling.md"
            "rules/langchain.md"
            "rules/ecosystem-integrations.md"
            "rules/gotchas.md"
          )
          missing=0
          for rule in "${expected_rules[@]}"; do
            if [ ! -f "$rule" ]; then
              echo "  MISSING: $rule"
              missing=$((missing + 1))
            else
              echo "  OK: $rule"
            fi
          done
          if [ $missing -gt 0 ]; then
            echo "ERROR: $missing rule file(s) missing"
            exit 1
          fi
          echo "All rule files present."

      - name: Verify community files
        run: |
          echo "Checking community files..."
          for file in CHANGELOG.md CONTRIBUTING.md LICENSE SECURITY.md; do
            if [ ! -f "$file" ]; then
              echo "  MISSING: $file"
              exit 1
            else
              echo "  OK: $file"
            fi
          done
          echo "All community files present."

      - name: Validate sub-skill manifests
        run: |
          echo "Checking sub-skill SKILL.md files..."
          for subskill in skills/*/SKILL.md; do
            echo "  Checking $subskill"
            head -1 "$subskill" | grep -q "^---" || { echo "ERROR: $subskill missing frontmatter"; exit 1; }
          done
          echo "All sub-skill manifests valid."

      - name: Version consistency
        run: |
          python3 scripts/check_version_consistency.py

name: Release

on:
  release:
    types: [published]
  workflow_dispatch:
    inputs:
      tag:
        description: "Existing release tag to (re)publish (e.g. v1.4.0)"
        required: true
        type: string

permissions:
  contents: read

jobs:
  validate-and-publish:
    name: Validate and Publish
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v6.0.2
        with:
          ref: ${{ github.event_name == 'workflow_dispatch' && inputs.tag || github.ref }}

      - name: Set up Python
        uses: actions/setup-python@v6.2.0
        with:
          python-version: "3.12"

      - name: Install uv
        uses: astral-sh/setup-uv@v8.1.0
        with:
          enable-cache: false

      - name: Python syntax validation
        run: |
          for script in scripts/*.py; do
            echo "Compiling $script"
            python3 -m py_compile "$script"
          done

      - name: Validate SKILL.md
        run: |
          if [ ! -f SKILL.md ]; then
            echo "ERROR: SKILL.md not found"
            exit 1
          fi
          head -1 SKILL.md | grep -q "^---" || { echo "ERROR: SKILL.md missing frontmatter"; exit 1; }
          grep -q "^name:" SKILL.md || { echo "ERROR: SKILL.md missing 'name' field"; exit 1; }
          grep -q "^description:" SKILL.md || { echo "ERROR: SKILL.md missing 'description' field"; exit 1; }
          echo "SKILL.md is valid."

      - name: Validate version consistency
        env:
          RELEASE_VERSION: ${{ github.event_name == 'workflow_dispatch' && inputs.tag || github.ref_name }}
        run: |
          python3 - <<'PY'
          import json
          import os
          import re
          import sys
          from pathlib import Path

          expected = os.environ["RELEASE_VERSION"]
          if expected.startswith("v"):
              expected = expected[1:]

          version_re = re.compile(r'(?m)^  version:\s*"([^"]+)"$')
          badge_re = re.compile(r'badge/version-([0-9][^-\]]*)-blue')
          changelog_re = re.compile(r'(?m)^## \[([^\]]+)\] - ')

          def extract_version(path: Path) -> str:
              match = version_re.search(path.read_text())
              if not match:
                  raise SystemExit(f"missing metadata.version in {path}")
              return match.group(1)

          root_version = extract_version(Path("SKILL.md"))
          if root_version != expected:
              raise SystemExit(f"SKILL.md version {root_version} != release tag {expected}")

          for path in sorted(Path("skills").glob("*/SKILL.md")):
              subskill_version = extract_version(path)
              if subskill_version != expected:
                  raise SystemExit(f"{path} version {subskill_version} != release tag {expected}")

          sources = json.loads(Path("SOURCES.json").read_text())
          if sources.get("skill_version") != expected:
              raise SystemExit(
                  f"SOURCES.json skill_version {sources.get('skill_version')} != release tag {expected}"
              )

          readme = Path("README.md").read_text()
          badge = badge_re.search(readme)
          if not badge or badge.group(1) != expected:
              raise SystemExit("README.md version badge does not match release tag")

          changelog = Path("CHANGELOG.md").read_text()
          latest = changelog_re.search(changelog)
          if not latest or latest.group(1) != expected:
              raise SystemExit("CHANGELOG.md latest entry does not match release tag")

          if not Path("rules/surrealkit.md").exists():
              raise SystemExit("rules/surrealkit.md is missing")
          if not Path("rules/ecosystem-integrations.md").exists():
              raise SystemExit("rules/ecosystem-integrations.md is missing")
          PY

      - name: Script smoke tests
        run: |
          uv run scripts/onboard.py --agent >/tmp/onboard.json
          uv run scripts/schema.py --help >/dev/null
          uv run scripts/doctor.py --help >/dev/null

      - name: Set up Node
        uses: actions/setup-node@v6.4.0
        with:
          node-version: "22"

      - name: Publish to clawhub.ai
        env:
          CLAWHUB_TOKEN: ${{ secrets.CLAWHUB_TOKEN }}
          RELEASE_TAG: ${{ github.event_name == 'workflow_dispatch' && inputs.tag || github.ref_name }}
        run: |
          [ -n "$CLAWHUB_TOKEN" ] || { echo "ERROR: CLAWHUB_TOKEN is not configured"; exit 1; }
          VERSION="${RELEASE_TAG#v}"
          CHANGELOG_TEXT="$(
            VERSION="$VERSION" python3 - <<'PY'
          import os
          import re
          from pathlib import Path

          version = os.environ["VERSION"]
          changelog = Path("CHANGELOG.md").read_text()
          match = re.search(
              rf"(?ms)^## \[{re.escape(version)}\] - .*?(?=^## \[|\Z)",
              changelog,
          )
          if not match:
              raise SystemExit(f"missing CHANGELOG.md entry for {version}")
          print(match.group(0).strip())
          PY
          )"
          export CLAWHUB_CONFIG_PATH="$RUNNER_TEMP/clawhub-config.json"
          echo "Publishing skill to clawhub.ai..."
          npx --yes clawhub login --token "$CLAWHUB_TOKEN" --no-browser
          PUBLISH_LOG="$RUNNER_TEMP/clawhub-publish.log"
          set +e
          npx --yes clawhub publish . \
            --slug surrealdb \
            --name "SurrealDB 3" \
            --version "$VERSION" \
            --changelog "$CHANGELOG_TEXT" \
            --tags "latest,ai-agents,database,graph,openclaw,surrealdb,vector" \
            2>&1 | tee "$PUBLISH_LOG"
          PUBLISH_STATUS=${PIPESTATUS[0]}
          set -e
          if [ "$PUBLISH_STATUS" -ne 0 ]; then
            if grep -Fq "Version already exists" "$PUBLISH_LOG"; then
              echo "Version already exists on clawhub.ai; treating as already published."
            else
              echo "ERROR: Failed to publish to clawhub.ai"
              exit "$PUBLISH_STATUS"
            fi
          else
            echo "Published successfully."
          fi

      - name: Trigger skills.sh reindex
        run: |
          echo "Triggering skills.sh reindex..."
          curl --fail-with-body --silent --show-error --retry 3 --retry-all-errors \
            --proto '=https' --tlsv1.2 -X POST \
            "https://skills.sh/api/reindex?repo=$GITHUB_REPOSITORY" \
            || echo "WARNING: skills.sh reindex trigger failed (non-fatal)"
          echo "Reindex triggered."

name: Upstream Freshness Check

on:
  schedule:
    # Run at 06:00 UTC every day
    - cron: '0 6 * * *'
  workflow_dispatch: {}

permissions:
  contents: read
  issues: write

jobs:
  check-upstream:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v6.0.2

      - name: Install uv
        uses: astral-sh/setup-uv@v8.1.0
        with:
          enable-cache: false

      - name: Check upstream repos
        id: check
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          uv run scripts/check_upstream.py --json > /tmp/upstream-report.json 2>/dev/null
          STALE_COUNT=$(jq '.stale_count' /tmp/upstream-report.json)
          echo "stale_count=$STALE_COUNT" >> "$GITHUB_OUTPUT"

          if [ "$STALE_COUNT" -gt 0 ]; then
            RULES=$(jq -r '.rules_to_update | join(", ")' /tmp/upstream-report.json)
            echo "rules_to_update=$RULES" >> "$GITHUB_OUTPUT"

            DETAILS=""
            for repo in $(jq -r '.repos[] | select(.status == "changed") | .repo' /tmp/upstream-report.json); do
              commits=$(jq -r --arg r "$repo" '.repos[] | select(.repo == $r) | .commits_behind' /tmp/upstream-report.json)
              baseline=$(jq -r --arg r "$repo" '.repos[] | select(.repo == $r) | .baseline_sha' /tmp/upstream-report.json)
              current=$(jq -r --arg r "$repo" '.repos[] | select(.repo == $r) | .current_sha' /tmp/upstream-report.json)
              DETAILS="${DETAILS}- **${repo}**: ${commits} new commits (${baseline} -> ${current})\n"
            done
            echo "details<<EOF" >> "$GITHUB_OUTPUT"
            echo -e "$DETAILS" >> "$GITHUB_OUTPUT"
            echo "EOF" >> "$GITHUB_OUTPUT"
          fi

      - name: Create issue if stale
        if: steps.check.outputs.stale_count > 0
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          gh label create "upstream-update" \
            --description "Tracks upstream SurrealDB ecosystem drift" \
            --color "5319e7" >/dev/null 2>&1 || true

          # Check for existing open issue to avoid duplicates
          EXISTING=$(gh issue list --label "upstream-update" --state open --json number --jq '.[0].number // empty')
          if [ -n "$EXISTING" ]; then
            gh issue comment "$EXISTING" --body "$(cat <<BODY
          ## Nightly Upstream Check -- $(date -u +%Y-%m-%d)

          ${{ steps.check.outputs.stale_count }} upstream repo(s) have new commits.

          **Changed repos:**
          ${{ steps.check.outputs.details }}
          **Rules to review:** ${{ steps.check.outputs.rules_to_update }}

          Run \`uv run scripts/check_upstream.py\` locally for full details.
          BODY
          )"
          else
            gh issue create \
              --title "Upstream update: ${{ steps.check.outputs.stale_count }} repo(s) changed" \
              --label "upstream-update" \
              --body "$(cat <<BODY
          ## Nightly Upstream Check -- $(date -u +%Y-%m-%d)

          ${{ steps.check.outputs.stale_count }} upstream repo(s) have new commits since the last skill snapshot.

          **Changed repos:**
          ${{ steps.check.outputs.details }}
          **Rules to review:** ${{ steps.check.outputs.rules_to_update }}

          ### Next steps
          1. Run \`uv run scripts/check_upstream.py\` to see full diff
          2. Review changelogs for each changed repo
          3. Update affected rules files
          4. Bump SOURCES.json SHAs
          5. Release new skill version
          BODY
          )"
          fi

      - name: Summary
        run: |
          echo "### Upstream Check Results" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY
          if [ "${{ steps.check.outputs.stale_count }}" = "0" ]; then
            echo "All upstream sources are current. No updates needed." >> $GITHUB_STEP_SUMMARY
          else
            echo "${{ steps.check.outputs.stale_count }} repo(s) have new commits." >> $GITHUB_STEP_SUMMARY
            echo "" >> $GITHUB_STEP_SUMMARY
            echo "**Rules to review:** ${{ steps.check.outputs.rules_to_update }}" >> $GITHUB_STEP_SUMMARY
          fi

Agent Briefing: surrealdb

Structured reference for AI agents. Minimal prose, maximum signal.

Quick Start

# Check if configured
uv run {baseDir}/scripts/onboard.py --check

# Get full capabilities manifest (JSON)
uv run {baseDir}/scripts/onboard.py --agent

Capabilities

Command	Script	What It Does	When to Use
`doctor`	`scripts/doctor.py`	Health check: CLI, connectivity, version, storage	First run, troubleshooting, verifying environment
`doctor --check`	`scripts/doctor.py`	Quick pass/fail (exit code only)	CI pipelines, pre-flight checks
`schema introspect`	`scripts/schema.py`	Full schema dump (tables, fields, indexes, events)	Understanding existing database structure
`schema tables`	`scripts/schema.py`	List tables with field counts and indexes	Quick overview of database contents
`schema table <name>`	`scripts/schema.py`	Inspect a single table in detail	Debugging a specific table definition
`schema export`	`scripts/schema.py`	Export schema as SurrealQL or JSON	Reproducible deployments, version control
`onboard --agent`	`scripts/onboard.py`	JSON capabilities manifest	Agent self-discovery, integration setup
`onboard --check`	`scripts/onboard.py`	Verify prerequisites	First run, CI

Decision Trees

"User wants to create a SurrealDB project"

1. Run doctor to verify environment:
   uv run {baseDir}/scripts/doctor.py

2. Is surreal CLI installed?
   NO  -> brew install surrealdb/tap/surreal (or see https://surrealdb.com/install)
   YES -> Continue

3. Choose storage engine (LOCAL DEV -- use scoped credentials in production):
   Development     -> surreal start memory --user root --pass root
   Single-node     -> surreal start rocksdb://data/mydb.db --user root --pass root
   Time-travel     -> surreal start surrealkv://data/mydb --user root --pass root
   Distributed     -> surreal start tikv://... --user root --pass root

4. Design schema:
   -> Reference rules/data-modeling.md for table/field patterns
   -> Reference rules/graph-queries.md if domain has relationships
   -> Reference rules/vector-search.md if semantic search needed

5. Apply schema (local dev credentials -- use scoped users in production):
   surreal import --endpoint $SURREAL_ENDPOINT --user root --pass root \
     --ns <ns> --db <db> schema.surql

6. Verify:
   uv run {baseDir}/scripts/schema.py introspect

"User has a data modeling question"

What kind of data?
  Documents/records    -> rules/data-modeling.md (record IDs, field types, schema modes)
  Relationships/graphs -> rules/graph-queries.md (RELATE, edge tables, traversal)
  Vector embeddings    -> rules/vector-search.md (vector fields, HNSW indexes, similarity)
  Time-series          -> rules/data-modeling.md (datetime fields, range queries, aggregations)
  Geospatial           -> rules/data-modeling.md (geometry types, geo functions, spatial indexes)
  Mixed/multi-model    -> rules/data-modeling.md + relevant specialized rules

Need schema validation?
  YES -> DEFINE TABLE ... SCHEMAFULL (strict, all fields must be defined)
  PARTIAL -> DEFINE TABLE ... SCHEMALESS (flexible, defined fields are validated)

"User needs to optimize performance"

1. Check current schema and indexes:
   uv run {baseDir}/scripts/schema.py introspect

2. Identify bottleneck type:
   Slow queries        -> rules/performance.md (EXPLAIN, index strategies)
   High write latency  -> rules/performance.md (batch operations, storage engine)
   Memory pressure     -> rules/deployment.md (resource limits, storage engine selection)
   Connection issues   -> rules/sdks.md (connection pooling, WebSocket vs HTTP)

3. Index audit:
   Missing index on filtered field  -> DEFINE INDEX ... ON TABLE ... FIELDS ...
   Full-text search slow             -> DEFINE INDEX ... SEARCH ANALYZER ...
   Vector search slow                -> DEFINE INDEX ... HNSW DIMENSION ... DIST ...

4. Storage engine review:
   Memory       -> Fast but volatile, development only
   RocksDB      -> General purpose, good read/write balance
   SurrealKV    -> Time-travel queries, versioned data
   TiKV         -> Distributed, horizontal scaling

"User wants to write WASM extensions"

1. Reference rules/surrealism.md for Surrealism module system
2. Prerequisites: Rust toolchain, wasm32-unknown-unknown target
3. Workflow:
   a. Create Rust project with surrealism SDK
   b. Implement custom functions/analyzers
   c. Compile to WASM
   d. Deploy to SurrealDB instance
   e. Use in SurrealQL queries via custom function syntax

"User wants to deploy / serve an ML model"

1. Reference rules/surrealml.md
2. Prerequisites: `surrealml` PyPI package 0.0.4 (extras: [sklearn] / [torch] /
   [tensorflow]); SurrealML is preview-stage and the SurrealQL invocation
   surface is unstable as of 2026-06-17.
3. The v1.4.0 documentation for `DEFINE MODEL`, `INFO FOR MODEL`,
   `ml::name<version>(...)`, `surreal ml import`, `db.upload_ml(...)`, and
   `SurMlFile.from_<framework>(...)` was retracted in v1.4.1 -- those
   surfaces were not present in current upstream. Treat anything beyond the
   `.surml` artifact format and the supported pip extras as pending
   verification; pin to a specific surrealml commit and consult the upstream
   `clients/python` source before writing code.
4. Stable patterns that don't depend on the unstable ML surface:
   - DEFINE INDEX ... HNSW DIMENSION ... DIST COSINE for vector storage
   - Compute embeddings client-side, persist with UPDATE in the same
     transaction

"User hit a surprising SurrealDB behavior / gotcha"

1. Reference rules/gotchas.md first — cross-domain footgun catalog (v3.1.4+)
2. Narrow by domain:
   Graph / RELATE / traversal     -> rules/graph-queries.md
   Vector / HNSW / DiskANN        -> rules/vector-search.md
   Permissions / auth             -> rules/security.md
   Upgrade / deploy / metrics     -> rules/deployment.md
   MCP / agent tooling            -> rules/surrealmcp.md
   Language / schema DDL          -> rules/surrealql.md
3. Confirm server version — many gotchas are version-gated (3.0.5 vs 3.1.x)
4. Recommend v3.1.4+ minimum for production when security fixes apply

"User wants AI agents to talk to SurrealDB"

1. Reference rules/surrealmcp.md
2. Choose MCP surface:
   Built-in (SurrealDB 3.1+) -> `surreal mcp` stdio or HTTP POST /mcp on a running server
   Standalone surrealmcp     -> extended tool catalog, cloud helpers, multi-endpoint switching
3. Built-in stdio (local IDE hosts — Cursor, Claude Desktop, Copilot in VS Code, Zed):
   surreal mcp --endpoint ws://localhost:8000/rpc --ns ... --db ... --user ... --pass ...
   WARNING: stdio MCP grants owner-level tool access with no login step — do not expose to untrusted hosts.
4. Standalone install (when built-in tools are insufficient):
   `cargo install --path .` from github.com/surrealdb/surrealmcp,
   OR `docker run --rm -i --pull always surrealdb/surrealmcp:latest start`.
   `surrealmcp` is NOT published to crates.io or npm.
5. Add to host MCP config — consult each host's own MCP docs for path/key shape.
6. Standalone binary requires `start` subcommand: `surrealmcp start --ns ... --db ...`.
   Connection env vars: SURREALDB_URL / SURREALDB_NS / SURREALDB_DB /
   SURREALDB_USER / SURREALDB_PASS. Server-side env vars use SURREAL_MCP_* prefix.
7. Production: scoped DB user (DEFINE USER ... ON DATABASE ROLES VIEWER),
   TLS, JWT bearer auth, `--rate-limit-rps` / `--rate-limit-burst` (standalone),
   RUST_LOG for structured logging, GET /health for health checks (standalone HTTP).

"User wants editor / IDE support"

1. Reference rules/editor-tooling.md
2. Prerequisites: an LSP binary on $PATH. First-party baseline:
   `surrealql-language-server` v0.1.6. `surql-lsp` v0.1.1 is a separate
   community crate.
3. Pick the editor:
   VS Code / Cursor / Windsurf -> "SurrealQL" extension (Marketplace + OpenVSX)
   JetBrains                    -> "SurrealQL" plugin (JetBrains Marketplace)
   Neovim                       -> surrealdb/surrealql-neovim + nvim-treesitter
   Helix                        -> wire via languages.toml once LSP is on $PATH
   Zed                          -> Zed extensions panel
4. Custom web editors -> `@surrealdb/codemirror` / `@surrealdb/lezer` v1.0.6
5. Per-extension command palettes, settings catalogs, and config-file
   schemas must still be verified against each extension's own README.

"User wants LangChain / RAG"

1. Reference rules/langchain.md + rules/vector-search.md
2. Python (verified package: langchain-surrealdb 0.2.1, deps
   langchain-core ~= 1.1.0 and surrealdb ~= 1.0.8 -- v1 SurrealDB SDK,
   not v2):
   pip install -U langchain-surrealdb surrealdb
   # Open the connection yourself, then pass it to the constructor:
   conn = Surreal("ws://localhost:8000/rpc")
   conn.signin({"username": "root", "password": "root"})
   conn.use("ns", "db")
   store = SurrealDBVectorStore(embeddings, conn)
   # Note: kwarg is `custom_filter`, not `filter`
   store.similarity_search_with_score(query=..., k=..., custom_filter={...})
3. JS/TS: NO official `@langchain/surrealdb` npm package as of 2026-06-17;
   the v1.4.0 documentation for it was retracted in v1.4.1. Use the v2
   JavaScript SurrealDB SDK directly until an official integration ships.
4. For multi-tenant:
   DEFINE TABLE document PERMISSIONS FOR select WHERE tenant_id = $auth.tenant_id;
   Then signin with DEFINE ACCESS record-level user before constructing the store
5. For server-side embeddings: SurrealML's invocation surface is unstable
   (rules/surrealml.md). Compute embeddings in Python with the embedding
   provider of your choice and persist via the vector store, OR via your
   own DEFINE FUNCTION wrapping a Surrealism extension.

"User wants n8n / AI framework / ecosystem integration"

1. Reference rules/ecosystem-integrations.md.
2. n8n:
   - Use scoped npm package `@surrealdb/n8n-nodes-surrealdb` v0.6.0.
   - Self-hosted n8n only; community nodes do not run in n8n Cloud.
   - HTTP/HTTPS only; do not configure ws:// or wss:// endpoints.
   - Set N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true only if exposing the
     node as an AI tool.
   - Use scoped SurrealDB users and parameterized query inputs.
3. AI framework docs:
   - LangChain has a verified local rule (`rules/langchain.md`).
   - Agno, Camel, CrewAI, Dagster, Google Agent, Kreuzberg, LlamaIndex,
     Pydantic AI, and SmolAgents are docs-index pointers. Verify package,
     import path, constructor/API shape, and SDK dependency before coding.
4. Spectron / Agent Memory Context:
   - Treat as roadmap-only until upstream publishes installable packages,
     schema/API docs, and operational guidance.
5. Official agent skills:
   - `npx skills add surrealdb/agent-skills` installs upstream narrow skills;
     this repo remains the broader SurrealDB 3 rule set.

"User migrating from another database"

Source database?
  PostgreSQL/MySQL/SQL -> rules/data-modeling.md (relational mapping to SurrealDB)
                          rules/surreal-sync.md (CDC migration with Surreal-Sync)
  MongoDB/CouchDB      -> rules/data-modeling.md (document model, record IDs)
                          rules/surreal-sync.md (CDC migration)
  Neo4j/graph DB       -> rules/graph-queries.md (edge table mapping, traversal equivalents)
  SurrealDB v2         -> rules/surrealql.md (v2->v3 breaking changes)
                          surreal export/import for data migration
  Redis/key-value      -> rules/data-modeling.md (record ID patterns, schemaless mode)

Migration steps:
  1. Map source schema to SurrealDB tables/fields
  2. Use Surreal-Sync for CDC if available (rules/surreal-sync.md)
  3. Or export -> transform -> import with surreal CLI
  4. Verify with schema introspection

Common Workflows

1. Verify environment and connect

# Health check
uv run {baseDir}/scripts/doctor.py

# Start dev server (LOCAL DEV ONLY -- use scoped credentials in production)
surreal start memory --user root --pass root --bind 127.0.0.1:8000

# Connect (local dev)
surreal sql --endpoint http://localhost:8000 --user root --pass root --ns test --db test

2. Design and apply a schema

-- Define namespace and database context
USE NS myapp DB production;

-- Define a schemafull table with fields and indexes
DEFINE TABLE user SCHEMAFULL;
DEFINE FIELD name ON TABLE user TYPE string;
DEFINE FIELD email ON TABLE user TYPE string ASSERT string::is::email($value);
DEFINE FIELD created ON TABLE user TYPE datetime DEFAULT time::now();
DEFINE INDEX idx_user_email ON TABLE user FIELDS email UNIQUE;

-- Define a graph edge table
DEFINE TABLE follows SCHEMAFULL TYPE RELATION IN user OUT user;
DEFINE FIELD since ON TABLE follows TYPE datetime DEFAULT time::now();

-- Define permissions
DEFINE TABLE post SCHEMALESS
  PERMISSIONS
    FOR select WHERE published = true OR author = $auth.id
    FOR create, update WHERE author = $auth.id
    FOR delete WHERE author = $auth.id OR $auth.role = 'admin';

surreal import --endpoint http://localhost:8000 --user root --pass root \
  --ns myapp --db production schema.surql

uv run {baseDir}/scripts/schema.py introspect

3. Set up vector search

-- Define table with vector field
DEFINE TABLE document SCHEMALESS;
DEFINE FIELD content ON TABLE document TYPE string;
DEFINE FIELD embedding ON TABLE document TYPE array<float> ASSERT array::len($value) = 1536;

-- Create HNSW vector index
DEFINE INDEX idx_doc_embedding ON TABLE document FIELDS embedding
  HNSW DIMENSION 1536 DIST COSINE;

-- Query by similarity
SELECT *, vector::similarity::cosine(embedding, $query_vec) AS score
  FROM document
  WHERE embedding <|10,40|> $query_vec
  ORDER BY score DESC
  LIMIT 10;

4. Graph traversal queries

-- Create records and relationships
CREATE person:alice SET name = 'Alice', role = 'engineer';
CREATE person:bob SET name = 'Bob', role = 'manager';
CREATE project:atlas SET name = 'Atlas', status = 'active';

RELATE person:alice->works_on->project:atlas SET since = d'2025-01-15';
RELATE person:bob->manages->project:atlas;
RELATE person:bob->mentors->person:alice SET topic = 'architecture';

-- Traverse outgoing edges
SELECT ->works_on->project.name AS projects FROM person:alice;

-- Traverse incoming edges
SELECT <-works_on<-person.name AS engineers FROM project:atlas;

-- Multi-hop traversal
SELECT ->mentors->person->works_on->project.name AS mentee_projects FROM person:bob;

-- Bidirectional traversal
SELECT <->mentors<->person.name AS mentorship_peers FROM person:alice;

5. Production deployment checklist

# 1. Choose storage engine (see rules/deployment.md)
# NOTE: 0.0.0.0 is correct for production servers behind a firewall/load balancer.
# For local dev, use 127.0.0.1 instead.
surreal start rocksdb://data/production.db \
  --user $SURREAL_USER --pass $SURREAL_PASS \
  --bind 0.0.0.0:8000 \
  --log info

# 2. Apply schema
surreal import --endpoint $SURREAL_ENDPOINT \
  --user $SURREAL_USER --pass $SURREAL_PASS \
  --ns production --db main schema.surql

# 3. Set up access control (see rules/security.md)
# 4. Configure backups
surreal export --endpoint $SURREAL_ENDPOINT \
  --user $SURREAL_USER --pass $SURREAL_PASS \
  --ns production --db main backup-$(date +%Y%m%d).surql

# 5. Verify
uv run {baseDir}/scripts/doctor.py --endpoint $SURREAL_ENDPOINT
uv run {baseDir}/scripts/schema.py introspect --endpoint $SURREAL_ENDPOINT

Rules Manifest

Rule	Description
`rules/surrealql.md`	Complete SurrealQL language reference: statements, functions, operators, idioms, v2-to-v3 migration notes
`rules/data-modeling.md`	Schema design patterns: record IDs, field types, schemafull vs schemaless, normalization, multi-model strategies, time-series, geospatial
`rules/graph-queries.md`	Graph edge creation with RELATE, traversal operators (-> <- <->), path expressions, recursive queries, filtering edges, aggregation
`rules/vector-search.md`	Vector field definitions, HNSW indexes (the v3 vector index type; brute-force is a fallback during index build/rebuild), distance metrics, similarity functions, RAG pipeline patterns, hybrid search
`rules/security.md`	Row-level permissions, DEFINE ACCESS (JWT, record), DEFINE USER, namespace/database/table scoping, $auth/$session variables, authentication flows
`rules/deployment.md`	Installation methods, storage engines (memory, RocksDB, SurrealKV, TiKV), Docker, Kubernetes Helm charts, production hardening, backup/restore, monitoring; `surrealdb/setup-surreal@v2` GitHub Action for CI (the v1.4.0 documentation that described setup-surreal as a CLI bootstrap was retracted in v1.4.2)
`rules/performance.md`	Index strategies (unique, search, HNSW), EXPLAIN for query analysis, batch operations, connection pooling, storage engine trade-offs, resource limits
`rules/sdks.md`	Official SDK usage for JS/TS, Python, Go, Rust, Java, Kotlin, .NET, C, PHP, Swift, Ruby plus source-only C boundary: connection setup, authentication, CRUD, live queries, typed records
`rules/surrealism.md`	Surrealism WASM extension system (new in v3): Rust SDK, custom functions, custom analyzers, module lifecycle, deployment
`rules/surrealml.md`	SurrealML scope summary (preview/unstable as of 2026-06-17); `.surml` artifact format, supported pip extras, GitHub v0.1.2 vs PyPI 0.0.4 boundary, setup-time native-library download warning
`rules/surrealmcp.md`	Model Context Protocol server (`surrealdb/surrealmcp` v0.4.0): verified install (Cargo from source / Docker; not on crates.io or npm), `surrealmcp start` CLI shape, `SURREALDB_*` env-var conventions, snake_case tool catalog grouped per upstream README, host-config pointers for Claude Desktop / Cursor / Copilot in VS Code / Zed / n8n, JWT bearer auth for HTTP mode
`rules/editor-tooling.md`	First-party `surrealql-language-server` v0.1.3, community `surql-lsp` boundary, `surrealql-tree-sitter`, CodeMirror packages, and discoverability pointers for VS Code / Cursor / Windsurf / VSCodium / JetBrains / Neovim / Helix / Sublime / Zed / Emacs extensions
`rules/langchain.md`	LangChain integration: `langchain-surrealdb` 0.2.1 (Python only) -- verified deps (`langchain-core ~= 1.1.0`, `surrealdb ~= 1.0.8` v1 SDK), constructor-based `SurrealDBVectorStore(embeddings, conn)` API, `custom_filter` kwarg. JS package, async class, chat history, and hybrid retriever from v1.4.0 were retracted in v1.4.1
`rules/ecosystem-integrations.md`	n8n community node (`@surrealdb/n8n-nodes-surrealdb` v0.6.0), official AI framework docs index, Spectron roadmap boundary, CodeMirror, official Agent Skills repo
`rules/surrealist.md`	Surrealist IDE/GUI: schema designer, query editor, graph visualizer, table explorer, connection management
`rules/surreal-sync.md`	Surreal-Sync CDC tool: source connectors, target connectors, migration workflows, incremental sync, schema translation
`rules/surrealfs.md`	SurrealFS AI agent filesystem: file storage and retrieval, metadata management, directory structures, agent integration patterns
`rules/surrealkit.md`	SurrealKit schema sync, rollout-based migrations, seeding, and declarative schema/API tests
`rules/gotchas.md`	Cross-domain edge cases, footguns, and verified gotchas (upgrade, graph, vector, security, MCP, SDKs)

Configuration Requirements

Requirement	How to Check	How to Fix
surreal CLI	`surreal version`	`brew install surrealdb/tap/surreal` or see install docs
Python 3.10+	`python3 --version`	Install from python.org or use system package manager
uv runtime	`which uv`	`brew install uv` or `pip install uv`
SurrealDB server	`uv run {baseDir}/scripts/doctor.py`	`surreal start memory --user root --pass root`

Environment variables (optional, all have defaults):

Variable	Default	Description
`SURREAL_ENDPOINT`	`http://localhost:8000`	SurrealDB server URL
`SURREAL_USER`	`root`	Authentication username
`SURREAL_PASS`	`root`	Authentication password
`SURREAL_NS`	`test`	Default namespace
`SURREAL_DB`	`test`	Default database

Output Contracts

All scripts: stderr = human-readable (Rich), stdout = JSON.

`doctor.py`

{
  "status": "healthy",
  "checks": {
    "cli_installed": true,
    "cli_version": "3.0.0",
    "server_reachable": true,
    "auth_valid": true,
    "namespace_exists": true,
    "database_exists": true,
    "storage_engine": "rocksdb"
  },
  "issues": []
}

`doctor.py` (with issues)

{
  "status": "unhealthy",
  "checks": {
    "cli_installed": true,
    "cli_version": "3.0.0",
    "server_reachable": false,
    "auth_valid": false,
    "namespace_exists": false,
    "database_exists": false,
    "storage_engine": null
  },
  "issues": ["Server not reachable at http://localhost:8000"]
}

`schema.py introspect`

{
  "namespace": "test",
  "database": "test",
  "tables": [
    {
      "name": "user",
      "type": "normal",
      "schema_mode": "schemafull",
      "fields": [
        {"name": "name", "type": "string", "default": null, "assert": null},
        {"name": "email", "type": "string", "default": null, "assert": "string::is::email($value)"}
      ],
      "indexes": [
        {"name": "idx_user_email", "fields": ["email"], "unique": true, "search": false, "vector": false}
      ],
      "events": [],
      "permissions": {"select": "FULL", "create": "FULL", "update": "FULL", "delete": "FULL"}
    }
  ],
  "accesses": [],
  "users": []
}

`schema.py tables`

{
  "tables": [
    {"name": "user", "type": "normal", "fields": 5, "indexes": 2, "events": 0},
    {"name": "follows", "type": "relation", "fields": 1, "indexes": 0, "events": 0},
    {"name": "post", "type": "normal", "fields": 8, "indexes": 3, "events": 1}
  ]
}

`onboard.py --agent`

{
  "skill": "surrealdb",
  "version": "1.7.1",
  "capabilities": ["surrealql", "data-modeling", "graph-queries", "vector-search", "security", "deployment", "performance", "sdks", "surrealism", "surrealml", "surrealmcp", "editor-tooling", "langchain", "ecosystem-integrations", "surrealist", "surreal-sync", "surrealfs", "surrealkit", "gotchas"],
  "scripts": ["doctor.py", "schema.py", "onboard.py", "check_upstream.py"],
  "rules": ["surrealql.md", "data-modeling.md", "graph-queries.md", "vector-search.md", "security.md", "deployment.md", "performance.md", "sdks.md", "surrealism.md", "surrealml.md", "surrealmcp.md", "editor-tooling.md", "langchain.md", "ecosystem-integrations.md", "surrealist.md", "surreal-sync.md", "surrealfs.md", "surrealkit.md", "gotchas.md"],
  "prerequisites": {
    "surreal_cli": true,
    "python": true,
    "uv": true,
    "server_reachable": true
  }
}

Error Handling

Exit Code	Meaning	Recovery
0	Success	N/A
1	Error	Check stderr for details

Common errors:

surreal CLI not found: Install with brew install surrealdb/tap/surreal or see https://surrealdb.com/install
Server not reachable: Start a server with surreal start memory --user root --pass root
Authentication failed: Verify SURREAL_USER and SURREAL_PASS environment variables
Namespace/database not found: Create with DEFINE NAMESPACE ... / DEFINE DATABASE ... or use USE NS ... DB ... in SurrealQL
Schema import failed: Check SurrealQL syntax; run surreal sql to test queries interactively
Permission denied: Check table-level permissions in rules/security.md

Version Information

Component	Version
SurrealDB target	3.1.4+ (recommend minimum for production)
Skill version	1.7.1
SurrealQL compat	SurrealDB 3.x
Python requirement	3.10+

Source Provenance

This skill was built from the following upstream sources. Use check_upstream.py to detect what changed since this snapshot for incremental updates.

uv run {baseDir}/scripts/check_upstream.py          # full diff report
uv run {baseDir}/scripts/check_upstream.py --stale   # only changed repos

Repository	Release	SHA (short)	Snapshot Date	Rules Affected
surrealdb/surrealdb	v3.1.4	`c9e039542e85`	2026-06-10	surrealql, data-modeling, security, performance, deployment, surrealism, surrealml, surrealmcp, vector-search, graph-queries
surrealdb/surrealist	surrealist-v3.9.0	`b0f4b03b3c6e`	2026-06-16	surrealist
surrealdb/surrealdb.js	v2.0.3	`c25ccbd12864`	2026-06-17	sdks
surrealdb/surrealdb.py	v2.0.0 (PyPI); main 3.0.0 unreleased	`616cc6eb65e7`	2026-06-17	sdks
surrealdb/surrealdb.go	v1.4.0 (main)	`82ed1db52c9e`	2026-06-17	sdks
surrealdb/surrealdb.java	v2.1.1	`175bf2584fb3`	2026-06-10	sdks
surrealdb/surrealdb.net	v0.10.2	`ab079d855b6f`	2026-06-17	sdks
surrealdb/surrealdb.php	v1.0.1	`2f8f7ade9c47`	2026-03-02	sdks
surrealdb/surrealdb.c	--	`039481e0c46f`	2026-03-06	sdks
surrealdb/surrealdb.swift	--	`046f7d5f2405`	2026-04-29	sdks
surrealdb/surrealdb.kotlin	--	`1d91ee969664`	2026-05-13	sdks
surrealdb/surrealdb.rb	v0.7.0	`5a98c3464b1f`	2026-04-01	sdks
surrealdb/surreal-sync	v0.3.4	`59b3166910f0`	2026-03-11	surreal-sync
surrealdb/surrealfs	--	`0008a3a94dbe`	2026-01-29	surrealfs
surrealdb/surrealkit	v0.7.0	`8b83dd867338`	2026-06-11	surrealkit
surrealdb/surrealmcp	v0.4.0 (standalone; built-in MCP in server 3.1+)	`6b82d699ece8`	2026-01-14	surrealmcp
surrealdb/surrealml	v0.1.2 GitHub; 0.0.4 PyPI	`152ac2d508f1`	2025-09-17	surrealml
surrealdb/surrealql-language-server	v0.1.6	`02706f9c6c98`	2026-05-28	editor-tooling
surrealdb/surrealql-tree-sitter	--	`5db387281bcc`	2026-05-07	editor-tooling
surrealdb/codemirror	v1.0.6	`f88011f3ac07`	2026-05-19	editor-tooling, ecosystem-integrations
surrealdb/langchain-surrealdb	v0.2.1	`4cfecc53efbc`	2026-03-16	langchain
surrealdb/n8n-nodes-surrealdb	v0.6.0	`a14db7def6e2`	2026-04-24	ecosystem-integrations
surrealdb/agent-skills	--	`95628976c277`	2026-06-17	ecosystem-integrations

Documentation: surrealdb.com/docs snapshot 2026-06-17.

Full provenance data: SOURCES.json (machine-readable).

Contributing to surreal-skills

Thank you for your interest in contributing to the SurrealDB 3 skill for AI coding agents. This guide covers everything you need to get started.

Prerequisites

Python 3.10+ (for running scripts)
[uv](https://docs.astral.sh/uv/) (Python package runner; no virtual environment needed)
SurrealDB CLI v3+ (surreal binary on your PATH)
Git with Conventional Commits knowledge

Development Setup

# Clone the repository
git clone https://github.com/24601/surreal-skills.git
cd surreal-skills

# Verify prerequisites
surreal version          # Should show v3.x
python3 --version        # Should show 3.10+
uv --version             # Should show latest uv

# Run the doctor script to verify your environment
uv run scripts/doctor.py

# Run the onboard script to test the setup wizard
uv run scripts/onboard.py --help

No virtual environment is required. All Python scripts use PEP 723 inline metadata, so uv run resolves dependencies automatically.

Project Structure

surreal-skills/
  SKILL.md              # Main skill manifest (frontmatter + body)
  rules/                # Knowledge base (Markdown rule files)
  scripts/              # Python tooling (PEP 723, run with uv)
  skills/               # Sub-skill manifests
  references/           # External links and cheatsheets
  tests/                # Test scripts
  .github/              # CI/CD workflows and templates

Code Style

Python Scripts (`scripts/`)

Follow PEP 8 for formatting.
Use PEP 723 inline script metadata for dependencies. Every script must be runnable with uv run scripts/<name>.py without a prior install step.
Include a module-level docstring describing the script's purpose.
Use argparse for CLI arguments.
Target Python 3.10+ (use match statements, | union types where appropriate).

Rule Files (`rules/`)

Write in standard Markdown.
Begin each file with a top-level heading (# Title).
Use fenced code blocks with language tags for all examples.
Prefer concrete, copy-pasteable examples over abstract descriptions.
Keep each rule file focused on a single topic.

SKILL.md Manifests

Frontmatter must be valid YAML between --- delimiters.
Required fields: name, description, license, metadata.version, metadata.author.

Adding or Updating Rules

1. Create or edit the appropriate file in rules/. 2. If adding a new rule file, update SKILL.md to reference it in the body section. 3. Ensure all SurrealQL examples are valid against SurrealDB v3. 4. Add the file to the expected-files list in .github/workflows/ci.yml if it is a new rule.

Commit Convention

This project uses Conventional Commits:

feat: add vector search rule file
fix: correct SurrealQL syntax in graph-queries.md
docs: update SDK examples for Python client v2
chore: update CI workflow for new rule file

Common types: feat, fix, docs, chore, refactor, test, ci.

Pull Request Process

1. Fork the repository and create a feature branch from main. 2. Make your changes following the style guidelines above. 3. Run the CI checks locally:

   # Syntax check all Python scripts
   python3 -m py_compile scripts/onboard.py
   python3 -m py_compile scripts/doctor.py
   python3 -m py_compile scripts/schema.py

   # Smoke test
   uv run scripts/onboard.py --help

4. Ensure all expected rule files exist. 5. Open a pull request against main using the PR template. 6. Fill out the checklist in the PR template. 7. A maintainer will review and provide feedback.

Issue Templates

When filing issues, please use the provided templates:

Bug Report: For errors in scripts, incorrect SurrealQL in rules, or CI failures.
Feature Request: For new rules, script enhancements, or sub-skill ideas.

Code of Conduct

Be respectful, constructive, and collaborative. We follow standard open-source community norms. Harassment, discrimination, and bad-faith contributions are not tolerated.

License

By contributing, you agree that your contributions will be licensed under the MIT License.

MIT License

Copyright (c) 2025-2026 24601

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

v1.5.x Convergence Trajectory

Tag declared stable: v1.5.10 (commit pending) Cycle dates: 2026-05-05 (single-day cycle, ~7 hours wall-clock) Reviewer: Pi+DeepSeek-V4-Pro:xhigh, run as 6 parallel processes per pass

Summary

Ten passes of single-reviewer adversarial audit closed 70 cumulative CRITs across six rule files plus deployment.md cross-fixes, ending in 6/6 GO+CONDITIONAL GO with 0 CRITs at pass-10. Per ~/CLAUDE.md "CONDITIONAL GO w/ no CRIT = ship if maintainer accepts IMPs as deferred" — v1.5.x is declared stable.

Per-pass CRIT counts

Pass	HEAD at audit	Verdicts	CRITs	Notes
1	v1.4.5 (f83ca4e)	5/5 NO-GO	21	Initial audit batch (5 rules)
2	v1.5.1 (1f0f9d4)	1 GO + 2 COND + 2 NO-GO	7	All 3 NO-GOs were v1.5.1 fix-drift
3	v1.5.2 (303faf9)	5 NO-GO + 1 COND	15	Added rules/surrealql.md as 6th target (first dedicated full-file Pi pass)
4	v1.5.3 (ff79f0b)	1 GO + 2 COND + 3 NO-GO	6	All 3 NO-GO surrealql CRITs were v1.5.3 fix-drift
5	v1.5.4 (c7aa9e9)	1 GO + 5 NO-GO	6	Major: vector-search.md JACCARD/PEARSON semantic-inversion catalog bug
6	v1.5.5 (4988d0f)	4 GO + 2 NO-GO	5	First high-GO-rate pass (4/6)
7	v1.5.6 (b5c40c8)	5 GO/COND + 1 NO-GO	1	Sharpest convergence; only DEFER fabrication caught
8	v1.5.7 (13f600b)	4 GO/COND + 2 NO-GO	2	Two pre-existing latent bugs (TYPE JWT FOR TOKEN claim wrong since v1.4.x; ALTER section absent since pre-v1.4.0)
9	v1.5.8 (59dc01a)	3 GO/COND + 3 NO-GO	5	v1.5.8 ALTER surgery introduced 2 phantom-clause CRITs; 2 cross-rule incomplete fixes from v1.5.8 callout patch; 1 pre-existing UPDATE LIMIT phantom
10	v1.5.9 (9560239)	6/6 GO+CONDITIONAL GO	0	CONVERGENCE TARGET REACHED — 0 CRITs across all 6 files
—	v1.5.10 (final)	declared stable	—	INTERSECT-as-infix sweep + ship

Total: 70 CRITs found-and-fixed across ten passes.

CRIT-trend post-pass-3

The pass-3 surrealql.md addition was an outlier (15 CRITs from a first-time full-file pass). The trend post-pass-3 shows monotone- decreasing-with-noise:

6 → 6 → 5 → 1 → 2 → 5 → 0

The pass-9 uptick (1→2→5) reflects v1.5.8 ALTER surgery fix-drift catching up. Pass-10 closure (0 CRITs across all 6) confirms the ALTER corrections held + the cycle exhausted the high-confidence correctness surface.

Notable findings

These are findings worth preserving as learnings:

Single most consequential correction: v1.5.3 LM rewrite

The HNSW LM parameter was mislabelled in v1.5.1 as "Minkowski distance order." Pass-3 verified against v3.0.5 parser source (define.rs t!("LM") => { ml = Some(self.next_token_value()?); }) that LM is the HNSW level multiplier (ml in the Malkov & Yashunin paper) used in l ← ⌊−ln(unif(0..1)) · ml⌋ for layer assignment, with default 1 / ln(M) (~0.402 at M=12). The Minkowski distance order is specified inline as DIST MINKOWSKI <order>, NOT via LM. Pre-v1.5.3 consumers who set LM N thinking they were configuring Minkowski order were silently flattening the HNSW hierarchy. Pattern: docs-only verification produced an incorrect fix; parser-body inspection corrected it.

Catalog-vs-docs mismatch: vector-search JACCARD/PEARSON

Pass-5 surfaced that the catalog's Distance::compute body (catalog/schema/index.rs:293-300) calls jaccard_similarity() and pearson_similarity() for DIST JACCARD / DIST PEARSON, while every other DIST value computes a true distance (smaller = closer). The HNSW KnnPriorityList uses ascending BTreeMap order, so configuring DIST JACCARD/PEARSON silently ranks LEAST-similar results first. v1.5.5 added an explicit warning callout. This is an upstream catalog behaviour, not a doc-only issue — flagged as a warning rather than removed because the syntax is parser-accepted.

Fix-drift pattern (`~/CLAUDE.md` empirical observation confirmed)

Every pass except pass-7 and pass-10 introduced 1-3 new bugs from the prior pass's surgery:

v1.5.1 LM "fix" was itself wrong (caught pass-3)
v1.5.2 EXPLAIN rewrite invented RangeScan + standalone Iterate
v1.5.3 vector-function adds had wrong signatures + included

unimplemented functions as if working (caught pass-4)

v1.5.3 added DEFER subsection from upstream-docs alone; parser

doesn't implement DEFER (caught pass-7)

v1.5.4 DEFINE NAMESPACE STRICT replacement was invalid v3

(caught pass-5)

v1.5.5 closure example used bare-identifier params (|x|) instead

of $-prefixed (|$x|); FORMAT TEXT removal was a regression

v1.5.5 added Computed Fields/Closures replacement section

introduced one new bug each

v1.5.6 added time::set_* + DEFINE INDEX clauses (CONCURRENTLY

was correct; DEFER carried forward as wrong claim)

v1.5.8 ALTER section had 2 phantom-clause examples (INDEX

COMPACT, SEQUENCE RESTART)

Verification escalator: docs → docs+grammar → parser body

Each pass tightened the verification standard:

Passes 1-2: relied largely on docs site
Passes 3-4: started citing parser tokens / grammar
Passes 5-7: required parser-body / function-body verification
Passes 8-10: required test-fixture parses + struct-field checks

The DEFER, FORMAT TEXT, vector::distance::knn, and ALTER findings all required parser-body inspection (registration tables alone were insufficient).

Per-rule pass-10 status

rules/data-modeling.md — CONDITIONAL GO (1 IMP fixed in v1.5.10:

INTERSECT infix → array::intersect()). Cumulative: 4 CRITs across 3 NO-GO passes (1/3/5).

rules/security.md — GO. Cumulative: 8 CRITs across 5 NO-GO

passes.

rules/vector-search.md — CONDITIONAL GO. Cumulative: 5 CRITs

including the LM correction + JACCARD/PEARSON warning.

rules/performance.md — GO. Cumulative: 18 CRITs across 6

NO-GO passes — by far the worst-drift file. Pass-7+8+10 all GO.

rules/graph-queries.md — CONDITIONAL GO (1 IMP fixed in

v1.5.10: same INTERSECT pattern). Cumulative: 10 CRITs across 4 NO-GO passes (1/2/3/4).

rules/surrealql.md — CONDITIONAL GO. Cumulative: 35+ CRITs —

highest single-file count, foundational language reference.

Deferred to v1.6.x

Approximately 30 IMPORTANT-classified items remain deferred, all documentation gaps (not contradictions of upstream):

security.md: WITH REFRESH on TYPE RECORD; JWKS URL on TYPE RECORD;

ACCESS REVOKE/SHOW/PURGE; DEFINE USER PASSHASH / DURATION clauses.

surrealql.md: function namespaces (encoding::, bytes::, file::*,

set::, sequence::, schema::, api::); data types (regex, range, literal, file); array<T,N> cardinality; INSERT IGNORE example; DEFINE API; DEFINE CONFIG; INFO FOR INDEX/USER variants. (Previously this list also claimed "10 undocumented ALTER targets" — corrected in v1.6.0: those targets do not exist in the v3.0.5 parser. v3.0.5 supports exactly seven ALTER targets — SYSTEM, NAMESPACE, DATABASE, TABLE, INDEX, FIELD, SEQUENCE — and surrealql.md now documents that explicitly. Pi/Codex passes audited clause shapes inside each ALTER subsection but did not catch the intro-paragraph target-list fabrication, a verification blind spot worth recording.)

vector-search.md: HASHED_VECTOR semantics (currently described as

memory-optimisation; needs upstream verification); MINKOWSKI in similarity-functions section; jaccard/pearson similarity-function examples.

performance.md: TLS flags in start-flag list; SURREAL_HNSW_CACHE_SIZE

env-var verification; REBUILD INDEX ON TABLE all-indexes form; SCHEMAFULL inference rationale rephrasing.

graph-queries.md: sub-SELECT graph clauses with ORDER/LIMIT/START/

GROUP BY; $parent in WHERE; custom edge Record IDs in RELATE; +path+inclusive form.

data-modeling.md: illustrative-edge consistency (knows / parent_of /

reviewed used without DEFINE TABLE); kNN metric mismatch in Exact kNN section.

These are documentation-completeness gaps. None contradict upstream v3.0.5; consumers who need any of the listed features can consult the upstream docs without being misled.

v1.6.x progress against this list

v1.6.0 — Deleted the falsified "10 undocumented ALTER targets"

bullet (those targets do not exist in the v3.0.5 parser).

v1.6.1 — Closed the seven function-namespace bullets

(encoding::*, bytes::*, file::*, set::*, sequence::*, schema::*, api::*). Three of those (bytes, sequence, schema) turned out to be SINGLE-function namespaces, not the multi-function namespaces the bullet implied — same fabrication pattern v1.6.0 corrected for ALTER. Process lesson recorded in CHANGELOG.md v1.6.1 process notes: verify against the parser / registry, not against list-of-features paragraphs (whether on the docs site OR in our own backlog notes). v1.6.1 also extends ### Search Functions (analyze / rrf / linear) and ### Session Functions (ac / rd) and adds the previously undocumented top-level sleep(duration) function.

v1.6.2 — Closed all five rules/security.md deferred

bullets in a single batch (WITH REFRESH on TYPE RECORD; WITH JWT URL JWKS endpoint; ACCESS GRANT/SHOW/REVOKE/PURGE statements; DEFINE USER PASSHASH; DEFINE USER DURATION FOR TOKEN/SESSION). Every claim grounded in a v3.0.5 parser source-line range plus a parser test-fixture line, continuing the v1.6.0 / v1.6.1 verification escalator. No fabrication pattern this batch — all five clauses parser-confirmed and test-fixture-confirmed before drafting; the deferral list bullet shape matched reality.

Stability declaration

v1.5.10 declared stable for the SurrealDB v3.0.5 surface. Future work (additive coverage of deferred IMPORTANTs, expansion to v3.1.x+ when released, four-WAY adversarial review) is tracked under v1.6.x.

v1.6.2 Ratification

Tag declared stable: v1.6.2 Cycle dates: 2026-05-06 (single-day cycle, ~7 hours wall-clock) Reviewers: Cursor (Composer 2) / Codex (gpt-5.5 xhigh) / Gemini (3.1 Pro) / Pi+DeepSeek-V4-Pro:xhigh, run as 4 parallel processes per pass

Summary

Seven passes of 4-WAY adversarial review closed 16 cumulative CRITs across the rules/security.md clause-catalog work, ending in 4/4 GO+CONDITIONAL GO with 0 CRITs at pass-7. Per ~/CLAUDE.md aggregation rule "CONDITIONAL GO w/ no CRIT = ship if maintainer accepts IMPs as deferred" — v1.6.2 is declared stable.

Per-pass CRIT counts

Pass	HEAD at audit	Verdicts	CRITs	Notes
1	rev-1 (df98aef)	4 NO-GO*	2	jwks Cargo gate (CONVERGENT Cursor+Codex) + TYPE JWT no-signin path (Cursor unique, pre-existing v1.5.x latent)
2	rev-2 (5467350)	2 COND + 1 GO + 1 NO-GO**	0**	**Pi C1 (iss.alg=Hs512 default for inline asymmetric verifier) REJECTED with parser-cited rebuttal at define.rs:1697; Gemini CRITs (ACCESS ON ROOT, URL on TYPE RECORD WITH JWT) also REJECTED in pass-1
3	rev-3 (733a410)	1 COND + 1 NO-GO + 1 GO + 1 NO-GO	3	kid round-trip + WITH ISSUER KEY in JWKS bullet + $token in SIGNIN (Pi caught $token-in-SIGNIN after 8 reviewer passes had missed it)
4	rev-4 (1e40cf9)	3 NO-GO + 1 COND	3	external_auth no-SIGNIN (CONVERGENT 4-way) + hybrid_record sub vs ID + no-AUTHENTICATE prose
5	rev-5 (691b63c)	2 NO-GO + 1 GO + 1 COND	3	parser-order in 3 examples (AUTHENTICATE before WITH JWT) + access.rs:237-242 label drift + signin.rs:340-345 wrong cite
6	rev-6 (7077c8f)	2 NO-GO + 1 GO + 1 COND	5	NS/DB/AC routing claims missing from IdP examples (pre-existing v1.5.x latent) + account JWKS shape (pre-existing) + Pattern A verify.rs:394 cite + CHANGELOG hybrid bullet stale + duplicate trajectory tables
7	rev-7 (accd06b)	3 COND + 1 GO	0	CONVERGENCE TARGET REACHED — 4/4 with 0 CRITs

Total: 16 CRITs found-and-fixed across seven passes.

\ Pass-1 verdicts: Cursor NO-GO, Codex NO-GO, Gemini NO-GO, Pi CONDITIONAL GO. \* Pass-2 had 4 reviewers; Pi's NO-GO was based on a wrong CRIT.

CRIT-trend post-pass-2

After Gemini's pass-1 CRITs were rejected, the trend showed non-monotone-decreasing-with-clusters:

2 → 0 → 3 → 3 → 3 → 5 → 0

Pass-6's spike to 5 reflects two pre-existing v1.5.x latent bugs finally surfacing (the NS/DB/AC routing-claim requirement that all four reviewers had missed across passes 1-5; the account JWKS example shape that had never been audited at this depth) plus rev-5-introduced parser-arm citation drift. Pass-7's drop to 0 confirms the surgery in rev-7 was precisely scoped and exhausted the discoverable correctness surface.

Notable findings

Single most consequential correction: NS/DB/AC routing claims

Codex pass-6 caught that inbound third-party JWTs MUST carry ns/db/ac routing claims (or aliases per core/src/iam/token.rs:248-275) for SurrealDB to match the database-access arm at core/src/iam/verify.rs:288-297. Without those claims, validation falls through to InvalidAuth at :824-825 BEFORE the access method's verifier or AUTHENTICATE clause runs. The v1.5.x-and-prior IdP example payload showed only sub/email/roles/tenant_id/exp — none of which routes. This bug had been documented in the rule for multiple revisions of this rule cycle without anyone catching it until pass-6.

The fix added a ROUTING-CLAIM REQUIREMENT block to the JWT-Based Authentication preamble + corrected the example payload in the lower IdP integration example. The block explicitly cites all six serde alias spellings per claim field and points at IdP custom-claim mechanisms (Auth0 Actions, Okta inline hooks, Cognito pre-token Lambda, Azure AD claim mapping).

Parse-clean-but-runtime-broken pattern (recurring)

Pi pass-3 caught $token in SIGNIN (only available in AUTHENTICATE per signin.rs:340-345 + verify.rs:255-260); Codex pass-6 caught NS/DB/AC routing-claim requirement; Cursor pass-4 caught hybrid_record $token.sub vs $token.ID mismatch after credential SIGNIN mint. All three are parse-clean examples that fail at runtime because the adversarial reviewers verified parser-grammar acceptance without tracing what each $variable actually resolves to at each evaluation point.

Doctrine update recorded in feedback_walk_examples_end_to_end.md (memory file): every example in a doc must be walked end-to-end at the SurrealQL evaluation level, not just verified to parse. The pattern generalises to any evaluation-context language with similar variable-scope traps.

Citation-line drift across passes

The single label expr/statements/access.rs:237-242 carried four different (mostly wrong) labels across passes 2-3-4-5 before pass-5 + pass-6 finally settled on the correct split (:231-234 for the Base::Db enforcement guard; :237-242 for the bearer-presence check + new_grant_bearer construction). Pi misread the multi-arm match control flow in two separate passes (Pi pass-2 C1 was rejected; Pi pass-5 PASS-on-F was wrong on the same lines).

Doctrine update recorded in feedback_pi_unique_crit_verify_against_source.md: when Pi produces a unique CRIT, source-verify cited line ranges PLUS the immediately-preceding match-arm body before patching.

Doc-vs-CHANGELOG drift (recurring)

Three confirmed instances across the cycle:

pass-2 (Cursor I1): CHANGELOG cited stmt.rs:402 as a

positive fixture; rule file had been updated to acknowledge it was commented out.

pass-3 (Codex I1): CHANGELOG (after rev-2 fix) listed

stmt.rs:627/:1256/:1264/:1272 as alternates; all turned out to be in /* */ blocks too.

pass-6 (Codex C4 + Pi I1+M1+M2 CONVERGENT): two

Cumulative trajectory tables left in [1.6.2] section, one stale ("Eight real CRITs") + one current ("11 real CRITs"). Pi pass-6 noted: "A mechanical check (for each cumulative trajectory table, does it appear exactly once?) would catch this class pre-commit."

The rev-7 R4-R5 commit removed the duplicate table and restructured the doctrine paragraphs under non-conflicting headings.

Verification escalator: parser-source line range + test-fixture line + runtime path

Each pass tightened the verification standard:

Passes 1-2: parser-source line ranges + test-fixture lines
Passes 3-4: added runtime path citations (signin.rs / verify.rs)
Passes 5-6: required exact match-arm body inspection
Pass 7: required example end-to-end walks at evaluation level

Every claim in the final v1.6.2 rules/security.md is grounded in a parser-source line range plus a test-fixture line plus a runtime path where applicable, so any reviewer can trace a clause back to the v3.0.5 commit that defined it.

Per-clause pass-7 status

`WITH REFRESH` on `TYPE RECORD` — GO. Cumulative: 4

CRITs across rev-2 / rev-3 / rev-4 fixes (citation chain + token-shape prefix + access.rs label drift).

`WITH JWT URL` (JWKS endpoint) — CONDITIONAL GO. Pi I1

pass-7 deferrable polish (auth0_jwt NS/DB/AC cross-ref).

`ACCESS GRANT/SHOW/REVOKE/PURGE` — GO. Cumulative: 1

CRIT (PURGE grace) + multiple line-range tightening.

`DEFINE USER PASSHASH` — GO. Cumulative: 1 CRIT

(validation timing) + minor cite tightening.

`DEFINE USER DURATION` — GO. Cumulative: stmt.rs:402

fixture-citation drift across passes 2-4-7.

JWT-Based Authentication / TYPE JWT — GO. Cumulative: 4

CRITs (no-signin path + WITH ISSUER semantics + parser-order + verify.rs cite drift).

JWKS-Backed JWT — GO. Cumulative: 5 CRITs (jwks Cargo

gate + kid round-trip + sub-vs-ID + account shape + bare WITH ISSUER KEY in JWKS bullet).

Deferred to v1.6.3

Pass-7 IMPs and minors that don't affect runtime correctness:

auth0_jwt TYPE JWT example doesn't restate NS/DB/AC

routing claims (preamble covers it; per-example consistency with account / external_idp would be stronger)

jwks_inbound DURATION-omission comment uses generic prose

vs the :282 / :457 dual-pointer used elsewhere

account + jwks_inbound examples in JWKS section now

functionally identical after rev-7's account rewrite — consolidate

verify.rs:155+ cite tightenable to :158-159 (anchor of

decode_claims_unverified call)

Archive Cumulative trajectory after pass-5 table as

historical (superseded by pass-6 table below)

Plus the broader v1.5.x deferred-IMPORTANT backlog (now security.md complete):

surrealql.md: data-type variants (regex, range, literal,

file); array<T,N> cardinality; INSERT IGNORE example; DEFINE API; DEFINE CONFIG; INFO FOR INDEX/USER variants

vector-search.md: HASHED_VECTOR semantics; MINKOWSKI in

similarity-functions; jaccard/pearson similarity-function examples

performance.md: TLS flags in start-flag list;

SURREAL_HNSW_CACHE_SIZE env-var verification; REBUILD INDEX ON TABLE all-indexes form; SCHEMAFULL inference rationale

graph-queries.md: sub-SELECT graph clauses; $parent in

WHERE; custom edge Record IDs in RELATE; +path+inclusive form

data-modeling.md: illustrative-edge consistency; kNN

metric mismatch in Exact kNN section

Reviewer-behaviour observations (refresh of v1.6.0/v1.6.1 notes)

Codex (deepest reviewer): caught 8 of 16 CRITs across the

cycle; consistently surfaced source-cited correctness bugs the other three reviewers missed (jwks Cargo gate + NS/DB/AC routing claims + parser-order in 3 examples). Convergent with Cursor on multi-pass items.

Cursor (packaging + presentation): caught the

hybrid_record claim-shape mismatch, the access.rs label drift across multiple passes, and several CHANGELOG vs rule drifts. Strong on cross-reference consistency.

Pi+DeepSeek-V4-Pro:xhigh: caught the $token in SIGNIN

semantic bug after 8 reviewer passes had missed it; also occasionally produced wrong CRITs from misreading multi-arm match control flow (Pi pass-2 C1 + Pi pass-5 PASS-on-F). When right, very deep; when wrong, parser-cited rebuttal feasible.

Gemini 3.1 Pro: GO-leaning sanity baseline; produced

wrong-direction CRITs in pass-1 + pass-2 from lack of source access; useful as a structural-coherence check. Achieved GO 3 times (passes 2, 3, 5) when other reviewers caught real bugs — i.e., Gemini GO is necessary but not sufficient evidence for ratification.

Memory artefacts

Three feedback memory files written during the cycle:

feedback_codex_review_wrapper_unbound_array.md —

~/bin/codex-review requires --add-dir under set -u

feedback_pi_unique_crit_verify_against_source.md — Pi can

misread multi-arm match control flow; verify cited line ranges PLUS preceding match-arm body

feedback_walk_examples_end_to_end.md — parse-clean

examples can be runtime-broken; trace every $variable to its evaluation point

Stability declaration

v1.6.2 declared stable for the SurrealDB v3.0.5 surface. Future work tracked under v1.6.3 (deferred IMPs from this cycle) and the broader v1.6.x backlog from the v1.5.x convergence catalog.

v1.6.5 Ratification

Tag declared stable: v1.6.5 Merge commit: d18aa51 (PR #9, squash merged 2026-05-06) Cycle dates: 2026-05-06 (single-day cycle) Reviewers: Cursor (Composer 2) / Codex (gpt-5.5 xhigh) / Gemini (3.1 Pro) / Pi+DeepSeek-V4-Pro:xhigh, run as 4 parallel processes per pass

Summary

Nine passes of 4-WAY adversarial review closed ~8 cumulative CRITs across the rules/vector-search.md v1.5.x deferred-IMPORTANT closure, ending in 4/4 GO with 0 CRITs / 0 IMPs / 0 MINORs at pass-9 (HEAD 0b26c27). PR #9 then addressed 3 Gemini code-assist post-merge threads (variable-name consistency a/b vs self/other/x/y) at rev-10 (f384fa2); CI Validate Skill + Cursor Bugbot both passed; PR squash-merged to main as commit d18aa51 and tagged v1.6.5.

Per-pass CRIT counts

Pass	HEAD at audit	Verdicts	CRITs	Notes
1	rev-1 (8cc004b)	1 NO-GO + 2 GO + 1 GO	1	Codex unique: string-array Jaccard fails runtime arg coercion (`vector::similarity::jaccard` dispatches as `(Vec<Number>, Vec<Number>)`)
2	rev-2 (b973bdf)	1 NO-GO + 2 COND + 1 GO	1	Cursor unique: jaccard impl multiset-asymmetric — `[0, 1]` range claim wrong (`jaccard([1], [1, 1]) = 2.0`); 3-way IMP CONVERGENT — pearson "Infinity" mathematically impossible (true for constant-operand sub-case only)
3	rev-3 (e853711)	1 NO-GO + 1 COND + 2 GO	1	Codex unique: pearson constant-vector NaN claim too narrow (missed FLOAT mean-rounding for `[0.1]`-style constants — non-roundtrip floats produce non-zero deviation)
4	rev-4 (b1d1713)	2 COND + 1 GO + 1 GO	0	2 CONVERGENT IMPs: pearson "tiny finite" wording overclaim; JACCARD distance-table both-empty NaN carve-out missing
5	rev-5 (1615176)	1 NO-GO + 1 GO + 1 COND + 1 GO	1	Codex unique: float-constant overgeneralization — `[0.3]`/`[0.5]`/`[0.25]` round-trip exactly through f64 sum-and-divide and DO hit NaN path; only `[0.1]`/`[0.2]`-style non-roundtrip floats avoid it
6	rev-6 (72bd982)	1 NO-GO* + 1 GO + 1 COND + 1 GO	0	Cursor unique CRIT REJECTED via empirical Python f64 trace — Cursor's `[0.3, 0.3, 0.3]` non-roundtrip claim was a hand-arithmetic error on the `/3` step; Codex pass-5 + Gemini pass-6 + Pi pass-6 + direct `python3 struct.pack` trace all confirmed roundtrip-exact. Codex 2 unique IMPs ACCEPT (exact-zero overclaim + HNSW pearson short-circuit divergence at `core/src/idx/trees/vector.rs:413-440`)
7	rev-7 (f6a6268)	1 NO-GO + 1 COND + 1 GO + 1 GO	1	Codex unique: f64 underflow edge — earlier "Infinity impossible" was correct only for constant-operand; underflow case (`[0.0, 1e-308]` × `[0.0, 1e154]`) drives `std_dev = 0` with non-zero covariance, producing `±Infinity`. CONVERGENT IMP: `
8	rev-8 (aee0db9)	1 NO-GO + 1 COND + 1 GO + 1 GO	2	Codex 2 CRITs: earlier prose still implied universal "std_dev=0 → covar=0 → NaN" without underflow exception; HNSW divergence callout said "NaN behaviour" not "non-finite"; PEARSON table cell missed `±Inf`. Cursor pass-8 IMP CONVERGENT on prose-scoping. Pi pass-8 GO with 2 wrong MINORs (different f64 accumulation order than try_add — REJECTED)
9	rev-9 (0b26c27)	4 GO	0	CONVERGENCE TARGET REACHED — 4/4 GO with 0 CRITs / 0 IMPs / 0 MINORs across all 4 reviewers

Total: ~8 CRITs found-and-fixed across nine passes; 1 unique Cursor CRIT rejected via empirical IEEE-754 trace; multiple Pi unique MINORs rejected via direct line-number / accumulation-order re-verification.

\* Pass-6 Cursor verdict was NO-GO based on a wrong CRIT; the underlying claim was empirically refuted by re-running the f64 sum-and-divide pipeline directly.

CRIT trajectory

1 → 1 → 1 → 0 → 1 → 0 → 1 → 2 → 0

The trend was non-monotone with two peaks (pass-5 and pass-8) and trough-at-pass-9. Pass-8's spike to 2 reflects the IEEE-754 under-flow regime that contradicted the long-standing "Infinity impossible" narrative from pass-2; rev-9 reconciled the constant-operand NaN sub-case with the underflow ±Infinity sub-case using explicit cross-references and a concrete worked example.

The reviewer-unique-CRIT verification doctrine (feedback_pi_unique_crit_verify_against_source.md) applied symmetrically to all reviewers in this cycle:

Cursor pass-6 — REJECTED ([0.3, 0.3, 0.3] non-roundtrip

claim wrong; Cursor's / 3 hand-arithmetic produced 0.29999999999999993; actual f64 result is exact 0.3 per python3 -c "import struct; struct.pack('!d', (0.3+0.3+0.3)/3).hex()" == "3fd3333333333333").

Pi pass-2 / pass-3 / pass-5 / pass-7 / pass-8 — multiple

rejected MINORs from misreading multi-arm match-arm line ranges (Self::Jaccard at line 297, not 302; Self::Pearson at line 300, not 305) plus accumulation-order errors in f64 manual traces (Pi got 0.19999999999999998 for mean([0.1, 0.2, 0.3]) when SurrealDB's left-to-right try_add produces 0.20000000000000004).

Notable findings

Single most consequential correction: literal-dependent float-constant Pearson

Codex pass-5 caught that float-constant Pearson is not a single regime. The v3.0.5 mean() implementation (core/src/fnc/util/math/mod.rs:54-67) accumulates via try_add left-to-right and divides by len. For some float constants the sum-and-divide pipeline produces a result that bit-equals the original element ([0.3, 0.3, 0.3], [0.5, 0.5, 0.5], [0.25, 0.25, 0.25]); for others it lands one ulp off ([0.1, 0.1, 0.1], [0.2, 0.2, 0.2]). The constant-operand NaN path (where every centered term is exactly zero) is reachable only for the round-trip-exact constants. Without this distinction the rule would mislead readers into expecting NaN for any float constant.

The fix went through revisions 5, 6, 7 to converge — first generalizing too narrowly, then too broadly, then catching the round-trip-exact distinction.

f64 underflow as a separate ±Infinity regime

Codex pass-7 caught that the long-standing "Infinity impossible" claim from pass-2 was correct only for the constant-operand case. The underflow case (std_dev drives to 0.0 via squared-term underflow while pairwise products do not underflow) produces ±Infinity, NOT NaN. Concrete example:

pearson([0.0, 1e-308], [0.0, 1e154])
  → centers: dx ∈ {-5e-309, +5e-309}, dy ∈ {-5e153, +5e153}
  → squared centered (5e-309)² ≈ 2.5e-617 underflows to 0
  → std_dev_a = 0
  → pairwise products (±5e-309)(±5e153) = 2.5e-155 (above min normal)
  → covar = 2.5e-155
  → result = 2.5e-155 / 0 = +Infinity

This required carefully scoping the earlier "Infinity impossible" prose to the constant-operand sub-case and adding a separate underflow callout with the worked example.

Reviewer hand-arithmetic errors on IEEE-754 traces (recurring)

Three confirmed instances across the cycle:

Cursor pass-6 — claimed [0.3, 0.3, 0.3] mean is

0.29999999999999993 (off by one ulp from exact 0.3).

Pi pass-8 — claimed mean([0.1, 0.2, 0.3]) = 0.19999999999999998

(off-by-one-ulp from the actual try_add-order result 0.20000000000000004).

Pi pass-7 — claimed Self::Jaccard at :302 and Self::Pearson

at :305 (actual :297 and :300).

Each rejected via direct re-verification: python3 -c for f64 arithmetic (matching SurrealDB's left-to-right try_add order) and direct grep -n for Rust line numbers. Verification artifacts archived under /tmp/v1.6.5-pass{N}/.

Doctrine update implicit (already covered by feedback_walk_examples_end_to_end.md + feedback_pi_unique_crit_verify_against_source.md): when reviewers diverge on numeric or line-number claims, source-verify before patching. The pattern generalises beyond Pi to any reviewer.

Verification escalator: parser-source line range + IEEE-754 trace

Each pass tightened the verification standard for pearson edge cases:

Passes 1-3: parser-source line ranges + test-fixture lines
Passes 4-5: required IEEE-754 mean-rounding trace
Passes 6-7: required end-to-end f64 sum-and-divide trace
Passes 8-9: required scoping IEEE-754 regimes (constant-operand

vs underflow vs Decimal) explicitly with concrete worked examples

Every claim in the final v1.6.5 rules/vector-search.md is grounded in a parser-source line range plus a test-fixture line plus an IEEE-754 trace where applicable, so any reviewer can trace a clause back to the v3.0.5 commit that defined it AND verify the arithmetic directly.

Per-clause pass-9 status

`HASHED_VECTOR` storage semantics — GO. Cumulative: 0 CRITs.

Stable since rev-1; survived 9 passes without revision.

MINKOWSKI similarity-fn example — GO. Cumulative: 0 CRITs.

Stable since rev-1; survived 9 passes without revision.

`vector::similarity::jaccard()` callout — GO. Cumulative: 2

CRITs (rev-1 string-array coercion + rev-2 multiset asymmetry) + 1 IMP (table both-empty NaN carve-out).

`vector::similarity::pearson()` callout — GO. Cumulative: 4

CRITs (rev-3 float mean-rounding + rev-5 literal-dependent + rev-7 underflow + rev-8 scoping) + multiple IMPs (Infinity impossible scoping + tiny-finite wording + |x| scale).

HNSW pearson short-circuit divergence sub-callout — GO.

Cumulative: 1 IMP (added in rev-7) + 1 CRIT (rev-8 wording NaN→non-finite).

PEARSON / JACCARD distance-table cells — GO. Cumulative: 1

IMP each (NaN/±Inf carve-outs + multiset asymmetry bound).

Deferred to v1.6.6

Pass-9 produced 0 deferrable items. Earlier-rev cosmetic MINORs that survived disposition:

define.rs:1154 → :1153 cite tightening (Cursor pass-1

MINOR; Cursor pass-5 reaffirmed the range cite is "more informative than a single-line cite")

I64 missing from Supported Data Types comment block at

rules/vector-search.md:66-70 (Pi pass-1 MINOR; pre-existing v1.5.x latent)

Minkowski example missing source-line cite (Pi pass-1 MINOR)
Jaccard fixture span starts on a blank line at line 3470 vs

3471 (Cursor pass-3 MINOR; line-drift nit)

Plus the broader v1.5.x deferred-IMPORTANT backlog (now vector-search.md complete):

surrealql.md: data-type variants (regex, range, literal,

file); array<T,N> cardinality; INSERT IGNORE example; DEFINE API; DEFINE CONFIG; INFO FOR INDEX/USER variants

performance.md: TLS flags in start-flag list;

SURREAL_HNSW_CACHE_SIZE env-var verification; REBUILD INDEX ON TABLE all-indexes form; SCHEMAFULL inference rationale

graph-queries.md: sub-SELECT graph clauses; $parent in

WHERE; custom edge Record IDs in RELATE; +path+inclusive form

Reviewer-behaviour observations (refresh of v1.6.0/v1.6.1/v1.6.2 notes)

Codex (deepest reviewer): caught 5 of 8 CRITs across the

cycle; consistently surfaced IEEE-754 edge cases the other three reviewers missed (string-array coercion, float mean-rounding, literal-dependent floats, underflow ±Infinity, scoping CRITs). Pass-9 first-time clean. Convergent with Cursor on multi-pass items.

Cursor (packaging + presentation, pass-9 unique): caught

the multiset-asymmetry CRIT at pass-2 (Cursor unique deepest catch in this cycle); produced one wrong unique CRIT at pass-6 ([0.3, 0.3, 0.3] non-roundtrip hand-arithmetic error); strong on prose-scoping IMPs at pass-4 / pass-7 / pass-8 / pass-7. Strong on cross-reference consistency.

Pi+DeepSeek-V4-Pro:xhigh: caught no unique CRITs in this

cycle; produced multiple wrong MINORs from misreading multi-arm match-arm line ranges and from f64 accumulation-order errors (left-to-right try_add vs alternate order). When right, very deep; when wrong, source-cited rebuttal feasible. Doctrine applies symmetrically to Pi.

Gemini 3.1 Pro: GO-leaning sanity baseline; produced no

CRITs but corroborated several CONVERGENT IMPs at pass-2 / pass-4 / pass-7 / pass-8. Useful as a structural-coherence + IEEE-754 trace check.

PR #9 post-merge polish

Three Gemini code-assist threads on PR #9 surfaced variable-name consistency issues between the prose (self/other/x/y) and the SurrealQL function signatures (a/b). All three accepted in rev-10 (f384fa2); replied to + resolved before merge. CI Validate Skill + Cursor Bugbot both green at merge time.

Memory artefacts

No new doctrine files written this cycle; existing feedback_walk_examples_end_to_end.md and feedback_pi_unique_crit_verify_against_source.md applied symmetrically (Cursor pass-6 hand-arithmetic error; Pi pass-2/3/5/7/8 multi-pass match-arm misreads + f64 accumulation-order error). The reviewer-misread pattern is now confirmed across both Pi and Cursor — generalises beyond any single reviewer.

Stability declaration

v1.6.5 declared stable for the SurrealDB v3.0.5 surface. Future work tracked under v1.6.6 (deferred MINORs from this cycle + broader v1.5.x convergence backlog: surrealql.md, performance.md, graph-queries.md).

surreal-skills

![CI](https://github.com/24601/surreal-skills/actions/workflows/ci.yml) ![License: MIT](LICENSE) ![Version](https://github.com/24601/surreal-skills/releases) ![skills.sh](https://skills.sh)

Expert SurrealDB 3 skill for AI coding agents. Tracks SurrealDB v3.1.4+. Complete coverage of SurrealQL, multi-model data modeling, graph traversal, vector search (HNSW + DiskANN), security, deployment, performance tuning, SDK integration, WASM extensions, built-in MCP (v3.1+), standalone SurrealMCP, SurrealKit, Surrealist, n8n, CodeMirror, and agent-skill workflows.

Features

SurrealQL mastery -- Complete language reference with statements, functions, operators, and idioms
Multi-model data modeling -- Document, graph, vector, relational, time-series, and geospatial patterns in a single schema
Graph queries -- First-class edge creation and traversal without JOINs
Vector search -- HNSW and DiskANN indexes, similarity functions, and RAG pipeline patterns
Built-in MCP (v3.1+) -- surreal mcp stdio and HTTP /mcp for AI agent hosts; standalone surrealmcp for extended tools
Security -- Row-level permissions, JWT auth, namespace/database/record-level access control
Deployment -- Storage engine selection, Docker, Kubernetes, production hardening
Performance -- Index strategies, EXPLAIN analysis, batch operations, connection pooling
12+ SDK integrations -- JavaScript/TypeScript, Python, Go, Rust, Java, Kotlin, .NET, C, PHP, Swift (iOS/macOS/visionOS), Ruby
Surrealism WASM extensions -- Custom functions and analyzers compiled from Rust (new in v3)
SurrealML scope coverage -- .surml artifact format (preview/unstable), PyPI-vs-GitHub release boundary, and native-library download warning
SurrealMCP for AI agents -- Built-in MCP in SurrealDB 3.1+ plus standalone surrealdb/surrealmcp v0.4.0
Editor tooling pointers -- first-party surrealql-language-server v0.1.6, tree-sitter grammar, CodeMirror v1.0.6, and discoverability pointers for VS Code / Cursor / Windsurf / VSCodium, JetBrains, Neovim, Helix, Sublime Text, Zed extensions
LangChain integration (Python only) -- langchain-surrealdb 0.2.1 (Python) -- vector store usage; @langchain/surrealdb JS package was retracted in v1.4.1 (does not exist on npm)
`surrealdb/setup-surreal@v2` GitHub Action -- Official Action for running SurrealDB inside CI workflows (the v1.4.0 documentation that described setup-surreal as a CLI bootstrap was retracted in v1.4.2)
Full ecosystem -- Surrealist IDE, Surreal-Sync CDC, SurrealFS agent filesystem, SurrealKit schema tooling, n8n community node, official Agent Skills repo, and Spectron roadmap boundary
Health checks and introspection -- Doctor script and schema introspection for any SurrealDB instance
Universal agent support -- Works with 30+ AI coding agents via skills.sh

Installation

Claude Code (recommended)

Option 1 -- Install as a Claude Code skill (global)

npx skills add 24601/surreal-skills -a claude-code -g -y

This installs the skill globally so it is available in every Claude Code session. The -g flag installs globally, -y auto-confirms prompts.

Option 2 -- Install per-project via CLAUDE.md

Clone the repo and reference it from your project's CLAUDE.md:

git clone https://github.com/24601/surreal-skills.git ~/.claude/skills/surrealdb

Then add to your project's CLAUDE.md (or ~/.claude/CLAUDE.md for global):

# SurrealDB Skill

@import ~/.claude/skills/surrealdb/AGENTS.md

Or inline the reference:

# SurrealDB Skill

For SurrealDB work, read the rules at ~/.claude/skills/surrealdb/rules/ and
use the scripts at ~/.claude/skills/surrealdb/scripts/ for health checks
and schema introspection.

Option 3 -- Add as a Claude Code custom slash command

Create ~/.claude/commands/surrealdb.md:

Load the SurrealDB 3 skill from ~/.claude/skills/surrealdb/AGENTS.md
and use its rules for all SurrealDB architecture, development, and operations tasks.
Available rules: surrealql, data-modeling, graph-queries, vector-search, security,
deployment, performance, sdks, surrealism, surrealist, surreal-sync, surrealfs,
surrealkit, surrealmcp, surrealml, editor-tooling, langchain, ecosystem-integrations, gotchas.

Then invoke with /surrealdb in any Claude Code session.

Option 4 -- Project-scoped slash commands

Add SurrealDB-specific commands to your project:

mkdir -p .claude/commands

Create .claude/commands/surreal-doctor.md:

Run the SurrealDB health check: uv run ~/.claude/skills/surrealdb/scripts/doctor.py
Report any issues found and suggest fixes based on the deployment rules.

Create .claude/commands/surreal-schema.md:

Introspect the current SurrealDB schema: uv run ~/.claude/skills/surrealdb/scripts/schema.py introspect
Analyze the output using the data-modeling rules and suggest improvements.

Other AI Agents

# skills.sh (universal -- works with all supported agents)
npx skills add 24601/surreal-skills

# Amp
npx skills add 24601/surreal-skills -a amp -g -y

# Codex
npx skills add 24601/surreal-skills -a codex -g -y

# Gemini CLI
npx skills add 24601/surreal-skills -a gemini-cli -g -y

# OpenCode
npx skills add 24601/surreal-skills -a opencode -g -y

# Pi (badlogic/pi-mono)
npx skills add 24601/surreal-skills -a pi -g -y

# OpenClaw / Clawdbot
npx skills add 24601/surreal-skills -a openclaw -g -y

GitHub Copilot (native agent skills)

Copilot supports the Agent Skills standard natively in VS Code, Copilot CLI, and the Copilot coding agent. This skill ships a Copilot-native .github/skills/surrealdb/SKILL.md that Copilot auto-loads when your prompt is SurrealDB-related.

Option 1 -- Project-level (recommended for teams)

Copy the entire skill into your project's .github/skills/ directory:

# From the surreal-skills repo
cp -r .github/skills/surrealdb <your-project>/.github/skills/surrealdb
cp -r rules/ <your-project>/.github/skills/surrealdb/rules/

Copilot discovers this automatically -- no config needed. Type /surrealdb in chat or let Copilot auto-load it when it detects SurrealQL context.

Option 2 -- Personal (all projects)

Clone into ~/.copilot/skills/:

git clone https://github.com/24601/surreal-skills.git ~/.copilot/skills/surrealdb

Or add a custom search location in VS Code settings:

{
  "chat.agentSkillsLocations": [
    "~/.copilot/skills"
  ]
}

Option 3 -- Use `/skills` menu

Type /skills in Copilot chat to open the Configure Skills menu, then browse to the cloned surrealdb directory.

Other IDE Integrations

# Cursor -- add skill to .cursor/skills/ (same Agent Skills standard)
cp -r .github/skills/surrealdb <your-project>/.cursor/skills/surrealdb

# Windsurf -- append AGENTS.md to .windsurfrules
cat AGENTS.md >> .windsurfrules

# Cline / Continue -- reference in your config
# Add the AGENTS.md path to your system prompt configuration

Manual installation

# Clone to any location
git clone https://github.com/24601/surreal-skills.git ~/.claude/skills/surrealdb

# Verify installation
uv run ~/.claude/skills/surrealdb/scripts/doctor.py --check

Quick Start

Credential warning: Examples below use root/root for **local development

only**. Never use default credentials against production or shared instances.

# Start SurrealDB in-memory for LOCAL DEVELOPMENT ONLY
surreal start memory --user root --pass root --bind 127.0.0.1:8000

# Connect via CLI REPL (local dev)
surreal sql --endpoint http://localhost:8000 --user root --pass root --ns test --db test

# Create records with SurrealQL
CREATE person:alice SET name = 'Alice', email = 'alice@example.com';
CREATE person:bob SET name = 'Bob', email = 'bob@example.com';

# Create graph edges
RELATE person:alice->follows->person:bob SET since = time::now();

# Traverse the graph
SELECT ->follows->person.name AS following FROM person:alice;

# Run the health check
uv run scripts/doctor.py

Architecture

surreal-skills/
  SKILL.md              # Skill manifest (frontmatter + body)
  AGENTS.md             # Structured agent briefing
  README.md             # This file
  LICENSE               # MIT license
  scripts/
    onboard.py          # Setup wizard / capabilities manifest
    doctor.py           # Health check (CLI, server, auth, storage)
    schema.py           # Schema introspection and export
  rules/
    surrealql.md        # SurrealQL language reference
    data-modeling.md    # Multi-model schema design patterns
    graph-queries.md    # Graph traversal and RELATE patterns
    vector-search.md    # Vector indexes, similarity search, RAG
    security.md         # Permissions, auth, access control
    deployment.md       # Storage engines, Docker, K8s, production, setup-surreal GitHub Action
    performance.md      # Indexes, EXPLAIN, optimization
    sdks.md             # Official SDK integration (12+ languages)
    surrealism.md       # WASM extension system (new in v3)
    surrealml.md        # SurrealML preview scope and package boundaries
    surrealmcp.md       # Model Context Protocol server
    editor-tooling.md   # LSP, tree-sitter, IDE extensions
    langchain.md        # LangChain Python integration
    ecosystem-integrations.md # n8n, CodeMirror, Agent Skills, Spectron boundary
    surrealist.md       # Surrealist IDE/GUI
    surreal-sync.md     # CDC migration tool
    surrealfs.md        # AI agent filesystem
    surrealkit.md       # Desired-state schema sync and rollouts
  skills/
    surrealism/
    surreal-sync/
    surrealfs/
    surrealkit/
    surrealmcp/

Rules

Rule	Description
`surrealql.md`	Complete SurrealQL language reference: CREATE, SELECT, UPDATE, DELETE, RELATE, INSERT, UPSERT, LIVE SELECT, DEFINE, REMOVE, INFO, subqueries, transactions, futures, all built-in functions, v2-to-v3 migration notes
`data-modeling.md`	Schema design patterns: record IDs (typed, generated, composite), field types, schemafull vs schemaless, normalization strategies, multi-model design (document + graph + vector in one schema), time-series and geospatial data
`graph-queries.md`	Graph edge creation with RELATE, traversal operators (-> outgoing, <- incoming, <-> bidirectional), path expressions, recursive queries, filtering and aggregation on edges, graph-specific DEFINE TABLE TYPE RELATION
`vector-search.md`	Vector field definitions, HNSW and brute-force index creation, distance metrics (cosine, euclidean, manhattan, minkowski), vector::similarity functions, RAG pipeline patterns, hybrid search combining vector + metadata filtering
`security.md`	Row-level permissions with WHERE predicates, DEFINE ACCESS for JWT and record-based auth, DEFINE USER for system users, namespace/database/table permission scoping, $auth and $session runtime variables, authentication flow patterns
`deployment.md`	Installation methods (package manager, Docker, binary), storage engine selection (memory, RocksDB, SurrealKV with time-travel, TiKV for distributed), Docker Compose and Kubernetes Helm charts, production hardening, backup/restore, log levels, monitoring, `surrealdb/setup-surreal@v2` GitHub Action for CI
`performance.md`	Index strategies (unique, full-text search analyzers, HNSW vector), EXPLAIN statement for query analysis, batch operations, connection pooling, storage engine trade-offs by workload, parallel queries, resource limits, compute-to-storage ratios
`sdks.md`	Official SDK usage for JavaScript/TypeScript (Node, Deno, Bun, browser), Python, Go, Rust, Java, Kotlin, .NET, C, PHP, Swift (iOS / macOS / visionOS), Ruby: connection setup (HTTP vs WebSocket), authentication flows, CRUD operations, live query subscriptions, typed record handling, error patterns
`surrealism.md`	Surrealism WASM extension system introduced in SurrealDB 3: Rust SDK for authoring, custom function registration, custom analyzer creation, module compilation to wasm32-unknown-unknown, deployment to running instances, versioning, testing
`surrealml.md`	SurrealML scope summary (preview/unstable; GitHub v0.1.2 vs PyPI 0.0.4 boundary; setup-time native-library download warning). `.surml` artifact format, supported pip extras, stable patterns that don't depend on the unstable ML surface
`surrealmcp.md`	SurrealMCP Model Context Protocol server: verified install (Cargo from source / Docker; not on crates.io or npm), `surrealmcp start` CLI shape, env-var conventions, tool catalog grouped per upstream README, host-config pointers for Claude Desktop / Cursor / Copilot / Zed / n8n
`editor-tooling.md`	First-party `surrealql-language-server` v0.1.3, `surql-lsp` community boundary, `surrealql-tree-sitter`, CodeMirror packages, and editor-extension discoverability pointers
`langchain.md`	LangChain integration: `langchain-surrealdb` 0.2.1 (Python) -- verified deps (`langchain-core ~= 1.1.0`, `surrealdb ~= 1.0.8`), constructor-based vector store API, `custom_filter` kwarg. JS section was retracted in v1.4.1 (`@langchain/surrealdb` not on npm)
`ecosystem-integrations.md`	n8n community node (`@surrealdb/n8n-nodes-surrealdb`), official AI framework docs index, Spectron roadmap boundary, CodeMirror, and upstream Agent Skills repo
`surrealist.md`	Surrealist IDE and GUI: schema designer with visual table editing, query editor with syntax highlighting and auto-complete, graph visualizer for relationships, table explorer, connection profiles, import/export, embedding in applications
`surreal-sync.md`	Surreal-Sync CDC migration tool: source connectors (PostgreSQL, MySQL, MongoDB, etc.), SurrealDB as target, incremental change data capture, schema translation rules, migration workflow orchestration, conflict resolution, monitoring
`surrealfs.md`	SurrealFS AI agent filesystem: file storage backed by SurrealDB, metadata management with SurrealQL queries, directory structures, file versioning, agent-friendly API patterns, integration with AI agent frameworks
`surrealkit.md`	SurrealKit schema management for SurrealDB apps: desired-state sync for dev, rollout-based migrations for shared/prod, seeds, and declarative schema/permission/API tests
`gotchas.md`	Cross-domain gotchas and footguns verified against v3.1.4+: migration, permissions, graph, vector, SurrealQL, MCP, SDKs

Scripts

Script	Usage	Description
`onboard.py`	`uv run scripts/onboard.py --check`	Verify prerequisites (surreal CLI, Python, uv, server connectivity)
`onboard.py`	`uv run scripts/onboard.py --agent`	Output JSON capabilities manifest for agent integration
`doctor.py`	`uv run scripts/doctor.py`	Full health check: CLI version, server reachability, auth, namespace, database, storage engine
`doctor.py`	`uv run scripts/doctor.py --check`	Quick pass/fail (exit code 0 = healthy, 1 = issues)
`doctor.py`	`uv run scripts/doctor.py --endpoint URL`	Check a specific SurrealDB endpoint
`schema.py`	`uv run scripts/schema.py introspect`	Full schema dump of all tables, fields, indexes, events, accesses
`schema.py`	`uv run scripts/schema.py tables`	List all tables with field/index counts
`schema.py`	`uv run scripts/schema.py table <name>`	Inspect a single table in detail
`schema.py`	`uv run scripts/schema.py export --format surql`	Export schema as reproducible DEFINE statements
`schema.py`	`uv run scripts/schema.py export --format json`	Export schema as structured JSON
`check_upstream.py`	`uv run scripts/check_upstream.py`	Compare upstream repos against skill snapshot; shows what changed
`check_upstream.py`	`uv run scripts/check_upstream.py --stale`	Only show repos with new commits since snapshot
`check_upstream.py`	`uv run scripts/check_upstream.py --json`	JSON-only output (no Rich table)

All scripts follow the dual-output convention: stderr for Rich-formatted human output, stdout for machine-readable JSON.

Sub-Skills

Surrealism (WASM Extensions)

New in SurrealDB 3. Extend the database with custom functions and analyzers written in Rust, compiled to WebAssembly, and deployed to running instances. The rules/surrealism.md rule covers the full Surrealism SDK, module authoring, compilation, deployment, and testing workflow.

Surreal-Sync (CDC Migration)

Change Data Capture tool for migrating data from external databases (PostgreSQL, MySQL, MongoDB, and others) into SurrealDB. Supports incremental sync, schema translation, and conflict resolution. See rules/surreal-sync.md.

SurrealFS (AI Agent Filesystem)

A filesystem abstraction built on SurrealDB, designed for AI agent workflows. Store files with rich metadata queryable via SurrealQL, version files automatically, and integrate with agent frameworks. See rules/surrealfs.md.

SurrealKit (Schema Sync and Rollouts)

SurrealDB schema management for application teams. Use desired-state sync for disposable environments, rollout manifests for shared and production databases, seed for fixture data, and test for declarative schema, permission, and API checks. See rules/surrealkit.md.

SurrealMCP (Model Context Protocol Server)

Built-in (SurrealDB 3.1+): surreal mcp stdio or HTTP POST /mcp — no separate install. Standalone: official surrealdb/surrealmcp v0.4.0 for extended tools and cloud helpers. Install standalone from source (cargo install --path .) or Docker; not on crates.io or npm. See rules/surrealmcp.md and skills/surrealmcp/SKILL.md.

SurrealML (In-Database ML Inference) -- preview / unstable

surrealml has a GitHub v0.1.2 release, but PyPI still exposes surrealml 0.0.4 as latest as of 2026-06-17. The stable local guidance remains the .surml artifact format and [sklearn], [torch], [tensorflow] extras. Current upstream Python setup can download native libraries from GitHub Releases into ~/surrealml_deps unless LOCAL_BUILD=TRUE; pin and audit before production use. See rules/surrealml.md.

Editor Tooling

First-party surrealql-language-server v0.1.6, community surql-lsp v0.1.1 boundary, tree-sitter grammar, @surrealdb/codemirror / @surrealdb/lezer v1.0.6, and pointer entries for VS Code / Cursor / Windsurf / VSCodium, JetBrains IDEs, Neovim, Helix, Sublime Text, Zed, and Emacs extensions. See rules/editor-tooling.md.

LangChain Integration (Python only)

langchain-surrealdb 0.2.1 (Python; langchain-core ~= 1.1.0, surrealdb ~= 1.0.8 v1 SDK) for LangChain 1.1+ pipelines: SurrealDB as a vector store via constructor SurrealDBVectorStore(embeddings, conn). The @langchain/surrealdb npm package, AsyncSurrealDBVectorStore, SurrealChatMessageHistory, SurrealHybridRetriever, and from_endpoint/from_client factories from v1.4.0 were retracted in v1.4.1. See rules/langchain.md.

Ecosystem Integrations

rules/ecosystem-integrations.md tracks new and pointer-level ecosystem surfaces: the official scoped n8n community node (@surrealdb/n8n-nodes-surrealdb v0.6.0), the official AI framework docs index, Spectron / Agent Memory Context as roadmap-only, CodeMirror packages, and surrealdb/agent-skills. Treat AI framework pages other than LangChain as pointers until their package/API shape is re-verified.

Use Cases

API Backend

Use SurrealDB as the primary datastore for REST or GraphQL APIs. Define tables with schemafull validation, set up row-level permissions for multi-tenant security, connect via the JavaScript or Python SDK over WebSocket for real-time live queries.

Real-Time Application

Leverage LIVE SELECT for push-based data subscriptions. Clients receive changes as they happen without polling. Combine with WebSocket SDK connections for chat applications, collaborative editors, dashboards, and notification systems.

Graph Analytics

Model complex relationships (social networks, organizational hierarchies, dependency trees, knowledge graphs) using RELATE and typed edge tables. Traverse paths of arbitrary depth with -> operators. Filter and aggregate at each hop without writing JOINs.

Vector Search and RAG

Store document embeddings alongside content. Create HNSW vector indexes with configurable distance metrics. Query with vector::similarity::cosine for semantic search. Build retrieval-augmented generation pipelines that combine vector similarity with metadata filtering in a single SurrealQL query.

IoT and Time-Series

Ingest high-volume sensor data with schemaless tables. Use datetime fields and range queries for time-series analysis. Aggregate with built-in math and time functions. SurrealKV storage engine enables time-travel queries to access historical state at any point in time.

Geospatial Applications

Store geometry types (points, polygons, multipoints) as native SurrealDB values. Use built-in geo functions (geo::distance, geo::bearing, geo::area, geo::contains) for spatial queries. Combine with other data models -- a single query can traverse a graph, filter by location, and rank by vector similarity.

Data Migration

Migrate from PostgreSQL, MySQL, MongoDB, or other databases using Surreal-Sync CDC. Translate schemas automatically, sync incrementally, and validate with schema introspection. For SurrealDB v2-to-v3 upgrades, use surreal export/import with the migration notes in rules/surrealql.md.

WASM Extensions

Extend SurrealDB with custom business logic using Surrealism. Write functions and analyzers in Rust, compile to WASM, and deploy without restarting the server. Use cases include custom validation, domain-specific scoring, proprietary tokenizers, and specialized aggregation functions.

AI Agent Filesystem

Use SurrealFS as a persistent, queryable filesystem for AI agent workflows. Agents can store and retrieve files with rich metadata, query across files with SurrealQL, and leverage SurrealDB's permissions system for multi-agent access control.

Full-Text Search

Define custom analyzers (tokenizers, filters, stemmers) and create search indexes on text fields. Query with full-text search predicates that integrate with the rest of SurrealQL -- combine text search with graph traversal, vector similarity, and relational filters in a single statement.

Configuration

Set these environment variables to configure the skill scripts. All are optional with sensible defaults.

Variable	Description	Default
`SURREAL_ENDPOINT`	SurrealDB server URL	`http://localhost:8000`
`SURREAL_USER`	Root or namespace username	`root`
`SURREAL_PASS`	Root or namespace password	`root`
`SURREAL_NS`	Default namespace	`test`
`SURREAL_DB`	Default database	`test`

These variables are also recognized by the surreal CLI and official SurrealDB SDKs.

Source Provenance

This skill was refreshed on 2026-05-03 from these upstream sources. Use check_upstream.py to detect what changed since this snapshot for incremental updates.

Repository	Release	SHA	Snapshot Date	Rules Affected
surrealdb/surrealdb	v3.0.5 (main toward v3.1.0-alpha)	`a97d3af85d79`	2026-04-29	surrealql, data-modeling, security, performance, deployment, surrealism
surrealdb/surrealist	surrealist-v3.8.5	`3699b2d09b62`	2026-05-01	surrealist
surrealdb/surrealdb.js	v2.0.3	`f0fa3cd7d8fb`	2026-03-25	sdks
surrealdb/surrealdb.py	v2.0.0 (GA)	`6e45a820d27c`	2026-05-02	sdks
surrealdb/surrealdb.go	v1.4.0 (main)	`aef39d3a439f`	2026-04-30	sdks
surrealdb/surreal-sync	v0.3.4	`59b3166910f0`	2026-03-11	surreal-sync
surrealdb/surrealfs	--	`0008a3a94dbe`	2026-01-29	surrealfs
surrealdb/surrealkit	v0.6.0 (pre-release)	`28f5a1c9d20c`	2026-05-03	surrealkit

Documentation: surrealdb.com/docs snapshot 2026-05-03.

Machine-readable provenance: `SOURCES.json`.

Registries

This skill is published to multiple agent skill registries:

Registry	Install Command
skills.sh	`npx skills add 24601/surreal-skills`
ClawHub	`npx clawhub install surrealdb`
OpenClaw / Clawdbot	`clawhub install surrealdb`
GitHub	`git clone https://github.com/24601/surreal-skills.git`

Contributing

See CONTRIBUTING.md for development setup, code style, and PR process.

Security

To report a vulnerability, use GitHub Security Advisories. See SECURITY.md for details.

This skill declares the following security properties in SKILL.md frontmatter:

Property	Value	Meaning
`no_network`	false	`doctor.py`/`schema.py` connect to user-specified SurrealDB endpoint (WebSocket). `check_upstream.py` calls GitHub API via `gh` CLI. No other third-party calls.
`no_credentials`	false	Scripts accept `SURREAL_USER`/`SURREAL_PASS` for DB auth. No credentials are stored in the skill itself.
`no_env_write`	true	Scripts do not modify environment variables
`no_file_write`	false	`schema.py` can write `schema.surql` when `--output-dir` is used, and `onboard.py --interactive` can write a local `.env` file only after explicit user confirmation.
`no_shell_exec`	false	Scripts invoke `surreal` CLI and `gh` CLI
`scripts_auditable`	true	All scripts are readable Python with no obfuscation
`scripts_use_pep723`	true	Dependencies declared inline via PEP 723, no requirements.txt
`no_obfuscated_code`	true	No obfuscated, encoded, or encrypted code
`no_binary_blobs`	true	No compiled binaries or WASM files
`no_minified_scripts`	true	No minified JavaScript or compressed code
`no_curl_pipe_sh`	true	The skill documents package-manager and container installs only. No pipe-to-shell installer commands are included.

Required Environment Variables

Declared in SKILL.md requires.env_vars:

Variable	Sensitive	Default	Purpose
`SURREAL_ENDPOINT`	No	`http://localhost:8000`	SurrealDB server URL
`SURREAL_USER`	Yes	`root`	Authentication username
`SURREAL_PASS`	Yes	`root`	Authentication password
`SURREAL_NS`	No	`test`	Default namespace
`SURREAL_DB`	No	`test`	Default database

Required Binaries

Declared in SKILL.md requires.binaries:

Binary	Required	Install
`surreal`	Yes	`brew install surrealdb/tap/surreal`
`python3` (>=3.10)	Yes	System package manager
`uv`	Yes	`brew install uv` or `pip install uv`
`docker`	No	Optional for containerized instances
`gh`	No	Optional -- only used by `check_upstream.py` to compare upstream repo SHAs via GitHub API

Script Safety

All user-provided table names are validated against [a-zA-Z_][a-zA-Z0-9_]* before interpolation into SurrealQL queries (prevents SurrealQL injection)
doctor.py and schema.py connect only to the SurrealDB endpoint specified by the user (via env var or CLI flag)
check_upstream.py calls GitHub API via gh CLI to compare upstream repo SHAs (optional maintenance script, not needed for normal usage)
No data is sent to third-party services
Credential warning labels are present on all root/root examples

License

MIT

Credits

Built for the SurrealDB community. SurrealDB is created and maintained by SurrealDB Ltd.

Published on skills.sh, ClawHub, and GitHub.

SurrealDB Online Documentation and Resources

A comprehensive directory of official SurrealDB documentation, repositories, and community resources.

Official Documentation

Resource	URL
Main Documentation	https://surrealdb.com/docs
SurrealQL Reference	https://surrealdb.com/docs/surrealdb/surrealql
Data Model	https://surrealdb.com/docs/surrealdb/datamodel
Extensions	https://surrealdb.com/docs/surrealdb/extensions
Security	https://surrealdb.com/docs/surrealdb/security
Deployment	https://surrealdb.com/docs/surrealdb/deployment
CLI Reference	https://surrealdb.com/docs/surrealdb/cli

SDKs

SDK	Documentation	Repository
JavaScript/TypeScript	https://surrealdb.com/docs/sdk/javascript	https://github.com/surrealdb/surrealdb.js
Python	https://surrealdb.com/docs/sdk/python	https://github.com/surrealdb/surrealdb.py
Rust	https://surrealdb.com/docs/sdk/rust	https://github.com/surrealdb/surrealdb (core)
Go	https://surrealdb.com/docs/sdk/go	https://github.com/surrealdb/surrealdb.go
Java	https://surrealdb.com/docs/sdk/java	https://github.com/surrealdb/surrealdb.java
.NET (C#)	https://surrealdb.com/docs/sdk/dotnet	https://github.com/surrealdb/surrealdb.net
PHP	https://surrealdb.com/docs/sdk/php	https://github.com/surrealdb/surrealdb.php
C	Source-only beta	https://github.com/surrealdb/surrealdb.c
Swift	Source / package docs	https://github.com/surrealdb/surrealdb.swift
Kotlin	Source / snapshot docs	https://github.com/surrealdb/surrealdb.kotlin
Ruby	Source / RubyGems docs	https://github.com/surrealdb/surrealdb.rb

GitHub Repositories

Repository	Description
https://github.com/surrealdb/surrealdb	Core database engine (Rust)
https://github.com/surrealdb/surrealdb.js	JavaScript/TypeScript SDK
https://github.com/surrealdb/surrealdb.py	Python SDK
https://github.com/surrealdb/surrealdb.go	Go SDK
https://github.com/surrealdb/surrealdb.java	Java SDK
https://github.com/surrealdb/surrealdb.net	.NET SDK
https://github.com/surrealdb/surrealdb.php	PHP SDK
https://github.com/surrealdb/surrealdb.c	C SDK binding (source-only beta)
https://github.com/surrealdb/surrealdb.swift	Swift SDK
https://github.com/surrealdb/surrealdb.kotlin	Kotlin SDK
https://github.com/surrealdb/surrealdb.rb	Ruby SDK
https://github.com/surrealdb/surrealist	Surrealist IDE/Query Explorer
https://github.com/surrealdb/surrealkit	Schema sync, rollouts, seeds, and DB tests
https://github.com/surrealdb/surrealmcp	Model Context Protocol server
https://github.com/surrealdb/surrealml	SurrealML preview tooling
https://github.com/surrealdb/n8n-nodes-surrealdb	Official scoped n8n community node
https://github.com/surrealdb/codemirror	CodeMirror / Lezer SurrealQL packages
https://github.com/surrealdb/agent-skills	Official upstream Agent Skills repository
https://github.com/surrealdb/docs.surrealdb.com	Documentation source

Tools and Applications

Tool	URL	Description
Surrealist (Cloud)	https://app.surrealdb.com	Browser-based query explorer and IDE
Surrealist (Desktop)	https://surrealdb.com/surrealist	Downloadable desktop application
SurrealDB Cloud	https://surrealdb.com/cloud	Managed SurrealDB hosting
n8n integration docs	https://surrealdb.com/docs/integrations/data-management/n8n/	Official self-hosted n8n community-node docs
AI framework integrations	https://surrealdb.com/docs/integrations/ai-frameworks	Official docs index; verify individual package/API shape before coding
Agent memory context / Spectron	https://surrealdb.com/docs/learn/context	Roadmap / coming-soon surface, not a GA runtime API

Community

Resource	URL
Discord	https://discord.gg/surrealdb
GitHub Discussions	https://github.com/surrealdb/surrealdb/discussions
Blog	https://surrealdb.com/blog
YouTube	https://youtube.com/@surrealdb
Twitter / X	https://x.com/surrealdb

Learning Resources

Resource	URL
Getting Started Guide	https://surrealdb.com/docs/surrealdb/introduction/start
SurrealQL Tutorial	https://surrealdb.com/docs/surrealdb/surrealql/overview
University (Video Courses)	https://surrealdb.com/learn

SurrealDB Ecosystem Integrations

This rule captures first-party or official-docs ecosystem surfaces that do not yet justify a full dedicated rule, or whose exact API should be re-verified before implementation. Use this as an ecosystem map, not as a substitute for the focused rules (rules/sdks.md, rules/langchain.md, rules/editor-tooling.md, rules/surrealmcp.md).

Verified snapshot: 2026-06-17.

---

New Ecosystem Surfaces (since v1.6.6)

Project	Status	Skill pointer
surqlize	Active development	Type-safe TypeScript ORM with graph support — verify API before examples
datasets	Official sample data	Browse in Surrealist v3.9+ datasets panel
agent-memory	Demo only	KG + vector agent memory reference; requires `--allow-experimental`
kaig	Demo	Graph RAG knowledge AI sample
Built-in MCP (`surreal mcp`)	GA in SurrealDB 3.1+	`rules/surrealmcp.md` — prefer over standalone for local IDE hosts

---

n8n Community Node

The official n8n node lives at surrealdb/n8n-nodes-surrealdb and publishes the scoped npm package @surrealdb/n8n-nodes-surrealdb.

Current verified release: v0.6.0 / npm 0.6.0 (2026-04-24). v0.6.0 adds SurrealDB server v3 support by upgrading to the JavaScript SDK surrealdb ^2.0.3, and the release workflow uses trusted publishing.

Install in a self-hosted n8n instance:

Settings -> Community Nodes -> Install -> @surrealdb/n8n-nodes-surrealdb

Important boundaries:

Self-hosted n8n only. Community nodes do not run in n8n Cloud.
HTTP/HTTPS only. The node does not support ws:// or wss:// connection

strings because of n8n's execution model.

To expose the node as an AI tool, set

N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true.

Credential scopes are root, namespace, or database. Use scoped SurrealDB

users for production workflows instead of root credentials.

Prefer the node's parameter fields for query variables; don't concatenate

untrusted user input into raw SurrealQL strings.

Operations covered by the upstream README and docs include record CRUD, table operations, field/index operations, relationship operations, raw query execution, visual SELECT-query building, health check, version, and connection pool statistics.

---

AI Framework Docs Index

The official docs index now lists multiple AI framework integrations:

Agno
Camel
CrewAI
Dagster
Google Agent
Kreuzberg
LangChain
LlamaIndex
Pydantic AI
SmolAgents

Only LangChain has a fully verified local rule in this skill (rules/langchain.md). For every other framework, treat the docs page as a pointer and verify the package, import path, constructor/API shape, and current SurrealDB SDK dependency before writing code.

Default production pattern across these frameworks:

1. Compute embeddings or agent memory artifacts in the framework runtime. 2. Persist structured data, graph edges, and vectors through an official SurrealDB SDK. 3. Enforce tenant/user isolation in SurrealDB with DEFINE ACCESS and table permissions instead of trusting framework-side filters only.

---

Spectron / Agent Memory Context

Spectron remains preview/alpha — not a generally available runtime API. However, upstream SDK main branches now expose Spectron-related endpoints:

surrealdb.js main: Spectron package at 1.0.0-alpha.4 (unreleased on npm)
surrealdb.py main: Spectron SDK endpoints added (unreleased on PyPI)

Do not present Spectron as stable. Pin to explicit commits and audit before production. The `surrealdb/agent-memory` demo shows a reference architecture combining graph + vectors; it requires experimental server flags and is not a production template.

Stable building blocks available today:

rules/vector-search.md for HNSW and DiskANN vector storage and retrieval
rules/graph-queries.md for graph edges and traversal
rules/security.md for access control and tenant isolation
rules/langchain.md for the currently verified Python LangChain vector store
rules/surrealmcp.md for agent tool access to SurrealDB

---

CodeMirror

The official CodeMirror packages are tracked in rules/editor-tooling.md: @surrealdb/codemirror and @surrealdb/lezer v1.0.6. Use them when building a custom web editor that needs SurrealQL syntax support. They are not database clients and do not replace the language server for schema-aware diagnostics.

---

Official Agent Skills Repo

SurrealDB also maintains surrealdb/agent-skills, a separate Agent Skills standard repository. Current verified commit: 95628976c277 (2026-06-17). Four additional upstream skills shipped since the v1.6.6 snapshot.

Install all official upstream skills:

npx skills add surrealdb/agent-skills

Install a specific upstream skill:

npx skills add surrealdb/agent-skills --skill surrealql
npx skills add surrealdb/agent-skills --skill surrealdb-vector
npx skills add surrealdb/agent-skills --skill surrealdb-python

Those upstream skills are narrower and are not a drop-in replacement for this package. This repo tracks a broader, adversarially corrected rule set across SurrealDB 3, SDKs, tooling, deployment, security, and AI-agent surfaces.

---

Cross-References

Official docs overview: https://surrealdb.com/docs
Official integrations docs: https://surrealdb.com/docs/integrations
n8n docs: https://surrealdb.com/docs/integrations/data-management/n8n/
n8n repo: https://github.com/surrealdb/n8n-nodes-surrealdb
CodeMirror repo: https://github.com/surrealdb/codemirror
Agent Skills repo: https://github.com/surrealdb/agent-skills

Related skills

Lark BaseLet their coding agents read from, write to, and query structured data stored in Lark Base (Feishu) spreadsheets and databases.493k

Azure KustoRun fast KQL queries against Azure Data Explorer for log analytics, telemetry, and time-series data.484k1.3k

Lark SheetsCreate, read, update, and export spreadsheets inside Lark (Feishu) directly from their AI coding agent.389k15.9k

Supabase Postgres Best PracticesAutomatically apply Supabase Postgres performance rules during query writing, schema design, and database optimization.313k2.4k

Firebase Data ConnectGenerate complete, production-ready Firebase Data Connect GraphQL schemas and queries for complex relational data models.112k392

Firebase FirestoreAdd Cloud Firestore read/write capabilities to an Android Kotlin app using the official Firebase SDK.77k392

FAQ

What SurrealDB version does it target?

SurrealDB 3, tracking v3.1.4 and later, snapshotted 2026-06-17.

What tools does it need?

The surreal CLI, Python 3.10+, and uv; Docker and the gh CLI are optional.

Databasesdatabases

About

Surrealdb by the numbers

surrealdb capabilities & compatibility

What surrealdb says it does

Add your badge

What it does

Who is it for?

When should I use this skill?

What you get

By the numbers

Files

SurrealDB 3 Expert Skill

When Copilot Should Use This Skill

Rules Reference

Quick Reference

SurrealQL Essentials

Key Concepts

Scripts

Security Notes

Describe the Bug

Steps to Reproduce

Expected Behavior

Actual Behavior

Environment

Relevant Log Output

Additional Context

Is your feature request related to a problem?

Describe the Solution You'd Like

Which Rule or Script Would This Affect?

Additional Context

Description

Type of Change

Checklist

Related Issues

Additional Notes

Agent Briefing: surrealdb

Quick Start

Capabilities

Decision Trees

"User wants to create a SurrealDB project"

"User has a data modeling question"

"User needs to optimize performance"

"User wants to write WASM extensions"

"User wants to deploy / serve an ML model"

"User hit a surprising SurrealDB behavior / gotcha"

"User wants AI agents to talk to SurrealDB"

"User wants editor / IDE support"

"User wants LangChain / RAG"

"User wants n8n / AI framework / ecosystem integration"

"User migrating from another database"

Common Workflows

1. Verify environment and connect

2. Design and apply a schema

3. Set up vector search

4. Graph traversal queries

5. Production deployment checklist

Rules Manifest

Configuration Requirements

Output Contracts

doctor.py

doctor.py (with issues)

schema.py introspect

schema.py tables

onboard.py --agent

Error Handling

Version Information

Source Provenance

Contributing to surreal-skills

Prerequisites

Development Setup

Project Structure

Code Style

Python Scripts (scripts/)

Rule Files (rules/)

SKILL.md Manifests

Adding or Updating Rules

Commit Convention

Pull Request Process

Issue Templates

Code of Conduct

`doctor.py`

`doctor.py` (with issues)

`schema.py introspect`

`schema.py tables`

`onboard.py --agent`

Python Scripts (`scripts/`)

Rule Files (`rules/`)

Fix-drift pattern (`~/CLAUDE.md` empirical observation confirmed)