Skip to content

📖 API Reference

SpectorMemory

The main façade for all cognitive memory operations.

Builder

SpectorMemory memory = SpectorMemory.builder()
    .dimensions(int)                        // Vector dimensionality (required)
    .embeddingProvider(EmbeddingProvider)    // Embedding provider (required)
    .workingCapacity(int)                   // Working memory slots (default: 100)
    .episodicPartitionCapacity(int)         // Records per episodic partition (default: 10,000)
    .semanticCapacity(int)                  // Semantic memory slots (default: 5,000)
    .proceduralCapacity(int)                // Procedural memory slots (default: 500)
    .quantizer(ScalarQuantizer)             // Custom quantizer (default: identity)
    .persistenceDir(Path)                   // Episodic mmap directory (default: temp dir)
    .build();

Core Methods

Method Return Type Description
remember(id, text, type, source, tags...) CompletableFuture<Void> Async ingestion — embeds, quantizes, stores, indexes
recall(queryText, options) List<CognitiveResult> Parallel SIMD-accelerated recall with cognitive scoring
forget(id) void Tombstones a memory (permanent, excluded from all scans)
suppress(id, reason) void Suppresses from recall results (reversible)
unsuppress(id) void Removes suppression
totalMemories() int Total record count across all tiers
introspect() MemoryIntrospector Memory health analytics
close() void Releases all off-heap memory and file handles

RecallOptions

Builder for recall query configuration.

RecallOptions options = RecallOptions.builder()
    .topK(int)                              // Max results (default: 10)
    .synapticFilter(String... tags)         // Bloom filter pre-screen
    .minImportance(float)                   // Minimum importance [0.0-1.0] (default: 0.0)
    .memoryTypes(MemoryType... types)       // Tier filter (default: all)
    .minValence(byte)                       // Min emotional valence (default: -128)
    .maxValence(byte)                       // Max emotional valence (default: +127)
    .alpha(float)                           // Similarity weight (default: 0.6)
    .beta(float)                            // Importance × decay weight (default: 0.4)
    .build();

Default Options

RecallOptions.DEFAULT  // topK=10, no filters, alpha=0.6, beta=0.4

Scoring Formula

\[\text{FinalScore} = \alpha \cdot \text{Similarity} + \beta \cdot \text{Importance} \cdot \text{Decay}\]

Where:

  • Similarity = 1 / (1 + L2_distance) — semantic relevance
  • Importance = [0.0 - 1.0] — computed by SurpriseDetector at ingestion
  • Decay = precomputed bucket lookup based on memory age

CognitiveResult

Immutable record returned by recall():

public record CognitiveResult(
    String id,                // Unique memory identifier
    String text,              // Raw text content
    float score,              // Final cognitive score (after habituation)
    float importance,         // Original importance at ingestion
    float ageDays,            // Age in fractional days
    short recallCount,        // Times previously recalled
    byte valence,             // Emotional coloring [-128 to +127]
    MemoryType memoryType,    // Cognitive tier (WORKING/EPISODIC/SEMANTIC/PROCEDURAL)
    MemorySource source,      // Provenance (USER_STATED/OBSERVED/PROCEDURAL/...)
    String[] synapticTags,    // Decoded tag labels
    float decayFactor,        // Current temporal decay multiplier
    float ltpAdjustedDecay    // Decay after reconsolidation adjustment
) {}

MemoryType

Enum representing the four cognitive tiers:

public enum MemoryType {
    WORKING,      // Prefrontal Cortex — volatile circular buffer
    EPISODIC,     // Hippocampus — time-partitioned mmap
    SEMANTIC,     // Neocortex — permanent knowledge
    PROCEDURAL    // Basal Ganglia — learned procedures
}

MemorySource

Provenance tracking for memory origin:

public enum MemorySource {
    USER_STATED,   // Explicit user input
    OBSERVED,      // System observation (logs, events)
    INFERRED,      // AI inference
    PROCEDURAL,    // Rule or procedure
    CONSOLIDATED   // Created by sleep consolidation (ReflectDaemon)
}

SynapticTagEncoder

64-bit inline Bloom filter encoder:

// Encode tags into a Bloom filter
long mask = SynapticTagEncoder.encode("java", "debugging", "performance");

// Check if a record matches (containment check)
long recordTags = layout.readSynapticTags(segment, offset);
boolean matches = (recordTags & mask) == mask;

// Match individual tag
boolean hasJava = SynapticTagEncoder.matches(recordTags, "java");

CognitiveRecordLayout

Binary layout for the 32-byte header + quantized vector:

CognitiveRecordLayout layout = new CognitiveRecordLayout(quantizedVecBytes);

// Record stride (header + vector)
int stride = layout.stride();            // e.g., 800 for 768-dim INT8

// Read/write header
CognitiveHeader header = layout.readHeader(segment, offset);
layout.writeHeader(segment, offset, header);

// Read individual fields
long tags = layout.readSynapticTags(segment, offset);
float importance = layout.readImportance(segment, offset);

// Merge tags (OR operation for co-activation)
layout.mergeSynapticTags(segment, offset, additionalTags);

CognitiveHeader

public record CognitiveHeader(
    long timestampMs,       // Unix epoch milliseconds
    long synapticTags,      // 64-bit Bloom filter
    float exactNorm,        // L2 norm of original float vector
    float importance,       // Cognitive importance [0.0 – 1.0]
    int centroidId,         // IVF centroid assignment
    short recallCount,      // Reconsolidation counter
    byte valence,           // Emotional coloring
    byte flags              // Bit flags: [0] tombstone, [1] pinned
) {}

ReflectReport

Summary of a sleep consolidation cycle:

public record ReflectReport(
    int partitionsProcessed,
    int memoriesConsolidated,
    int semanticMemoriesCreated,
    long durationMs
) {}

EpisodicPartition

A single time-partitioned episodic memory file:

// Access partition data
int count = partition.count();
int tombstoneCount = partition.tombstoneCount();
float tombstoneRatio = partition.tombstoneRatio();
PartitionState state = partition.state();
MemorySegment segment = partition.segment();
CognitiveRecordLayout layout = partition.layout();

// Lifecycle operations
partition.seal();                          // Prevent further writes
partition.setState(PartitionState.REFLECTABLE);
partition.force();                          // Flush to disk
partition.close();                          // Release resources

PartitionState

public enum PartitionState {
    ACTIVE,       // Accepting writes
    SEALED,       // Read-only, awaiting consolidation
    REFLECTABLE,  // Consolidation complete, eligible for pruning
    TOMBSTONED,   // High tombstone ratio, queued for compaction
    COMPACTED     // Rebuilt as dense partition
}

Next Steps