remagent 1.0.0__py3-none-any.whl

remagent/__init__.py

@@ -0,0 +1,40 @@
+"""
+RemAgent: Autonomous Zero-Vector Memory Framework for AI Agents.
+Powered by Google Gemini and biological sleep/REM consolidation principles.
+"""
+
+from remagent.schemas import (
+    Fact,
+    OperationalRule,
+    DreamConsolidationResult,
+    RawTurnLog,
+    MemoryProfile,
+    ContradictionResolution,
+)
+from remagent.storage.base import StorageAdapter
+from remagent.storage.sqlite import SQLiteStorageAdapter
+from remagent.storage.firestore import FirestoreStorageAdapter
+from remagent.engine.synthesizer import DreamSynthesizer
+from remagent.daemon import DreamDaemon
+from remagent.governor import TokenBudgetGovernor
+from remagent.decay import MemoryDecayEngine
+from remagent.integrations.hermes import HermesMemoryConnector, RemAgentTool
+
+__version__ = "1.0.0"
+__all__ = [
+    "Fact",
+    "OperationalRule",
+    "DreamConsolidationResult",
+    "RawTurnLog",
+    "MemoryProfile",
+    "ContradictionResolution",
+    "StorageAdapter",
+    "SQLiteStorageAdapter",
+    "FirestoreStorageAdapter",
+    "DreamSynthesizer",
+    "DreamDaemon",
+    "TokenBudgetGovernor",
+    "MemoryDecayEngine",
+    "HermesMemoryConnector",
+    "RemAgentTool",
+]

remagent/cli.py

@@ -0,0 +1,305 @@
+"""
+Command-line interface for the RemAgent framework.
+"""
+
+import argparse
+import asyncio
+import json
+import os
+import sys
+from remagent.daemon import ConsolidationBusyError, DreamDaemon
+from remagent.decay import MemoryDecayEngine
+from remagent.doctor import run_doctor
+from remagent.export import ExportError, default_out_dir, export_markdown
+from remagent.schemas import current_utc_iso
+from remagent.engine.synthesizer import DreamSynthesizer
+from remagent.schemas import RawTurnLog
+from remagent.storage.sqlite import SQLiteStorageAdapter
+from remagent.governor import GovernorBudgetError, TokenBudgetGovernor
+from remagent.integrations.claude_hooks import detect_native_auto_memory, generate_claude_configuration
+
+
+def _default_db() -> str:
+    """--db default: REMAGENT_DB env var wins, else remagent_memory.db in CWD."""
+    return os.environ.get("REMAGENT_DB", "remagent_memory.db")
+
+
+def _default_agent(fallback: str = "default_agent") -> str:
+    """--agent default: REMAGENT_AGENT env var wins, else the command's fallback."""
+    return os.environ.get("REMAGENT_AGENT", fallback)
+
+
+async def run_cli():
+    parser = argparse.ArgumentParser(
+        prog="remagent",
+        description="RemAgent: Autonomous Zero-Vector Memory Framework for AI Agents",
+    )
+    subparsers = parser.add_subparsers(dest="command", help="Sub-commands")
+
+    # Command: dream
+    dream_parser = subparsers.add_parser("dream", help="Trigger an immediate REM consolidation cycle")
+    dream_parser.add_argument("--db", default=_default_db(), help="SQLite database path (env: REMAGENT_DB)")
+    dream_parser.add_argument("--agent", default=_default_agent(), help="Agent identifier (env: REMAGENT_AGENT)")
+    dream_parser.add_argument(
+        "--export-md", nargs="?", const="", default=None, metavar="DIR",
+        help="After a successful dream, regenerate the markdown mirror (default DIR: <db>_md)",
+    )
+
+    # Command: status
+    status_parser = subparsers.add_parser("status", help="Inspect active memory profile and consolidated facts")
+    status_parser.add_argument("--db", default=_default_db(), help="SQLite database path (env: REMAGENT_DB)")
+    status_parser.add_argument("--agent", default=_default_agent(), help="Agent identifier (env: REMAGENT_AGENT)")
+
+    # Command: recall
+    recall_parser = subparsers.add_parser("recall", help="Recall consolidated memory and active directives")
+    recall_parser.add_argument("--format", choices=["injection", "json"], default="injection", help="Output format")
+    recall_parser.add_argument("--query", default=None, help="Query context for fact relevance filtering")
+    recall_parser.add_argument("--agent", default=_default_agent(), help="Agent identifier (env: REMAGENT_AGENT)")
+    recall_parser.add_argument("--max-tokens", type=int, default=6000, help="Maximum token budget for prompt injection")
+    recall_parser.add_argument("--db", default=_default_db(), help="SQLite database path (env: REMAGENT_DB)")
+
+    # Command: log
+    log_parser = subparsers.add_parser("log", help="Append a raw interaction turn into the memory buffer")
+    log_parser.add_argument("--role", choices=["user", "assistant", "system", "tool"], required=True, help="Turn role")
+    log_parser.add_argument("--content", required=True, help="Turn message content")
+    log_parser.add_argument("--session", default="default_session", help="Session ID")
+    log_parser.add_argument("--db", default=_default_db(), help="SQLite database path (env: REMAGENT_DB)")
+
+    # Command: export
+    export_parser = subparsers.add_parser("export", help="Export memory as a human-readable mirror")
+    export_parser.add_argument("--markdown", action="store_true", help="Markdown format (currently the only format)")
+    export_parser.add_argument("--db", default=_default_db(), help="SQLite database path (env: REMAGENT_DB)")
+    export_parser.add_argument("--agent", default=_default_agent(), help="Agent identifier (env: REMAGENT_AGENT)")
+    export_parser.add_argument("--out", default=None, help="Output directory (default: <db>_md next to the database)")
+
+    # Command: decay
+    decay_parser = subparsers.add_parser("decay", help="Apply Ebbinghaus temporal decay to stored facts")
+    decay_parser.add_argument("--db", default=_default_db(), help="SQLite database path (env: REMAGENT_DB)")
+    decay_parser.add_argument("--agent", default=_default_agent(), help="Agent identifier (env: REMAGENT_AGENT)")
+    decay_parser.add_argument("--half-life-days", type=float, default=30.0, help="Confidence half-life in days")
+    decay_parser.add_argument("--floor", type=float, default=0.20, help="Confidence floor below which facts are deactivated")
+
+    # Command: doctor
+    doctor_parser = subparsers.add_parser("doctor", help="Read-only self-audit of the memory pipeline")
+    doctor_parser.add_argument("--db", default=_default_db(), help="SQLite database path (env: REMAGENT_DB)")
+    doctor_parser.add_argument("--agent", default=_default_agent(), help="Agent identifier (env: REMAGENT_AGENT)")
+    doctor_parser.add_argument("--max-queue", type=int, default=100, help="Max acceptable unconsolidated turns")
+    doctor_parser.add_argument("--max-dream-age-hours", type=float, default=24.0, help="Max hours since last dream when turns are queued")
+    doctor_parser.add_argument("--json", action="store_true", help="Emit one JSON object instead of text")
+
+    # Command: soak
+    soak_parser = subparsers.add_parser("soak", help="Plain-English verdict on the 7-day soak")
+    soak_parser.add_argument("--config", default="~/.remagent/soak_config.json", help="Soak config path")
+    soak_parser.add_argument("--today", default=None, help=argparse.SUPPRESS)  # test hook: YYYY-MM-DD
+
+    # Command: init-claude
+    init_claude_parser = subparsers.add_parser("init-claude", help="Scaffold Claude Code hooks and settings.json")
+    init_claude_parser.add_argument("--dir", default=".", help="Target workspace directory")
+    init_claude_parser.add_argument("--db", default=_default_db(), help="SQLite database path (env: REMAGENT_DB)")
+    init_claude_parser.add_argument("--agent", default=_default_agent("claude_code"), help="Agent identifier (env: REMAGENT_AGENT)")
+    init_claude_parser.add_argument("--force", action="store_true", help="Overwrite existing configuration and hooks")
+
+    args = parser.parse_args()
+
+    if not args.command:
+        parser.print_help()
+        return
+
+    if args.command == "init-claude":
+        # Detect BEFORE scaffolding so pre-existing settings are what's read.
+        native_state, native_detail = detect_native_auto_memory(args.dir)
+        results = generate_claude_configuration(
+            target_dir=args.dir,
+            db_path=args.db,
+            agent_id=args.agent,
+            force=args.force,
+        )
+        print("🧠 [RemAgent] Claude Code Integration Scaffolding:")
+        for path, status in results.items():
+            print(f"   • {path}: {status}")
+        print("\n✨ Claude Code is now wired to RemAgent memory!")
+        print("   - SessionStart hook: Pre-loads active rules & knowledge into context.")
+        print("   - Stop hook: Runs background REM sleep consolidation when work completes.")
+        print("   - MCP server: Exposes remagent_recall, remagent_log, and remagent_dream tools.")
+        if native_state == "disabled":
+            print(f"\nℹ️  Native Claude Code auto-memory appears DISABLED ({native_detail}).")
+            print("   RemAgent will be the only memory layer for this repo.")
+        else:
+            qualifier = "is ACTIVE" if native_state == "active" else "may be active"
+            print(f"\nℹ️  Native Claude Code auto-memory (Auto Dream) {qualifier} ({native_detail}).")
+            print("   The two are complementary: native handles this repo's own markdown memory;")
+            print("   RemAgent adds a cross-agent shared brain on top (one database reachable from")
+            print("   Claude Code, Gemini, and any MCP host).")
+        return
+
+    if args.command == "soak":
+        from remagent.soak import run_soak_report
+        code, report = run_soak_report(config_path=args.config, today=args.today)
+        print(report)
+        if code != 0:
+            sys.exit(code)
+        return
+
+    if args.command == "export":
+        # Read-only like doctor: must never create the DB it mirrors.
+        if not args.markdown:
+            print("❌ FAILED: specify a format — currently only --markdown is supported.", file=sys.stderr)
+            sys.exit(2)
+        out_dir = args.out or default_out_dir(args.db)
+        try:
+            written = export_markdown(db_path=args.db, agent_id=args.agent, out_dir=out_dir)
+        except ExportError as exc:
+            print(f"❌ FAILED: markdown export did not complete: {exc}", file=sys.stderr)
+            print("   Nothing was written.", file=sys.stderr)
+            sys.exit(1)
+        print(f"📝 [RemAgent] Memory mirror written: {len(written)} file(s) in {out_dir}")
+        for path in written:
+            print(f"   • {os.path.basename(path)}")
+        return
+
+    if args.command == "doctor":
+        # Runs before any storage initialization: doctor is strictly
+        # read-only and must never create the database it is auditing.
+        results = run_doctor(
+            db_path=args.db,
+            agent_id=args.agent,
+            max_queue=args.max_queue,
+            max_dream_age_hours=args.max_dream_age_hours,
+        )
+        ok = all(r.passed for r in results)
+        if args.json:
+            print(json.dumps({
+                "ok": ok,
+                "timestamp": current_utc_iso(),
+                "db": args.db,
+                "agent": args.agent,
+                "checks": [{"name": r.name, "passed": r.passed, "detail": r.detail} for r in results],
+            }))
+        else:
+            print(f"🩺 [RemAgent Doctor] db={args.db} agent={args.agent}")
+            for r in results:
+                print(f"   {'✅' if r.passed else '❌'} {r.name}: {r.detail}")
+            print("   → ALL CHECKS PASSED" if ok else "   → DOCTOR FAILED: pipeline needs attention")
+        if not ok:
+            sys.exit(1)
+        return
+
+    storage = SQLiteStorageAdapter(db_path=args.db)
+    await storage.initialize()
+
+    try:
+        if args.command == "dream":
+            print("🧠 [RemAgent] Initiating REM Sleep Consolidation Cycle...")
+            synthesizer = DreamSynthesizer()
+            daemon = DreamDaemon(storage=storage, synthesizer=synthesizer, agent_id=args.agent)
+            try:
+                result = await daemon.consolidate_now()
+            except ConsolidationBusyError as exc:
+                print(f"⏳ BUSY: {exc}", file=sys.stderr)
+                sys.exit(2)
+            except Exception as exc:
+                print(f"❌ FAILED: REM consolidation did not complete: {exc}", file=sys.stderr)
+                print("   No facts were written; unconsolidated turns remain queued for retry.", file=sys.stderr)
+                sys.exit(1)
+            if result:
+                print(f"✨ Consolidation Complete! Run ID: {result.run_id}")
+                print(f"   - Added Facts: {len(result.added_facts)}")
+                print(f"   - Updated Rules: {len(result.updated_rules)}")
+                print(f"   - Pruned Noise Items: {result.pruned_noise_count}")
+                print(f"   - Token Savings: ~{result.estimated_token_savings} tokens")
+                print(f"   - Cognitive Reasoning: {result.reasoning_summary}")
+                if args.export_md is not None:
+                    out_dir = args.export_md or default_out_dir(args.db)
+                    try:
+                        written = export_markdown(db_path=args.db, agent_id=args.agent, out_dir=out_dir)
+                        print(f"📝 Memory mirror regenerated: {len(written)} file(s) in {out_dir}")
+                    except ExportError as exc:
+                        # The consolidation itself persisted; the mirror did not.
+                        print(f"❌ FAILED: consolidation succeeded but markdown export failed: {exc}", file=sys.stderr)
+                        sys.exit(1)
+            else:
+                print("💤 No unconsolidated turns found. Agent memory is already fully consolidated.")
+
+        elif args.command == "status":
+            profile = await storage.load_memory_profile(agent_id=args.agent)
+            print(f"📊 [RemAgent Profile: {profile.agent_id}]")
+            print(f"   Last Dream: {profile.last_dream_at or 'Never'}")
+            print(f"   Total Pruned Turns: {profile.total_pruned_turns}")
+            print(f"\n📌 Active Facts ({len([f for f in profile.facts if f.is_active])}):")
+            for f in profile.facts:
+                if f.is_active:
+                    print(f"   • {f.entity}.{f.attribute} = {f.value} (conf: {f.confidence})")
+            print(f"\n📜 Operational Directives & Rules ({len([r for r in profile.rules if r.is_active])}):")
+            for r in profile.rules:
+                if r.is_active:
+                    print(f"   • [{r.category.upper()}] P{r.priority}: {r.rule}")
+
+        elif args.command == "recall":
+            profile = await storage.load_memory_profile(agent_id=args.agent)
+            if args.format == "json":
+                active_facts = [f.model_dump() for f in profile.facts if f.is_active]
+                active_rules = [r.model_dump() for r in profile.rules if r.is_active]
+                print(json.dumps({
+                    "agent_id": args.agent,
+                    "facts": active_facts,
+                    "rules": active_rules,
+                    "last_dream_at": profile.last_dream_at,
+                }, indent=2))
+            else:
+                governor = TokenBudgetGovernor(default_max_tokens=args.max_tokens)
+                try:
+                    injection = governor.build_budgeted_prompt_injection(
+                        profile=profile,
+                        query_context=args.query,
+                        max_tokens=args.max_tokens,
+                    )
+                except GovernorBudgetError as exc:
+                    print(f"❌ FAILED: recall injection could not be built: {exc}", file=sys.stderr)
+                    sys.exit(1)
+                if injection:
+                    print(injection)
+                else:
+                    print("[No active memory facts or rules found]")
+
+        elif args.command == "decay":
+            try:
+                profile = await storage.load_memory_profile(agent_id=args.agent)
+                if not profile.facts and not profile.rules and profile.last_dream_at is None:
+                    print(
+                        f"❌ FAILED: no memory profile found for agent '{args.agent}' in {args.db}.",
+                        file=sys.stderr,
+                    )
+                    sys.exit(1)
+                engine = MemoryDecayEngine(
+                    half_life_days=args.half_life_days,
+                    min_confidence_floor=args.floor,
+                )
+                updated_profile, pruned = engine.apply_decay(profile)
+                # Persist only after a fully successful decay pass.
+                await storage.save_memory_profile(updated_profile)
+            except Exception as exc:
+                print(f"❌ FAILED: decay pass did not complete: {exc}", file=sys.stderr)
+                print("   No changes were persisted.", file=sys.stderr)
+                sys.exit(1)
+            active_count = len([f for f in updated_profile.facts if f.is_active])
+            print(f"🍂 [RemAgent] Decay pass complete for agent '{args.agent}'.")
+            print(f"   - Half-life: {args.half_life_days} days | Confidence floor: {args.floor}")
+            print(f"   - Facts deactivated this pass: {len(pruned)}")
+            for f in pruned:
+                print(f"     • {f.entity}.{f.attribute} (confidence decayed below floor)")
+            print(f"   - Active facts remaining: {active_count}")
+
+        elif args.command == "log":
+            turn = RawTurnLog(session_id=args.session, role=args.role, content=args.content)
+            await storage.save_turn(turn)
+            print(f"📥 Logged raw turn {turn.turn_id} to buffer.")
+    finally:
+        await storage.close()
+
+
+def main():
+    asyncio.run(run_cli())
+
+
+if __name__ == "__main__":
+    main()

remagent/daemon.py

@@ -0,0 +1,274 @@
+"""
+DreamDaemon: Autonomous background worker for RemAgent.
+Monitors agent activity, triggers biological sleep / REM consolidation cycles during idle windows,
+and commits consolidated structured memory to storage.
+"""
+
+import asyncio
+import logging
+import time
+from typing import Callable, Coroutine, List, Optional
+from datetime import datetime, timezone
+
+from remagent.schemas import (
+    Fact,
+    MemoryProfile,
+    DreamConsolidationResult,
+    current_utc_iso,
+)
+from remagent.storage.base import StorageAdapter
+from remagent.engine.synthesizer import DreamSynthesizer
+
+logger = logging.getLogger("remagent.daemon")
+
+
+class ConsolidationBusyError(RuntimeError):
+    """
+    Raised when a consolidation cycle is already in progress. This is NOT
+    "memory is up to date": unconsolidated turns remain queued and untouched.
+    Callers must report busy as busy and retry after the running cycle ends.
+    """
+
+
+class DreamDaemon:
+    """
+    Background daemon that runs autonomous REM consolidation passes
+    when the agent is idle or when explicitly triggered.
+    """
+
+    def __init__(
+        self,
+        storage: StorageAdapter,
+        synthesizer: Optional[DreamSynthesizer] = None,
+        agent_id: str = "default_agent",
+        idle_threshold_seconds: float = 30.0,
+        check_interval_seconds: float = 5.0,
+        min_turns_to_dream: int = 1,
+        on_dream_completed: Optional[Callable[[DreamConsolidationResult], Coroutine]] = None,
+    ):
+        self.storage = storage
+        self.synthesizer = synthesizer or DreamSynthesizer()
+        self.agent_id = agent_id
+        self.idle_threshold_seconds = idle_threshold_seconds
+        self.check_interval_seconds = check_interval_seconds
+        self.min_turns_to_dream = min_turns_to_dream
+        self.on_dream_completed = on_dream_completed
+
+        self._last_activity_time: float = time.time()
+        self._is_running: bool = False
+        self._is_dreaming: bool = False
+        self._task: Optional[asyncio.Task] = None
+        self._lock = asyncio.Lock()
+
+    def record_activity(self) -> None:
+        """Call whenever user or agent interacts to reset idle countdown."""
+        self._last_activity_time = time.time()
+
+    @property
+    def is_idle(self) -> bool:
+        return (time.time() - self._last_activity_time) >= self.idle_threshold_seconds
+
+    @property
+    def idle_seconds(self) -> float:
+        return time.time() - self._last_activity_time
+
+    @property
+    def is_dreaming(self) -> bool:
+        return self._is_dreaming
+
+    async def start(self) -> None:
+        """Start the background daemon loop."""
+        if self._is_running:
+            return
+        self._is_running = True
+        await self.storage.initialize()
+        self._task = asyncio.create_task(self._daemon_loop())
+        logger.info(f"RemAgent DreamDaemon started for agent '{self.agent_id}' (idle threshold: {self.idle_threshold_seconds}s)")
+
+    async def stop(self) -> None:
+        """Stop background daemon gracefully."""
+        self._is_running = False
+        if self._task and not self._task.done():
+            self._task.cancel()
+            try:
+                await self._task
+            except asyncio.CancelledError:
+                pass
+        logger.info(f"RemAgent DreamDaemon stopped for agent '{self.agent_id}'")
+
+    async def _daemon_loop(self) -> None:
+        while self._is_running:
+            try:
+                await asyncio.sleep(self.check_interval_seconds)
+                if not self._is_running:
+                    break
+
+                if self.is_idle and not self._is_dreaming:
+                    # Check if there are unconsolidated turns
+                    turns = await self.storage.get_unconsolidated_turns(limit=50)
+                    if len(turns) >= self.min_turns_to_dream:
+                        logger.info(f"Idle detected ({self.idle_seconds:.1f}s). Triggering REM consolidation for {len(turns)} turns.")
+                        await self.consolidate_now()
+
+            except asyncio.CancelledError:
+                break
+            except ConsolidationBusyError:
+                logger.debug("Skipped scheduled consolidation: a cycle is already in progress.")
+            except Exception as e:
+                logger.error(f"Error in DreamDaemon loop: {e}", exc_info=True)
+
+    async def consolidate_now(self) -> Optional[DreamConsolidationResult]:
+        """
+        Forces an immediate REM consolidation pass regardless of idle timer.
+
+        Returns None ONLY when there are no unconsolidated turns (memory is
+        genuinely up to date). Raises ConsolidationBusyError when another
+        cycle is already running — turns remain queued in that case.
+        """
+        if self._is_dreaming or self._lock.locked():
+            raise ConsolidationBusyError(
+                "A REM consolidation cycle is already in progress; "
+                "unconsolidated turns remain queued. Retry shortly."
+            )
+
+        async with self._lock:
+            self._is_dreaming = True
+            try:
+                # 1. Fetch pending turns
+                unconsolidated = await self.storage.get_unconsolidated_turns(limit=100)
+                if not unconsolidated:
+                    logger.debug("No turns to consolidate.")
+                    return None
+
+                # 2. Load existing profile
+                profile = await self.storage.load_memory_profile(agent_id=self.agent_id)
+
+                # 3. Run Gemini Dream Synthesizer
+                result = await self.synthesizer.consolidate_window(
+                    unconsolidated_turns=unconsolidated,
+                    existing_profile=profile,
+                )
+
+                # A failed or fabricated synthesis must never be persisted:
+                # no facts, no profile update, and turns stay unconsolidated
+                # so they are reprocessed on the next dream cycle.
+                if result.is_fallback or result.error:
+                    raise RuntimeError(
+                        f"Dream synthesis returned a failure result "
+                        f"(is_fallback={result.is_fallback}, error={result.error}); "
+                        f"refusing to persist memory or mark turns consolidated."
+                    )
+
+                # 4. Resolve contradictions. The replacing fact is determined
+                # (or materialized) BEFORE the existing graph is touched, so
+                # every deactivated fact records the ID of the fact that
+                # superseded it. The daemon must stay correct even when the
+                # model returns an unexpected shape: an update must never
+                # leave the entity/attribute without an active fact.
+                def _find_replacement(entity: str, attribute: str) -> Optional[Fact]:
+                    for f in result.added_facts:
+                        if (
+                            f.is_active
+                            and f.entity.lower() == entity.lower()
+                            and f.attribute.lower() == attribute.lower()
+                        ):
+                            return f
+                    return None
+
+                for resolution in result.contradiction_resolutions:
+                    replacement = _find_replacement(resolution.entity, resolution.attribute)
+                    if replacement is None:
+                        logger.warning(
+                            f"Synthesizer resolved contradiction on "
+                            f"{resolution.entity}.{resolution.attribute} without emitting a "
+                            f"replacement in added_facts; materializing active fact from "
+                            f"new_value={resolution.new_value!r}."
+                        )
+                        replacement = Fact(
+                            entity=resolution.entity,
+                            attribute=resolution.attribute,
+                            value=resolution.new_value,
+                            confidence=1.0,
+                            source_turn_ids=list(result.consolidated_turn_ids),
+                            is_active=True,
+                        )
+                        result.added_facts.append(replacement)
+
+                    # Deactivate the pre-existing facts, pointing each at the
+                    # fact that replaced it (added_facts are not yet appended,
+                    # so the replacement itself cannot be deactivated here).
+                    for fact in profile.facts:
+                        if (
+                            fact.entity.lower() == resolution.entity.lower()
+                            and fact.attribute.lower() == resolution.attribute.lower()
+                            and fact.is_active
+                        ):
+                            fact.is_active = False
+                            fact.superseded_by = replacement.id
+
+                # 5. Append new active facts
+                for new_fact in result.added_facts:
+                    profile.facts.append(new_fact)
+
+                def _has_active_fact(entity: str, attribute: str) -> bool:
+                    return any(
+                        f.is_active
+                        and f.entity.lower() == entity.lower()
+                        and f.attribute.lower() == attribute.lower()
+                        for f in profile.facts
+                    )
+
+                # 5c. Invariant: after applying contradictions, every resolved
+                # entity/attribute must have an active fact. A deactivated fact
+                # with no active replacement means memory was erased, not
+                # updated — fail the run instead of committing that state.
+                for resolution in result.contradiction_resolutions:
+                    if not _has_active_fact(resolution.entity, resolution.attribute):
+                        raise RuntimeError(
+                            f"Memory-erasure invariant violated: "
+                            f"{resolution.entity}.{resolution.attribute} was superseded but has "
+                            f"no active replacement fact. Refusing to persist; turns remain "
+                            f"unconsolidated for retry."
+                        )
+
+                # 6. Update or append operational rules
+                existing_rule_map = {r.rule.lower(): r for r in profile.rules}
+                for new_rule in result.updated_rules:
+                    if new_rule.rule.lower() in existing_rule_map:
+                        existing_rule_map[new_rule.rule.lower()].priority = new_rule.priority
+                        existing_rule_map[new_rule.rule.lower()].rationale = new_rule.rationale
+                        existing_rule_map[new_rule.rule.lower()].updated_at = current_utc_iso()
+                    else:
+                        profile.rules.append(new_rule)
+
+                # 7. Update profile metadata
+                profile.total_pruned_turns += result.pruned_noise_count
+                profile.last_dream_at = result.timestamp
+
+                # 8. Save updated profile & mark turns consolidated
+                await self.storage.save_memory_profile(profile)
+                await self.storage.mark_turns_consolidated(result.consolidated_turn_ids)
+                await self.storage.record_consolidation_audit(result, agent_id=self.agent_id)
+
+                logger.info(
+                    f"REM consolidation finished. Added {len(result.added_facts)} facts, "
+                    f"updated {len(result.updated_rules)} rules, pruned {result.pruned_noise_count} noise items. "
+                    f"Estimated savings: {result.estimated_token_savings} tokens."
+                )
+
+                # Reset activity clock so it doesn't dream in a tight loop
+                self.record_activity()
+
+                if self.on_dream_completed:
+                    try:
+                        await self.on_dream_completed(result)
+                    except Exception as cb_err:
+                        logger.warning(f"Error in on_dream_completed callback: {cb_err}")
+
+                return result
+
+            except Exception as e:
+                logger.error(f"Failed to execute REM consolidation: {e}", exc_info=True)
+                raise
+            finally:
+                self._is_dreaming = False