Hugging Face's logo

algorembrant
/
HippocampAIF

Model card Files
xet
 Community
HippocampAIF / GUIDE.md
algorembrant's picture
algorembrant
Upload 253 files
32d978d verified
preview code
|
Raw
History Blame Contribute Delete
32.3 kB

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.