Explainability

Understand every result

When Engramma returns a memory, you can always ask why. Unlike black-box systems that return a similarity score with no context, Engramma provides explainability at two layers:

1. Text Explanation — a simple, human-readable answer for end users and logs
2. Advanced XAI — raw pathway diagnostics, attention head weights, and surprise scores for debugging and compliance

This matters for:

• Debugging — understanding why the wrong result was returned
• Trust — showing users why the AI "remembered" something
• Compliance — enterprise requirements for explainable AI decisions

Layer 1: Text Explanation

The simplest way to understand a retrieval result. Send a natural-language query and get back a human-readable explanation with a confidence score.

Endpoint: POST /v1/memory/text/explain

import requests

response = requests.post(
    "https://api.engramma.ai/v1/memory/text/explain",
    headers={"X-API-Key": "your-api-key"},
    json={
        "query": "What's our cloud budget?",
        "lang": "en"
    }
)

data = response.json()
print(data["explanation"])
print(data["method"])
print(data["confidence"])

Response:

{
  "explanation": "The stored memory about AWS infrastructure costs closely matches your query about cloud spending. The match was found through direct semantic similarity between the query and the stored fact.",
  "method": "cosine_similarity",
  "confidence": 0.94
}

Request body

Response fields

Understanding confidence scores

The confidence value from the text explanation endpoint tells you how strongly the query matched stored memories.

Layer 2: Advanced XAI

The XAI layer works with raw embeddings, not text. It exposes the internal routing machinery: which pathway was chosen, how attention heads contributed, and how surprising the match was. Use this for:

• Deep debugging of unexpected retrieval behavior
• Compliance audits that need internal decision traces
• Understanding the routing engine's pathway selection

Explain a query/result pair

Endpoint: POST /v1/memory/xai/explain

Send the raw embeddings of a query and result to see the full routing decision.

import requests

# query_embedding and result_embedding are vectors
# obtained from your retrieval pipeline
response = requests.post(
    "https://api.engramma.ai/v1/memory/xai/explain",
    headers={"X-API-Key": "your-api-key"},
    json={
        "query": query_embedding,
        "result": result_embedding
    }
)

data = response.json()
print(f"Pathway chosen: {data['pathway_chosen']}")
print(f"Pathway scores: {data['pathway_scores']}")
print(f"Surprise: {data['surprise']}")
print(f"Regime: {data['regime']}")
print(f"Head contributions: {data['head_contributions']}")
print(f"Neuromodulation: {data['neuromodulation']}")
print(f"Phi-B validation: {data['phi_b_validation']}")

Response:

{
  "pathway_chosen": "energy",
  "pathway_scores": {
    "exact": 0.23,
    "energy": 0.89,
    "attention": 0.45
  },
  "surprise": 0.34,
  "regime": "normal",
  "head_contributions": [0.4, 0.35, 0.25],
  "neuromodulation": {
    "signal": 0.67,
    "gate": 0.82
  },
  "phi_b_validation": {
    "geometric_surprise": 0.12,
    "valid": true
  }
}

XAI response fields

Layered explanations

Endpoint: POST /v1/memory/xai/explain/layered

Get the XAI explanation formatted at a chosen detail level.

import requests

response = requests.post(
    "https://api.engramma.ai/v1/memory/xai/explain/layered",
    headers={"X-API-Key": "your-api-key"},
    json={
        "query": query_embedding,
        "result": result_embedding,
        "level": "detailed"
    }
)

print(response.json())

Additional XAI endpoints

response = requests.post(
    "https://api.engramma.ai/v1/memory/xai/surprise",
    headers={"X-API-Key": "your-api-key"},
    json={
        "query": query_embedding,
        "result": result_embedding
    }
)
print(response.json())

When to use which layer

Key concept: Pathways live in XAI

An important architectural distinction: the pathway concept (exact, energy, attention) only exists in the XAI layer. The text-level endpoints (/text/explain, /text/retrieve, /text/recall) do not expose pathway information — they give you a confidence score and a human-readable explanation.

If you need to know which pathway was used, you must call the XAI layer with the raw embeddings.

Next steps

• Memory Types — Understand the three pathways that XAI diagnostics reference
• Regimes — How regime state affects routing and confidence
• API Reference — Full endpoint documentation