🧠 Cognitive Memory¶

Persona, Dream, Wander, Decide, Express are experimental — see Experimental pathways.

The 4-Tier Memory Architecture¶

Rather than treating memory as an undifferentiated vector store, Spector organizes traces across four cognitive tiers to address distinct operational retention windows, access frequencies, and consolidation dynamics:

🧭 Which Memory Tier & Pathway Do I Need?¶

Choosing the right memory tier ensures optimal signal-to-noise ratio, hardware cache efficiency, and retention physics. Use this interactive decision tree and comparison matrix to select the right tier and retrieval pathway for your agent:

flowchart TD
    START(["🧠 Ingesting or Recalling Knowledge"]) --> Q1{"What is the operational lifecycle of this trace?"}

    Q1 -->|"Current prompt / dialogue turn<br/>(Volatile buffer)"| T_WM["🧪 Working Memory<br/><b>rememberWorking(...)</b><br/>• Circular volatile buffer<br/>• Sub-microsecond seek<br/>• Auto-evicts oldest entries"]
    Q1 -->|"Timestamped event / agent action<br/>(Autobiographical journal)"| T_EM["📝 Episodic Memory<br/><b>rememberEpisodic(...)</b><br/>• Daily memory-mapped partition<br/>• Power-law temporal decay<br/>• Consolidated during sleep"]
    Q1 -->|"Distilled fact / user preference<br/>(Permanent world knowledge)"| T_SE["🧬 Semantic Memory<br/><b>rememberSemantic(...)</b><br/>• Zero-GC off-heap partitions<br/>• Parallel SIMD vector scan<br/>• Enduring cross-session facts"]
    Q1 -->|"Operational rule / tool constraint<br/>(Behavioral guidelines)"| T_PR["⚙️ Procedural Memory<br/><b>rememberProcedural(...)</b><br/>• Append-only WAL store<br/>• Deterministic constraint check<br/>• Pinned across all sessions"]

    T_WM --> P_SELECT{"How will this trace be queried?"}
    T_EM --> P_SELECT
    T_SE --> P_SELECT
    T_PR --> P_SELECT

    P_SELECT -->|"Associative cue + temporal context"| PW_FUSED["⚡ 6-Phase Fused Recall<br/>Bloom filter + valence + decay + SIMD distance"]
    P_SELECT -->|"Direct pointer / known Engram ID"| PW_DIRECT["🎯 Direct Engram Seek<br/>Zero-allocation offset seek (~150ns)"]
    P_SELECT -->|"Entity relationship or causal flow"| PW_GRAPH["🕸️ Cognitive Graph Recall<br/>Hebbian association + Temporal chains"]
    P_SELECT -->|"Corroboration from multiple events"| PW_MULTI["🔍 Multi-Evidence Recall<br/>Cross-episode fact synthesis & clustering"]

    classDef working fill:#2563eb18,stroke:#3b82f6,stroke-width:1.5px
    classDef episodic fill:#10b98118,stroke:#10b981,stroke-width:1.5px
    classDef semantic fill:#8b5cf618,stroke:#8b5cf6,stroke-width:1.5px
    classDef procedural fill:#f59e0b18,stroke:#f59e0b,stroke-width:1.5px

    class T_WM working
    class T_EM episodic
    class T_SE semantic
    class T_PR procedural

Tier Decision Matrix¶

Cognitive Architecture Mapping¶

As established in the Memory Fundamentals Specification (MF-001), Spector models cognitive subsystems as concrete operational mechanisms addressing specific retrieval and retention requirements:

graph TB
    subgraph "🧠 Spector Memory"
        SM[SpectorMemory<br/>Façade]:::core --> CT[RememberPathway<br/>Pathway: Remember]:::core
        SM --> RP[RecallPathway<br/>Pathway: Recall]:::core

        subgraph "Cortex — Tier Stores"
            NK[NamespaceKernel<br/>EngramMemory]:::core --> WM[Working<br/>Working tier]:::working
            NK --> EM[Episodic<br/>Episodic tier]:::episodic
            NK --> SE[Semantic<br/>Semantic tier]:::semantic
            NK --> PR[Procedural<br/>Procedural tier]:::procedural
        end

        subgraph "Synapse — Scoring"
            CS[CognitiveScorer<br/>6-phase SIMD]:::synapse --> STE[SynapticTagEncoder<br/>Bloom Filter]:::synapse
            CS --> DS[DecayStrategy<br/>Temporal Decay]:::synapse
        end

        subgraph "Neuromodulators"
            SD[SurpriseDetector<br/>Dopamine]:::synapse --> FP[FlashbulbPolicy]:::synapse
            VT[ValenceTracker<br/>Amygdala]:::synapse
            HP[HabituationPenalty<br/>Anti-filter bubble]:::synapse
            SS[SuppressionSet<br/>Inhibition]:::synapse
        end

        subgraph "3-Layer Cognitive Graph"
            HG[HebbianGraph<br/>Layer 1: Association]:::core
            TC[TemporalChain<br/>Layer 2: Causal]:::core
            HEG[HyperEntityGraph<br/>Layer 3: Event-Episode]:::core
            ED[EntityDirectory<br/>Identity Registry]:::core
            CA[CoActivationMemory<br/>STDP Learning]:::core
        end

        subgraph "Consolidation"
            RD[ReflectDaemon<br/>Reflect Consolidation]:::core
            TCC[VacuumCompactor<br/>Tombstone census only]:::core
        end

        CT --> NK
        RP --> CS
        RP --> NK
        RP --> HG
        RP --> TC
        RP --> ED
        RP --> HEG
    end

What Makes This Different¶

Every AI memory solution today wraps a scripting layer around Postgres/pgvector or a standard vector database. They suffer from:

• Network latency: 50-200ms per query (HTTP → DB → HTTP)
• Global Interpreter Lock: Sequential embedding and scoring under a lock
• The truncation trap: Candidate generation by a single signal (typically cosine top-K) followed by post-filtering, permanently dropping high-importance or emotionally salient memories with lower initial cosine similarity.

Spector Memory collapses the entire cognitive stack onto a zero-overhead, off-heap memory store with hardware-accelerated scoring. The result:

† Measured on Intel Core Ultra 9 285K, Java 25, AVX2. See Benchmarks.

Explore the Documentation¶