surrealdb-canonical-layer

SurrealDB Canonical-Layer Verification

A SurrealDB-backed canonical layer (persons/organizations/affiliations plus a schemaless observations log, all multi-tenant via client_access) is first live in augment-it, and the pattern — canonical entities + an append-only observation log + client-scoped visibility — is the kind of shape other Lossless projects (dididecks-ai, memopop-ai) are likely to reach for too. This skill is the discipline for querying that layer directly to verify a batch of writes landed correctly, replacing the previous habit of writing a fresh disposable Node script (connect → signin → use → query, deleted after) for every check.

Companion piece: search-lossless-corpus does the same job for the Chroma corpus (MCP for raw access, a skill for the discipline on top). This skill copies that shape for SurrealDB.

Prerequisite — the surrealdb MCP server

Each project that wants this skill needs its own project-scoped .mcp.json entry pointing at surrealmcp, the official SurrealDB MCP server. It's a Rust binary with exactly two distribution paths — build from source (cargo install --path .) or the surrealdb/surrealmcp:latest Docker image. There's no npm/PyPI package, so it can't be invoked the one-line uvx/npx way the chroma MCP server is.

augment-it's wiring (the reference implementation — copy this shape into a new project rather than re-deriving it):

• augment-it/scripts/mcp-surrealdb.sh — a wrapper script that sources .env relative to its own location ($(dirname "${BASH_SOURCE[0]}")), not $PWD and not the launching shell's exported environment, then execs docker run --rm -i --pull always -e SURREALDB_URL=... surrealdb/surrealmcp:latest start. This matters because Claude Code's ${VAR} expansion in .mcp.json only reads variables already exported in the shell that launched claude — it does not read .env files — and this repo's habit is sourcing .env per-command (set -a; source ./.env; set +a), not exporting at shell startup. The wrapper script sidesteps that dependency entirely.
• augment-it/.mcp.json:

  {
    "mcpServers": {
      "surrealdb": {
        "command": "${CLAUDE_PROJECT_DIR:-.}/scripts/mcp-surrealdb.sh"
      }
    }
  }
  

  ${CLAUDE_PROJECT_DIR:-.} (not a hardcoded absolute path) keeps this portable across machines — Claude Code sets that variable to the project root when spawning the server.
• Env vars the wrapper maps from this project's existing SURREAL_* names (.env) to surrealmcp's expected SURREALDB_* names: SURREAL_URL → SURREALDB_URL, SURREAL_NS → SURREALDB_NS, SURREAL_DB → SURREALDB_DB, SURREAL_USER → SURREALDB_USER, SURREAL_PASS → SURREALDB_PASS.
• After adding or editing .mcp.json, the tools don't appear in an already-running Claude Code session — reconnect (/mcp) or start a new session. claude mcp list from a shell confirms connectivity independently of whether the current chat session has picked up the new tools yet.