Modules

Modules

Spector is organized as a multi-module Maven project (27 modules). Each module has a focused responsibility, clear API boundaries, and minimal cross-module coupling.

---

Architecture Hierarchy

graph TB
    subgraph nucleus["nucleus/ (Foundation & Acceleration)"]
        commons["spector-commons<br/><i>Error codes & utilities</i>"]
        core["spector-core<br/><i>Compute SPIs & quantization</i>"]
        cpu["spector-cpu<br/><i>Java 25 SIMD acceleration</i>"]
        gpu["spector-gpu<br/><i>Panama FFM + CUDA GPU</i>"]
        hdc["spector-hdc<br/><i>Hyperdimensional vectors</i>"]
        index["spector-index<br/><i>HNSW + SpectorIndex + BM25</i>"]
        config["spector-config<br/><i>SpectorConfig + YAML</i>"]
        events["spector-events<br/><i>Telemetry event bus</i>"]
        testsupport["spector-test-support<br/><i>Test harnesses & mocks</i>"]
    end

    subgraph memory["memory/ (Cognitive Memory Engine)"]
        spectorkernel["spector-kernel<br/><i>Zero-GC Panama FFM, Bundles & Shapes</i>"]
        spectormemory["spector-memory<br/><i>Cognitive Pathways & Daemons</i>"]
        providerApi["spector-provider-api<br/><i>Provider SPI</i>"]
        providers["spector-providers<br/><i>AI Providers (Ollama, OpenAI, ONNX)</i>"]
        ingestion["spector-ingestion<br/><i>File & sensory ingest pipeline</i>"]
        inspect["spector-inspect<br/><i>Bundle inspection tool</i>"]
        metrics["spector-metrics<br/><i>Micrometer + Prometheus metrics</i>"]
    end

    subgraph synapse["synapse/ (API, Integration & Gateways)"]
        synapseapp["spector-synapse<br/><i>Spring Boot 4 / REST, SSE & Chat Graph</i>"]
        connector["spector-connector<br/><i>Camel data connectors</i>"]
        mcp["spector-mcp<br/><i>MCP Server (STDIO/SSE)</i>"]
        cli["spector-cli<br/><i>spectorctl CLI & standalone spector.jar</i>"]
        spring["spector-spring<br/><i>Spring AI VectorStore</i>"]
        batch["spector-batch<br/><i>Batch migration engine</i>"]
    end

    subgraph bench["bench/ (Performance & Validation)"]
        spectorbench["spector-bench<br/><i>JMH & cognitive benchmarks</i>"]
    end

    nucleus --> memory --> synapse
    synapse --> bench
    memory -.-> bench

Loading

---

Module Dependency Graph

graph TD
    synapseapp["🌐 synapse"] --> mcp["🤖 mcp"]
    synapseapp --> connector["🔌 connector"]
    synapseapp --> metrics["📈 metrics"]
    synapseapp --> events["📡 events"]
    synapseapp --> memory["🧠 memory"]
    
    mcp --> memory
    mcp --> ingestion["📥 ingestion"]
    cli["🖥️ cli"] --> memory
    cli --> mcp
    cli --> ingestion

    memory --> kernel["🛡️ kernel"]
    memory --> index["📊 index"]
    memory --> core["🔬 core"]
    memory --> cpu["⚡ cpu"]
    memory --> config["⚙️ config"]
    memory --> providerApi["🧬 provider-api"]

    kernel --> commons["📄 commons"]
    inspect --> kernel

    index --> core
    index --> config
    index --> commons["📄 commons"]

    gpu --> index
    gpu --> core
    gpu --> commons

    cpu --> core
    cpu --> commons

    metrics --> memory
    metrics --> events

    connector --> ingestion
    connector --> providerApi

    spring["🌱 spring"] --> memory
    spring --> metrics
    bench["🧪 bench"] --> memory
    bench --> providers["🤖 providers"]

Loading

Legend: Solid arrows = compile dependency. Dotted arrows = optional/benchmark dependency.

important: Bundle Kernel Architecture spector-memory is backed by the off-heap Bundle Kernel Architecture (PartitionBundle, RuntimeBundle, EngramLayout). In-memory vector indexes are managed directly by spector-index, and SIMD/GPU operations are accelerated by spector-cpu and spector-gpu.

---

Architecture: Direct Memory Composition

All entry points (MCP Server, CLI, Spring Boot Synapse) interact directly with SpectorMemory:

graph TD
    cli["🖥️ spector-cli<br/><i>SpectorCtl / spector.jar</i>"]
    mcp["🤖 spector-mcp<br/><i>SpectorMcpServer</i>"]
    synapseapp["🌐 spector-synapse<br/><i>SynapseApplication (Spring Boot 4)</i>"]

    cli --> memory["🧠 SpectorMemory<br/><i>DefaultSpectorMemory</i>"]
    mcp --> memory
    synapseapp --> memory

    memory --> recall["Recall Pathway<br/><i>Dense + Sparse + Graph + Metamemory</i>"]
    memory --> daemons["Consolidation Daemons<br/><i>Eager, Synaptic, Circadian</i>"]
    memory --> storage["Bundle Kernel<br/><i>Off-Heap Memory Mapped</i>"]

Loading

---

Module Overview

Foundation & Acceleration Layer (/nucleus)

Module	Description
[[spector-bom	Modules--Spector-Bom]]
[[spector-commons	Modules--Spector-Commons]]
[[spector-core	Modules--Spector-Core]]
[[spector-cpu	Modules--Spector-Cpu]]
[[spector-gpu	Modules--Spector-Gpu]]
[[spector-hdc	Modules--Spector-Hdc]]
[[spector-index	Modules--Spector-Index]]
[[spector-config	Modules--Spector-Config]]
[[spector-events	Modules--Spector-Events]]
[[spector-test-support	Modules--Spector-Test-Support]]

Cognitive Memory Layer (/memory)

Module	Description
[[spector-kernel	Modules--Spector-Kernel]]
[[spector-memory	Modules--Spector-Memory]]
[[spector-provider-api	Modules--Spector-Provider-Api]]
[[spector-providers	Modules--Spector-Providers]]
[[spector-ingestion	Modules--Spector-Ingestion]]
[[spector-inspect	Modules--Spector-Inspect]]
[[spector-metrics	Modules--Spector-Metrics]]

Nervous System & Gateways (/synapse)

Module	Description
[[spector-synapse	Modules--Spector-Synapse]]
[[spector-connector	Modules--Spector-Connector]]
[[spector-mcp	Modules--Spector-Mcp]]
[[spector-cli	Modules--Spector-Cli]]
[[spector-spring	Modules--Spector-Spring]]
[[spector-batch	Modules--Spector-Batch]]

Benchmarks (/bench)

Module	Description
[[spector-bench	Modules--Spector-Bench]]