🧠 Cognitive Memory

The Vision

Legacy AI frameworks bolt memory onto flat vector databases. Spector Memory is designed from the ground up as a cognitive memory engine — a biologically-inspired system where memories have importance, emotions, temporal decay, and contextual tags. It's the difference between a filing cabinet and a brain.

---

What Makes This Different

Every AI memory solution today — Mem0, Letta (MemGPT), Zep — wraps a Python layer around Postgres/pgvector or ChromaDB. They suffer from:

• Network latency: 50-200ms per query (HTTP → Postgres → HTTP)
• Python GIL: Sequential embedding + scoring under a global lock
• Post-filtering trap: Retrieve top-K by similarity, then filter by importance/time — losing critical memories that are old but vital

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

Metric	Python Memory Layer	Spector Memory
Query latency (1M memories)	50-200ms	0.13ms †
GC pauses	Unpredictable	≤0.01% (100% off-heap) †
Scoring pipeline	Post-filter (lossy)	Fused SIMD (lossless)
Concurrent queries	GIL-limited	61,000 QPS (Virtual Threads) †
Memory per record	~500B (Python objects)	32B header + quantized vector

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

---

The Biological Metaphor

Spector Memory maps every major cognitive subsystem from neuroscience to a dedicated Java package:

graph TB
    subgraph "🧠 Spector Memory"
        SM[SpectorMemory<br/>Façade] --> CT[CognitiveIngestionTarget<br/>Cognitive remember]
        SM --> RP[RecallPipeline<br/>Parallel recall]

        subgraph "Cortex — Tier Stores"
            TR[TierRouter] --> WM[Working<br/>Prefrontal Cortex]
            TR --> EM[Episodic<br/>Hippocampus]
            TR --> SE[Semantic<br/>Neocortex]
            TR --> PR[Procedural<br/>Basal Ganglia]
        end

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

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

        subgraph "3-Layer Cognitive Graph"
            HG[HebbianGraph<br/>Layer 1: Association]
            EG[EntityGraph<br/>Layer 2: Knowledge]
            TC[TemporalChain<br/>Layer 3: Causal]
            CA[CoActivationTracker<br/>STDP Learning]
        end

        subgraph "Consolidation"
            RD[ReflectDaemon<br/>Sleep Consolidation]
            TCC[TombstoneCompactor<br/>Synaptic Pruning]
        end

        CT --> TR
        RP --> CS
        RP --> TR
        RP --> HG
        RP --> TC
        RP --> EG
    end

---

The 4-Tier Memory Architecture

Just as the human brain has distinct memory systems, Spector organizes memories into four cognitive tiers:

🧪 Working Memory📝 Episodic Memory🧬 Semantic Memory⚙️ Procedural Memory

Biological analog: Prefrontal Cortex

Volatile, limited-capacity buffer for the current task context. Circular buffer — oldest entries are evicted when full.

• Capacity: Configurable (default: 100 records)
• Storage: In-memory Arena.ofShared() segment
• Use case: "What was the user just talking about?"

Biological analog: Hippocampus

Time-stamped event records. Partitioned by day, backed by mmap'd files for persistence across JVM restarts. Supports sleep consolidation into semantic memory.

• Capacity: Unbounded (partitioned, mmap-backed)
• Storage: FileChannel.map() with 64-byte metadata header per partition
• Use case: "What error did we debug yesterday?"

Biological analog: Neocortex

Distilled, permanent knowledge. Created by sleep consolidation (ReflectDaemon) from episodic clusters, or directly by the user.

• Capacity: Configurable (default: 5,000 records)
• Storage: Header-only slab (fast metadata scan)
• Use case: "The user prefers dark mode."

Biological analog: Basal Ganglia

Learned procedures, rules, and patterns. Small, append-only store for procedural knowledge.

• Capacity: Configurable (default: 500 records)
• Storage: In-memory Arena.ofShared() segment
• Use case: "Always use exponential backoff for retries."

---

Explore the Documentation

• System Architecture

  ---

  Package hierarchy, data flow diagrams, and extensibility model

  Architecture

• 6-Phase Scoring Pipeline

  ---

  Deep dive into the SIMD hot-loop: tombstone → tags → valence → importance → L2 → fused score

  Scoring Pipeline

• 3-Layer Cognitive Graph

  ---

  Hebbian association, entity-relationship knowledge, and temporal causal chains — three off-heap graph structures that augment vector recall

  Cognitive Graph

• Biological Systems

  ---

  Each brain region mapped to code: Cortex, Hippocampus, Synapse, Dopamine, Amygdala, Habituation, Inhibition

  Start with Cortex

• Performance & SIMD

  ---

  Benchmark results, SIMD kernel throughput, optimization techniques, virtual thread scaling

  Performance

• Off-Heap Panama Design

  ---

  Zero-GC architecture, MemorySegment lifecycle, mmap partitions, 32-byte CognitiveRecord binary format

  Panama Design

• API Reference

  ---

  SpectorMemory.Builder, RecallOptions, CognitiveResult, MemoryType — full method signatures

  API Reference