Skip to content

Memory

Jump to bottom
github-actions[bot] edited this page Jun 9, 2026 · 6 revisions

🧠 Cognitive Memory

quote: 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) 64B 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
Loading

The 4-Tier Memory Architecture

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

🧪 Working 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?"

📝 Episodic Memory

**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?"

🧬 Semantic Memory

**Biological analog: Neocortex**

Distilled, permanent knowledge. Created by sleep consolidation (ReflectDaemon) from episodic clusters, or directly by the user. Supports two storage modes:

- **Single-file** (in-memory mode): Fixed-capacity slab via `Arena.ofShared()`
- **Partitioned** (DISK mode, default): Rolling `semantic-NNN.mem` files with parallel per-partition recall via virtual threads

- **Capacity**: Unbounded in partitioned mode (configurable per-partition, default: 10,000 records)
- **Recall**: Parallel scan — each partition searched on its own virtual thread
- **Compaction**: Per-partition rebuild (live during operation)
- **Migration**: Auto-migrates from single-file on first startup
- **Use case**: "The user prefers dark mode."

⚙️ Procedural Memory

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

🏠 Home

Clone this wiki locally