🧬 Biological Systems — Overview¶

Spector Memory doesn't just borrow neuroscience terminology — it implements the actual computational principles behind biological memory. Each package in spector-memory corresponds to a distinct brain region or cognitive mechanism, implementing the mathematical models that neuroscientists have validated over decades of research.

The Brain–Code Mapping¶

graph TB
    subgraph "Encoding & Storage"
        STE["🧩 Synapse<br/>Synaptic Tags & Scoring<br/><i>Bloom filter + binary layout</i>"]
        CT["🧠 Cortex<br/>4-Tier Memory Stores<br/><i>Working → Episodic → Semantic → Procedural</i>"]
    end

    subgraph "Emotional & Importance Modulation"
        DA["⚡ Dopamine<br/>Surprise Detection<br/><i>Welford Z-score → importance</i>"]
        AM["❤️ Amygdala<br/>Emotional Valence<br/><i>-128 to +127 coloring</i>"]
    end

    subgraph "Retrieval Dynamics"
        HB["🛑 Habituation<br/>Anti-Filter Bubble<br/><i>Repetition penalty</i>"]
        IN["🚫 Inhibition<br/>Suppression Set<br/><i>Inhibition of return</i>"]
        IF["🔀 Interference<br/>Deduplication<br/><i>Proactive/retroactive</i>"]
    end

    subgraph "Association & Learning"
        HE["🔗 3-Layer Cognitive Graph<br/>Hebbian + Entity + Temporal<br/><i>Off-heap graph structures</i>"]
    end

    subgraph "Consolidation & Planning"
        HP["💤 Hippocampus<br/>Sleep Consolidation<br/><i>ReflectDaemon cycle</i>"]
        PR["📋 Prospective<br/>Future Intents<br/><i>Scheduled reminders</i>"]
        MM["🔍 Metamemory<br/>Self-Reflection<br/><i>Confidence calibration</i>"]
    end

    DA --> STE
    AM --> STE
    STE --> CT
    CT --> HE
    HE --> HP

    style HE fill:#e74c3c,color:white
    style DA fill:#f39c12,color:white
    style HP fill:#9b59b6,color:white

Systems at a Glance¶

System	Brain Region	Key Concept	Spector Implementation	Reference
Cortex	Prefrontal, Hippocampus, Neocortex, Basal Ganglia	Multi-store memory model	4-tier off-heap stores (Working, Episodic, Semantic, Procedural)	Atkinson & Shiffrin, 1968¹
Synapse	Synaptic junction	Synaptic tagging & capture	64-bit Bloom filter tag encoding, 32B binary header	Frey & Morris, 1997²
Dopamine	Ventral tegmental area	Prediction error signaling	Welford Z-score surprise detection, flashbulb encoding	Schultz, 1997³
Amygdala	Amygdala	Emotional memory modulation	Signed valence byte (-128 to +127), emotional filtering	McGaugh, 2004⁴
3-Layer Graph	Cortical networks, Hippocampus	Hebbian learning, STDP, episodic sequences	Off-heap HebbianGraph, EntityGraph, TemporalChain	Hebb, 1949⁵; Bi & Poo, 2001⁶
Habituation	Sensory cortex	Response decrement to repetition	Exponential penalty on repeated recall	Thompson & Spencer, 1966⁷
Inhibition	Prefrontal cortex	Inhibition of return	SuppressionSet with TTL-based suppression windows	Klein, 2000⁸
Interference	Hippocampus	Proactive/retroactive interference	Similarity-based deduplication during ingestion	Underwood, 1957⁹
Hippocampus	Hippocampus	Sleep consolidation & replay	ReflectDaemon: decay, compaction, episodic→semantic promotion	Rasch & Born, 2013¹⁰
Prospective	Prefrontal cortex	Prospective memory	Scheduled future intent reminders	Einstein & McDaniel, 1990¹¹
Metamemory	Prefrontal cortex	Metacognitive monitoring	Confidence calibration, recall quality estimation	Nelson & Narens, 1990¹²
Sync	— (engineering)	Persistence & replication	WAL + mmap-backed partitions	—

Key Mathematical Models¶

Temporal Decay (Ebbinghaus Forgetting Curve)¶

Spector approximates the exponential forgetting curve using precomputed decay buckets — avoiding expensive Math.exp() calls in the hot loop:

\[R(t) = e^{-\lambda t / S}\]

Where \(R(t)\) is retrieval strength, \(\lambda\) is the decay rate, \(t\) is time since encoding, and \(S\) is storage strength. Spector discretizes this into 9 buckets (see Scoring Pipeline).

Reference: Ebbinghaus, H. (1885). Über das Gedächtnis¹³

Reconsolidation (Spacing Effect)¶

Each recall shifts the decay bucket backward, simulating how retrieved memories become more durable:

\[\text{adjustedBucket} = \text{rawBucket} - \lfloor \text{recallCount} / 3 \rfloor\]

Reference: Bjork & Bjork (1992). A New Theory of Disuse¹⁴

Surprise Detection (Dopamine Prediction Error)¶

The importance signal uses a Z-score from Welford's online statistics:

\[\text{importance} = \alpha \cdot \sigma\left(\frac{x - \mu}{\sigma}\right) + \beta \cdot \text{temporalNovelty}\]

Where \(\sigma()\) is the sigmoid function, \(\alpha = 0.6\), \(\beta = 0.4\).

Reference: Schultz, W. (1997). A neural substrate of prediction and reward³

Hebbian Edge Strengthening¶

Co-ingested memories strengthen their bidirectional edge:

\[w_{ij}(t+1) = w_{ij}(t) + \Delta w\]

With decay during consolidation: \(w_{ij}(t+1) = 0.9 \cdot w_{ij}(t)\)

Reference: Hebb, D.O. (1949). The Organization of Behavior⁵

STDP — Spike-Timing Dependent Plasticity¶

Directed causal edges are strengthened when tag A is recalled before tag B:

\[\Delta w = \begin{cases} A_+ \cdot e^{-\Delta t / \tau_+} & \text{if } \Delta t > 0 \text{ (causal)} \\ -A_- \cdot e^{\Delta t / \tau_-} & \text{if } \Delta t < 0 \text{ (anti-causal)} \end{cases}\]

Reference: Bi & Poo (2001). Synaptic modification by correlated activity⁶

Habituation Penalty¶

Repeated recall of the same memory incurs an exponentially increasing penalty:

\[\text{penalty}(n) = 1 - e^{-\gamma \cdot n}\]

Where \(n\) is the number of times the memory appeared in recent results and \(\gamma\) controls penalty steepness.

Reference: Thompson & Spencer (1966). Habituation: A model phenomenon⁷

Design Principles¶

Fidelity to neuroscience: Each system implements a real cognitive mechanism, not just a metaphor. The mathematical models are drawn from peer-reviewed research.
Independent testability: Each biological system is a standalone package with its own unit tests. Systems compose via dependency injection, not inheritance.
Graceful degradation: Every system is optional. Disabling surprise detection, habituation, or graph augmentation produces a functional (if less intelligent) memory system.
Performance-first biology: Biological accuracy is constrained by microsecond latency requirements. Where exact models are too expensive (e.g., continuous exponential decay), we use precomputed approximations (decay buckets, Bloom filter tags).

Explore Each System¶

Cortex — Tier Stores

Working, Episodic, Semantic, and Procedural memory tiers

Cortex
Synapse — Tags & Scoring

Bloom filter encoding, binary layout, 6-phase scorer

Synapse
:material-head-lightning-bolt:{ .lg .middle } Dopamine — Surprise

Welford Z-score, flashbulb encoding, importance scoring

Dopamine
Amygdala — Valence

Emotional coloring, valence-based filtering

Amygdala
3-Layer Cognitive Graph

Hebbian, Entity-Relationship, and Temporal Causal graphs

Cognitive Graph
Hippocampus — Consolidation

Sleep cycles, decay, episodic-to-semantic promotion

Hippocampus

References¶

Atkinson, R.C. & Shiffrin, R.M. (1968). Human memory: A proposed system and its control processes. In Psychology of Learning and Motivation, 2, 89–195. doi:10.1016/S0079-7421(08)60422-3 ↩
Frey, U. & Morris, R.G.M. (1997). Synaptic tagging and long-term potentiation. Nature, 385, 533–536. doi:10.1038/385533a0 ↩
Schultz, W. (1997). A neural substrate of prediction and reward. Science, 275(5306), 1593–1599. doi:10.1126/science.275.5306.1593 ↩↩
McGaugh, J.L. (2004). The amygdala modulates the consolidation of memories of emotionally arousing experiences. Annual Review of Neuroscience, 27, 1–28. doi:10.1146/annurev.neuro.27.070203.144157 ↩
Hebb, D.O. (1949). The Organization of Behavior: A Neuropsychological Theory. New York: Wiley. ↩↩
Bi, G. & Poo, M. (2001). Synaptic modification by correlated activity: Hebb's postulate revisited. Annual Review of Neuroscience, 24, 139–166. doi:10.1146/annurev.neuro.24.1.139 ↩↩
Thompson, R.F. & Spencer, W.A. (1966). Habituation: A model phenomenon for the study of neuronal substrates of behavior. Psychological Review, 73(1), 16–43. doi:10.1037/h0022681 ↩↩
Klein, R.M. (2000). Inhibition of return. Trends in Cognitive Sciences, 4(4), 138–147. doi:10.1016/S1364-6613(00)01452-2 ↩
Underwood, B.J. (1957). Interference and forgetting. Psychological Review, 64(1), 49–60. doi:10.1037/h0044616 ↩
Rasch, B. & Born, J. (2013). About sleep's role in memory. Physiological Reviews, 93(2), 681–766. doi:10.1152/physrev.00032.2012 ↩
Einstein, G.O. & McDaniel, M.A. (1990). Normal aging and prospective memory. Journal of Experimental Psychology: Learning, Memory, and Cognition, 16(4), 717–726. doi:10.1037/0278-7393.16.4.717 ↩
Nelson, T.O. & Narens, L. (1990). Metamemory: A theoretical framework and new findings. In Psychology of Learning and Motivation, 26, 125–173. doi:10.1016/S0079-7421(08)60053-5 ↩
Ebbinghaus, H. (1885). Über das Gedächtnis: Untersuchungen zur experimentellen Psychologie. Leipzig: Duncker & Humblot. English translation: Memory: A Contribution to Experimental Psychology (1913). ↩
Bjork, R.A. & Bjork, E.L. (1992). A new theory of disuse and an old theory of stimulus fluctuation. In From Learning Processes to Cognitive Processes: Essays in Honor of William K. Estes, 2, 35–67. ↩