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