🧬 Biological Systems — Overview¶

Spector Memory draws on computational neuroscience research to implement simplified, performance-optimized approximations of biological memory mechanisms. Each package in spector-memory maps to a neuroscience concept, implementing mathematical models inspired by peer-reviewed cognitive science — particularly Anderson's ACT-R architecture (1993) — and optimized for microsecond-scale agent memory operations.

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¶

Key Mathematical Models¶

Temporal Decay (Power Law of Forgetting)¶

Spector approximates the power law of forgetting using precomputed decay buckets — avoiding expensive Math.pow() calls in the hot loop:

Where \(R(t)\) is retrieval strength, \(t\) is time since encoding, and \(d\) is the configurable decay exponent (default: 0.15). Research since Wixted (2004) has established that forgetting follows a power law, not the exponential curve originally proposed by Ebbinghaus (1885). Spector discretizes this into 12 buckets spanning 5+ years, with a configurable permastore floor (default: 0.10) — see Scoring Pipeline).

References: Wixted, J.T. (2004). The psychology and neuroscience of forgetting¹⁵; Ebbinghaus, H. (1885). Über das Gedächtnis¹³

Reconsolidation (Spacing Effect)¶

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

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:

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:

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:

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

Scoring Formula (ACT-R Lineage)¶

Spector's core scoring formula is a simplified, hardware-optimized approximation of the ACT-R activation equation (Anderson, 1993):

Spector's approximation:

Where:

• Similarity ≈ ACT-R's spreading activation from current context
• Importance × decay ≈ ACT-R's base-level activation \(B_i\)
• \(S^{0.3}\) (storage strength) ≈ Bjork's two-factor model (1992)¹⁴
• α, β = relative weighting of context vs. base-level (default: 0.6, 0.4)

References: Anderson, J.R. (1993). Rules of the Mind¹⁶; Anderson, J.R. & Lebiere, C. (1998). The Atomic Components of Thought¹⁷

Habituation Penalty¶

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

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¶

1. Grounded in research: Each system implements a mathematical model inspired by peer-reviewed cognitive science, optimized for microsecond-scale agent memory operations. The scoring formula is a simplified, hardware-optimized approximation of the ACT-R activation equation (Anderson, 1993)¹⁶, with extensions for emotional valence (McGaugh, 2004)⁴ and storage strength (Bjork & Bjork, 1992)¹⁴.

2. Independent testability: Each biological system is a standalone package with its own unit tests. Systems compose via dependency injection, not inheritance.

3. Graceful degradation: Every system is optional. Disabling surprise detection, habituation, or graph augmentation produces a functional (if less intelligent) memory system.

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

References¶