Quickstart

Your first "what was true, when" query — in five minutes.

InvariantDB is a decision database: every write records what was true, when it was true, and what the system knew when it acted. Three paths to your first query — pick what's on your desk:

Want the full 30-minute walkthrough with production hardening, bitemporal deep-dive, and MCP integration? See the 30-minute onboarding runbook.

Path 1 — I have an AI agent (Claude / Cursor / custom LLM via MCP)
Path 2 — I have a Python or Node app (SDK)
Path 3 — I have curl (HTTP API)

Path 1 — AI agent via MCP

InvariantDB ships a Model Context Protocol server. One config line gets your agent 14 tools: Cypher query, fulltext + vector search, schema introspection, agent-memory primitives (record/replay episodes, beliefs, salience), provenance + audit replay.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows). Replace {name} with your graph name:

{
  "mcpServers": {
    "invariantdb": {
      "type": "http",
      "url": "https://invariantdb.com/graphs/{name}/mcp",
      "headers": {
        "Authorization": "Bearer gq_paste_your_api_key_here"
      }
    }
  }
}

Restart Claude Desktop. The 14 tools appear under the 🔌 icon.

Cursor / Continue / VS Code

The same shape works in any MCP-compatible client. Endpoint: https://invariantdb.com/graphs/{name}/mcp (HTTP POST, JSON-RPC 2.0). See the full tool catalog.

Get an API key

Sign in to the dashboard and create a graph. POST /cloud/me/graphs returns the raw API key exactly once — copy it immediately:

{
  "graph_id": "grph_01H...",
  "name": "my-graph",
  "status": "active",
  "api_key": "gq_live_a1b2c3...",
  "api_key_id": "key_01H...",
  "api_key_prefix": "gq_live_a1b2",
  "mcp_config": {
    "mcpServers": {
      "invariantdb": {
        "type": "http",
        "url": "https://us.invariantdb.com/graphs/my-graph/mcp",
        "headers": { "Authorization": "Bearer gq_live_a1b2c3..." }
      }
    }
  },
  "already_existed": false
}

On repeat calls (same graph name), the response returns "api_key": null and "mcp_config": null — mint a fresh key from the dashboard's API keys panel if you lost the original.

First query through your agent

"Show me every employee whose role changed in the last 90 days, with the timestamp the change was recorded versus when it took effect."

The agent translates this to Cypher, runs MATCH (p:Person)-[:HAS_ROLE]->(r) AT RECORDED <ts> AT VALID <ts> ..., and replies with structured output. The audit chain records the query, the noise (if you're in DP mode), and every property accessed.

Path 2 — SDK

Python

pip install invariantdb==0.7.0

from invariantdb import Client

db = Client("https://invariantdb.com", api_key="gq_...")
db.graphs.ensure("my-graph")

rows = db.cypher(
    graph="my-graph",
    query="MATCH (p:Person) WHERE p.role = 'engineer' RETURN p.name, p.startDate",
).rows

# Agent memory in one call
db.cypher(graph="my-graph", query="""
    CALL db.recordEpisode($s, 'observation', $text, {topic: 'pricing'})
""", parameters={"s": "conv-abc-123", "text": "User asked about pricing"})

Node

npm install https://sdk.invariantdb.com/node/invariantdb-0.7.0.tgz

import { Client } from 'invariantdb';

const db = new Client({ url: 'https://invariantdb.com', apiKey: 'gq_...' });
await db.graphs.ensure({ name: 'my-graph' });
const { rows } = await db.cypher({
  graph: 'my-graph',
  query: 'MATCH (n) RETURN count(n) AS total',
});

Full SDK reference: docs.

Path 3 — curl against the HTTP API

Graph creation uses a JWT (from the dashboard sign-in flow). Cypher queries use the raw gq_... API key returned by that create call.

KEY="gq_paste_your_api_key_here"
JWT="paste_your_dashboard_jwt_here"

# 1. Create a graph (idempotent; returns raw api_key once)
curl -fsS -X POST -H "Authorization: Bearer $JWT" \
    -H "Content-Type: application/json" \
    --data '{"name": "my-graph"}' \
    https://invariantdb.com/cloud/me/graphs

# 2. Run a Cypher query
curl -fsS -X POST -H "Authorization: Bearer $KEY" \
    -H "Content-Type: application/json" \
    --data '{
      "graph": "my-graph",
      "query": "CREATE (p:Person {name: \"Alice\", role: \"engineer\"}) RETURN p"
    }' \
    https://invariantdb.com/cypher

# 3. Read it back — with every version of the node (bitemporal)
curl -fsS -X POST -H "Authorization: Bearer $KEY" \
    -H "Content-Type: application/json" \
    --data '{
      "graph": "my-graph",
      "query": "MATCH (p:Person {name: \"Alice\"}) CALL db.history(id(p)) YIELD version, timestamp, properties, validFrom, validTo RETURN version, timestamp, properties, validFrom, validTo"
    }' \
    https://invariantdb.com/cypher

Full HTTP API: /openapi.yaml or the interactive /docs (Swagger UI).

Next steps by goal

If you're building…	Read
An AI agent that remembers	AI memory primitives
A compliance-grade audit trail	Compliance dashboard
A research data API with privacy guarantees	Features › Differential privacy
Anything in healthcare / finance / insurance / public sector	Regulated industries
The full feature catalog	Features

When something doesn't work

401 Unauthorized — missing or wrong Authorization: Bearer gq_... header. Mint a fresh key from the dashboard.
403 Forbidden — key auth'd, but the role doesn't permit the operation. Mint an admin-role key.
404 Not Found on /graphs/<name>/... — create the graph first via POST /cloud/me/graphs.
429 Too Many Requests — per-key rate limit. Increase via the rateLimits block.
PRIVATE_MODE_NON_AGGREGATE_RETURN — you're using a private-mode (DP) key; only scalar aggregates allowed. See Features › Differential privacy.
Cypher parse error — InvariantDB targets openCypher; minor syntax differences listed in the docs.