GUIDE.md

# HippocampAIF — End-to-End Codebase Guide

**A Biologically Grounded Cognitive Architecture for One-Shot Learning & Active Inference**

License: © 2026 Algorembrant, Rembrant Oyangoren Albeos

---

## Table of Contents

1. [What This Is](#what-this-is)
2. [Theoretical Foundations](#theoretical-foundations)
3. [Architecture Map](#architecture-map)
4. [Setup](#setup)
5. [Module Reference](#module-reference)
6. [How the Pipeline Works](#how-the-pipeline-works)
7. [Using the MNIST Agent](#using-the-mnist-agent)
8. [Using the Breakout Agent](#using-the-breakout-agent)
9. [Running Tests](#running-tests)
10. [Extending the Framework](#extending-the-framework)
11. [Design Decisions & Rationale](#design-decisions--rationale)
12. [File Map](#file-map)

---

## What This Is

HippocampAIF is a **complete cognitive architecture** implemented in pure Python (NumPy + SciPy only — no PyTorch, no TensorFlow, no JAX). Every module corresponds to a real brain structure with citations to the computational neuroscience literature.

The framework does two things that conventional ML cannot:

1. **One-shot classification** — learn to recognize a new category from a single example (like humans do)
2. **Fast game mastery** — play Atari Breakout using innate physics priors (like infants understand gravity before they can walk)

### Key Innovation

Instead of POMDP/VI/MCMC (traditional AI approaches), HippocampAIF uses:
- **Free-Energy Minimization** (Friston) for perception and action
- **Hippocampal Fast-Binding** for instant one-shot memory
- **Spelke's Core Knowledge** systems as hardcoded innate priors
- **Distortable Canvas** for elastic image comparison

---

## Theoretical Foundations

### Three Source Papers

| Paper | What It Provides | Where in Code |
|-------|-----------------|---------------|
| **Friston (2009)** "The free-energy principle: a rough guide to the brain" | Free energy F = Energy − Entropy, recognition dynamics, active inference | `core/free_energy.py`, `core/message_passing.py`, `neocortex/predictive_coding.py`, `action/active_inference.py` |
| **Lake et al. (2015)** "Human-level concept learning through probabilistic program induction" (BPL) | One-shot learning from single examples, compositional representations | `learning/one_shot_classifier.py`, `hippocampus/index_memory.py`, `agent/mnist_agent.py` |
| **Distortable Canvas** (oneandtrulyone) | Elastic canvas deformation, dual distance metric, AMGD optimization | `learning/distortable_canvas.py`, `learning/amgd.py`, `core_knowledge/geometry_system.py` |

### Core Equations

**Free Energy (Friston Box 1):**
```
F = −⟨ln p(y,ϑ|m)⟩_q + ⟨ln q(ϑ|μ)⟩_q
```
Under Laplace approximation: `F ≈ −ln p(y,μ) + ½ ln|Π(μ)|`

**Recognition Dynamics (Friston Box 3):**
```
μ̇ = −∂F/∂μ   (perception: update internal model)
ȧ = −∂F/∂a   (action: change world to match predictions)
λ̇ = −∂F/∂λ   (attention: optimize precision)
```

**Dual Distance (Distortable Canvas):**
```
D(I₁, I₂) = min_u,v [ color_dist(warp(I₁, u, v), I₂) + λ × canvas_dist(u, v) ]
```

---

## Architecture Map

```
                        ┌────────────────────────────┐
                        │    Prefrontal Cortex (PFC) │
                        │  • Working memory (7±2)    │
                        │  • Executive control       │
                        │  • Goal stack              │
                        └──────────┬─────────────────┘
                                   │ top-down control
          ┌────────────────────────┼────────────────────────┐
          │                        │                        │
          ▼                        ▼                        ▼
┌─────────────────┐   ┌──────────────────┐    ┌────────────────────┐
│ Temporal Cortex │   │ Predictive Coding│    │  Parietal Cortex   │
│ • Recognition   │   │ • Friston Box 3  │    │  • Priority maps   │
│ • Categories    │◄──│ • Free-energy min│──► │  • Coord. transforms│
│ • Semantic mem. │   │ • Error signals  │    │  • Sensorimotor    │
└────────┬────────┘   └────────┬─────────┘    └────────┬───────────┘
         │                     │                       │
         │     ┌───────────────┼───────────────┐       │
         │     ▼               ▼               ▼       │
         │  ┌─────┐   ┌──────────────┐  ┌──────────┐   │
         │  │ SC  │   │  Precision   │  │ Biased   │   │
         │  │Saccade│ │  Modulator   │  │ Compete  │   │
         │  └──┬──┘   └──────┬──────┘   └────┬─────┘   │
         │     └─────────────┼───────────────┘         │
         │                   │ attention               │
         │     ┌─────────────┼─────────────┐           │
         ▼     ▼             ▼             ▼           ▼
    ┌──────────────────────────────────────────────────────┐
    │              H I P P O C A M P U S                   │
    │  ┌────────┐  ┌─────┐  ┌─────┐  ┌──────────────┐      │
    │  │  DG    │→ │ CA3 │→ │ CA1  │→│ Index Memory │      │
    │  │Separate │ │Complete│ │Match│  │ Fast-binding  │   │
    │  └────────┘  └─────┘  └─────┘  └──────────────┘      │
    │  ┌───────────────┐  ┌───────────────┐                │
    │  │ Entorhinal EC │  │ Replay Buffer │                │
    │  │ Grid cells    │  │ Consolidation │                │
    │  └───────────────┘  └───────────────┘                │
    └──────────────────────────┬───────────────────────────┘
                               │ features
    ┌──────────────────────────┴───────────────────────────┐
    │              V I S U A L   C O R T E X               │
    │  ┌───────────┐  ┌──────────────┐  ┌───────────────┐  │
    │  │ V1 Simple │→ │ V1 Complex   │→ │ HMAX Hierarchy│  │
    │  │ Gabor     │  │ Max-pooling  │  │ V2→V4→IT      │  │
    │  └───────────┘  └──────────────┘  └───────────────┘  │
    └──────────────────────────┬───────────────────────────┘
                               │ ON/OFF sparse
    ┌──────────────────────────┴───────────────────────────┐
    │                    R E T I N A                       │
    │  ┌──────────────┐  ┌──────────┐  ┌────────────────┐  │
    │  │ Photoreceptors│ │ Ganglion │  │ Spatiotemporal │  │
    │  │ Adaptation   │  │ DoG      │  │ Motion energy  │  │
    │  └──────────────┘  └──────────┘  └────────────────┘  │
    └──────────────────────────┬───────────────────────────┘
                               │ raw image
                          ═════╧═════
                          │ SENSES │
                          ═══════════

    ┌──────────────────────────────────────────────────────┐
    │            C O R E   K N O W L E D G E               │
    │  ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐         │
    │  │Objects │ │Physics │ │Number  │ │Geometry│         │
    │  │Perm/Coh│ │Gravity │ │ANS/Sub │ │Canvas  │         │
    │  └────────┘ └────────┘ └────────┘ └────────┘         │
    │  ┌────────┐ ┌────────┐                               │
    │  │Agent   │ │Social  │    ← INNATE, NOT LEARNED      │
    │  │Goals   │ │Helper  │                               │
    │  └────────┘ └────────┘                               │
    └──────────────────────────────────────────────────────┘

    ┌──────────────────────────────────────────────────────┐
    │              A C T I O N   S Y S T E M               │
    │  ┌──────────────────┐  ┌────────────┐  ┌──────────┐  │
    │  │ Active Inference │  │ Motor      │  │ Reflex   │  │
    │  │ ȧ = −∂F/∂a       │  │ Primitives │  │ Arc      │  │
    │  │ Expected FE min. │  │ L/R/Fire   │  │ Track    │  │
    │  └──────────────────┘  └────────────┘  └──────────┘  │
    └──────────────────────────────────────────────────────┘
```

---

## Setup

### Prerequisites
- Python ≥ 3.10
- NumPy ≥ 1.24
- SciPy ≥ 1.10
- Pillow ≥ 9.0

### Installation

```powershell
# 1. Clone or navigate to the project
cd c:\Users\User\Desktop\debugrem\clawd-one-and-only-one-shot

# 2. Create virtual environment
python -m venv .venv

# 3. Activate
.venv\Scripts\activate

# 4. Install dependencies
pip install -r requirements.txt

# 5. Set PYTHONPATH (REQUIRED — PowerShell syntax)
$env:PYTHONPATH = "c:\Users\User\Desktop\debugrem\clawd-one-and-only-one-shot"
```

> **CMD users:** Use `set PYTHONPATH=c:\Users\User\Desktop\debugrem\clawd-one-and-only-one-shot`

> **Linux/Mac users:** Use `export PYTHONPATH=$(pwd)`

### Verify Installation

```powershell
python -c "import hippocampaif; print(f'HippocampAIF v{hippocampaif.__version__}')"
# Expected: HippocampAIF v1.0.0
```

---

## Module Reference

### Phase 1: Core Infrastructure (`core/`)

| Module | Class | Purpose |
|--------|-------|---------|
| `tensor.py` | `SparseTensor` | Sparse ndarray wrapper — the brain is "lazy and sparse" |
| `free_energy.py` | `FreeEnergyEngine` | Variational free-energy computation and gradient descent |
| `message_passing.py` | `HierarchicalMessagePassing` | Forward (errors) + Backward (predictions) message passing |
| `dynamics.py` | `ContinuousDynamics` | Euler integration of recognition dynamics |

**Usage:**
```python
from hippocampaif.core.free_energy import FreeEnergyEngine

fe = FreeEnergyEngine(learning_rate=0.01)
F = fe.compute_free_energy(sensory_input, prediction, precision)
new_state = fe.perception_update(state, sensory_input, generative_fn, precision)
```

### Phase 2: Retina (`retina/`)

| Module | Class | Purpose |
|--------|-------|---------|
| `photoreceptor.py` | `PhotoreceptorArray` | Luminance adaptation, Weber's law |
| `ganglion.py` | `GanglionCellLayer` | DoG center-surround → ON/OFF sparse channels |
| `spatiotemporal_energy.py` | `SpatiotemporalEnergyBank` | Adelson-Bergen motion energy |

**Usage:**
```python
from hippocampaif.retina.ganglion import GanglionCellLayer

retina = GanglionCellLayer(center_sigma=1.0, surround_sigma=3.0)
st_on, st_off = retina.process(image)  # Returns SparseTensors
on_array = st_on.data  # Dense numpy array
```

### Phase 3: Visual Cortex (`v1_v5/`)

| Module | Class | Purpose |
|--------|-------|---------|
| `gabor_filters.py` | `V1SimpleCells` | 2D Gabor filter bank (multi-orientation, multi-scale) |
| `sparse_coding.py` | `V1ComplexCells` | Max-pooling for shift invariance + hypercolumn sparsity |
| `hmax_pooling.py` | `HMAXHierarchy` | S-cell/C-cell hierarchy: V1→V2→V4→IT |

**Usage:**
```python
from hippocampaif.v1_v5.gabor_filters import V1SimpleCells
from hippocampaif.v1_v5.sparse_coding import V1ComplexCells
from hippocampaif.v1_v5.hmax_pooling import HMAXHierarchy

v1 = V1SimpleCells(n_orientations=8, n_scales=2, kernel_size=11, frequency=0.25)
v1c = V1ComplexCells(pool_size=3)
hmax = HMAXHierarchy(pool_sizes=[2, 2])

simple = v1.process(on_center_image)       # (n_filters, H, W)
complex_maps = v1c.process(simple)          # list[SparseTensor]
hierarchy = hmax.process(complex_maps)      # list[list[SparseTensor]]
```

### Phase 4: Hippocampus (`hippocampus/`)

| Module | Class | Purpose |
|--------|-------|---------|
| `dg.py` | `DentateGyrus` | Pattern separation — sparse expansion coding |
| `ca3.py` | `CA3` | Pattern completion — attractor network |
| `ca1.py` | `CA1` | Match/mismatch detection → novelty signals |
| `entorhinal.py` | `EntorhinalCortex` | Grid cells, spatial coding |
| `index_memory.py` | `HippocampalIndex` | **One-shot fast-binding** — store and retrieve in 1 exposure |
| `replay.py` | `ReplayBuffer` | Memory consolidation via offline replay |

**Usage (one-shot memory):**
```python
from hippocampaif.hippocampus.index_memory import HippocampalIndex

mem = HippocampalIndex(cortical_size=128, index_size=256)
mem.store(features_vector)                      # Instant! No training loops
result = mem.retrieve(query_features)            # Nearest match
```

### Phase 5: Core Knowledge (`core_knowledge/`)

These are **innate priors** — hardcoded "common sense" that constrains perception, NOT learned from data.

| Module | Class | What It Encodes |
|--------|-------|----------------|
| `object_system.py` | `ObjectSystem` | Objects persist when occluded, can't teleport, don't pass through each other |
| `physics_system.py` | `PhysicsSystem` | Gravity pulls down, objects bounce elastically, friction slows things |
| `number_system.py` | `NumberSystem` | Exact count ≤4 (subitizing), Weber ratio for larger sets |
| `geometry_system.py` | `GeometrySystem` | Spatial relations + Distortable Canvas deformation fields |
| `agent_system.py` | `AgentSystem` | Self-propelled entities with direction changes = intentional agents |
| `social_system.py` | `SocialSystem` | Helpers are preferred over hinderers |

**Usage (physics prediction for Breakout):**
```python
from hippocampaif.core_knowledge.physics_system import PhysicsSystem, PhysicsState

phys = PhysicsSystem(gravity=0.0, elasticity=1.0)
ball = PhysicsState(position=[50, 100], velocity=[3, -2])
trajectory = phys.predict_trajectory(ball, steps=50, bounds=([0,0], [160,210]))
# → Predicts ball path with wall bounces
```

### Phase 6: Neocortex + Attention (`neocortex/`, `attention/`)

| Module | Class | Purpose |
|--------|-------|---------|
| `predictive_coding.py` | `PredictiveCodingHierarchy` | Hierarchical free-energy minimization (Friston Box 3) |
| `prefrontal.py` | `PrefrontalCortex` | Working memory (7±2 items), executive control |
| `temporal.py` | `TemporalCortex` | Object recognition, one-shot categories |
| `parietal.py` | `ParietalCortex` | Priority maps, coordinate transforms |
| `superior_colliculus.py` | `SuperiorColliculus` | Saccade target selection via WTA competition |
| `precision.py` | `PrecisionModulator` | Attention = precision weighting (attend/suppress channels) |
| `competition.py` | `BiasedCompetition` | Desimone & Duncan biased competition model |

### Phase 7: One-Shot Learning (`learning/`)

| Module | Class | Purpose |
|--------|-------|---------|
| `distortable_canvas.py` | `DistortableCanvas` | Elastic image warping + dual distance metric |
| `amgd.py` | `AMGD` | Coarse-to-fine deformation optimization |
| `one_shot_classifier.py` | `OneShotClassifier` | Full pipeline: features → match → canvas refine |
| `hebbian.py` | `HebbianLearning` | Basic/Oja/BCM/anti-Hebbian plasticity rules |

### Phase 8: Action (`action/`)

| Module | Class | Purpose |
|--------|-------|---------|
| `active_inference.py` | `ActiveInferenceController` | ȧ = −∂F/∂a — choose actions that minimize surprise |
| `motor_primitives.py` | `MotorPrimitives` | NOOP/FIRE/LEFT/RIGHT for Breakout |
| `reflex_arc.py` | `ReflexArc` | Tracking, withdrawal, orienting, intercept reflexes |

### Phase 9: Integrated Agent (`agent/`)

| Module | Class | Purpose |
|--------|-------|---------|
| `brain.py` | `Brain` | Wires ALL modules together: sense→remember→predict→attend→act |
| `mnist_agent.py` | `MNISTAgent` | One-shot MNIST: 1 exemplar per digit → classify |
| `breakout_agent.py` | `BreakoutAgent` | Breakout: physics priors + reflex tracking |

---

## How the Pipeline Works

### Perception Pipeline (seeing)

```
Raw Image (28×28 or 84×84)
    │
    ▼  GanglionCellLayer.process()
ON/OFF SparseTensors (DoG filtered)
    │
    ▼  V1SimpleCells.process()
Gabor responses (n_orientations × n_scales, H, W)
    │
    ▼  V1ComplexCells.process()
Shift-invariant sparse maps: list[SparseTensor]
    │
    ▼  HMAXHierarchy.process()
Hierarchical features: list[list[SparseTensor]]
    │
    ▼  Flatten + truncate to feature_size
Feature vector (128-dim)
    │
    ├──► PredictiveCodingHierarchy.process() → free energy minimization
    ├──► TemporalCortex.recognize() → category label
    ├──► PrefrontalCortex.store() → working memory
    └──► HippocampalIndex.store() → one-shot binding
```

### Action Pipeline (doing)

```
Current internal state (from predictive coding)
    │
    ▼  ActiveInferenceController.select_action()
Expected free energy G(a) for each action
    │
    ▼  softmax(−β × G)
Action probabilities
    │
    ▼  argmin or sample
Discrete action (0-3)
    │
    ▼  MotorPrimitives.get_action_name()
"LEFT" / "RIGHT" / "FIRE" / "NOOP"
```

### One-Shot Learning Pipeline (classifying)

```
Test Image
    │
    ▼  Full perception pipeline
Feature vector
    │
    ▼  OneShotClassifier.classify()
    │
    ├── Compare to all stored exemplar features
    ├── If confidence > threshold → return label
    └── If ambiguous → DistortableCanvas refinement:
        ├── AMGD optimizes deformation field
        ├── Dual distance = color_dist + λ × canvas_dist
        └── Choose exemplar with lowest dual distance
```

---

## Using the MNIST Agent

### Quick Start

```python
import numpy as np
from hippocampaif.agent.mnist_agent import MNISTAgent

# Create agent (feature_size=128 is the default)
agent = MNISTAgent(feature_size=128, use_canvas=True)

# === TRAINING: Learn 1 exemplar per digit ===
# Load your MNIST data (10 training images, one per digit)
for digit in range(10):
    image = training_images[digit]  # 28×28 numpy array, values 0-255
    agent.learn_digit(image, label=digit)

print(f"Learned {agent.exemplars_stored} digits")

# === TESTING: Classify new images ===
result = agent.classify(test_image)
print(f"Predicted: {result['label_int']}, Confidence: {result['confidence']:.2f}")

# === EVALUATION: Batch accuracy ===
stats = agent.evaluate(test_images, test_labels)
print(f"Accuracy: {stats['accuracy']*100:.1f}%")
print(f"Per-class: {stats['per_class_accuracy']}")
```

### Loading MNIST Data

```python
# Option 1: From sklearn
from sklearn.datasets import fetch_openml
mnist = fetch_openml('mnist_784', version=1)
images = mnist.data.values.reshape(-1, 28, 28)
labels = mnist.target.values.astype(int)

# Option 2: From local .npy files
images = np.load('mnist_images.npy')
labels = np.load('mnist_labels.npy')

# Select 1 training exemplar per digit
train_indices = []
for d in range(10):
    idx = np.where(labels == d)[0][0]
    train_indices.append(idx)

train_images = images[train_indices]
train_labels = labels[train_indices]
```

---

## Using the Breakout Agent

### Quick Start

```python
import numpy as np
from hippocampaif.agent.breakout_agent import BreakoutAgent

# Create agent
agent = BreakoutAgent(screen_height=210, screen_width=160)

# === Game Loop ===
agent.new_episode()
observation = env.reset()  # From gymnasium

for step in range(10000):
    action = agent.act(observation, reward=0.0)
    observation, reward, done, _, info = env.step(action)
    
    if done:
        print(f"Episode {agent.episode}: reward = {agent.episode_reward}")
        agent.new_episode()
        observation = env.reset()
```

### With Gymnasium (requires optional deps)

```powershell
pip install gymnasium[atari] ale-py
```

```python
import gymnasium as gym
from hippocampaif.agent.breakout_agent import BreakoutAgent

env = gym.make('BreakoutNoFrameskip-v4', render_mode='human')
agent = BreakoutAgent()

for episode in range(5):
    agent.new_episode()
    obs, _ = env.reset()
    total_reward = 0
    
    while True:
        action = agent.act(obs)
        obs, reward, term, trunc, _ = env.step(action)
        total_reward += reward
        if term or trunc:
            break
    
    print(f"Episode {episode+1}: {total_reward} reward")
    print(agent.get_stats())

env.close()
```

---

## Running Tests

### All Phases

```powershell
# Set PYTHONPATH first!
$env:PYTHONPATH = "c:\Users\User\Desktop\debugrem\clawd-one-and-only-one-shot"

# Phase 1-4 (Core, Retina, Visual Cortex, Hippocampus)
python -m hippocampaif.tests.test_core
python -m hippocampaif.tests.test_retina
python -m hippocampaif.tests.test_v1_v5
python -m hippocampaif.tests.test_hippocampus

# Phase 5-8 (Core Knowledge, Neocortex, Learning, Action)
python -m hippocampaif.tests.test_core_knowledge
python -m hippocampaif.tests.test_neocortex_attention
python -m hippocampaif.tests.test_learning
python -m hippocampaif.tests.test_action
```

### What Each Test Suite Validates

| Test Suite | # Tests | What It Checks |
|-----------|---------|----------------|
| `test_core` | — | Free-energy convergence, message passing stability, sparse tensor ops |
| `test_retina` | — | DoG center-surround, motion energy detection |
| `test_v1_v5` | — | Gabor orientations, HMAX invariant features |
| `test_hippocampus` | — | Pattern separation orthgonality, completion from partial cues |
| `test_core_knowledge` | 11 | Object permanence, continuity, gravity, bounce, support, subitizing, Weber, geometry, deformation, agency, social |
| `test_neocortex_attention` | 10 | PC convergence, PC learning, WM capacity, WM decay, one-shot recognition, coord transforms, priority maps, saccades, precision, biased competition |
| `test_learning` | 7 | Canvas warp identity, dual distance, same-class distance, AMGD, Hebbian basic, Oja bounded, one-shot classifier |
| `test_action` | 6 | Active inference goal-seeking, forward model learning, motor primitives, reflex tracking, intercept, habituation |

---

## Extending the Framework

### Adding a New Core Knowledge System

```python
# hippocampaif/core_knowledge/my_new_system.py
import numpy as np

class TemporalSystem:
    """Core knowledge of time and causality."""
    
    def __init__(self):
        self.causal_chains = []
    
    def detect_causality(self, event_a, event_b, time_gap):
        """Innate prior: causes precede effects in time."""
        if time_gap > 0 and time_gap < 2.0:  # Temporal contiguity
            return {'causal': True, 'strength': 1.0 / time_gap}
        return {'causal': False, 'strength': 0.0}
```

Then add to `core_knowledge/__init__.py`:
```python
from .my_new_system import TemporalSystem
```

### Adding a New Agent

```python
# hippocampaif/agent/my_agent.py
from hippocampaif.agent.brain import Brain

class MyAgent:
    def __init__(self):
        self.brain = Brain(image_height=64, image_width=64, n_actions=4)
    
    def act(self, observation):
        perception = self.brain.perceive(observation)
        return self.brain.act()
    
    def learn(self, image, label):
        self.brain.one_shot_learn(image, label)
```

### Adding Custom Reflexes

```python
from hippocampaif.action.reflex_arc import ReflexArc

class CustomReflexArc(ReflexArc):
    def dodge_reflex(self, projectile_pos, projectile_vel, agent_pos):
        """Dodge an incoming projectile."""
        # Predict collision point
        predicted = projectile_pos + projectile_vel * 0.5
        
        # Move perpendicular to projectile trajectory
        direction = np.cross(projectile_vel, [0, 0, 1])[:2]
        return self.reflex_gain * direction
```

---

## Design Decisions & Rationale

### Why No PyTorch/TensorFlow/JAX?

The framework is intentionally pure NumPy + SciPy because:
1. **Biological fidelity** — neural computations are local gradient updates, not backprop through a compute graph
2. **Interpretability** — every array corresponds to a neural population with known anatomy
3. **Minimal dependencies** — runs on any machine with Python and NumPy
4. **Educational value** — you can read every line and understand the neuroscience

### Why Hippocampal Fast-Binding Instead of MCMC?

MCMC sampling is computationally expensive and biologically implausible. The hippocampus stores new memories **instantly** via pattern separation (DG) + fast Hebbian binding  (CA3) — no need for thousands of samples.

### Why Spelke's Core Knowledge Instead of Tabula Rasa?

Human infants are NOT blank slates. They have innate expectations about:
- **Objects** — things persist when hidden
- **Physics** — dropped objects fall
- **Numbers** — small quantities are exact

These priors are hardcoded because they evolved over millions of years and shouldn't need to be learned from scratch by every agent.

### Why Distortable Canvas Instead of CNN Features?

CNNs require thousands of training images. The Distortable Canvas achieves 90% MNIST accuracy with just **4 examples** by treating image comparison as a smooth deformation problem — "how much do I need to warp image A to look like image B?"

---

## File Map

```
hippocampaif/                          # 59 Python files across 9 packages
├── __init__.py                        # v1.0.0, exports core classes
├── core/                              # Phase 1 — Foundation
│   ├── tensor.py                      # SparseTensor
│   ├── free_energy.py                 # FreeEnergyEngine
│   ├── message_passing.py             # HierarchicalMessagePassing
│   └── dynamics.py                    # ContinuousDynamics
├── retina/                            # Phase 2 — Eye
│   ├── photoreceptor.py               # PhotoreceptorArray
│   ├── ganglion.py                    # GanglionCellLayer (DoG)
│   └── spatiotemporal_energy.py       # SpatiotemporalEnergyBank
├── v1_v5/                             # Phase 3 — Visual Cortex
│   ├── gabor_filters.py               # V1SimpleCells
│   ├── sparse_coding.py               # V1ComplexCells
│   └── hmax_pooling.py                # HMAXHierarchy
├── hippocampus/                       # Phase 4 — Memory
│   ├── dg.py                          # DentateGyrus
│   ├── ca3.py                         # CA3
│   ├── ca1.py                         # CA1
│   ├── entorhinal.py                  # EntorhinalCortex
│   ├── index_memory.py                # HippocampalIndex
│   └── replay.py                      # ReplayBuffer
├── core_knowledge/                    # Phase 5 — Innate Priors
│   ├── object_system.py               # ObjectSystem
│   ├── physics_system.py              # PhysicsSystem
│   ├── number_system.py               # NumberSystem
│   ├── geometry_system.py             # GeometrySystem
│   ├── agent_system.py                # AgentSystem
│   └── social_system.py               # SocialSystem
├── neocortex/                         # Phase 6a — Higher Cognition
│   ├── predictive_coding.py           # PredictiveCodingHierarchy
│   ├── prefrontal.py                  # PrefrontalCortex
│   ├── temporal.py                    # TemporalCortex
│   └── parietal.py                    # ParietalCortex
├── attention/                         # Phase 6b — Attention
│   ├── superior_colliculus.py         # SuperiorColliculus
│   ├── precision.py                   # PrecisionModulator
│   └── competition.py                 # BiasedCompetition
├── learning/                          # Phase 7 — One-Shot
│   ├── distortable_canvas.py          # DistortableCanvas
│   ├── amgd.py                        # AMGD
│   ├── one_shot_classifier.py         # OneShotClassifier
│   └── hebbian.py                     # HebbianLearning
├── action/                            # Phase 8 — Motor
│   ├── active_inference.py            # ActiveInferenceController
│   ├── motor_primitives.py            # MotorPrimitives
│   └── reflex_arc.py                  # ReflexArc
├── agent/                             # Phase 9 — Integration
│   ├── brain.py                       # Brain (full pipeline)
│   ├── mnist_agent.py                 # MNISTAgent
│   └── breakout_agent.py              # BreakoutAgent
└── tests/                             # 8 test suites, 34+ tests
    ├── test_core.py
    ├── test_retina.py
    ├── test_visual_cortex.py
    ├── test_hippocampus.py
    ├── test_core_knowledge.py
    ├── test_neocortex_attention.py
    ├── test_learning.py
    └── test_action.py
```

---

## Citation

If you use this framework in research or production, please cite:

```bibtex
@software{hippocampaif2026,
  author = {Albeos, Rembrant Oyangoren},
  title = {HippocampAIF: Biologically Grounded Cognitive Architecture},
  year = {2026},
  description = {Free-energy minimization + hippocampal fast-binding + 
                 Spelke's core knowledge for one-shot learning and active inference}
}
```

**References:**
- Friston, K. (2009). The free-energy principle: a rough guide to the brain. *Trends in Cognitive Sciences*, 13(7), 293-301.
- Lake, B. M., Salakhutdinov, R., & Tenenbaum, J. B. (2015). Human-level concept learning through probabilistic program induction. *Science*, 350(6266), 1332-1338.
- Spelke, E. S. (2000). Core knowledge. *American Psychologist*, 55(11), 1233-1243.