mindgraph

Python client for the MindGraph Cloud API — a structured semantic memory graph for AI agents.

Install

pip install mindgraph-sdk

Quick Start

from mindgraph import MindGraph

with MindGraph("https://api.mindgraph.cloud", api_key="mg_...") as graph:
    # Add a node
    node = graph.add_node(
        label="User prefers dark mode",
        node_type="Preference",
    )

    # Search
    results = graph.search("what does the user prefer?")

    # Connect knowledge
    graph.add_link(
        from_uid=node["uid"],
        to_uid="user_abc",
        edge_type="BelongsTo",
    )

API Reference

Constructor

MindGraph(base_url, *, api_key=None, jwt=None, timeout=30.0)

Supports context manager protocol (with statement) for automatic cleanup.

Reality Layer

Typed entity example:

person = graph.find_or_create_person("Marie Curie", props={"nationality": "Polish"})
org = graph.find_or_create_organization("CERN", props={"org_type": "intergovernmental"})
concept = graph.find_or_create_concept("Nuclear Physics")

# find_or_create_entity() still works as a generic fallback for any entity type
entity = graph.find_or_create_entity("Some Entity")

Epistemic Layer

Intent Layer

Action Layer

Memory Layer

output_type="skill" requires caller-authored SKILL.md content and at least one provenance field. It always creates a candidate for review:

graph.distill(
    label="Recover a malformed import",
    output_type="skill",
    work_uid="work_import_42",
    props={
        "name": "recover-malformed-import",
        "description": "Use after a spreadsheet import fails schema validation.",
        "content": "# Recovery\n\nValidate headers, normalize dates, then retry.",
    },
)

Agent Layer

Synthesis (Projects)

Scope a corpus to a Project (via commit(action="project", ...) then link documents with PartOfProject), then mine cross-document signals and generate synthesis articles.

project = graph.commit(action="project", label="Q2 China strategy")
# ...link documents to the project via PartOfProject edges...
signals = graph.signals(project["uid"], signals="clustered_claim_hubs,dialectical_pairs")
job = graph.run_synthesis(project["uid"])
status = graph.get_job(job["job_id"])

Operational Ontology (Layer 7)

Define typed domain objects (Customer, Order, Contract…) as a semantic contract and either bind them to a SQL database or extract them from documents — fused onto one object. Connecting a database (credentials/sync) is done in the dashboard; the SDK proposes/reviews schemas, queries, and lists the generated agent read tools.

res = graph.propose_ontology_schema(description="Clients, orders, contracts.")
graph.activate_ontology_schema(res["schema_id"])
tools = graph.list_ontology_tools()
ctx = graph.query_ontology(query="Which customers are a churn risk?", schema_id=res["schema_id"])

See the Operational Ontology and Connect a database docs.

CRUD

Search

Traversal

Ingestion & Retrieval

Lifecycle Shortcuts

Cross-cutting

Health & Stats

Account sign-up, login, and API key management live in the MindGraph dashboard — not the SDK. Get your API key there, then pass it to the MindGraph constructor.

Examples

See examples/ for runnable demos, including a research continuity scenario showing cross-session memory retrieval.

Error Handling

All methods raise MindGraphError on HTTP errors:

from mindgraph import MindGraphError

try:
    graph.get_node("nonexistent")
except MindGraphError as e:
    print(e.status, e.body)

License

MIT

Retry and engine-error contract

HTTP 503 retries are bounded and apply only to reviewed reads (including selected POST query actions) and keyed /agent/plan work operations: claim_task, heartbeat, start_iteration, checkpoint_iteration, block_task, complete_task, and abandon_iteration. These work operations atomically store their mutation and idempotency receipt. A nonempty idempotency_key must stay unchanged across attempts. Other writes are not retried automatically; supplying a key or telemetry request ID on an unsupported route does not change that.

MindGraphError preserves the response status and body and exposes optional code and retriable fields. Explicit retriable: false always stops retries, including admission failures and index maintenance. Memory limits, timeouts, and cancellation remain failures; they do not become empty search results. Older responses without retry guidance retain retries only for the reviewed operations above. Each delay, including fallback backoff, is capped at 10 seconds. Network exceptions and other HTTP statuses are not automatically retried.