Vector databases retrieve. Engramma composes. Your agent asks: "What do you know about Python AND machine learning?" ChromaDB returns two separate results. Engramma returns one fused answer.

📖 Table of Contents

• The Problem
• Quickstart
• Why Not Just Use a Vector DB?
• How It Works
• Benchmarks
• Integrations
• Engramma Cloud
• Contributing

🚩 The Problem

Every AI memory system today is just retrieval — find the nearest vector, return it. That's a search engine, not a memory. Real memory does more:

• 🧩 Composes — "What's the intersection of X and Y?" → a single coherent answer
• 🧠 Generalizes — noisy input still triggers the right pattern
• 📈 Adapts — frequently accessed patterns become stronger
• 🗑️ Forgets — outdated patterns decay naturally

Engramma does all four. In 3 lines of code.

⚡ Quickstart

Installation

pip install engramma-memory

Basic Usage

import numpy as np
from engramma_memory import EngrammaMemory

# Initialize local, purely in-memory engine
mem = EngrammaMemory(dim=256, backend="local")

# Store knowledge
mem.store(key=embedding_a, value="Python is a programming language")
mem.store(key=embedding_b, value="Machine learning uses data to learn")

# Retrieve — smart routing across 3 pathways
result = mem.retrieve(query_embedding)

# Compose — the killer feature ⚡
blend = mem.compose([embedding_a, embedding_b])  
# Native multi-head attention fusion returns a coherent response

[!NOTE] That's it. No config files. No Docker. No API keys. Just numpy.

🆚 Why Not Just Use a Vector DB?

When combining concepts using traditional vector databases, you are forced to retrieve multiple results and manually piece them together. Engramma solves this with native composition.

The Vector DB Way

# ChromaDB / Pinecone / FAISS — you get TWO separate results
result_a = db.query(key_a)  # "Python is a language..."
result_b = db.query(key_b)  # "ML uses data to learn..."

# Now what? Average them? Concatenate? Pray?
blend = (result_a + result_b) / 2  # Meaningless arithmetic

The Engramma Way

# Engramma — you get ONE fused answer
blend = mem.compose([key_a, key_b])  
# Each head specializes: some recall A, some recall B → coherent fusion

🏗️ How It Works

Engramma uses a multi-pathway architecture to route queries intelligently based on the task.

graph TD
    Q[Query] --> Exact[Exact kNN Memory]
    Q --> Energy[Energy Hopfield]
    Q --> MHA[Multi-Head Attention]
    
    Exact --> Router[Confidence Router<br/>learned weights]
    Energy --> Router
    MHA --> Router
    
    Router --> Best[Best Result]

• Exact Memory — perfect recall via kNN with importance scoring
• Energy Memory — soft generalization via temperature-scaled Hopfield dynamics
• Multi-Head Attention — each head attends to different patterns → native composition
• Confidence Router — learns which pathway handles which query type

[!TIP] All learning is local (Hebbian). No backpropagation. No GPU required. Pure NumPy.

📊 Benchmarks

Engramma trades a tiny bit of raw speed for massive gains in composition capability.

🔌 Integrations

Engramma drops right into your existing AI stack.

from engramma_memory.integrations.langchain import EngrammaLangChainMemory

memory = EngrammaLangChainMemory(dim=256, embed_fn=fn)

from engramma_memory.integrations.llamaindex import EngrammaRetriever

retriever = EngrammaRetriever(dim=256, embed_fn=fn)

from engramma_memory.integrations.openai_assistants import engramma_tool_definitions

tools = engramma_tool_definitions()

from engramma_memory.integrations.fastapi import create_memory_router

app.include_router(create_memory_router(dim=256))

☁️ Engramma Cloud

Same API. No limits. 43 premium capabilities.

One line to production:

# Local (free, open source, limited to 1000 patterns)
mem = EngrammaMemory(dim=256, backend="local")

# Cloud (unlimited, persistent, intelligent) — same code, one line change!
mem = EngrammaMemory(dim=256, backend="cloud", api_key="nx_live_...")

[!IMPORTANT] Get Your Free API Key →

What Cloud Unlocks

Cloud Feature Highlights

# Discover causal structure
graph = mem.get_causal_graph()

# "If I change A, what happens to B?"
effect = mem.predict_causal_effect(cause_key=a, effect_key=b)

# Fractional composition (not just 50/50)
blend = mem.compose_fractional(a, b, alpha=0.7)

# Auto-block risky OOD compositions
mem.enable_anomaly_protection(enabled=True)

# Store with natural language (no embeddings needed!)
mem.store_text("User prefers Python over JS")

# Query with natural language
results = mem.query_text("what language does the user prefer?")

# Understand WHY a result was returned
explanation = mem.explain(query)
# { pathway: "attention", confidence: ..., attention_map: [...] }

from engramma_memory import EngrammaMemoryAsync

async with EngrammaMemoryAsync(dim=256, backend="cloud", api_key="...") as mem:
    await mem.store(key=embedding, value=data)
    results = await mem.query(embedding, top_k=5)

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for details.

git clone https://github.com/engramma-ai/engramma-memory.git
cd engramma-memory
pip install -e ".[dev]"
pytest  # 39 tests, all green

Ready for production?

Local is free forever. When you hit the wall — 1000 patterns, no persistence, no causal reasoning — Cloud is one line away.

MIT License • Documentation • GitHub • Issues