engramai 0.2.3

//! Main Memory API — simplified interface to Engram's cognitive models.

use chrono::Utc;
use std::collections::{HashMap, VecDeque};
use std::fs::File;
use std::io::Write;
use uuid::Uuid;

use crate::bus::EmpathyBus;
use crate::config::MemoryConfig;
use crate::embeddings::{EmbeddingConfig, EmbeddingProvider, EmbeddingError};
use crate::entities::EntityExtractor;
use crate::extractor::MemoryExtractor;
use crate::models::{effective_strength, retrieval_activation, run_consolidation_cycle};
use crate::storage::{Storage, EmbeddingStats};
use crate::bus::{SubscriptionManager, Subscription, Notification};
use crate::models::hebbian::{MemoryWithNamespace, record_cross_namespace_coactivation};
use crate::session_wm::{SessionWorkingMemory, SessionRecallResult};
use crate::synthesis::types::SynthesisEngine;
use crate::lifecycle::{DecayReport, ForgetReport, LifecycleError, ReconcileCandidate, ReconcileReport, PhaseReport};
use crate::types::{AclEntry, CrossLink, HebbianLink, LayerStats, MemoryLayer, MemoryRecord, MemoryStats, MemoryType, Permission, RecallResult, RecallWithAssociationsResult, TypeStats};

/// Report from a unified sleep cycle (consolidation + synthesis).
#[derive(Debug)]
pub struct SleepReport {
    /// Whether the consolidation phase completed successfully.
    pub consolidation_ok: bool,
    /// Synthesis report (None if synthesis not enabled or failed non-fatally).
    pub synthesis: Option<crate::synthesis::types::SynthesisReport>,
    /// Per-phase timing reports.
    pub phases: Vec<crate::lifecycle::PhaseReport>,
    /// Decay check report (if run).
    pub decay: Option<crate::lifecycle::DecayReport>,
    /// Forget report (if run).
    pub forget: Option<crate::lifecycle::ForgetReport>,
    /// Rebalance repair report (if run).
    pub rebalance: Option<crate::lifecycle::RebalanceReport>,
    /// Total sleep cycle duration in milliseconds.
    pub duration_ms: u64,
}

/// Check if a memory record is a synthesis insight.
pub fn is_insight(record: &MemoryRecord) -> bool {
    record
        .metadata
        .as_ref()
        .and_then(|m| m.get("is_synthesis"))
        .and_then(|v| v.as_bool())
        .unwrap_or(false)
}

/// Main interface to the Engram memory system.
///
/// Wraps the neuroscience math models behind a clean API.
/// All complexity is hidden — you just add, recall, and consolidate.
pub struct Memory {
    storage: Storage,
    config: MemoryConfig,
    created_at: chrono::DateTime<Utc>,
    /// Agent ID for this memory instance (used for ACL checks)
    agent_id: Option<String>,
    /// Optional Empathy Bus for drive alignment and emotional tracking
    empathy_bus: Option<EmpathyBus>,
    /// Embedding provider for semantic similarity (optional - falls back to FTS if unavailable)
    embedding: Option<EmbeddingProvider>,
    /// Optional LLM-based memory extractor for converting raw text to structured facts
    extractor: Option<Box<dyn MemoryExtractor>>,
    /// Entity extractor for identifying entities in memory content
    entity_extractor: EntityExtractor,
    /// Optional synthesis settings (None = synthesis disabled)
    synthesis_settings: Option<crate::synthesis::types::SynthesisSettings>,
    /// Optional LLM provider for synthesis insight generation
    synthesis_llm_provider: Option<Box<dyn crate::synthesis::types::SynthesisLlmProvider>>,
    /// Interoceptive hub for unified internal state monitoring
    interoceptive_hub: crate::interoceptive::InteroceptiveHub,
    /// Optional LLM-based triple extractor for knowledge graph enrichment
    triple_extractor: Option<Box<dyn crate::triple_extractor::TripleExtractor>>,
    /// Cached emotion data from last LLM extraction: Vec<(valence, domain)>.
    /// One-shot: `take_last_emotions()` clears it.
    last_extraction_emotions: std::sync::Mutex<Option<Vec<(f64, String)>>>,
    /// Recent recall timestamps for cross-recall co-occurrence detection (C8).
    /// Bounded ring buffer: last 50 recalls.
    recent_recalls: VecDeque<(String, std::time::Instant)>,
    /// Last add result for metrics access. Reset each sleep_cycle.
    last_add_result: Option<crate::lifecycle::AddResult>,
    /// Dedup merge counter (reset each sleep_cycle).
    dedup_merge_count: usize,
    /// Dedup new-write counter (reset each sleep_cycle).
    dedup_write_count: usize,
}

impl Memory {
    /// Initialize Engram memory system.
    ///
    /// # Arguments
    ///
    /// * `path` - Path to SQLite database file. Created if it doesn't exist.
    ///   Use `:memory:` for in-memory (non-persistent) operation.
    /// * `config` - MemoryConfig with tunable parameters. None = literature defaults.
    ///
    /// If Ollama is available, embeddings will be used for semantic search.
    /// Otherwise, falls back to FTS5 keyword matching.
    pub fn new(path: &str, config: Option<MemoryConfig>) -> Result<Self, Box<dyn std::error::Error>> {
        let storage = Storage::new(path)?;
        let config = config.unwrap_or_default();
        let created_at = Utc::now();
        
        // Create embedding provider (optional - check if Ollama is available)
        let embedding_provider = EmbeddingProvider::new(config.embedding.clone());
        let embedding = if embedding_provider.is_available() {
            log::info!("Ollama available at {}, embedding enabled", config.embedding.host);
            Some(embedding_provider)
        } else {
            log::warn!("Ollama not available at {}, falling back to FTS", config.embedding.host);
            None
        };

        let entity_extractor = EntityExtractor::new(&config.entity_config);

        let mut mem = Self {
            storage,
            config,
            created_at,
            agent_id: None,
            empathy_bus: None,
            embedding,
            extractor: None,
            entity_extractor,
            synthesis_settings: None,
            synthesis_llm_provider: None,
            interoceptive_hub: crate::interoceptive::InteroceptiveHub::new(),
            triple_extractor: None,
            last_extraction_emotions: std::sync::Mutex::new(None),
            recent_recalls: VecDeque::new(),
            last_add_result: None,
            dedup_merge_count: 0,
            dedup_write_count: 0,
        };
        
        // Auto-configure extractor from environment/config
        mem.auto_configure_extractor();
        
        Ok(mem)
    }
    
    /// Initialize Engram memory system requiring embeddings.
    ///
    /// Returns an error if Ollama is not available. Use this when embedding
    /// support is required for your use case.
    ///
    /// # Arguments
    ///
    /// * `path` - Path to SQLite database file
    /// * `config` - MemoryConfig with tunable parameters
    pub fn new_with_required_embedding(
        path: &str,
        config: Option<MemoryConfig>,
    ) -> Result<Self, Box<dyn std::error::Error>> {
        let storage = Storage::new(path)?;
        let config = config.unwrap_or_default();
        let created_at = Utc::now();
        
        // Create embedding provider and validate Ollama is available
        let embedding = EmbeddingProvider::new(config.embedding.clone());
        if !embedding.is_available() {
            return Err(Box::new(EmbeddingError::OllamaNotAvailable(
                config.embedding.host.clone()
            )));
        }

        let entity_extractor = EntityExtractor::new(&config.entity_config);

        let mut mem = Self {
            storage,
            config,
            created_at,
            agent_id: None,
            empathy_bus: None,
            embedding: Some(embedding),
            extractor: None,
            entity_extractor,
            synthesis_settings: None,
            synthesis_llm_provider: None,
            interoceptive_hub: crate::interoceptive::InteroceptiveHub::new(),
            triple_extractor: None,
            last_extraction_emotions: std::sync::Mutex::new(None),
            recent_recalls: VecDeque::new(),
            last_add_result: None,
            dedup_merge_count: 0,
            dedup_write_count: 0,
        };
        
        // Auto-configure extractor from environment/config
        mem.auto_configure_extractor();
        
        Ok(mem)
    }
    
    /// Initialize Engram memory system with custom embedding config.
    ///
    /// # Arguments
    ///
    /// * `path` - Path to SQLite database file
    /// * `config` - MemoryConfig with tunable parameters
    /// * `embedding_config` - Custom embedding configuration (overrides config.embedding)
    pub fn with_embedding(
        path: &str,
        config: Option<MemoryConfig>,
        embedding_config: EmbeddingConfig,
    ) -> Result<Self, Box<dyn std::error::Error>> {
        let storage = Storage::new(path)?;
        let mut config = config.unwrap_or_default();
        config.embedding = embedding_config;
        let created_at = Utc::now();
        
        // Create embedding provider (optional - check if Ollama is available)
        let embedding_provider = EmbeddingProvider::new(config.embedding.clone());
        let embedding = if embedding_provider.is_available() {
            Some(embedding_provider)
        } else {
            log::warn!("Ollama not available at {}, falling back to FTS", config.embedding.host);
            None
        };

        let entity_extractor = EntityExtractor::new(&config.entity_config);

        let mut mem = Self {
            storage,
            config,
            created_at,
            agent_id: None,
            empathy_bus: None,
            embedding,
            extractor: None,
            entity_extractor,
            synthesis_settings: None,
            synthesis_llm_provider: None,
            interoceptive_hub: crate::interoceptive::InteroceptiveHub::new(),
            triple_extractor: None,
            last_extraction_emotions: std::sync::Mutex::new(None),
            recent_recalls: VecDeque::new(),
            last_add_result: None,
            dedup_merge_count: 0,
            dedup_write_count: 0,
        };
        
        // Auto-configure extractor from environment/config
        mem.auto_configure_extractor();
        
        Ok(mem)
    }
    
    /// Create a Memory instance with an Empathy Bus attached.
    ///
    /// The Empathy Bus connects memory to workspace files (SOUL.md, HEARTBEAT.md)
    /// for drive alignment and empathy feedback loops.
    ///
    /// # Arguments
    ///
    /// * `path` - Path to SQLite database file
    /// * `workspace_dir` - Path to the agent workspace directory
    /// * `config` - Optional MemoryConfig
    pub fn with_empathy_bus(
        path: &str,
        workspace_dir: &str,
        config: Option<MemoryConfig>,
    ) -> Result<Self, Box<dyn std::error::Error>> {
        let storage = Storage::new(path)?;
        let config = config.unwrap_or_default();
        let created_at = Utc::now();
        
        // Create Empathy Bus using storage's connection
        let empathy_bus = Some(EmpathyBus::new(workspace_dir, storage.connection())?);
        
        // Create embedding provider (optional - check if Ollama is available)
        let embedding_provider = EmbeddingProvider::new(config.embedding.clone());
        let embedding = if embedding_provider.is_available() {
            Some(embedding_provider)
        } else {
            log::warn!("Ollama not available at {}, falling back to FTS", config.embedding.host);
            None
        };
        
        let entity_extractor = EntityExtractor::new(&config.entity_config);

        let mut mem = Self {
            storage,
            config,
            created_at,
            agent_id: None,
            empathy_bus,
            embedding,
            extractor: None,
            entity_extractor,
            synthesis_settings: None,
            synthesis_llm_provider: None,
            interoceptive_hub: crate::interoceptive::InteroceptiveHub::new(),
            triple_extractor: None,
            last_extraction_emotions: std::sync::Mutex::new(None),
            recent_recalls: VecDeque::new(),
            last_add_result: None,
            dedup_merge_count: 0,
            dedup_write_count: 0,
        };
        
        // Auto-configure extractor from environment/config
        mem.auto_configure_extractor();
        
        Ok(mem)
    }

    /// Backward-compat alias.
    pub fn with_emotional_bus(
        path: &str,
        workspace_dir: &str,
        config: Option<MemoryConfig>,
    ) -> Result<Self, Box<dyn std::error::Error>> {
        Self::with_empathy_bus(path, workspace_dir, config)
    }
    
    /// Get a reference to the Empathy Bus, if attached.
    pub fn empathy_bus(&self) -> Option<&EmpathyBus> {
        self.empathy_bus.as_ref()
    }

    /// Backward-compat alias.
    #[inline]
    pub fn emotional_bus(&self) -> Option<&EmpathyBus> { self.empathy_bus() }
    
    /// Get a mutable reference to the Empathy Bus, if attached.
    pub fn empathy_bus_mut(&mut self) -> Option<&mut EmpathyBus> {
        self.empathy_bus.as_mut()
    }

    /// Backward-compat alias.
    #[inline]
    pub fn emotional_bus_mut(&mut self) -> Option<&mut EmpathyBus> { self.empathy_bus_mut() }

    // ── Interoceptive Hub API ─────────────────────────────────────────

    /// Get a reference to the interoceptive hub.
    pub fn interoceptive_hub(&self) -> &crate::interoceptive::InteroceptiveHub {
        &self.interoceptive_hub
    }

    /// Get a mutable reference to the interoceptive hub.
    pub fn interoceptive_hub_mut(&mut self) -> &mut crate::interoceptive::InteroceptiveHub {
        &mut self.interoceptive_hub
    }

    /// Take a snapshot of the current interoceptive state.
    ///
    /// Returns the integrated state across all domains — suitable for
    /// injection into system prompts or inspection.
    pub fn interoceptive_snapshot(&self) -> crate::interoceptive::InteroceptiveState {
        self.interoceptive_hub.current_state()
    }

    // ── Extraction Emotion Cache ───────────────────────────────────────

    /// Take the emotion data from the most recent LLM extraction.
    ///
    /// Returns `None` if no extraction has occurred since the last call.
    /// This is one-shot: calling it clears the cache.
    ///
    /// Each entry is `(valence, domain)` — one per extracted fact.
    /// A single user message may produce multiple facts with different
    /// valences and domains.
    pub fn take_last_emotions(&self) -> Option<Vec<(f64, String)>> {
        self.last_extraction_emotions.lock().unwrap().take()
    }

    /// Run an interoceptive tick: pull signals from all attached subsystems
    /// and feed them into the hub.
    ///
    /// Call this periodically (e.g., every heartbeat or every N messages)
    /// to keep the interoceptive state current.
    pub fn interoceptive_tick(&mut self) {
        use crate::bus::accumulator::EmpathyAccumulator;
        use crate::bus::feedback::BehaviorFeedback;
        use crate::interoceptive::InteroceptiveSignal;

        let mut signals: Vec<InteroceptiveSignal> = Vec::new();

        // Pull from DB-backed subsystems via the storage connection.
        let conn = self.storage.connection();

        // Accumulator: pull all empathy trends.
        if let Ok(acc) = EmpathyAccumulator::new(conn) {
            if let Ok(trends) = acc.get_all_trends() {
                for trend in &trends {
                    if let Ok(Some(sig)) = acc.to_signal(&trend.domain) {
                        signals.push(sig);
                    }
                }
            }
        }

        // Feedback: pull all action stats.
        if let Ok(fb) = BehaviorFeedback::new(conn) {
            if let Ok(stats) = fb.get_all_action_stats() {
                for stat in &stats {
                    if let Ok(Some(sig)) = fb.to_signal(&stat.action) {
                        signals.push(sig);
                    }
                }
            }
        }

        // Alignment: generate signal if emotional bus is attached (has drives).
        // Note: alignment is content-dependent, so we skip it in tick.
        // It's triggered per-interaction instead.

        // Feed all collected signals into the hub.
        if !signals.is_empty() {
            log::debug!("Interoceptive tick: processing {} signals", signals.len());
            self.interoceptive_hub.process_batch(signals);
        }
    }

    /// Feed an external interoceptive signal directly into the hub.
    ///
    /// Used by host agents (e.g., RustClaw) to inject runtime-sourced
    /// signals (OperationalLoad, ExecutionStress, CognitiveFlow, ResourcePressure)
    /// that originate outside of engram's own monitoring subsystems.
    pub fn feed_interoceptive_signal(&mut self, signal: crate::interoceptive::InteroceptiveSignal) {
        self.interoceptive_hub.process_signal(signal);
    }

    /// Broadcast memory admission to the interoceptive hub (GWT global workspace).
    ///
    /// When memories enter working memory (via recall), this broadcasts
    /// signals to the hub for integration. Implements Baars' Global Workspace
    /// Theory: working memory contents are "broadcast" to all cognitive modules.
    ///
    /// For each admitted memory:
    /// 1. Generate a confidence signal (metacognitive assessment)
    /// 2. Check drive alignment if emotional bus is attached
    /// 3. Spread activation to Hebbian neighbors (associative priming)
    ///
    /// Returns the IDs of Hebbian neighbors activated (for potential WM boosting).
    pub fn broadcast_admission(
        &mut self,
        memory_ids: &[String],
        session_wm: &mut SessionWorkingMemory,
    ) -> Vec<String> {
        use crate::interoceptive::InteroceptiveSignal;

        let mut signals: Vec<InteroceptiveSignal> = Vec::new();
        let mut neighbor_ids: Vec<String> = Vec::new();

        for memory_id in memory_ids {
            // Fetch the memory record for signal generation.
            let record = match self.storage.get(memory_id) {
                Ok(Some(r)) => r,
                _ => continue,
            };

            // 1. Confidence signal — metacognitive assessment of this memory.
            let conf_signal = crate::confidence::confidence_to_signal(&record, None, None);
            signals.push(conf_signal);

            // 2. Alignment signal — does this memory align with core drives?
            if let Some(ref bus) = self.empathy_bus {
                let drives = bus.drives();
                if !drives.is_empty() {
                    let align_signal =
                        crate::bus::alignment::alignment_to_signal(&record.content, drives);
                    signals.push(align_signal);
                }
            }

            // 3. Spreading activation — Hebbian neighbors get primed.
            if self.config.hebbian_enabled {
                if let Ok(neighbors) = self.storage.get_hebbian_links_weighted(memory_id) {
                    for (neighbor_id, weight) in &neighbors {
                        // Only spread to neighbors with meaningful link strength.
                        if *weight > 0.1 {
                            neighbor_ids.push(neighbor_id.clone());
                        }
                    }
                }
            }
        }

        // Feed all broadcast signals into the hub.
        if !signals.is_empty() {
            log::debug!(
                "GWT broadcast: {} memories → {} signals",
                memory_ids.len(),
                signals.len()
            );
            self.interoceptive_hub.process_batch(signals);
        }

        // Boost Hebbian neighbors in working memory (associative priming).
        // This implements spreading activation: memories connected to the
        // admitted ones get a small activation boost in WM.
        if !neighbor_ids.is_empty() {
            neighbor_ids.dedup();
            session_wm.activate(&neighbor_ids);
            log::debug!(
                "GWT spreading activation: {} Hebbian neighbors primed",
                neighbor_ids.len()
            );
        }

        neighbor_ids
    }
    
    /// Get the last add result (Created or Merged).
    pub fn last_add_result(&self) -> Option<&crate::lifecycle::AddResult> {
        self.last_add_result.as_ref()
    }

    /// Get a reference to the underlying storage connection.
    pub fn connection(&self) -> &rusqlite::Connection {
        self.storage.connection()
    }

    /// Get a reference to the underlying Storage.
    pub fn storage(&self) -> &Storage {
        &self.storage
    }

    /// Get a mutable reference to the underlying Storage.
    pub fn storage_mut(&mut self) -> &mut Storage {
        &mut self.storage
    }

    /// Access recent recalls ring buffer (for testing/inspection).
    pub fn recent_recalls(&self) -> &VecDeque<(String, std::time::Instant)> {
        &self.recent_recalls
    }

    /// Mutable access to recent recalls (for testing).
    pub fn recent_recalls_mut(&mut self) -> &mut VecDeque<(String, std::time::Instant)> {
        &mut self.recent_recalls
    }

    /// Scan namespace for duplicate pairs above similarity threshold.
    /// Returns candidates sorted by combined score (0.7 * embedding_sim + 0.3 * entity_jaccard).
    pub fn reconcile(
        &self,
        namespace: &str,
        max_scan: Option<usize>,
    ) -> Result<Vec<ReconcileCandidate>, LifecycleError> {
        let max_scan = max_scan.unwrap_or(1000);
        let model_id = self.config.embedding.model_id();

        // Load embeddings (bounded)
        let embeddings = self.storage.get_embeddings_in_namespace(
            Some(namespace), &model_id,
        ).map_err(LifecycleError::Storage)?;

        // Bound by max_scan
        let embeddings: Vec<_> = embeddings.into_iter().take(max_scan).collect();

        let mut candidates: Vec<ReconcileCandidate> = Vec::new();
        let mut seen_pairs: std::collections::HashSet<(String, String)> = std::collections::HashSet::new();

        for (id_a, emb_a) in &embeddings {
            let matches = self.storage.find_all_above_threshold(
                emb_a, &model_id, Some(namespace), 0.85,
            ).map_err(LifecycleError::Storage)?;

            for (id_b, score) in matches {
                if id_a == &id_b { continue; }
                let pair = if id_a < &id_b {
                    (id_a.clone(), id_b.clone())
                } else {
                    (id_b.clone(), id_a.clone())
                };
                if seen_pairs.contains(&pair) { continue; }
                seen_pairs.insert(pair);

                let entities_a = self.storage.get_entities_for_memory(id_a)
                    .map_err(LifecycleError::Storage)?;
                let entities_b = self.storage.get_entities_for_memory(&id_b)
                    .map_err(LifecycleError::Storage)?;
                let jaccard = jaccard_similarity_strings(&entities_a, &entities_b);

                let preview_a = self.storage.get_memory_content_preview(id_a, 100)
                    .map_err(LifecycleError::Storage)?;
                let preview_b = self.storage.get_memory_content_preview(&id_b, 100)
                    .map_err(LifecycleError::Storage)?;

                candidates.push(ReconcileCandidate {
                    id_a: id_a.clone(),
                    id_b,
                    similarity: score,
                    entity_overlap: jaccard,
                    content_preview_a: preview_a,
                    content_preview_b: preview_b,
                });
            }
        }

        // Sort by combined score: 0.7 * similarity + 0.3 * entity_overlap
        candidates.sort_by(|a, b| {
            let score_a = 0.7 * a.similarity as f64 + 0.3 * a.entity_overlap;
            let score_b = 0.7 * b.similarity as f64 + 0.3 * b.entity_overlap;
            score_b.partial_cmp(&score_a).unwrap_or(std::cmp::Ordering::Equal)
        });

        Ok(candidates)
    }

    /// Apply reconcile merges. If dry_run=true, just counts.
    pub fn reconcile_apply(
        &mut self,
        candidates: &[ReconcileCandidate],
        dry_run: bool,
    ) -> Result<ReconcileReport, LifecycleError> {
        let mut report = ReconcileReport {
            scanned: candidates.len(),
            candidates_found: candidates.len(),
            merges_applied: 0,
            dry_run,
        };

        if dry_run { return Ok(report); }

        let mut merged_away: std::collections::HashSet<String> = std::collections::HashSet::new();

        for candidate in candidates {
            if merged_away.contains(&candidate.id_a) || merged_away.contains(&candidate.id_b) {
                continue;
            }

            // Keep the older memory, merge newer into it
            let (keep_id, donor_id) = {
                let a = self.storage.get(&candidate.id_a).map_err(LifecycleError::Storage)?;
                let b = self.storage.get(&candidate.id_b).map_err(LifecycleError::Storage)?;
                match (a, b) {
                    (Some(a), Some(b)) => {
                        if a.created_at <= b.created_at {
                            (candidate.id_a.clone(), candidate.id_b.clone())
                        } else {
                            (candidate.id_b.clone(), candidate.id_a.clone())
                        }
                    }
                    _ => continue, // one already gone
                }
            };

            // Get donor content for merge
            let donor_content = self.storage.get_memory_content_preview(&donor_id, 10000)
                .map_err(LifecycleError::Storage)?;

            // Use existing merge_memory_into
            self.storage.merge_memory_into(&keep_id, &donor_content, 0.0, candidate.similarity)
                .map_err(LifecycleError::Storage)?;

            // Merge Hebbian links
            let _ = self.storage.merge_hebbian_links(&donor_id, &keep_id);

            // Record provenance
            let _ = self.storage.append_merge_provenance(
                &keep_id, &donor_id, candidate.similarity, false,
            );

            // Delete donor
            self.storage.hard_delete_cascade(&donor_id)
                .map_err(LifecycleError::Storage)?;

            merged_away.insert(donor_id);
            report.merges_applied += 1;
        }

        Ok(report)
    }

    // === Lifecycle: Decay Detection + Safe Forget (FEAT-003 C5+C6) ===

    /// Check memories for decay using Ebbinghaus model and flag weak ones.
    /// Called during sleep_cycle's forget phase.
    pub fn check_decay_and_flag(
        &mut self,
        namespace: Option<&str>,
    ) -> Result<DecayReport, LifecycleError> {
        use crate::models::ebbinghaus;

        let memories = self.storage.all_in_namespace(namespace)
            .map_err(LifecycleError::Storage)?;
        let now = Utc::now();
        let mut report = DecayReport::default();

        for record in &memories {
            if record.pinned {
                continue;
            }
            let effective = ebbinghaus::effective_strength(record, now);
            if effective < 0.1 {
                report.below_threshold += 1;
                // Only auto-flag if rarely accessed (< 2 accesses)
                if record.access_times.len() < 2 {
                    self.storage.soft_delete(&record.id)
                        .map_err(LifecycleError::Storage)?;
                    report.flagged_for_forget += 1;
                    log::debug!(
                        "memory {} flagged for forget via Ebbinghaus decay (effective_strength={}, access_count={})",
                        record.id,
                        effective,
                        record.access_times.len(),
                    );
                }
            }
        }

        Ok(report)
    }

    /// Targeted forget: soft or hard delete a specific memory.
    pub fn forget_targeted(
        &mut self,
        memory_id: &str,
        soft: bool,
    ) -> Result<(), LifecycleError> {
        if soft {
            self.storage.soft_delete(memory_id)
                .map_err(LifecycleError::Storage)?;
            log::info!("soft-deleted memory {}", memory_id);
        } else {
            self.storage.hard_delete_cascade(memory_id)
                .map_err(LifecycleError::Storage)?;
            log::info!("hard-deleted memory {} with cascade", memory_id);
        }
        Ok(())
    }

    /// Bulk forget: soft-delete weak memories, hard-delete old soft-deleted ones.
    pub fn forget_bulk(&mut self) -> Result<ForgetReport, LifecycleError> {
        let mut report = ForgetReport::default();
        let now = Utc::now();

        // Phase A: soft-delete weak memories (that aren't already soft-deleted)
        let all = self.storage.all_in_namespace(None)  // active memories only
            .map_err(LifecycleError::Storage)?;
        report.scanned = all.len();

        for record in &all {
            if record.pinned { continue; }
            let effective = crate::models::ebbinghaus::effective_strength(record, now);
            if effective < self.config.forget_threshold {
                self.storage.soft_delete(&record.id)
                    .map_err(LifecycleError::Storage)?;
                report.soft_deleted += 1;
            }
        }

        // Phase B: hard-delete memories that were soft-deleted > 30 days ago
        let deleted = self.storage.list_deleted(Some("*"))
            .map_err(LifecycleError::Storage)?;
        for record in &deleted {
            // Parse deleted_at from DB column
            if let Some(deleted_at_str) = self.storage.get_deleted_at(&record.id)
                .map_err(LifecycleError::Storage)?
            {
                if let Ok(deleted_at) = chrono::DateTime::parse_from_rfc3339(&deleted_at_str) {
                    let days_deleted = (now - deleted_at.with_timezone(&Utc)).num_days();
                    if days_deleted > 30 {
                        self.storage.hard_delete_cascade(&record.id)
                            .map_err(LifecycleError::Storage)?;
                        report.hard_deleted += 1;
                    }
                }
            }
        }

        Ok(report)
    }

    /// Health check: inspect memory system integrity.
    pub fn health(&self) -> Result<crate::lifecycle::HealthReport, LifecycleError> {
        use crate::lifecycle::HealthReport;

        let total = self.storage.count_memories_in_namespace(None)
            .map_err(LifecycleError::Storage)?;
        let namespaces = self.storage.list_namespaces()
            .map_err(LifecycleError::Storage)?;
        let mut per_ns = std::collections::HashMap::new();
        for ns in &namespaces {
            let count = self.storage.count_memories_in_namespace(Some(ns))
                .map_err(LifecycleError::Storage)?;
            per_ns.insert(ns.clone(), count);
        }
        let orphans = self.storage.count_orphan_memories()
            .map_err(LifecycleError::Storage)?;
        let dangling = self.storage.count_dangling_hebbian()
            .map_err(LifecycleError::Storage)?;
        let soft_del = self.storage.count_soft_deleted()
            .map_err(LifecycleError::Storage)?;

        // Count memories below decay threshold
        let all = self.storage.all_in_namespace(None).map_err(LifecycleError::Storage)?;
        let now = Utc::now();
        let below = all.iter()
            .filter(|r| crate::models::ebbinghaus::effective_strength(r, now) < 0.1)
            .count();

        Ok(HealthReport {
            total_memories: total,
            per_namespace: per_ns,
            below_threshold: below,
            orphan_memories: orphans,
            stale_clusters: 0,  // TODO: implement stale cluster counting
            dangling_hebbian_links: dangling,
            soft_deleted: soft_del,
        })
    }

    /// Rebalance: repair integrity issues.
    pub fn rebalance(&mut self) -> Result<crate::lifecycle::RebalanceReport, LifecycleError> {
        self.rebalance_internal()
    }

    fn rebalance_internal(&mut self) -> Result<crate::lifecycle::RebalanceReport, LifecycleError> {
        let mut report = crate::lifecycle::RebalanceReport::default();

        // 1. Remove orphaned access_log entries
        report.access_log_cleaned = self.storage.cleanup_orphaned_access_log()
            .map_err(LifecycleError::Storage)?;

        // 2. Repair dangling Hebbian links
        report.hebbian_repaired = self.storage.cleanup_dangling_hebbian()
            .map_err(LifecycleError::Storage)?;

        // 3. Cleanup entity_links for deleted memories
        report.entity_links_cleaned = self.storage.cleanup_orphaned_entity_links()
            .map_err(LifecycleError::Storage)?;

        // Note: embedding rebuilding requires EmbeddingProvider which is optional.
        // Skip for now — embeddings are rebuilt on next recall if missing.

        report.repairs = report.access_log_cleaned
            + report.hebbian_repaired
            + report.entity_links_cleaned;

        Ok(report)
    }

    // ── Supersession: High-Level API (Step 5) ──────────────────────────

    /// Correct a single memory: create a replacement and supersede the old one.
    ///
    /// This is the recommended way to fix wrong memories. It:
    /// 1. Fetches the old memory to inherit type/importance/namespace
    /// 2. Stores the new content as a fresh memory
    /// 3. Marks the old memory as superseded by the new one
    ///
    /// Returns the new memory's ID.
    pub fn correct(
        &mut self,
        old_id: &str,
        new_content: &str,
        importance_override: Option<f64>,
        memory_type_override: Option<MemoryType>,
    ) -> Result<String, Box<dyn std::error::Error>> {
        // 1. Fetch old memory
        let old = self.storage.get(old_id)?
            .ok_or_else(|| format!("Memory not found: {}", old_id))?;

        // 2. Determine type and importance
        let memory_type = memory_type_override.unwrap_or(old.memory_type);
        let importance = importance_override.unwrap_or_else(|| old.importance.max(0.5));

        // 3. Get namespace of old memory
        let namespace = self.storage.get_namespace(old_id)?;
        let ns_ref = namespace.as_deref();

        // 4. Store the new memory in the same namespace
        let new_id = self.add_to_namespace(
            new_content,
            memory_type,
            Some(importance),
            Some("correction"),
            None,
            ns_ref,
        )?;

        // 5. Supersede old → new
        self.storage.supersede(old_id, &new_id)
            .map_err(|e| format!("Supersession failed after storing new memory: {}", e))?;

        log::info!("Corrected memory {} → {} in namespace {:?}", old_id, new_id, ns_ref);
        Ok(new_id)
    }

    /// Correct multiple memories matching a query: find them, create a replacement,
    /// and supersede all matches.
    ///
    /// The confirmation step (showing matches before applying) is handled at the
    /// CLI layer, not here. This method is unconditional.
    ///
    /// Returns a `BulkCorrectionResult` with the new ID and all superseded IDs.
    pub fn correct_bulk(
        &mut self,
        query: &str,
        new_content: &str,
        namespace: Option<&str>,
        limit: usize,
    ) -> Result<crate::types::BulkCorrectionResult, Box<dyn std::error::Error>> {
        // 1. Find matching memories via recall
        let matches = self.recall_from_namespace(query, limit, None, None, namespace)?;
        if matches.is_empty() {
            return Err("No matching memories found for correction".into());
        }

        // 2. Determine memory type from the highest-scored match
        let best_match = &matches[0];
        let memory_type = best_match.record.memory_type;

        // 3. Store the new correction memory
        let new_id = self.add_to_namespace(
            new_content,
            memory_type,
            Some(0.7), // Corrections get moderate-high importance
            Some("bulk_correction"),
            None,
            namespace,
        )?;

        // 4. Supersede all matching memories
        let ids: Vec<String> = matches.iter().map(|r| r.record.id.clone()).collect();
        let id_refs: Vec<&str> = ids.iter().map(|s| s.as_str()).collect();
        let count = self.storage.supersede_bulk(&id_refs, &new_id)
            .map_err(|e| format!("Bulk supersession failed: {}", e))?;

        log::info!("Bulk corrected {} memories → {} (query: '{}')", count, new_id, query);

        Ok(crate::types::BulkCorrectionResult {
            new_id,
            superseded_count: count,
            superseded_ids: ids,
        })
    }

    /// List all superseded memories (observability).
    ///
    /// Returns superseded records with their replacement ID and chain head.
    pub fn list_superseded(
        &self,
        namespace: Option<&str>,
    ) -> Result<Vec<crate::types::SupersessionInfo>, Box<dyn std::error::Error>> {
        let pairs = self.storage.list_superseded(namespace)?;
        let mut results = Vec::with_capacity(pairs.len());
        for (record, replacement_id) in pairs {
            let chain_head = self.storage.resolve_chain_head(&replacement_id)?;
            results.push(crate::types::SupersessionInfo {
                superseded: record,
                superseded_by_id: replacement_id,
                chain_head,
            });
        }
        Ok(results)
    }

    /// Undo a supersession, restoring a memory to active recall.
    pub fn unsupersede(&mut self, id: &str) -> Result<(), Box<dyn std::error::Error>> {
        self.storage.unsupersede(id)
            .map_err(|e| format!("Unsupersede failed: {}", e))?;
        log::info!("Restored memory {} to active recall", id);
        Ok(())
    }

    /// Set the agent ID for this memory instance.
    /// 
    /// This is used for ACL checks when storing and recalling memories.
    /// Each agent should identify itself before performing operations.
    pub fn set_agent_id(&mut self, id: &str) {
        self.agent_id = Some(id.to_string());
    }
    
    /// Get the current agent ID.
    pub fn agent_id(&self) -> Option<&str> {
        self.agent_id.as_deref()
    }
    
    /// Set a memory extractor for LLM-based fact extraction.
    ///
    /// When an extractor is set, `add()` and `add_to_namespace()` will
    /// pass the raw content through the LLM to extract structured facts,
    /// storing each fact as a separate memory. If extraction fails,
    /// the raw content is stored as a fallback.
    ///
    /// # Arguments
    ///
    /// * `extractor` - The extractor implementation (e.g., AnthropicExtractor, OllamaExtractor)
    pub fn set_extractor(&mut self, extractor: Box<dyn MemoryExtractor>) {
        self.extractor = Some(extractor);
    }

    /// Set the synthesis settings. Enables knowledge synthesis during consolidation.
    ///
    /// Synthesis is opt-in: it only runs when settings.enabled is true.
    /// This maintains backward compatibility (GUARD-3).
    pub fn set_synthesis_settings(&mut self, settings: crate::synthesis::types::SynthesisSettings) {
        self.synthesis_settings = Some(settings);
    }

    /// Set the LLM provider for synthesis insight generation.
    ///
    /// Without a provider, synthesis still discovers clusters and runs the gate check,
    /// but skips LLM insight generation (graceful degradation).
    pub fn set_synthesis_llm_provider(&mut self, provider: Box<dyn crate::synthesis::types::SynthesisLlmProvider>) {
        self.synthesis_llm_provider = Some(provider);
    }

    /// Set the LLM triple extractor for knowledge graph enrichment during consolidation.
    pub fn set_triple_extractor(&mut self, extractor: Box<dyn crate::triple_extractor::TripleExtractor>) {
        self.triple_extractor = Some(extractor);
    }
    
    /// Remove the memory extractor (revert to storing raw content).
    pub fn clear_extractor(&mut self) {
        self.extractor = None;
    }
    
    /// Check if an extractor is configured.
    pub fn has_extractor(&self) -> bool {
        self.extractor.is_some()
    }
    
    /// Auto-configure extractor from environment and config file.
    ///
    /// Called during Memory::new() if no extractor is explicitly set.
    /// This provides "just works" behavior for users who set env vars.
    ///
    /// Detection order (high → low priority):
    /// 1. ANTHROPIC_AUTH_TOKEN env var → AnthropicExtractor with OAuth
    /// 2. ANTHROPIC_API_KEY env var → AnthropicExtractor with API key
    /// 3. ~/.config/engram/config.json extractor section
    /// 4. None → no extraction (backward compatible)
    ///
    /// Model can be overridden via ENGRAM_EXTRACTOR_MODEL env var.
    pub fn auto_configure_extractor(&mut self) {
        use crate::extractor::{AnthropicExtractor, AnthropicExtractorConfig};
        
        // Check ANTHROPIC_AUTH_TOKEN first (OAuth mode)
        if let Ok(token) = std::env::var("ANTHROPIC_AUTH_TOKEN") {
            let model = std::env::var("ENGRAM_EXTRACTOR_MODEL")
                .unwrap_or_else(|_| "claude-haiku-4-5-20251001".to_string());
            let config = AnthropicExtractorConfig {
                model,
                ..Default::default()
            };
            self.extractor = Some(Box::new(AnthropicExtractor::with_config(&token, true, config)));
            log::info!("Extractor: Anthropic (OAuth) from ANTHROPIC_AUTH_TOKEN");
            return;
        }
        
        // Check ANTHROPIC_API_KEY (API key mode)
        if let Ok(key) = std::env::var("ANTHROPIC_API_KEY") {
            let model = std::env::var("ENGRAM_EXTRACTOR_MODEL")
                .unwrap_or_else(|_| "claude-haiku-4-5-20251001".to_string());
            let config = AnthropicExtractorConfig {
                model,
                ..Default::default()
            };
            self.extractor = Some(Box::new(AnthropicExtractor::with_config(&key, false, config)));
            log::info!("Extractor: Anthropic (API key) from ANTHROPIC_API_KEY");
            return;
        }
        
        // Check config file
        if let Some(extractor) = self.load_extractor_from_config() {
            self.extractor = Some(extractor);
            return;
        }
        
        // No extractor configured - that's fine, backward compatible
        log::debug!("No extractor configured, storing raw text");
    }
    
    /// Load extractor configuration from ~/.config/engram/config.json.
    ///
    /// The config file stores non-sensitive settings (provider, model, host).
    /// Auth tokens MUST come from environment variables or code.
    ///
    /// Config format:
    /// ```json
    /// {
    ///   "extractor": {
    ///     "provider": "anthropic",  // or "ollama"
    ///     "model": "claude-haiku-4-5-20251001"
    ///   }
    /// }
    /// ```
    fn load_extractor_from_config(&self) -> Option<Box<dyn MemoryExtractor>> {
        use crate::extractor::{AnthropicExtractor, AnthropicExtractorConfig, OllamaExtractor};
        
        // Get config directory
        let config_path = dirs::config_dir()?.join("engram/config.json");
        if !config_path.exists() {
            return None;
        }
        
        // Read and parse config file
        let content = std::fs::read_to_string(&config_path).ok()?;
        let config: serde_json::Value = serde_json::from_str(&content).ok()?;
        
        // Get extractor section
        let extractor_config = config.get("extractor")?;
        let provider = extractor_config.get("provider")?.as_str()?;
        
        match provider {
            "anthropic" => {
                // Still need env var for auth - config file NEVER stores tokens
                let token = std::env::var("ANTHROPIC_AUTH_TOKEN")
                    .or_else(|_| std::env::var("ANTHROPIC_API_KEY"))
                    .ok()?;
                let is_oauth = std::env::var("ANTHROPIC_AUTH_TOKEN").is_ok();
                
                let model = extractor_config
                    .get("model")
                    .and_then(|v| v.as_str())
                    .unwrap_or("claude-haiku-4-5-20251001")
                    .to_string();
                
                let api_config = AnthropicExtractorConfig {
                    model: model.clone(),
                    ..Default::default()
                };
                
                log::info!("Extractor: Anthropic ({}) from config file", model);
                Some(Box::new(AnthropicExtractor::with_config(&token, is_oauth, api_config)))
            }
            "ollama" => {
                let model = extractor_config
                    .get("model")
                    .and_then(|v| v.as_str())
                    .unwrap_or("llama3.2:3b")
                    .to_string();
                let host = extractor_config
                    .get("host")
                    .and_then(|v| v.as_str())
                    .unwrap_or("http://localhost:11434")
                    .to_string();
                
                log::info!("Extractor: Ollama ({}) from config file", model);
                Some(Box::new(OllamaExtractor::with_host(&model, &host)))
            }
            _ => {
                log::warn!("Unknown extractor provider in config: {}", provider);
                None
            }
        }
    }

    /// Store a new memory. Returns memory ID.
    ///
    /// The memory is encoded with initial working_strength=1.0 (strong
    /// hippocampal trace) and core_strength=0.0 (no neocortical trace yet).
    /// Consolidation cycles will gradually transfer it to core.
    ///
    /// # Arguments
    ///
    /// * `content` - The memory content (natural language)
    /// * `memory_type` - Memory type classification
    /// * `importance` - 0-1 importance score (None = auto from type)
    /// * `source` - Source identifier (e.g., filename, conversation ID)
    /// * `metadata` - Optional structured metadata (e.g., for causal memories)
    pub fn add(
        &mut self,
        content: &str,
        memory_type: MemoryType,
        importance: Option<f64>,
        source: Option<&str>,
        metadata: Option<serde_json::Value>,
    ) -> Result<String, Box<dyn std::error::Error>> {
        self.add_to_namespace(content, memory_type, importance, source, metadata, None)
    }
    
    /// Store a new memory in a specific namespace. Returns memory ID.
    ///
    /// If an extractor is configured, the content is first passed through
    /// the LLM to extract structured facts. Each extracted fact is stored
    /// as a separate memory. If extraction fails or returns nothing,
    /// the raw content is stored as a fallback.
    ///
    /// # Arguments
    ///
    /// * `content` - The memory content (natural language)
    /// * `memory_type` - Memory type classification (used as fallback if extraction fails)
    /// * `importance` - 0-1 importance score (None = auto from type, or from extraction)
    /// * `source` - Source identifier (e.g., filename, conversation ID)
    /// * `metadata` - Optional structured metadata (e.g., for causal memories)
    /// * `namespace` - Namespace to store in (None = "default")
    pub fn add_to_namespace(
        &mut self,
        content: &str,
        memory_type: MemoryType,
        importance: Option<f64>,
        source: Option<&str>,
        metadata: Option<serde_json::Value>,
        namespace: Option<&str>,
    ) -> Result<String, Box<dyn std::error::Error>> {
        // If extractor is configured, try to extract facts first
        if let Some(ref extractor) = self.extractor {
            match extractor.extract(content) {
                Ok(facts) if !facts.is_empty() => {
                    log::info!("Extracted {} facts from content ({}...)", facts.len(),
                        content.chars().take(40).collect::<String>());
                    let mut last_id = String::new();
                    for fact in &facts {
                        log::info!("  → [{}] (imp={:.1}, val={:.2}, dom={}) {}", 
                            fact.memory_type, fact.importance, fact.valence, fact.domain,
                            fact.content.chars().take(80).collect::<String>());
                    }
                    
                    // Cache emotion data from extraction for downstream consumers
                    let emotions: Vec<(f64, String)> = facts.iter()
                        .map(|f| (f.valence, f.domain.clone()))
                        .collect();
                    *self.last_extraction_emotions.lock().unwrap() = Some(emotions);
                    
                    for fact in facts {
                        // Convert extracted memory_type string to MemoryType enum
                        let fact_type = Self::parse_memory_type(&fact.memory_type)
                            .unwrap_or(memory_type);
                        
                        // Cap auto-extracted importance to prevent noise from dominating recall
                        let capped_importance = fact.importance.min(self.config.auto_extract_importance_cap);
                        if fact.importance > self.config.auto_extract_importance_cap {
                            log::debug!("  ↓ importance capped: {:.2} → {:.2}", fact.importance, capped_importance);
                        }
                        let fact_importance = Some(capped_importance);
                        
                        // Store each extracted fact separately
                        last_id = self.add_raw(
                            &fact.content,
                            fact_type,
                            fact_importance,
                            source,
                            metadata.clone(),
                            namespace,
                        )?;
                    }
                    return Ok(last_id);
                }
                Ok(_) => {
                    // No facts extracted - nothing worth storing
                    log::info!("Extractor: nothing worth storing in: {}...", 
                        content.chars().take(50).collect::<String>());
                    return Ok(String::new());
                }
                Err(e) => {
                    // Extractor failed - fall back to storing raw text
                    log::warn!("Extractor failed, storing raw: {}", e);
                    // Fall through to raw storage below
                }
            }
        }
        
        // No extractor or extractor failed - store raw (backward compatible)
        self.add_raw(content, memory_type, importance, source, metadata, namespace)
    }
    
    /// Parse a memory type string into MemoryType enum.
    fn parse_memory_type(s: &str) -> Option<MemoryType> {
        match s.to_lowercase().as_str() {
            "factual" => Some(MemoryType::Factual),
            "episodic" => Some(MemoryType::Episodic),
            "relational" => Some(MemoryType::Relational),
            "emotional" => Some(MemoryType::Emotional),
            "procedural" => Some(MemoryType::Procedural),
            "opinion" => Some(MemoryType::Opinion),
            "causal" => Some(MemoryType::Causal),
            _ => None,
        }
    }
    
    /// Store a memory directly without extraction (internal method).
    ///
    /// This is the raw storage path used when no extractor is configured
    /// or when extractor fails.
    ///
    /// Flow (with dedup):
    /// 1. Generate embedding (if provider available)
    /// 2. If dedup enabled + have embedding → check for duplicates
    /// 3. If duplicate found → merge_memory_into + return existing_id
    /// 4. If no duplicate → storage.add() the new record
    /// 5. Store the pre-computed embedding (don't re-embed)
    /// 6. Extract entities
    fn add_raw(
        &mut self,
        content: &str,
        memory_type: MemoryType,
        importance: Option<f64>,
        source: Option<&str>,
        metadata: Option<serde_json::Value>,
        namespace: Option<&str>,
    ) -> Result<String, Box<dyn std::error::Error>> {
        let ns = namespace.unwrap_or("default");
        let id = format!("{}", Uuid::new_v4())[..8].to_string();
        let base_importance = importance.unwrap_or_else(|| memory_type.default_importance());
        
        // Apply drive alignment boost if Empathy Bus is attached
        let importance = if let Some(ref bus) = self.empathy_bus {
            let boost = bus.align_importance(content);
            (base_importance * boost).min(1.0) // Cap at 1.0
        } else {
            base_importance
        };

        // Step 1: Generate embedding up front (if provider available)
        // We need it before storage for dedup check, and reuse it after storage.
        let pre_embedding = if let Some(ref embedding_provider) = self.embedding {
            match embedding_provider.embed(content) {
                Ok(emb) => Some(emb),
                Err(e) => {
                    log::warn!("Failed to generate embedding for dedup/storage: {}", e);
                    None
                }
            }
        } else {
            None
        };

        // Step 2: Dedup check — entity Jaccard + embedding similarity
        if self.config.dedup_enabled {
            // Phase A: entity Jaccard pre-check (if entities are available)
            if self.config.entity_config.enabled {
                let entities = self.entity_extractor.extract(content);
                let entity_names: Vec<String> = entities.iter()
                    .map(|e| e.normalized.clone())
                    .collect();
                
                if !entity_names.is_empty() {
                    if let Ok(Some((candidate_id, _jaccard))) = 
                        self.storage.find_entity_overlap(&entity_names, ns, 0.5) 
                    {
                        // Entity overlap found — confirm with embedding similarity
                        if let Some(ref embedding) = pre_embedding {
                            // Check similarity specifically against the candidate
                            if let Ok(Some(candidate_emb)) = self.storage.get_embedding_for_memory(&candidate_id) {
                                let sim = crate::embeddings::EmbeddingProvider::cosine_similarity(embedding, &candidate_emb);
                                if sim as f64 >= self.config.dedup_threshold {
                                    log::info!(
                                        "Dedup (entity+embedding): merging into {} (jaccard={:.3}, sim={:.4})",
                                        candidate_id, _jaccard, sim
                                    );
                                    let outcome = self.storage.merge_memory_into(
                                        &candidate_id, content, importance, sim,
                                    )?;
                                    if outcome.content_updated {
                                        log::info!(
                                            "Dedup: content updated for {} (merge_count={})",
                                            candidate_id, outcome.merge_count,
                                        );
                                    }
                                    // Update entity links for the merged memory
                                    for entity in &entities {
                                        if let Ok(eid) = self.storage.upsert_entity(
                                            &entity.normalized, entity.entity_type.as_str(), ns, None,
                                        ) {
                                            let _ = self.storage.link_memory_entity(&candidate_id, &eid, "mention");
                                        }
                                    }
                                    self.last_add_result = Some(crate::lifecycle::AddResult::Merged { 
                                        into: candidate_id.clone(), similarity: sim 
                                    });
                                    self.dedup_merge_count += 1;
                                    return Ok(candidate_id);
                                }
                            }
                        }
                    }
                }
            }
            
            // Phase B: embedding-only dedup (existing logic, catches cases without entities)
            if let Some(ref embedding) = pre_embedding {
                let model_id = self.config.embedding.model_id();
                if let Ok(Some((existing_id, similarity))) = self.storage.find_nearest_embedding(
                    embedding, &model_id, Some(ns), self.config.dedup_threshold,
                ) {
                    log::info!(
                        "Dedup: merging into existing memory {} (similarity: {:.4})",
                        existing_id, similarity
                    );
                    let outcome = self.storage.merge_memory_into(
                        &existing_id, content, importance, similarity,
                    )?;
                    if outcome.content_updated {
                        log::info!(
                            "Dedup: content updated for {} (merge_count={})",
                            existing_id, outcome.merge_count,
                        );
                    }
                    if self.config.entity_config.enabled {
                        let entities = self.entity_extractor.extract(content);
                        for entity in &entities {
                            if let Ok(eid) = self.storage.upsert_entity(
                                &entity.normalized, entity.entity_type.as_str(), ns, None,
                            ) {
                                let _ = self.storage.link_memory_entity(&existing_id, &eid, "mention");
                            }
                        }
                    }
                    self.last_add_result = Some(crate::lifecycle::AddResult::Merged { 
                        into: existing_id.clone(), similarity 
                    });
                    self.dedup_merge_count += 1;
                    return Ok(existing_id);
                }
            }
        }

        // Step 3: No duplicate found — create new memory record
        let record = MemoryRecord {
            id: id.clone(),
            content: content.to_string(),
            memory_type,
            layer: MemoryLayer::Working,
            created_at: Utc::now(),
            access_times: vec![Utc::now()],
            working_strength: 1.0,
            core_strength: 0.0,
            importance,
            pinned: false,
            consolidation_count: 0,
            last_consolidated: None,
            source: source.unwrap_or("").to_string(),
            contradicts: None,
            contradicted_by: None,
            superseded_by: None,
            metadata,
        };

        self.storage.add(&record, ns)?;
        self.last_add_result = Some(crate::lifecycle::AddResult::Created { id: id.clone() });
        self.dedup_write_count += 1;
        
        // Step 4: Store pre-computed embedding (avoid double-embed)
        // Keep a reference for Step 6 (association discovery) before consuming
        let embedding_for_assoc: Option<Vec<f32>> = if self.config.association.enabled {
            pre_embedding.clone()
        } else {
            None
        };
        if let Some(embedding) = pre_embedding {
            self.storage.store_embedding(
                &id,
                &embedding,
                &self.config.embedding.model_id(),
                self.config.embedding.dimensions,
            )?;
        }
        
        // Step 5: Entity extraction
        if self.config.entity_config.enabled {
            let entities = self.entity_extractor.extract(content);
            let mut entity_ids = Vec::new();
            
            for entity in &entities {
                match self.storage.upsert_entity(
                    &entity.normalized,
                    entity.entity_type.as_str(),
                    ns,
                    None,
                ) {
                    Ok(eid) => {
                        if let Err(e) = self.storage.link_memory_entity(&id, &eid, "mention") {
                            log::warn!("Failed to link memory {} to entity {}: {}", id, eid, e);
                        }
                        entity_ids.push(eid);
                    }
                    Err(e) => {
                        log::warn!("Failed to upsert entity '{}': {}", entity.normalized, e);
                    }
                }
            }
            
            // Co-occurrence relations (capped at 10 to avoid O(n²))
            let cap = entity_ids.len().min(10);
            for i in 0..cap {
                for j in (i + 1)..cap {
                    if let Err(e) = self.storage.upsert_entity_relation(
                        &entity_ids[i],
                        &entity_ids[j],
                        "co_occurs",
                        ns,
                    ) {
                        log::warn!("Failed to upsert entity relation: {}", e);
                    }
                }
            }
        }

        // Step 6: Association discovery (multi-signal Hebbian)
        if self.config.association.enabled {
            let start = std::time::Instant::now();

            // Collect entity names for signal computation
            let entity_names: Vec<String> = if self.config.entity_config.enabled {
                self.entity_extractor.extract(content)
                    .into_iter()
                    .map(|e| e.normalized)
                    .collect()
            } else {
                Vec::new()
            };

            // created_at as f64 timestamp (same format as storage)
            let created_at_f64 = record.created_at.timestamp() as f64
                + record.created_at.timestamp_subsec_nanos() as f64 / 1_000_000_000.0;

            let selector = crate::association::CandidateSelector::new(&self.storage);
            match selector.select_candidates(
                &id,
                created_at_f64,
                &entity_names,
                embedding_for_assoc.as_deref(),
                &self.config.association,
            ) {
                Ok(candidates) if !candidates.is_empty() => {
                    let former = crate::association::LinkFormer::new(&self.storage);
                    match former.discover_associations(
                        &id,
                        candidates,
                        &entity_names,
                        embedding_for_assoc.as_deref(),
                        created_at_f64,
                        &self.config.association,
                        ns,
                    ) {
                        Ok(n) => {
                            if n > 0 {
                                log::debug!(
                                    "Association discovery: created {} links for memory {}",
                                    n, &id
                                );
                            }
                        }
                        Err(e) => {
                            log::warn!("Association discovery failed: {}", e);
                        }
                    }
                }
                Ok(_) => {} // No candidates found
                Err(e) => {
                    log::warn!("Association candidate selection failed: {}", e);
                }
            }

            let elapsed = start.elapsed();
            if elapsed > std::time::Duration::from_millis(100) {
                log::warn!(
                    "Association discovery took {:?} — consider tuning candidate_limit",
                    elapsed
                );
            }
        }
        
        Ok(id)
    }
    
    /// Store a new memory with emotional tracking.
    ///
    /// This method both stores the memory and records the empathy valence
    /// in the Empathy Bus for trend tracking. Requires an Empathy Bus
    /// to be attached.
    ///
    /// # Arguments
    ///
    /// * `content` - The memory content
    /// * `memory_type` - Memory type classification
    /// * `importance` - 0-1 importance score (None = auto)
    /// * `source` - Source identifier
    /// * `metadata` - Optional metadata
    /// * `namespace` - Namespace to store in
    /// * `emotion` - Emotional valence (-1.0 to 1.0)
    /// * `domain` - Domain for emotional tracking
    #[allow(clippy::too_many_arguments)]
    pub fn add_with_emotion(
        &mut self,
        content: &str,
        memory_type: MemoryType,
        importance: Option<f64>,
        source: Option<&str>,
        metadata: Option<serde_json::Value>,
        namespace: Option<&str>,
        emotion: f64,
        domain: &str,
    ) -> Result<String, Box<dyn std::error::Error>> {
        // Store the memory (with importance boost from alignment)
        let id = self.add_to_namespace(content, memory_type, importance, source, metadata, namespace)?;
        
        // Record emotion if bus is attached
        if let Some(ref bus) = self.empathy_bus {
            bus.process_interaction(self.storage.connection(), content, emotion, domain)?;
        }
        
        Ok(id)
    }

    /// Retrieve relevant memories using ACT-R activation-based retrieval.
    ///
    /// Unlike simple cosine similarity, this uses:
    /// - Base-level activation (frequency × recency, power law)
    /// - Spreading activation from context keywords
    /// - Importance modulation (emotional memories are more accessible)
    ///
    /// Results include a confidence score (metacognitive monitoring)
    /// that tells you how "trustworthy" each retrieval is.
    ///
    /// # Arguments
    ///
    /// * `query` - Natural language query
    /// * `limit` - Maximum number of results
    /// * `context` - Additional context keywords to boost relevant memories
    /// * `min_confidence` - Minimum confidence threshold (0-1)
    pub fn recall(
        &mut self,
        query: &str,
        limit: usize,
        context: Option<Vec<String>>,
        min_confidence: Option<f64>,
    ) -> Result<Vec<RecallResult>, Box<dyn std::error::Error>> {
        self.recall_from_namespace(query, limit, context, min_confidence, None)
    }
    
    /// Retrieve relevant memories from a specific namespace.
    ///
    /// Uses hybrid search: FTS + embedding + ACT-R activation.
    /// FTS catches exact term matches, embedding catches semantic similarity,
    /// ACT-R boosts frequently/recently accessed memories.
    ///
    /// When embedding is not available, uses FTS + ACT-R only.
    ///
    /// # Arguments
    ///
    /// * `query` - Natural language query
    /// * `limit` - Maximum number of results
    /// * `context` - Additional context keywords to boost relevant memories
    /// * `min_confidence` - Minimum confidence threshold (0-1)
    /// * `namespace` - Namespace to search (None = "default", Some("*") = all namespaces)
    pub fn recall_from_namespace(
        &mut self,
        query: &str,
        limit: usize,
        context: Option<Vec<String>>,
        min_confidence: Option<f64>,
        namespace: Option<&str>,
    ) -> Result<Vec<RecallResult>, Box<dyn std::error::Error>> {
        let now = Utc::now();
        let context = context.unwrap_or_default();
        let min_conf = min_confidence.unwrap_or(0.0);
        let ns = namespace.unwrap_or("default");
        
        // If embedding provider is available, use embedding-based recall
        if let Some(ref embedding_provider) = self.embedding {
            // Generate embedding for query
            let query_embedding = match embedding_provider.embed(query) {
                Ok(emb) => emb,
                Err(e) => {
                    log::warn!("Failed to generate query embedding, falling back to FTS: {}", e);
                    return self.recall_fts(query, limit, &context, min_conf, ns, now);
                }
            };
            
            // Get all embeddings for namespace and current model
            let model_id = self.config.embedding.model_id();
            let stored_embeddings = self.storage.get_embeddings_in_namespace(Some(ns), &model_id)?;
            
            // If no embedded memories, fall back to FTS
            if stored_embeddings.is_empty() {
                log::debug!("No embedded memories in namespace '{}', falling back to FTS", ns);
                return self.recall_fts(query, limit, &context, min_conf, ns, now);
            }
            
            // Build a map of memory_id -> embedding similarity
            let mut similarity_map: HashMap<String, f32> = HashMap::new();
            for (memory_id, stored_emb) in &stored_embeddings {
                let sim = EmbeddingProvider::cosine_similarity(&query_embedding, stored_emb);
                similarity_map.insert(memory_id.clone(), sim);
            }
            
            // Also get FTS results for exact term matching
            let fts_results = self.storage.search_fts_ns(query, limit * 3, Some(ns))
                .unwrap_or_default();
            let fts_count = fts_results.len();
            
            // Build FTS score map (rank-based normalization)
            let mut fts_score_map: HashMap<String, f64> = HashMap::new();
            for (rank, record) in fts_results.iter().enumerate() {
                let score = 1.0 - (rank as f64 / (fts_count.max(1)) as f64);
                fts_score_map.insert(record.id.clone(), score);
            }
            
            // Entity-based recall (4th channel)
            let (entity_scores, entity_w) = if self.config.entity_config.enabled {
                let es = self.entity_recall(query, Some(ns), limit * 3)?;
                (es, self.config.entity_weight)
            } else {
                (HashMap::new(), 0.0)
            };
            
            // Query-type adaptive weight adjustment (C7: Multi-Retrieval Fusion)
            let query_analysis = if self.config.adaptive_weights {
                crate::query_classifier::classify_query(query)
            } else {
                crate::query_classifier::QueryAnalysis::neutral()
            };
            
            // Merge candidate IDs from embedding, FTS, and entity recall
            let mut all_ids: std::collections::HashSet<String> = similarity_map.keys().cloned().collect();
            for record in &fts_results {
                all_ids.insert(record.id.clone());
            }
            for id in entity_scores.keys() {
                all_ids.insert(id.clone());
            }
            
            // Get candidate memories
            let mut candidates: Vec<MemoryRecord> = Vec::new();
            for id in &all_ids {
                if let Some(record) = self.storage.get(id)? {
                    candidates.push(record);
                }
            }
            
            // Defense-in-depth: filter out any superseded memories that slipped through SQL filter
            candidates.retain(|r| r.superseded_by.is_none());
            
            // Hebbian channel (6th channel): score candidates by Hebbian connectivity
            let candidate_ids: Vec<String> = candidates.iter().map(|r| r.id.clone()).collect();
            let hebbian_scores = if self.config.hebbian_enabled {
                Self::hebbian_channel_scores(&self.storage, &candidate_ids)?
            } else {
                HashMap::new()
            };
            let hebbian_w = if self.config.hebbian_enabled {
                self.config.hebbian_recall_weight
            } else {
                0.0
            };
            
            // Base weights (from config)
            let raw_fts_weight = self.config.fts_weight;
            let raw_emb_weight = self.config.embedding_weight;
            let raw_actr_weight = self.config.actr_weight;
            let raw_entity_weight = entity_w;
            let raw_temporal_weight = self.config.temporal_weight;
            let raw_hebbian_weight = hebbian_w;
            
            // Apply query-type modifiers (C7 adaptive weights)
            let adj_fts = raw_fts_weight * query_analysis.weight_modifiers.fts;
            let adj_emb = raw_emb_weight * query_analysis.weight_modifiers.embedding;
            let adj_actr = raw_actr_weight * query_analysis.weight_modifiers.actr;
            let adj_entity = raw_entity_weight * query_analysis.weight_modifiers.entity;
            let adj_temporal = raw_temporal_weight * query_analysis.weight_modifiers.temporal;
            let adj_hebbian = raw_hebbian_weight * query_analysis.weight_modifiers.hebbian;
            
            // Runtime normalization — always divide by sum
            let total_weight = adj_fts + adj_emb + adj_actr + adj_entity + adj_temporal + adj_hebbian;
            let (fts_weight, emb_weight, actr_weight, ent_weight, temp_weight, hebb_weight) = if total_weight > 0.0 {
                (
                    adj_fts / total_weight,
                    adj_emb / total_weight,
                    adj_actr / total_weight,
                    adj_entity / total_weight,
                    adj_temporal / total_weight,
                    adj_hebbian / total_weight,
                )
            } else {
                let n = 1.0 / 6.0;
                (n, n, n, n, n, n)
            };
            
            log::debug!(
                "C7 recall weights: fts={:.3} emb={:.3} actr={:.3} entity={:.3} temporal={:.3} hebbian={:.3} (query_type={:?})",
                fts_weight, emb_weight, actr_weight, ent_weight, temp_weight, hebb_weight,
                query_analysis.query_type,
            );
            
            let mut scored: Vec<_> = candidates
                .into_iter()
                .map(|record| {
                    // Get embedding similarity (already normalized to -1..1, convert to 0..1)
                    let embedding_sim = similarity_map
                        .get(&record.id)
                        .copied()
                        .unwrap_or(0.0);
                    let embedding_score = (embedding_sim + 1.0) / 2.0; // Normalize to 0..1
                    
                    // Get FTS score (0 if not in FTS results)
                    let fts_score = fts_score_map.get(&record.id).copied().unwrap_or(0.0);
                    
                    // Get entity score (0 if not in entity results)
                    let entity_score = entity_scores.get(&record.id).copied().unwrap_or(0.0);
                    
                    // Get ACT-R activation
                    let activation = retrieval_activation(
                        &record,
                        &context,
                        now,
                        self.config.actr_decay,
                        self.config.context_weight,
                        self.config.importance_weight,
                        self.config.contradiction_penalty,
                    );
                    
                    // Normalize activation to 0..1 range (sigmoid — much better discrimination than linear)
                    let activation_normalized = crate::models::actr::normalize_activation(
                        activation,
                        self.config.actr_sigmoid_center,
                        self.config.actr_sigmoid_scale,
                    );
                    
                    // Temporal channel (5th) — time-range proximity
                    let temporal_score = Self::temporal_score(&record, &query_analysis.time_range, now);
                    
                    // Hebbian channel (6th) — graph connectivity
                    let hebbian_score = hebbian_scores.get(&record.id).copied().unwrap_or(0.0);
                    
                    // Combined: 6-channel fusion
                    let combined_score = (fts_weight * fts_score)
                        + (emb_weight * embedding_score as f64)
                        + (actr_weight * activation_normalized)
                        + (ent_weight * entity_score)
                        + (temp_weight * temporal_score)
                        + (hebb_weight * hebbian_score);
                    
                    (record, combined_score, activation)
                })
                .collect();

            // Sort by combined score descending
            scored.sort_by(|a, b| b.1.partial_cmp(&a.1).unwrap());

            // Take expanded candidate pool for dedup backfilling
            let expanded_limit = if self.config.recall_dedup_enabled { limit * 3 } else { limit };
            let top_candidates: Vec<_> = scored.into_iter().take(expanded_limit).collect();

            // Build pairwise embedding lookup for dedup
            let embedding_lookup: HashMap<&str, &Vec<f32>> = stored_embeddings.iter()
                .map(|(id, emb)| (id.as_str(), emb))
                .collect();

            // Convert to RecallResults with confidence
            let mut all_results: Vec<RecallResult> = top_candidates.iter()
                .map(|(record, _combined_score, activation)| {
                    // Compute confidence from individual signals (not combined_score)
                    let age_hours = (now - record.created_at).num_seconds() as f64 / 3600.0;
                    let confidence = compute_query_confidence(
                        similarity_map.get(&record.id).copied(),
                        fts_score_map.contains_key(&record.id),
                        entity_scores.get(&record.id).copied().unwrap_or(0.0),
                        age_hours,
                    );
                    let confidence_label = confidence_label(confidence);

                    RecallResult {
                        record: record.clone(),
                        activation: *activation,
                        confidence,
                        confidence_label,
                    }
                })
                .filter(|r| r.confidence >= min_conf)
                .collect();

            // Dedup by embedding similarity
            if self.config.recall_dedup_enabled {
                all_results = Self::dedup_recall_results_by_embedding(
                    all_results,
                    &embedding_lookup,
                    self.config.recall_dedup_threshold,
                    limit,
                );
            } else {
                all_results.truncate(limit);
            }

            let results = all_results;

            // Record access for all retrieved memories (ACT-R learning)
            for result in &results {
                self.storage.record_access(&result.record.id)?;
            }

            // Hebbian learning: record co-activation (namespace-aware)
            if self.config.hebbian_enabled && results.len() >= 2 {
                let memory_ids: Vec<_> = results.iter().map(|r| r.record.id.clone()).collect();
                crate::models::record_coactivation_ns(
                    &mut self.storage,
                    &memory_ids,
                    self.config.hebbian_threshold,
                    ns,
                )?;
            }

            // Cross-recall co-occurrence detection (C8 / GOAL-17)
            // Track which memories are recalled across separate queries.
            // If two memories are recalled within 30 seconds (across different queries),
            // record their co-activation to strengthen Hebbian links.
            {
                let now_instant = std::time::Instant::now();
                for result in &results {
                    // Check against previously recalled memories within 30s window
                    for (prev_id, prev_time) in &self.recent_recalls {
                        if prev_id == &result.record.id { continue; }
                        if now_instant.duration_since(*prev_time) <= std::time::Duration::from_secs(30) {
                            // Within 30s window → record co-activation
                            let _ = self.storage.record_coactivation_ns(
                                prev_id,
                                &result.record.id,
                                self.config.hebbian_threshold,
                                ns,
                            );
                        }
                    }
                    // Add this result to the ring buffer
                    self.recent_recalls.push_back((result.record.id.clone(), now_instant));
                    if self.recent_recalls.len() > 50 {
                        self.recent_recalls.pop_front();
                    }
                }
            }

            Ok(results)
        } else {
            // No embedding provider, use FTS fallback
            self.recall_fts(query, limit, &context, min_conf, ns, now)
        }
    }

    /// Fetch the N most recently created memories, ordered newest-first.
    ///
    /// No query string needed — pure chronological retrieval.
    /// Designed for session bootstrap: after restart, inject recent context
    /// so the agent doesn't start from zero.
    ///
    /// # Arguments
    ///
    /// * `limit` - Maximum number of memories to return
    /// * `namespace` - Namespace filter (None = "default", Some("*") = all)
    pub fn recall_recent(
        &self,
        limit: usize,
        namespace: Option<&str>,
    ) -> Result<Vec<MemoryRecord>, Box<dyn std::error::Error>> {
        let mut records = self.storage.fetch_recent(limit, namespace)?;
        // Defense-in-depth: filter out any superseded memories that slipped through SQL filter
        records.retain(|r| r.superseded_by.is_none());
        Ok(records)
    }
    
    /// Entity-based recall: extract entities from query, look up matching entities,
    /// return memory→score mapping (0.0-1.0 normalized).
    ///
    /// Direct entity matches get full score, 1-hop related entities get half score.
    /// Scores are normalized to 0.0-1.0 by dividing by the maximum score.
    fn entity_recall(
        &self,
        query: &str,
        namespace: Option<&str>,
        limit: usize,
    ) -> Result<HashMap<String, f64>, Box<dyn std::error::Error>> {
        let _ = limit; // limit is implicit via the number of entity matches
        let query_entities = self.entity_extractor.extract(query);
        let mut memory_scores: HashMap<String, f64> = HashMap::new();
        
        for qe in &query_entities {
            // Direct entity match (exact name)
            let matches = self.storage.find_entities(&qe.normalized, namespace, 5)?;
            for entity in &matches {
                let memory_ids = self.storage.get_entity_memories(&entity.id)?;
                for mid in memory_ids {
                    *memory_scores.entry(mid).or_insert(0.0) += 1.0;
                }
                
                // 1-hop related entities (weaker signal)
                let related = self.storage.get_related_entities(&entity.id, 10)?;
                for (rel_id, _relation) in related {
                    let rel_memories = self.storage.get_entity_memories(&rel_id)?;
                    for mid in rel_memories {
                        *memory_scores.entry(mid).or_insert(0.0) += 0.5;
                    }
                }
            }
        }
        
        // Normalize scores to 0.0-1.0
        if let Some(&max_score) = memory_scores.values().max_by(|a, b| a.partial_cmp(b).unwrap()) {
            if max_score > 0.0 {
                for score in memory_scores.values_mut() {
                    *score /= max_score;
                }
            }
        }
        
        Ok(memory_scores)
    }
    
    /// Temporal channel scoring for C7 Multi-Retrieval Fusion.
    ///
    /// When a time range is detected in the query, memories within that range
    /// are scored by proximity to the range center (1.0 at center, 0.5 at edges).
    /// Memories outside the range get 0.0.
    ///
    /// When no time range is detected, returns a neutral 0.5 for all memories
    /// (so the temporal channel doesn't distort results when there's no temporal signal).
    fn temporal_score(
        record: &MemoryRecord,
        time_range: &Option<crate::query_classifier::TimeRange>,
        now: chrono::DateTime<chrono::Utc>,
    ) -> f64 {
        match time_range {
            Some(range) => {
                if record.created_at >= range.start && record.created_at <= range.end {
                    // Within range: score by proximity to center of range
                    let range_duration = (range.end - range.start).num_seconds() as f64;
                    let range_center = range.start + (range.end - range.start) / 2;
                    let distance = (record.created_at - range_center).num_seconds().abs() as f64;
                    let half_range = range_duration / 2.0;
                    if half_range > 0.0 {
                        // 1.0 at center, 0.5 at edges
                        1.0 - (distance / half_range) * 0.5
                    } else {
                        1.0
                    }
                } else {
                    0.0 // Outside range
                }
            }
            None => {
                // No temporal query: gentle recency signal (complement ACT-R)
                // Recent memories get slight boost, but not enough to dominate
                let age_hours = (now - record.created_at).num_seconds() as f64 / 3600.0;
                // Sigmoid centered at 72 hours (3 days), scale 48
                let recency = 1.0 / (1.0 + (age_hours - 72.0).exp() / 48.0_f64.exp());
                // Map to 0.3-0.7 range (narrow band so it's a weak signal)
                0.3 + recency * 0.4
            }
        }
    }
    
    /// Hebbian channel scoring for C7 Multi-Retrieval Fusion.
    ///
    /// For each candidate, checks how many other candidates it's Hebbian-linked to.
    /// Memories that are well-connected to other recall results get boosted —
    /// they form coherent clusters of associated knowledge.
    ///
    /// Scores are normalized to 0.0-1.0.
    fn hebbian_channel_scores(
        storage: &crate::storage::Storage,
        candidate_ids: &[String],
    ) -> Result<HashMap<String, f64>, Box<dyn std::error::Error>> {
        let mut scores: HashMap<String, f64> = HashMap::new();
        let candidate_set: std::collections::HashSet<&String> = candidate_ids.iter().collect();
        
        for id in candidate_ids {
            let links = storage.get_hebbian_links_weighted(id)?;
            let mut link_score = 0.0;
            for (linked_id, strength) in &links {
                if candidate_set.contains(linked_id) {
                    // This candidate is Hebbian-linked to another candidate
                    link_score += strength;
                }
            }
            if link_score > 0.0 {
                scores.insert(id.clone(), link_score);
            }
        }
        
        // Normalize to 0.0-1.0
        if let Some(&max) = scores.values().max_by(|a, b| a.partial_cmp(b).unwrap()) {
            if max > 0.0 {
                for v in scores.values_mut() {
                    *v /= max;
                }
            }
        }
        
        Ok(scores)
    }
    
    /// Remove near-duplicate recall results based on pairwise embedding similarity.
    /// Greedy: iterate in score order, skip any result too similar to an already-kept one.
    /// Backfills from the expanded candidate pool to maintain the requested limit.
    fn dedup_recall_results_by_embedding(
        candidates: Vec<RecallResult>,
        embeddings: &HashMap<&str, &Vec<f32>>,
        threshold: f64,
        limit: usize,
    ) -> Vec<RecallResult> {
        let mut kept: Vec<RecallResult> = Vec::with_capacity(limit);
        let mut kept_embeddings: Vec<&Vec<f32>> = Vec::with_capacity(limit);

        for candidate in candidates {
            if kept.len() >= limit {
                break;
            }

            let candidate_emb = match embeddings.get(candidate.record.id.as_str()) {
                Some(emb) => *emb,
                None => {
                    // No embedding available, keep by default
                    kept.push(candidate);
                    continue;
                }
            };

            // Check against all kept results
            let is_dup = kept_embeddings.iter().any(|kept_emb| {
                let sim = EmbeddingProvider::cosine_similarity(candidate_emb, kept_emb);
                sim as f64 > threshold
            });

            if !is_dup {
                kept_embeddings.push(candidate_emb);
                kept.push(candidate);
            }
        }

        kept
    }

    /// FTS-based recall fallback when embeddings are not available.
    fn recall_fts(
        &mut self,
        query: &str,
        limit: usize,
        context: &[String],
        min_conf: f64,
        ns: &str,
        now: chrono::DateTime<Utc>,
    ) -> Result<Vec<RecallResult>, Box<dyn std::error::Error>> {
        let fts_candidates = self.storage.search_fts_ns(query, limit * 3, Some(ns))?;
        
        // Defense-in-depth: filter out any superseded memories that slipped through SQL filter
        let fts_candidates: Vec<_> = fts_candidates.into_iter()
            .filter(|r| r.superseded_by.is_none())
            .collect();
        
        let mut scored: Vec<_> = fts_candidates
            .into_iter()
            .map(|record| {
                let activation = retrieval_activation(
                    &record,
                    context,
                    now,
                    self.config.actr_decay,
                    self.config.context_weight,
                    self.config.importance_weight,
                    self.config.contradiction_penalty,
                );
                (record, activation)
            })
            .filter(|(_, act)| *act > f64::NEG_INFINITY)
            .collect();

        scored.sort_by(|a, b| b.1.partial_cmp(&a.1).unwrap());

        let results: Vec<_> = scored
            .into_iter()
            .take(limit)
            .map(|(record, activation)| {
                let age_hours = (now - record.created_at).num_seconds() as f64 / 3600.0;
                let confidence = compute_query_confidence(
                    None,       // no embedding available in FTS path
                    true,       // it's an FTS result by definition
                    0.0,        // no entity score in FTS path
                    age_hours,
                );
                let confidence_label = confidence_label(confidence);

                RecallResult {
                    record,
                    activation,
                    confidence,
                    confidence_label,
                }
            })
            .filter(|r| r.confidence >= min_conf)
            .collect();

        for result in &results {
            self.storage.record_access(&result.record.id)?;
        }

        // Hebbian learning: record co-activation (namespace-aware)
        if self.config.hebbian_enabled && results.len() >= 2 {
            let memory_ids: Vec<_> = results.iter().map(|r| r.record.id.clone()).collect();
            crate::models::record_coactivation_ns(
                &mut self.storage,
                &memory_ids,
                self.config.hebbian_threshold,
                ns,
            )?;
        }

        // Cross-recall co-occurrence detection (C8 / GOAL-17)
        // Track which memories are recalled across separate queries.
        // If two memories are recalled within 30 seconds (across different queries),
        // record their co-activation to strengthen Hebbian links.
        {
            let now_instant = std::time::Instant::now();
            for result in &results {
                // Check against previously recalled memories within 30s window
                for (prev_id, prev_time) in &self.recent_recalls {
                    if prev_id == &result.record.id { continue; }
                    if now_instant.duration_since(*prev_time) <= std::time::Duration::from_secs(30) {
                        // Within 30s window → record co-activation
                        let _ = self.storage.record_coactivation_ns(
                            prev_id,
                            &result.record.id,
                            self.config.hebbian_threshold,
                            ns,
                        );
                    }
                }
                // Add this result to the ring buffer
                self.recent_recalls.push_back((result.record.id.clone(), now_instant));
                if self.recent_recalls.len() > 50 {
                    self.recent_recalls.pop_front();
                }
            }
        }

        Ok(results)
    }

    /// Run a consolidation cycle ("sleep replay").
    ///
    /// This is the core of memory maintenance. Based on Murre & Chessa's
    /// Memory Chain Model, it:
    ///
    /// 1. Decays working_strength (hippocampal traces fade)
    /// 2. Transfers knowledge to core_strength (neocortical consolidation)
    /// 3. Replays archived memories (prevents catastrophic forgetting)
    /// 4. Rebalances layers (promote strong → core, demote weak → archive)
    ///
    /// Call this periodically — once per "day" of agent operation,
    /// or after significant learning sessions.
    ///
    /// # Arguments
    ///
    /// * `days` - Simulated time step in days (1.0 = one day of consolidation)
    pub fn consolidate(&mut self, days: f64) -> Result<(), Box<dyn std::error::Error>> {
        self.consolidate_namespace(days, None)
    }
    
    /// Run a consolidation cycle for a specific namespace.
    ///
    /// # Arguments
    ///
    /// * `days` - Simulated time step in days (1.0 = one day of consolidation)
    /// * `namespace` - Namespace to consolidate (None = all namespaces)
    pub fn consolidate_namespace(
        &mut self,
        days: f64,
        namespace: Option<&str>,
    ) -> Result<(), Box<dyn std::error::Error>> {
        run_consolidation_cycle(&mut self.storage, days, &self.config, namespace)?;

        // Decay Hebbian links
        if self.config.hebbian_enabled {
            if self.config.association.enabled {
                // Differential decay: co-recall links decay slowest, multi medium, single fastest
                self.storage.decay_hebbian_links_differential(
                    self.config.association.decay_corecall,
                    self.config.association.decay_multi,
                    self.config.association.decay_single,
                )?;
            } else {
                self.storage.decay_hebbian_links(self.config.hebbian_decay)?;
            }
        }

        // Run synthesis if enabled (GUARD-3: opt-in, backward compatible)
        let synth_settings = self.synthesis_settings.clone();
        if let Some(ref settings) = synth_settings {
            if settings.enabled {
                let embedding_model = self.embedding.as_ref().map(|e| e.config().model_id());
                let engine = self.build_synthesis_engine(embedding_model);
                match engine.synthesize(&mut self.storage, settings) {
                    Ok(report) => {
                        if report.clusters_found > 0 {
                            log::info!(
                                "Synthesis: {} clusters found, {} synthesized, {} skipped, {} deferred",
                                report.clusters_found,
                                report.clusters_synthesized,
                                report.clusters_skipped,
                                report.clusters_deferred,
                            );
                        }
                    }
                    Err(e) => {
                        log::warn!("Synthesis failed (non-fatal): {e}");
                    }
                }
                self.restore_llm_provider(engine.into_provider());
            }
        }

        // [ISS-016] Triple extraction phase (cold path, no DB lock during LLM calls)
        if self.config.triple.enabled
            && self.triple_extractor.is_some() {
                if let Err(e) = self.run_triple_extraction() {
                    log::warn!("Triple extraction failed (non-fatal): {e}");
                }
            }

        // [ISS-008] Promotion detection phase
        if self.config.promotion.enabled {
            match self.detect_promotion_candidates() {
                Ok(candidates) if !candidates.is_empty() => {
                    log::info!("Promotion: {} candidates found", candidates.len());
                    for c in &candidates {
                        if let Err(e) = self.storage.store_promotion_candidate(c) {
                            log::warn!("Failed to store promotion candidate: {}", e);
                        }
                    }
                }
                Ok(_) => {}
                Err(e) => log::warn!("Promotion detection failed (non-fatal): {e}"),
            }
        }

        Ok(())
    }

    /// Run triple extraction on un-enriched memories.
    /// Called during consolidation when triple extraction is enabled.
    /// Uses lock-release-lock pattern to avoid holding DB lock during LLM calls.
    fn run_triple_extraction(&mut self) -> Result<(), Box<dyn std::error::Error>> {
        let batch_size = self.config.triple.batch_size;
        let max_retries = self.config.triple.max_retries;

        // Step 1: Query un-enriched memories
        let memory_ids = self.storage.get_unenriched_memory_ids(batch_size, max_retries)?;
        if memory_ids.is_empty() {
            return Ok(());
        }

        // Step 2: Read memory content (batch read)
        let mut memory_texts: Vec<(String, String)> = Vec::new();
        for id in &memory_ids {
            if let Ok(Some(record)) = self.storage.get(id) {
                memory_texts.push((id.clone(), record.content.clone()));
            }
        }

        // Step 3: LLM extraction — NO DB lock held
        let extractor = self.triple_extractor.as_ref().unwrap(); // caller checks this
        type TripleResult = Vec<(String, Result<Vec<crate::triple::Triple>, Box<dyn std::error::Error + Send + Sync>>)>;
        let mut results: TripleResult = Vec::new();
        for (id, content) in &memory_texts {
            let result = extractor.extract_triples(content);
            results.push((id.clone(), result));
        }

        // Step 4: Store results in a transaction
        self.storage.begin_transaction()?;
        let write_result = (|| -> Result<(), Box<dyn std::error::Error>> {
            for (id, result) in &results {
                match result {
                    Ok(triples) if !triples.is_empty() => {
                        self.storage.store_triples(id, triples)?;
                        log::debug!("Extracted {} triples for memory {}", triples.len(), id);
                    }
                    Ok(_) => {
                        // Empty triples — mark as attempted
                        self.storage.increment_extraction_attempts(id)?;
                    }
                    Err(e) => {
                        log::warn!("Triple extraction failed for {}: {}", id, e);
                        self.storage.increment_extraction_attempts(id)?;
                    }
                }
            }
            Ok(())
        })();

        match write_result {
            Ok(()) => {
                self.storage.commit_transaction()?;
            }
            Err(e) => {
                let _ = self.storage.rollback_transaction();
                log::warn!("Triple storage failed (non-fatal): {}", e);
            }
        }

        Ok(())
    }

    // === [ISS-008] Knowledge Promotion API ===

    /// Detect knowledge clusters ready for promotion to persistent documents.
    pub fn detect_promotion_candidates(&self) -> Result<Vec<crate::promotion::PromotionCandidate>, Box<dyn std::error::Error>> {
        crate::promotion::detect_promotable_clusters(&self.storage, &self.config.promotion)
    }

    /// Get pending promotion suggestions.
    pub fn pending_promotions(&self) -> Result<Vec<crate::promotion::PromotionCandidate>, Box<dyn std::error::Error>> {
        Ok(self.storage.get_pending_promotions()?)
    }

    /// Approve or dismiss a promotion candidate.
    pub fn resolve_promotion(&self, id: &str, status: &str) -> Result<(), Box<dyn std::error::Error>> {
        Ok(self.storage.resolve_promotion(id, status)?)
    }

    /// Forget a specific memory or prune all below threshold.
    ///
    /// If memory_id is given, removes that specific memory.
    /// Otherwise, prunes all memories whose effective_strength
    /// is below threshold (moves them to archive).
    pub fn forget(
        &mut self,
        memory_id: Option<&str>,
        threshold: Option<f64>,
    ) -> Result<(), Box<dyn std::error::Error>> {
        let threshold = threshold.unwrap_or(self.config.forget_threshold);

        if let Some(id) = memory_id {
            self.storage.delete(id)?;
        } else {
            // Prune all weak memories
            let now = Utc::now();
            let all = self.storage.all()?;
            for record in all {
                if !record.pinned && effective_strength(&record, now) < threshold
                    && record.layer != MemoryLayer::Archive {
                        let mut updated = record;
                        updated.layer = MemoryLayer::Archive;
                        self.storage.update(&updated)?;
                    }
            }
        }

        Ok(())
    }

    /// Process user feedback as a dopaminergic reward signal.
    ///
    /// Detects positive/negative sentiment and applies reward modulation
    /// to recently accessed memories.
    pub fn reward(&mut self, feedback: &str, recent_n: usize) -> Result<(), Box<dyn std::error::Error>> {
        let polarity = detect_feedback_polarity(feedback);

        if polarity == 0.0 {
            return Ok(()); // Neutral feedback
        }

        // Get recently accessed memories
        let all = self.storage.all()?;
        let _now = Utc::now();
        let mut recent: Vec<_> = all
            .into_iter()
            .filter(|r| !r.access_times.is_empty())
            .collect();
        recent.sort_by_key(|r| std::cmp::Reverse(r.access_times.last().cloned()));

        // Apply reward to top-N recent
        for mut record in recent.into_iter().take(recent_n) {
            if polarity > 0.0 {
                // Positive feedback: boost working strength
                record.working_strength += self.config.reward_magnitude * polarity;
                record.working_strength = record.working_strength.min(2.0);
            } else {
                // Negative feedback: suppress working strength
                record.working_strength *= 1.0 + polarity * 0.1; // polarity is negative
                record.working_strength = record.working_strength.max(0.0);
            }
            self.storage.update(&record)?;
        }

        Ok(())
    }

    /// Global synaptic downscaling — normalize all memory weights.
    ///
    /// Based on Tononi & Cirelli's Synaptic Homeostasis Hypothesis.
    pub fn downscale(&mut self, factor: Option<f64>) -> Result<usize, Box<dyn std::error::Error>> {
        let factor = factor.unwrap_or(self.config.downscale_factor);
        let all = self.storage.all()?;
        let mut count = 0;

        for mut record in all {
            if !record.pinned {
                record.working_strength *= factor;
                record.core_strength *= factor;
                self.storage.update(&record)?;
                count += 1;
            }
        }

        Ok(count)
    }

    /// Memory system statistics.
    pub fn stats(&self) -> Result<MemoryStats, Box<dyn std::error::Error>> {
        let all = self.storage.all()?;
        let now = Utc::now();

        let mut by_type: HashMap<String, Vec<&MemoryRecord>> = HashMap::new();
        let mut by_layer: HashMap<String, Vec<&MemoryRecord>> = HashMap::new();
        let mut pinned = 0;

        for record in &all {
            by_type
                .entry(record.memory_type.to_string())
                .or_default()
                .push(record);
            by_layer
                .entry(record.layer.to_string())
                .or_default()
                .push(record);
            if record.pinned {
                pinned += 1;
            }
        }

        let type_stats: HashMap<String, TypeStats> = by_type
            .into_iter()
            .map(|(type_name, records)| {
                let count = records.len();
                let avg_strength = records
                    .iter()
                    .map(|r| effective_strength(r, now))
                    .sum::<f64>()
                    / count as f64;
                let avg_importance = records.iter().map(|r| r.importance).sum::<f64>() / count as f64;

                (
                    type_name,
                    TypeStats {
                        count,
                        avg_strength,
                        avg_importance,
                    },
                )
            })
            .collect();

        let layer_stats: HashMap<String, LayerStats> = by_layer
            .into_iter()
            .map(|(layer_name, records)| {
                let count = records.len();
                let avg_working = records.iter().map(|r| r.working_strength).sum::<f64>() / count as f64;
                let avg_core = records.iter().map(|r| r.core_strength).sum::<f64>() / count as f64;

                (
                    layer_name,
                    LayerStats {
                        count,
                        avg_working,
                        avg_core,
                    },
                )
            })
            .collect();

        let uptime_hours = (now - self.created_at).num_seconds() as f64 / 3600.0;

        Ok(MemoryStats {
            total_memories: all.len(),
            by_type: type_stats,
            by_layer: layer_stats,
            pinned,
            uptime_hours,
        })
    }

    /// Pin a memory — it won't decay or be pruned.
    pub fn pin(&mut self, memory_id: &str) -> Result<(), Box<dyn std::error::Error>> {
        if let Some(mut record) = self.storage.get(memory_id)? {
            record.pinned = true;
            self.storage.update(&record)?;
        }
        Ok(())
    }

    /// Unpin a memory — it will resume normal decay.
    pub fn unpin(&mut self, memory_id: &str) -> Result<(), Box<dyn std::error::Error>> {
        if let Some(mut record) = self.storage.get(memory_id)? {
            record.pinned = false;
            self.storage.update(&record)?;
        }
        Ok(())
    }
    
    // === Update Memory ===
    
    /// Update an existing memory's content.
    ///
    /// Stores the old content in metadata for audit trail and regenerates
    /// the embedding if embedding support is enabled.
    ///
    /// # Arguments
    ///
    /// * `memory_id` - ID of the memory to update
    /// * `new_content` - New content to replace the existing content
    /// * `reason` - Reason for the update (stored in metadata)
    ///
    /// # Returns
    ///
    /// The memory ID on success, or an error if the memory doesn't exist.
    pub fn update_memory(
        &mut self,
        memory_id: &str,
        new_content: &str,
        reason: &str,
    ) -> Result<String, Box<dyn std::error::Error>> {
        // Get existing memory
        let record = self.storage.get(memory_id)?
            .ok_or_else(|| format!("Memory {} not found", memory_id))?;
        
        // Build updated metadata with audit trail
        let mut metadata = record.metadata.clone().unwrap_or_else(|| serde_json::json!({}));
        if let Some(obj) = metadata.as_object_mut() {
            obj.insert("previous_content".to_string(), serde_json::json!(record.content));
            obj.insert("update_reason".to_string(), serde_json::json!(reason));
            obj.insert("updated_at".to_string(), serde_json::json!(Utc::now().to_rfc3339()));
        }
        
        // Update content in storage
        self.storage.update_content(memory_id, new_content, Some(metadata))?;
        
        // Regenerate embedding if provider is available
        if let Some(ref embedding_provider) = self.embedding {
            match embedding_provider.embed(new_content) {
                Ok(embedding) => {
                    // Delete old embedding for this model and store new one
                    self.storage.delete_embedding(memory_id, &self.config.embedding.model_id())?;
                    self.storage.store_embedding(
                        memory_id,
                        &embedding,
                        &self.config.embedding.model_id(),
                        self.config.embedding.dimensions,
                    )?;
                }
                Err(e) => {
                    log::warn!("Failed to regenerate embedding for {}: {}", memory_id, e);
                }
            }
        }
        
        Ok(memory_id.to_string())
    }
    
    // === Export ===
    
    /// Export all memories to a JSON file.
    ///
    /// # Arguments
    ///
    /// * `path` - Path to the output JSON file
    ///
    /// # Returns
    ///
    /// Number of memories exported.
    pub fn export(&self, path: &str) -> Result<usize, Box<dyn std::error::Error>> {
        self.export_namespace(path, None)
    }
    
    /// Export memories from a specific namespace to a JSON file.
    ///
    /// # Arguments
    ///
    /// * `path` - Path to the output JSON file
    /// * `namespace` - Namespace to export (None = all)
    ///
    /// # Returns
    ///
    /// Number of memories exported.
    pub fn export_namespace(
        &self,
        path: &str,
        namespace: Option<&str>,
    ) -> Result<usize, Box<dyn std::error::Error>> {
        let memories = self.storage.all_in_namespace(namespace)?;
        let count = memories.len();
        
        // Serialize to JSON
        let json = serde_json::to_string_pretty(&memories)?;
        
        // Write to file
        let mut file = File::create(path)?;
        file.write_all(json.as_bytes())?;
        
        log::info!("Exported {} memories to {}", count, path);
        
        Ok(count)
    }
    
    // === Recall Causal ===
    
    /// Recall associated memories (type=causal, created by STDP during consolidation).
    ///
    /// # Arguments
    ///
    /// * `cause_query` - Optional query to filter causal memories
    /// * `limit` - Maximum number of results
    /// * `min_confidence` - Minimum confidence threshold
    ///
    /// # Returns
    ///
    /// Matching associated memories sorted by importance.
    /// Hybrid recall combining FTS + embedding + ACT-R activation.
    /// 
    /// Unlike `recall()` which uses embedding+ACT-R only, this also includes
    /// FTS exact matching. Better for queries with specific names/terms.
    pub fn hybrid_recall(
        &mut self,
        query: &str,
        limit: usize,
        namespace: Option<&str>,
    ) -> Result<Vec<RecallResult>, Box<dyn std::error::Error>> {
        use crate::hybrid_search::{hybrid_search, HybridSearchOpts};
        
        // Generate query embedding if available
        let query_vector = if let Some(ref embedding) = self.embedding {
            embedding.embed(query).ok()
        } else {
            None
        };
        
        let opts = HybridSearchOpts {
            limit,
            namespace: namespace.map(String::from),
            ..Default::default()
        };
        
        let results = hybrid_search(
            &self.storage,
            query_vector.as_deref(),
            query,
            opts,
            &self.config.embedding.model_id(),
        )?;
        
        // Convert HybridSearchResult to RecallResult
        let recall_results: Vec<RecallResult> = results.into_iter()
            .filter_map(|hr| {
                let record = hr.record?; // Skip if no record
                let score = hr.score;
                let label = if score > 0.7 {
                    "confident".to_string()
                } else if score > 0.4 {
                    "likely".to_string()
                } else {
                    "uncertain".to_string()
                };
                Some(RecallResult {
                    record,
                    activation: score,
                    confidence: score,
                    confidence_label: label,
                })
            })
            .collect();
        
        // Defense-in-depth: filter out any superseded memories that slipped through
        let recall_results: Vec<_> = recall_results.into_iter()
            .filter(|r| r.record.superseded_by.is_none())
            .collect();
        
        Ok(recall_results)
    }    
    /// Uses Hebbian links to find memories that frequently co-occur.
    /// Note: this finds *associations*, not true causal relationships.
    /// LLMs can infer causality from the associated context.
    pub fn recall_associated(
        &mut self,
        cause_query: Option<&str>,
        limit: usize,
        min_confidence: f64,
    ) -> Result<Vec<RecallResult>, Box<dyn std::error::Error>> {
        self.recall_associated_ns(cause_query, limit, min_confidence, None)
    }
    
    /// Recall associated memories from a specific namespace.
    pub fn recall_associated_ns(
        &mut self,
        cause_query: Option<&str>,
        limit: usize,
        min_confidence: f64,
        namespace: Option<&str>,
    ) -> Result<Vec<RecallResult>, Box<dyn std::error::Error>> {
        let now = Utc::now();
        
        if let Some(query) = cause_query {
            // Do normal recall but filter to causal type
            let results = self.recall_from_namespace(
                query,
                limit * 2, // Fetch more to filter
                None,
                Some(min_confidence),
                namespace,
            )?;
            
            // Filter to causal type
            let filtered: Vec<_> = results
                .into_iter()
                .filter(|r| r.record.memory_type == MemoryType::Causal)
                .take(limit)
                .collect();
            
            Ok(filtered)
        } else {
            // Get all causal memories sorted by importance
            let causal_memories = self.storage.search_by_type_ns(
                MemoryType::Causal,
                namespace,
                limit * 2,
            )?;
            
            // Score and filter
            let mut scored: Vec<_> = causal_memories
                .into_iter()
                .filter(|r| r.superseded_by.is_none()) // Defense-in-depth
                .map(|record| {
                    let activation = retrieval_activation(
                        &record,
                        &[],
                        now,
                        self.config.actr_decay,
                        self.config.context_weight,
                        self.config.importance_weight,
                        self.config.contradiction_penalty,
                    );
                    let age_hours = (now - record.created_at).num_seconds() as f64 / 3600.0;
                    let confidence = compute_query_confidence(
                        None,   // no embedding in causal recall path
                        false,  // not an FTS query match
                        0.0,    // no entity score
                        age_hours,
                    );
                    (record, activation, confidence)
                })
                .filter(|(_, _, conf)| *conf >= min_confidence)
                .collect();
            
            // Sort by importance then activation
            scored.sort_by(|a, b| {
                b.0.importance.partial_cmp(&a.0.importance)
                    .unwrap_or(std::cmp::Ordering::Equal)
            });
            
            // Take top-k
            let results: Vec<_> = scored
                .into_iter()
                .take(limit)
                .map(|(record, activation, confidence)| {
                    RecallResult {
                        record,
                        activation,
                        confidence,
                        confidence_label: confidence_label(confidence),
                    }
                })
                .collect();
            
            Ok(results)
        }
    }
    
    // === Session Recall ===
    
    /// Session-aware recall using working memory to avoid redundant searches.
    ///
    /// If the topic is continuous (high overlap with previous recall), returns
    /// cached working memory items. If topic changed or WM is empty, does full recall.
    ///
    /// # Arguments
    ///
    /// * `query` - Search query
    /// * `session_wm` - Mutable reference to session's working memory
    /// * `limit` - Maximum number of results
    /// * `context` - Optional context keywords
    /// * `min_confidence` - Minimum confidence threshold
    ///
    /// # Returns
    ///
    /// SessionRecallResult with memories and metadata about the recall.
    pub fn session_recall(
        &mut self,
        query: &str,
        session_wm: &mut SessionWorkingMemory,
        limit: usize,
        context: Option<Vec<String>>,
        min_confidence: Option<f64>,
    ) -> Result<SessionRecallResult, Box<dyn std::error::Error>> {
        self.session_recall_ns(query, session_wm, limit, context, min_confidence, None)
    }
    
    /// Session-aware recall from a specific namespace.
    pub fn session_recall_ns(
        &mut self,
        query: &str,
        session_wm: &mut SessionWorkingMemory,
        limit: usize,
        context: Option<Vec<String>>,
        min_confidence: Option<f64>,
        namespace: Option<&str>,
    ) -> Result<SessionRecallResult, Box<dyn std::error::Error>> {
        const CONTINUITY_THRESHOLD: f64 = 0.6;
        
        // Get active IDs from working memory
        let active_ids = session_wm.get_active_ids();
        
        // Check if we need full recall, capturing the initial probe ratio
        let (need_full_recall, initial_ratio) = if active_ids.is_empty() {
            (true, 0.0)
        } else {
            // Do lightweight probe (3 results) to check topic continuity
            let probe = self.recall_from_namespace(
                query,
                3,
                context.clone(),
                min_confidence,
                namespace,
            )?;
            
            let probe_ids: Vec<String> = probe.iter().map(|r| r.record.id.clone()).collect();
            let (_, ratio) = session_wm.overlap(&probe_ids);
            if ratio >= CONTINUITY_THRESHOLD {
                (false, ratio)  // topic continuous
            } else {
                (true, ratio)   // topic changed
            }
        };
        
        if need_full_recall {
            // Topic changed or WM empty → full recall
            let results = self.recall_from_namespace(
                query,
                limit,
                context,
                min_confidence,
                namespace,
            )?;
            
            // Update working memory with scores for future cached path
            let entries: Vec<(String, f64, f64)> = results.iter()
                .map(|r| (r.record.id.clone(), r.confidence, r.activation))
                .collect();
            session_wm.activate_with_scores(&entries);
            session_wm.set_query(query);

            // GWT broadcast: admitted memories → interoceptive hub + Hebbian spreading.
            let admitted_ids: Vec<String> = results.iter().map(|r| r.record.id.clone()).collect();
            self.broadcast_admission(&admitted_ids, session_wm);
            
            Ok(SessionRecallResult {
                results,
                full_recall: true,
                wm_size: session_wm.len(),
                continuity_ratio: initial_ratio,
            })
        } else {
            // Topic continuous → return cached WM items with preserved scores
            let mut cached_results = Vec::new();
            let now = Utc::now();
            
            for id in &active_ids {
                if let Some(record) = self.storage.get(id)? {
                    // Reuse cached scores from the original full recall
                    let (activation, confidence) = if let Some(cached) = session_wm.get_score(id) {
                        (cached.activation, cached.confidence)
                    } else {
                        // Fallback: memory activated by ID only (legacy/no cached scores)
                        let activation = retrieval_activation(
                            &record,
                            &context.clone().unwrap_or_default(),
                            now,
                            self.config.actr_decay,
                            self.config.context_weight,
                            self.config.importance_weight,
                            self.config.contradiction_penalty,
                        );
                        let age_hours = (now - record.created_at).num_seconds() as f64 / 3600.0;
                        let confidence = compute_query_confidence(
                            None,
                            false,
                            0.0,
                            age_hours,
                        );
                        (activation, confidence)
                    };
                    
                    if min_confidence.map(|mc| confidence >= mc).unwrap_or(true) {
                        cached_results.push(RecallResult {
                            record,
                            activation,
                            confidence,
                            confidence_label: confidence_label(confidence),
                        });
                    }
                }
            }
            
            // Sort by activation
            cached_results.sort_by(|a, b| {
                b.activation.partial_cmp(&a.activation).unwrap_or(std::cmp::Ordering::Equal)
            });
            cached_results.truncate(limit);
            
            // Refresh activation timestamps (reuse existing scores)
            let result_ids: Vec<String> = cached_results.iter().map(|r| r.record.id.clone()).collect();
            session_wm.activate(&result_ids);
            session_wm.set_query(query);

            // GWT broadcast on cached path too — re-activation reinforces the hub state.
            // (Lighter than full-recall broadcast: same memories, but keeps hub current.)
            self.broadcast_admission(&result_ids, session_wm);
            
            Ok(SessionRecallResult {
                results: cached_results,
                full_recall: false,
                wm_size: session_wm.len(),
                continuity_ratio: initial_ratio,  // reuse from initial probe
            })
        }
    }
    
    /// Get a memory by ID.
    pub fn get(&self, memory_id: &str) -> Result<Option<MemoryRecord>, Box<dyn std::error::Error>> {
        Ok(self.storage.get(memory_id)?)
    }
    
    /// List all memories (with optional limit).
    pub fn list(&self, limit: Option<usize>) -> Result<Vec<MemoryRecord>, Box<dyn std::error::Error>> {
        let all = self.storage.all()?;
        match limit {
            Some(l) => Ok(all.into_iter().take(l).collect()),
            None => Ok(all),
        }
    }
    
    /// List all memories in a namespace.
    pub fn list_ns(
        &self,
        namespace: Option<&str>,
        limit: Option<usize>,
    ) -> Result<Vec<MemoryRecord>, Box<dyn std::error::Error>> {
        let all = self.storage.all_in_namespace(namespace)?;
        match limit {
            Some(l) => Ok(all.into_iter().take(l).collect()),
            None => Ok(all),
        }
    }

    /// Get Hebbian links for a specific memory.
    pub fn hebbian_links(&self, memory_id: &str) -> Result<Vec<String>, Box<dyn std::error::Error>> {
        Ok(self.storage.get_hebbian_neighbors(memory_id)?)
    }
    
    /// Get Hebbian links for a specific memory, filtered by namespace.
    pub fn hebbian_links_ns(
        &self,
        memory_id: &str,
        namespace: Option<&str>,
    ) -> Result<Vec<String>, Box<dyn std::error::Error>> {
        Ok(self.storage.get_hebbian_neighbors_ns(memory_id, namespace)?)
    }
    
    // === Embedding Methods ===
    
    /// Get embedding statistics.
    pub fn embedding_stats(&self) -> Result<EmbeddingStats, Box<dyn std::error::Error>> {
        Ok(self.storage.embedding_stats()?)
    }
    
    /// Get the embedding configuration.
    pub fn embedding_config(&self) -> &EmbeddingConfig {
        &self.config.embedding
    }
    
    /// Check if the embedding provider is available.
    pub fn is_embedding_available(&self) -> bool {
        self.embedding.as_ref().map(|e| e.is_available()).unwrap_or(false)
    }

    /// Get a reference to the embedding provider (if available).
    pub fn embedding_provider(&self) -> Option<&EmbeddingProvider> {
        self.embedding.as_ref()
    }
    
    /// Check if embedding support is enabled (provider was created).
    pub fn has_embedding_support(&self) -> bool {
        self.embedding.is_some()
    }
    
    /// Reindex embeddings for all memories without embeddings.
    ///
    /// Useful after migration or model change. Iterates all memories
    /// that don't have embeddings and generates them.
    ///
    /// Returns the number of memories reindexed.
    /// Returns an error if embedding provider is not available.
    pub fn reindex_embeddings(&mut self) -> Result<usize, Box<dyn std::error::Error>> {
        let embedding_provider = self.embedding.as_ref().ok_or_else(|| {
            Box::new(EmbeddingError::OllamaNotAvailable(self.config.embedding.host.clone()))
                as Box<dyn std::error::Error>
        })?;
        
        let model_id = self.config.embedding.model_id();
        let missing_ids = self.storage.get_memories_without_embeddings(&model_id)?;
        let total = missing_ids.len();
        
        if total == 0 {
            return Ok(0);
        }
        
        log::info!("Reindexing {} memories without embeddings for model {}", total, model_id);
        
        let mut reindexed = 0;
        for id in missing_ids {
            if let Some(record) = self.storage.get(&id)? {
                match embedding_provider.embed(&record.content) {
                    Ok(embedding) => {
                        self.storage.store_embedding(
                            &id,
                            &embedding,
                            &model_id,
                            self.config.embedding.dimensions,
                        )?;
                        reindexed += 1;
                    }
                    Err(e) => {
                        log::warn!("Failed to generate embedding for {}: {}", id, e);
                    }
                }
            }
        }
        
        log::info!("Reindexed {}/{} memories", reindexed, total);
        Ok(reindexed)
    }
    
    /// Reindex embeddings with progress callback.
    ///
    /// The callback receives (current, total) progress updates.
    /// Returns an error if embedding provider is not available.
    pub fn reindex_embeddings_with_progress<F>(
        &mut self,
        mut progress: F,
    ) -> Result<usize, Box<dyn std::error::Error>>
    where
        F: FnMut(usize, usize),
    {
        let embedding_provider = self.embedding.as_ref().ok_or_else(|| {
            Box::new(EmbeddingError::OllamaNotAvailable(self.config.embedding.host.clone()))
                as Box<dyn std::error::Error>
        })?;
        
        let model_id = self.config.embedding.model_id();
        let missing_ids = self.storage.get_memories_without_embeddings(&model_id)?;
        let total = missing_ids.len();
        
        if total == 0 {
            return Ok(0);
        }
        
        let mut reindexed = 0;
        for (i, id) in missing_ids.into_iter().enumerate() {
            progress(i + 1, total);
            
            if let Some(record) = self.storage.get(&id)? {
                match embedding_provider.embed(&record.content) {
                    Ok(embedding) => {
                        self.storage.store_embedding(
                            &id,
                            &embedding,
                            &model_id,
                            self.config.embedding.dimensions,
                        )?;
                        reindexed += 1;
                    }
                    Err(e) => {
                        log::warn!("Failed to generate embedding for {}: {}", id, e);
                    }
                }
            }
        }
        
        Ok(reindexed)
    }
    
    // === ACL Methods ===
    
    /// Grant a permission to an agent for a namespace.
    /// 
    /// Only agents with admin permission on the namespace (or wildcard admin)
    /// can grant permissions. If no agent_id is set, uses "system" as grantor.
    pub fn grant(
        &mut self,
        agent_id: &str,
        namespace: &str,
        permission: Permission,
    ) -> Result<(), Box<dyn std::error::Error>> {
        let grantor = self.agent_id.clone().unwrap_or_else(|| "system".to_string());
        self.storage.grant_permission(agent_id, namespace, permission, &grantor)?;
        Ok(())
    }
    
    /// Revoke a permission from an agent for a namespace.
    pub fn revoke(&mut self, agent_id: &str, namespace: &str) -> Result<(), Box<dyn std::error::Error>> {
        self.storage.revoke_permission(agent_id, namespace)?;
        Ok(())
    }
    
    /// Check if an agent has a specific permission for a namespace.
    pub fn check_permission(
        &self,
        agent_id: &str,
        namespace: &str,
        permission: Permission,
    ) -> Result<bool, Box<dyn std::error::Error>> {
        Ok(self.storage.check_permission(agent_id, namespace, permission)?)
    }
    
    /// List all permissions for an agent.
    pub fn list_permissions(&self, agent_id: &str) -> Result<Vec<AclEntry>, Box<dyn std::error::Error>> {
        Ok(self.storage.list_permissions(agent_id)?)
    }
    
    /// Get statistics for a specific namespace.
    pub fn stats_ns(&self, namespace: Option<&str>) -> Result<MemoryStats, Box<dyn std::error::Error>> {
        let all = self.storage.all_in_namespace(namespace)?;
        let now = Utc::now();

        let mut by_type: HashMap<String, Vec<&MemoryRecord>> = HashMap::new();
        let mut by_layer: HashMap<String, Vec<&MemoryRecord>> = HashMap::new();
        let mut pinned = 0;

        for record in &all {
            by_type
                .entry(record.memory_type.to_string())
                .or_default()
                .push(record);
            by_layer
                .entry(record.layer.to_string())
                .or_default()
                .push(record);
            if record.pinned {
                pinned += 1;
            }
        }

        let type_stats: HashMap<String, TypeStats> = by_type
            .into_iter()
            .map(|(type_name, records)| {
                let count = records.len();
                let avg_strength = records
                    .iter()
                    .map(|r| effective_strength(r, now))
                    .sum::<f64>()
                    / count as f64;
                let avg_importance = records.iter().map(|r| r.importance).sum::<f64>() / count as f64;

                (
                    type_name,
                    TypeStats {
                        count,
                        avg_strength,
                        avg_importance,
                    },
                )
            })
            .collect();

        let layer_stats: HashMap<String, LayerStats> = by_layer
            .into_iter()
            .map(|(layer_name, records)| {
                let count = records.len();
                let avg_working = records.iter().map(|r| r.working_strength).sum::<f64>() / count as f64;
                let avg_core = records.iter().map(|r| r.core_strength).sum::<f64>() / count as f64;

                (
                    layer_name,
                    LayerStats {
                        count,
                        avg_working,
                        avg_core,
                    },
                )
            })
            .collect();

        let uptime_hours = (now - self.created_at).num_seconds() as f64 / 3600.0;

        Ok(MemoryStats {
            total_memories: all.len(),
            by_type: type_stats,
            by_layer: layer_stats,
            pinned,
            uptime_hours,
        })
    }
    
    // === Phase 3: Cross-Agent Intelligence ===
    
    /// Recall memories with cross-namespace associations.
    ///
    /// When using namespace="*", this also returns Hebbian links that span
    /// across different namespaces, enabling cross-domain intelligence.
    ///
    /// # Arguments
    ///
    /// * `query` - Natural language query
    /// * `namespace` - Namespace to search ("*" for all)
    /// * `limit` - Maximum number of results
    pub fn recall_with_associations(
        &mut self,
        query: &str,
        namespace: Option<&str>,
        limit: usize,
    ) -> Result<RecallWithAssociationsResult, Box<dyn std::error::Error>> {
        let now = Utc::now();
        let ns = namespace.unwrap_or("default");
        
        // Get candidate memories via FTS
        let candidates = self.storage.search_fts_ns(query, limit * 3, Some(ns))?;
        
        // Score each candidate with ACT-R activation
        let mut scored: Vec<_> = candidates
            .into_iter()
            .filter(|r| r.superseded_by.is_none()) // Defense-in-depth
            .map(|record| {
                let activation = retrieval_activation(
                    &record,
                    &[],
                    now,
                    self.config.actr_decay,
                    self.config.context_weight,
                    self.config.importance_weight,
                    self.config.contradiction_penalty,
                );
                (record, activation)
            })
            .filter(|(_, act)| *act > f64::NEG_INFINITY)
            .collect();
        
        scored.sort_by(|a, b| b.1.partial_cmp(&a.1).unwrap());
        
        // Take top-k
        let results: Vec<_> = scored
            .into_iter()
            .take(limit)
            .map(|(record, activation)| {
                let age_hours = (now - record.created_at).num_seconds() as f64 / 3600.0;
                let confidence = compute_query_confidence(
                    None,   // no embedding in associations path
                    false,  // not an FTS query match
                    0.0,    // no entity score
                    age_hours,
                );
                let confidence_label = confidence_label(confidence);
                
                RecallResult {
                    record,
                    activation,
                    confidence,
                    confidence_label,
                }
            })
            .collect();
        
        // Record access for all retrieved memories
        for result in &results {
            self.storage.record_access(&result.record.id)?;
        }
        
        // Collect cross-namespace associations
        let mut cross_links = Vec::new();
        
        // For wildcard namespace queries, also collect cross-namespace Hebbian neighbors
        if ns == "*" && results.len() >= 2 {
            // Get namespaces for all retrieved memories
            let mut memories_with_ns: Vec<MemoryWithNamespace> = Vec::new();
            
            for result in &results {
                if let Some(mem_ns) = self.storage.get_namespace(&result.record.id)? {
                    memories_with_ns.push(MemoryWithNamespace {
                        id: result.record.id.clone(),
                        namespace: mem_ns,
                    });
                }
            }
            
            // Record cross-namespace co-activation
            if self.config.hebbian_enabled {
                record_cross_namespace_coactivation(
                    &mut self.storage,
                    &memories_with_ns,
                    self.config.hebbian_threshold,
                )?;
            }
            
            // Collect cross-links from all retrieved memories
            for result in &results {
                let links = self.storage.get_cross_namespace_neighbors(&result.record.id)?;
                cross_links.extend(links);
            }
            
            // Deduplicate by (source_id, target_id)
            cross_links.sort_by(|a, b| {
                (&a.source_id, &a.target_id).cmp(&(&b.source_id, &b.target_id))
            });
            cross_links.dedup_by(|a, b| a.source_id == b.source_id && a.target_id == b.target_id);
            
            // Sort by strength descending
            cross_links.sort_by(|a, b| b.strength.partial_cmp(&a.strength).unwrap());
        }
        
        Ok(RecallWithAssociationsResult {
            memories: results,
            cross_links,
        })
    }
    
    /// Discover cross-namespace Hebbian links between two namespaces.
    ///
    /// Returns all Hebbian associations that span across the given namespaces.
    /// ACL-aware: only returns links between namespaces the agent can read.
    pub fn discover_cross_links(
        &self,
        namespace_a: &str,
        namespace_b: &str,
    ) -> Result<Vec<HebbianLink>, Box<dyn std::error::Error>> {
        // ACL check if agent_id is set
        if let Some(ref agent_id) = self.agent_id {
            let can_read_a = self.storage.check_permission(agent_id, namespace_a, Permission::Read)?;
            let can_read_b = self.storage.check_permission(agent_id, namespace_b, Permission::Read)?;
            
            if !can_read_a || !can_read_b {
                return Ok(vec![]); // No access to one or both namespaces
            }
        }
        
        Ok(self.storage.discover_cross_links(namespace_a, namespace_b)?)
    }
    
    /// Get all cross-namespace associations for a memory.
    pub fn get_cross_associations(
        &self,
        memory_id: &str,
    ) -> Result<Vec<CrossLink>, Box<dyn std::error::Error>> {
        Ok(self.storage.get_cross_namespace_neighbors(memory_id)?)
    }
    
    // === Subscription/Notification Methods ===
    
    /// Subscribe to notifications for a namespace.
    ///
    /// The agent will receive notifications when new memories are stored
    /// with importance >= min_importance in the specified namespace.
    pub fn subscribe(
        &self,
        agent_id: &str,
        namespace: &str,
        min_importance: f64,
    ) -> Result<(), Box<dyn std::error::Error>> {
        let mgr = SubscriptionManager::new(self.storage.connection())?;
        mgr.subscribe(agent_id, namespace, min_importance)?;
        Ok(())
    }
    
    /// Unsubscribe from a namespace.
    pub fn unsubscribe(
        &self,
        agent_id: &str,
        namespace: &str,
    ) -> Result<bool, Box<dyn std::error::Error>> {
        let mgr = SubscriptionManager::new(self.storage.connection())?;
        mgr.unsubscribe(agent_id, namespace)
    }
    
    /// List subscriptions for an agent.
    pub fn list_subscriptions(
        &self,
        agent_id: &str,
    ) -> Result<Vec<Subscription>, Box<dyn std::error::Error>> {
        let mgr = SubscriptionManager::new(self.storage.connection())?;
        mgr.list_subscriptions(agent_id)
    }
    
    /// Check for notifications since last check.
    ///
    /// Returns new memories that exceed the subscription thresholds.
    /// Updates the cursor so the same notifications aren't returned twice.
    pub fn check_notifications(
        &self,
        agent_id: &str,
    ) -> Result<Vec<Notification>, Box<dyn std::error::Error>> {
        let mgr = SubscriptionManager::new(self.storage.connection())?;
        mgr.check_notifications(agent_id)
    }
    
    /// Peek at notifications without updating cursor.
    pub fn peek_notifications(
        &self,
        agent_id: &str,
    ) -> Result<Vec<Notification>, Box<dyn std::error::Error>> {
        let mgr = SubscriptionManager::new(self.storage.connection())?;
        mgr.peek_notifications(agent_id)
    }

    /// Extract entities from existing memories that don't have entity links yet.
    /// Returns (processed_count, entity_count, relation_count).
    pub fn backfill_entities(&self, batch_size: usize) -> Result<(usize, usize, usize), Box<dyn std::error::Error>> {
        let unlinked = self.storage.get_memories_without_entities(batch_size)?;
        let mut entity_count = 0;
        let mut relation_count = 0;
        let processed = unlinked.len();

        for (memory_id, content, ns) in &unlinked {
            let entities = self.entity_extractor.extract(content);
            let mut entity_ids = Vec::new();

            for entity in &entities {
                match self.storage.upsert_entity(
                    &entity.normalized,
                    entity.entity_type.as_str(),
                    ns,
                    None,
                ) {
                    Ok(eid) => {
                        let _ = self.storage.link_memory_entity(memory_id, &eid, "mention");
                        entity_ids.push(eid);
                        entity_count += 1;
                    }
                    Err(e) => {
                        log::warn!("Entity upsert failed during backfill: {}", e);
                    }
                }
            }

            // Co-occurrence (capped at 10)
            let cap = entity_ids.len().min(10);
            for i in 0..cap {
                for j in (i + 1)..cap {
                    if self
                        .storage
                        .upsert_entity_relation(&entity_ids[i], &entity_ids[j], "co_occurs", ns)
                        .is_ok()
                    {
                        relation_count += 1;
                    }
                }
            }
        }

        Ok((processed, entity_count, relation_count))
    }

    /// Get entity statistics: (entity_count, relation_count, link_count).
    pub fn entity_stats(&self) -> Result<(usize, usize, usize), Box<dyn std::error::Error>> {
        Ok(self.storage.entity_stats()?)
    }
    
    /// Purge garbage entities created by regex false positives.
    /// Removes:
    /// - Person entities that are 1-2 chars or pure digits (e.g., "0", "1", "types")
    /// - Orphaned entities with no memory links
    ///
    /// Returns count of entities deleted.
    pub fn purge_garbage_entities(&self) -> Result<usize, Box<dyn std::error::Error>> {
        let mut total_deleted = 0;
        
        // Phase 1: Delete short/numeric person entities that are clearly false positives
        let garbage_persons: Vec<String> = {
            let conn = self.storage.connection();
            let mut stmt = conn.prepare(
                "SELECT id, name FROM entities WHERE entity_type = 'person'"
            )?;
            let rows: Vec<(String, String)> = stmt.query_map([], |row| {
                Ok((row.get::<_, String>(0)?, row.get::<_, String>(1)?))
            })?.filter_map(|r| r.ok()).collect();
            drop(stmt);
            
            rows.into_iter()
                .filter(|(_, name)| {
                    let n = name.trim();
                    // Pure digit, single char, or known false positive
                    n.len() <= 2
                        || n.chars().all(|c| c.is_ascii_digit())
                        || matches!(n, "types" | "user" | "mac" | "sigma" | "github")
                })
                .map(|(id, _)| id)
                .collect()
        };
        
        for id in &garbage_persons {
            if self.storage.delete_entity(id)? {
                total_deleted += 1;
            }
        }
        
        // Phase 2: Delete orphaned entities (no memory_entities links)
        let orphans: Vec<String> = {
            let conn = self.storage.connection();
            let mut stmt = conn.prepare(
                "SELECT e.id FROM entities e
                 LEFT JOIN memory_entities me ON e.id = me.entity_id
                 WHERE me.entity_id IS NULL"
            )?;
            let rows = stmt.query_map([], |row| row.get::<_, String>(0))?;
            rows.filter_map(|r| r.ok()).collect()
        };
        
        for id in &orphans {
            if self.storage.delete_entity(id)? {
                total_deleted += 1;
            }
        }
        
        if total_deleted > 0 {
            log::info!("Purged {} garbage entities ({} false-positive persons, {} orphans)",
                total_deleted, garbage_persons.len(), orphans.len());
        }
        
        Ok(total_deleted)
    }

    /// List entities, optionally filtered by type and namespace.
    /// Returns (EntityRecord, mention_count) pairs ordered by mention count descending.
    pub fn list_entities(
        &self,
        entity_type: Option<&str>,
        namespace: Option<&str>,
        limit: usize,
    ) -> Result<Vec<(crate::storage::EntityRecord, usize)>, Box<dyn std::error::Error>> {
        Ok(self.storage.list_entities(entity_type, namespace, limit)?)
    }

    // ===================================================================
    // Knowledge Synthesis API (ISS-005)
    // ===================================================================

    /// Run a full synthesis cycle: discover clusters → gate check → generate insights → store.
    ///
    /// Requires `set_synthesis_settings()` to have been called with `enabled: true`.
    /// Without an LLM provider (`set_synthesis_llm_provider()`), synthesis still
    /// discovers clusters and runs gate checks but skips insight text generation
    /// (graceful degradation).
    pub fn synthesize(
        &mut self,
    ) -> Result<crate::synthesis::types::SynthesisReport, Box<dyn std::error::Error>> {
        let settings = self.synthesis_settings.clone().unwrap_or_default();
        let embedding_model = self.embedding.as_ref().map(|e| e.config().model_id());
        let engine = self.build_synthesis_engine(embedding_model);
        let result = engine.synthesize(&mut self.storage, &settings);
        // Restore LLM provider (consumed by build_synthesis_engine via take())
        self.restore_llm_provider(engine.into_provider());
        result
    }

    /// Run a full synthesis cycle with custom settings (overrides stored settings).
    pub fn synthesize_with(
        &mut self,
        settings: &crate::synthesis::types::SynthesisSettings,
    ) -> Result<crate::synthesis::types::SynthesisReport, Box<dyn std::error::Error>> {
        let embedding_model = self.embedding.as_ref().map(|e| e.config().model_id());
        let engine = self.build_synthesis_engine(embedding_model);
        let result = engine.synthesize(&mut self.storage, settings);
        self.restore_llm_provider(engine.into_provider());
        result
    }

    /// Dry-run synthesis: discover clusters and gate decisions without making any changes.
    ///
    /// Returns the report with clusters_found and gate_results populated,
    /// but insights_created and sources_demoted will be empty.
    pub fn synthesize_dry_run(
        &mut self,
    ) -> Result<crate::synthesis::types::SynthesisReport, Box<dyn std::error::Error>> {
        use crate::synthesis::{cluster, gate};
        let settings = self.synthesis_settings.clone().unwrap_or_default();
        let embedding_model = self.embedding.as_ref().map(|e| e.config().model_id());

        let clusters = cluster::discover_clusters(
            &self.storage,
            &settings.cluster_discovery,
            embedding_model.as_deref(),
        )?;

        let mut gate_results = Vec::new();
        for cluster_data in &clusters {
            let all_memories = self.storage.all()?;
            let member_set: std::collections::HashSet<&str> =
                cluster_data.members.iter().map(|s| s.as_str()).collect();
            let members: Vec<MemoryRecord> = all_memories
                .into_iter()
                .filter(|m| member_set.contains(m.id.as_str()))
                .collect();

            let covered_pct = self.storage.check_coverage(&cluster_data.members)?;
            let gate_result = gate::check_gate(
                cluster_data,
                &members,
                &settings.gate,
                covered_pct,
                true,  // assume changed
                false, // not all pairs similar
            );
            gate_results.push(gate_result);
        }

        Ok(crate::synthesis::types::SynthesisReport {
            clusters_found: clusters.len(),
            clusters_synthesized: 0,
            clusters_auto_updated: 0,
            clusters_deferred: gate_results.iter().filter(|g| matches!(g.decision, crate::synthesis::types::GateDecision::Defer { .. })).count(),
            clusters_skipped: gate_results.iter().filter(|g| matches!(g.decision, crate::synthesis::types::GateDecision::Skip { .. })).count(),
            synthesis_runs_full: 0,
            synthesis_runs_incremental: 0,
            insights_created: Vec::new(),
            sources_demoted: Vec::new(),
            errors: Vec::new(),
            duration: std::time::Duration::ZERO,
            gate_results,
        })
    }

    /// Unified sleep cycle: consolidate, synthesize, decay, forget, rebalance.
    ///
    /// This is the recommended way to run the full memory maintenance pipeline.
    /// Consolidation always runs; synthesis only runs if enabled via settings.
    pub fn sleep_cycle(
        &mut self,
        days: f64,
        namespace: Option<&str>,
    ) -> Result<SleepReport, Box<dyn std::error::Error>> {
        use std::time::Instant;
        let cycle_start = Instant::now();
        let mut phases = Vec::new();

        // Phase 1: Synaptic consolidation (existing)
        let t = Instant::now();
        self.consolidate_namespace(days, namespace)?;
        phases.push(PhaseReport {
            name: "consolidate".to_string(),
            duration_ms: t.elapsed().as_millis() as u64,
            count: 0,
        });

        // Phase 2: Knowledge synthesis (if enabled, now incremental via C4)
        let t = Instant::now();
        let synthesis = if self.synthesis_settings.as_ref().is_some_and(|s| s.enabled) {
            match self.synthesize() {
                Ok(report) => {
                    phases.push(PhaseReport {
                        name: "synthesis".to_string(),
                        duration_ms: t.elapsed().as_millis() as u64,
                        count: report.insights_created.len(),
                    });
                    Some(report)
                }
                Err(e) => {
                    log::warn!("Synthesis in sleep cycle failed (non-fatal): {e}");
                    phases.push(PhaseReport {
                        name: "synthesis".to_string(),
                        duration_ms: t.elapsed().as_millis() as u64,
                        count: 0,
                    });
                    None
                }
            }
        } else {
            None
        };

        // Phase 3: Decay check (C5) — flag weak memories
        let t = Instant::now();
        let decay = self.check_decay_and_flag(namespace)?;
        phases.push(PhaseReport {
            name: "decay".to_string(),
            duration_ms: t.elapsed().as_millis() as u64,
            count: decay.flagged_for_forget,
        });

        // Phase 4: Forget (C6) — soft-delete + hard-delete old
        let t = Instant::now();
        let forget = self.forget_bulk()?;
        phases.push(PhaseReport {
            name: "forget".to_string(),
            duration_ms: t.elapsed().as_millis() as u64,
            count: forget.soft_deleted + forget.hard_deleted,
        });

        // Phase 5: Rebalance (C9) — repair integrity
        let t = Instant::now();
        let rebalance = self.rebalance_internal()?;
        phases.push(PhaseReport {
            name: "rebalance".to_string(),
            duration_ms: t.elapsed().as_millis() as u64,
            count: rebalance.repairs,
        });

        // Reset per-cycle counters
        self.dedup_merge_count = 0;
        self.dedup_write_count = 0;
        self.last_add_result = None;

        Ok(SleepReport {
            consolidation_ok: true,
            synthesis,
            phases,
            decay: Some(decay),
            forget: Some(forget),
            rebalance: Some(rebalance),
            duration_ms: cycle_start.elapsed().as_millis() as u64,
        })
    }

    /// List all insight memories (memories with `is_synthesis: true` metadata).
    ///
    /// Returns insight MemoryRecords sorted by creation time (newest first).
    pub fn list_insights(
        &self,
        limit: Option<usize>,
    ) -> Result<Vec<MemoryRecord>, Box<dyn std::error::Error>> {
        let all = self.storage.all()?;
        let mut insights: Vec<MemoryRecord> = all
            .into_iter()
            .filter(is_insight)
            .collect();
        insights.sort_by(|a, b| b.created_at.cmp(&a.created_at));
        if let Some(l) = limit {
            insights.truncate(l);
        }
        Ok(insights)
    }

    /// Get source provenance records for a given insight.
    pub fn insight_sources(
        &self,
        insight_id: &str,
    ) -> Result<Vec<crate::synthesis::types::ProvenanceRecord>, Box<dyn std::error::Error>> {
        self.storage.get_insight_sources(insight_id)
    }

    /// Get insights derived from a specific source memory.
    pub fn insights_for_memory(
        &self,
        memory_id: &str,
    ) -> Result<Vec<crate::synthesis::types::ProvenanceRecord>, Box<dyn std::error::Error>> {
        self.storage.get_memory_insights(memory_id)
    }

    /// Reverse a synthesis: archive the insight and restore source importances.
    ///
    /// Does NOT delete the insight (GUARD-1: No Data Loss). Instead, archives it
    /// with importance 0.0 and restores all source memories to their pre-demotion state.
    pub fn reverse_synthesis(
        &mut self,
        insight_id: &str,
    ) -> Result<crate::synthesis::types::UndoSynthesis, Box<dyn std::error::Error>> {
        let embedding_model = self.embedding.as_ref().map(|e| e.config().model_id());
        let engine = self.build_synthesis_engine(embedding_model);
        let result = engine.undo_synthesis(&mut self.storage, insight_id);
        self.restore_llm_provider(engine.into_provider());
        result
    }

    /// Trace the provenance chain of a memory/insight back through its sources.
    pub fn get_provenance(
        &self,
        memory_id: &str,
        max_depth: usize,
    ) -> Result<crate::synthesis::types::ProvenanceChain, Box<dyn std::error::Error>> {
        // get_provenance only needs &Storage, no need to take LLM provider
        crate::synthesis::provenance::get_provenance_chain(&self.storage, memory_id, max_depth)
    }

    /// Build a DefaultSynthesisEngine, temporarily borrowing the LLM provider.
    ///
    /// Uses `Option::take` to move the provider into the engine. Callers must
    /// call `restore_llm_provider` after using the engine to put it back.
    fn build_synthesis_engine(
        &mut self,
        embedding_model: Option<String>,
    ) -> crate::synthesis::engine::DefaultSynthesisEngine {
        let llm = self.synthesis_llm_provider.take();
        crate::synthesis::engine::DefaultSynthesisEngine::new(llm, embedding_model)
    }

    /// Restore the LLM provider after engine use (engine returns it via `into_provider()`).
    fn restore_llm_provider(&mut self, provider: Option<Box<dyn crate::synthesis::types::SynthesisLlmProvider>>) {
        self.synthesis_llm_provider = provider;
    }

}

/// Compute confidence score (0.0-1.0) for a recall result.
///
/// Unlike the ranking score (combined_score), confidence measures how certain
/// we are that this memory is genuinely relevant to the query.
///
/// Signals:
/// - embedding_similarity: cosine sim of query vs memory embedding (strongest signal)
/// - in_fts_results: whether FTS found this memory (keyword overlap = confidence boost)
/// - entity_score: entity overlap score 0-1 (topical relevance)
/// - age_hours: memory age in hours (mild recency boost for very recent memories)
fn compute_query_confidence(
    embedding_similarity: Option<f32>,  // None if no embedding available
    in_fts_results: bool,
    entity_score: f64,  // 0.0 if no entity match or entity disabled
    age_hours: f64,
) -> f64 {
    let mut confidence = 0.0;
    let mut max_possible = 0.0;

    // Signal 1: Embedding similarity (weight: 0.55)
    if let Some(sim) = embedding_similarity {
        let sim = sim as f64;
        // Apply sigmoid-like curve to sharpen discrimination
        // sim > 0.7 → strong confidence, sim < 0.3 → near zero
        let emb_conf = if sim > 0.0 {
            // Logistic function centered at 0.5 with steepness 10
            1.0 / (1.0 + (-10.0 * (sim - 0.5)).exp())
        } else {
            0.0
        };
        confidence += 0.55 * emb_conf;
        max_possible += 0.55;
    }

    // Signal 2: FTS match (weight: 0.20)
    if in_fts_results {
        confidence += 0.20;
    }
    max_possible += 0.20;

    // Signal 3: Entity overlap (weight: 0.20)
    confidence += 0.20 * entity_score;
    max_possible += 0.20;

    // Signal 4: Recency boost (weight: 0.05)
    // Very recent memories get a small confidence boost
    // 1 hour ago → ~1.0, 24 hours → ~0.5, 7 days → ~0.1
    let recency = 1.0 / (1.0 + (age_hours / 24.0).ln().max(0.0));
    confidence += 0.05 * recency.clamp(0.0, 1.0);
    max_possible += 0.05;

    // Normalize by max possible (handles case where embedding is unavailable)
    if max_possible > 0.0 {
        (confidence / max_possible).clamp(0.0, 1.0)
    } else {
        0.0
    }
}

fn confidence_label(confidence: f64) -> String {
    match confidence {
        c if c >= 0.8 => "high".to_string(),
        c if c >= 0.5 => "medium".to_string(),
        c if c >= 0.2 => "low".to_string(),
        _ => "very low".to_string(),
    }
}

fn detect_feedback_polarity(feedback: &str) -> f64 {
    let lower = feedback.to_lowercase();
    let positive = ["good", "great", "excellent", "correct", "right", "yes", "nice", "perfect"];
    let negative = ["bad", "wrong", "incorrect", "no", "error", "mistake", "poor"];

    let pos_count = positive.iter().filter(|&w| lower.contains(w)).count();
    let neg_count = negative.iter().filter(|&w| lower.contains(w)).count();

    if pos_count > neg_count {
        1.0
    } else if neg_count > pos_count {
        -1.0
    } else {
        0.0
    }
}

#[cfg(test)]
mod confidence_tests {
    use super::*;

    #[test]
    fn test_confidence_high_embedding_sim() {
        // High embedding sim + FTS + entity → high confidence
        let c = compute_query_confidence(Some(0.85), true, 0.8, 1.0);
        assert!(c > 0.8, "expected high confidence, got {c}");
        assert_eq!(confidence_label(c), "high");
    }

    #[test]
    fn test_confidence_low_embedding_sim() {
        // Low embedding sim, no FTS, no entity → low confidence
        let c = compute_query_confidence(Some(0.2), false, 0.0, 720.0);
        assert!(c < 0.3, "expected low confidence, got {c}");
    }

    #[test]
    fn test_confidence_medium_embedding_sim() {
        // Medium embedding sim + FTS → medium range
        let c = compute_query_confidence(Some(0.55), true, 0.0, 24.0);
        assert!(c > 0.3 && c < 0.8, "expected medium confidence, got {c}");
    }

    #[test]
    fn test_confidence_no_embedding() {
        // No embedding available, FTS=true, some entity match
        let c = compute_query_confidence(None, true, 0.5, 2.0);
        // Without embedding, max_possible = 0.45, confidence comes from FTS + entity + recency
        assert!(c > 0.3, "expected reasonable confidence without embedding, got {c}");
        assert!(c < 1.0);
    }

    #[test]
    fn test_confidence_fts_only_boost() {
        // No embedding, FTS only, no entity
        let c_fts = compute_query_confidence(None, true, 0.0, 24.0);
        let c_none = compute_query_confidence(None, false, 0.0, 24.0);
        assert!(c_fts > c_none, "FTS should boost confidence: {c_fts} > {c_none}");
    }

    #[test]
    fn test_confidence_entity_boost() {
        // Same embedding sim, but different entity scores
        let c_entity = compute_query_confidence(Some(0.5), false, 0.9, 48.0);
        let c_no_entity = compute_query_confidence(Some(0.5), false, 0.0, 48.0);
        assert!(c_entity > c_no_entity, "entity should boost confidence: {c_entity} > {c_no_entity}");
    }

    #[test]
    fn test_confidence_recency_boost() {
        // Recent (1h) vs old (30 days = 720h) — same other signals
        let c_recent = compute_query_confidence(Some(0.6), true, 0.0, 1.0);
        let c_old = compute_query_confidence(Some(0.6), true, 0.0, 720.0);
        assert!(c_recent > c_old, "recent should have slightly higher confidence: {c_recent} > {c_old}");
        // But the difference should be small (recency weight is only 0.05)
        assert!((c_recent - c_old).abs() < 0.1, "recency difference should be small");
    }

    #[test]
    fn test_confidence_all_zero() {
        // All signals at worst values
        let c = compute_query_confidence(Some(0.0), false, 0.0, 8760.0); // 1 year old
        assert!(c < 0.1, "all-zero signals should give near-zero confidence, got {c}");
    }

    #[test]
    fn test_confidence_all_max() {
        // All signals at best values
        let c = compute_query_confidence(Some(0.99), true, 1.0, 0.1);
        assert!(c > 0.9, "all-max signals should give high confidence, got {c}");
    }

    #[test]
    fn test_confidence_label_thresholds() {
        assert_eq!(confidence_label(0.9), "high");
        assert_eq!(confidence_label(0.8), "high");
        assert_eq!(confidence_label(0.79), "medium");
        assert_eq!(confidence_label(0.5), "medium");
        assert_eq!(confidence_label(0.49), "low");
        assert_eq!(confidence_label(0.2), "low");
        assert_eq!(confidence_label(0.19), "very low");
        assert_eq!(confidence_label(0.0), "very low");
    }

    #[test]
    fn test_confidence_sigmoid_discrimination() {
        // The sigmoid should create clear separation between high/low sim
        let c_high = compute_query_confidence(Some(0.8), false, 0.0, 100.0);
        let c_low = compute_query_confidence(Some(0.3), false, 0.0, 100.0);
        let gap = c_high - c_low;
        assert!(gap > 0.3, "sigmoid should create large gap between 0.8 and 0.3 sim: gap={gap}");
    }

    #[test]
    fn test_auto_extract_importance_cap() {
        let mut config = MemoryConfig::default();
        config.auto_extract_importance_cap = 0.7;
        
        // Test capping logic directly
        let extracted_importance: f64 = 0.95;
        let capped = extracted_importance.min(config.auto_extract_importance_cap);
        assert_eq!(capped, 0.7);
        
        // Below cap — no change
        let low_importance: f64 = 0.3;
        let not_capped = low_importance.min(config.auto_extract_importance_cap);
        assert_eq!(not_capped, 0.3);
        
        // Exactly at cap — no change
        let at_cap: f64 = 0.7;
        let stays = at_cap.min(config.auto_extract_importance_cap);
        assert_eq!(stays, 0.7);
    }

    #[test]
    fn test_auto_extract_importance_cap_default() {
        let config = MemoryConfig::default();
        assert_eq!(config.auto_extract_importance_cap, 0.7);
    }

    #[test]
    fn test_dedup_recall_results_by_embedding() {
        // Create mock embeddings - two near-identical and one different
        let emb_a: Vec<f32> = vec![1.0, 0.0, 0.0];
        let emb_b: Vec<f32> = vec![0.99, 0.1, 0.0]; // Very similar to A
        let emb_c: Vec<f32> = vec![0.0, 1.0, 0.0]; // Different

        let mut embeddings_map: HashMap<&str, &Vec<f32>> = HashMap::new();
        embeddings_map.insert("id-a", &emb_a);
        embeddings_map.insert("id-b", &emb_b);
        embeddings_map.insert("id-c", &emb_c);

        let make_result = |id: &str, confidence: f64| RecallResult {
            record: MemoryRecord {
                id: id.to_string(),
                content: format!("content-{}", id),
                memory_type: MemoryType::Factual,
                layer: MemoryLayer::Working,
                created_at: Utc::now(),
                access_times: vec![Utc::now()],
                working_strength: 1.0,
                core_strength: 0.0,
                importance: 0.5,
                pinned: false,
                consolidation_count: 0,
                last_consolidated: None,
                source: "test".to_string(),
                contradicts: None,
                contradicted_by: None,
            superseded_by: None,
                metadata: None,
            },
            activation: 0.5,
            confidence,
            confidence_label: "high".to_string(),
        };

        let candidates = vec![
            make_result("id-a", 0.9),
            make_result("id-b", 0.8), // Near-dup of A
            make_result("id-c", 0.7),
        ];

        let result = Memory::dedup_recall_results_by_embedding(
            candidates,
            &embeddings_map,
            0.85, // threshold
            3,    // limit
        );

        // Should keep A and C, skip B (too similar to A)
        assert_eq!(result.len(), 2);
        assert_eq!(result[0].record.id, "id-a");
        assert_eq!(result[1].record.id, "id-c");
    }

    #[test]
    fn test_dedup_recall_no_duplicates() {
        // All embeddings are orthogonal — nothing should be deduped
        let emb_a: Vec<f32> = vec![1.0, 0.0, 0.0];
        let emb_b: Vec<f32> = vec![0.0, 1.0, 0.0];
        let emb_c: Vec<f32> = vec![0.0, 0.0, 1.0];

        let mut embeddings_map: HashMap<&str, &Vec<f32>> = HashMap::new();
        embeddings_map.insert("id-a", &emb_a);
        embeddings_map.insert("id-b", &emb_b);
        embeddings_map.insert("id-c", &emb_c);

        let make_result = |id: &str, confidence: f64| RecallResult {
            record: MemoryRecord {
                id: id.to_string(),
                content: format!("content-{}", id),
                memory_type: MemoryType::Factual,
                layer: MemoryLayer::Working,
                created_at: Utc::now(),
                access_times: vec![Utc::now()],
                working_strength: 1.0,
                core_strength: 0.0,
                importance: 0.5,
                pinned: false,
                consolidation_count: 0,
                last_consolidated: None,
                source: "test".to_string(),
                contradicts: None,
                contradicted_by: None,
            superseded_by: None,
                metadata: None,
            },
            activation: 0.5,
            confidence,
            confidence_label: "high".to_string(),
        };

        let candidates = vec![
            make_result("id-a", 0.9),
            make_result("id-b", 0.8),
            make_result("id-c", 0.7),
        ];

        let result = Memory::dedup_recall_results_by_embedding(
            candidates,
            &embeddings_map,
            0.85,
            3,
        );

        // All three should be kept
        assert_eq!(result.len(), 3);
    }

    #[test]
    fn test_dedup_recall_respects_limit() {
        // No dups, but limit is 2
        let emb_a: Vec<f32> = vec![1.0, 0.0, 0.0];
        let emb_b: Vec<f32> = vec![0.0, 1.0, 0.0];
        let emb_c: Vec<f32> = vec![0.0, 0.0, 1.0];

        let mut embeddings_map: HashMap<&str, &Vec<f32>> = HashMap::new();
        embeddings_map.insert("id-a", &emb_a);
        embeddings_map.insert("id-b", &emb_b);
        embeddings_map.insert("id-c", &emb_c);

        let make_result = |id: &str| RecallResult {
            record: MemoryRecord {
                id: id.to_string(),
                content: format!("content-{}", id),
                memory_type: MemoryType::Factual,
                layer: MemoryLayer::Working,
                created_at: Utc::now(),
                access_times: vec![Utc::now()],
                working_strength: 1.0,
                core_strength: 0.0,
                importance: 0.5,
                pinned: false,
                consolidation_count: 0,
                last_consolidated: None,
                source: "test".to_string(),
                contradicts: None,
                contradicted_by: None,
            superseded_by: None,
                metadata: None,
            },
            activation: 0.5,
            confidence: 0.8,
            confidence_label: "high".to_string(),
        };

        let candidates = vec![
            make_result("id-a"),
            make_result("id-b"),
            make_result("id-c"),
        ];

        let result = Memory::dedup_recall_results_by_embedding(
            candidates,
            &embeddings_map,
            0.85,
            2, // limit of 2
        );

        assert_eq!(result.len(), 2);
        assert_eq!(result[0].record.id, "id-a");
        assert_eq!(result[1].record.id, "id-b");
    }

    #[test]
    fn test_dedup_recall_missing_embedding_kept() {
        // If a candidate has no embedding in the lookup, it should be kept
        let emb_a: Vec<f32> = vec![1.0, 0.0, 0.0];

        let mut embeddings_map: HashMap<&str, &Vec<f32>> = HashMap::new();
        embeddings_map.insert("id-a", &emb_a);
        // id-b has no embedding

        let make_result = |id: &str| RecallResult {
            record: MemoryRecord {
                id: id.to_string(),
                content: format!("content-{}", id),
                memory_type: MemoryType::Factual,
                layer: MemoryLayer::Working,
                created_at: Utc::now(),
                access_times: vec![Utc::now()],
                working_strength: 1.0,
                core_strength: 0.0,
                importance: 0.5,
                pinned: false,
                consolidation_count: 0,
                last_consolidated: None,
                source: "test".to_string(),
                contradicts: None,
                contradicted_by: None,
            superseded_by: None,
                metadata: None,
            },
            activation: 0.5,
            confidence: 0.8,
            confidence_label: "high".to_string(),
        };

        let candidates = vec![
            make_result("id-a"),
            make_result("id-b"), // No embedding
        ];

        let result = Memory::dedup_recall_results_by_embedding(
            candidates,
            &embeddings_map,
            0.85,
            5,
        );

        // Both should be kept (id-b has no embedding, so can't be deduped)
        assert_eq!(result.len(), 2);
    }

    #[test]
    fn test_dedup_recall_backfills_from_candidates() {
        // A, B (dup of A), C (different) — with limit=2, should get A and C
        let emb_a: Vec<f32> = vec![1.0, 0.0, 0.0];
        let emb_b: Vec<f32> = vec![0.98, 0.05, 0.0]; // Near-duplicate of A
        let emb_c: Vec<f32> = vec![0.0, 1.0, 0.0]; // Different

        let mut embeddings_map: HashMap<&str, &Vec<f32>> = HashMap::new();
        embeddings_map.insert("id-a", &emb_a);
        embeddings_map.insert("id-b", &emb_b);
        embeddings_map.insert("id-c", &emb_c);

        let make_result = |id: &str, confidence: f64| RecallResult {
            record: MemoryRecord {
                id: id.to_string(),
                content: format!("content-{}", id),
                memory_type: MemoryType::Factual,
                layer: MemoryLayer::Working,
                created_at: Utc::now(),
                access_times: vec![Utc::now()],
                working_strength: 1.0,
                core_strength: 0.0,
                importance: 0.5,
                pinned: false,
                consolidation_count: 0,
                last_consolidated: None,
                source: "test".to_string(),
                contradicts: None,
                contradicted_by: None,
            superseded_by: None,
                metadata: None,
            },
            activation: 0.5,
            confidence,
            confidence_label: "high".to_string(),
        };

        let candidates = vec![
            make_result("id-a", 0.9),
            make_result("id-b", 0.85), // Dup of A, would normally be #2
            make_result("id-c", 0.7),  // #3 backfills into slot #2
        ];

        let result = Memory::dedup_recall_results_by_embedding(
            candidates,
            &embeddings_map,
            0.85,
            2, // limit=2, B gets deduped, C backfills
        );

        assert_eq!(result.len(), 2);
        assert_eq!(result[0].record.id, "id-a");
        assert_eq!(result[1].record.id, "id-c"); // Backfilled
    }

    #[test]
    fn test_recall_dedup_config_defaults() {
        let config = MemoryConfig::default();
        assert!(config.recall_dedup_enabled);
        assert!((config.recall_dedup_threshold - 0.85).abs() < f64::EPSILON);
    }

    // ── C7 Multi-Retrieval Fusion tests ────────────────────────────

    fn make_test_record(id: &str, content: &str, created_at: chrono::DateTime<Utc>) -> MemoryRecord {
        MemoryRecord {
            id: id.to_string(),
            content: content.to_string(),
            memory_type: MemoryType::Factual,
            layer: crate::types::MemoryLayer::Working,
            created_at,
            access_times: vec![created_at],
            working_strength: 1.0,
            core_strength: 0.0,
            importance: 0.5,
            pinned: false,
            consolidation_count: 0,
            last_consolidated: None,
            source: "test".to_string(),
            contradicts: None,
            contradicted_by: None,
            superseded_by: None,
            metadata: None,
        }
    }

    #[test]
    fn test_temporal_score_within_range() {
        use crate::query_classifier::TimeRange;
        let now = Utc::now();
        
        // Memory at the center of a 24-hour range
        let range = TimeRange {
            start: now - chrono::Duration::hours(24),
            end: now,
        };
        
        let record = make_test_record("t1", "test", now - chrono::Duration::hours(12));
        
        let score = Memory::temporal_score(&record, &Some(range), now);
        assert!(score > 0.9, "Center of range should score high: {}", score);
    }

    #[test]
    fn test_temporal_score_outside_range() {
        use crate::query_classifier::TimeRange;
        let now = Utc::now();
        
        let range = TimeRange {
            start: now - chrono::Duration::hours(24),
            end: now - chrono::Duration::hours(12),
        };
        
        let record = make_test_record("t2", "test", now - chrono::Duration::hours(1));
        
        let score = Memory::temporal_score(&record, &Some(range), now);
        assert!(score < 0.01, "Outside range should score ~0: {}", score);
    }

    #[test]
    fn test_temporal_score_no_range() {
        let now = Utc::now();
        
        let record = make_test_record("t3", "test", now - chrono::Duration::hours(1));
        
        let score = Memory::temporal_score(&record, &None, now);
        // Should be in neutral range (0.25-0.75)
        assert!(score >= 0.25 && score <= 0.75,
            "No range: score should be neutral-ish: {}", score);
    }

    #[test]
    fn test_hebbian_channel_scores_basic() {
        let dir = tempfile::tempdir().unwrap();
        let db = dir.path().join("test.db");
        let mut storage = crate::storage::Storage::new(db.to_str().unwrap()).unwrap();
        
        let now = Utc::now();
        let rec_a = make_test_record("a", "memory A", now);
        let rec_b = make_test_record("b", "memory B", now);
        let rec_c = make_test_record("c", "memory C", now);
        storage.add(&rec_a, "default").unwrap();
        storage.add(&rec_b, "default").unwrap();
        storage.add(&rec_c, "default").unwrap();
        
        // Create Hebbian link between A and B
        // First call creates tracking record, second call forms the link (threshold=1)
        storage.record_coactivation("a", "b", 1).unwrap();
        storage.record_coactivation("a", "b", 1).unwrap();
        
        let candidate_ids = vec!["a".to_string(), "b".to_string(), "c".to_string()];
        let scores = Memory::hebbian_channel_scores(&storage, &candidate_ids).unwrap();
        
        // A and B should have scores (linked to each other), C should not
        assert!(scores.get("a").copied().unwrap_or(0.0) > 0.0, "A should have hebbian score");
        assert!(scores.get("b").copied().unwrap_or(0.0) > 0.0, "B should have hebbian score");
        assert!(scores.get("c").copied().unwrap_or(0.0) < 0.01, "C should have no hebbian score");
    }

    #[test]
    fn test_c7_config_defaults() {
        let config = MemoryConfig::default();
        assert!((config.temporal_weight - 0.10).abs() < f64::EPSILON);
        assert!((config.hebbian_recall_weight - 0.10).abs() < f64::EPSILON);
        assert!(config.adaptive_weights);
    }

    #[test]
    fn test_adaptive_weights_disabled_preserves_behavior() {
        // When adaptive_weights = false, query classifier should return neutral
        let analysis = crate::query_classifier::QueryAnalysis::neutral();
        assert_eq!(analysis.weight_modifiers.fts, 1.0);
        assert_eq!(analysis.weight_modifiers.embedding, 1.0);
        assert_eq!(analysis.weight_modifiers.actr, 1.0);
        assert_eq!(analysis.weight_modifiers.temporal, 1.0);
        assert_eq!(analysis.weight_modifiers.hebbian, 1.0);
    }

    // ── GWT Broadcast Tests ───────────────────────────────────────

    #[test]
    fn test_broadcast_admission_generates_confidence_signals() {
        let mut mem = Memory::new(":memory:", None).unwrap();
        let mut wm = SessionWorkingMemory::default();

        // Store a memory so we have something to broadcast.
        let id = mem
            .add("Rust is a systems programming language", MemoryType::Factual, Some(0.5), None, None)
            .unwrap();

        // Hub should be empty before broadcast.
        assert_eq!(mem.interoceptive_hub().buffer_len(), 0);

        // Broadcast the memory admission.
        mem.broadcast_admission(&[id], &mut wm);

        // Hub should now have at least one signal (confidence).
        // No emotional bus → no alignment signal, but confidence is always generated.
        assert!(
            mem.interoceptive_hub().buffer_len() >= 1,
            "expected ≥1 signal in hub, got {}",
            mem.interoceptive_hub().buffer_len()
        );
    }

    #[test]
    fn test_broadcast_admission_multiple_memories() {
        let mut mem = Memory::new(":memory:", None).unwrap();
        let mut wm = SessionWorkingMemory::default();

        let id1 = mem
            .add("First memory about coding", MemoryType::Factual, Some(0.5), None, None)
            .unwrap();
        let id2 = mem
            .add("Second memory about trading", MemoryType::Factual, Some(0.6), None, None)
            .unwrap();
        let id3 = mem
            .add("Third memory about research", MemoryType::Factual, Some(0.7), None, None)
            .unwrap();

        mem.broadcast_admission(&[id1, id2, id3], &mut wm);

        // Each memory generates at least 1 confidence signal → ≥3.
        assert!(
            mem.interoceptive_hub().buffer_len() >= 3,
            "expected ≥3 signals, got {}",
            mem.interoceptive_hub().buffer_len()
        );
    }

    #[test]
    fn test_broadcast_with_nonexistent_memory_is_safe() {
        let mut mem = Memory::new(":memory:", None).unwrap();
        let mut wm = SessionWorkingMemory::default();

        // Broadcast a memory that doesn't exist — should not panic.
        let neighbors = mem.broadcast_admission(&["nonexistent-id".to_string()], &mut wm);
        assert!(neighbors.is_empty());
        assert_eq!(mem.interoceptive_hub().buffer_len(), 0);
    }

    #[test]
    fn test_broadcast_updates_hub_domain_state() {
        let mut mem = Memory::new(":memory:", None).unwrap();
        let mut wm = SessionWorkingMemory::default();

        // Store multiple memories and broadcast them.
        let id1 = mem
            .add("Important fact about Rust", MemoryType::Factual, Some(0.8), None, None)
            .unwrap();
        let id2 = mem
            .add("Another fact about memory", MemoryType::Factual, Some(0.3), None, None)
            .unwrap();

        mem.broadcast_admission(&[id1, id2], &mut wm);

        // Hub should have processed signals and have some state.
        let state = mem.interoceptive_snapshot();
        assert!(state.buffer_size > 0, "hub should have buffered signals");
    }

    #[test]
    fn test_broadcast_hebbian_spreading() {
        // Use raw storage to set up Hebbian links, then verify
        // broadcast_admission spreads activation.
        let dir = tempfile::tempdir().unwrap();
        let db = dir.path().join("broadcast_hebb.db");
        let mut mem = Memory::new(db.to_str().unwrap(), None).unwrap();
        let mut wm = SessionWorkingMemory::default();

        // Store two memories.
        let id_a = mem
            .add("Memory A about Rust", MemoryType::Factual, Some(0.5), None, None)
            .unwrap();
        let id_b = mem
            .add("Memory B about Rust compilers", MemoryType::Factual, Some(0.5), None, None)
            .unwrap();

        // Create a Hebbian link by simulating co-recall via the storage layer.
        // We need to strengthen it enough (weight > 0.1) for spreading to activate.
        // record_coactivation with threshold=1 → second call forms the link.
        {
            // Use recall to trigger co-activation recording (indirect approach).
            // Or directly use the underlying record_coactivation on Memory.
            // Since Memory doesn't expose &mut Storage, we'll use a workaround:
            // call recall with both IDs to trigger Hebbian learning.
            //
            // Actually, the cleanest approach: use rusqlite directly on the
            // connection to insert a Hebbian link for testing purposes.
            let conn = mem.connection();
            conn.execute(
                "INSERT OR REPLACE INTO hebbian_links (source_id, target_id, strength, coactivation_count, created_at) VALUES (?1, ?2, 0.5, 5, ?3)",
                rusqlite::params![&id_a, &id_b, Utc::now().timestamp() as f64],
            ).unwrap();
        }

        // Now broadcast only memory A → should spread to B via Hebbian link.
        let neighbors = mem.broadcast_admission(&[id_a.clone()], &mut wm);

        // B should appear as a primed neighbor.
        assert!(
            neighbors.contains(&id_b),
            "expected id_b in neighbors, got {:?}",
            neighbors
        );

        // B should now be in working memory (primed by spreading activation).
        assert!(wm.contains(&id_b), "id_b should be in WM after spreading");
    }
}

/// Jaccard similarity between two string sets.
fn jaccard_similarity_strings(a: &[String], b: &[String]) -> f64 {
    if a.is_empty() && b.is_empty() { return 0.0; }
    let set_a: std::collections::HashSet<&str> = a.iter().map(|s| s.as_str()).collect();
    let set_b: std::collections::HashSet<&str> = b.iter().map(|s| s.as_str()).collect();
    let intersection = set_a.intersection(&set_b).count();
    let union = set_a.union(&set_b).count();
    if union == 0 { 0.0 } else { intersection as f64 / union as f64 }
}