Summary
Extract the current hardcoded ImportanceEstimator logic behind a pluggable ImportanceProvider SPI, enabling third-party and domain-specific importance scoring strategies.
Context & Motivation
Origin: Gork Critique Deep Analysis — P0 recommendation #1
Importance is the single most influential signal in Spector's recall ranking pipeline. A memory with importance 8.0 surfaces far more readily than one with importance 0.3, even if both are semantically similar to the query. Despite this critical role:
SalienceProfileProvider SPI exists — handles "what topics matter" via interest/disinterest domains and ICNU weightsImportanceProvider SPI does NOT exist — the "how much does this specific memory matter" question is hardcoded in ImportanceEstimator.java
This means users cannot replace the importance model without modifying core Spector code. The importance pipeline (Welford surprise → ICNU fusion → flashbulb gating → nearest-neighbor novelty) is opinionated and excellent for general use, but domain-specific use cases (enterprise compliance, medical, legal) may need fundamentally different importance strategies.
Current Architecture
SurpriseDetector (Welford z-score)
│
▼
ImportanceEstimator (FINAL CLASS — not pluggable)
├── Welford novelty z-score
├── ICNU fusion (Interest, Challenge, Novelty, Urgency)
├── FlashbulbPolicy (extreme surprise → permanent pin)
└── Nearest-neighbor distance (diversity)
│
▼
ImportanceEstimate (score, isFlashbulb, confidence)
Key files:
ImportanceEstimator.java — final class, hardcoded in SpectorMemoryFactorySurpriseDetector.java — Welford online mean/stddevFlashbulbPolicy.java — extreme surprise detectionIcnuWeights.java — 4-factor weight configurationBiologicalSubsystemsBuilder.java — wires the subsystemSpectorMemoryFactory.java — instantiates new ImportanceEstimator(...)
Proposed Design
1. Define ImportanceProvider SPI
public interface ImportanceProvider {
ImportanceEstimate estimate(ImportanceContext context);
record ImportanceContext(
String text,
float[] embedding,
Map<String, String> metadata,
@Nullable SalienceProfile effectiveProfile,
@Nullable MemoryType targetTier
) {}
record ImportanceEstimate(
double score, // 0.05 – 10.0
boolean isFlashbulb,
double confidence,
Map<String, Double> breakdown // explainability: which factors contributed
) {}
}2. Extract Current Logic as Default Implementation
public final class DefaultImportanceProvider implements ImportanceProvider {
// Current ImportanceEstimator logic, unchanged
// Welford + ICNU + Flashbulb + nearest-neighbor
}3. Provide Reference Alternative Implementations
LlmImportanceProvider — delegates to an LLM for importance judgment (slower, more contextual)HybridImportanceProvider — heuristic first-pass + LLM refinement for high-uncertainty casesFeedbackDrivenImportanceProvider — learns from reinforce/suppress signals over time
4. Add Importance Explainability
When a memory is scored, expose why it received that importance:
{
"score": 7.2,
"breakdown": {
"welford_novelty": 3.8,
"icnu_interest": 1.2,
"icnu_challenge": 0.8,
"icnu_novelty": 0.9,
"icnu_urgency": 0.5,
"salience_boost": 1.2,
"flashbulb": false
}
}Acceptance Criteria
Effort Estimate
2–3 weeks (includes SPI design, extraction, alternative impl, tests, docs)
References
Summary
Extract the current hardcoded
ImportanceEstimatorlogic behind a pluggableImportanceProviderSPI, enabling third-party and domain-specific importance scoring strategies.Context & Motivation
Origin: Gork Critique Deep Analysis — P0 recommendation #1
Importance is the single most influential signal in Spector's recall ranking pipeline. A memory with importance 8.0 surfaces far more readily than one with importance 0.3, even if both are semantically similar to the query. Despite this critical role:
SalienceProfileProviderSPI exists — handles "what topics matter" via interest/disinterest domains and ICNU weightsImportanceProviderSPI does NOT exist — the "how much does this specific memory matter" question is hardcoded inImportanceEstimator.javaThis means users cannot replace the importance model without modifying core Spector code. The importance pipeline (Welford surprise → ICNU fusion → flashbulb gating → nearest-neighbor novelty) is opinionated and excellent for general use, but domain-specific use cases (enterprise compliance, medical, legal) may need fundamentally different importance strategies.
Current Architecture
Key files:
ImportanceEstimator.java—final class, hardcoded inSpectorMemoryFactorySurpriseDetector.java— Welford online mean/stddevFlashbulbPolicy.java— extreme surprise detectionIcnuWeights.java— 4-factor weight configurationBiologicalSubsystemsBuilder.java— wires the subsystemSpectorMemoryFactory.java— instantiatesnew ImportanceEstimator(...)Proposed Design
1. Define
ImportanceProviderSPI2. Extract Current Logic as Default Implementation
3. Provide Reference Alternative Implementations
LlmImportanceProvider— delegates to an LLM for importance judgment (slower, more contextual)HybridImportanceProvider— heuristic first-pass + LLM refinement for high-uncertainty casesFeedbackDrivenImportanceProvider— learns from reinforce/suppress signals over time4. Add Importance Explainability
When a memory is scored, expose why it received that importance:
{ "score": 7.2, "breakdown": { "welford_novelty": 3.8, "icnu_interest": 1.2, "icnu_challenge": 0.8, "icnu_novelty": 0.9, "icnu_urgency": 0.5, "salience_boost": 1.2, "flashbulb": false } }Acceptance Criteria
ImportanceProviderinterface defined inspector-memorypublic APIImportanceEstimatorlogic extracted intoDefaultImportanceProvider(zero behavior change)SpectorMemoryFactory/BiologicalSubsystemsBuilderaccept pluggableImportanceProviderImportanceEstimate.breakdown()memory_rememberresponse includes importance breakdown when availablespector.memory.importance.provider=default|llm|hybrid|customin YAMLEffort Estimate
2–3 weeks (includes SPI design, extraction, alternative impl, tests, docs)
References