Local vs Remote

The SDK exposes two interchangeable backends behind the hm.connect() factory and the hypermesh.types.Database protocol. Write code against Database and it runs unchanged against either.

import hypermesh as hm

def count_recent(db: hm.types.Database, start: int, end: int) -> int:
    res = db.execute(
        "MATCH HYPEREDGE (he:CoProximity) "
        "WHERE he.event_ts >= $s AND he.event_ts <= $e RETURN *",
        parameters={"s": start, "e": end},
    )
    return res.num_tuples

Choosing a backend

	Embedded (Connection)	Remote (Client / AsyncClient)
Open with	a filesystem path	an http(s):// URL
Engine binary	required ([engine])	not required
execute, insert, delete, compact, analytics	✅	✅
copy_from_csv/df/parquet/json/numpy	✅	❌ (use COPY ... FROM via execute)
Multi-statement transactions	✅	❌
to_hypergraph()	✅	❌
Auth / TLS / retries	n/a	✅

Remote client configuration

db = hm.connect(
    "https://hypermesh.internal:8000",
    api_key="…",            # or HYPERMESH_API_KEY
    timeout=30.0,
    verify=True,            # TLS verification (or a CA bundle path)
    retries=2,              # exponential backoff + jitter
    backoff_factor=0.25,
    headers={"X-Tenant": "acme"},
)
db.ping()       # -> bool
db.health()     # -> dict

Environment variables: HYPERMESH_URL, HYPERMESH_API_KEY. Resolve everything once with hm.Config.from_env().

Async

import asyncio
from hypermesh import AsyncClient

async def main():
    async with AsyncClient("https://hypermesh.internal:8000") as db:
        res = await db.execute("MATCH HYPEREDGE (he:CoProximity) RETURN *")
        print(res.num_tuples)

asyncio.run(main())