Engramma

Your First Memory

beginner

Store, retrieve, and explain your first memory in under 5 minutes. A complete Hello World for Engramma.

What you'll build

A working script that stores a fact, retrieves it with similarity scoring, and explains why it was returned — in 12 lines of code.

Prerequisites

RequirementDetails
AccountFree tier or above (sign up)
API keyGenerate one in your dashboard
Time~5 minutes

Steps

1

Set your API key

Export your key as an environment variable.
2

Store a memory

Save a fact to your memory space. The engine embeds, indexes, and stores it automatically.
3

Retrieve it

Ask a natural-language question. The engine finds the best match via cosine similarity.
4

Recall with Active Inference

Use /text/recall for intelligent retrieval with semantic re-ranking.
5

Explain the result

Ask why that result was returned. Get a human-readable explanation with method and confidence.

Complete code

import requests, os

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

# Step 1: Store a memory
resp = requests.post(f"{API}/v1/memory/text/store", headers=HEADERS, json={
    "text": "The deployment window is Tuesday 2-4pm UTC"
})
result = resp.json()
print(f"Stored! Pattern ID: {result['pattern_id']}")
print(f"Usage: {result['patterns_used']}/{result['patterns_limit']}")

# Step 2: Retrieve it with a natural question
resp = requests.post(f"{API}/v1/memory/text/retrieve", headers=HEADERS, json={
    "query": "When can we deploy?",
    "top_k": 3
})
results = resp.json()["results"]
print(f"Answer: {results[0]['text']}")
print(f"Similarity: {results[0]['similarity']}")

# Step 3: Recall with Active Inference (smarter retrieval)
resp = requests.post(f"{API}/v1/memory/text/recall", headers=HEADERS, json={
    "query": "When can we deploy?",
    "top_k": 3
})
recall_results = resp.json()["results"]
print(f"Recall: {recall_results[0]['text']}")
print(f"Similarity: {recall_results[0]['similarity']}")

# Step 4: Explain why this result was returned
resp = requests.post(f"{API}/v1/memory/text/explain", headers=HEADERS, json={
    "query": "When can we deploy?"
})
explanation = resp.json()
print(f"Method: {explanation['method']}")
print(f"Confidence: {explanation['confidence']}")
print(f"Explanation: {explanation['explanation']}")

Expected output

Stored! Pattern ID: pat_7f3a2b
Usage: 42/5000
Answer: The deployment window is Tuesday 2-4pm UTC
Similarity: 0.94
Recall: The deployment window is Tuesday 2-4pm UTC
Similarity: 0.96
Method: cosine_similarity
Confidence: 0.94
Explanation: High-confidence match (0.94) via cosine similarity. The stored fact 'The deployment window is Tuesday 2-4pm UTC' directly answers the query. Stored 5 days ago, accessed 12 times.

What just happened

  1. Store — The engine embedded your text using paraphrase-multilingual-MiniLM-L12-v2 (384 dimensions), assessed importance, and indexed it.

  2. Retrieve — Your question was embedded and matched against stored patterns via cosine similarity. The response includes a similarity score (0-1).

  3. Recall — The Active Inference retrieval cycle ran, applying semantic re-ranking based on co-access patterns. Returns higher-quality results after the memory space has been used for a while.

  4. Explain — The engine described the retrieval method, confidence score, and reasoning in human-readable text.

Tip

/text/retrieve uses pure cosine similarity — fast and predictable. /text/recall adds Active Inference re-ranking — better results over time as the engine learns access patterns.

Next steps

RegimesBuilding a Chatbot