engramma-memory 0.1.0__tar.gz

engramma_memory-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,73 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest tests/ -v --cov=engramma_memory --cov-report=xml
+
+      - name: Upload coverage
+        if: matrix.python-version == '3.12'
+        uses: codecov/codecov-action@v4
+        with:
+          file: ./coverage.xml
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install ruff
+        run: pip install ruff
+
+      - name: Lint
+        run: ruff check engramma_memory/
+
+      - name: Format check
+        run: ruff format --check engramma_memory/
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: |
+          pip install -e ".[dev]"
+          pip install mypy numpy
+
+      - name: Type check
+        run: mypy engramma_memory/ --ignore-missing-imports

engramma_memory-0.1.0/.gitignore

@@ -0,0 +1,19 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.pytest_cache/
+.coverage
+htmlcov/
+.env
+.venv/
+venv/
+*.so
+.mypy_cache/
+.ruff_cache/
+site/
+.ipynb_checkpoints/

engramma_memory-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,16 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.4.4
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+        args: [--maxkb=500]

engramma_memory-0.1.0/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-07-06
+
+### Added
+
+- Initial public release of Engramma Memory SDK
+- Hybrid memory engine with three pathways:
+  - Exact kNN Memory with importance-based eviction
+  - Energy-based Memory (Modern Hopfield network)
+  - Multi-Head Attention Memory for native composition
+- Confidence-based routing between pathways
+- Local backend (in-process, zero dependencies beyond NumPy)
+- Cloud backend (production-grade, unlimited storage)
+- Framework integrations:
+  - LangChain (BaseMemory adapter)
+  - LlamaIndex (BaseRetriever adapter)
+  - OpenAI Assistants (tool definitions + handler)
+  - CrewAI (memory integration)
+  - FastAPI (router middleware)
+- Examples: quickstart, chatbot memory, RAG agent
+- Jupyter notebooks for interactive exploration
+- Full MkDocs documentation site
+- MIT License

engramma_memory-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,78 @@
+# Contributing to Engramma Memory
+
+Thank you for your interest in contributing! This guide will help you get started.
+
+## Development Setup
+
+```bash
+git clone https://github.com/engramma-ai/engramma-memory.git
+cd engramma-memory
+python -m venv .venv
+source .venv/bin/activate  # or .venv\Scripts\activate on Windows
+pip install -e ".[dev,docs]"
+```
+
+## Running Tests
+
+```bash
+pytest tests/ -v
+pytest tests/ -v --cov=engramma_memory  # with coverage
+```
+
+## Code Style
+
+We use [Ruff](https://docs.astral.sh/ruff/) for linting and formatting:
+
+```bash
+ruff check engramma_memory/
+ruff format engramma_memory/
+```
+
+## Type Checking
+
+```bash
+mypy engramma_memory/ --ignore-missing-imports
+```
+
+## Pull Request Process
+
+1. Fork the repository and create a feature branch from `main`.
+2. Write tests for any new functionality.
+3. Ensure all tests pass and code is formatted.
+4. Update documentation if your change affects the public API.
+5. Submit a PR with a clear description of what changed and why.
+
+## What We're Looking For
+
+- Bug fixes with regression tests
+- Performance improvements (with benchmarks)
+- New framework integrations
+- Documentation improvements
+- Examples and tutorials
+
+## Architecture Overview
+
+```
+engramma_memory/
+├── core.py          # Public API (EngrammaMemory class)
+├── engine.py        # Hybrid memory engine (Exact + Energy + Attention)
+├── backends/        # Local and Cloud backend implementations
+└── integrations/    # Framework adapters (LangChain, LlamaIndex, etc.)
+```
+
+The engine uses three pathways:
+- **ExactMemory** — kNN with importance-based eviction
+- **EnergyMemory** — Hopfield network with temperature-scaled softmax
+- **MultiHeadAttentionMemory** — Compositional retrieval via split-query attention
+
+## Reporting Issues
+
+Please use [GitHub Issues](https://github.com/engramma-ai/engramma-memory/issues) and include:
+- Python version
+- Engramma version (`engramma_memory.__version__`)
+- Minimal reproducible example
+- Expected vs actual behavior
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.

engramma_memory-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 engramma-ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

engramma_memory-0.1.0/PKG-INFO

@@ -0,0 +1,379 @@
+Metadata-Version: 2.4
+Name: engramma-memory
+Version: 0.1.0
+Summary: A composable memory engine for AI systems that learns, adapts, and reasons - not just retrieves.
+Project-URL: Homepage, https://www.engramma-memory.com
+Project-URL: Documentation, https://doc.engramma-memory.com
+Project-URL: Repository, https://github.com/engramma-ai/engramma-memory
+Project-URL: Issues, https://github.com/engramma-ai/engramma-memory/issues
+Author: Engramma Team
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,ai,composition,llm,memory,neural,retrieval
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Requires-Dist: numpy>=1.21.0
+Provides-Extra: all
+Requires-Dist: crewai>=0.1.0; extra == 'all'
+Requires-Dist: fastapi>=0.100.0; extra == 'all'
+Requires-Dist: httpx>=0.24.0; extra == 'all'
+Requires-Dist: langchain-core>=0.1.0; extra == 'all'
+Requires-Dist: llama-index-core>=0.10.0; extra == 'all'
+Requires-Dist: openai>=1.0.0; extra == 'all'
+Provides-Extra: cloud
+Requires-Dist: httpx>=0.24.0; extra == 'cloud'
+Provides-Extra: crewai
+Requires-Dist: crewai>=0.1.0; extra == 'crewai'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.0; extra == 'docs'
+Requires-Dist: pymdown-extensions>=10.0; extra == 'docs'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.100.0; extra == 'fastapi'
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.1.0; extra == 'langchain'
+Provides-Extra: llamaindex
+Requires-Dist: llama-index-core>=0.10.0; extra == 'llamaindex'
+Provides-Extra: openai
+Requires-Dist: openai>=1.0.0; extra == 'openai'
+Description-Content-Type: text/markdown
+
+<div align="center">
+  <!-- You can add a logo here: <img src="docs/assets/logo.png" alt="Engramma Logo" width="200"/> -->
+  <h1>🧠 Engramma Memory</h1>
+  <p><strong>The memory engine for AI that <em>thinks</em> — not just retrieves.</strong></p>
+  <p>Composition. Generalization. Causal reasoning. One <code>pip install</code> away.</p>
+
+  <p>
+    <a href="https://pypi.org/project/engramma-memory/"><img src="https://img.shields.io/pypi/v/engramma-memory?style=for-the-badge&color=5A67D8" alt="PyPI" /></a>
+    <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.9+-5A67D8?style=for-the-badge&logo=python&logoColor=white" alt="Python 3.9+" /></a>
+    <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green?style=for-the-badge" alt="License: MIT" /></a>
+    <a href="https://github.com/engramma-ai/engramma-memory/actions"><img src="https://img.shields.io/badge/tests-39%20passed-brightgreen?style=for-the-badge" alt="Tests" /></a>
+    <a href="https://doc.engramma-memory.com"><img src="https://img.shields.io/badge/docs-engramma--memory.dev-blue?style=for-the-badge" alt="Docs" /></a>
+  </p>
+
+  <h4>
+    <a href="#-quickstart">Get Started</a> &nbsp;&bull;&nbsp;
+    <a href="#-why-engramma">Why Engramma?</a> &nbsp;&bull;&nbsp;
+    <a href="#-how-it-works">Architecture</a> &nbsp;&bull;&nbsp;
+    <a href="#%E2%98%81%EF%B8%8F-engramma-cloud">Cloud</a> &nbsp;&bull;&nbsp;
+    <a href="https://doc.engramma-memory.com">Documentation</a>
+  </h4>
+</div>
+
+---
+
+> **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](#-the-problem)
+- [Quickstart](#-quickstart)
+- [Why Not Just Use a Vector DB?](#-why-not-just-use-a-vector-db)
+- [How It Works](#-how-it-works)
+- [Benchmarks](#-benchmarks)
+- [Integrations](#-integrations)
+- [Engramma Cloud](#%E2%98%81%EF%B8%8F-engramma-cloud)
+- [Contributing](#-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
+
+```bash
+pip install engramma-memory
+```
+
+### Basic Usage
+
+```python
+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
+```python
+# 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
+```python
+# Engramma — you get ONE fused answer
+blend = mem.compose([key_a, key_b])  
+# Each head specializes: some recall A, some recall B → coherent fusion
+```
+
+| Feature | Traditional Vector DBs | **Engramma** |
+|:---|:---:|:---:|
+| 🔍 Nearest-neighbor search | ✅ | ✅ |
+| 🧩 **Native composition** | ❌ | **✅** |
+| 🧠 Soft generalization (Hopfield)| ❌ | **✅** |
+| 🔀 Adaptive routing | ❌ | **✅** |
+| 📉 Importance-based eviction | ❌ | **✅** |
+| 🍂 Gradual forgetting | ❌ | **✅** |
+| 📦 Zero dependencies | ❌ | **✅** (numpy only) |
+
+---
+
+## 🏗️ How It Works
+
+Engramma uses a multi-pathway architecture to route queries intelligently based on the task.
+
+```mermaid
+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.
+
+| Task | Engramma | FAISS | ChromaDB | Raw kNN |
+|:---|:---:|:---:|:---:|:---:|
+| Exact recall @1000 | 100% | 100% | 100% | 100% |
+| **Composition (2-way)** | **81.4%** | 70.6% | 70.0% | 70.3% |
+| **Composition (3-way)** | **68.4%** | 56.6% | 57.0% | 55.9% |
+| **Continual learning** | **8.6%** | 1.1% | 1.1% | 1.1% |
+| Noisy retrieval (σ=0.3)| 70.0% | 70.5% | 72.0% | 62.5% |
+
+<details>
+<summary>⏱️ <strong>Latency & memory (honest tradeoffs)</strong></summary>
+
+| Metric | Engramma | FAISS | ChromaDB |
+|:---|:---:|:---:|:---:|
+| Latency p50 @1000 | 8.8ms | 0.02ms | 0.75ms |
+| Memory (MB/1000) | 3.14 | 0.72 | 0.46 |
+
+Engramma trades raw speed for composition capability. For pure nearest-neighbor at millions of vectors, use FAISS. For AI agents that need to *think* with their memory, use Engramma.
+</details>
+
+---
+
+## 🔌 Integrations
+
+Engramma drops right into your existing AI stack.
+
+<details open>
+<summary><strong>LangChain</strong></summary>
+
+```python
+from engramma_memory.integrations.langchain import EngrammaLangChainMemory
+
+memory = EngrammaLangChainMemory(dim=256, embed_fn=fn)
+```
+</details>
+
+<details>
+<summary><strong>LlamaIndex</strong></summary>
+
+```python
+from engramma_memory.integrations.llamaindex import EngrammaRetriever
+
+retriever = EngrammaRetriever(dim=256, embed_fn=fn)
+```
+</details>
+
+<details>
+<summary><strong>OpenAI Assistants</strong></summary>
+
+```python
+from engramma_memory.integrations.openai_assistants import engramma_tool_definitions
+
+tools = engramma_tool_definitions()
+```
+</details>
+
+<details>
+<summary><strong>FastAPI</strong></summary>
+
+```python
+from engramma_memory.integrations.fastapi import create_memory_router
+
+app.include_router(create_memory_router(dim=256))
+```
+</details>
+
+---
+
+## ☁️ Engramma Cloud
+
+### Same API. No limits. 43 premium capabilities.
+
+**One line to production:**
+
+```python
+# 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 →](https://www.engramma-memory.com/signup)**
+
+### What Cloud Unlocks
+
+| Feature | Local (free) | Cloud |
+|:---|:---:|:---:|
+| 🗃️ **Max patterns** | 1,000 | **Unlimited** |
+| 💾 **Storage** | RAM only | **Tiered (hot/warm/cold)** |
+| ⚖️ **Composition weights** | Equal only | **Custom fractional (0.0–1.0)** |
+| 🛡️ **Persistence** | None (in-process) | **Durable + snapshots** |
+| 🧠 **Routing** | Confidence-based | **Active Inference + phi_B** |
+| 🔗 **Causal reasoning** | — | **DAG discovery + interventions** |
+| 🚨 **Anomaly detection** | — | **3-regime safety system** |
+| 🔮 **Temporal prediction**| — | **Granger causality + prefetch** |
+| 💬 **Text interface** | — | **HDC tokenizer (no embeddings needed)** |
+| 🔬 **Explainability** | — | **Full XAI dashboard** |
+
+### Cloud Feature Highlights
+
+<details>
+<summary><strong>Causal Reasoning & Safety</strong></summary>
+
+```python
+# 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)
+```
+</details>
+
+<details>
+<summary><strong>Text Memory & Explainability</strong></summary>
+
+```python
+# 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: [...] }
+```
+</details>
+
+<details>
+<summary><strong>Async Support</strong></summary>
+
+For production async frameworks (FastAPI, etc.):
+```python
+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)
+```
+</details>
+
+---
+
+## 🤝 Contributing
+
+We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+
+```bash
+git clone https://github.com/engramma-ai/engramma-memory.git
+cd engramma-memory
+pip install -e ".[dev]"
+pytest  # 39 tests, all green
+```
+
+---
+
+<div align="center">
+  <h2>Ready for production?</h2>
+  <p><strong>Local is free forever.</strong> When you hit the wall — 1000 patterns, no persistence, no causal reasoning — Cloud is one line away.</p>
+  <a href="https://www.engramma-memory.com/signup"><img src="https://img.shields.io/badge/Start%20Free%20%E2%86%92-5A67D8?style=for-the-badge" alt="Start Free" /></a>
+  <br/><br/>
+  <p>
+    MIT License &bull; 
+    <a href="https://doc.engramma-memory.com">Documentation</a> &bull; 
+    <a href="https://github.com/engramma-ai/engramma-memory">GitHub</a> &bull; 
+    <a href="https://github.com/engramma-ai/engramma-memory/issues">Issues</a>
+  </p>
+</div>