Engramma

Explainability (XAI)

advanced

Explain retrievals, get layered explanations, surprise analysis, head weights, and routing decisions.

Explain retrieval

POST/v1/memory/xai/explain

Explain a retrieval: pathway, surprise, regime, head contributions.

queryarray[number]required

Query embedding.

resultarray[number]required

Result embedding.

200Response
{
  "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
  }
}

Layered explanation

POST/v1/memory/xai/explain/layered

Layered XAI explanation — simple/detailed/technical. Level auto-selected based on tenant tier if not specified.

queryarray[number]required

Query embedding.

resultarray[number]required

Result embedding.

levelstring | null

Explanation level: simple, detailed, or technical. Auto-selected if omitted.

langstring | null

Language: fr or en. Auto-detected if omitted.

200Response
{
  "level": "detailed",
  "explanation": "The memory was retrieved via the energy pathway because...",
  "technical_details": {
    "pathway_scores": {
      "exact": 0.23,
      "energy": 0.89
    },
    "surprise": 0.34
  }
}

XAI report

GET/v1/memory/xai/report

Get comprehensive XAI report combining all observability data.

200Response
{
  "surprise_analysis": {
    "current": 0.34,
    "mean": 0.28,
    "trend": "stable"
  },
  "regime_analysis": {
    "current": "normal",
    "transitions": 3
  },
  "routing_analysis": {
    "dominant_pathway": "energy",
    "distribution": {
      "exact": 0.2,
      "energy": 0.6,
      "attention": 0.2
    }
  },
  "head_evolution": {
    "weights": [
      0.4,
      0.35,
      0.25
    ],
    "stability": 0.92
  }
}

Surprise analysis

GET/v1/memory/xai/surprise

Get surprise trajectory analysis.

windowintegerDefault: 50

Number of recent operations to analyze.

200Response
{
  "current": 0.34,
  "mean": 0.28,
  "std": 0.12,
  "min": 0.05,
  "max": 0.89,
  "trend": "stable",
  "trajectory": [
    0.23,
    0.28,
    0.31,
    0.34
  ]
}

Head weights

GET/v1/memory/xai/heads

Get head weight evolution over time.

last_nintegerDefault: 50

Number of recent snapshots.

200Response
{
  "current_weights": [
    0.4,
    0.35,
    0.25
  ],
  "history": [
    [
      0.38,
      0.36,
      0.26
    ],
    [
      0.39,
      0.35,
      0.26
    ],
    [
      0.4,
      0.35,
      0.25
    ]
  ]
}

Routing distribution

GET/v1/memory/xai/routing

Get routing decision distribution.

windowintegerDefault: 100

Number of recent decisions to analyze.

200Response
{
  "distribution": {
    "exact": 0.2,
    "energy": 0.6,
    "attention": 0.2
  },
  "total_decisions": 100
}

Next steps

HDCRegime