Memory Types

Three pathways, one answer

When you retrieve a memory, Engramma doesn't use a single similarity metric. It evaluates your query through three independent pathways, then a Confidence Router selects the best result.

Think of it like asking three specialists the same question: one checks for exact matches, one looks at energy landscapes, and one uses attention across your memory space. The router picks the most confident answer.

The three pathways

Exact Pathway

Best for: Direct factual lookups, verbatim recall, high-precision queries.

The Exact pathway performs dense similarity matching. When your query closely matches a stored memory, this pathway fires with high confidence.

# Exact pathway example
client.store("The deployment runs on port 8080")

# This query is close to the stored text → Exact pathway
results = client.retrieve("What port does the deployment use?")
print(results[0].pathway)    # "exact"
print(results[0].confidence) # 0.92

Energy Pathway

Best for: Approximate matches, contextual understanding, broader associations.

The Energy pathway evaluates queries using free-energy minimization. It excels when the answer requires understanding context rather than matching specific words.

# Energy pathway example
client.store("Our infrastructure costs $2,400/month on AWS")

# Different phrasing, same meaning → Energy pathway
results = client.retrieve("How much do we spend on cloud hosting?")
print(results[0].pathway)    # "energy"
print(results[0].confidence) # 0.78

Attention Pathway

Best for: Multi-hop reasoning, connecting facts, complex queries that span multiple memories.

The Attention pathway uses multi-head attention to reason across your entire memory space. It can connect pieces of information that no single memory contains.

# Attention pathway example
client.store("Sarah leads the ML team")
client.store("The ML team is hiring 3 engineers")
client.store("Sarah's budget was approved last week")

# Requires connecting: Sarah → ML team → hiring + budget
results = client.retrieve("Can Sarah's team hire people now?")
print(results[0].pathway)    # "attention"
print(results[0].confidence) # 0.71

The Confidence Router

You never need to choose a pathway manually. The Confidence Router evaluates all three in parallel and selects the one with the highest confidence for each query.

{
  "results": [{
    "text": "The ML team is hiring 3 engineers",
    "confidence": 0.71,
    "pathway": "attention"
  }],
  "routing_details": {
    "exact_score": 0.42,
    "energy_score": 0.58,
    "attention_score": 0.71,
    "selected": "attention",
    "reason": "Multi-hop connection required"
  }
}

The router learns from usage patterns. If your application frequently triggers the Attention pathway, the router adapts its thresholds to optimize latency vs. accuracy for your workload.

When each pathway is selected

Pathway scores in results

Every result includes pathway information, even when you don't use the explain endpoint:

results = client.retrieve("What's our deployment schedule?")

for r in results:
    print(f"{r.text}")
    print(f"  Confidence: {r.confidence}")
    print(f"  Pathway: {r.pathway}")
    print(f"  ---")

# Output:
# "Deployments happen every Tuesday at 2pm"
#   Confidence: 0.89
#   Pathway: exact
#   ---
# "The release freeze is active during holiday weeks"
#   Confidence: 0.64
#   Pathway: energy
#   ---

Practical tips

• High confidence (> 0.85): Trust the result strongly — it's likely an exact or near-exact match
• Medium confidence (0.65-0.85): Good result, but consider showing multiple options to the user
• Low confidence (< 0.65): The engine is less sure — you may want to prompt the user for clarification
• Pathway = attention: The engine connected multiple facts — the reasoning chain in explain() will be especially useful here

Next steps

• Causal Reasoning — How memories form cause-effect relationships
• Explainability — Deep dive into confidence scores and reasoning chains
• How It Works — The full 10-phase cycle