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

---

Legacy AI stacks bolt memory onto stateless vector databases — storage without cognition. Spector is a cognitive memory backbone for modern AI agents: it remembers, forgets, consolidates, and forms associations across a biologically-inspired memory graph — Hebbian co-activation, temporal chains, and event-episode hyperedges — then retrieves with fused semantic and hybrid scoring at sub-millisecond latency. Connect any AI agent through the built-in MCP server, call it over REST/gRPC, drive it from the Python SDK, or embed it directly in the JVM. Every user, agent, or tenant is physically isolated in its own on-disk namespace — true data separation, not a shared-store filter. Under the hood, Java Project Panama and the Vector API deliver C++-class SIMD speed with zero garbage-collection pressure.

---

📐 Mathematical Foundation

Spector Cognitive Memory is built on a mathematically rigorous foundation modeling biological memory encoding and retrieval dynamics.

Ingestion: Remember

When a new memory $m$ is ingested, Spector initializes its state vector with fused importance scoring:

$$\mathbf{S}_m(t_0) = \langle \vec{v}_m, \text{Bloom}(T_m), V_m, I_m(t_0), R_m(t_0) \rangle$$

$$\text{where } I_m(t_0) = \omega_s \cdot \left(1 - e^{-\lambda \cdot |\vec{v}_m - \vec{\mu}_t|^2}\right) + \omega_p \cdot \text{Salience}(m)$$

📖 Read the Ingestion Mathematics deep-dive →

Retrieval: Recall

Recall dynamically decays importance over time using Bjork & Bjork retrieval strength dynamics and applies emotional valence state-dependent constraints in a single SIMD pass:

$$\text{FusedScore}(m, \vec{q}) = \left[ \alpha \cdot \text{Cos}(\vec{q}, \vec{v}_m) + \beta \cdot I_m(t) \cdot e^{-\delta \cdot \frac{t - t_m}{R_m(t)}} + \gamma \cdot \frac{|\text{Bloom}(T_q) \cap \text{Bloom}(T_m)|}{\text{BitCount}(\text{Bloom}(T_q))} \right] \cdot \left( 1.0 - \eta \cdot \frac{|V_q - V_m|}{255} \right)$$

📖 Read the Retrieval Mathematics deep-dive →

---

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), 3-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	What makes it different
🧠 Cognitive memory tiers	Working → Episodic → Semantic → Procedural, with decay, consolidation, and emotional valence — memory that behaves like memory, not a key-value store
🔗 Associative memory graphs	Hebbian co-activation, temporal chains, and event-episode hyperedges — recall surfaces what's related, not just what matches
🤖 In-process MCP server	Cognitive tools over stdio + Streamable HTTP — agents call memory directly, zero network hops
⚡ Fused SIMD scoring	Similarity × importance × decay in one pass — 0.13ms p50 recall at 1M memories
🔍 Hybrid retrieval	Dense + sparse + late-interaction reranking, fused with RRF, with graceful degradation
🔒 Physical namespace isolation	Every user, agent, or tenant's memory lives in its own on-disk directory tree — true data separation, not a logical filter — hash-sharded to millions of namespaces, encrypted at rest (AES-256-GCM)
🧊 Zero-GC off-heap storage	100% off-heap via Panama — ~0.01% GC overhead measured
🗜️ Quantization	SVASQ-8/4 + IVF-PQ — 4–32× compression at ~99.5% recall
🖥️ GPU acceleration	Optional CUDA via Panama FFM, zero-copy transfer
📦 Flexible deployment	Embedded JAR, standalone, or distributed

---

📸 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