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 full explainability at three levels of detail.

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

Three explanation levels

Simple

A one-sentence human-readable summary. Perfect for showing end users or logging.

explanation = client.explain(
    query="What's our cloud budget?",
    level="simple"
)

print(explanation.summary)
# "Matched via exact pathway with 91% confidence.
#  The stored memory closely matches your query about cloud spending."

Detailed

Includes pathway scores, the winning pathway, and a step-by-step reasoning chain. Great for developers debugging retrieval behavior.

explanation = client.explain(
    query="What's our cloud budget?",
    level="detailed"
)

print(explanation.summary)
print(explanation.pathway_scores)
print(explanation.reasoning_chain)
print(explanation.result_text)

Response:

{
  "summary": "High-confidence exact match. The query 'cloud budget' directly maps to a stored fact about AWS spending.",
  "pathway_scores": {
    "exact": 0.91,
    "energy": 0.67,
    "attention": 0.54
  },
  "reasoning_chain": [
    "Query encoded to 256-dim embedding",
    "Exact pathway: cosine similarity 0.91 with pattern pat_3f2a",
    "Energy pathway: free-energy score 0.67 (below exact threshold)",
    "Attention pathway: no multi-hop connections found (0.54)",
    "Router selected: exact (highest confidence at 0.91)",
    "Result: 'Our AWS infrastructure costs $2,400/month'"
  ],
  "result_text": "Our AWS infrastructure costs $2,400/month",
  "selected_pathway": "exact",
  "confidence": 0.91
}

Technical

Full internal details including feature contributions, pathway weights, routing decision factors, and memory access history. Useful for advanced debugging or compliance audits.

explanation = client.explain(
    query="What's our cloud budget?",
    level="technical"
)

print(explanation.summary)
print(explanation.feature_contributions)
print(explanation.routing_factors)
print(explanation.access_history)
print(explanation.consolidation_status)

Response:

{
  "summary": "High-confidence exact match via dense cosine similarity.",
  "pathway_scores": {
    "exact": 0.91,
    "energy": 0.67,
    "attention": 0.54
  },
  "feature_contributions": {
    "semantic_similarity": 0.82,
    "temporal_recency": 0.06,
    "access_frequency": 0.03,
    "causal_relevance": 0.00
  },
  "routing_factors": {
    "pathway_history_bias": 0.12,
    "confidence_gap": 0.24,
    "regime_state": "normal",
    "plasticity_gate": 0.7
  },
  "access_history": {
    "pattern_id": "pat_3f2a",
    "times_accessed": 14,
    "last_accessed": "2026-01-15T09:32:00Z",
    "importance_score": 0.84,
    "consolidation_cycles_survived": 3
  },
  "consolidation_status": {
    "protected": false,
    "decay_risk": "low",
    "last_strengthened": "2026-01-14T02:00:00Z"
  }
}

Using explanations in your application

Show users why the AI remembered something

# In a chatbot context
results = client.retrieve("What does the user like?")
explanation = client.explain(query="What does the user like?", level="simple")

# Show the user
response = f"""Based on our conversation history, I remember:

> {results[0].text}

💡 _{explanation.summary}_"""

print(response)
# Based on our conversation history, I remember:
#
# > You prefer concise answers and dark mode
#
# 💡 _Matched via exact pathway with 89% confidence.
#    This preference was stated directly in a previous conversation._

Debug low-confidence results

results = client.retrieve("quarterly revenue growth")

# Low confidence? Investigate.
if results[0].confidence < 0.7:
    explanation = client.explain(
        query="quarterly revenue growth",
        level="detailed"
    )
    
    print(f"Best pathway: {explanation.selected_pathway}")
    print(f"Scores: {explanation.pathway_scores}")
    print(f"Chain: {explanation.reasoning_chain}")
    
    # Now you know: was the query too vague?
    # Was there no relevant memory stored?
    # Did the attention pathway try and fail to connect facts?

Understanding confidence scores

Confidence vs. similarity

Important distinction: Confidence is not the same as cosine similarity.

• Cosine similarity = how geometrically close two vectors are (one pathway's raw score)
• Confidence = Engramma's overall assessment after evaluating all three pathways, access history, causal links, and regime state

A memory can have moderate cosine similarity (0.70) but high confidence (0.88) if:

• It was accessed frequently (reinforced through use)
• It has strong causal links to the query context
• The Attention pathway confirmed it via multi-hop reasoning

Explanation API at a glance

Next steps

• Memory Types — Understand the three pathways that explanations reference
• Regimes — How regime state affects confidence scoring
• API Reference — Full explain endpoint documentation