Spector

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

🧠 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.

📖 Full Cognitive Memory Documentation →

✨ Key Capabilities

📸 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.

📖 Full Benchmark Report → · Performance Tuning →

📖 Documentation

📖 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.