mindgraph-sdk 0.1.0

Python client for the MindGraph Cloud API

mindgraph

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

Install

pip install mindgraph

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

Method	Description
ingest(**kwargs)	Ingest a source, snippet, or observation
entity(**kwargs)	Create, alias, resolve, or merge entities
find_or_create_entity(label, entity_type?, agent_id?)	Convenience: create or find an entity by label

Epistemic Layer

Method	Description
argue(**kwargs)	Construct a full argument: claim + evidence + warrant + edges
inquire(**kwargs)	Add hypothesis, theory, paradigm, anomaly, assumption, or question
structure(**kwargs)	Add concept, pattern, mechanism, model, analogy, theorem, etc.

Intent Layer

Method	Description
commit(**kwargs)	Create a goal, project, or milestone
deliberate(**kwargs)	Open decisions, add options/constraints, resolve decisions

Action Layer

Method	Description
procedure(**kwargs)	Build flows, add steps, affordances, and controls
risk(**kwargs)	Assess risk or retrieve existing assessments

Memory Layer

Method	Description
session(**kwargs)	Open a session, record traces, or close a session
distill(**kwargs)	Create a summary that distills multiple source nodes
memory_config(**kwargs)	Set/get preferences and memory policies

Agent Layer

Method	Description
plan(**kwargs)	Create tasks, plans, plan steps, update status
governance(**kwargs)	Create policies, set safety budgets, request/resolve approvals
execution(**kwargs)	Track execution lifecycle and register agents

CRUD

Method	Description
get_node(uid)	Get a node by UID
add_node(label, node_type?, props?, agent_id?)	Add a generic node
update_node(uid, **kwargs)	Update node fields
delete_node(uid)	Tombstone a node and all connected edges
add_link(from_uid, to_uid, edge_type, agent_id?)	Add a typed edge
get_edges(from_uid?, to_uid?)	Get edges by source or target

Search

Method	Description
search(query, node_type?, layer?, limit?)	Full-text search
hybrid_search(query, k?, node_types?, layer?)	BM25 + vector search with rank fusion

Traversal

Method	Description
reasoning_chain(uid, max_depth=5)	Follow epistemic edges from a node
neighborhood(uid, max_depth=1)	Get all nodes within N hops

Cross-cutting

Method	Description
retrieve(**kwargs)	Unified retrieval: text search, active goals, open questions, weak claims
traverse(**kwargs)	Graph traversal: chain, neighborhood, path, or subgraph
evolve(**kwargs)	Lifecycle mutations: update, tombstone, restore, decay, history

Health & Stats

Method	Description
health()	Health check
stats()	Graph-wide statistics

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