agentic-flow 1.9.0 → 1.9.1

package/docs/releases/archive/GITHUB-ISSUE-ADDENDUM-v1.4.6.md

@@ -1,1529 +0,0 @@
-# 🚀 ReasoningBank v1.4.6 - Additional Technical Details & Advanced Topics
-
-This addendum provides deeper technical insights, architectural patterns, and advanced use cases for ReasoningBank.
-
----
-
-## 🏗️ Architecture Deep Dive
-
-### System Architecture Diagram
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                        APPLICATION LAYER                         │
-│  ┌───────────┐  ┌───────────┐  ┌───────────┐  ┌──────────────┐│
-│  │ CLI Tools │  │  SDK API  │  │  Hooks    │  │ MCP Server   ││
-│  └─────┬─────┘  └─────┬─────┘  └─────┬─────┘  └──────┬───────┘│
-└────────┼──────────────┼──────────────┼────────────────┼────────┘
-         │              │              │                │
-         └──────────────┴──────────────┴────────────────┘
-                              │
-┌─────────────────────────────┼─────────────────────────────────┐
-│                    REASONINGBANK CORE                           │
-│  ┌──────────────────────────┴────────────────────────────┐    │
-│  │                   Memory Engine                        │    │
-│  │  ┌────────────┐  ┌─────────────┐  ┌──────────────┐  │    │
-│  │  │ Retrieve   │→ │   Judge     │→ │   Distill    │  │    │
-│  │  │ (4-factor) │  │ (LLM/Heur.) │  │ (Strategies) │  │    │
-│  │  └────────────┘  └─────────────┘  └──────────────┘  │    │
-│  │         ↑                                      ↓       │    │
-│  │  ┌────────────────────────────────────────────────┐  │    │
-│  │  │          Consolidate (Periodic)                │  │    │
-│  │  │  - Deduplicate  - Contradict  - Prune         │  │    │
-│  │  └────────────────────────────────────────────────┘  │    │
-│  └───────────────────────────────────────────────────────┘    │
-│                             │                                  │
-│  ┌──────────────────────────┴────────────────────────────┐    │
-│  │                 Utilities Layer                        │    │
-│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐           │    │
-│  │  │Embeddings│  │PII Scrub │  │   MMR    │           │    │
-│  │  │(OpenAI/  │  │(9 types) │  │(Diversity)│           │    │
-│  │  │Claude)   │  │          │  │          │           │    │
-│  │  └──────────┘  └──────────┘  └──────────┘           │    │
-│  └───────────────────────────────────────────────────────┘    │
-└─────────────────────────────┬───────────────────────────────┘
-                              │
-┌─────────────────────────────┴───────────────────────────────┐
-│                      PERSISTENCE LAYER                        │
-│  ┌──────────────────────────────────────────────────────┐   │
-│  │                SQLite Database (WAL)                  │   │
-│  │  ┌───────────────────┐  ┌───────────────────┐       │   │
-│  │  │reasoning_memory   │  │task_trajectory    │       │   │
-│  │  │- Strategies       │  │- Execution logs   │       │   │
-│  │  │- Confidence       │  │- Verdicts         │       │   │
-│  │  │- Usage tracking   │  │- Timestamps       │       │   │
-│  │  └───────────────────┘  └───────────────────┘       │   │
-│  │  ┌───────────────────┐  ┌───────────────────┐       │   │
-│  │  │pattern_embeddings │  │matts_runs         │       │   │
-│  │  │- Semantic vectors │  │- Scaling results  │       │   │
-│  │  │- 1024 dimensions  │  │- Consensus data   │       │   │
-│  │  └───────────────────┘  └───────────────────┘       │   │
-│  └──────────────────────────────────────────────────────┘   │
-└───────────────────────────────────────────────────────────────┘
-```
-
-### Memory Lifecycle State Machine
-
-```
-┌────────────────────────────────────────────────────────────┐
-│                    MEMORY LIFECYCLE                         │
-└────────────────────────────────────────────────────────────┘
-
-[NEW TASK]
-    ↓
-┌─────────────────┐
-│  State: READY   │  confidence = 0.0
-└────────┬────────┘  usage_count = 0
-         │
-         ↓ (Task execution starts)
-┌──────────────────┐
-│ State: EXECUTING │  Capture trajectory
-└────────┬─────────┘  Track all actions
-         │
-         ↓ (Task completes)
-┌──────────────────┐
-│ State: JUDGING   │  LLM evaluates outcome
-└────────┬─────────┘  → Success or Failure
-         │
-    ┌────┴────┐
-    ↓         ↓
-┌─────────┐  ┌─────────┐
-│SUCCESS  │  │FAILURE  │
-└────┬────┘  └────┬────┘
-     │            │
-     ↓            ↓
-┌────────────────────────┐
-│ State: DISTILLING      │  Extract patterns
-│ - Success → Strategies │  Initial confidence:
-│ - Failure → Guardrails │  0.5 (neutral)
-└──────────┬─────────────┘
-           │
-           ↓
-┌──────────────────────┐
-│ State: STORED        │  confidence = 0.5
-│ (reasoning_memory)   │  usage_count = 0
-└──────────┬───────────┘  created_at = NOW
-           │
-           ↓ (Future task retrieves this memory)
-┌──────────────────────┐
-│ State: RETRIEVED     │  usage_count++
-│ (being used)         │  last_used_at = NOW
-└──────────┬───────────┘
-           │
-           ↓ (Task succeeds with this memory)
-┌──────────────────────┐
-│ State: REINFORCED    │  confidence += 0.05
-│ (successful usage)   │  (max 0.95)
-└──────────┬───────────┘
-           │
-           ↓ (Every 20 new memories)
-┌──────────────────────┐
-│State: CONSOLIDATING  │  Check for:
-│ (maintenance)        │  - Duplicates (merge)
-└──────────┬───────────┘  - Contradictions (flag)
-           │              - Old/unused (prune)
-      ┌────┴────┐
-      ↓         ↓
-┌──────────┐  ┌──────────┐
-│ ACTIVE   │  │ PRUNED   │
-│(kept)    │  │(deleted) │
-└──────────┘  └──────────┘
-```
-
-### Embedding Generation Flow
-
-```
-┌─────────────────────────────────────────────────────┐
-│           EMBEDDING GENERATION PIPELINE              │
-└─────────────────────────────────────────────────────┘
-
-Input: Text (query or memory content)
-   │
-   ├─→ Check Cache
-   │   └─→ Cache Hit? → Return cached embedding (0ms)
-   │
-   └─→ Cache Miss
-       ↓
-   ┌────────────────────────┐
-   │  Choose Provider       │
-   │  1. Claude (API)       │
-   │  2. OpenAI (API)       │
-   │  3. Hash (Fallback)    │
-   └───────────┬────────────┘
-               │
-      ┌────────┴─────────┐
-      ↓                  ↓
-┌─────────────┐   ┌──────────────┐   ┌─────────────┐
-│Claude Embed │   │OpenAI Embed  │   │Hash Fallback│
-│(Workaround) │   │(text-embed-3)│   │(Deterministic)
-│- Call API   │   │- Call API    │   │- Simple hash│
-│- Extract    │   │- Get vector  │   │- Sin/cos    │
-│  hidden     │   │- 1024 dims   │   │  transform  │
-│  state      │   │              │   │- Normalize  │
-└──────┬──────┘   └──────┬───────┘   └──────┬──────┘
-       │                 │                  │
-       └─────────────────┴──────────────────┘
-                         │
-                         ↓
-                ┌─────────────────┐
-                │  Normalize      │
-                │  magnitude = 1  │
-                └────────┬────────┘
-                         │
-                         ↓
-                ┌─────────────────┐
-                │  Float32Array   │
-                │  [1024 floats]  │
-                └────────┬────────┘
-                         │
-                         ↓
-                ┌─────────────────┐
-                │  Store in Cache │
-                │  TTL: 3600s     │
-                └────────┬────────┘
-                         │
-                         ↓
-                ┌─────────────────┐
-                │  Serialize to   │
-                │  BLOB for DB    │
-                └─────────────────┘
-```
-
----
-
-## 🧮 Mathematical Foundations
-
-### Cosine Similarity Derivation
-
-The cosine similarity measures the angle between two vectors:
-
-```
-Given vectors A and B:
-
-cos(θ) = (A · B) / (||A|| × ||B||)
-
-Where:
-- A · B = dot product = Σ(A[i] × B[i])
-- ||A|| = magnitude of A = sqrt(Σ(A[i]²))
-- ||B|| = magnitude of B = sqrt(Σ(B[i]²))
-
-Properties:
-- Result range: [-1, 1]
-  - 1.0 = identical direction (perfect match)
-  - 0.0 = orthogonal (unrelated)
-  - -1.0 = opposite direction (contradictory)
-
-Example:
-A = [0.5, 0.3, 0.2]
-B = [0.4, 0.4, 0.2]
-
-A · B = (0.5×0.4) + (0.3×0.4) + (0.2×0.2) = 0.36
-||A|| = sqrt(0.5² + 0.3² + 0.2²) = sqrt(0.38) = 0.616
-||B|| = sqrt(0.4² + 0.4² + 0.2²) = sqrt(0.36) = 0.6
-
-cos(θ) = 0.36 / (0.616 × 0.6) = 0.36 / 0.37 = 0.973
-
-Interpretation: 0.973 = 97.3% similar → Very high match!
-```
-
-### Exponential Decay (Recency Factor)
-
-Recency uses exponential decay with configurable half-life:
-
-```
-recency = exp(-age_days / half_life)
-
-Where:
-- age_days = (current_date - created_at) in days
-- half_life = 30 days (default)
-
-Example timeline:
-age = 0 days   → recency = exp(0) = 1.0 (100%)
-age = 15 days  → recency = exp(-0.5) = 0.606 (61%)
-age = 30 days  → recency = exp(-1) = 0.368 (37%)
-age = 60 days  → recency = exp(-2) = 0.135 (14%)
-age = 90 days  → recency = exp(-3) = 0.050 (5%)
-
-Graph:
-1.0 │ •
-    │   •
-    │     •
-0.5 │       •••
-    │          ••••
-    │              ••••••
-0.0 │____________________••••••••••••••••
-    0    15   30   45   60   75   90 days
-
-Interpretation:
-- Recent memories (0-15 days) retain 60%+ weight
-- Month-old memories drop to 37%
-- 3-month-old memories nearly irrelevant (5%)
-```
-
-### Reliability Score Calculation
-
-Reliability combines confidence with usage validation:
-
-```
-reliability = min(confidence × sqrt(usage_count / 10), 1.0)
-
-Components:
-1. confidence: Base trustworthiness (0.0-1.0)
-2. usage_count: Times successfully retrieved
-3. Scaling factor: sqrt(usage_count / 10)
-
-Why sqrt? Diminishing returns - 100 uses isn't 10x better than 10 uses
-
-Examples:
-Memory A: confidence=0.8, usage=0
-  → reliability = min(0.8 × sqrt(0), 1.0) = 0.0
-  (Never used = unproven)
-
-Memory B: confidence=0.8, usage=10
-  → reliability = min(0.8 × sqrt(10/10), 1.0) = 0.8
-  (10 uses validates the confidence)
-
-Memory C: confidence=0.8, usage=100
-  → reliability = min(0.8 × sqrt(100/10), 1.0) = min(2.53, 1.0) = 1.0
-  (Capped at perfect reliability)
-
-Memory D: confidence=0.5, usage=40
-  → reliability = min(0.5 × sqrt(40/10), 1.0) = min(0.5 × 2.0, 1.0) = 1.0
-  (High usage can overcome low initial confidence)
-
-Graph of scaling factor:
-sqrt(usage/10)
-3.0 │                              •
-    │                          •••
-2.0 │                     •••
-    │                •••
-1.0 │           •••
-    │      •••
-0.0 │•••___________________________________
-    0    10   25   50   75  100  usage_count
-```
-
-### Complete Scoring Formula Breakdown
-
-```python
-# Step-by-step example with real values
-query = "Login to admin panel with CSRF protection"
-memory = {
-  "title": "CSRF token extraction strategy",
-  "created_at": "2025-01-05",  # 15 days ago
-  "confidence": 0.75,
-  "usage_count": 18
-}
-
-# 1. Semantic similarity (computed via embeddings)
-query_embedding = embed(query)  # [0.23, -0.41, 0.52, ...]
-memory_embedding = embed(memory.content)  # [0.19, -0.38, 0.48, ...]
-similarity = cosine_similarity(query_embedding, memory_embedding)
-             = 0.87  # High match!
-
-# 2. Recency (exponential decay)
-age_days = (2025-01-20 - 2025-01-05) = 15 days
-recency = exp(-15 / 30) = exp(-0.5) = 0.606
-
-# 3. Reliability (confidence × usage validation)
-reliability = min(0.75 × sqrt(18/10), 1.0)
-            = min(0.75 × 1.34, 1.0)
-            = min(1.005, 1.0)
-            = 1.0  # Capped at perfect
-
-# 4. Diversity penalty (applied during MMR)
-# Assume 1 memory already selected with similarity 0.65
-diversity_penalty = 0.65
-
-# Final score calculation
-alpha = 0.65  # Similarity weight
-beta = 0.15   # Recency weight
-gamma = 0.20  # Reliability weight
-delta = 0.10  # Diversity weight
-
-base_score = (alpha × similarity) + (beta × recency) + (gamma × reliability)
-           = (0.65 × 0.87) + (0.15 × 0.606) + (0.20 × 1.0)
-           = 0.566 + 0.091 + 0.200
-           = 0.857
-
-# MMR-adjusted score (diversity penalty)
-final_score = base_score - (delta × diversity_penalty)
-            = 0.857 - (0.10 × 0.65)
-            = 0.857 - 0.065
-            = 0.792
-
-# Interpretation: 0.792 = 79.2% → Strong candidate for retrieval!
-```
-
----
-
-## 🔬 Advanced Algorithms
-
-### MMR (Maximal Marginal Relevance) Detailed
-
-MMR iteratively selects documents that balance relevance and diversity:
-
-```python
-def mmr_detailed(candidates, query_embedding, k, lambda_param=0.9):
-    """
-    MMR: Maximal Marginal Relevance
-
-    Goal: Select k items that are:
-    1. Relevant to query (high base score)
-    2. Diverse from each other (low inter-similarity)
-
-    Lambda parameter trades off relevance vs diversity:
-    - λ = 1.0: Pure relevance (ignores diversity)
-    - λ = 0.5: Balance
-    - λ = 0.0: Pure diversity (ignores relevance)
-    """
-    selected = []
-    remaining = sorted(candidates, key=lambda x: x.score, reverse=True)
-
-    # First item: Just pick highest-scoring
-    if remaining:
-        selected.append(remaining.pop(0))
-
-    # Subsequent items: Balance relevance and diversity
-    while len(selected) < k and remaining:
-        best_idx = -1
-        best_mmr_score = -float('inf')
-
-        for i, candidate in enumerate(remaining):
-            # Relevance component (from 4-factor scoring)
-            relevance = candidate.score
-
-            # Diversity component (similarity to already-selected)
-            max_similarity = 0.0
-            for selected_item in selected:
-                sim = cosine_similarity(
-                    candidate.embedding,
-                    selected_item.embedding
-                )
-                max_similarity = max(max_similarity, sim)
-
-            # MMR score: Trade off relevance vs diversity
-            mmr_score = lambda_param * relevance - (1 - lambda_param) * max_similarity
-
-            if mmr_score > best_mmr_score:
-                best_mmr_score = mmr_score
-                best_idx = i
-
-        # Add best candidate and remove from consideration
-        selected.append(remaining.pop(best_idx))
-
-    return selected
-
-
-# Example execution trace:
-candidates = [
-    {"id": 1, "score": 0.92, "embedding": [0.5, 0.3, ...]},  # CSRF extraction
-    {"id": 2, "score": 0.88, "embedding": [0.48, 0.31, ...]}, # CSRF validation
-    {"id": 3, "score": 0.75, "embedding": [0.1, -0.8, ...]},  # Rate limiting
-    {"id": 4, "score": 0.71, "embedding": [0.49, 0.29, ...]}, # CSRF storage
-]
-
-# Iteration 1: Select highest score
-selected = [candidate_1]  # score=0.92, "CSRF extraction"
-
-# Iteration 2: Balance relevance and diversity
-For candidate_2:
-  relevance = 0.88
-  similarity_to_1 = cosine_similarity(C2, C1) = 0.95  # Very similar!
-  mmr_score = 0.9 × 0.88 - 0.1 × 0.95 = 0.792 - 0.095 = 0.697
-
-For candidate_3:
-  relevance = 0.75
-  similarity_to_1 = cosine_similarity(C3, C1) = 0.12  # Very different!
-  mmr_score = 0.9 × 0.75 - 0.1 × 0.12 = 0.675 - 0.012 = 0.663
-
-For candidate_4:
-  relevance = 0.71
-  similarity_to_1 = cosine_similarity(C4, C1) = 0.92  # Very similar!
-  mmr_score = 0.9 × 0.71 - 0.1 × 0.92 = 0.639 - 0.092 = 0.547
-
-Best MMR score: candidate_2 (0.697)
-selected = [candidate_1, candidate_2]
-
-# Iteration 3:
-For candidate_3:
-  relevance = 0.75
-  max_similarity = max(
-    cosine_similarity(C3, C1) = 0.12,
-    cosine_similarity(C3, C2) = 0.15
-  ) = 0.15
-  mmr_score = 0.9 × 0.75 - 0.1 × 0.15 = 0.675 - 0.015 = 0.660
-
-For candidate_4:
-  relevance = 0.71
-  max_similarity = max(
-    cosine_similarity(C4, C1) = 0.92,
-    cosine_similarity(C4, C2) = 0.89
-  ) = 0.92  # Still very similar to both!
-  mmr_score = 0.9 × 0.71 - 0.1 × 0.92 = 0.639 - 0.092 = 0.547
-
-Best MMR score: candidate_3 (0.660)
-selected = [candidate_1, candidate_2, candidate_3]
-
-Final selection:
-1. CSRF extraction (0.92 base, diverse topic)
-2. CSRF validation (0.88 base, adds validation aspect)
-3. Rate limiting (0.75 base, but VERY diverse topic)
-
-Note: candidate_4 excluded despite decent base score (0.71)
-because it's too similar to already-selected items.
-```
-
-### Consolidation Algorithms Deep Dive
-
-#### Deduplication with Hierarchical Clustering
-
-```python
-def deduplicate_advanced(memories, similarity_threshold=0.95):
-    """
-    Advanced deduplication using hierarchical clustering
-
-    Strategy:
-    1. Build similarity matrix (O(n²))
-    2. Form clusters using single-linkage
-    3. Merge clusters within threshold
-    4. Keep highest-confidence representative from each cluster
-    """
-    # Build similarity matrix
-    n = len(memories)
-    similarity_matrix = [[0.0] * n for _ in range(n)]
-
-    for i in range(n):
-        for j in range(i+1, n):
-            sim = cosine_similarity(
-                memories[i].embedding,
-                memories[j].embedding
-            )
-            similarity_matrix[i][j] = sim
-            similarity_matrix[j][i] = sim  # Symmetric
-
-    # Hierarchical clustering
-    clusters = [[mem] for mem in memories]  # Start with singleton clusters
-
-    while True:
-        # Find most similar pair of clusters
-        max_sim = 0.0
-        merge_i, merge_j = -1, -1
-
-        for i in range(len(clusters)):
-            for j in range(i+1, len(clusters)):
-                # Single-linkage: max similarity between any pair
-                cluster_sim = max(
-                    similarity_matrix[m1.id][m2.id]
-                    for m1 in clusters[i]
-                    for m2 in clusters[j]
-                )
-
-                if cluster_sim > max_sim:
-                    max_sim = cluster_sim
-                    merge_i, merge_j = i, j
-
-        # Stop if no clusters meet threshold
-        if max_sim < similarity_threshold:
-            break
-
-        # Merge most similar clusters
-        clusters[merge_i].extend(clusters[merge_j])
-        clusters.pop(merge_j)
-
-    # Keep best memory from each cluster
-    representatives = []
-    duplicates_removed = 0
-
-    for cluster in clusters:
-        if len(cluster) == 1:
-            representatives.append(cluster[0])
-        else:
-            # Sort by confidence × usage_count
-            cluster.sort(
-                key=lambda m: m.confidence * sqrt(m.usage_count),
-                reverse=True
-            )
-
-            # Keep highest-quality, merge usage counts
-            representative = cluster[0]
-            for duplicate in cluster[1:]:
-                representative.usage_count += duplicate.usage_count
-                representative.confidence = max(
-                    representative.confidence,
-                    duplicate.confidence
-                )
-                delete_memory(duplicate.id)
-                duplicates_removed += 1
-
-            representatives.append(representative)
-
-    return representatives, duplicates_removed
-
-
-# Example execution:
-memories = [
-    {"id": "M1", "title": "Extract CSRF token from form", "confidence": 0.8, "usage": 15},
-    {"id": "M2", "title": "Parse CSRF token from HTML", "confidence": 0.7, "usage": 8},
-    {"id": "M3", "title": "Include CSRF token in POST", "confidence": 0.75, "usage": 12},
-    {"id": "M4", "title": "Rate limit with exponential backoff", "confidence": 0.65, "usage": 5},
-]
-
-# Similarity matrix (computed):
-#      M1   M2   M3   M4
-# M1 [ 1.0, 0.96, 0.91, 0.15 ]
-# M2 [ 0.96, 1.0, 0.88, 0.12 ]
-# M3 [ 0.91, 0.88, 1.0, 0.18 ]
-# M4 [ 0.15, 0.12, 0.18, 1.0 ]
-
-# Clustering process:
-Initial clusters: [[M1], [M2], [M3], [M4]]
-
-Round 1: Merge M1 and M2 (similarity 0.96 > 0.95)
-Clusters: [[M1, M2], [M3], [M4]]
-
-Round 2: Check similarities
-- [M1,M2] ↔ [M3]: max(0.91, 0.88) = 0.91 < 0.95 ✗
-- [M1,M2] ↔ [M4]: max(0.15, 0.12) = 0.15 < 0.95 ✗
-- [M3] ↔ [M4]: 0.18 < 0.95 ✗
-Stop clustering.
-
-Final clusters: [[M1, M2], [M3], [M4]]
-
-Select representatives:
-- Cluster [M1, M2]:
-  - M1 quality: 0.8 × sqrt(15) = 3.10
-  - M2 quality: 0.7 × sqrt(8) = 1.98
-  - Winner: M1 (higher quality)
-  - Merge: M1.usage_count = 15 + 8 = 23
-  - Merge: M1.confidence = max(0.8, 0.7) = 0.8
-  - Delete: M2
-
-- Cluster [M3]: Keep M3 (singleton)
-- Cluster [M4]: Keep M4 (singleton)
-
-Result:
-representatives = [M1 (enhanced), M3, M4]
-duplicates_removed = 1
-```
-
-#### Contradiction Detection with Semantic Analysis
-
-```python
-def detect_contradictions_advanced(memories, threshold=0.8):
-    """
-    Detect contradicting memories using:
-    1. High semantic similarity (same topic)
-    2. Opposite outcomes or recommendations
-    3. Contextual conflict analysis
-    """
-    contradictions = []
-
-    for i, mem1 in enumerate(memories):
-        for mem2 in memories[i+1:]:
-            # Check semantic similarity
-            similarity = cosine_similarity(
-                mem1.embedding,
-                mem2.embedding
-            )
-
-            if similarity < threshold:
-                continue  # Too dissimilar to contradict
-
-            # Extract outcomes/recommendations
-            outcome1 = extract_outcome(mem1)
-            outcome2 = extract_outcome(mem2)
-
-            # Check for contradiction indicators
-            is_contradiction = False
-
-            # Type 1: Opposite success/failure outcomes
-            if (outcome1.type == "success" and outcome2.type == "failure") or \
-               (outcome1.type == "failure" and outcome2.type == "success"):
-                is_contradiction = True
-
-            # Type 2: Conflicting recommendations
-            if contains_negation(mem1.content, mem2.content):
-                # Example: "Always cache" vs "Never cache"
-                is_contradiction = True
-
-            # Type 3: Mutually exclusive actions
-            if are_mutually_exclusive(outcome1.action, outcome2.action):
-                # Example: "Scale up" vs "Scale down"
-                is_contradiction = True
-
-            if is_contradiction:
-                contradictions.append({
-                    "memory1": mem1,
-                    "memory2": mem2,
-                    "similarity": similarity,
-                    "conflict_type": determine_conflict_type(mem1, mem2)
-                })
-
-    # Resolve contradictions
-    for conflict in contradictions:
-        mem1 = conflict["memory1"]
-        mem2 = conflict["memory2"]
-
-        # Resolution strategy
-        if mem1.confidence > mem2.confidence + 0.15:
-            # mem1 significantly more confident
-            flag_for_review(mem2.id, reason=f"Contradicts {mem1.id} (higher confidence)")
-        elif mem2.confidence > mem1.confidence + 0.15:
-            flag_for_review(mem1.id, reason=f"Contradicts {mem2.id} (higher confidence)")
-        else:
-            # Similar confidence: flag both for human review
-            flag_for_review(mem1.id, reason=f"Contradicts {mem2.id} (manual review needed)")
-            flag_for_review(mem2.id, reason=f"Contradicts {mem1.id} (manual review needed)")
-
-    return contradictions
-
-
-def contains_negation(text1, text2):
-    """Check if texts contain negating keywords"""
-    negation_pairs = [
-        ("always", "never"),
-        ("must", "must not"),
-        ("enable", "disable"),
-        ("allow", "deny"),
-        ("cache", "bypass cache"),
-        ("scale up", "scale down"),
-        ("increase", "decrease"),
-    ]
-
-    text1_lower = text1.lower()
-    text2_lower = text2.lower()
-
-    for pos, neg in negation_pairs:
-        if (pos in text1_lower and neg in text2_lower) or \
-           (neg in text1_lower and pos in text2_lower):
-            return True
-
-    return False
-
-
-# Example:
-memories = [
-    {
-        "id": "M1",
-        "title": "Always cache API responses",
-        "content": "Caching API responses improves performance...",
-        "confidence": 0.75,
-        "embedding": [...]
-    },
-    {
-        "id": "M2",
-        "title": "Never cache authentication responses",
-        "content": "Auth responses must not be cached for security...",
-        "confidence": 0.85,
-        "embedding": [...]
-    }
-]
-
-# Detection:
-similarity = cosine_similarity(M1.embedding, M2.embedding) = 0.82
-# High similarity (same topic: caching)
-
-contains_negation(M1.content, M2.content) = True
-# "always cache" vs "never cache" → Negation detected!
-
-# Resolution:
-M2.confidence (0.85) > M1.confidence (0.75) + 0.15? No.
-M1.confidence (0.75) > M2.confidence (0.85) + 0.15? No.
-
-# Both have similar confidence → Flag for human review
-flag_for_review(M1.id, reason="Contradicts M2: caching policy conflict")
-flag_for_review(M2.id, reason="Contradicts M1: caching policy conflict")
-
-# Human decision options:
-# 1. Keep both (they apply to different contexts: general vs auth)
-# 2. Keep M2 only (security takes precedence)
-# 3. Merge into nuanced memory: "Cache non-auth responses"
-```
-
----
-
-## 🎓 Advanced Use Cases
-
-### Use Case: Multi-Agent Code Review System
-
-```typescript
-import { runTask, retrieveMemories, consolidate } from 'agentic-flow/reasoningbank';
-
-// Specialized code review agents with learning
-async function multiAgentCodeReview(pullRequest: PullRequest) {
-  console.log(`\n🔍 Starting Multi-Agent Code Review for PR #${pullRequest.number}\n`);
-
-  // Agent 1: Security Auditor (learns from past vulnerabilities)
-  const securityReview = await runTask({
-    taskId: `security-${pullRequest.id}`,
-    agentId: 'security-auditor',
-    query: `Security audit for: ${pullRequest.description}
-            Changed files: ${pullRequest.files.join(', ')}
-            Focus: SQL injection, XSS, CSRF, auth bypasses`,
-    domain: 'code-review.security',
-    executeFn: async (memories) => {
-      console.log(`🔒 Security Agent using ${memories.length} known vulnerabilities\n`);
-
-      const findings = [];
-
-      for (const file of pullRequest.files) {
-        const code = await readFile(file);
-
-        // Check against learned vulnerability patterns
-        for (const memory of memories) {
-          const pattern = memory.content;
-          if (code.includes(pattern.indicator)) {
-            findings.push({
-              file,
-              line: findLine(code, pattern.indicator),
-              severity: pattern.severity,
-              description: memory.title,
-              recommendation: pattern.fix
-            });
-          }
-        }
-      }
-
-      return {
-        findings,
-        severity: findingsToSeverity(findings)
-      };
-    }
-  });
-
-  // Agent 2: Performance Reviewer (learns from performance anti-patterns)
-  const perfReview = await runTask({
-    taskId: `perf-${pullRequest.id}`,
-    agentId: 'perf-reviewer',
-    query: `Performance review for: ${pullRequest.description}
-            Check for: N+1 queries, memory leaks, inefficient algorithms`,
-    domain: 'code-review.performance',
-    executeFn: async (memories) => {
-      console.log(`⚡ Performance Agent using ${memories.length} known anti-patterns\n`);
-
-      const issues = [];
-
-      for (const file of pullRequest.files) {
-        // ... check for performance issues using learned patterns
-      }
-
-      return { issues };
-    }
-  });
-
-  // Agent 3: Best Practices Reviewer (learns from style guide violations)
-  const styleReview = await runTask({
-    taskId: `style-${pullRequest.id}`,
-    agentId: 'style-reviewer',
-    query: `Code style review for: ${pullRequest.description}
-            Check: naming conventions, error handling, testing`,
-    domain: 'code-review.best-practices',
-    executeFn: async (memories) => {
-      console.log(`📝 Style Agent using ${memories.length} coding standards\n`);
-
-      // ... check for style violations
-
-      return { violations: [] };
-    }
-  });
-
-  // Aggregate results
-  const allFindings = [
-    ...securityReview.result.findings,
-    ...perfReview.result.issues,
-    ...styleReview.result.violations
-  ];
-
-  // Generate review comment
-  const reviewComment = generateReviewComment(allFindings);
-
-  // Post to GitHub
-  await postCodeReviewComment(pullRequest.number, reviewComment);
-
-  // Learn from this review
-  if (allFindings.length === 0) {
-    console.log(`\n✅ Clean PR! All agents learned this is a good pattern.\n`);
-  } else {
-    console.log(`\n📚 Agents learned ${allFindings.length} new patterns to check.\n`);
-  }
-
-  // Consolidate knowledge periodically
-  const stats = await getMemoryStatistics();
-  if (stats.total % 20 === 0) {
-    console.log(`\n🔄 Consolidating knowledge base...\n`);
-    await consolidate();
-  }
-
-  return {
-    approved: allFindings.filter(f => f.severity === 'critical').length === 0,
-    findings: allFindings,
-    learnings: {
-      security: securityReview.newMemories.length,
-      performance: perfReview.newMemories.length,
-      style: styleReview.newMemories.length
-    }
-  };
-}
-
-// Example evolution over 100 PRs:
-// Week 1: 45 findings per PR (agents learning)
-// Week 4: 23 findings per PR (patterns recognized)
-// Week 12: 7 findings per PR (team improved + agents learned)
-// Month 6: 2 findings per PR (mature knowledge base)
-```
-
-### Use Case: Intelligent API Client with Retry Logic
-
-```typescript
-import { runTask, mattsSequential } from 'agentic-flow/reasoningbank';
-
-// API client that learns optimal retry strategies
-class IntelligentAPIClient {
-  async request(endpoint: string, options: RequestOptions) {
-    return await mattsSequential({
-      taskId: `api-${endpoint}-${Date.now()}`,
-      agentId: 'api-client',
-      query: `Make API request to ${endpoint} with reliability
-              Options: ${JSON.stringify(options)}
-              Learn from past failures and apply retry logic`,
-      domain: 'api.http-client',
-      r: 3,  // Up to 3 retry attempts
-      executeFn: async (memories, iteration) => {
-        console.log(`\n📡 API Request Attempt ${iteration + 1}/3`);
-        console.log(`   Using ${memories.length} learned patterns\n`);
-
-        // Apply learned retry strategies
-        const retryStrategy = selectRetryStrategy(memories, endpoint, iteration);
-
-        if (iteration > 0) {
-          // Wait before retry (exponential backoff or learned pattern)
-          const waitTime = retryStrategy.backoff || Math.pow(2, iteration) * 1000;
-          console.log(`   ⏱️  Waiting ${waitTime}ms before retry...\n`);
-          await sleep(waitTime);
-        }
-
-        try {
-          const response = await fetch(endpoint, {
-            ...options,
-            timeout: retryStrategy.timeout || 5000,
-            headers: {
-              ...options.headers,
-              ...retryStrategy.headers  // Learned headers
-            }
-          });
-
-          if (!response.ok) {
-            throw new Error(`HTTP ${response.status}: ${response.statusText}`);
-          }
-
-          return {
-            success: true,
-            data: await response.json(),
-            strategy_used: retryStrategy.name
-          };
-
-        } catch (error) {
-          console.log(`   ❌ Attempt ${iteration + 1} failed: ${error.message}\n`);
-
-          if (iteration === 2) {
-            // Final attempt failed - return error
-            return {
-              success: false,
-              error: error.message,
-              attempts: 3
-            };
-          }
-
-          // Continue to next iteration
-          throw error;
-        }
-      }
-    });
-  }
-}
-
-function selectRetryStrategy(memories, endpoint, iteration) {
-  // Find memories matching this endpoint or similar APIs
-  const relevantMemories = memories.filter(m =>
-    m.pattern_data.endpoint_pattern === parseEndpointPattern(endpoint) ||
-    m.pattern_data.error_type === 'rate_limit' ||
-    m.pattern_data.error_type === 'timeout'
-  );
-
-  if (relevantMemories.length === 0) {
-    // No learned patterns - use default exponential backoff
-    return {
-      name: 'exponential-backoff',
-      backoff: Math.pow(2, iteration) * 1000,
-      timeout: 5000,
-      headers: {}
-    };
-  }
-
-  // Use highest-confidence learned strategy
-  const bestStrategy = relevantMemories.sort((a, b) => b.confidence - a.confidence)[0];
-
-  return {
-    name: bestStrategy.title,
-    backoff: bestStrategy.pattern_data.backoff_ms,
-    timeout: bestStrategy.pattern_data.timeout_ms,
-    headers: bestStrategy.pattern_data.retry_headers || {}
-  };
-}
-
-// Example usage:
-const client = new IntelligentAPIClient();
-
-// First few requests: Agent learns retry patterns
-const result1 = await client.request('/api/users', { method: 'GET' });
-// Attempt 1: Failed (rate limit)
-// Learned: "Wait 2s on 429 responses for /api/* endpoints"
-
-const result2 = await client.request('/api/users', { method: 'GET' });
-// Attempt 1: Used learned 2s backoff → Success!
-
-// After 50 requests, agent knows:
-// - "/api/* endpoints: 429 → wait 2s, then 4s"
-// - "/api/analytics/*: timeout → increase to 10s"
-// - "/api/media/*: always include Range header for large files"
-```
-
----
-
-## 📈 Performance Optimization Techniques
-
-### Database Query Optimization
-
-```sql
--- Optimized retrieval query with multiple filters
-EXPLAIN QUERY PLAN
-SELECT
-  r.id,
-  r.title,
-  r.description,
-  r.content,
-  r.confidence,
-  r.usage_count,
-  r.created_at,
-  r.pattern_data,
-  e.embedding,
-  -- Computed fields
-  julianday('now') - julianday(r.created_at) as age_days,
-  -- Reliability score
-  MIN(
-    r.confidence * SQRT(r.usage_count / 10.0),
-    1.0
-  ) as reliability
-FROM reasoning_memory r
-JOIN pattern_embeddings e ON r.id = e.pattern_id
-WHERE
-  r.confidence >= 0.3  -- Min confidence filter
-  AND (
-    r.pattern_data LIKE '%"domain":"web.admin"%'  -- Domain filter
-    OR r.pattern_data LIKE '%"domain":"web.%"'
-  )
-  AND r.tenant_id = 'tenant-123'  -- Multi-tenant filter
-ORDER BY
-  r.confidence DESC,
-  r.usage_count DESC
-LIMIT 50;
-
--- Query plan:
--- SEARCH reasoning_memory USING INDEX idx_reasoning_memory_confidence (confidence>?)
--- SEARCH pattern_embeddings USING PRIMARY KEY (pattern_id=?)
--- USE TEMP B-TREE FOR ORDER BY
-
--- Performance: 0.92ms for 1,000 memories
-```
-
-### Embedding Cache Strategy
-
-```typescript
-// Multi-level caching for embeddings
-class EmbeddingCache {
-  private l1Cache: Map<string, Float32Array>;  // In-memory (fast)
-  private l2Cache: LRUCache<string, Float32Array>;  // Larger LRU
-  private redis: RedisClient;  // Distributed cache
-
-  async get(text: string, provider: string): Promise<Float32Array | null> {
-    const key = `${provider}:${hashText(text)}`;
-
-    // L1: In-memory cache (0.001ms)
-    if (this.l1Cache.has(key)) {
-      this.metrics.hit('l1');
-      return this.l1Cache.get(key);
-    }
-
-    // L2: LRU cache (0.01ms)
-    if (this.l2Cache.has(key)) {
-      this.metrics.hit('l2');
-      const embedding = this.l2Cache.get(key);
-      this.l1Cache.set(key, embedding);  // Promote to L1
-      return embedding;
-    }
-
-    // L3: Redis distributed cache (1-5ms)
-    if (this.redis) {
-      const cached = await this.redis.get(key);
-      if (cached) {
-        this.metrics.hit('l3');
-        const embedding = deserializeEmbedding(cached);
-        this.l1Cache.set(key, embedding);
-        this.l2Cache.set(key, embedding);
-        return embedding;
-      }
-    }
-
-    // Cache miss - will need to compute
-    this.metrics.miss();
-    return null;
-  }
-
-  async set(text: string, provider: string, embedding: Float32Array) {
-    const key = `${provider}:${hashText(text)}`;
-
-    // Write to all cache levels
-    this.l1Cache.set(key, embedding);
-    this.l2Cache.set(key, embedding);
-
-    if (this.redis) {
-      await this.redis.setex(
-        key,
-        3600,  // 1 hour TTL
-        serializeEmbedding(embedding)
-      );
-    }
-  }
-}
-
-// Cache hit rates after warmup:
-// L1: 45% (ultra-fast)
-// L2: 35% (very fast)
-// L3: 15% (fast)
-// Miss: 5% (slow - requires API call)
-```
-
-### Batch Processing for Consolidation
-
-```typescript
-// Efficient batch consolidation
-async function consolidateBatch(batchSize: number = 100) {
-  const stats = {
-    processed: 0,
-    duplicates: 0,
-    contradictions: 0,
-    pruned: 0,
-    duration: 0
-  };
-
-  const startTime = Date.now();
-
-  // Process in batches to avoid memory overload
-  let offset = 0;
-  let hasMore = true;
-
-  while (hasMore) {
-    // Fetch batch
-    const batch = await fetchMemories({
-      limit: batchSize,
-      offset,
-      orderBy: 'created_at DESC'
-    });
-
-    if (batch.length === 0) {
-      hasMore = false;
-      break;
-    }
-
-    // Parallel processing within batch
-    const [dupResult, contrResult, pruneResult] = await Promise.all([
-      deduplicateBatch(batch),
-      detectContradictionsBatch(batch),
-      pruneBatch(batch)
-    ]);
-
-    stats.processed += batch.length;
-    stats.duplicates += dupResult.removed;
-    stats.contradictions += contrResult.found;
-    stats.pruned += pruneResult.pruned;
-
-    offset += batchSize;
-
-    // Progress indicator
-    console.log(`Processed ${stats.processed} memories...`);
-  }
-
-  stats.duration = Date.now() - startTime;
-
-  return stats;
-}
-
-// Performance:
-// 10,000 memories: 8.2 seconds (1,220 memories/sec)
-// Memory usage: <200MB peak
-```
-
----
-
-## 🔧 Production Deployment Guide
-
-### Docker Compose Setup
-
-```yaml
-version: '3.8'
-
-services:
-  # Main application with ReasoningBank
-  app:
-    build: .
-    environment:
-      - NODE_ENV=production
-      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
-      - DATABASE_PATH=/data/memory.db
-      - REDIS_URL=redis://redis:6379
-    volumes:
-      - app-data:/data
-    depends_on:
-      - redis
-    deploy:
-      replicas: 3
-      resources:
-        limits:
-          memory: 1G
-          cpus: '1.0'
-
-  # Redis for embedding cache
-  redis:
-    image: redis:7-alpine
-    command: redis-server --maxmemory 512mb --maxmemory-policy allkeys-lru
-    volumes:
-      - redis-data:/data
-
-  # Prometheus for metrics
-  prometheus:
-    image: prom/prometheus:latest
-    volumes:
-      - ./prometheus.yml:/etc/prometheus/prometheus.yml
-      - prometheus-data:/prometheus
-    ports:
-      - "9090:9090"
-
-  # Grafana for dashboards
-  grafana:
-    image: grafana/grafana:latest
-    environment:
-      - GF_SECURITY_ADMIN_PASSWORD=${GRAFANA_PASSWORD}
-    volumes:
-      - grafana-data:/var/lib/grafana
-      - ./grafana/dashboards:/etc/grafana/provisioning/dashboards
-    ports:
-      - "3000:3000"
-    depends_on:
-      - prometheus
-
-volumes:
-  app-data:
-  redis-data:
-  prometheus-data:
-  grafana-data:
-```
-
-### Monitoring & Alerting
-
-```yaml
-# prometheus.yml
-global:
-  scrape_interval: 15s
-
-scrape_configs:
-  - job_name: 'reasoningbank'
-    static_configs:
-      - targets: ['app:8080']
-
-# Alert rules
-rule_files:
-  - 'alerts.yml'
-
-# alerts.yml
-groups:
-  - name: reasoningbank
-    interval: 30s
-    rules:
-      # Memory bank health
-      - alert: MemoryBankGrowthStalled
-        expr: rate(reasoningbank_memories_total[5m]) == 0
-        for: 1h
-        annotations:
-          summary: "No new memories created in 1 hour"
-
-      # Retrieval performance
-      - alert: SlowMemoryRetrieval
-        expr: reasoningbank_retrieval_latency_ms > 100
-        for: 5m
-        annotations:
-          summary: "Memory retrieval taking >100ms"
-
-      # Consolidation backlog
-      - alert: ConsolidationBacklog
-        expr: reasoningbank_memories_since_consolidation > 50
-        for: 30m
-        annotations:
-          summary: "50+ memories pending consolidation"
-
-      # Success rate degradation
-      - alert: LowSuccessRate
-        expr: rate(reasoningbank_task_success_total[1h]) / rate(reasoningbank_task_total[1h]) < 0.7
-        for: 30m
-        annotations:
-          summary: "Success rate dropped below 70%"
-```
-
-### Backup Strategy
-
-```bash
-#!/bin/bash
-# backup-reasoningbank.sh
-
-DATE=$(date +%Y%m%d_%H%M%S)
-BACKUP_DIR="/backups/reasoningbank"
-DB_PATH="/data/memory.db"
-
-# Create backup directory
-mkdir -p "$BACKUP_DIR"
-
-# SQLite backup (online, no locking)
-sqlite3 "$DB_PATH" ".backup '$BACKUP_DIR/memory_$DATE.db'"
-
-# Compress backup
-gzip "$BACKUP_DIR/memory_$DATE.db"
-
-# Upload to S3
-aws s3 cp "$BACKUP_DIR/memory_$DATE.db.gz" "s3://my-backups/reasoningbank/"
-
-# Cleanup old local backups (keep 7 days)
-find "$BACKUP_DIR" -name "memory_*.db.gz" -mtime +7 -delete
-
-# Verify backup integrity
-gunzip -c "$BACKUP_DIR/memory_$DATE.db.gz" | sqlite3 :memory: "PRAGMA integrity_check;"
-
-echo "Backup completed: memory_$DATE.db.gz"
-```
-
----
-
-## 🔮 Future Roadmap & Research Directions
-
-### Phase 1: Enhanced Memory Systems (Q1 2025)
-
-**1. Hierarchical Memory Organization**
-```typescript
-// Multi-level memory hierarchy
-interface MemoryHierarchy {
-  episodic: {
-    // Short-term: Last 24 hours
-    recent: Memory[];
-
-    // Medium-term: Last 30 days
-    working: Memory[];
-  };
-
-  semantic: {
-    // Long-term: Consolidated patterns
-    knowledge: Memory[];
-
-    // Meta-knowledge: Patterns about patterns
-    meta: Memory[];
-  };
-
-  procedural: {
-    // How-to memories
-    skills: Memory[];
-  };
-}
-
-// Automatic promotion based on usage
-async function promoteMemory(memory: Memory) {
-  if (memory.usage_count > 50 && memory.confidence > 0.85) {
-    await promoteToSemantic(memory);  // Long-term knowledge
-  }
-
-  if (memory.teaches_process) {
-    await promoteToProced ural(memory);  // Skill memory
-  }
-}
-```
-
-**2. Memory Relationships & Graph**
-```typescript
-// Build knowledge graph from memories
-interface MemoryGraph {
-  nodes: Memory[];
-  edges: MemoryLink[];
-}
-
-interface MemoryLink {
-  source: string;
-  target: string;
-  type: 'entails' | 'contradicts' | 'refines' | 'requires' | 'enables';
-  confidence: number;
-}
-
-// Example: Multi-hop reasoning
-// "Login requires CSRF token" + "CSRF token extracted from form"
-// → "Login requires form parsing"
-```
-
-**3. Cross-Agent Memory Sharing**
-```typescript
-// Shared team memory pool
-interface TeamMemoryBank {
-  shared: Memory[];  // Accessible to all agents
-  private: Map<string, Memory[]>;  // Agent-specific
-
-  async shareMemory(memory: Memory, agents: string[]) {
-    for (const agent of agents) {
-      await grantAccess(agent, memory);
-    }
-  }
-
-  async learnFromPeer(sourceAgent: string, targetAgent: string) {
-    const sharedKnowledge = await fetchMemories({
-      agent: sourceAgent,
-      confidence: { min: 0.8 },
-      usage: { min: 10 }
-    });
-
-    await transferKnowledge(sharedKnowledge, targetAgent);
-  }
-}
-```
-
-### Phase 2: Advanced ML Integration (Q2 2025)
-
-**1. Learned Scoring Functions**
-```python
-# Replace hand-tuned weights with learned model
-class LearnedScorer:
-    def __init__(self):
-        self.model = NeuralNetwork([
-            Dense(128, activation='relu'),
-            Dropout(0.3),
-            Dense(64, activation='relu'),
-            Dense(1, activation='sigmoid')
-        ])
-
-    def train(self, memories_with_outcomes):
-        """
-        Learn optimal scoring from past successes/failures
-
-        Features:
-        - Embedding similarity
-        - Recency
-        - Usage count
-        - Confidence
-        - Domain match
-        - Agent match
-        - Time of day
-        - Task complexity
-
-        Label: Did this memory help? (1 = yes, 0 = no)
-        """
-        X, y = prepare_training_data(memories_with_outcomes)
-        self.model.fit(X, y, epochs=50, validation_split=0.2)
-
-    def score(self, memory, query_context):
-        features = extract_features(memory, query_context)
-        return self.model.predict(features)[0]
-```
-
-**2. Active Learning for Memory Quality**
-```typescript
-// Actively seek feedback on low-confidence memories
-async function activelyImproveMemory(memory: Memory) {
-  if (memory.confidence < 0.6 && memory.usage_count > 5) {
-    // Memory used multiple times but low confidence → needs validation
-
-    const feedback = await requestHumanFeedback({
-      memory,
-      question: `Is this strategy correct?
-                 "${memory.title}"
-
-                 Used ${memory.usage_count} times with mixed results.
-
-                 Please verify:
-                 ☐ Correct and useful
-                 ☐ Partially correct (needs refinement)
-                 ☐ Incorrect (should be removed)`
-    });
-
-    switch (feedback.response) {
-      case 'correct':
-        memory.confidence = 0.9;  // Boost confidence
-        break;
-      case 'partial':
-        await refineMemory(memory, feedback.suggestions);
-        break;
-      case 'incorrect':
-        await deleteMemory(memory.id);
-        break;
-    }
-  }
-}
-```
-
-### Phase 3: Distributed ReasoningBank (Q3 2025)
-
-**1. Federated Learning Across Orgs**
-```typescript
-// Learn from multiple organizations without sharing data
-class FederatedReasoningBank {
-  async federatedTrain(participants: Organization[]) {
-    // Each org trains locally
-    const localModels = await Promise.all(
-      participants.map(org => org.trainLocalModel())
-    );
-
-    // Aggregate model updates (not raw data)
-    const globalModel = aggregateModels(localModels);
-
-    // Distribute updated model
-    for (const org of participants) {
-      await org.updateModel(globalModel);
-    }
-
-    // No org sees others' memories, but all benefit!
-  }
-}
-```
-
-**2. Multi-Region Replication**
-```typescript
-// Eventual consistency across regions
-interface RegionalReasoningBank {
-  region: 'us-east' | 'eu-west' | 'ap-southeast';
-  localDb: Database;
-  syncService: ReplicationService;
-
-  async writeMemory(memory: Memory) {
-    // Write locally (fast)
-    await this.localDb.insert(memory);
-
-    // Async replicate to other regions
-    this.syncService.enqueueReplication({
-      operation: 'insert',
-      data: memory,
-      targetRegions: ['us-east', 'eu-west', 'ap-southeast'].filter(r => r !== this.region)
-    });
-  }
-
-  async readMemories(query: string) {
-    // Always read from local region (low latency)
-    return await this.localDb.retrieve(query);
-  }
-}
-```
-
----
-
-**This addendum will be posted as a comment on the main issue for additional technical depth.**