Modules¶

Spector is organized as a multi-module Maven project (24 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)"]
        spectormemory["spector-memory<br/><i>Bundle Kernel, Recall Pipeline & 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

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 --> index["📊 index"]
    memory --> core["🔬 core"]
    memory --> cpu["⚡ cpu"]
    memory --> config["⚙️ config"]
    memory --> providerApi["🧬 provider-api"]

    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"]

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

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 Pipeline<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>"]

Module Overview¶

Foundation & Acceleration Layer (/nucleus)¶

Cognitive Memory Layer (/memory)¶

Nervous System & Gateways (/synapse)¶

Benchmarks (/bench)¶