MemgraphAI

API Reference

REST API for storing memories, retrieving context, and debugging agent decisions. All endpoints accept API key auth via X-API-Key header.

Base URL

Cloud: https://api.memgraph.aiSelf-hosted: http://localhost:8001

Authentication

API Key (mg_*) via header or SDK. Dashboard uses JWT tokens.

Store MemoryRetrieve ContextManage BeliefsCognitive SidecarDecisionsEntities & GraphMemory QualityAccount & Keys

Store Memory

Two ways to store: beliefs (immediate, searchable) or events (async pipeline processing).

MethodPathDescriptionAuth
POST/v1/beliefsCreate a belief — immediately searchable with vector embeddingAPI Key
POST/v1/beliefs/batchBatch create up to 100 beliefs at onceAPI Key
POST/v1/eventsLog an event — processed async via Events → Episodes → Beliefs pipelineAPI Key
POST/v1/ingestIngest text or file (PDF, TXT) — auto-extracts beliefsAPI Key
POST/v1/documentsStore a document with embedding for knowledge baseAPI Key
POST/v1/documents/uploadUpload a file (PDF, TXT, Markdown)API Key
POST/v1/documents/linkScrape and ingest a URLAPI Key
bash
# Store a belief (immediate)
curl -X POST https://api.memgraph.ai/v1/beliefs \
  -H "X-API-Key: mg_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "subject_id": "alice",
    "key": "deployment_preference",
    "value": "Prefers Kubernetes over Docker Compose",
    "confidence": 0.95,
    "belief_type": "preference",
    "domain": "infrastructure"
  }'

Retrieve Context

Get relevant memories for your agent's prompt. v2/context is the recommended endpoint — it includes entities, decisions, and graph data alongside beliefs.

MethodPathDescriptionAuth
POST/v2/contextFull context retrieval — beliefs + entities + decisions + graph (recommended)API Key
POST/v1/contextBasic context retrieval — beliefs + episodes onlyAPI Key
bash
# Retrieve context (recommended — v2)
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
  }'

# Response includes:
# - results[] — scored beliefs and memories
# - entities[] — related entities
# - decisions[] — relevant past decisions
# - graph — entity relationship data

Manage Beliefs

MethodPathDescriptionAuth
GET/v1/beliefsList beliefs with pagination (?subject_id, ?domain, ?limit, ?cursor)API Key
GET/v1/beliefs/{subject_id}Get all beliefs for a user/subjectAPI Key
PUT/v1/beliefs/{belief_id}Update a belief (value, confidence, type, domain)API Key
DELETE/v1/beliefs/{belief_id}Delete a specific beliefAPI Key
DELETE/v1/beliefsBulk delete by subject + domain (soft or hard)API Key
GET/v1/beliefs/history/{subject_id}/{key}Version history for a specific belief keyAPI Key
GET/v1/beliefs/timeline/{subject_id}Chronological timeline of all belief changesAPI Key

Cognitive Sidecar

Auto-recall context before LLM calls and auto-learn from exchanges. See the Sidecar guide for SDK usage.

MethodPathDescriptionAuth
POST/v1/sidecar/pre-flightGet memory context to inject before your LLM callAPI Key
POST/v1/sidecar/post-flightExtract and store learnings from a message exchangeAPI Key
POST/v1/sidecar/processCombined pre-flight + post-flight in one callAPI Key
bash
# Pre-flight: inject memory into your prompt
curl -X POST https://api.memgraph.ai/v1/sidecar/pre-flight \
  -H "X-API-Key: mg_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "alice",
    "agent_id": "support-bot",
    "message": "How should I deploy to production?",
    "token_budget": 4000
  }'

# Post-flight: learn from the exchange
curl -X POST https://api.memgraph.ai/v1/sidecar/post-flight \
  -H "X-API-Key: mg_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "alice",
    "agent_id": "support-bot",
    "messages": [
      {"role": "user", "content": "I prefer Kubernetes"},
      {"role": "assistant", "content": "Noted, will recommend K8s"}
    ]
  }'

Decisions

Record, inspect, and debug agent reasoning traces. See the Decisions guide for patterns.

MethodPathDescriptionAuth
POST/v2/decisionsRecord a decision with goal, reasoning steps, tools, and outcomeAPI Key
POST/v2/decisions/synthesizeAuto-extract a decision from a message exchangeAPI Key
GET/v2/decisions/{id}Get a decision by IDAPI Key
GET/v2/decisions/{id}/explainFull debug view — beliefs, context snapshot, entity graphAPI Key
GET/v2/decisionsList decisions (?agent_id, ?user_id, ?outcome, ?limit)API Key
PATCH/v2/decisions/{id}/outcomeRecord outcome — auto-adjusts belief confidence (LTP/LTD)API Key
POST/v2/outcomes/recordPlatform-friendly outcome recordingAPI Key

Entities & Graph

Knowledge graph with named entities and temporal relationships.

MethodPathDescriptionAuth
POST/v2/entitiesCreate entity (person, org, product, place, concept, system, project)API Key
GET/v2/entitiesList entities (?entity_type, ?limit)API Key
POST/v2/entities/searchFuzzy + semantic entity searchAPI Key
DELETE/v2/entities/{id}Delete entity and its relationshipsAPI Key
POST/v2/relationshipsCreate relationship between entities (with temporal validity)API Key
GET/v2/relationshipsList relationships (?entity_id, ?relation_type)API Key
POST/v2/graph/traverseTraverse entity graph from seed nodes (max_depth, temporal_filter)API Key

Memory Quality

Monitor memory health, detect contradictions, and track agent reliability.

MethodPathDescriptionAuth
GET/v1/intelligence/healthMemory health — confidence stats, staleness, contradiction rateAPI Key
GET/v1/intelligence/contradictionsContradiction report with resolution historyAPI Key
GET/v1/intelligence/mcisMemgraph Cognitive Integrity Score (0-100 composite)API Key
POST/v1/intelligence/evaluateScore a retrieval query — detailed breakdown of all 5 signalsAPI Key
GET/v2/contradictionsList contradictions (?status=active)API Key
PATCH/v2/contradictions/{id}Resolve or dismiss a contradictionAPI Key
GET/v2/trust-score/{agent_id}Agent trust score — accuracy and track recordAPI Key
GET/v2/analyticsDecision analytics — success rate, outcome distributionAPI Key

Account & Keys

MethodPathDescriptionAuth
POST/v1/auth/onboardCreate account + tenant + API key in one callPublic
POST/v1/auth/loginLogin and get JWT tokenPublic
GET/v1/auth/meGet current user profileJWT
GET/v1/auth/whoamiResolve identity from API key or JWTKey/JWT
POST/v1/api-keysCreate new API keyJWT
GET/v1/api-keysList API keys (prefix only)JWT
DELETE/v1/api-keys/{key_id}Revoke an API keyJWT
GET/healthHealth check (DB + cache status)Public

Self-Hosting Endpoints

Additional endpoints useful when running your own instance.

MethodPathDescriptionAuth
POST/v1/dreaming/triggerManually trigger belief consolidation for pending episodesAPI Key
GET/v1/dreaming/healthCheck if the background dreaming worker is runningAPI Key
GET/v1/admin/exportExport all tenant data as JSON (GDPR-compliant)Admin
POST/v1/admin/importImport beliefs and events from JSON backupAdmin
GET/metricsPrometheus metrics endpointPublic

Full Example: Store + Retrieve + Decide

bash
# 1. Store a memory
curl -X POST https://api.memgraph.ai/v1/beliefs \
  -H "X-API-Key: mg_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "subject_id": "alice",
    "key": "deployment_preference",
    "value": "Prefers Kubernetes for production workloads",
    "confidence": 0.95,
    "belief_type": "preference"
  }'

# 2. Retrieve context for your agent
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 method does Alice prefer?",
    "user_id": "alice",
    "include_decisions": true
  }'

# 3. Record a decision
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",
    "confidence": 0.85,
    "outcome": "SUCCESS"
  }'

Error Codes

CodeMeaningWhat to do
400Bad requestCheck required fields and data types
401UnauthorizedCheck your API key or JWT token
404Not foundResource doesn't exist or wrong tenant
429Rate limitedWait and retry (120 req/min per tenant)
500Server errorRetry with backoff, check /health

All errors return { "detail": "error message" }. The SDK auto-retries on 429 and 5xx with exponential backoff.

Interactive docs: FastAPI auto-generates OpenAPI docs at /docs on your server (e.g., http://localhost:8001/docs) — useful for exploring all endpoints including internal ones.