The Zero-Overhead, Agent-Ready AI Memory Backbone.

---

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

_{🎥 Watch the Neural Graph in action →}

📊 Dashboard — 12+ live cognitive panels

Real-time scoring pipeline, SIMD lanes, decay curves, vector space, Hebbian graph, cognitive profiles, live metrics — all rendered with Three.js, Canvas 2D, and Angular Signals.

🌌 Graph Explorer — 3D neural galaxy

Interactive 3D graph with glowing star nodes, Hebbian/temporal/entity edges, fly-to navigation, and real-time topology stats.

🧠 Memory Table — browse & manage memories

Full CRUD with tier filtering, importance bars, valence indicators, synaptic tags, recall counts, and bulk actions.

🔬 Memory Detail — deep cognitive inspection

Identity, cognitive state (importance/valence/arousal), synaptic tags, and full relationship graph (Hebbian associations, temporal chains, entity links).

---

🚀 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!

• 🐛 Found a bug? → Open an Issue
• 💡 Have an idea? → Start a Discussion
• 🔧 Want to contribute code? → See CONTRIBUTING.md
• 🤖 AI-assisted PRs welcome!

---

⭐ Star History

---

📄 License

This repository uses a split licensing model:

• spector-memory — Business Source License 1.1 (transitions to Apache 2.0 on May 27, 2030)
• spector-cortex — Business Source License 1.1 (transitions to Apache 2.0 on July 6, 2030)
• spector-synapse — Business Source License 1.1 (transitions to Apache 2.0 on July 6, 2030)
• All other modules — Apache License 2.0

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.

---

Built with ⚡ by Spectrayan