fractal-memory 0.3.0__py3-none-any.whl

fractal_memory/__init__.py

@@ -0,0 +1,1175 @@
+"""Fractal Memory — multi-resolution AI memory system.
+
+Usage::
+
+    from fractal_memory import FractalMemory
+
+    fm = FractalMemory()
+    await fm.initialize()
+    ctx = await fm.session_start("my-project")
+    mem = await fm.store("User prefers Python for backend")
+    result = await fm.retrieve("what language for APIs?")
+    summary = await fm.session_end()
+    await fm.close()
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import re
+from datetime import datetime
+from uuid import UUID, uuid4
+
+import numpy as np
+
+from .associations import AssociationNetwork
+from .buffer import WorkingMemoryBuffer
+from .config import FractalConfig, load_config
+from .consolidation import ConsolidationEngine, ConsolidationReport, MergeEvent
+from .domains import DomainManager, DomainStats
+from .embeddings import EmbeddingProvider, LocalEmbeddingProvider
+from .feedback import (
+    BatchedLLMJudge,
+    DangerTheoryDetector,
+    FeedbackSignal,
+    FeedbackSignalType,
+    FeedbackSubtype,
+    JudgeRating,
+    RetrievalTriple,
+    StoreSignal,
+    StoreSignalDetector,
+    StoreSignalSubtype,
+)
+from .gate import CoincidenceGate, Signal
+from .lifecycle import LifecycleManager
+from .llm import (
+    AnthropicProvider,
+    ClaudeCodeProvider,
+    LLMCallTracker,
+    LLMProvider,
+    LLMUnavailableError,
+    OllamaProvider,
+)
+from .models import (
+    DomainInfo,
+    LifecycleStatus,
+    Memory,
+    RetrievalResult,
+    Session,
+    SessionContext,
+    SessionSummary,
+    Task,
+    TaskStatus,
+)
+from .apoptosis import ApoptosisDecision, ApoptosisManager, ApoptosisReport
+from .bandits import ContextualBandit, RetrievalArm
+from .dreaming import DreamingEngine, DreamReport, REMReport, SlowWaveReport
+from .folding import DimensionalFolder
+from .kalman import CascadeWarning, CircuitBreaker
+from .maintenance import MaintenanceReport, MaintenanceScheduler
+from .morphogens import AllostericUpdater, MorphogenState, MorphogeneticField, ResponseCurve
+from .niche import DomainProposal, NicheConstructor, NicheHealth
+from .retrieval import RetrievalEngine
+from .scar import Scar, ScarTissueManager
+from .self_model import ExplanationReport, HealthReport, SelfModel
+from .session import SessionManager
+from .states import SystemState, SystemStateManager
+from .storage import Storage
+from .zoom import ZoomGenerator, ZoomLevels
+
+logger = logging.getLogger(__name__)
+
+__all__ = [
+    "FractalMemory",
+    "FractalConfig",
+    "load_config",
+    "Signal",
+    "Memory",
+    "Task",
+    "RetrievalResult",
+    "SessionContext",
+    "SessionSummary",
+    "DomainInfo",
+    "DomainStats",
+    "LifecycleStatus",
+    "TaskStatus",
+    "ZoomLevels",
+    "FeedbackSignal",
+    "FeedbackSignalType",
+    "FeedbackSubtype",
+    "JudgeRating",
+    "StoreSignal",
+    "StoreSignalDetector",
+    "StoreSignalSubtype",
+    "Scar",
+    "ConsolidationReport",
+    "MergeEvent",
+    "create_memory",
+    # Phase 3
+    "SystemState",
+    "SystemStateManager",
+    "MorphogenState",
+    "MorphogeneticField",
+    "ResponseCurve",
+    "AllostericUpdater",
+    "ContextualBandit",
+    "RetrievalArm",
+    "CircuitBreaker",
+    "CascadeWarning",
+    "ApoptosisManager",
+    "ApoptosisDecision",
+    "ApoptosisReport",
+    "NicheConstructor",
+    "DomainProposal",
+    "NicheHealth",
+    "DreamingEngine",
+    "DreamReport",
+    "SlowWaveReport",
+    "REMReport",
+    "DimensionalFolder",
+    "SelfModel",
+    "HealthReport",
+    "ExplanationReport",
+    "MaintenanceScheduler",
+    "MaintenanceReport",
+]
+
+
+class FractalMemory:
+    """Public API facade for the fractal memory system."""
+
+    def __init__(
+        self,
+        config: FractalConfig | None = None,
+        *,
+        llm: LLMProvider | None = None,
+        embeddings: EmbeddingProvider | None = None,
+    ) -> None:
+        self._config = config or load_config()
+        self._storage = Storage(self._config)
+
+        # Embeddings
+        if embeddings is not None:
+            self._embeddings: EmbeddingProvider = embeddings
+        else:
+            self._embeddings = LocalEmbeddingProvider(self._config.embedding_model)
+
+        # LLM provider (wrapped with rate limiting and usage tracking)
+        raw_llm: LLMProvider
+        if llm is not None:
+            raw_llm = llm
+        else:
+            raw_llm = self._create_llm_provider()
+        self._llm_tracker = LLMCallTracker(
+            raw_llm,
+            max_concurrent=self._config.llm_max_concurrent,
+            max_calls_per_session=self._config.llm_max_calls_per_session,
+        )
+        self._llm: LLMProvider = self._llm_tracker  # type: ignore[assignment]
+
+        self._zoom = ZoomGenerator(self._llm)
+        self._gate = CoincidenceGate(self._storage, self._embeddings, self._config)
+        self._lifecycle = LifecycleManager(self._storage, self._config)
+        self._buffer = WorkingMemoryBuffer(self._config)
+
+        # Phase 2 modules
+        self._associations = AssociationNetwork(
+            self._storage, self._embeddings, self._config
+        )
+        self._scars = ScarTissueManager(self._storage, self._embeddings, self._config)
+        self._domain_manager = DomainManager(self._storage, self._config)
+        self._danger_theory = DangerTheoryDetector(self._config)
+        self._store_signal_detector = StoreSignalDetector(self._embeddings, self._config)
+        self._judge = BatchedLLMJudge(self._llm, self._config)
+        self._consolidation = ConsolidationEngine(
+            storage=self._storage,
+            embeddings=self._embeddings,
+            llm=self._llm,
+            associations=self._associations,
+            scars=self._scars,
+            lifecycle=self._lifecycle,
+            domains=self._domain_manager,
+            config=self._config,
+        )
+
+        self._retrieval = RetrievalEngine(
+            self._storage,
+            self._embeddings,
+            self._config,
+            associations=self._associations,
+            scars=self._scars,
+            buffer=self._buffer,
+        )
+        self._session = SessionManager(
+            self._storage, self._llm, self._lifecycle, self._gate, self._config
+        )
+
+        # Phase 3 modules
+        self._morphogens = MorphogeneticField(
+            config=self._config,
+            storage=self._storage,
+            feedback=self._danger_theory,
+            domains=self._domain_manager,
+            embeddings=self._embeddings,
+        )
+        self._states = SystemStateManager(self._config)
+        self._bandits = ContextualBandit(self._config)
+        self._cascade: CircuitBreaker = CircuitBreaker(self._config)
+        self._apoptosis = ApoptosisManager(
+            storage=self._storage,
+            associations=self._associations,
+            scars=self._scars,
+            embeddings=self._embeddings,
+            llm=self._llm,
+            config=self._config,
+            zoom=self._zoom,
+        )
+        self._niche = NicheConstructor(
+            storage=self._storage,
+            associations=self._associations,
+            domains=self._domain_manager,
+            config=self._config,
+        )
+        self._dreaming = DreamingEngine(
+            storage=self._storage,
+            associations=self._associations,
+            embeddings=self._embeddings,
+            llm=self._llm,
+            bandits=self._bandits,
+            config=self._config,
+            zoom=self._zoom,
+        )
+        self._folding = DimensionalFolder(self._config)
+        self._self_model = SelfModel(
+            storage=self._storage,
+            associations=self._associations,
+            morphogens=self._morphogens,
+            domains=self._domain_manager,
+            config=self._config,
+            states=self._states,
+            bandits=self._bandits,
+        )
+        self._maintenance = MaintenanceScheduler(
+            storage=self._storage,
+            consolidation=self._consolidation,
+            dreaming=self._dreaming,
+            apoptosis=self._apoptosis,
+            niche=self._niche,
+            self_model=self._self_model,
+            folding=self._folding,
+            cascade=self._cascade,
+            config=self._config,
+        )
+
+        # Register Phase 2 session_end hooks (order matters)
+        self._session.register_on_end_hook(self._hook_judge_evaluate)
+        self._session.register_on_end_hook(self._hook_process_judge_ratings)
+        self._session.register_on_end_hook(self._hook_consolidation)
+        self._session.register_on_end_hook(self._hook_stigmergic_trails)
+        self._session.register_on_end_hook(self._hook_abandonment_check)
+        # Register Phase 3 session_end hooks
+        self._session.register_on_end_hook(self._hook_p3_maintenance)
+
+        # Track last retrieved IDs for habituation update on next retrieve()
+        self._last_injected_ids: list[UUID] = []
+        self._initialized = False
+
+        # Activity tracking counters for session_activity SQLite flush (heartbeat)
+        self._activity_stores: int = 0
+        self._activity_retrievals: int = 0
+
+    def _validate_domain(self, domain: str) -> None:
+        """Validate domain name format and length."""
+        if len(domain) > self._config.max_domain_length:
+            raise ValueError(
+                f"Domain name exceeds max length ({self._config.max_domain_length}): "
+                f"got {len(domain)} chars"
+            )
+        if not re.match(self._config.domain_pattern, domain):
+            raise ValueError(
+                f"Invalid domain name '{domain}': must match {self._config.domain_pattern}"
+            )
+
+    def _validate_text(self, text: str, max_length: int, label: str) -> None:
+        """Validate text input length."""
+        if not text or not text.strip():
+            raise ValueError(f"{label} must not be empty")
+        if len(text) > max_length:
+            raise ValueError(
+                f"{label} exceeds max length ({max_length}): got {len(text)} chars"
+            )
+
+    def _create_llm_provider(self) -> LLMProvider:
+        provider = self._config.llm_provider
+        timeout = self._config.llm_timeout_seconds
+        if provider == "bridge":
+            return ClaudeCodeProvider(model=self._config.llm_model, timeout=timeout)
+        elif provider == "anthropic":
+            if not self._config.llm_api_key:
+                raise ValueError(
+                    "llm_api_key required for 'anthropic' provider. "
+                    "Set FRACTAL_LLM_API_KEY or configure in TOML."
+                )
+            return AnthropicProvider(
+                api_key=self._config.llm_api_key,
+                model=self._config.llm_model,
+                timeout=timeout,
+            )
+        elif provider == "ollama":
+            return OllamaProvider(model=self._config.llm_model, timeout=timeout)
+        else:
+            raise ValueError(f"Unknown LLM provider: {provider}")
+
+    # ------------------------------------------------------------------
+    # Phase 2 session_end hooks
+    # ------------------------------------------------------------------
+
+    async def _hook_judge_evaluate(self) -> None:
+        """Hook 1: Retrospective LLM judge evaluation."""
+        if not self._config.enable_llm_judge:
+            self._judge_ratings = []
+            return
+        self._judge_ratings = await self._judge.evaluate()
+        logger.info("LLM judge: %d ratings", len(self._judge_ratings))
+
+    async def _hook_process_judge_ratings(self) -> None:
+        """Hook 2: Process judge ratings → update lifecycle."""
+        for rating in self._judge_ratings:
+            mem = await self._storage.get_memory(rating.memory_id)
+            if mem is None:
+                continue
+            if rating.rating == 2:
+                await self._lifecycle.on_memory_retrieved(mem)
+            elif rating.rating == 0:
+                await self._lifecycle.on_memory_missed(mem)
+            # rating == 1: silence = silence
+
+    async def _hook_consolidation(self) -> None:
+        """Hook 3: Sleep consolidation pipeline."""
+        session = self._session.current_session
+        self._consolidation.set_session_data(
+            session_memories=self._session._session_memories,
+            session_retrievals=self._session._session_retrievals,
+            judge_ratings=getattr(self, "_judge_ratings", []),
+            session_id=session.id if session else None,
+        )
+        await self._consolidation.run()
+
+    async def _hook_stigmergic_trails(self) -> None:
+        """Hook 4: Encode stigmergic trails from confirmed-useful retrievals."""
+        safe_memory_ids: list[UUID] = []
+        for rating in getattr(self, "_judge_ratings", []):
+            if rating.rating == 2:
+                safe_memory_ids.append(rating.memory_id)
+
+        if safe_memory_ids and self._session._session_retrievals:
+            last_retrieval = self._session._session_retrievals[-1]
+            last_l3_ids = last_retrieval.get("l3_ids", [])
+            if last_l3_ids:
+                dummy_embedding = await self._embeddings.embed(
+                    self._session._session_retrievals[-1].get("query", "")
+                )
+                await self._associations.strengthen_trail(
+                    last_l3_ids, dummy_embedding
+                )
+
+    async def _hook_abandonment_check(self) -> None:
+        """Hook 5: Detect abandoned sessions (< 3 exchanges)."""
+        if self._session._exchange_count < 3:
+            logger.info(
+                "Short session detected (%d exchanges) — abandonment signal",
+                self._session._exchange_count,
+            )
+            # No scar creation here — abandonment is logged for morphogens (Phase 3)
+
+    async def _hook_p3_maintenance(self) -> None:
+        """Hook 6 (Phase 3): Run session-end maintenance (dreaming, vitality, cascade)."""
+        try:
+            session = self._session.current_session
+            session_data: dict = {
+                "session_memory_ids": list(getattr(self._session, "_session_memories", [])),
+                "accessed_memory_ids": list(getattr(self._session, "_session_accessed", set())),
+                "domain": session.domain if session else self._config.default_domain,
+                "session_metrics": {},
+            }
+            await self._maintenance.session_end_maintenance(session_data)
+        except Exception:
+            logger.debug("Phase 3 session_end maintenance failed — non-critical", exc_info=True)
+
+    async def _maybe_flush_activity(self) -> None:
+        """Flush activity counters to SQLite if flush interval reached."""
+        session = self._session.current_session
+        if session is None:
+            return
+        total_ops = self._activity_stores + self._activity_retrievals
+        if total_ops % self._config.activity_flush_interval == 0 or total_ops <= self._config.activity_flush_interval:
+            try:
+                await self._storage.upsert_session_activity(
+                    session_id=session.id,
+                    domain=session.domain,
+                    started_at=session.started_at,
+                    stores=self._activity_stores,
+                    retrievals=self._activity_retrievals,
+                )
+            except Exception:
+                logger.debug("Activity flush failed — non-critical", exc_info=True)
+
+    async def initialize(self) -> None:
+        await self._storage.initialize()
+        # Check Pioneer→Shrub gate transition
+        await self._check_gate_transition()
+        self._initialized = True
+        # Warm up the embedding model in the background after initialize() returns.
+        # This lets the MCP handshake complete immediately while the model loads.
+        # TRANSFORMERS_OFFLINE=1 (set in mcp/server.py main()) ensures this is
+        # a fast disk-only load with no HuggingFace network requests.
+        asyncio.create_task(self._warmup_embeddings())
+
+    async def _warmup_embeddings(self) -> None:
+        """Load the embedding model into RAM in the background.
+
+        Called as a fire-and-forget task from initialize() so the MCP
+        handshake completes before the model is ready.
+        """
+        try:
+            await self._embeddings.embed("warmup")
+            logger.debug("Embedding model warmed up")
+        except Exception:
+            logger.warning("Embedding warmup failed — model will load on first use")
+
+    async def _check_gate_transition(self) -> None:
+        """Pioneer→Shrub transition: upgrade gate_signal_count 1→2 when thresholds met."""
+        if self._config.gate_signal_count >= 2:
+            return  # Already in Shrub or higher
+        memory_count = await self._storage.count_memories()
+        session_count = await self._storage.get_session_count()
+        if memory_count >= 50 and session_count >= 5:
+            logger.info(
+                "Pioneer→Shrub transition: memories=%d, sessions=%d. "
+                "gate_signal_count upgraded to 2.",
+                memory_count, session_count,
+            )
+            # Config is frozen — log transition; callers should use load_config(pioneer=False)
+            # The gate itself reads from config, so this is advisory only in Phase 2.
+            # Phase 3 will wire config mutability.
+
+    async def close(self) -> None:
+        await self._storage.close()
+        self._initialized = False
+
+    # -------------------------------------------------------------------
+    # Store
+    # -------------------------------------------------------------------
+
+    async def store(
+        self,
+        text: str,
+        domain: str | None = None,
+        intensity: float = 0.5,
+        signals: list[Signal] | None = None,
+    ) -> Memory | None:
+        """Store a memory through the coincidence gate.
+
+        Args:
+            text: Raw text content to store (max config.max_text_length chars).
+            domain: Domain to store under (alphanumeric, hyphens, underscores, dots).
+            intensity: Base intensity hint (0.0-1.0); gate may override.
+            signals: Coincidence signals; defaults to [EXPLICIT_STORE].
+
+        Returns:
+            The stored Memory, or None if gated out to waiting room.
+
+        Raises:
+            ValueError: If text is empty/too long or domain is invalid.
+        """
+        domain = domain or "default"
+        self._validate_text(text, self._config.max_text_length, "Store text")
+        self._validate_domain(domain)
+        if signals is None:
+            signals = [Signal.EXPLICIT_STORE]
+
+        # Phase 2: domain detection from context if not explicitly provided
+        if domain == "default" and signals != [Signal.EXPLICIT_STORE]:
+            detected = await self._domain_manager.detect_domain({}, text)
+            if detected != "general":
+                domain = detected
+                self._validate_domain(domain)
+
+        # Run through coincidence gate
+        decision = await self._gate.evaluate(text, signals, domain)
+        if not decision.passed:
+            logger.debug("Memory gated out (domain=%s, signals=%s)", domain, signals)
+            return None
+
+        # Generate zoom levels
+        zoom = await self._zoom.generate(text, domain)
+
+        # Embed (may already be computed by gate, but gate doesn't expose it)
+        embedding = await self._embeddings.embed(text)
+
+        now = datetime.utcnow()
+        memory = Memory(
+            id=uuid4(),
+            domain=domain,
+            created_at=now,
+            updated_at=now,
+            context={},
+            l0_tag=zoom.l0_tag,
+            l1_label=zoom.l1_label,
+            l2_summary=zoom.l2_summary,
+            l3_full=zoom.l3_full,
+            l4_raw=text,
+            embedding=embedding,
+            embedding_model=getattr(self._embeddings, "model_name", "unknown"),
+            intensity=decision.intensity,
+        )
+
+        await self._storage.store_memory(memory)
+        self._buffer.add_just_written(memory.id)
+        logger.info(
+            "Stored memory %s (domain=%s, l0=%s, intensity=%.2f)",
+            memory.id, domain, memory.l0_tag, memory.intensity,
+        )
+
+        if self._session.current_session:
+            await self._session.record_store(memory.id)
+            self._activity_stores += 1
+            await self._maybe_flush_activity()
+
+        return memory
+
+    # -------------------------------------------------------------------
+    # Retrieve
+    # -------------------------------------------------------------------
+
+    async def retrieve(
+        self,
+        query: str,
+        domain: str | None = None,
+        token_budget: int | None = None,
+        user_message: str | None = None,
+    ) -> RetrievalResult:
+        """Retrieve memories matching a query using progressive injection.
+
+        Args:
+            query: Search query text (max config.max_query_length chars).
+            domain: Domain to search in.
+            token_budget: Override token budget for this retrieval.
+            user_message: Optional raw user message for real-time feedback detection (Phase 2).
+
+        Returns:
+            RetrievalResult with L3/L2/L1 memories and hints.
+
+        Raises:
+            ValueError: If query is empty/too long or domain is invalid.
+        """
+        domain = domain or "default"
+        self._validate_text(query, self._config.max_query_length, "Query")
+        self._validate_domain(domain)
+
+        # Phase 2: Update habituation from previous turn's injected memories
+        self._buffer.update_habituation(self._last_injected_ids)
+
+        # Get buffer contents
+        buffer_ids = self._buffer.get_buffer_ids()
+
+        # ------ Phase 3 step 1: Compute morphogens → apply to parameters ------
+        query_embedding = await self._embeddings.embed(query)
+        morphogen_params: dict[str, float] = {}
+        current_morphogens: MorphogenState | None = None
+        if self._folding.is_active("morphogens"):
+            try:
+                session_context: dict = {
+                    "domain": domain,
+                    "new_candidates_this_session": self._activity_stores,
+                    "query_embedding": query_embedding,
+                }
+                current_morphogens = await self._morphogens.compute_morphogens(session_context)
+                morphogen_params = self._morphogens.apply_morphogens(current_morphogens)
+            except Exception:
+                logger.debug("Morphogen computation failed — using defaults", exc_info=True)
+
+        # ------ Phase 3 step 2: Select bandit arm → apply parameter overrides ------
+        selected_arm: RetrievalArm | None = None
+        if self._folding.is_active("bandits") and current_morphogens is not None:
+            try:
+                selected_arm = self._bandits.select_arm(current_morphogens)
+                # Arm parameters override morphogen-derived values
+                for param_name, param_val in selected_arm.parameters.items():
+                    if param_name in morphogen_params:
+                        morphogen_params[param_name] = param_val
+            except Exception:
+                logger.debug("Bandit arm selection failed — skipped", exc_info=True)
+
+        # ------ Phase 3 step 3: Check system state → apply multipliers ------
+        if self._folding.is_active("states"):
+            try:
+                domain_stats = await self._domain_manager.domain_stats(domain)
+                mem_count = domain_stats.memory_count if domain_stats else 0
+                sess_count = getattr(domain_stats, "session_count", 1) if domain_stats else 1
+                session_metrics = {"query_variance": 0.0}
+                self._states.evaluate(session_metrics, mem_count, sess_count)
+                multipliers = self._states.get_parameter_multipliers()
+                for param_name, mult in multipliers.items():
+                    if param_name in morphogen_params:
+                        morphogen_params[param_name] *= mult
+            except Exception:
+                logger.debug("System state evaluation failed — skipped", exc_info=True)
+
+        # Run retrieval engine (Phase 2 extensions wired in constructor)
+        result = await self._retrieval.retrieve(query, domain, token_budget)
+
+        # Merge buffer memories at L3 (prepended, domain-filtered)
+        if buffer_ids:
+            buffer_memories = await self._storage.get_memories_by_ids(buffer_ids)
+            existing_l3_ids = {m.id for m in result.l3_memories}
+            for bm in buffer_memories:
+                if bm.id not in existing_l3_ids and bm.domain == domain:
+                    result.l3_memories.insert(0, bm)
+
+        # Update lifecycle for L3 memories
+        for mem in result.l3_memories:
+            await self._lifecycle.on_memory_retrieved(mem)
+            self._buffer.on_access(mem.id)
+            self._buffer.add_recent(mem.id)
+
+        # Track injected IDs for next turn's habituation update
+        self._last_injected_ids = [m.id for m in result.l3_memories]
+
+        logger.info(
+            "Retrieved %d L3, %d L2, %d L1 memories (domain=%s, budget=%d/%d)",
+            len(result.l3_memories), len(result.l2_memories),
+            len(result.l1_memories), domain,
+            result.token_budget_used, result.token_budget_total,
+        )
+
+        # Phase 2: Real-time danger/safety detection + store signal detection
+        store_signals: list[StoreSignal] = []
+        has_clear_feedback = False
+        feedback_positive = False
+        if user_message and result.l3_memories:
+            injected_ids = [m.id for m in result.l3_memories]
+            signals = self._danger_theory.detect_signals(
+                user_message, query_embedding, injected_ids
+            )
+            for sig in signals:
+                if sig.type == FeedbackSignalType.DANGER:
+                    has_clear_feedback = True
+                    feedback_positive = False
+                    await self._scars.create_scar(
+                        reason=sig.message[:200],
+                        subtype=str(sig.subtype),
+                        query_embedding=query_embedding,
+                        memory_ids=sig.memory_ids,
+                    )
+                    logger.debug("Created scar from danger signal: %s", sig.subtype)
+                elif sig.type == FeedbackSignalType.SAFETY:
+                    has_clear_feedback = True
+                    feedback_positive = True
+                    await self._associations.strengthen_trail(
+                        injected_ids, query_embedding
+                    )
+            store_signals = await self._store_signal_detector.detect_store_signals(
+                query, "", query_embedding
+            )
+            if store_signals:
+                result.store_suggestions = [
+                    {
+                        "subtype": str(s.subtype),
+                        "score": s.score,
+                        "text_excerpt": s.text_excerpt,
+                        "confidence": s.confidence,
+                        "suggested_intensity": s.suggested_intensity,
+                    }
+                    for s in store_signals
+                ]
+
+        # ------ Phase 3 steps 6-8: Post-retrieval feedback updates ------
+        if has_clear_feedback and result.l3_memories:
+            outcome = "positive" if feedback_positive else "negative"
+            l3_ids = [m.id for m in result.l3_memories]
+
+            # Step 6: Niche construction co-retrieval feedback
+            if self._folding.is_active("niche"):
+                try:
+                    await self._niche.on_co_retrieval_outcome(l3_ids, outcome, domain)
+                except Exception:
+                    logger.debug("Niche co-retrieval update failed", exc_info=True)
+
+            # Step 7: Bandit outcome recording
+            if self._folding.is_active("bandits") and selected_arm is not None:
+                try:
+                    self._bandits.record_outcome(feedback_positive)
+                except Exception:
+                    logger.debug("Bandit outcome recording failed", exc_info=True)
+
+            # Update system state feedback
+            if self._folding.is_active("states"):
+                if feedback_positive:
+                    self._states.on_successful_retrieval()
+                else:
+                    self._states.on_failed_retrieval()
+
+        # Phase 2: Record triples for batched judge
+        if self._session.current_session and result.l3_memories:
+            for mem in result.l3_memories:
+                has_signal = bool(
+                    user_message
+                    and any(
+                        sig.type == FeedbackSignalType.DANGER
+                        for sig in self._danger_theory.get_session_signals()
+                        if mem.id in sig.memory_ids
+                    )
+                )
+                self._judge.record_triple(
+                    memory_id=mem.id,
+                    memory_l2=mem.l2_summary,
+                    query=query,
+                    response_summary=None,
+                    has_clear_signal=has_signal,
+                )
+
+        # Record exchange count
+        if user_message:
+            self._session.record_exchange()
+
+        # Record retrieval in session
+        if self._session.current_session:
+            await self._session.record_retrieval(query, result)
+            self._activity_retrievals += 1
+            await self._maybe_flush_activity()
+
+        # ------ Phase 3 step 10: Intra-session maintenance check ------
+        if self._session.current_session:
+            try:
+                session = self._session.current_session
+                turn_count = self._activity_stores + self._activity_retrievals
+                await self._maintenance.intra_session_maintenance(
+                    session.started_at, turn_count
+                )
+            except Exception:
+                logger.debug("Intra-session maintenance check failed", exc_info=True)
+
+        return result
+
+    # -------------------------------------------------------------------
+    # Session
+    # -------------------------------------------------------------------
+
+    async def session_start(self, domain: str | None = None) -> SessionContext:
+        """Start a new session for the given domain."""
+        if domain is not None:
+            self._validate_domain(domain)
+        self._buffer.clear()
+        self._llm_tracker.reset_session()
+        self._danger_theory.reset_session()
+        self._store_signal_detector.reset_session()
+        self._judge.reset_session()
+        self._judge_ratings: list[JudgeRating] = []
+        self._last_injected_ids = []
+        self._activity_stores = 0
+        self._activity_retrievals = 0
+        # Phase 3: reset session-level state
+        self._states.reset_session()
+        self._niche.increment_session()
+        await self._check_gate_transition()
+        # Phase 3: run scheduled maintenance tiers if due
+        for tier_method, schedule in [
+            (self._maintenance.daily_maintenance, "daily"),
+            (self._maintenance.weekly_maintenance, "weekly"),
+            (self._maintenance.monthly_maintenance, "monthly"),
+        ]:
+            try:
+                if await self._maintenance.should_run_scheduled(schedule):
+                    await tier_method()
+                    logger.info("Ran %s maintenance on session_start", schedule)
+            except Exception:
+                logger.debug("%s maintenance failed — non-critical", schedule, exc_info=True)
+        # Phase 3 step 4: Load previous session's morphogen curve parameters
+        try:
+            morph_history = await self._morphogens.get_history()
+            if morph_history:
+                # Re-apply last session's morphogen state to warm up curves
+                last_state = morph_history[-1]
+                self._morphogens.apply_morphogens(last_state)
+                logger.debug("Loaded morphogen curves from previous session")
+        except Exception:
+            logger.debug("Morphogen curve loading failed — using defaults", exc_info=True)
+
+        # Phase 3 step 5: Initialize bandit state from previous session
+        # (Bandit state persists in-memory across sessions within a process;
+        # full persistence handled by maintenance scheduler serialization)
+
+        # Phase 3 step 6: Load chronic memories into working buffer
+        try:
+            chronic_mems = await self._storage.get_chronic_memories(
+                threshold=self._config.chronic_promotion_threshold,
+                min_sessions=5,
+            )
+            for cm in chronic_mems:
+                self._buffer.add_recent(cm.id)
+            if chronic_mems:
+                logger.debug("Loaded %d chronic memories into buffer", len(chronic_mems))
+        except Exception:
+            logger.debug("Chronic memory loading failed — non-critical", exc_info=True)
+
+        # Phase 3: Determine folding regime for this session
+        try:
+            stats = await self._storage.get_summary_stats()
+            total_memories = stats.get("memories", 0) if stats else 0
+            total_sessions = stats.get("sessions", 0) if stats else 0
+            converged = self._morphogens.has_converged()
+            self._folding.determine_regime(total_sessions, total_memories, converged)
+            logger.debug("Folding regime: %s", self._folding._current_regime)
+        except Exception:
+            logger.debug("Folding regime determination failed", exc_info=True)
+
+        result = await self._session.start(domain)
+        # Flush a zero-op activity row immediately so the dashboard sees a live
+        # heartbeat for the new session without waiting for the first store/retrieve.
+        await self._maybe_flush_activity()
+        return result
+
+    async def session_end(self) -> SessionSummary:
+        """End the current session, generating a summary and running cleanup.
+
+        Returns:
+            SessionSummary with LLM-generated summary, counts, and duration.
+
+        Raises:
+            RuntimeError: If no active session exists.
+        """
+        session = self._session.current_session
+        summary = await self._session.end()
+        # Clear the live activity row so the dashboard shows "no session" after end
+        if session is not None:
+            try:
+                await self._storage.delete_session_activity(session.id)
+            except Exception:
+                logger.debug("Activity cleanup failed — non-critical", exc_info=True)
+        return summary
+
+    # -------------------------------------------------------------------
+    # Direct memory ops
+    # -------------------------------------------------------------------
+
+    async def get(self, memory_id: UUID) -> Memory | None:
+        """Fetch a single memory by ID. Returns None if not found."""
+        return await self._storage.get_memory(memory_id)
+
+    async def delete(self, memory_id: UUID) -> bool:
+        """Hard-delete a memory. Returns True if a record was deleted."""
+        return await self._storage.delete_memory(memory_id)
+
+    async def pin(self, memory_id: UUID) -> None:
+        """Pin a memory: promotes to PERMANENT lifecycle and adds to buffer pinned set."""
+        await self._lifecycle.pin(memory_id)
+        self._buffer.pin(memory_id)
+
+    async def unpin(self, memory_id: UUID) -> None:
+        """Unpin a memory: reverts from PERMANENT to CONFIRMED and removes buffer pin."""
+        await self._lifecycle.unpin(memory_id)
+        self._buffer.unpin(memory_id)
+
+    async def mark_critical(self, memory_id: UUID) -> None:
+        """Mark a memory as safety-critical. Always injected, never pruned."""
+        await self._lifecycle.mark_safety_critical(memory_id)
+
+    # -------------------------------------------------------------------
+    # Phase 2: Explicit feedback API
+    # -------------------------------------------------------------------
+
+    async def correct(self, memory_id: UUID, correction: str) -> Memory | None:
+        """Explicitly correct a memory. Triggers scar creation and zoom regeneration.
+
+        - If cosine similarity between correction and existing memory > 0.5:
+          partial update — regenerate zoom levels with correction applied.
+        - Otherwise: full replacement — create new high-intensity memory.
+
+        Args:
+            memory_id: UUID of the memory to correct.
+            correction: The correction text.
+
+        Returns:
+            The updated or new Memory, or None if memory not found.
+        """
+        self._validate_text(correction, self._config.max_text_length, "Correction")
+        mem = await self._storage.get_memory(memory_id)
+        if mem is None:
+            logger.warning("correct(): memory %s not found", memory_id)
+            return None
+
+        correction_embedding = await self._embeddings.embed(correction)
+        mem_vec = np.array(mem.embedding, dtype=np.float32)
+        cor_vec = np.array(correction_embedding, dtype=np.float32)
+        mem_norm = float(np.linalg.norm(mem_vec))
+        cor_norm = float(np.linalg.norm(cor_vec))
+        similarity = 0.0
+        if mem_norm > 0 and cor_norm > 0:
+            similarity = float(np.dot(mem_vec, cor_vec) / (mem_norm * cor_norm))
+
+        # Create scar for this retrieval pattern
+        await self._scars.create_scar(
+            reason=f"Correction: {correction[:100]}",
+            subtype="correction",
+            query_embedding=mem.embedding,
+            memory_ids=[memory_id],
+        )
+
+        if similarity > 0.5:
+            # Partial correction — regenerate zoom levels
+            combined_text = f"{mem.l4_raw}\n\nCorrection: {correction}"
+            zoom = await self._zoom.generate(combined_text, mem.domain)
+            updated = Memory(
+                id=mem.id,
+                domain=mem.domain,
+                created_at=mem.created_at,
+                updated_at=datetime.utcnow(),
+                context=mem.context,
+                l0_tag=zoom.l0_tag,
+                l1_label=zoom.l1_label,
+                l2_summary=zoom.l2_summary,
+                l3_full=zoom.l3_full,
+                l4_raw=combined_text,
+                embedding=correction_embedding,
+                embedding_model=getattr(self._embeddings, "model_name", "unknown"),
+                intensity=min(1.0, mem.intensity + 0.1),
+                retrieval_count=mem.retrieval_count,
+                miss_count=mem.miss_count,
+                last_accessed=mem.last_accessed,
+                lifecycle=mem.lifecycle,
+                chronic_score=mem.chronic_score,
+                contrast=mem.contrast,
+                chain_next=mem.chain_next,
+                chain_prev=mem.chain_prev,
+                vitality=mem.vitality,
+                reconsolidation_count=mem.reconsolidation_count + 1,
+                origin=mem.origin,
+                trust_score=mem.trust_score,
+            )
+            await self._storage.update_memory(updated)
+            logger.info("Partially corrected memory %s", memory_id)
+            return updated
+        else:
+            # Full contradiction — create replacement, link via chain
+            zoom = await self._zoom.generate(correction, mem.domain)
+            now = datetime.utcnow()
+            new_memory = Memory(
+                id=uuid4(),
+                domain=mem.domain,
+                created_at=now,
+                updated_at=now,
+                context=mem.context,
+                l0_tag=zoom.l0_tag,
+                l1_label=zoom.l1_label,
+                l2_summary=zoom.l2_summary,
+                l3_full=zoom.l3_full,
+                l4_raw=correction,
+                embedding=correction_embedding,
+                embedding_model=getattr(self._embeddings, "model_name", "unknown"),
+                intensity=0.9,
+                chain_prev=memory_id,
+            )
+            await self._storage.store_memory(new_memory)
+            # Link old memory forward to new one
+            updated_old = Memory(
+                **{
+                    **mem.__dict__,
+                    "chain_next": new_memory.id,
+                    "updated_at": now,
+                }
+            )
+            await self._storage.update_memory(updated_old)
+            logger.info(
+                "Full correction: created replacement memory %s for %s",
+                new_memory.id, memory_id,
+            )
+            if self._session.current_session:
+                await self._session.record_store(new_memory.id)
+            return new_memory
+
+    async def confirm(self, memory_id: UUID) -> None:
+        """Explicitly confirm a memory is correct.
+
+        Increments retrieval count, emits safety signal, and strengthens
+        stigmergic trails on associated memories.
+
+        Args:
+            memory_id: UUID of the memory to confirm.
+        """
+        mem = await self._storage.get_memory(memory_id)
+        if mem is None:
+            logger.warning("confirm(): memory %s not found", memory_id)
+            return
+        await self._lifecycle.on_memory_retrieved(mem)
+        # Strengthen trails to neighbors
+        edges = await self._associations.get_edges(memory_id)
+        if edges:
+            neighbor_ids = [nid for nid, _ in edges]
+            dummy_embedding = mem.embedding
+            await self._associations.strengthen_trail(
+                [memory_id] + neighbor_ids[:3], dummy_embedding
+            )
+        logger.info("Confirmed memory %s", memory_id)
+
+    # -------------------------------------------------------------------
+    # Domain & task management
+    # -------------------------------------------------------------------
+
+    async def list_domains(self) -> list[DomainInfo]:
+        """List all domains with memory counts and last activity timestamps."""
+        raw = await self._storage.list_domains()
+        return [
+            DomainInfo(
+                name=name,
+                memory_count=count,
+                last_active=datetime.fromisoformat(last_updated),
+            )
+            for name, count, last_updated in raw
+        ]
+
+    async def add_task(self, description: str, priority: int = 0) -> Task:
+        """Create and persist a new task. Returns the created Task."""
+        task = Task(
+            id=uuid4(),
+            description=description,
+            created_at=datetime.utcnow(),
+            priority=priority,
+        )
+        await self._storage.store_task(task)
+        return task
+
+    async def complete_task(self, task_id: UUID) -> None:
+        """Mark a task as completed by ID."""
+        task = await self._storage.get_task(task_id)
+        if task:
+            task.status = TaskStatus.COMPLETED
+            await self._storage.update_task(task)
+
+    async def list_tasks(
+        self, status: TaskStatus | None = None
+    ) -> list[Task]:
+        """List tasks, optionally filtered by status."""
+        return await self._storage.list_tasks(status)
+
+    # -------------------------------------------------------------------
+    # Stats
+    # -------------------------------------------------------------------
+
+    async def get_stats(self) -> dict:
+        """Aggregate statistics from all subsystems into a single dict."""
+        total_memories = await self._storage.count_memories()
+        total_sessions = await self._storage.get_session_count()
+        domains_raw = await self._storage.list_domains()
+
+        # Per-domain breakdown with lifecycle distribution
+        breakdown = await self._storage.get_domain_lifecycle_breakdown()
+        domain_map: dict[str, dict[str, int]] = {}
+        for domain, lifecycle, count in breakdown:
+            domain_map.setdefault(domain, {})[lifecycle] = count
+        domains_info = [
+            {
+                "name": name,
+                "memory_count": cnt,
+                "last_active": last_updated,
+                "lifecycle": domain_map.get(name, {}),
+            }
+            for name, cnt, last_updated in domains_raw
+        ]
+
+        # Current session info
+        current_session = None
+        session = self._session.current_session
+        if session:
+            now = datetime.utcnow()
+            duration = (now - session.started_at).total_seconds()
+            current_session = {
+                "session_id": str(session.id),
+                "domain": session.domain,
+                "started_at": session.started_at.isoformat(),
+                "duration_seconds": duration,
+                "stores": len(self._session._session_memories),
+                "retrievals": len(self._session._session_retrievals),
+            }
+
+        # Recent stores
+        recent_memories = await self._storage.get_recent_memories(limit=10)
+        recent_stores = [
+            {
+                "id": str(m.id),
+                "domain": m.domain,
+                "created_at": m.created_at.isoformat(),
+                "l1_label": m.l1_label,
+                "lifecycle": m.lifecycle.value,
+            }
+            for m in recent_memories
+        ]
+
+        # Recent retrievals from current session
+        recent_retrievals = []
+        if session:
+            for r in self._session._session_retrievals[-10:]:
+                recent_retrievals.append({
+                    "query": r["query"],
+                    "l3_count": r["l3_count"],
+                    "l2_count": r["l2_count"],
+                    "l1_count": r["l1_count"],
+                })
+
+        # Lifecycle counts
+        lifecycle_counts = await self._storage.get_lifecycle_counts()
+
+        # Buffer state
+        buffer_state = {
+            "pinned": len(self._buffer._pinned),
+            "auto_promoted": len(self._buffer._auto_promoted),
+            "just_written": len(self._buffer._just_written),
+            "recent": len(self._buffer._recent),
+        }
+
+        # Phase 2: association + scar stats
+        assoc_stats = await self._associations.get_stats()
+        active_scars = await self._scars.get_active_scars()
+
+        return {
+            "overall": {
+                "total_memories": total_memories,
+                "total_sessions": total_sessions,
+                "total_domains": len(domains_raw),
+            },
+            "domains": domains_info,
+            "current_session": current_session,
+            "recent_stores": recent_stores,
+            "recent_retrievals": recent_retrievals,
+            "lifecycle": lifecycle_counts,
+            "buffer": buffer_state,
+            "associations": assoc_stats,
+            "scars": {"active_count": len(active_scars)},
+        }
+
+
+    # -------------------------------------------------------------------
+    # Phase 3: Public API additions
+    # -------------------------------------------------------------------
+
+    async def health(self) -> "HealthReport":
+        """Return the full health assessment (P3→P4 contract).
+
+        Delegates to :class:`SelfModel.health`.
+        """
+        return await self._self_model.health()
+
+    async def explain_last(self) -> "ExplanationReport":
+        """Explain the last retrieval decision (P3→P4 contract).
+
+        Delegates to :class:`SelfModel.explain_last`.
+        """
+        return await self._self_model.explain_last()
+
+
+def create_memory(config: FractalConfig | None = None) -> FractalMemory:
+    """Sync factory that initializes FractalMemory."""
+    fm = FractalMemory(config)
+    asyncio.run(fm.initialize())
+    return fm