README.md

---
title: HippocampAIF
colorFrom: blue
colorTo: indigo
sdk: docker
pinned: false
license: other
---

# HippocampAIF

A Biologically Grounded Cognitive Architecture for One-Shot Learning and Active Inference.

[![License](https://img.shields.io/badge/License-Proprietary-blue.svg)](#license)
[![Python Version](https://img.shields.io/badge/Python-3.10%2B-blue)](#tech-stack-audit)
[![Build Status](https://img.shields.io/badge/Build-Passing-brightgreen)](#running-tests)
[![Architecture](https://img.shields.io/badge/Architecture-Biologically%20Grounded-purple)](#architecture-map)

---

## What This Is

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

The framework is designed to achieve two milestones that conventional machine learning approaches struggle with:
1. **One-shot classification** - learn to recognize a new category from a single example.
2. **Fast game mastery** - play Atari Breakout using innate physics priors without requiring millions of training episodes.

Instead of traditional AI approaches (like POMDPs or MCMC), HippocampAIF uses:
- **Free-Energy Minimization** (Friston) for perception and action.
- **Hippocampal Fast-Binding** for instant one-shot episodic memory.
- **Spelke's Core Knowledge** systems as hardcoded innate priors (understanding gravity, objects, and numbers inherently).
- **Distortable Canvas** for elastic image comparison and matching.

---

## Architecture Map

```mermaid
flowchart TD
    classDef default fill:#f9f9f9,stroke:#333,stroke-width:1px
    
    PFC["Prefrontal Cortex (PFC)\nWorking memory (7 +/- 2)\nExecutive control\nGoal stack"]
    
    TC["Temporal Cortex\nRecognition\nCategories\nSemantic mem."]
    PC["Predictive Coding\nFriston Box 3\nFree-energy min\nError signals"]
    PAR["Parietal Cortex\nPriority maps\nCoord. transforms\nSensorimotor"]
    
    SC["Superior Colliculus\nSaccade"]
    PM["Precision Modulator"]
    BC["Biased Compete"]
    
    subgraph Hippocampus ["H I P P O C A M P U S"]
        direction LR
        DG["DG\nSeparate"] --> CA3["CA3\nComplete"]
        CA3 --> CA1["CA1\nMatch"]
        CA1 --> IM["Index Memory\nFast-binding"]
        EC["Entorhinal EC\nGrid cells"]
        RB["Replay Buffer\nConsolidation"]
    end
    
    subgraph VisualCortex ["V I S U A L   C O R T E X"]
        direction LR
        V1S["V1 Simple\nGabor"] --> V1C["V1 Complex\nMax-pooling"]
        V1C --> HMAX["HMAX Hierarchy\nV2->V4->IT"]
    end
    
    subgraph RetinaData ["R E T I N A"]
        direction LR
        PR["Photoreceptors\nAdaptation"]
        GAN["Ganglion\nDoG"]
        STE["Spatiotemporal\nMotion energy"]
    end
    
    SENSES["SENSES\n=================\nraw image"]
    
    subgraph CoreKnowledge ["C O R E   K N O W L E D G E (Innate, Not Learned)"]
        direction LR
        OBJ["Objects\nPerm/Coh"]
        PHY["Physics\nGravity"]
        NUM["Number\nANS/Sub"]
        GEO["Geometry\nCanvas"]
        AGT["Agent\nGoals"]
        SOC["Social\nHelper"]
    end
    
    subgraph ActionSystem ["A C T I O N   S Y S T E M"]
        direction LR
        ACTI["Active Inference\na = -dF/da\nExpected FE min."]
        MOT["Motor Primitives\nL/R/Fire"]
        REF["Reflex Arc\nTrack"]
    end
    
    PFC -->|"top-down control"| TC
    PFC -->|"top-down control"| PC
    PFC -->|"top-down control"| PAR
    
    PC --> TC
    PC --> PAR
    
    TC --> SC
    PC --> PM
    PAR --> BC
    
    SC --> Hippocampus
    PM -->|"attention"| Hippocampus
    BC --> Hippocampus
    
    Hippocampus -->|"features"| VisualCortex
    VisualCortex -->|"ON/OFF sparse"| RetinaData
    RetinaData --> SENSES
```

---

## File Structure

```text
hippocampaif/                          
├── __init__.py                        
├── core/                              # Phase 1 — Foundation
│   ├── tensor.py                      
│   ├── free_energy.py                 
│   ├── message_passing.py             
│   └── dynamics.py                    
├── retina/                            # Phase 2 — Eye
│   ├── photoreceptor.py               
│   ├── ganglion.py                    
│   └── spatiotemporal_energy.py       
├── v1_v5/                             # Phase 3 — Visual Cortex
│   ├── gabor_filters.py               
│   ├── sparse_coding.py               
│   └── hmax_pooling.py                
├── hippocampus/                       # Phase 4 — Memory
│   ├── dg.py                          
│   ├── ca3.py                         
│   ├── ca1.py                         
│   ├── entorhinal.py                  
│   ├── index_memory.py                
│   └── replay.py                      
├── core_knowledge/                    # Phase 5 — Innate Priors
│   ├── object_system.py               
│   ├── physics_system.py              
│   ├── number_system.py               
│   ├── geometry_system.py             
│   ├── agent_system.py                
│   └── social_system.py               
├── neocortex/                         # Phase 6a — Higher Cognition
│   ├── predictive_coding.py           
│   ├── prefrontal.py                  
│   ├── temporal.py                    
│   └── parietal.py                    
├── attention/                         # Phase 6b — Attention
│   ├── superior_colliculus.py         
│   ├── precision.py                   
│   └── competition.py                 
├── learning/                          # Phase 7 — One-Shot
│   ├── distortable_canvas.py          
│   ├── amgd.py                        
│   ├── one_shot_classifier.py         
│   └── hebbian.py                     
├── action/                            # Phase 8 — Motor
│   ├── active_inference.py            
│   ├── motor_primitives.py            
│   └── reflex_arc.py                  
├── agent/                             # Phase 9 — Integration
│   ├── brain.py                       
│   ├── mnist_agent.py                 
│   └── breakout_agent.py              
└── tests/                             # 8 test suites, 34+ tests passing
    ├── 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
```

---

## Tech Stack Audit

HippocampAIF is built intentionally with **zero deep learning frameworks** to maximize biological fidelity, deployment portability, and mathematical interpretability.

- **Language:** Python >= 3.10
- **Math Engine:** NumPy >= 1.24, SciPy >= 1.10
- **Image Processing:** Pillow >= 9.0
- **Linting and Diagnostics:** Pyre2 / Pyright explicit configurations
- **Version Control Optimizations:** `.gitattributes` generated for Git LFS (GitHub) and Xet Storage (Hugging Face)

---

## Setup

```powershell
# 1. Clone the repository
cd C:\Your\Workspace\Path

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

# 3. Activate the environment
.venv\Scripts\activate

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

# 5. Set the Python path explicitly
$env:PYTHONPATH = (Get-Location).Path
```

---

## Running Tests

The test suite validates the biological mechanics built into the architecture.

```powershell
# 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

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

---

## License and Citation

License: Proprietary
Author: Algorembrant, Rembrant Oyangoren Albeos
Year: 2026

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.