Metadata-Version: 2.4
Name: slfn-substrate
Version: 0.3.0
Summary: Unified Cognition Substrate (UCS) - Neuromorphic memory as living computation
Author-email: SLFN <bozo@slfn.ca>
License: MIT
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.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: torch>=2.3.0
Requires-Dist: numpy>=1.26.0
Requires-Dist: pydantic>=2.7.0
Requires-Dist: pyyaml>=6.0.1
Provides-Extra: jax
Requires-Dist: jax>=0.4.25; extra == "jax"
Requires-Dist: jaxlib>=0.4.25; extra == "jax"
Provides-Extra: dev
Requires-Dist: pytest>=8.2.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Requires-Dist: mypy>=1.10.0; extra == "dev"
Provides-Extra: bench
Requires-Dist: pytest-benchmark>=4.0.0; extra == "bench"

# Unified Cognition Substrate (UCS)

**Making memory into computation. No retrieval — only resonance.**

## Overview

The Unified Cognition Substrate is a neuromorphic memory architecture where concepts are self-stabilizing attractors in a high-dimensional manifold, not passive vectors in a database. This is the breakthrough: **memory becomes active computation**.

### The 5 Evolutionary Milestones

| Milestone | Name | Breakthrough |
|-----------|------|--------------|
| 1 | **Resonance** | Continuous attractor networks - patterns snap to stable states |
| 2 | **Metabolism** | Energy-gated structure - forgetting = decay |
| 3 | **Subjective Time** | Dilation scheduling - saliency → compute cycles |
| 4 | **Thermodynamics** | Landauer-limit enforcement - physics as architecture |
| 5 | **Entanglement** | Quantum-inspired sync - instant cross-agent memory |

### Product Manifestation

- **Hurcules**: Growth protocol (NSME + AttractorMemoryCache)
- **HCOS**: Metabolism engine (Energy budgets + Thermodynamic OS)
- **HRCC**: Nervous system (Entanglement graph + Real-time mesh)

All powered by a single `substrate` library.

## Installation

```bash
# Core dependencies
pip install torch numpy pydantic pyyaml

# Optional: sentence-transformers for text encoding
pip install sentence-transformers

# Development
pip install -e ".[dev]"

# JAX backend (optional)
pip install -e ".[jax]"
```

## Quick Start

```python
from substrate import AttractorMemoryCache, MemoryConfig
from substrate.attractor import AttractorConfig

# Configure
config = MemoryConfig(
    attractor=AttractorConfig(dimension=4096, num_patterns=10000),
    projection_dim=4096
)

# Create cache
cache = AttractorMemoryCache(config)

# Store concepts (natural language → attractor patterns)
cache.store("greg_phone", "Greg Ermine's phone is 306-961-4734")
cache.store("slfn_info", "SLFN is a Treaty 6 nation with ~1500 members")

# Recall through RESONANCE (zero-latency, no retrieval)
results = cache.recall("What's Greg's phone number?")
# Returns: [{concept_id: "greg_phone", similarity: 0.94, ...}]

# Test noise robustness
cache.inject_noise_and_recover("greg_phone", noise_std=0.2)
# Pattern recovers correctly even with 20% noise
```

## Architecture

```
substrate/
├── attractor.py      # Continuous Attractor Network (core)
├── memory.py         # AttractorMemoryCache (production API)
├── energy.py         # EnergyGate (Milestone 2)
├── time.py           # TimeDilationScheduler (Milestone 3)
├── thermo.py         # ThermodynamicAccountant (Milestone 4)
├── entanglement.py   # EntanglementGraph (Milestone 5)
└── __init__.py       # Exports
```

## Running Demos

```bash
# Milestone 1 demo
python -m substrate.examples.demo

# Or directly
python examples/demo.py
```

## Running Tests

```bash
# All tests
pytest tests/ -v

# Specific component
pytest tests/test_substrate.py::TestContinuousAttractorNetwork -v

# With coverage
pytest tests/ --cov=substrate --cov-report=term-missing
```

## The Science

### Why Attractors?

Traditional memory: **Vector DB + RAG**
- Query → Embed → Search → Retrieve → Attend → Reason
- Latency at every step
- Passive storage

Attractor memory: **Continuous Dynamics**
- Cue → Resonate → Converge → Activate
- Single forward pass
- Active computation

### Theoretical Foundation

- **Hopfield (1982)**: Binary attractors, capacity ~0.14N
- **Krotov & Hopfield (2020+)**: Dense associative memory, exponential capacity
- **Modern continuous attractors**: Polynomial/Exponential activation functions
- **Energy function**: E = -∑F(ξ^μ·x) + ½∑x²
- **Dynamics**: dx/dt = -x + β∑ξ^μF'(ξ^μ·x)

### Noise Robustness

The network's energy landscape creates basins of attraction around each stored pattern. Noisy/partial cues fall into the nearest basin and dynamically converge to the stable attractor. This is **pattern completion through physics**, not algorithmic search.

## Milestone Status

- ✅ **Milestone 1: Resonance** - Continuous Attractor Network implemented
- ✅ **Milestone 2: Metabolism** - EnergyGate integrated (living memory with metabolic cost)
- ✅ **Milestone 3: Subjective Time** - TimeDilationScheduler integrated (saliency-based dilation)
- ✅ **Milestone 4: Thermodynamics** - ThermodynamicAccountant integrated (Landauer-limit enforcement)
- ✅ **Milestone 5: Entanglement** - EntanglementGraph integrated (quantum-inspired sync)

## License

MIT
