decision_trace
Retrieves the complete trace of a decision envelope, including all events, policy evaluations, and data access. This method is self-access only (you can only retrieve traces for decisions created by your own agent).
Overview
The decision_trace method returns the complete audit trail of a decision, showing all operations that occurred within that decision envelope. This includes reads, writes, policy evaluations, approvals, and context events.
Request
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
decision_id | string | Yes | The decision ID to retrieve the trace for |
Example Request
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "decision_trace",
"arguments": {
"decision_id": "TMEM_abc123..."
}
}
}
Response
Success Response
The response contains a complete trace object with all events:
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [
{
"type": "text",
"text": "{\"decision_id\": \"TMEM_abc123...\", \"intent\": \"customer.order.create\", \"status\": \"committed\", \"events\": [...]}"
}
]
}
}
Response Structure
The trace includes:
- Decision metadata (intent, status, automation_mode, etc.)
- All events in chronological order:
- Read events (data access)
- Write events (data mutations)
- Policy evaluation events
- Approval request events
- Context events
- Decision close event
Example Trace Structure
{
"decision_id": "TMEM_abc123...",
"intent": "customer.order.create",
"status": "committed",
"created_at": "2026-01-07T12:00:00Z",
"closed_at": "2026-01-07T12:05:00Z",
"events": [
{
"event_id": "evt_001",
"type": "read",
"timestamp": "2026-01-07T12:00:05Z",
"product": "pg_customers_v1",
"purpose": "order_validation",
"data_ref": "ref:read:..."
},
{
"event_id": "evt_002",
"type": "evaluate",
"timestamp": "2026-01-07T12:00:10Z",
"policy_id": "order_validation_v1",
"outcome": "allow"
},
{
"event_id": "evt_003",
"type": "write",
"timestamp": "2026-01-07T12:00:15Z",
"product": "pg_orders_v1",
"purpose": "order_creation",
"mutation_summary": {...}
},
{
"event_id": "evt_004",
"type": "close",
"timestamp": "2026-01-07T12:05:00Z",
"action": "commit"
}
]
}
Error Cases
Missing Decision ID
Error Code: -32600 (Invalid Request)
{
"jsonrpc": "2.0",
"id": 1,
"error": {
"code": -32600,
"message": "Invalid Request",
"data": "decision_id is required"
}
}
Decision Not Found
Error Code: -32603 (Internal error)
{
"jsonrpc": "2.0",
"id": 1,
"error": {
"code": -32603,
"message": "Internal error",
"data": "Decision not found"
}
}
Permission Denied (Self-Access Only)
HTTP Status: 403 Forbidden
{
"jsonrpc": "2.0",
"id": 1,
"error": {
"code": -32603,
"message": "Internal error",
"data": "Access denied: can only retrieve traces for own decisions"
}
}
Note: You can only retrieve traces for decisions created by your own agent. This is a security feature to prevent agents from accessing each other's decision traces.
Authentication Errors
HTTP Status: 401 Unauthorized
Occurs when:
- API key is missing
- API key is invalid
- API key has been revoked
Usage Examples
Retrieve Complete Trace
import requests
import json
def get_decision_trace(decision_id, api_key):
response = requests.post('https://mcp.tracemem.com',
headers={'Authorization': f'Agent {api_key}'},
json={
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "decision_trace",
"arguments": {
"decision_id": decision_id
}
}
})
result = response.json()
trace_data = json.loads(result["result"]["content"][0]["text"])
return trace_data
# Get trace
trace = get_decision_trace("TMEM_abc123...", api_key)
# Analyze events
for event in trace["events"]:
print(f"{event['timestamp']}: {event['type']} - {event.get('product', 'N/A')}")
Audit Trail Analysis
def analyze_trace(trace):
"""Analyze a decision trace for audit purposes"""
analysis = {
"total_events": len(trace["events"]),
"reads": 0,
"writes": 0,
"policy_evaluations": 0,
"approvals": 0
}
for event in trace["events"]:
if event["type"] == "read":
analysis["reads"] += 1
elif event["type"] == "write":
analysis["writes"] += 1
elif event["type"] == "evaluate":
analysis["policy_evaluations"] += 1
elif event["type"] == "approval":
analysis["approvals"] += 1
return analysis
trace = get_decision_trace(decision_id, api_key)
analysis = analyze_trace(trace)
print(f"Decision processed {analysis['reads']} reads and {analysis['writes']} writes")
Best Practices
-
Use for debugging: Retrieve traces when debugging agent behavior or investigating issues
-
Audit compliance: Use traces for compliance audits and demonstrating decision-making processes
-
Performance analysis: Analyze traces to understand decision flow and identify bottlenecks
-
Security review: Review traces to ensure proper data access patterns and policy compliance
-
Store for records: Save important traces for long-term audit records
Important Notes
- Self-access only: You can only retrieve traces for decisions created by your own agent credentials
- Complete history: The trace includes all events from decision creation to closure
- Immutable: Traces are immutable once a decision is closed
- Data references: Read/write events may contain data references rather than full data for privacy
- Chronological order: Events are returned in chronological order
Related Methods
decision_create- Create a decision (starts the trace)decision_get- Get decision status (summary only)decision_receipt- Get cryptographic receipt (proof of decision)