From cold sign-up to your first bitemporal query, agent memory, and a live AI connection — in 30 minutes.

Zero fluff. Every command below is written against the current production binary on the box that answers invariantdb.com. If something fails, the failure output is printed next to the fix — and if the exact behavior drifts under you, please tell us at the signup form so we can pin the next revision.

Requirements: a terminal, Python 3.9+ (or Node 18+), and 30 minutes. You do not need a credit card. You do not need to install a database. If you are on Windows, use PowerShell or WSL — every command below is copy-pasteable in either.

0—3Sign up and verify email

Go to invariantdb.com/signup.html. Fill in email + name + password. You will be issued a Cognito account and a tenant.

Under the hood the site does two things:

1. Cognito hosted sign-up → verification email → you click the link.
2. After first successful sign-in, the browser calls POST /cloud/me/bootstrap with your Cognito JWT. That call is idempotent and creates your tenant record (region us by default; add ?region=eu if you need EU residency).

You will land on the dashboard. On the dashboard, do two things:

1. Create a graph. Type hello as the name and press Create graph. The response contains an api_key that starts with gq_. Copy this key into a safe place immediately — it is displayed once and cannot be recovered later. It is your data-plane credential; every subsequent HTTP call, SDK call, and MCP connection uses it as Authorization: Bearer gq_….
2. Note your MCP config block. The same response shows a copy-paste JSON for Claude Desktop and Cursor. You will use this at minute 25.

export IDB_KEY="gq_paste_your_api_key_here"
export IDB_GRAPH="hello"

3—5Understand what you got

Three nouns, three verbs. Read this once and you will never be confused by the API surface again.

Every call goes to one of three URL prefixes:

The critical distinction: the JWT from Cognito is only for administering your tenant. It cannot run Cypher. The gq_… key is only for the data plane. It cannot mint other keys. Mixing them silently 401s.

$ curl -H "Authorization: Bearer eyJraWQ..." https://invariantdb.com/e/graphs/hello/cypher \
    -d '{"query":"MATCH (n) RETURN count(n)"}'
{"error":{"code":"UNAUTHORIZED","message":"invalid credential for data plane"}}

5—10Install the SDK and count the nodes in your empty graph

Python

pip install invariantdb

Then, in a Python REPL or a file called hello.py:

from invariantdb import Client

db = Client("https://invariantdb.com", api_key="gq_paste_your_api_key_here")

result = db.cypher(
    graph="hello",
    query="MATCH (n) RETURN count(n) AS total"
)
# `rows` are positional lists that line up with `columns`.
# Call `.as_dicts()` for keyed output.
print(result.columns, result.rows)
# -> ['total'] [[0]]
print(result.as_dicts())
# -> [{'total': 0}]

You just:

1. Authenticated with a bearer token,
2. Hit POST https://invariantdb.com/e/graphs/hello/cypher,
3. Parsed a Cypher result set,
4. Verified the graph has zero nodes (which is correct — you just made it).

Node

npm install invariantdb

import { Client } from 'invariantdb';

const db = new Client({ url: 'https://invariantdb.com', apiKey: 'gq_paste_your_api_key_here' });

const { rows } = await db.cypher({
    graph: 'hello',
    query: 'MATCH (n) RETURN count(n) AS total'
});
console.log(rows);
// [{ total: 0 }]

curl (equivalent)

curl -fsS -X POST -H "Authorization: Bearer $IDB_KEY" \
    -H "Content-Type: application/json" \
    --data '{"query":"MATCH (n) RETURN count(n) AS total"}' \
    "https://invariantdb.com/e/graphs/$IDB_GRAPH/cypher"
# {"rows":[{"total":0}],"columns":["total"],"stats":{...}}

{"error":{"code":"UNAUTHORIZED","message":"missing or invalid Authorization header"}}

{"error":{"code":"GRAPH_NOT_FOUND","message":"graph 'hell' not found"}}

10—15Create three people and a company

Cypher — the same query language you already know from Neo4j — drives every write and read. InvariantDB adds bitemporal extensions on top; the core language is unchanged.

Copy-paste this into your Python file:

db.cypher(graph="hello", query="""
    CREATE (a:Person {name: 'Alice', role: 'engineer',      startDate: date('2024-01-15')})
    CREATE (b:Person {name: 'Bob',   role: 'product',       startDate: date('2024-03-01')})
    CREATE (c:Person {name: 'Carol', role: 'engineer',      startDate: date('2025-06-01')})
    CREATE (co:Company {name: 'Acme', industry: 'software'})
    CREATE (a)-[:WORKS_AT {since: date('2024-01-15')}]->(co)
    CREATE (b)-[:WORKS_AT {since: date('2024-03-01')}]->(co)
    CREATE (c)-[:WORKS_AT {since: date('2025-06-01')}]->(co)
    RETURN count(*) AS created
""")

# Read it back — iterating a CypherResult yields column-keyed dicts.
result = db.cypher(graph="hello", query="""
    MATCH (p:Person)-[:WORKS_AT]->(co:Company {name: 'Acme'})
    RETURN p.name, p.role, p.startDate
    ORDER BY p.startDate
""")
for r in result:
    print(r)
# {'p.name': 'Alice', 'p.role': 'engineer', 'p.startDate': '2024-01-15'}
# {'p.name': 'Bob',   'p.role': 'product',  'p.startDate': '2024-03-01'}
# {'p.name': 'Carol', 'p.role': 'engineer', 'p.startDate': '2025-06-01'}

Two things worth noticing:

• Dates are first-class. date('2024-01-15') parses to an ISO-8601 calendar date — not a string, not a millisecond timestamp. You can compare, add days, extract year, all through openCypher's temporal API.
• The write returned a stats block. If you inspect result.stats you will see nodesCreated, relationshipsCreated, propertiesSet. This is how you know an idempotent MERGE actually did something.

Now try a MERGE. Run it twice — the second run should not create anything new:

for _ in range(2):
    r = db.cypher(graph="hello", query="""
        MERGE (d:Person {name: 'Dana'})
          ON CREATE SET d.role = 'design', d.startDate = date('2026-02-01')
        RETURN d.name AS name
    """)
    print(r.stats)
# {'nodesCreated': 1, 'propertiesSet': 2, ...}
# {'nodesCreated': 0, 'propertiesSet': 0, ...}

{"error":{"code":"CYPHER_PARSE_ERROR","message":"expected '{' at line 1, column 42",
          "position":{"line":1,"column":42}}}

15—20The bitemporal WOW: rewrite the past without a migration

Let us walk it. Right now, Alice's role is engineer as of 2024-01-15. Suppose HR corrects the record on today: “actually, Alice was promoted to senior engineer on 2025-01-01 — we just forgot to update the system.”

Step 1 — write the correction, valid-from 2025-01-01

Bitemporal clauses attach to the MATCH pattern as a prefix (AT VALID '<ISO-8601>') — not as a trailing SET modifier. The write below opens a new valid-time interval starting 2025-01-01 for Alice's role:

db.cypher(graph="hello", query="""
    AT VALID '2025-01-01T00:00:00Z'
    MATCH (a:Person {name: 'Alice'})
    SET a.role = 'senior engineer'
""")

InvariantDB does not overwrite Alice's role. It closes the old row (role=engineer valid [2024-01-15, 2025-01-01)) and opens a new row (role=senior engineer valid [2025-01-01, ∞)). Both rows share a recorded_at of “right now” — because that is when the system learned about the correction.

Step 2 — query the world as of April 2024

result = db.cypher(graph="hello", query="""
    MATCH (a:Person {name: 'Alice'}) AT VALID '2024-04-15T00:00:00Z'
    RETURN a.name, a.role
""")
print(result.as_dicts())
# [{'a.name': 'Alice', 'a.role': 'engineer'}]

Alice was an engineer in April 2024. That was true then and it is still true now.

Step 3 — query the world as of today

result = db.cypher(graph="hello", query="""
    MATCH (a:Person {name: 'Alice'})
    RETURN a.name, a.role
""")
print(result.as_dicts())
# [{'a.name': 'Alice', 'a.role': 'senior engineer'}]

Step 4 — query what the system believed yesterday (before the correction)

from datetime import datetime, timezone, timedelta
# ISO-8601 with the trailing 'Z' for UTC — no timezone offset.
yesterday = (datetime.now(timezone.utc) - timedelta(days=1)).strftime('%Y-%m-%dT%H:%M:%SZ')

result = db.cypher(graph="hello", query=f"""
    MATCH (a:Person {{name: 'Alice'}}) AT RECORDED '{yesterday}'
    RETURN a.name, a.role
""")
print(result.as_dicts())
# [{'a.name': 'Alice', 'a.role': 'engineer'}]

Yesterday, we still thought Alice was an engineer — because the correction had not been recorded yet. This is what knowledge time gives you: an unforgeable answer to “what did we know when we acted?”

Step 5 — walk the full history of Alice's role

result = db.cypher(graph="hello", query="""
    MATCH (a:Person {name: 'Alice'})
    CALL db.propertyHistory(id(a), 'role') YIELD value, validFrom, validTo, version, txnAt
    RETURN value, validFrom, validTo, version, txnAt
    ORDER BY validFrom
""")
for r in result:
    print(r)
# {'value':'engineer',        'validFrom':'2024-01-15T00:00:00Z','validTo':'2025-01-01T00:00:00Z','version':1,'txnAt':...}
# {'value':'senior engineer', 'validFrom':'2025-01-01T00:00:00Z','validTo':null,                    'version':2,'txnAt':...}

Two rows. Different valid intervals. txnAt is the transaction time (when the system learned it) — the recorded-time axis. The audit trail is the schema.

{"error":{"code":"CYPHER_PARSE_ERROR",
          "message":"unexpected token near AT VALID"}}

20—25Agent memory: record an episode, replay it

An episode is a first-class primitive: a single observed event in the life of an AI agent (a user turn, a tool call, a summarization, an internal reflection). Each episode carries a subject (usually a conversation ID), a kind, text content, structured metadata, and — automatically — an embedding for later hybrid recall.

Record two episodes on a conversation

Each call takes (sessionId, kind, text [, payload]). payload is optional structured metadata — pass a JSON-shaped map as the fourth argument. The procedure YIELDS eventId and ts (nanosecond epoch).

db.cypher(graph="hello", parameters={
    "conv": "conv-2026-07-09-001",
    "text1": "User asked about pricing for the enterprise plan.",
    "text2": "Agent replied with a summary of tiers; user asked to schedule a call.",
}, query="""
    CALL db.recordEpisode($conv, 'observation', $text1) YIELD eventId AS e1, ts AS t1
    CALL db.recordEpisode($conv, 'observation', $text2) YIELD eventId AS e2, ts AS t2
    RETURN e1, t1, e2, t2
""")

Two :Event nodes now hang off a :Session {id: 'conv-2026-07-09-001'} node via [:HAD_EVENT] edges. Each Event carries an id, a nanosecond ts, the raw text, and (when embeddings are configured) a vector under _embedding_v1.

Replay them chronologically

result = db.cypher(graph="hello", parameters={"conv": "conv-2026-07-09-001"}, query="""
    CALL db.replayEpisodes($conv, 50)
    YIELD eventId, kind, ts, text, payload
    RETURN kind, text, ts, payload
    ORDER BY ts
""")
for r in result:
    print(r)

This is the primitive that lets an agent reconstruct the exact conversation state from any point in time — useful for “why did the agent make that decision at 4:12 PM?” postmortems and for warm-starting a new session with a summary of the last one.

Vector search across all conversations

gds.vectorSearch takes (label, prop, query [, k]) — a label + property pair, not a named index. db.recordEpisode writes into Event._embedding_v1, so that is what we search:

result = db.cypher(graph="hello", parameters={
    "q": "customer wanted to schedule a call about enterprise pricing"
}, query="""
    CALL gds.vectorSearch('Event', '_embedding_v1', $q, 5)
    YIELD nodeId, score
    MATCH (e:Event) WHERE id(e) = nodeId
    RETURN e.id, e.text, score
    ORDER BY score DESC
""")
for r in result:
    print(r)

This queries the same Events with semantic similarity. The vector index is built and stamped the first time you call recordEpisode — the default embedding model is applied unless you have configured one explicitly.

{"error":{"code":"UNKNOWN_YIELD_COLUMN",
          "message":"procedure 'db.replayEpisodes' does not YIELD 'content'; available: eventId, kind, ts, text, payload"}}

25—30Connect an AI over MCP

InvariantDB ships an MCP server. Any MCP-compatible client (Claude Desktop, Cursor, Continue, VS Code with the MCP extension) can attach in one config block and get access to 14 tools: Cypher query, fulltext + vector search, schema introspection, episode record/replay, belief-revision primitives, provenance queries, audit replay.

Path A — Claude Desktop

Open the config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Add (or merge) this block. HTTP MCP transport requires a recent Claude Desktop build (2025+); if your client only accepts stdio servers, the MCP catalog page lists a small stdio bridge you can shim in front:

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

Restart Claude Desktop. Click the tools icon (looks like a small plug). You should see 14 tools appear under “invariantdb.” Ask Claude:

“Using the invariantdb tool, count the people in the hello graph and list their roles.”

Claude will call cypher_query, run the query against your graph, and reply with structured output. You just gave an LLM a durable, bitemporal memory in six lines of config.

Path B — Cursor / Continue / VS Code

Same shape, different config file. See the MCP catalog page for the exact path per client. The endpoint (https://invariantdb.com/e/mcp), the auth header shape, and the tool surface are identical.

Path C — skip MCP and drive the decision demo

If you do not have an AI client on hand, open /decision-demo.html. It renders a live workflow — a synthetic underwriting decision that runs Cypher against a real graph, shows the bitemporal audit trail, and lets you scrub back in time to see what the model believed at any point. It is the same story you just walked minute-by-minute, in a UI.

Frequently asked, in the first hour

Where to go next

Three concrete paths. Pick the one closest to what you are trying to build.

Start free   Watch the decision demo   Full docs

Runbook version: 2026-07-09. Written against the current production binary. If a command in this page does not work exactly as printed, that is a bug — tell us at the signup form and we will fix it in the next revision.