🧠 Spector Memory¶

The Cognitive Memory Engine for Autonomous AI Agents.

A biologically-inspired, off-heap memory system that gives AI agents the ability to remember, forget, consolidate, and associate — with microsecond latency and zero garbage collection pressure. Built on Java Project Panama, SIMD-accelerated vector math, and Virtual Threads.

Why Cognitive Memory?¶

Traditional vector databases treat memories as static documents in a flat index. Real cognition is fundamentally different:

Traditional Vector DB	Spector Memory
Flat document store	4-tier cognitive architecture (Working → Episodic → Semantic → Procedural)
Static similarity search	Fused scoring — similarity × importance × temporal decay in a single SIMD pass
No temporal awareness	Reconsolidation — frequently recalled memories resist forgetting
No emotional context	Valence tracking — memories carry emotional coloring
No contextual gating	Synaptic tags — 64-bit Bloom filter eliminates 99% of candidates in 1 CPU cycle
Python + network hops	Zero-GC, off-heap Panama — microsecond latency, no serialization

Architecture¶

spector-memory/
├── SpectorMemory.java              ← Unified entry point for memory operations
├── pipeline/                       ← "Neural Pathways" — ingestion + recall pipelines
│     ├── IngestionPipeline.java        (10-step remember pipeline)
│     ├── RecallPipeline.java           (parallel tier scanning + scoring)
│     └── HebbianCoActivationListener   (Post-recall co-activation updater)
│
├── kernel/                         ← "Memory Kernel" — Memory<Layout> & Shapes
│     ├── Memory.java                   (Base interface)
│     ├── RegionPreamble.java           (On-disk SMKM region preamble)
│     ├── layout/                       (Layout types for records, entities, graphs)
│     └── shape/                        (RecordMemory, AppendMemory, GraphMemory, etc.)
│
├── cortex/                         ← "Cerebral Cortex" — 4 tier stores
│     ├── TierStore.java                (Tier storage interface)
│     ├── TierRouter.java               (Registry + polymorphic dispatch)
│     ├── WorkingMemoryStore.java       (Prefrontal Cortex — volatile circular buffer)
│     ├── EpisodicPartitionedMemory.java      (Hippocampus — time-partitioned mmap)
│     ├── SemanticMemoryStore.java      (Neocortex — single-file semantic storage)
│     ├── PartitionedSemanticStore.java (Neocortex — rolling partitioned semantic storage)
│     ├── StorageMigrator.java          (Single-file → partitioned migration)
│     └── ProceduralMemoryStore.java    (Basal Ganglia — learned procedures)
│
├── synapse/                        ← "Synaptic Machinery" — header layout + scoring
│     ├── EngramLayout.java    (64-byte cache-line-aligned synaptic header)
│     ├── CognitiveScorer.java          (6-phase fused scoring hot-loop)
│     ├── SynapticTagEncoder.java       (64-bit inline Bloom filter)
│     ├── EncodingHeaderFields.java     (offsets, masks, field sizes)
│     ├── TemperatureSoftmax.java       (numerically stable retrieval temperature)
│     └── DecayStrategy.java            (SIMD-friendly temporal decay)
│
├── dopamine/                       ← "Dopamine System" — surprise & importance
│     ├── SurpriseDetector.java         (Welford online statistics + Z-score)
│     ├── FlashbulbPolicy.java          (extreme surprise → pinned memory)
│     └── WelfordStats.java             (running mean/variance tracker)
│
├── amygdala/                       ← "Amygdala" — emotional valence
│     └── ValenceTracker.java           (emotional coloring of memories)
│
├── hebbian/                        ← "Hebbian Learning" — associations
│     ├── CoActivationTracker.java      (tag co-occurrence tracking)
│     └── HebbianGraph.java             (associative memory network)
│
├── graph/                          ← "Entity-Relationship Graph" + temporal
│     ├── HyperEntityGraphMemory.java   (hypergraph entity storage)
│     ├── EntityType.java               (21 well-known entity types)
│     ├── TypeRegistryMemory.java       (open-schema string ↔ int registry)
│     ├── TemporalChainMemory.java      (session-linked causal sequences)
│     └── LlmEntityExtractor.java       (LLM entity extraction SPI impl)
│
├── hippocampus/                    ← "Hippocampus" — consolidation & cleanup
│     ├── ReflectPathway.java           (sleep consolidation & reflection)
│     └── VacuumCompactor.java         (physical tombstone compaction)
│
├── habituation/                    ← "Habituation" — anti-filter bubble
│     └── HabituationPenalty.java       (frequency-based score decay)
│
├── inhibition/                     ← "Inhibition" — suppression
│     └── SuppressionSet.java           (explicit memory blocking)
│
├── prospective/                    ← "Prospective Memory" — future intents
│     ├── ProspectiveScheduler.java     (time-triggered reminders)
│     └── Reminder.java                 (scheduled memory record)
│
├── metamemory/                     ← "Metamemory" — self-reflection
│     └── MemoryIntrospector.java       (memory health stats & analytics)
│
├── index/                          ← O(1) reverse index
│     └── MemoryIndex.java              (ConcurrentHashMap forward + reverse)
│
└── sync/                           ← Persistence & replication
      ├── MemoryWal.java                (Write-Ahead Log)
      └── CrdtMergeStrategy.java        (CRDT merge for distributed sync)

Biological System → Package Mapping¶

Brain Region	Package	Java Classes	Function
💾 Sub-cortical Core	`kernel/`	`Memory`, `RegionPreamble`, `MemoryShape`	Core Panama storage abstractions (RecordMemory, AppendMemory, etc.)
🧠 Cerebral Cortex	`cortex/`	`TierRouter`, `TierStore`, 4 stores	4-tier memory storage (Working → Episodic → Semantic → Procedural)
🔗 Synapses	`synapse/`	`CognitiveScorer`, `SynapticTagEncoder`, `EngramLayout`	64-byte header, 6-phase scoring, Bloom filter gating
⚡ Dopamine System	`dopamine/`	`SurpriseDetector`, `FlashbulbPolicy`	Surprise detection, auto-importance, flashbulb pinning
😱 Amygdala	`amygdala/`	`ValenceTracker`	Emotional coloring (positive/negative/neutral)
🔄 Hebbian Learning	`hebbian/`	`CoActivationTracker`, `HebbianGraph`	"Neurons that fire together wire together"
🔗 Entity Knowledge	`graph/`	`EntityGraph`, `TypeRegistry`, `LlmEntityExtractor`	LLM-powered entity-relationship graph with open-schema types
⏳ Temporal Chain	`graph/`	`TemporalChain`	Session-linked causal sequences ("what happened next?")
🛏️ Hippocampus	`hippocampus/`	`ReflectDaemon`, `VacuumCompactor`	Sleep consolidation, synaptic pruning, tombstone compaction
😴 Habituation	`habituation/`	`HabituationPenalty`	Anti-filter bubble — penalizes repetitive recall
🚫 Inhibition	`inhibition/`	`SuppressionSet`	Explicit memory suppression (user redaction)
🔮 Prospective Memory	`prospective/`	`ProspectiveScheduler`, `Reminder`	Future-oriented intent reminders
🪞 Metamemory	`metamemory/`	`MemoryIntrospector`	Self-reflective memory health analytics

Spector Memory Kernel (SMK)¶

Spector Memory uses a unified Memory Kernel abstraction (Memory<Layout>) that standardizes all persistent and volatile storage structures using Project Panama's Foreign Function & Memory API. Rather than implementing individual binary layouts from scratch, every subsystem maps to a standardized kernel Shape:

RecordMemory: Fixed-size contiguous slots used by the cognitive tiers (Working, Semantic, and Procedural stores) and CoActivationTracker. Partitioning across episodic bundles is managed by PartitionManager (the legacy monolithic PartitionedRecordMemory shape was retired in favor of modular PartitionBundle files per ADR-0002).
AppendMemory: Append-only log arrays with cursor offsets, backing TextDataStore and the Write-Ahead Log.
RegistryMemory: Open-schema string-to-int mapping used for metadata serialization (TypeRegistry).
GraphMemory: CSR (Compressed Sparse Row) and slab-allocated structures backing the EntityGraph and HebbianGraph.
ChainMemory: Causal sequence structures backing the TemporalChain.

All memory operations are journaled to the WAL at the kernel shape level, enabling complete state reconstruction on startup via WalRecoveryDispatcher.

Quick Start¶

// 1. Create a cognitive memory with Ollama embeddings
SpectorMemory memory = SpectorMemory.builder()
    .dimensions(4096)
    .embeddingProvider(OllamaEmbeddingProvider.create("qwen3-embedding"))
    .workingCapacity(100)
    .episodicPartitionCapacity(10_000)
    .nodesPerPartition(10_000)         // Semantic partition capacity (rolling files)
    .semanticCapacity(5_000)           // Single-file fallback capacity
    .proceduralCapacity(500)
    .build();

// 2. Remember — 10-step ingestion pipeline
memory.remember("pref-dark-mode",
    "The user strongly prefers dark mode for all IDE editors.",
    MemoryType.EPISODIC, MemorySource.USER_STATED,
    "ui", "preferences", "coding");

// 3. Recall — parallel SIMD-accelerated search with cognitive scoring
List<CognitiveResult> results = memory.recall("dark theme settings",
    RecallOptions.builder()
        .topK(5)
        .synapticFilter("preferences")    // Bloom filter pre-screen
        .minImportance(0.3f)              // Skip low-importance memories
        .build());

for (CognitiveResult r : results) {
    System.out.printf("%.4f [%s] %s%n", r.score(), r.memoryType(), r.text());
}

// 4. Forget — tombstone a memory
memory.forget("pref-dark-mode");

// 5. Suppress — temporarily hide from recall
memory.suppress("noisy-memory-id", "Not relevant right now");

// 6. Close — releases all off-heap memory
memory.close();

The 6-Phase Scoring Pipeline¶

Every recall query executes a SIMD-optimized hot-loop that fuses six filtering and scoring phases into a single sequential scan. Each phase eliminates candidates before the expensive vector math:

Phase 1: Tombstone Check     (~1 cycle)    → Skip dead memories
Phase 2: Synaptic Tag Gating (~1 cycle)    → Bloom filter eliminates 99% of irrelevant
Phase 3: Valence Filter      (~2 cycles)   → Emotional range filtering
Phase 4: Importance/Decay    (~5 cycles)   → Skip old + low-importance
Phase 5: SIMD L2 Distance   (~200 cycles)  → Quantized INT8 Euclidean via Vector API
Phase 6: Fused Score         (~7 cycles)   → α·similarity + β·importance·decay

The math: If an agent has 1,000,000 episodic memories but only 10,000 match the active synaptic tags:

Phases 1-4 eliminate 990,000 memories in ~990µs (cheap header reads)
Phase 5 computes SIMD distance on only ~10,000 candidates
Total: Ultra-fast in-process scan vs ~200ms without gating

Performance¶

Benchmarked on Intel Core Ultra 9 285K, Java 25, AVX2 256-bit:

Benchmark	Result
SIMD L2 Distance (768-dim)	2.2 µs/vector (1.4M vectors/sec)
SIMD L2 Distance (128-dim)	0.8 µs/vector (1.2M vectors/sec)
Reverse Index Lookup	180 ns/lookup (O(1) via ConcurrentHashMap)
CognitiveScorer (10K × 128-dim)	2.9 ms total
Batch Habituation (1K IDs)	101 µs total
Full Pipeline (1K ingest + 100 recall)	< 50 ms/query
Real Embedding (qwen3-embedding 4096-dim)	31 ms/embed via Ollama

Test Suite¶

spector-core:   276 tests ✅  (includes 15 SIMD kernel tests)
spector-memory: 167 tests ✅  (includes 33 perf + index tests)
                + 10 Ollama real embedding E2E tests (gated by OLLAMA_LIVE=true)
Total: 443 tests, 0 failures

Competitive Landscape¶

Feature	Spector Memory	Mem0	Letta (MemGPT)	Zep
Language	Java 25	Python	Python	Go/Python
Storage	Off-heap Panama	Postgres/pgvector	Postgres/Chroma	Postgres
Latency	Ultra-low latency	~50-200ms	~100-500ms	~20-100ms
GC Pressure	Zero	Python GC	Python GC	Go GC
Temporal Decay	Fused SIMD	Post-filter	Post-filter	Post-filter
Emotional Valence	✅ Built-in	❌	❌	❌
Synaptic Tag Gating	✅ 1-cycle Bloom	❌	❌	❌
Sleep Consolidation	✅ K-Means	❌	❌	❌
Entity Knowledge Graph	✅ LLM-powered, open-schema	❌	❌	❌
Temporal Causal Chains	✅ Session-linked	❌	❌	❌
Surprise Detection	✅ Welford Z-score	❌	❌	❌
Habituation	✅ Anti-filter bubble	❌	❌	❌
MCP Integration	✅ Native	❌	❌	❌

Documentation¶

📖 Full documentation: See the Cognitive Memory Guide for:

System Architecture — package hierarchy, data flow, subsystem architecture
6-Phase Scoring Pipeline — deep dive with math and cycle counts
Biological Systems — each brain region mapped to code
Performance & SIMD — benchmarks, optimization techniques
Off-Heap Panama Design — zero-GC architecture
API Reference — full method signatures

License¶

This module is licensed under the Apache License, Version 2.0.

See the LICENSE file for the full terms and conditions.

Built with ⚡ by Spectrayan