🗺️ Roadmap¶

Spector is under active development. This page details planned improvements, their projected impact, and implementation status.

✅ Priority: OpenClaw Integration¶

✅ OpenClaw Integration — Spector as Main Memory¶

Integrate Spector Memory as the primary long-term memory backend for OpenClaw — the open-source autonomous AI agent framework that runs as a local gateway across WhatsApp, Telegram, Slack, and Discord.

Why OpenClaw + Spector:

OpenClaw provides the agentic loop (observe → reason → act) and multi-channel interface, but lacks a biologically-inspired long-term memory system. Currently, OpenClaw agents lose context across sessions or rely on simple key-value stores. Spector Memory gives OpenClaw agents:

• Cross-session persistence — memories survive across conversations and channels
• Cognitive recall — biologically-inspired scoring (decay, importance, valence) instead of naive vector search
• Emotional context — valence-filtered recall for empathetic responses
• Anti-repetition — habituation prevents the agent from repeating the same responses
• Associative recall — Hebbian + Temporal + Entity graphs surface connected memories

Architecture:

┌──────────────────────────────────────────────┐
│  OpenClaw Agent (Python)                      │
│  Observe → Reason → Act loop                  │
│  Multi-channel: WhatsApp, Telegram, Slack     │
├──────────────────────────────────────────────┤
│  ↕  MCP stdio / HTTP transport                │
├──────────────────────────────────────────────┤
│  Spector MCP Server (Java)                    │
│  memory_recall · memory_remember          │
│  memory_reinforce · memory_introspect         │
│  memory_why_not · memory_status               │
├──────────────────────────────────────────────┤
│  Spector Memory Engine                        │
│  4-tier storage · SIMD scoring · Bloom filter │
│  Cognitive graph · Decay · Habituation        │
│  ⚡ Local, private, off-heap, sub-ms recall    │
└──────────────────────────────────────────────┘

Integration points:

Profile mapping for OpenClaw modes:

Implementation plan:

1. MCP Bridge: OpenClaw connects to Spector via MCP stdio transport (local) or HTTP transport (remote)
2. Memory Lifecycle Hook: OpenClaw's agentic loop calls memory_remember after each skill execution and memory_recall before each reasoning step
3. Channel Metadata: Channel (WhatsApp/Telegram/Slack) and user ID encoded as synaptic tags for cross-channel memory isolation or sharing
4. Consolidation: Spector's reflect() daemon runs on a schedule, consolidating episodic memories into semantic knowledge across all channels
5. Python SDK: The planned Python SDK wraps the MCP transport for native OpenClaw integration

Privacy advantage: Both OpenClaw and Spector run locally — the most personal conversations never leave the user's machine.

✅ Completed — Client SDKs & Documentation¶

✅ Python SDK — MCP Client Wrapper¶

A lightweight Python package that wraps Spector's MCP server via subprocess/stdio transport, giving Python developers a native-feeling API without touching Java:

from spector import Memory

mem = Memory()
mem.remember("user likes dark mode", tags=["pref", "ui"])
results = mem.recall("theme preference?")
# → [MemoryResult(text="user likes dark mode", score=0.92, confidence=HIGH)]

explanation = mem.why_not("mem-42", "theme preference?")
# → WhyNot(reason=OUTRANKED, score_gap=0.15, ...)

Implementation:

• Thin subprocess.Popen wrapper for MCP stdio transport
• Maps all MCP tools to Pythonic methods (remember, recall, forget, reinforce, why_not, introspect)
• Returns typed dataclasses (MemoryResult, WhyNotExplanation, MemoryInsight)
• Published to PyPI as spector-memory

Why: The Python-first AI ecosystem (LangChain, LlamaIndex, AutoGen) is the largest potential audience. Eliminates the "language barrier" concern entirely.

✅ Documentation Split — User Guide vs Architecture Guide¶

Separate documentation into two tracks to prevent the "19 packages overwhelm developers" perception:

Key principle: A developer using memory.recall("query") should never see SynapticHeaderConstants or CognitiveRecordLayout in the getting-started docs.

📜 Planned — Agentic AI¶

✅ ProfileAdaptor — Self-Tuning Cognitive Profiles¶

A lightweight contextual bandit that learns which CognitiveProfile performs best for each context (tag combination), using the existing memory_reinforce feedback signal. Instead of requiring AI agents to manually select DEBUGGING vs EXPLORING vs BALANCED, the system auto-selects the optimal profile based on historical reinforcement rates.

How it works:

1. Agent calls memory_recall with profile=BALANCED (or no profile)
2. Agent calls memory_reinforce on useful results (positive valence) or unhelpful results (negative valence)
3. ProfileAdaptor tracks reinforcement rates per (tag-context, profile) pair via an exponential moving average
4. On subsequent recalls with matching tags, ProfileAdaptor.suggest() returns the profile with the highest historical hit rate

API:

public class ProfileAdaptor {
    // Track reinforcement rates per (tag-context, profile) pair
    private final Map<String, Map<CognitiveProfile, RunningStats>> stats;

    /** Called after memory_reinforce. Updates profile effectiveness. */
    public void recordOutcome(CognitiveProfile profile, String[] tags, boolean positive);

    /** Suggests the best profile for a given tag context. */
    public CognitiveProfile suggest(String... tags);
}

MCP integration:

{
  "query": "why did the payment service crash?",
  "profile": "auto",
  "synaptic_filter": "payments,errors"
}

When profile=auto, the system queries ProfileAdaptor.suggest("payments", "errors") and transparently selects the best-performing profile for that tag context.

Design considerations:

• Cold start: Falls back to BALANCED until ≥10 reinforcement signals are recorded for a context
• Exploration: ε-greedy strategy (10% random profile selection) to avoid local optima
• Persistence: Stats serialized to WAL for cross-session learning
• Multi-tenant: Per-user stats isolation via the planned userId field

📜 Planned — Compute & Hardware¶

📜 GPU Kernel Dispatch¶

Ship actual CUDA compute kernels for batch cosine similarity and HNSW neighbor selection. The existing spector-gpu module provides context management, memory allocation, and kernel loading via Panama FFM — the remaining work is the CUDA kernel code itself.

Prerequisites: CUDA Toolkit 12+ on the host machine.

Expected impact: 10–100× throughput improvement for batch similarity computation on large datasets (> 100K vectors).

🔄 Project Valhalla Value Classes¶

Migrate hot-path intermediate records to value class (or value record). JDK 25 does not include JEP 401 — Valhalla value classes are expected in JDK 28+.

Current preparation:

• Javadoc TODOs added to all 5 hot-path records: CognitiveHeader, ScoredRecord, HebbianEdge, EntityEdge, TraversalResult
• Manual flat-array optimization (FlatMinHeap) serves as the bridge pattern — will be replaceable with PriorityQueue<value ScoredRecord> once specialized generics land
• Performance optimizations implemented as stop-gap: autoboxing elimination (int[] vs List<Integer>), boolean[] vs HashSet<Integer>, LUT-based Math.pow replacement

Benefits (when JDK 28+ lands): - Zero-GC Hot Path: Short-lived search results and option records are stack-allocated, avoiding the JVM heap. - Cache Locality: Contiguous storage of value structures inside arrays prevents pointer chasing. - Header Elimination: Removes standard 12-to-16-byte JVM object headers for inline arrays.

🔬 Research & Future¶

🔬 TypeScript/JavaScript SDK¶

A TypeScript SDK for Node.js and browser-adjacent environments, wrapping the Streamable HTTP MCP transport:

import { SpectorMemory } from '@spector/memory';

const mem = new SpectorMemory({ url: 'http://localhost:8080' });
await mem.remember('user prefers dark mode', { tags: ['pref', 'ui'] });
const results = await mem.recall('theme preference?');

Use cases: Next.js agents, Vercel AI SDK integration, Electron desktop assistants.

🔬 RecallMode.REPLAY — WAL Time-Travel Recall¶

Replay recall from a frozen point-in-time state by reconstructing memory state from WAL events. Answers the question: "Why did the agent retrieve X instead of Y at 2pm yesterday?"

How it works:

1. User calls memory_recall with recall_mode=REPLAY and a target replay_timestamp
2. System reads WAL events (ingestions, reinforcements, suppressions) up to the target timestamp
3. Reconstructs a temporary off-heap MemorySegment representing the memory state at time T
4. Runs the standard recall pipeline against the frozen snapshot (no mutations)
5. Returns results with a [REPLAY @ 2025-06-02T14:00:00Z] provenance marker

Implementation options:

• Option A — Full replay: Read all WAL events from start to target timestamp, apply each mutation to a temporary segment. Expensive compute, but minimal storage overhead.
• Option B — Periodic snapshots: Periodically snapshot the full off-heap state. Replay only needs events between the last snapshot and the target timestamp. More storage, faster replay.

Prerequisites:

• WAL must record all header mutations (recallCount, valence, storageStrength changes)
• Snapshot serialization for off-heap MemorySegment state
• Temporary segment allocation + cleanup lifecycle

Use cases: Debugging agent behavior, audit trails, compliance (regulated industries), algorithm comparison ("did the new scoring function improve recall quality?").

🔬 LoRA Adapter Routing¶

Multi-tenant query projection via SIMD matrix multiply. Instead of creating separate indexes per tenant, store one base index and apply per-tenant LoRA weight matrices at query time using Panama FMA loops.

How it works: - Ingest base model embeddings once - Each tenant uploads a small LoRA matrix (\(W_A\), typically 768×32 or similar) - At query time: \(q_{tenant} = q_{base} \times W_A\) (microseconds via Panama SIMD) - Search the same index with the projected query

Expected impact: Zero-downtime multi-tenant customization without index duplication.

✅ ColBERT v2 Late Interaction Reranking¶

Native ColBERT reranking using Panama FMA loops. ColBERT stores a vector for every token in a document, then computes relevance via MaxSim (maximum similarity per query token).

Spector advantage: Off-heap MemorySegment arrays and Fused-Multiply-Add Panama loops natively execute ColBERT MaxSim reranking faster than almost any competitor.

Implementation:

• ColBERTReranker: Takes TokenEmbeddingProvider SPI, computes MaxSim with SIMD-accelerated dot products
• TokenEmbeddingProvider SPI: Produces per-token embedding arrays (e.g., from ColBERT v2 model)
• TokenEmbeddingResult: Wraps float[][] token-level embeddings
• Integration in RecallPipeline Step 6b: Reranks top-N first-stage candidates after sort
• Scoring: combinedScore = α·maxSimScore + (1-α)·firstStageScore
• Nullable SPI pattern: silently skips if TokenEmbeddingProvider is not configured

Configuration:

RecallOptions.builder()
    .enableReranker(true)
    .rerankerDepth(50)    // rerank top-50 first-stage candidates
    .textSearchMode(TextSearchMode.COLBERT_RERANK)
    .build();

🔬 SVASQ-PQ Hybrid — Product Quantization of SVASQ Residuals¶

After FWHT rotation, instead of scalar INT8/INT4 quantization, apply Product Quantization to the rotated coordinates. The FWHT rotation makes coordinates near-independent (isotropized), which is the ideal input distribution for PQ — similar to how Optimized PQ (OPQ) works with learned rotations, but using FWHT instead of an expensive SVD-based rotation matrix.

Memory layout:

[float32 normSq (4 bytes)] [PQ codes: M bytes (one centroid ID per subspace)]

With M=16 subspaces, K=256 centroids:

Recall impact:

• PQ on FWHT-rotated residuals: ~85–93% recall@10
• FWHT rotation gives ~3–5% recall advantage over naive PQ (pre-decorrelates dimensions)
• Rescore with exact float32 residuals pushes recall to 95%+

Why it works: The FWHT rotation is essentially a free, lossless "Optimized PQ" rotation — it decorrelates dimensions without requiring an expensive SVD or learned rotation matrix. This means PQ subspaces can be independent slices of the rotated vector, which is information-theoretically optimal.

Implementation scope:

• Train PQ codebooks per shard (or globally after FWHT rotation)
• Asymmetric Distance Computation (ADC) lookup tables during search
• New SIMD kernel for PQ distance computation
• Integration with existing ProductQuantizer in spector-index

🔬 Flat-Mode SVASQ — Compress Flat-Shard Storage¶

In SpectorShard's flat mode, residuals are stored as raw float32[]. Since all residuals in a shard share the same centroid, they have similar statistical distributions. SVASQ quantization of flat residuals could compress flat-mode storage by ~3× without changing the shard architecture.

Savings:

Recall impact:

• If applied only to storage (decode for search): None — search uses decoded float32
• If applied to search (scan quantized codes directly): Same as SVASQ-8 (~99.5%)

Implementation scope:

• Integrate SVASQ encoding into the flat-mode ingestion path
• Modify SpectorShard.flatScan() to use the SVASQ SIMD kernel directly
• Per-shard calibration using the shard's centroid residuals

🔬 NPU Acceleration¶

Leverage Intel NPU (via OpenVINO) or AMD XDNA (via DirectML) for INT8 batch operations. NPUs are optimized for low-precision matrix operations, making them ideal for quantized SVASQ distance computation.

Target workloads: INT8/INT4 batch similarity, SVASQ kernel offload.

🔬 WASM Runtime for Edge Deployment¶

Compile the core SIMD kernels and HNSW index to WebAssembly for browser-based or edge deployment. This would enable client-side semantic search without a server round-trip.

🔴 Adaptive Bit-Width SVASQ¶

Instead of uniform INT8 across all dimensions, assign more bits to high-variance dimensions and fewer to low-variance ones (after FWHT rotation):

• Dimensions with σ > 2× median: 8 bits
• Dimensions with σ < 0.5× median: 4 bits
• Others: 6 bits

Projected savings: ~10–15% additional compression.

Recall impact: Minimal (< 0.5%) — allocating bits proportionally to variance is information-theoretically optimal.

Why it's not recommended: FWHT already equalizes variance by design, so the marginal gain from adaptive bit-widths is small. The implementation requires variable-length encoding, non-aligned SIMD reads, and per-dimension bit-width bookkeeping — the worst effort-to-benefit ratio of all proposed improvements.

🔬 SPLARE — Sparse Autoencoder Learned Retrieval¶

SPLARE (Sparse Autoencoder Learned Retrieval) uses sparse autoencoders to extract interpretable sparse features from dense embeddings. Unlike SPLADE which uses a masked language model, SPLARE operates on the embedding space directly, making it model-agnostic.

Proposed approach:

1. Train a sparse autoencoder on the embedding provider's dense vectors
2. Extract top-K active features per document (typically 128-256)
3. Use feature indices + activations as sparse retrieval keys
4. Index into the existing SpladeIndex infrastructure (same posting list format)

Advantages over SPLADE:

Prerequisites: Sparse autoencoder training pipeline, feature dictionary management, SparseEncodingProvider adapter.

🔬 ColPali — Vision-Language Late Interaction¶

Extend ColBERT's late interaction paradigm to visual documents using the ColPali architecture (Faysse et al., 2024). Instead of OCR → text → embed, ColPali directly produces per-patch token embeddings from document images, enabling visual retrieval of PDFs, screenshots, diagrams, and handwritten notes.

How it works:

1. Document images are encoded by a vision transformer (e.g., PaliGemma) into per-patch embeddings
2. Query text is encoded into per-token embeddings (same as ColBERT)
3. MaxSim scoring between query tokens and image patches
4. Reuses the existing ColBERTReranker MaxSim SIMD kernel

Architecture:

Query: "database schema diagram"         Document: [screenshot.png]
   ↓                                          ↓
TokenEmbeddingProvider.embed()           VisionPatchProvider.embed()
   ↓                                          ↓
["database", "schema", "diagram"]        [patch_1, patch_2, ..., patch_N]
   ↓              ↓            ↓              ↓
[768-d vec]   [768-d vec]  [768-d vec]    [768-d vec] × N patches
   └──────────── MaxSim ──────────────────────┘

Prerequisites:

• VisionPatchProvider SPI (produces float[][] per-patch embeddings)
• Vision model integration (PaliGemma, SigLIP, or similar)
• Image storage in TextDataStore or new MediaDataStore
• Multi-modal MemoryType extension

Estimated effort: 6-8 weeks (vision encoder integration is the bottleneck).

✅ Completed¶

✅ Native MCP Server¶

Built-in Model Context Protocol server that gives AI agents (Claude Desktop, Cursor, autonomous agents) direct, in-process access to Spector's search engine. Zero network overhead — tool handlers call SpectorEngine directly via virtual threads.

Tools: semantic_search, hybrid_search, rag_query, ingest_document, delete_document, engine_status

Architecture: - McpToolHandler abstract base class (common timing, error handling, arg parsing) - ToolSchemaBuilder fluent JSON schema construction - SpectorToolRegistry for extensible tool registration - SpectorResourceProvider + SpectorPromptProvider for MCP resources/prompts - ResultFormatter shared formatting utilities

✅ Streamable HTTP Transport¶

HTTP-based MCP transport for remote/cloud deployments. Same 6 tools exposed over an HTTP endpoint.

Implementation:

• TransportMode enum: STDIO (default), HTTP
• CLI flags: --transport=http, --port=8080
• SpectorMcpMain: Parses transport mode and configures server accordingly
• Graceful shutdown on SIGTERM for container readiness

Use cases: Cloud deployments, remote agent connections, multi-agent architectures.

✅ 3-Layer Cognitive Graph¶

Full graph augmentation layer for spector-memory — three biologically-inspired graph structures that augment vector recall with associative, temporal, and relational signals.

Architecture:

RecallPipeline
  Step 5a: Habituation + Inhibition of Return
  Step 5b: STDP causal boost (CoActivationTracker)
  Step 5c: Hebbian spreading activation (HebbianGraph, depth=2)
  Step 5d: Temporal chain extension (TemporalChain, maxHops=3)
  Step 5e: Entity graph traversal (EntityGraph, 2-hop BFS)

Layer 1 — Hebbian Association Graph:

• Off-heap adjacency list (164B/node, MAX_DEGREE=20) via Panama MemorySegment
• Edge strengthening, decay (0.9 factor per consolidation), spreading activation
• Persistence via HGPH magic header, chunked 64KB FileChannel I/O
• CoActivationTracker migrated to off-heap: OffHeapPairTable (32B/slot) + OffHeapEdgeTable (40B/slot)
• Persistence via COAX magic header with hash→tag reverse map

Layer 2 — Entity-Relationship Graph:

• Off-heap entity store (64B/entity, 12B/edge), BFS traversal with typed edge filtering
• Unlimited entity→memory adjacency via separate off-heap adjacency segment (8B/entry: memIdx + weight)
• LTP reinforcement (+0.2 weight on re-mention), LTD decay (0.95× per reflection cycle, pruned below 0.2)
• Fan-effect attenuation (1/√refCount) in recall scoring — ACT-R spreading activation dilution
• Adjacency compaction (defragmentation) during reflection cycles
• 21 entity types × 21 relation types (well-known seeds) + open-schema TypeRegistry for LLM-identified novel types
• EntityExtractor SPI with LlmEntityExtractor (externalized prompt template) and NoOpEntityExtractor
• Persistence via EGPH magic header with nameIndex reconstruction + adjacency segment + separate TypeRegistry files

Layer 3 — Temporal Causal Chain:

• Off-heap linked list (16B/node: prevIdx + nextIdx + sessionId + pad)
• Session-local memory linking at ingestion, forward/backward traversal at recall
• Persistence via TPCH magic header

Error framework: 6 error codes (SPE-310-006..011), 7 granular exception classes extending SpectorGraphException. All catch sites use catch(RuntimeException) → create exception → log(ex.getMessage()). No string concatenation.

Each graph step is additive and gracefully degrading — if the graph is null/empty or the operation throws, the step is a no-op.

✅ Temporal Chain Pruning¶

Temporal chain links now support automatic pruning during the reflect() consolidation cycle.

Implementation:

• TemporalChain.pruneOlderThan(long cutoffEpochMs): Scans all nodes, unlinks stale entries, re-stitches prev → next pointers
• pad:4B field in node layout replaced with epochSec:4B (seconds since epoch)
• Configurable via Builder: temporalRetentionDays(int) (default: 7)
• Pruned count reported in ReflectReport

✅ Cross-Layer Promotion (Hebbian → Entity)¶

Strong statistical Hebbian associations are automatically promoted to explicit entity relations during the reflect() consolidation cycle — analogous to hippocampal replay.

Implementation:

• During reflect(), scans HebbianGraph for edges with weight ≥ threshold
• Builds memoryIdx → entityIds reverse index for O(1) lookup (vs previous O(E×R) scan)
• If shared entities exist, strengthens the entity relation edge; if none, creates a RELATED_TO relation
• Cross-promotion count reported in ReflectReport

✅ Entity Graph Decay + Node Merging + Adjacency Maintenance¶

Entity graph edges now decay during consolidation, near-duplicate entities are automatically merged, and entity→memory adjacency links decay and compact.

Implementation:

• EntityGraph.decayRelations(float factor): Multiplicative decay, prunes edges below threshold
• EntityGraph.mergeSimilarEntities(int maxEditDistance): Levenshtein-based fuzzy matching with ThreadLocal reusable int[] arrays (zero GC after warmup)
• EntityGraph.decayAdjacencyWeights(float factor, float threshold): LTD decay of entity→memory link weights, pruning weak associations
• EntityGraph.compactAdjacency(): Defragments the adjacency segment, reclaiming dead blocks from pruned/grown entries
• EntityGraph.fanFactor(int entityId): Returns 1/√(refCount) for ACT-R spreading activation dilution in recall scoring
• Integrated into ReflectionOrchestrator as Phase 5 (edge decay + merge), Phase 5b (adjacency LTD), Phase 5c (compaction)
• Decay/merge/compaction counts reported in ReflectReport

✅ Graph-Aware Scoring Weights¶

All hardcoded graph score attenuation factors are now extracted into a configurable GraphScoringPolicy record:

public record GraphScoringPolicy(
    float causalBoostWeight,       // default 0.3
    float hebbianBoostFactor,      // default 0.3
    float temporalForwardFactor,   // default 0.8
    float temporalBackwardFactor,  // default 0.7
    float entityHopAttenuation,    // default 0.25
    int hebbianMaxDepth,           // default 2
    int temporalMaxHops,           // default 3
    int entityMaxHops              // default 2
) {
    public static final GraphScoringPolicy DEFAULT = ...;
}

• Configurable via Builder: graphScoringPolicy(GraphScoringPolicy)
• All 8 constants replaced with policy accessors in RecallPipeline
• Future: online tuning based on user reinforcement/suppression feedback

✅ SVASQ-4 — Half-Precision SVASQ (INT4 Codes)¶

Replace INT8 [-127, 127] codes with INT4 [-7, 7] codes in the SVASQ pipeline. The FWHT rotation still equalizes variance, so INT4 quantization error remains uniformly distributed — just at a coarser granularity (15 levels vs 255).

Memory layout:

[float32 normSq (4 bytes)] [INT4 × paddedDim nibble-packed (paddedDim/2 bytes)]

Recall:

• Without rescore: ~95–97% recall@10
• With 3× oversampling rescore: ~97–99% recall@10

Key design decisions:

• Separate Svasq4Encoder / Svasq4SimdKernel classes (not parameterizing SVASQ-8) to avoid impacting existing code
• Offset encoding [0, 14] keeps byte values non-negative for correct castShape sign extension
• Deinterleaved hi/lo query arrays match nibble layout for natural SIMD ILP
• Tighter clipping (2.5σ vs 3.0σ) optimizes for 15 quantization levels

✅ Padding-Aware Storage — Skip Zero Dimensions¶

SVASQ pads vectors to the next power-of-two dimensionality (e.g., 768 → 1024), adding wasted bytes. The padded dimensions are zero-filled before FWHT, so their rotated codes are predictable. We now store only the first originalDim codes (aligned to the next SIMD boundary) and reconstruct padded codes at query time.

Recall impact: None for L2 distance — padded dimensions contribute a constant offset that doesn't affect ranking.

Implementation: SIMD-aligned stored codes (Option A — aligns storedDim to next 16-byte boundary). Zero SIMD tail loop overhead.

Changes:

• SvasqParams.storedDim(): Returns SIMD-aligned originalDim
• SvasqEncoder / Svasq4Encoder: Store only storedDim codes
• SvasqSimdKernel / Svasq4SimdKernel: Loop over storedDim instead of paddedDim

✅ Norm Header Compression — float32 → float16¶

The 4-byte float32 exactNormSq header is now compressed to 2 bytes using float16 (half-precision).

Savings: 2 bytes per vector (combined with padding-aware storage for maximum effect).

Recall impact: < 0.01% — float16 has ~3 decimal digits of precision.

Changes:

• SvasqEncoder / Svasq4Encoder: Write norm via Float.floatToFloat16()
• SvasqSimdKernel / Svasq4SimdKernel: Read via Float.float16ToFloat()
• SvasqParams.bytesPerVector(): Uses 2-byte norm header

✅ Structured Concurrency (JEP 505)¶

Migrated all 6 concurrency sites from unstructured ExecutorService + Future to the JEP 505 StructuredTaskScope API, centralized in ConcurrentTasks:

Key design decisions:

• Centralized in ConcurrentTasks (spector-commons) for single-point updates when JEP finalizes
• Feature flag: -Dspector.concurrency.structured=false for fallback to classic virtual threads
• forkJoinAll(): all-or-nothing with auto-cancel (uses awaitAllSuccessfulOrThrow Joiner)
• forkJoinPartial(): deadline-based with LabeledTask/PartialResult records (uses awaitAll Joiner + Configuration.withTimeout())

✅ 4-Layer Retrieval Stack¶

Full 4-layer retrieval architecture with SIMD-accelerated scoring at every layer:

Layer 4: ColBERT v2 Reranker   (token-level late interaction, SIMD MaxSim)
Layer 3: SPLADE / Li-LSR       (learned sparse retrieval, inverted index)
Layer 2: BM25                  (keyword search, AVX-512 SIMD scoring)
Layer 1: Dense Vector           (HNSW semantic similarity, SQ8/SQ4 quantized)
─────── RRF Fusion ─────────── (merges all layer signals)

Components built:

Pipeline integration:

• CognitiveIngestionTarget Step 9a-splade: SPLADE encoding + indexing at ingestion
• RecallPipeline Step 3c: SPLADE sparse search (parallel to BM25, fused via RRF)
• RecallPipeline Step 6b: ColBERT reranking (top-N candidates after first-stage sort)
• All features follow the nullable SPI pattern — graceful degradation when providers are absent

Configuration:

RecallOptions.builder()
    .textSearchMode(TextSearchMode.FULL_STACK)  // all 4 layers
    .enableReranker(true)                       // ColBERT reranking
    .rerankerDepth(50)                          // top-50 reranked
    .gamma(0.3f)                                // BM25/SPLADE weight
    .build();

Summary Table¶

📜 Active & Planned¶

🔬 Research & Future¶

✅ Completed¶