Retrieval Modes

Two modes, different strengths

When you query your memories, Engramma offers two retrieval endpoints with fundamentally different approaches:

Retrieve: cosine similarity

The simplest retrieval mode. Your query is embedded and compared against all stored patterns using cosine similarity. Results are ranked by geometric distance in embedding space.

import requests, os

API = "https://api.engramma-memory.com"
HEADERS = {
    "X-API-Key": os.environ["ENGRAMMA_API_KEY"],
    "Content-Type": "application/json"
}

resp = requests.post(f"{API}/v1/memory/text/retrieve", headers=HEADERS, json={
    "query": "What port does the deployment use?",
    "top_k": 5
})
for r in resp.json()["results"]:
    print(f"[{r['similarity']:.2f}] {r['text']}")

Response:

{
  "results": [
    {
      "text": "The deployment runs on port 8080",
      "metadata": {"category": "ops"},
      "similarity": 0.92,
      "pattern_id": "pat_a7f2c1"
    }
  ],
  "latency_ms": 2.3
}

Recall: Active Inference

The intelligent retrieval mode. Uses the same cosine similarity as a starting point, but then applies Active Inference with semantic re-ranking based on co-access patterns. Results improve as the engine learns which patterns are accessed together.

resp = requests.post(f"{API}/v1/memory/text/recall", headers=HEADERS, json={
    "query": "What port does the deployment use?",
    "top_k": 5
})
for r in resp.json()["results"]:
    print(f"[{r['similarity']:.2f}] {r['text']}")

Response:

{
  "results": [
    {
      "text": "The deployment runs on port 8080",
      "metadata": {"category": "ops"},
      "similarity": 0.96,
      "pattern_id": "pat_a7f2c1"
    }
  ],
  "info": {},
  "latency_ms": 8.1
}

When to use which

Understanding similarity scores

Both endpoints return a similarity score between 0 and 1:

The XAI layer: explaining results

For any retrieval, you can get a human-readable explanation via /v1/memory/text/explain:

resp = requests.post(f"{API}/v1/memory/text/explain", headers=HEADERS, json={
    "query": "What port does the deployment use?"
})
expl = resp.json()
print(f"Method: {expl['method']}")
print(f"Confidence: {expl['confidence']}")
print(f"Explanation: {expl['explanation']}")

Response:

{
  "explanation": "High-confidence match (0.92) via cosine similarity. The stored fact 'The deployment runs on port 8080' directly answers the query.",
  "method": "cosine_similarity",
  "confidence": 0.92
}

Advanced XAI endpoints

For deeper introspection, Engramma provides dedicated XAI endpoints that work at the embedding level:

These endpoints accept raw embeddings and provide detailed internal analysis — useful for debugging or compliance audits.

How recall improves over time

The Active Inference engine learns from how you use it:

1. Day 1 — Recall results are similar to retrieve (no history yet)
2. Week 1 — The engine notices which patterns are accessed together after the same queries
3. Week 2 — Co-access patterns start boosting related results
4. Month 1 — The engine can surface relevant results that pure cosine similarity would miss

This improvement happens automatically. Consolidation cycles (/v1/memory/consolidation/sleep) accelerate the process by reinforcing frequently-validated access patterns.

Practical tips

• Start with recall for production — even on day 1 it returns at least as good as retrieve
• Use retrieve for testing — deterministic cosine similarity makes debugging easier
• Check similarity > 0.7 before showing results to users
• Use /text/explain when you need to understand why a result was returned
• Run consolidation periodically to accelerate the learning process

Next steps

• Causal Reasoning — How memories form cause-effect relationships
• Explainability — Deep dive into XAI endpoints
• How It Works — The full 10-phase cycle