smruti 0.1.0__tar.gz

smruti-0.1.0/.gitignore

@@ -0,0 +1,35 @@
+# Python bytecode & cache
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.pytest_cache/
+.ruff_cache/
+
+# Virtual Environment
+.venv/
+venv/
+env/
+ENV/
+
+# smruti local workspace database
+.smruti/
+.smriti/
+*.db
+*.db-wal
+*.db-shm
+
+# Tests folder
+tests/
+
+# Build artifacts
+build/
+dist/
+*.egg-info/
+*.whl
+
+# IDE & OS
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db

smruti-0.1.0/PKG-INFO

@@ -0,0 +1,56 @@
+Metadata-Version: 2.5
+Name: smruti
+Version: 0.1.0
+Summary: A Biologically Inspired, Dual-Valence Cognitive Memory Engine for Autonomous AI Agents
+License-Expression: Apache-2.0
+Requires-Python: >=3.10
+Requires-Dist: fastembed>=0.2.0
+Requires-Dist: fastmcp>=0.1.0
+Requires-Dist: numpy>=1.20.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: typer>=0.9.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.20.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# smruti (स्मृति)
+
+> **Biologically Inspired, Dual-Valence Cognitive Memory for Autonomous AI Agents**
+
+smruti equips autonomous coding and reasoning agents with an active, biological memory architecture:
+
+1. **Tier 1 (Episodic Working Stream):** Sub-millisecond, append-only SQLite WAL stream. Zero LLM latency while acting.
+2. **Tier 2 (The "Sleep" Consolidation Engine):** Periodic background distillation that strips 90% verbatim token noise into schemas and rules.
+3. **Tier 3 (Dual-Valence Cortical Mesh):**
+   - **Positive Heuristics (Tier 3A):** Verified solution paths with biological Ebbinghaus decay and Hebbian reinforcement.
+   - **Inhibitory Anti-Memories (Tier 3B):** Active preflight interception gate that prevents agents from repeating known fatal mistakes and compiler errors.
+
+---
+
+## Quickstart
+
+### Installation
+```bash
+pip install -e .
+```
+
+### CLI Inspection
+```bash
+smruti init      # Initialize .smruti/ database in your project
+smruti status    # View positive rules, anti-memories, and decay health
+smruti sleep     # Run offline consolidation over recent episodes
+smruti audit     # Inspect chronological agent trajectories
+```
+
+### MCP (Model Context Protocol) Server for Cursor / Claude Code / Antigravity
+Add to your MCP configuration (`mcpServers`):
+```json
+{
+  "smruti": {
+    "command": "smruti",
+    "args": ["mcp"]
+  }
+}
+```

smruti-0.1.0/README.md

@@ -0,0 +1,39 @@
+# smruti (स्मृति)
+
+> **Biologically Inspired, Dual-Valence Cognitive Memory for Autonomous AI Agents**
+
+smruti equips autonomous coding and reasoning agents with an active, biological memory architecture:
+
+1. **Tier 1 (Episodic Working Stream):** Sub-millisecond, append-only SQLite WAL stream. Zero LLM latency while acting.
+2. **Tier 2 (The "Sleep" Consolidation Engine):** Periodic background distillation that strips 90% verbatim token noise into schemas and rules.
+3. **Tier 3 (Dual-Valence Cortical Mesh):**
+   - **Positive Heuristics (Tier 3A):** Verified solution paths with biological Ebbinghaus decay and Hebbian reinforcement.
+   - **Inhibitory Anti-Memories (Tier 3B):** Active preflight interception gate that prevents agents from repeating known fatal mistakes and compiler errors.
+
+---
+
+## Quickstart
+
+### Installation
+```bash
+pip install -e .
+```
+
+### CLI Inspection
+```bash
+smruti init      # Initialize .smruti/ database in your project
+smruti status    # View positive rules, anti-memories, and decay health
+smruti sleep     # Run offline consolidation over recent episodes
+smruti audit     # Inspect chronological agent trajectories
+```
+
+### MCP (Model Context Protocol) Server for Cursor / Claude Code / Antigravity
+Add to your MCP configuration (`mcpServers`):
+```json
+{
+  "smruti": {
+    "command": "smruti",
+    "args": ["mcp"]
+  }
+}
+```

smruti-0.1.0/implementation.md

@@ -0,0 +1,191 @@
+# smruti (स्मृति) — Technical Implementation Specification
+
+> **A Biologically Inspired, Dual-Valence Cognitive Memory Engine for Autonomous AI Agents**
+> *Bridging fast episodic buffering, offline consolidation, inhibitory anti-memories, and synaptic decay.*
+
+---
+
+## 1. Executive Summary & Problem Space
+
+Current AI memory solutions (Cognee, Mem0, Zep, GraphRAG) approach agent memory as a relational or graph database with vector indexing bolted on. This architecture introduces severe cognitive limitations when paired with autonomous coding agents:
+
+1. **Eager Ingestion Latency:** Every turn incurs heavy chunking, multiple LLM extraction calls, and graph compilation. Writes are slow, expensive, and block the agent's reasoning loop.
+2. **Graph Bloat (Missing Consolidation):** Lacking a "sleep" or distillation phase, every casual interaction spawns noisy entity nodes (`User`, `Hello`, `Command`), rapidly cluttering graph traversal.
+3. **Absence of Negative Knowledge (Anti-Memories):** Existing engines only store positive assertions (`X is Y`). They cannot represent failure trajectories, resulting in agents repeating identical mistakes, syntax errors, or compiler dead ends across sessions.
+4. **Static Flat Weighting:** A file or note ingested months ago holds the exact same retrieval weight as a fact recalled two minutes ago. There is no biological forgetting curve or reinforcement mechanism.
+
+**smruti** replaces this paradigm with a biological, dual-valence memory engine built on three decoupled tiers.
+
+---
+
+## 2. The Tri-Tier Biological Architecture
+
+```
+┌────────────────────────────────────────────────────────────────────────┐
+│                   TIER 1: EPISODIC WORKING STREAM                     │
+│  • Sub-millisecond append (Zero LLM overhead on write)                 │
+│  • Causal trajectory: [Context] -> [Action] -> [Outcome] -> [Duration] │
+└───────────────────────────────────┬────────────────────────────────────┘
+                                    │
+                                    ▼ (Triggered "Sleep" / Consolidation)
+┌────────────────────────────────────────────────────────────────────────┐
+│                   TIER 2: THE CONSOLIDATION ENGINE                     │
+│  • Strips 90% verbatim token noise                                     │
+│  • Distills episodes into generalized rules and heuristics             │
+└───────────────────┬────────────────────────────────┬───────────────────┘
+                    │                                │
+                    ▼                                ▼
+┌──────────────────────────────────────┐ ┌───────────────────────────────┐
+│     TIER 3A: POSITIVE KNOWLEDGE      │ │   TIER 3B: INHIBITORY MEMORY  │
+│  • Verified solution paths           │ │   • Anti-memories / Dead ends │
+│  • Ebbinghaus reinforcement & decay  │ │   • Exact failure signatures  │
+│  • Spreading associative activation  │ │   • Proactive error prevention│
+└──────────────────────────────────────┘ └───────────────────────────────┘
+```
+
+### Tier 1: Episodic Working Stream (Hippocampal Buffer)
+- Append-only, transaction-safe event stream.
+- Captures actions, tool invocations, shell commands, and execution results in real time.
+- Operates at sub-millisecond latency using SQLite in Write-Ahead Logging (`WAL`) mode.
+- **Zero LLM overhead during writes.** The agent is never stalled waiting for embeddings or entity extraction.
+
+### Tier 2: Memory Consolidation Engine ("The Sleep Cycle")
+- Periodic or threshold-triggered background worker (runs during idle agent periods or session boundaries).
+- Replays recent episodic trajectories, separates verified successes from failed attempts, and prunes verbose raw text.
+- Generalizes episodes into abstract schemas and heuristics.
+- Applies biological synaptic decay sweeps across dormant memories.
+
+### Tier 3: Dual-Valence Cortical Mesh
+- **Tier 3A (Positive Excitatory Knowledge):**
+  - Stores verified solution strategies, project invariants, and architectural rules.
+  - Governed by Hebbian reinforcement: frequently recalled rules gain higher retrieval priority (`strength`).
+  - Governed by the Ebbinghaus forgetting curve: unused memories fade exponentially over time.
+- **Tier 3B (Inhibitory Anti-Memories — Vimarsha):**
+  - Stores known dead ends, syntax traps, compiler failure signatures, and environmental collisions.
+  - Active preflight gate: intercepts agent actions *before* execution if a matching failure signature is detected.
+
+---
+
+## 3. Technology Stack & Design Rationale
+
+| Component | Technology | Rationale |
+| :--- | :--- | :--- |
+| **Language** | Python 3.10+ | Native to AI agent tooling, IDE plugins, and Python packaging. |
+| **Episodic Stream (Buffer)** | **SQLite (WAL Mode)** | Zero-configuration, zero-daemon, embedded, sub-1ms ACID commits. |
+| **Embedded Graph Storage** | **SQLite Adjacency Tables / Kùzu** | In-process relational adjacency mesh with optional Kùzu backend. Zero Docker requirements. |
+| **Vector Engine (Local)** | **FastEmbed / sqlite-vec** | In-process CPU-friendly embeddings without requiring external vector microservices. |
+| **IDE Protocol Interface** | **FastMCP (Model Context Protocol)** | First-class stdio integration for Cursor, Claude Code, Antigravity, and Windsurf. |
+| **Developer CLI** | **Typer** | Intuitive terminal tool for memory inspection, manual consolidation, and system health audits. |
+
+---
+
+## 4. Package & Directory Structure
+
+```text
+smruti/
+├── pyproject.toml              # Project dependencies: fastmcp, typer, pydantic, fastembed
+├── README.md                   # Quickstart, architecture overview, and MCP configuration
+├── implementation.md           # Technical specification and mathematical/logical models
+├── tasks.md                    # Actionable task tracking and milestone progress
+├── smruti/
+│   ├── __init__.py             # Public Python API: smrutiEngine, Guard
+│   ├── config.py               # Database paths, decay half-life, thresholds
+│   ├── models.py               # Pydantic schemas (Episode, AntiMemory, Rule, Valence)
+│   ├── storage/
+│   │   ├── __init__.py
+│   │   └── db.py               # SQLite WAL mode initialization, indexing, and migrations
+│   ├── engine/
+│   │   ├── __init__.py
+│   │   ├── stream.py           # Tier 1: Sub-millisecond episodic buffer (append-only)
+│   │   ├── inhibitory.py       # Tier 3B: Exact & fuzzy failure signature matcher
+│   │   ├── cortex.py           # Tier 3A: Positive rules, associative links, synaptic decay
+│   │   └── consolidator.py     # Tier 2: "Sleep" consolidation & token pruning pipeline
+│   ├── interfaces/
+│   │   ├── __init__.py
+│   │   ├── mcp_server.py       # FastMCP Server (stdio tools for AI coding assistants)
+│   │   └── cli.py              # Typer CLI (smruti init, inspect, sleep, audit)
+└── tests/
+    ├── test_stream.py          # Sub-ms append benchmark & schema checks
+    ├── test_inhibition.py      # Preflight interception verification
+    ├── test_decay.py           # Synaptic decay & reinforcement math verification
+    ├── test_consolidation.py   # Token compression & schema distillation tests
+    └── test_mcp.py             # MCP tool invocation tests
+```
+
+---
+
+## 5. Mathematical & Algorithmic Formulation
+
+### Biological Synaptic Decay
+Memory strength degrades exponentially according to the Ebbinghaus retention model:
+
+```text
+effective_strength = base_strength * exp(-decay_rate * (current_time - last_accessed_at))
+```
+
+- When a rule is retrieved and successfully utilized by the agent:
+  - `access_count` increments by 1.
+  - `base_strength` increases (Hebbian reinforcement: `base_strength = min(1.0, base_strength + reinforcement_factor)`).
+  - `last_accessed_at` updates to `current_time`.
+- When `effective_strength` falls below `prune_threshold` (e.g. 0.15) and has not been accessed across multiple consolidation cycles, the rule is compacted or archived.
+
+### Inhibitory Matching Logic
+An inhibitory anti-memory matches an action candidate if:
+1. **Exact Signature Match:** Exact command or pattern match with a previously failed trajectory.
+2. **Contextual Collision:** Action contains known destructive flags or conflicting dependencies in the current environment context.
+3. **Regex / Error Trace Substring:** Action resembles an error-inducing command under identical project conditions.
+
+---
+
+## 6. End-to-End System Flow
+
+```
+                      [ Agent Prompt / Plan ]
+                                 │
+                                 ▼
+                     ┌───────────────────────┐
+                     │ STEP 1: PREFLIGHT     │
+                     │ INHIBITION CHECK      │
+                     └───────────┬───────────┘
+                                 │
+        ┌────────────────────────┴────────────────────────┐
+        ▼ (Match Found)                                   ▼ (Clear)
+[ INTERCEPT AGENT ]                              [ AGENT EXECUTES ACTION ]
+"Blocked: Known dead end: ..."                            │
+                                                          ▼
+                                                 ┌───────────────────────┐
+                                                 │ STEP 2: FAST EPISODIC │
+                                                 │ APPEND (Sub-1ms)      │
+                                                 └───────────┬───────────┘
+                                                             │
+                                                             ▼ (Idle / Periodic)
+                                                 ┌───────────────────────┐
+                                                 │ STEP 3: CONSOLIDATION │
+                                                 │ ("Sleep" Distillation)│
+                                                 │ Strips token noise    │
+                                                 │ Updates synaptic decay│
+                                                 └───────────┬───────────┘
+                                                             │
+                                                             ▼
+                                                 [ PERMANENT CORTICAL MESH ]
+                                                 • Positive Heuristics (Tier 3A)
+                                                 • Inhibitory Anti-Memories (Tier 3B)
+```
+
+---
+
+## 7. Delivery Interfaces
+
+### Interface A: FastMCP Server
+Equips AI IDEs (Cursor, Claude Code, Antigravity) with four native tools over stdio:
+1. `smruti_preflight_check(action, context)`: Intercepts actions before execution.
+2. `smruti_record_episode(action, outcome, status, latency_ms)`: Logs execution results into Tier 1.
+3. `smruti_recall_heuristics(query, limit)`: Injects top-weighted positive rules into working memory.
+4. `smruti_trigger_sleep()`: Runs the consolidation cycle.
+
+### Interface B: Typer CLI
+Provides developers with terminal inspection and manual management:
+- `smruti init`: Initializes `.smruti/` database in the current project root.
+- `smruti status`: Displays active positive rules, anti-memories, and decay health.
+- `smruti sleep`: Forces memory consolidation over uncompacted episodes.
+- `smruti audit`: Shows chronological trajectory logs and blocked dead ends.

smruti-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "smruti"
+version = "0.1.0"
+description = "A Biologically Inspired, Dual-Valence Cognitive Memory Engine for Autonomous AI Agents"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+dependencies = [
+    "pydantic>=2.0.0",
+    "typer>=0.9.0",
+    "fastmcp>=0.1.0",
+    "fastembed>=0.2.0",
+    "numpy>=1.20.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.20.0",
+    "ruff>=0.1.0",
+]
+
+[project.scripts]
+smruti = "smruti.interfaces.cli:app"
+
+[tool.hatch.build.targets.wheel]
+packages = ["smruti"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"

smruti-0.1.0/smruti/__init__.py

@@ -0,0 +1,34 @@
+"""
+smruti (स्मृति) - Biologically Inspired, Dual-Valence Cognitive Memory for Autonomous AI Agents.
+"""
+
+from smruti.config import SmrutiConfig, get_config, smrutiConfig
+from smruti.engine.consolidator import Consolidator
+from smruti.engine.cortex import Cortex
+from smruti.engine.inhibitory import InhibitoryGate
+from smruti.engine.stream import StreamBuffer
+from smruti.framework import Smruti, SmrutiInhibitionError, smruti, smrutiInhibitionError
+from smruti.models import ActionStatus, AntiMemory, CorticalRule, Episode, InhibitionResult
+from smruti.storage.db import DatabaseManager, get_db
+
+__version__ = "0.1.0"
+__all__ = [
+    "ActionStatus",
+    "AntiMemory",
+    "Consolidator",
+    "Cortex",
+    "CorticalRule",
+    "DatabaseManager",
+    "Episode",
+    "InhibitionResult",
+    "InhibitoryGate",
+    "Smruti",
+    "SmrutiConfig",
+    "SmrutiInhibitionError",
+    "smruti",
+    "smrutiConfig",
+    "smrutiInhibitionError",
+    "StreamBuffer",
+    "get_config",
+    "get_db",
+]

smruti-0.1.0/smruti/config.py

@@ -0,0 +1,53 @@
+"""
+config.py - Dynamic environment and runtime configuration for smruti.
+Discovers local .smruti/ directory or falls back to user home directory.
+"""
+
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass
+class smrutiConfig:
+    # Storage settings
+    db_filename: str = "smruti.db"
+    project_dir: Path = Path.cwd()
+    smruti_dir_name: str = ".smruti"
+    
+    # Biological decay parameters
+    # decay_rate: controls how fast unused rules decay over time (in hours^-1)
+    default_decay_rate: float = 0.05
+    # prune_threshold: rules with effective strength below this are archived
+    prune_threshold: float = 0.15
+    # reinforcement_boost: strength added per successful recall
+    reinforcement_boost: float = 0.15
+    
+    # Semantic & Associative Graph parameters
+    dedup_similarity_threshold: float = 0.85
+    associative_edge_threshold: float = 0.60
+    spreading_activation_factor: float = 0.25
+    embedding_model: str = "BAAI/bge-small-en-v1.5"
+
+    # Consolidation thresholds
+    consolidation_turn_interval: int = 5
+    auto_consolidate: bool = True
+    raw_retention_days: int = 7
+
+    @property
+    def smruti_dir(self) -> Path:
+        """Finds .smruti in current working directory or ancestors, else creates in cwd."""
+        current = self.project_dir.resolve()
+        for parent in [current, *current.parents]:
+            candidate = parent / self.smruti_dir_name
+            if candidate.is_dir():
+                return candidate
+        return current / self.smruti_dir_name
+
+    @property
+    def db_path(self) -> Path:
+        return self.smruti_dir / self.db_filename
+
+def get_config() -> smrutiConfig:
+    return smrutiConfig()
+
+SmrutiConfig = smrutiConfig

smruti-0.1.0/smruti/engine/__init__.py

@@ -0,0 +1,12 @@
+"""Engine modules for smruti."""
+from smruti.engine.consolidator import Consolidator
+from smruti.engine.cortex import Cortex
+from smruti.engine.inhibitory import InhibitoryGate
+from smruti.engine.stream import StreamBuffer
+
+__all__ = [
+    "Consolidator",
+    "Cortex",
+    "InhibitoryGate",
+    "StreamBuffer",
+]

smruti-0.1.0/smruti/engine/consolidator.py

@@ -0,0 +1,199 @@
+"""
+consolidator.py - Tier 2: The "Sleep" Consolidation & Distillation Engine.
+Replays raw episodic trajectories, extracts schemas and heuristics, promotes recurring
+errors into permanent inhibitory anti-memories, links causal resolution trajectories,
+and sweeps historical raw buffers and decaying cortical rules.
+"""
+
+import logging
+import re
+from collections import defaultdict
+from collections.abc import Callable
+from datetime import datetime, timezone
+from typing import Any
+
+from smruti.config import smrutiConfig, get_config
+from smruti.engine.cortex import Cortex
+from smruti.engine.inhibitory import InhibitoryGate
+from smruti.engine.llm import LLMClient
+from smruti.engine.stream import StreamBuffer
+from smruti.models import ActionStatus, Episode
+from smruti.storage.db import DatabaseManager, get_db
+
+logger = logging.getLogger(__name__)
+
+class Consolidator:
+    def __init__(
+        self,
+        db: DatabaseManager | None = None,
+        config: smrutiConfig | None = None,
+        stream: StreamBuffer | None = None,
+        inhibitory: InhibitoryGate | None = None,
+        cortex: Cortex | None = None,
+        llm_summarizer: Callable[[str, list[dict[str, Any]]], str] | None = None,
+        llm_client: LLMClient | None = None
+    ):
+        self.config = config or get_config()
+        self.db = db or get_db(self.config)
+        self.stream = stream or StreamBuffer(self.db)
+        self.inhibitory = inhibitory or InhibitoryGate(self.db)
+        self.cortex = cortex or Cortex(self.db, self.config)
+        self.llm_client = llm_client or LLMClient()
+        self.llm_summarizer = llm_summarizer
+
+    def sleep(
+        self,
+        session_id: str | None = None,
+        current_time: float | None = None,
+        project_root: str | None = None
+    ) -> dict[str, Any]:
+        """
+        Executes memory consolidation ("Sleep Cycle"):
+        1. Analyzes unconsolidated episodic trajectories.
+        2. Detects recurring failures and promotes them to Inhibitory Anti-Memories.
+        3. Discovers multi-step causal resolutions and promotes them to Cortical Rules.
+        4. Marks analyzed episodes as consolidated (idempotent execution).
+        5. Enforces raw_retention_days cleanup on old consolidated episodes.
+        6. Sweeps decaying dormant rules.
+        """
+        now = current_time or datetime.now(timezone.utc).timestamp()
+        
+        # 1. Fetch only unconsolidated episodes
+        unconsolidated = self.stream.get_unconsolidated(limit=200, session_id=session_id)
+        if not unconsolidated:
+            # Still perform maintenance sweeps even if no new episodes
+            pruned_rules = self.cortex.prune_decayed_rules(current_time=now)
+            pruned_raw = self.stream.prune_older_than(
+                self.config.raw_retention_days * 86400.0,
+                only_consolidated=True
+            )
+            return {
+                "processed_episodes": 0,
+                "promoted_anti_memories": 0,
+                "promoted_positive_rules": 0,
+                "pruned_decayed_rules": pruned_rules,
+                "pruned_raw_episodes": pruned_raw,
+                "timestamp": now
+            }
+
+        episodes = sorted(unconsolidated, key=lambda e: e.timestamp)
+        promoted_anti_memories = 0
+        promoted_rules = 0
+
+        # 2. Analyze failure repetitions with normalized command & error clustering
+        failure_clusters: dict[str, list[Episode]] = defaultdict(list)
+        for ep in episodes:
+            if ep.status in [ActionStatus.FAILURE, ActionStatus.ERROR]:
+                cluster_key = self._extract_cluster_key(ep.action)
+                failure_clusters[cluster_key].append(ep)
+
+        for cluster_key, cluster in failure_clusters.items():
+            if len(cluster) >= 2:
+                # Recurring failure pattern detected -> promote to anti-memory
+                first_ep = cluster[0]
+                sig = f"recurring_failure_{self._slugify(cluster_key)}"
+                
+                # Check for project scoping in episode metadata or parameter
+                ep_proj = project_root or first_ep.metadata.get("project_root")
+                
+                cluster_data = [
+                    {"action": e.action, "result": e.result[:200], "context": e.context}
+                    for e in cluster
+                ]
+                if self.llm_summarizer:
+                    try:
+                        reason = self.llm_summarizer("failure_summary", cluster_data)
+                    except Exception as e:
+                        logger.warning("LLM summarizer failed: %s; falling back to heuristic", e)
+                        reason = f"Command '{cluster_key}' failed {len(cluster)} times. Sample error: {first_ep.result[:120]}"
+                elif self.llm_client.is_configured():
+                    reason = self.llm_client.summarize_failure_cluster(cluster_data)
+                else:
+                    sample_err = first_ep.result.strip().split("\n")[-1][:120] if first_ep.result else "Non-zero exit code"
+                    reason = f"Command pattern '{cluster_key}' failed {len(cluster)} times. Error: {sample_err}"
+
+                self.inhibitory.record_anti_memory(
+                    signature=sig,
+                    pattern=cluster_key,
+                    reason=reason,
+                    suggested_fix="Check prerequisites and inspect command arguments.",
+                    severity="high",
+                    project_root=ep_proj
+                )
+                promoted_anti_memories += 1
+
+        # 3. Multi-Step Causal Discovery (Window of up to 4 episodes)
+        # Finds a failure followed by a subsequent resolution in the same session
+        processed_pairs = set()
+        for i in range(len(episodes)):
+            curr_ep = episodes[i]
+            if curr_ep.status not in [ActionStatus.FAILURE, ActionStatus.ERROR]:
+                continue
+
+            # Look ahead up to 4 steps for a successful resolution
+            lookahead_limit = min(len(episodes), i + 5)
+            for j in range(i + 1, lookahead_limit):
+                succ_ep = episodes[j]
+                if succ_ep.status == ActionStatus.SUCCESS and succ_ep.session_id == curr_ep.session_id:
+                    pair_key = (curr_ep.action.strip(), succ_ep.action.strip())
+                    if pair_key in processed_pairs:
+                        break
+                    processed_pairs.add(pair_key)
+
+                    # Distill causal heuristic
+                    transitions = [{"failed_action": curr_ep.action, "error": curr_ep.result[:150], "fix_action": succ_ep.action}]
+                    if self.llm_summarizer:
+                        try:
+                            rule_text = self.llm_summarizer("causal_resolution", transitions)
+                        except Exception:
+                            rule_text = f"When '{curr_ep.action}' fails, use '{succ_ep.action}' instead."
+                    elif self.llm_client.is_configured():
+                        rule_text = self.llm_client.distill_resolution_heuristic(transitions)
+                    else:
+                        rule_text = f"When '{curr_ep.action}' fails, use '{succ_ep.action}' instead."
+
+                    self.cortex.add_rule(
+                        rule_text=rule_text,
+                        category="problem_resolution",
+                        confidence=0.9,
+                        base_strength=0.9,
+                        source_episode_ids=[curr_ep.id, succ_ep.id]
+                    )
+                    promoted_rules += 1
+                    break  # Found the resolution for curr_ep
+
+        # 4. Mark all processed episodes as consolidated
+        ep_ids = [e.id for e in episodes]
+        self.stream.mark_consolidated(ep_ids, now)
+
+        # 5. Raw retention cleanup: prune historical episodes older than retention limit
+        retention_seconds = self.config.raw_retention_days * 86400.0
+        pruned_raw = self.stream.prune_older_than(retention_seconds, only_consolidated=True)
+
+        # 6. Sweep biologically decayed rules
+        pruned_rules = self.cortex.prune_decayed_rules(current_time=now)
+
+        return {
+            "processed_episodes": len(episodes),
+            "promoted_anti_memories": promoted_anti_memories,
+            "promoted_positive_rules": promoted_rules,
+            "pruned_decayed_rules": pruned_rules,
+            "pruned_raw_episodes": pruned_raw,
+            "timestamp": now
+        }
+
+    @staticmethod
+    def _extract_cluster_key(action: str) -> str:
+        """Extracts normalized command or pattern key from action string."""
+        tokens = action.strip().split()
+        if not tokens:
+            return "unknown"
+        # If multi-word command like "pip install" or "npm run" or "git push", group top 2 words
+        if len(tokens) >= 2 and tokens[0].lower() in {"pip", "npm", "git", "docker", "yarn", "cargo", "pnpm", "poetry", "uv"}:
+            return f"{tokens[0]} {tokens[1]}"
+        return tokens[0]
+
+    @staticmethod
+    def _slugify(text: str) -> str:
+        """Creates safe alphanumeric identifier."""
+        return re.sub(r"[^a-zA-Z0-9_]+", "_", text).strip("_").lower()