File size: 9,109 Bytes
32d978d | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 | ---
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)
[](#tech-stack-audit)
[](#running-tests)
[](#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.
|