A Biologically Grounded Cognitive Architecture for One-Shot Learning and Active Inference.
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:
1flowchart TD
2 classDef default fill:#f9f9f9,stroke:#333,stroke-width:1px
3
4 PFC["Prefrontal Cortex (PFC)\nWorking memory (7 +/- 2)\nExecutive control\nGoal stack"]
5
6 TC["Temporal Cortex\nRecognition\nCategories\nSemantic mem."]
7 PC["Predictive Coding\nFriston Box 3\nFree-energy min\nError signals"]
8 PAR["Parietal Cortex\nPriority maps\nCoord. transforms\nSensorimotor"]
9
10 SC["Superior Colliculus\nSaccade"]
11 PM["Precision Modulator"]
12 BC["Biased Compete"]
13
14 subgraph Hippocampus ["H I P P O C A M P U S"]
15 direction LR
16 DG["DG\nSeparate"] --> CA3["CA3\nComplete"]
17 CA3 --> CA1["CA1\nMatch"]
18 CA1 --> IM["Index Memory\nFast-binding"]
19 EC["Entorhinal EC\nGrid cells"]
20 RB["Replay Buffer\nConsolidation"]
21 end
22
23 subgraph VisualCortex ["V I S U A L C O R T E X"]
24 direction LR
25 V1S["V1 Simple\nGabor"] --> V1C["V1 Complex\nMax-pooling"]
26 V1C --> HMAX["HMAX Hierarchy\nV2->V4->IT"]
27 end
28
29 subgraph RetinaData ["R E T I N A"]
30 direction LR
31 PR["Photoreceptors\nAdaptation"]
32 GAN["Ganglion\nDoG"]
33 STE["Spatiotemporal\nMotion energy"]
34 end
35
36 SENSES["SENSES\n=================\nraw image"]
37
38 subgraph CoreKnowledge ["C O R E K N O W L E D G E (Innate, Not Learned)"]
39 direction LR
40 OBJ["Objects\nPerm/Coh"]
41 PHY["Physics\nGravity"]
42 NUM["Number\nANS/Sub"]
43 GEO["Geometry\nCanvas"]
44 AGT["Agent\nGoals"]
45 SOC["Social\nHelper"]
46 end
47
48 subgraph ActionSystem ["A C T I O N S Y S T E M"]
49 direction LR
50 ACTI["Active Inference\na = -dF/da\nExpected FE min."]
51 MOT["Motor Primitives\nL/R/Fire"]
52 REF["Reflex Arc\nTrack"]
53 end
54
55 PFC -->|"top-down control"| TC
56 PFC -->|"top-down control"| PC
57 PFC -->|"top-down control"| PAR
58
59 PC --> TC
60 PC --> PAR
61
62 TC --> SC
63 PC --> PM
64 PAR --> BC
65
66 SC --> Hippocampus
67 PM -->|"attention"| Hippocampus
68 BC --> Hippocampus
69
70 Hippocampus -->|"features"| VisualCortex
71 VisualCortex -->|"ON/OFF sparse"| RetinaData
72 RetinaData --> SENSES
1hippocampaif/
2├── __init__.py
3├── core/ # Phase 1 — Foundation
4│ ├── tensor.py
5│ ├── free_energy.py
6│ ├── message_passing.py
7│ └── dynamics.py
8├── retina/ # Phase 2 — Eye
9│ ├── photoreceptor.py
10│ ├── ganglion.py
11│ └── spatiotemporal_energy.py
12├── v1_v5/ # Phase 3 — Visual Cortex
13│ ├── gabor_filters.py
14│ ├── sparse_coding.py
15│ └── hmax_pooling.py
16├── hippocampus/ # Phase 4 — Memory
17│ ├── dg.py
18│ ├── ca3.py
19│ ├── ca1.py
20│ ├── entorhinal.py
21│ ├── index_memory.py
22│ └── replay.py
23├── core_knowledge/ # Phase 5 — Innate Priors
24│ ├── object_system.py
25│ ├── physics_system.py
26│ ├── number_system.py
27│ ├── geometry_system.py
28│ ├── agent_system.py
29│ └── social_system.py
30├── neocortex/ # Phase 6a — Higher Cognition
31│ ├── predictive_coding.py
32│ ├── prefrontal.py
33│ ├── temporal.py
34│ └── parietal.py
35├── attention/ # Phase 6b — Attention
36│ ├── superior_colliculus.py
37│ ├── precision.py
38│ └── competition.py
39├── learning/ # Phase 7 — One-Shot
40│ ├── distortable_canvas.py
41│ ├── amgd.py
42│ ├── one_shot_classifier.py
43│ └── hebbian.py
44├── action/ # Phase 8 — Motor
45│ ├── active_inference.py
46│ ├── motor_primitives.py
47│ └── reflex_arc.py
48├── agent/ # Phase 9 — Integration
49│ ├── brain.py
50│ ├── mnist_agent.py
51│ └── breakout_agent.py
52└── tests/ # 8 test suites, 34+ tests passing
53 ├── test_core.py
54 ├── test_retina.py
55 ├── test_visual_cortex.py
56 ├── test_hippocampus.py
57 ├── test_core_knowledge.py
58 ├── test_neocortex_attention.py
59 ├── test_learning.py
60 └── test_action.py
1# 1. Clone the repository
2cd C:\Your\Workspace\Path
3
4# 2. Create the virtual environment
5python -m venv .venv
6
7# 3. Activate the environment
8.venv\Scripts\activate
9
10# 4. Install dependencies
11pip install -r requirements.txt
12
13# 5. Set the Python path explicitly
14$env:PYTHONPATH = (Get-Location).Path
The test suite validates the biological mechanics built into the architecture.
1# Core, Retina, Visual Cortex, Hippocampus
2python -m hippocampaif.tests.test_core
3python -m hippocampaif.tests.test_retina
4python -m hippocampaif.tests.test_v1_v5
5python -m hippocampaif.tests.test_hippocampus
6
7# Core Knowledge, Neocortex, Learning, Action
8python -m hippocampaif.tests.test_core_knowledge
9python -m hippocampaif.tests.test_neocortex_attention
10python -m hippocampaif.tests.test_learning
11python -m hippocampaif.tests.test_action
1@software{hippocampaif2026,
2 author = {Albeos, Rembrant Oyangoren},
3 title = {HippocampAIF: Biologically Grounded Cognitive Architecture},
4 year = {2026},
5 description = {Free-energy minimization + hippocampal fast-binding +
6 Spelke's core knowledge for one-shot learning and active inference}
7}
