Metadata-Version: 2.4
Name: engram-engine
Version: 0.1.0
Summary: O(1) memory for infinite context — drop-in Transformer replacement with holographic toroidal attention
Author-email: Justin Arndt <justinarndt05@gmail.com>
License: Research & Academic Use
Project-URL: Homepage, https://github.com/justinarndt/Engram
Project-URL: Repository, https://github.com/justinarndt/Engram
Project-URL: Issues, https://github.com/justinarndt/Engram/issues
Keywords: holographic-memory,toroidal-attention,engram,swarm-intelligence,llm,infinite-context
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: torch>=2.0
Requires-Dist: typer>=0.9
Requires-Dist: rich>=13.0
Requires-Dist: safetensors>=0.4
Requires-Dist: matplotlib>=3.5
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Provides-Extra: server
Requires-Dist: fastapi>=0.100; extra == "server"
Requires-Dist: uvicorn>=0.20; extra == "server"
Provides-Extra: hf
Requires-Dist: transformers>=4.30; extra == "hf"
Provides-Extra: all
Requires-Dist: fastapi>=0.100; extra == "all"
Requires-Dist: uvicorn>=0.20; extra == "all"
Requires-Dist: transformers>=4.30; extra == "all"
Dynamic: license-file

<div align="center">

# 🧠 Engram

### Persistent Systolic Continuous State Engine
**O(1) Memory for Infinite Context — Drop-In Transformer Replacement**

*Stop passing tokens. Start sharing consciousness.*

[![License: Research Use](https://img.shields.io/badge/License-Research%20%26%20Academic%20Use-blue.svg)](LICENSE.md)
[![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-3776ab.svg)](https://python.org)
[![PyTorch 2.0+](https://img.shields.io/badge/PyTorch-2.0%2B-ee4c2c.svg)](https://pytorch.org)
[![Patent Pending](https://img.shields.io/badge/Patent-63%2F989%2C566-red.svg)](#patent-notice)

</div>

---

## The Problem

Every LLM today is trapped behind two walls:

1. **The Memory Wall.** A 1M-token context requires $O(N)$ KV-Cache memory. A single H100 allocates 40+ GB of VRAM just to remember a conversation. At 500K tokens, it crashes.

2. **The Forgetting Wall.** State-space models (Mamba, RWKV) compress context to $O(1)$, but they can't recall a specific API key buried 100K tokens deep. They forget.

**Engram solves both.** It replaces sparse Attention with a dual-memory architecture inspired by the 2D bivariate torus topology used in Quantum Error Correction:

| Component | Role | Behavior |
|:--|:--|:--|
| **Liquid Torus** | Working memory | $O(1)$ IIR fluid state — handles syntax and recent context |
| **Crystalline Engram** | Long-term memory | $O(1)$ Hebbian weight matrix — permanently etches facts |
| **Holographic Recall** | Retrieval | Resonance query — only matching memories amplify |

The result: **0.83 recall at 10K tokens on 1 MB of fixed memory.** No KV cache. No vector database. No forgetting.

---

## Benchmarks (RTX 4060 8GB)

### Needle-in-a-Haystack: 10,000-Token Recall

| Memory Architecture | Recall @ 10K | Memory | Scaling |
|:--|:--|:--|:--|
| Standard Attention (KV Cache) | 1.000 | **10,001 KB** | 💥 $O(N)$ — OOM |
| Liquid Torus Only (SSM) | ~0.000 | **4 KB** | $O(1)$ — amnesia |
| **Engram Systolic Engram** | **> 0.83** | **1,028 KB** | 🚀 **$O(1)$ — permanent** |

*10x less memory at 10K tokens. 10,000x less at 1M tokens. The model learns the document the first time it reads it.*

![Needle Recall Benchmark](plots/needle_recall.png)

### The Von Neumann Memory Wall

A standard transformer's KV cache **crashes a $40,000 H100** at 500K tokens.
Engram runs to **1,000,000+ tokens** on an **$800 laptop GPU** at constant 0.2 GB.

![Memory Wall Benchmark](plots/memory_wall.png)

---

## Architecture

![Engram Architecture](plots/architecture_v2.png)

**How it works:**

1. **Liquid Torus (Working Memory):** Tokens are spatially convoluted across a fixed $O(1)$ 2D toroidal grid via systolic shift kernels. Immediate syntactic context is maintained through IIR temporal inertia. Memory never grows.

2. **Systolic Engram (Long-Term Memory):** As tokens flow through the torus, a continuous Hebbian outer product *etches* their high-dimensional signature into a fixed-size weight matrix. Top-K sparse orthogonalization (10% peaks) + Oja's leaky decay prevent crosstalk.

3. **Holographic Resonance (Recall):** The query torus state acts as a holographic laser. Due to high-dimensional orthogonality, irrelevant tokens destructively cancel. Only the matching memory constructively resonates.

4. **Reward-Modulated Etching:** The Hebbian update is scaled by a reward signal — enabling zero-shot forward-pass RL without backpropagation:
   ```
   W_engram += (reward × η) · (token ⊗ sparse_torus_state)
   ```

---

## Quick Start

```bash
pip install engram
```

Or from source:

```bash
git clone https://github.com/justinarndt/Engram.git
cd Engram
pip install -e .          # Core + CLI
pip install -e ".[all]"   # + FastAPI server + HuggingFace
```

```bash
engram --help
engram info                        # Architecture & memory report

# Demos
engram run swarm                   # Multi-agent weight sharing
engram run kung-fu                 # Zero-shot skill transfer
engram run lobotomy                # Transformer attention replacement
engram run cartridge               # Knowledge Cartridge save/load
engram run recall                  # Needle-in-a-haystack benchmark
engram run memory-wall             # The OOM benchmark

# Knowledge Cartridges
engram save my_codebase.cart        # Save engram to portable file
engram inspect my_codebase.cart     # View metadata
engram inject my_codebase.cart      # Load on any machine, <1ms

# OpenAI-compatible server
engram serve                        # Launch on port 8000
```

### Docker Compose (Instant UI)

Get a full ChatGPT-like interface backed by the Engram engine:

```bash
docker compose up -d
# Open http://localhost:3000 for the chat UI
# Open http://localhost:8000/docs for the API docs
```

This spins up the FastAPI backend + [Open-WebUI](https://github.com/open-webui/open-webui) frontend. All chat sessions share a single Engram matrix in memory.

### Use in 5 Lines

```python
from engram import HolographicLM
import torch

model = HolographicLM().cuda()
input_ids = torch.randint(0, 50257, (1, 512)).cuda()
output = model(input_ids)
print(f"Logits: {output['logits'].shape}")  # [1, 512, 50257]
```

### HuggingFace Integration

```python
from engram import AutoHolographicModel, HolographicConfig

config = HolographicConfig(d_model=512, n_layers=6)
model = AutoHolographicModel(config).cuda()

# Standard HF interface — works with Trainer, pipeline, etc.
outputs = model(input_ids=ids, labels=labels)
print(outputs.logits.shape)       # [B, T, 50257]
print(outputs.loss)               # Cross-entropy loss
print(outputs.past_key_values)    # None — no KV cache
```

### Swarm-Chat Server

```bash
engram serve --port 8000

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "engram-hive", "messages": [{"role": "user", "content": "Hello"}]}'

curl http://localhost:8000/v1/engram/status
```

### Systolic Engram in 10 Lines

```python
from engram import SystolicEngramCache

engram = SystolicEngramCache(d_model=512, channels=8, grid_l=64, grid_m=64).cuda()
print(engram)  # O(1) memory breakdown

token_emb = torch.randn(1, 8 * 64 * 64, device="cuda")
output = engram(token_emb, reward=1.0)

# output["liquid"]   — fluid working memory (syntax)
# output["engram"]   — crystalline fact recall (permanent)
# output["combined"] — the full readout
```

---

## What Engram Enables

### Multi-Agent Weight Sharing

Standard multi-agent systems (AutoGen, CrewAI) share knowledge by serializing state to JSON strings and injecting them into each other's prompts. This blows up context limits.

Engram agents **share the exact same Engram matrix in VRAM**. Agent A etches a fact, Agent B recalls it via tensor resonance. Zero JSON. Zero latency.

```bash
engram run swarm
```

| Metric | KV-Cache Agents | Engram |
|:--|:--|:--|
| 2 agents, 10K tokens each | 20,002 KB | **8,622 KB** |
| 1,000 agents, 10K tokens each | **10.2 GB** (OOM) | **24.6 MB** |
| Knowledge sharing | JSON serialization | Tensor resonance |

---

### Zero-Shot Forward-Pass RL

The Engram supports reward-modulated etching — no gradient descent, no backpropagation:

- `reward > 0` → Strengthen (constructive etch)
- `reward < 0` → Anti-etch (suppress failed actions)
- `reward = 0` → Pure inference

```bash
engram run kung-fu
```

Agent 0 tries 5 API actions, fails 3 times (`reward=-1.0`), succeeds once (`reward=+2.0`). Agent 4, with a blank context, instantly knows the correct action via policy resonance.

---

### Knowledge Cartridges

Your entire context compressed into a portable `.cart` file. Save it, share it, load it in under 1ms.

```bash
engram run cartridge
```

Uses `safetensors` — fast, safe, no pickle. Upload a `.cart` to Discord. Any agent with the same architecture loads it and instantly possesses the accumulated knowledge.

---

### Drop-In Transformer Grafting

Load any pre-trained Transformer, remove `nn.MultiheadAttention`, graft the O(1) Engram in its place, retain all FFN weights. Run a cheap LoRA fine-tune to adapt.

```bash
engram run lobotomy
```

| Context Length | Standard Attention | Engram Engram |
|:--|:--|:--|
| 1,000 tokens | 2.0 MB | **4.1 KB** |
| 10,000 tokens | 20.5 MB | **4.1 KB** |
| 100,000 tokens | 204.8 MB | **4.1 KB** |
| 1,000,000 tokens | 2,048 MB | **4.1 KB** |

---

## Repository Structure

```
Engram/
├── src/engram/                      # Core engine
│   ├── torus.py                    # O(1) toroidal state
│   ├── attention.py                # Holographic attention (MHA replacement)
│   ├── model.py                    # HolographicLM language model
│   ├── engram.py                   # Systolic Engram Cache
│   ├── cartridge.py                # .cart format (safetensors)
│   └── auto_model.py               # HuggingFace PreTrainedModel wrapper
├── cli/                            # Typer/Rich CLI
│   └── main.py                     # engram run / save / inject / inspect / serve
├── server/                         # FastAPI backend
│   └── swarm_chat.py               # OpenAI-compatible API
├── benchmarks/
│   ├── memory_wall.py              # OOM benchmark
│   ├── long_context_recall.py      # Needle-in-a-haystack
│   ├── hybrid_inference.py         # GPT-2 + holographic adapter
│   └── perplexity.py               # Perplexity benchmark
├── demo/
│   ├── hive_mind.py                # Multi-agent weight sharing
│   ├── swarm_rl.py                 # Zero-shot RL
│   ├── knowledge_cartridge.py      # Cartridge save/load
│   ├── lobotomy.py                 # Transformer grafting
│   └── generate.py                 # Text generation
├── train/
│   └── train_holographic_lm.py     # Training script
├── Dockerfile                      # Container image
├── docker-compose.yml              # Engine + Open-WebUI
├── demo.tape                       # VHS terminal recording script
├── pyproject.toml                  # Package config
├── plots/                          # Benchmark plots
└── LICENSE.md
```

---

## Hardware

| Configuration | Hardware | Notes |
|:--|:--|:--|
| ✅ Development | Any CUDA GPU | RTX 3060+ recommended |
| ✅ **Benchmarked** | **RTX 4060 Laptop (8GB)** | **All results in this repo** |
| ✅ Training | RTX 4060+ | ~30min for 30M param model |
| ✅ Full suite | H100 / TPU v5e | For paper-grade results |

---

## Citation

```bibtex
@software{arndt2026engram,
  author    = {Arndt, Justin},
  title     = {{Engram}: Persistent Systolic Continuous State Engine},
  year      = {2026},
  url       = {https://github.com/justinarndt/Engram},
  note      = {O(1) holographic memory with Hebbian crystalline recall}
}
```

---

## License

**[Research & Academic Use License](LICENSE.md)**

✅ Academic research, publication, experimentation · ❌ Commercial use requires separate license

### Patent Notice

The Engram architecture is the subject of U.S. Provisional Patent Application No. 63/989,566, filed February 24, 2026.

---

## Contact

**Justin Arndt** · 📧 justinarndt05@gmail.com

For commercial licensing, partnership, or research collaboration.
