Legacy AI architectures bolted memory onto stateless vector databases. Spector is designed from the ground up for modern AI as a unified cognitive memory backbone — leveraging Java Project Panama to achieve C++ bare-metal SIMD speeds natively across dense vector similarity, BM25 keyword matching, SPLADE learned sparse retrieval, and associative Hebbian graph memory, with a built-in MCP server that turns any AI agent into a memory-augmented reasoning machine.

System Architecture & Data Flow

Spector is structured around a modular, biologically-inspired architecture designed to bridge low-level bare-metal SIMD operations with high-level agent orchestration:

  • Nucleus (Foundation): Core configurations, off-heap storage layouts (Panama MemorySegment), and standard utilities.
  • Memory (Cognitive Engine): The flagship hybrid retrieval and cognitive memory system combining dense vector, sparse (SPLADE/Li-LSR), keyword (BM25), 4-layer cognitive graph, and sleep consolidation pipelines.
  • Synapse (Gateway & APIs): Spring Boot entry points, Armeria-based REST/gRPC gateways, and stdio/HTTP Model Context Protocol (MCP) servers.
  • Cortex (UI): Three.js and Angular-powered neural dashboard for real-time visualization of memory graphs, decay, and search metrics.

For a comprehensive analysis of the system architecture, data flows, thread scheduling model, and detailed Mermaid diagrams, see the Architecture Overview Docs.

🤖 MCP-Native — Built for AI Agents

Spector is an MCP-native cognitive memory — not an afterthought adapter. The MCP server runs in-process with the memory system (zero network, zero serialization), giving agents direct SIMD-accelerated access to 16 tools across memory storage, recall, and introspection.

Why MCP-Native Matters

Spector (MCP-native) Typical MCP adapter
Architecture Memory + MCP in one JVM Python wrapper → HTTP → DB
Memory recall 0.13ms (fused scoring) 50–200ms (Mem0/Letta/Zep)
Tools 16 (cognitive memory tools) 3–5 basic CRUD
Cognitive features Decay, Hebbian, consolidation, valence Key-value store
GC pressure Zero (Panama off-heap) Full GC overhead

🧠 Cognitive Memory — AI Agents That Actually Remember

Spector Memory is a biologically-inspired cognitive memory system that gives AI agents the ability to remember, forget, consolidate, and associate — with microsecond latency and zero garbage collection pressure.

Capability What it does
🧠 4-Tier Cortex Working → Episodic → Semantic → Procedural memory
⚡ 0.13ms recall at 1M memories 15× faster than the 2ms target (vs. 50–200ms for Mem0/Letta/Zep)
🔗 Fused SIMD Scoring Similarity × importance × decay in a single pass — no truncation trap
🛏️ Sleep Consolidation Hippocampus-inspired pruning and partition rebuild
😱 Emotional Valence Amygdala-driven positive/negative/neutral tagging
🚫 Zero GC 100% off-heap Panama storage (≤0.01% overhead measured)

📖 Full Cognitive Memory Documentation →

✨ Key Capabilities

Capability Technology Performance / Specifications
🤖 Agent-Native (MCP) Model Context Protocol · 16 tools · stdio + Streamable HTTP Claude · Cursor · autonomous agents
⚡ SIMD Scoring Java Vector API (AVX2/AVX-512/NEON) 0.13ms p50 recall
🧊 Off-Heap Storage Panama MemorySegment · zero-copy I/O 0.01% GC overhead
🗜️ Quantization SVASQ-8/4 · IVF-PQ · FWHT rotation 4–32× compression · 99.5% recall
🔍 Hybrid Retrieval 4-Layer Stack: Dense HNSW + BM25 + SPLADE / Li-LSR + ColBERT v2 Multi-way RRF fusion + MaxSim SIMD reranking
📄 Off-Heap Doc Store Encrypted TextDataStore (AES-256-GCM) Zero-copy mmap'd readTextDirect · zero GC pressure
🔗 Cognitive Graphs Hebbian co-activation + LLM Entity Graphs Spreading activation, temporal chains & entity links
🎛️ Retrieval Modes 8 TextSearchMode paths (HYBRID, FULL_STACK, etc.) Graceful degradation & flexible query optimization
🖥️ GPU Acceleration CUDA via Panama FFM Optional · zero-copy transfer
📦 Flexible Deployment Embedded JAR · Standalone · Distributed Zero to cluster in one config

📸 Demo

🚀 Quick Start

Prerequisites: JDK 25+, Maven 3.9+

git clone https://github.com/spectrayan/spector.git
cd spector
mvn clean test                                        # Build & run all 685+ tests
mvn package -pl spector-dist -am -DskipTests          # Build the distribution JAR

Start the MCP server (for AI agents):

java --add-modules jdk.incubator.vector \
  --enable-native-access=ALL-UNNAMED --enable-preview \
  -jar spector-dist/target/spector.jar \
  --config spector.yml

Claude Desktop config — add to claude_desktop_config.json:

{
  "mcpServers": {
    "spector": {
      "command": "java",
      "args": [
        "--add-modules", "jdk.incubator.vector",
        "--enable-native-access=ALL-UNNAMED",
        "--enable-preview",
        "-jar", "/path/to/spector-dist/target/spector.jar",
        "--config", "/path/to/spector.yml"
      ]
    }
  }
}

📖 Full Quick Start Guide → · Configuration Reference →

📊 Benchmarks

All numbers measured on Intel Core Ultra 9 285K, Java 25, AVX2 256-bit.

Benchmark Result Notes
Vector search p50 88–143µs 10K–100K docs, HNSW M=16
Cognitive recall at 1M 0.13ms p50 15× better than 2ms target
Peak QPS (16 threads) 61,011 Concurrent vectorSearch
GC overhead 0.01% 1 pause / 100K searches
vs. Python MCP servers 23–113× faster In-process SIMD, zero network

📖 Full Benchmark Report → · Performance Tuning →

📖 Documentation

I want to... Start here
Use Spector Quick Start · Installation · Configuration
Contribute to Spector Developer Guide · Contributing
Connect an AI agent MCP Server Guide · Claude Desktop Config
Add cognitive memory Memory Overview · Getting Started · Use Cases
Use the Java SDK Java SDK Guide · Spring AI Integration
Deploy to production Docker Deployment · Performance Tuning
Extend with Enterprise Spector Enterprise — enterprise connectors, access control, management APIs

📖 Full Documentation →

🤝 Contributing

We welcome contributions of all kinds — code, docs, tests, benchmarks, and ideas!

⭐ Star History

Star History Chart

📄 License

This repository uses a split licensing model:

For branding and trademark guidelines, see the NOTICE file.

🔒 Security

See SECURITY.md for our security policy and vulnerability reporting.

🙏 Acknowledgments

See ACKNOWLEDGMENTS.md for credits to the cognitive science researchers, open-source frameworks, and AI coding tools that made Spector possible.