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