MemgraphAI

Decisions & Debugging

Record every agent decision, trace its reasoning, and improve outcomes over time. Decisions are the core object in Memgraph — everything links back to them.

What is a Decision?

A Decision captures the full reasoning trace of an agent action: what goal it was pursuing, what steps it took, which tools it called, which beliefs it relied on, and what the outcome was. This creates a complete audit trail for debugging and improvement.

goal

What the agent was trying to accomplish

reasoning_steps

Step-by-step thought process

tools_used

Tool calls with inputs and outputs

beliefs_used

Memory that informed the decision

confidence

Agent's confidence in the decision (0-1)

outcome

SUCCESS, FAILURE, PARTIAL, or REVERTED

The Debug Loop

Memgraph's core workflow for improving agent performance:

1
Run

Agent executes and decisions are recorded

2
Observe

Review decisions in Studio's 3-column debugger

3
Debug

Explain a decision — see beliefs, graph, context

4
Improve

Record outcomes, beliefs auto-adjust confidence

Record a Decision

python
from memgraph_sdk import MemgraphClient

client = MemgraphClient(api_key="mg_your_key")

decision = client.record_decision(
    goal="Find deployment options for the user",
    agent_id="support-agent",
    user_id="alice",
    reasoning_steps=[
        {"step": "Recall user context", "thought": "Check what we know about Alice"},
        {"step": "Search knowledge base", "thought": "Look for deployment docs"},
        {"step": "Formulate answer", "result": "Recommended Kubernetes based on history"},
    ],
    tools_used=[
        {"name": "memory_search", "input": "Alice deployment preferences", "output": "Prefers K8s"},
        {"name": "doc_search", "input": "deployment options", "output": "3 options found"},
    ],
    beliefs_used=["belief-uuid-1", "belief-uuid-2"],
    confidence=0.85,
    outcome="SUCCESS",
)

print(decision["id"])  # decision UUID

Auto-Synthesize from Conversation

Don't want to manually construct decision objects? Use synthesize to automatically extract a decision from a message exchange:

bash
curl -X POST https://api.memgraph.ai/v2/decisions/synthesize \
  -H "X-API-Key: mg_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "support-agent",
    "user_id": "alice",
    "messages": [
      {"role": "user", "content": "How should I deploy this?"},
      {"role": "assistant", "content": "Based on your history with Kubernetes..."}
    ]
  }'

Explain a Decision

The explain endpoint returns the full context that led to a decision — the beliefs that were active, the entity graph, and the context snapshot at decision time.

python
explanation = client.explain_decision("decision-uuid")

# Returns:
# {
#   "decision": { ... },           # Full decision record
#   "beliefs": [ ... ],            # Beliefs that were active when decision was made
#   "context_snapshot": { ... },   # Frozen state of context at decision time
#   "graph": {                     # Entity graph around the decision
#     "entities": [...],
#     "relationships": [...]
#   }
# }

Record Outcomes

When you learn whether a decision was correct, record the outcome. Memgraph automatically adjusts belief confidence — beliefs that led to failures get weakened, beliefs behind successes get strengthened (LTP/LTD).

bash
# Update decision outcome via REST API
curl -X PATCH https://api.memgraph.ai/v2/decisions/DECISION_UUID/outcome \
  -H "X-API-Key: mg_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "outcome": "FAILURE",
    "outcome_assessment": "User reported the deployment failed on ARM nodes"
  }'

# Or record outcome separately
curl -X POST https://api.memgraph.ai/v2/outcomes/record \
  -H "X-API-Key: mg_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "decision_id": "DECISION_UUID",
    "outcome": "SUCCESS",
    "assessment": "Deployment succeeded, user confirmed",
    "source": "user_feedback"
  }'

Automatic confidence adjustment: When an outcome is recorded, Memgraph traces back to the beliefs that informed the decision. Successful outcomes strengthen belief confidence (LTP), while failures weaken it (LTD). Over time, your agent's memory self-corrects.

Decision Analytics

Track agent performance across all decisions:

python
analytics = client.analytics()
# {
#   "total_decisions": 142,
#   "success_rate": 0.78,
#   "outcome_distribution": {"SUCCESS": 111, "FAILURE": 18, "PARTIAL": 13},
#   "contradiction_rate": 0.05,
#   "avg_confidence": 0.82,
# }

# Filter decisions by outcome to analyze failure patterns
failures = client.list_decisions(agent_id="support-agent", outcome="FAILURE")
for d in failures:
    print(f"Goal: {d['goal']}, Confidence: {d.get('confidence')}")

Studio Decision Debugger

The Studio dashboard includes a visual Decision Debugger with a 3-column layout:

Decision List

Browse all decisions with outcome badges, confidence scores, and timestamps. Filter by agent, user, or outcome.

Decision Detail

Inspect reasoning steps, tool calls with inputs/outputs, beliefs referenced, and the goal. See the full chain of thought.

Context Panel

View the context snapshot, entity graph, and suggestions for improvement. See exactly what the agent knew at decision time.

Next steps