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
2. Theoretical Foundations
3. Architecture Map
4. Setup
5. Module Reference
6. How the Pipeline Works
7. Using the MNIST Agent
8. Using the Breakout Agent
9. Running Tests
10. Extending the Framework
11. Design Decisions & Rationale
12. 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

# 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

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:

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:

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:

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):

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):

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

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

# 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

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)

pip install gymnasium[atari] ale-py

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

# 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

# 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:

from .my_new_system import TemporalSystem

Adding a New Agent

# 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

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:

@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.