MemgraphAI

v2 API — Cognitive Infrastructure

The v2 API adds cognitive primitives on top of v1's memory CRUD: entities, relationships, decisions, graph traversal, and context assembly. All endpoints use API key authentication.

Base URL: https://api.memgraph.ai/v2
Auth: X-API-Key: mg_your_key

Context Graph (Core)

The primary v2 endpoint. Performs 6-stage retrieval: semantic search, entity resolution, graph expansion, temporal filtering, confidence weighting, and context assembly.

POST/v2/context

Assemble full context for a query with memories, entities, decisions, and graph data.

bash
curl -X POST https://api.memgraph.ai/v2/context \
  -H "X-API-Key: mg_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What deployment strategy does Alice prefer?",
    "user_id": "alice",
    "agent_id": "support-bot",
    "include_decisions": true,
    "include_graph": true,
    "create_snapshot": false,
    "max_depth": 2
  }'

Response: memories[] (scored), entities[], relationships[], decisions[], snapshot, debug info

Entities

Named objects in the knowledge graph. Types: person, org, product, place, concept, system, project.

POST/v2/entities

Create a new entity with type, name, properties, and aliases.

bash
curl -X POST https://api.memgraph.ai/v2/entities \
  -H "X-API-Key: mg_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_type": "person",
    "name": "Alice Chen",
    "properties": {"role": "engineer", "team": "infra"},
    "aliases": ["alice", "achen"]
  }'
GET/v2/entities/{entity_id}

Get entity by ID.

GET/v2/entities

List entities. Filter by ?entity_type=person&limit=50.

POST/v2/entities/search

Fuzzy + semantic entity search.

bash
curl -X POST https://api.memgraph.ai/v2/entities/search \
  -H "X-API-Key: mg_your_key" \
  -H "Content-Type: application/json" \
  -d '{"query": "Alice", "max_results": 5}'
DELETE/v2/entities/{entity_id}

Delete entity and its relationships.

Relationships

Temporal edges between entities. Support valid_from/valid_to for time-scoped relationships.

POST/v2/relationships

Create a relationship between two entities.

bash
curl -X POST https://api.memgraph.ai/v2/relationships \
  -H "X-API-Key: mg_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "source_entity_id": "entity-uuid-1",
    "target_entity_id": "entity-uuid-2",
    "relation_type": "works_with",
    "confidence": 0.95,
    "valid_from": "2025-01-01",
    "valid_to": null
  }'
GET/v2/relationships

List relationships. Filter by ?entity_id=...&relation_type=...&limit=50.

DELETE/v2/relationships/{relationship_id}

Delete a relationship.

Decisions

Agent reasoning traces with goals, steps, tools, beliefs, and outcomes. See the Decisions guide for detailed usage.

POST/v2/decisions

Record a decision with reasoning trace.

bash
curl -X POST https://api.memgraph.ai/v2/decisions \
  -H "X-API-Key: mg_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "support-bot",
    "user_id": "alice",
    "goal": "Recommend deployment strategy",
    "reasoning_steps": [
      {"step": "Recall preferences", "thought": "Check user history"},
      {"step": "Analyze options", "result": "K8s best fit"}
    ],
    "tools_used": [
      {"name": "memory_search", "input": "deployment", "output": "K8s preferred"}
    ],
    "beliefs_used": ["belief-uuid-1"],
    "confidence": 0.85,
    "outcome": "SUCCESS"
  }'
POST/v2/decisions/synthesize

Auto-extract a decision from a message exchange.

GET/v2/decisions/{decision_id}

Get decision by ID.

GET/v2/decisions/{decision_id}/explain

Full explanation: beliefs, context snapshot, entity graph at decision time.

PATCH/v2/decisions/{decision_id}/outcome

Update outcome after the fact. Triggers belief confidence adjustment (LTP/LTD).

GET/v2/decisions/{decision_id}/outcome-impact

See which beliefs were strengthened/weakened by an outcome.

POST/v2/outcomes/record

Platform-friendly outcome recording.

GET/v2/decisions

List decisions. Filter by ?agent_id, ?user_id, ?outcome, ?limit.

Graph Traversal

POST/v2/graph/traverse

Traverse entity graph from seed entities.

bash
curl -X POST https://api.memgraph.ai/v2/graph/traverse \
  -H "X-API-Key: mg_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_ids": ["entity-uuid-1"],
    "max_depth": 2,
    "temporal_filter": true
  }'

Contradictions

Memgraph automatically detects when new beliefs contradict existing ones.

GET/v2/contradictions

List contradictions. Filter by ?status=active&limit=50.

PATCH/v2/contradictions/{contradiction_id}

Resolve or dismiss a contradiction.

bash
curl -X PATCH https://api.memgraph.ai/v2/contradictions/uuid \
  -H "X-API-Key: mg_your_key" \
  -H "Content-Type: application/json" \
  -d '{"resolution_status": "resolved", "resolved_by": "manual"}'

Trust Score

GET/v2/trust-score/{agent_id}

Agent accuracy and track record. Optional ?domain filter.

GET/v2/trust-score/{agent_id}/failure-analysis

Which beliefs correlate with agent failures.

Analytics

GET/v2/analytics

Decision success rate, outcome distribution, contradiction rate, avg confidence.

GET/v2/decisions/belief-usage

Belief usage stats: total uses, success count, failure count per belief.

GET/v2/cache/stats

Context cache hit/miss/error statistics.

Domains

GET/v2/domains

List supported professional domains.

GET/v2/domains/{domain_name}

Get domain configuration: categories, trust threshold, etc.

Using v2 with the Python SDK

python
from memgraph_sdk import MemgraphClient

client = MemgraphClient(api_key="mg_your_key")

# Context graph (core v2 interface)
context = client.get_context_graph(
    query="What does Alice prefer?",
    user_id="alice",
    include_decisions=True,
    include_graph=True,
)

# Entities
entity = client.create_entity(
    entity_type="person",
    name="Alice Chen",
    properties={"role": "engineer"},
    aliases=["alice"],
)
results = client.search_entities("Alice", max_results=5)

# Relationships
rel = client.create_relationship(
    source_entity_id=entity["id"],
    target_entity_id="other-entity-id",
    relation_type="works_with",
    confidence=0.95,
)

# Decisions
decision = client.record_decision(
    goal="Recommend deployment",
    agent_id="bot",
    user_id="alice",
    confidence=0.85,
    outcome="SUCCESS",
)
explanation = client.explain_decision(decision["id"])

# Graph traversal
graph = client.traverse_graph(
    entity_ids=[entity["id"]],
    max_depth=2,
)

# Contradictions
contradictions = client.list_contradictions(status="active")
client.resolve_contradiction(contradictions[0]["id"])

Next steps