README.md

# Morpho-Logic Engine (MLE) — Adaptive Learning System

## Overview

The **Morpho-Logic Engine (MLE)** is a high-dimensional sparse distributed memory system with energy-based dynamics, optimized for CPU performance through bit-slicing SIMD operations. It learns continuously during inference without classical backpropagation, using purely local, energy-driven updates.

## Core Architecture

The system comprises five integrated modules that co-evolve during operation:

### 1. Memory — Adaptive Sparse Address Table
- **4096-bit binary vectors** with target sparsity ~5% (~200 active bits)
- **Dynamic creation**: new vectors spawn for recurrent or under-represented patterns
- **Fusion & specialization**: close vectors merge; context-dependent specializations branch off
- **Local reorganization**: semantic neighborhood coherence is improved iteratively
- **Controlled forgetting**: pruning of under-used entries prevents drift

### 2. Routing — Hamming Distance + Bit-Slicing SIMD
- Vectors packed into **64 × uint64** slices
- **Parallel Hamming distance** computation via bit-twiddling popcount
- **Inverted index** per slice for sub-linear candidate retrieval
- **Learned route cache**: frequently traversed query→neighbor mappings are memorized

### 3. Binding — Circular Convolution
- **Role-filler binding** via circular convolution in frequency domain (FFT)
- **Structure composition**: multiple role-filler pairs superposed into composite vectors
- **Robust unbinding**: recover fillers from bound representations

### 4. Energy Landscape — Learnable Coherence Function
- **Hamming energy**: local coherence via neighbor distances
- **Hebbian-like associations**: co-occurring vectors in low-energy states strengthen links
- **Anti-Hebbian for instability**: high-energy configurations weaken spurious associations
- **Adaptive biases**: per-bit biases shift based on experience
- **No global gradient**: all updates are purely local

### 5. Inference — Online Learning through Energy Minimization
- **Stochastic bit-flip descent** with simulated annealing temperature schedule
- **Metropolis-Hastings acceptance** for exploration/exploitation balance
- **Learning during inference**: associations, biases, and routes update at every iteration
- **Post-inference reinforcement**: stable low-energy trajectories are consolidated

## Key Capabilities

### Continuous Online Learning
The system learns while it reasons. Every inference pass updates:
- Vector co-activation weights
- Energy landscape associations
- Routing cache entries
- Memory structure (creation, fusion, specialization)

### Generalization through Composition
- **Binding/unbinding** enables compositional reasoning
- **Pattern abstraction** detects recurrent low-energy trajectories and compiles them into new memory units
- **Structure reuse**: existing sub-patterns are recycled in novel contexts

### Semantic Coherence
Local reorganization ensures vectors that are close in Hamming space correspond to semantically related concepts. Coherence score is continuously monitored.

### CPU-Optimized Performance
- All core operations use vectorized NumPy and JIT-compiled Numba kernels
- No dense matrix multiplications
- Bit-slicing reduces memory bandwidth by 64×
- Hamming distances computed via XOR + popcount

## Benchmark Results

```
Learning confirmed:        ✓ Energy decreased with experience
Binding accuracy:          100% (10/10)
Semantic coherence:        0.996
Avg inference time:        ~540 ms
Memory growth:            controlled (auto-pruning)
Convergence rate:          ~78%
```

## Usage

```python
from mle import MLESystem
import numpy as np

# Initialize
mle = MLESystem(
    memory_capacity=2000,
    online_learning=True,
    temperature=0.5,
)

# Create a sparse input vector
vec = np.zeros(4096, dtype=np.uint8)
vec[np.random.choice(4096, size=200, replace=False)] = 1

# Process (inference + learning)
result = mle.process(vec)
print(f"Converged: {result.converged}")
print(f"Energy: {result.energy_trajectory[-1]:.1f}")

# Query neighbors
neighbors = mle.query(vec, k=5)

# Check system health
mle.print_summary()
```

## Directory Structure

```
mle/
├── __init__.py          # Package exports
├── memory.py            # Adaptive Sparse Address Table
├── routing.py           # Hamming router with bit-slicing
├── binding.py            # Circular convolution binder
├── energy.py             # Learnable energy landscape
├── inference.py          # Online learning inference engine
├── mle_system.py         # Full system integration + metrics
└── tests.py              # Comprehensive benchmark suite
```

## Design Principles

1. **Locality**: every update touches only a neighborhood, no global passes
2. **Sparsity**: 5% active bits → 95% of computation skipped implicitly
3. **Energy as teacher**: low energy = good, high energy = bad, no labels needed
4. **Memory is computation**: the memory table *is* the model; no separate weights
5. **Continuity**: training and inference are the same operation

## Future Directions

- Multi-resolution binding for hierarchical structures
- Cross-modal binding (vision + language in shared space)
- Energy landscape visualization and analysis
- Distributed memory shards for web-scale operation
- Integration with LLM token embeddings for hybrid reasoning