How It Works

Understand Engramma's 10-phase cognitive cycle — from storing a memory to retrieving it with similarity scores and explanations.

The big picture

When you call /v1/memory/text/store or /v1/memory/text/recall, Engramma doesn't just save or search vectors. It runs a 10-phase cognitive cycle — a pipeline that encodes, routes, scores, strengthens, and explains your memories.

Think of it as the difference between a hard drive (stores bytes) and a brain (processes, connects, and reasons about information).

The 10-phase cycle

Here's what happens every time you interact with Engramma:

Neuromodulation

The engine assesses the current context — novelty, urgency, importance — and sets a plasticity gate that determines how strongly new information will be encoded. Visible via GET /v1/memory/neuromodulation/state.

Encoding

Your text is transformed into a 384-dimensional embedding using paraphrase-multilingual-MiniLM-L12-v2. For vector endpoints, you provide your own embeddings.

Regime Detection

The system monitors its own state: normal, high_surprise, anomaly, or recovery. Behavior adapts accordingly. Check via GET /v1/memory/regime.

Plasticity

Connection strengths between memories update using spike-timing rules — recent, frequently co-accessed memories form stronger bonds.

Storage & Indexing

The pattern is stored with its embedding, metadata, and importance score. Assigned a unique pattern_id (pat_...). Usage tracked against tenant limits.

Semantic Linking

New memories are linked to existing ones based on cosine similarity. Clusters form organically over time. Visible via GET /v1/memory/semantic/clusters.

Causal Discovery

The engine identifies potential cause-effect relationships between co-accessed patterns, building a causal graph queryable via /v1/memory/causal/* endpoints.

Temporal Tracking

Time-based patterns emerge — the engine notices sequences and predicts likely next queries via /v1/memory/temporal/predict.

Active Inference Retrieval

On recall, the engine applies Active Inference with semantic re-ranking by co-access patterns. This is what makes /text/recall superior to /text/retrieve over time.

Consolidation

During sleep cycles (/v1/memory/consolidation/sleep), weak memories are evicted, strong ones are strengthened, and duplicates merge — like biological memory during sleep.

What you observe as a user

You don't need to understand the internal phases to use Engramma. Here's what you actually see:

You do...	Engramma does...	You get...
POST `/text/store`	Phases 1-7 run	`pattern_id` + usage count
POST `/text/retrieve`	Cosine similarity search	Ranked results with `similarity` scores
POST `/text/recall`	Full Active Inference cycle	Higher-quality results with re-ranking
POST `/text/explain`	XAI analysis	Human-readable explanation + method + confidence
POST `/consolidation/sleep`	Phase 10 runs	Evicted/strengthened counts
GET `/text/stats`	Reads current state	Pattern count, embedding dim, storage bytes

A concrete example

Let's trace what happens when you store and retrieve a memory:

import requests, os

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

# Store three related facts
for text in [
    "Alice manages the backend team",
    "The backend team uses Python and Go",
    "Alice prefers async architectures"
]:
    requests.post(f"{API}/v1/memory/text/store", headers=HEADERS,
                  json={"text": text})

# Retrieve — cosine similarity search
resp = requests.post(f"{API}/v1/memory/text/retrieve", headers=HEADERS,
    json={"query": "What languages does Alice's team use?", "top_k": 3}
)
results = resp.json()["results"]
print(results[0]["text"])       # "The backend team uses Python and Go"
print(results[0]["similarity"]) # 0.87

# Recall — Active Inference (better at connecting related facts)
resp = requests.post(f"{API}/v1/memory/text/recall", headers=HEADERS,
    json={"query": "What languages does Alice's team use?", "top_k": 3}
)
recall = resp.json()["results"]
print(recall[0]["text"])        # "The backend team uses Python and Go"
print(recall[0]["similarity"])  # 0.91 (boosted by co-access patterns)

Notice how /text/recall can return higher similarity scores than /text/retrieve for the same query — it applies learned co-access patterns to boost results that are semantically related in context.

Latency

The full cycle completes in milliseconds:

Operation	Typical latency
Store (text)	3-8 ms
Retrieve (top 5)	2-5 ms
Recall (Active Inference)	5-12 ms
Explain	5-12 ms
Consolidation sleep	50-200 ms (background)

These numbers scale with your memory count. At 5,000 patterns (Free tier limit), retrieve stays under 5ms.

Two retrieval modes

	`/text/retrieve`	`/text/recall`
Method	Pure cosine similarity	Active Inference + semantic re-ranking
Speed	Fastest (2-5ms)	Slightly slower (5-12ms)
Accuracy	Good from day 1	Improves over time
Best for	Simple similarity search	Production-quality retrieval
When to use	Prototyping, exact matching	Chatbots, knowledge bases, assistants

What makes this different from embeddings + cosine search

A vector database embeds your text and searches by cosine similarity. That's one operation.

Engramma adds:

Active Inference retrieval — learned access patterns improve results over time
Causal links — memories don't exist in isolation, they form a queryable causal graph
Temporal awareness — the engine notices sequences and predicts next queries
Regime detection — the engine monitors its own state and adapts behavior
Consolidation — memory quality improves over time without re-indexing
Explainability — every retrieval can be explained with method and confidence

Next steps

Consolidation — How sleep cycles improve memory quality
Explainability — Understand confidence scores and reasoning
Quickstart — Try it yourself in 5 minutes