nexo-brain 2.6.15 → 2.6.17

package/src/cognitive/_core.py

@@ -19,6 +19,8 @@ COGNITIVE_DB = os.path.join(_data_dir, "cognitive.db")
 EMBEDDING_DIM = 768
 LAMBDA_STM = 0.004126   # half-life = ln(2) / (7 * 24) ≈ 7 days
 LAMBDA_LTM = 0.000481  # half-life = ln(2) / (60 * 24) ≈ 60 days
+DEFAULT_MEMORY_STABILITY = 1.0
+DEFAULT_MEMORY_DIFFICULTY = 0.5
 
 # Prediction Error Gate thresholds
 PE_GATE_REJECT = 0.85     # similarity > this → reject (not novel enough)
@@ -145,6 +147,7 @@ def _get_db() -> sqlite3.Connection:
         _init_tables(_conn)
         _migrate_lifecycle(_conn)
         _migrate_co_activation(_conn)
+        _migrate_memory_personalization(_conn)
         _auto_migrate_embeddings(_conn)
     return _conn
 
@@ -192,6 +195,79 @@ def _migrate_co_activation(conn: sqlite3.Connection):
     conn.commit()
 
 
+def clamp_memory_stability(value: float | int | str | None) -> float:
+    try:
+        numeric = float(value)
+    except (TypeError, ValueError):
+        numeric = DEFAULT_MEMORY_STABILITY
+    return max(0.6, min(3.0, numeric))
+
+
+def clamp_memory_difficulty(value: float | int | str | None) -> float:
+    try:
+        numeric = float(value)
+    except (TypeError, ValueError):
+        numeric = DEFAULT_MEMORY_DIFFICULTY
+    return max(0.2, min(1.2, numeric))
+
+
+def initial_memory_profile(source_type: str, *, store: str = "stm") -> tuple[float, float]:
+    source = str(source_type or "").strip().lower()
+    if source in {"learning", "decision", "feedback"}:
+        return 1.2 if store == "stm" else 1.4, 0.4
+    if source in {"dream_insight", "session_summary"}:
+        return 1.1 if store == "stm" else 1.25, 0.55
+    if source in {"sensory", "dialog"}:
+        return 0.9, 0.6
+    return DEFAULT_MEMORY_STABILITY, DEFAULT_MEMORY_DIFFICULTY
+
+
+def personalize_decay_rate(base_lambda: float, *, stability: float, difficulty: float) -> float:
+    stability_factor = clamp_memory_stability(stability)
+    difficulty_factor = 0.75 + (clamp_memory_difficulty(difficulty) * 0.5)
+    return base_lambda * difficulty_factor / stability_factor
+
+
+def rehearsal_profile_update(
+    stability: float,
+    difficulty: float,
+    score: float,
+    *,
+    refinement: bool = False,
+) -> tuple[float, float]:
+    stable = clamp_memory_stability(stability)
+    hard = clamp_memory_difficulty(difficulty)
+    score = max(0.0, min(1.0, float(score or 0.0)))
+
+    stability_gain = 0.03 + max(0.0, score - 0.45) * 0.12
+    if refinement:
+        stability_gain += 0.03
+    new_stability = clamp_memory_stability(stable + stability_gain)
+
+    target_difficulty = clamp_memory_difficulty(1.0 - (score * 0.8))
+    if refinement:
+        target_difficulty = clamp_memory_difficulty(target_difficulty + 0.05)
+    new_difficulty = clamp_memory_difficulty((hard * 0.82) + (target_difficulty * 0.18))
+    return new_stability, new_difficulty
+
+
+def _migrate_memory_personalization(conn: sqlite3.Connection):
+    """Add per-memory stability and difficulty columns if they don't exist."""
+    for table in ("stm_memories", "ltm_memories"):
+        for col, col_type in [
+            ("stability", f"REAL DEFAULT {DEFAULT_MEMORY_STABILITY}"),
+            ("difficulty", f"REAL DEFAULT {DEFAULT_MEMORY_DIFFICULTY}"),
+        ]:
+            try:
+                conn.execute(f"ALTER TABLE {table} ADD COLUMN {col} {col_type}")
+                conn.commit()
+            except sqlite3.OperationalError as e:
+                if "duplicate column" in str(e).lower():
+                    pass
+                else:
+                    raise
+
+
 def _auto_migrate_embeddings(conn: sqlite3.Connection):
     """Auto-detect old 384-dim embeddings and re-embed to 768-dim. Transparent to user."""
     try:
@@ -242,6 +318,8 @@ def _init_tables(conn: sqlite3.Connection):
             last_accessed TEXT DEFAULT (datetime('now')),
             access_count INTEGER DEFAULT 0,
             strength REAL DEFAULT 1.0,
+            stability REAL DEFAULT 1.0,
+            difficulty REAL DEFAULT 0.5,
             promoted_to_ltm INTEGER DEFAULT 0
         );
 
@@ -257,6 +335,8 @@ def _init_tables(conn: sqlite3.Connection):
             last_accessed TEXT DEFAULT (datetime('now')),
             access_count INTEGER DEFAULT 0,
             strength REAL DEFAULT 1.0,
+            stability REAL DEFAULT 1.0,
+            difficulty REAL DEFAULT 0.5,
             is_dormant INTEGER DEFAULT 0,
             original_stm_id INTEGER,
             tags TEXT DEFAULT ''

package/src/cognitive/_decay.py

@@ -2,7 +2,11 @@
 import math
 import numpy as np
 from datetime import datetime, timedelta
-from cognitive._core import _get_db, embed, cosine_similarity, _blob_to_array, _array_to_blob, LAMBDA_STM, LAMBDA_LTM, EMBEDDING_DIM
+from cognitive._core import (
+    _get_db, embed, cosine_similarity, _blob_to_array, _array_to_blob,
+    LAMBDA_STM, LAMBDA_LTM, EMBEDDING_DIM,
+    initial_memory_profile, personalize_decay_rate,
+)
 
 
 def _hnsw_invalidate():
@@ -48,20 +52,32 @@ def apply_decay(adaptive: bool = True):
                 _protected_ltm.add(row["id"])
 
     # STM decay (skip pinned)
-    rows = db.execute("SELECT id, last_accessed, strength FROM stm_memories WHERE promoted_to_ltm = 0 AND (lifecycle_state IS NULL OR lifecycle_state != 'pinned')").fetchall()
+    rows = db.execute("SELECT id, last_accessed, strength, stability, difficulty FROM stm_memories WHERE promoted_to_ltm = 0 AND (lifecycle_state IS NULL OR lifecycle_state != 'pinned')").fetchall()
     for row in rows:
         last = datetime.fromisoformat(row["last_accessed"])
         hours = (now - last).total_seconds() / 3600.0
-        decay_rate = LAMBDA_STM * 0.25 if (adaptive and row["id"] in _protected_stm) else LAMBDA_STM
+        decay_rate = personalize_decay_rate(
+            LAMBDA_STM,
+            stability=row["stability"],
+            difficulty=row["difficulty"],
+        )
+        if adaptive and row["id"] in _protected_stm:
+            decay_rate *= 0.25
         new_strength = row["strength"] * math.exp(-decay_rate * hours)
         db.execute("UPDATE stm_memories SET strength = ? WHERE id = ?", (new_strength, row["id"]))
 
     # LTM decay (skip pinned)
-    rows = db.execute("SELECT id, last_accessed, strength FROM ltm_memories WHERE is_dormant = 0 AND (lifecycle_state IS NULL OR lifecycle_state != 'pinned')").fetchall()
+    rows = db.execute("SELECT id, last_accessed, strength, stability, difficulty FROM ltm_memories WHERE is_dormant = 0 AND (lifecycle_state IS NULL OR lifecycle_state != 'pinned')").fetchall()
     for row in rows:
         last = datetime.fromisoformat(row["last_accessed"])
         hours = (now - last).total_seconds() / 3600.0
-        decay_rate = LAMBDA_LTM * 0.25 if (adaptive and row["id"] in _protected_ltm) else LAMBDA_LTM
+        decay_rate = personalize_decay_rate(
+            LAMBDA_LTM,
+            stability=row["stability"],
+            difficulty=row["difficulty"],
+        )
+        if adaptive and row["id"] in _protected_ltm:
+            decay_rate *= 0.25
         new_strength = row["strength"] * math.exp(-decay_rate * hours)
         if new_strength < 0.1:
             db.execute("UPDATE ltm_memories SET strength = ?, is_dormant = 1 WHERE id = ?", (new_strength, row["id"]))
@@ -101,10 +117,10 @@ def promote_stm_to_ltm():
     for row in rows:
         redacted = row["redaction_applied"] if "redaction_applied" in row.keys() else 0
         db.execute(
-            """INSERT INTO ltm_memories (content, embedding, source_type, source_id, source_title, domain, original_stm_id, redaction_applied)
-               VALUES (?, ?, ?, ?, ?, ?, ?, ?)""",
+            """INSERT INTO ltm_memories (content, embedding, source_type, source_id, source_title, domain, original_stm_id, redaction_applied, stability, difficulty)
+               VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
             (row["content"], row["embedding"], row["source_type"], row["source_id"],
-             row["source_title"], row["domain"], row["id"], redacted)
+             row["source_title"], row["domain"], row["id"], redacted, row["stability"], row["difficulty"])
         )
         db.execute("UPDATE stm_memories SET promoted_to_ltm = 1 WHERE id = ?", (row["id"],))
         promoted += 1
@@ -322,12 +338,13 @@ def dream_cycle(max_insights: int = 50) -> dict:
 
         # Store as LTM with dream_insight tag
         cur = db.execute(
-            """INSERT INTO ltm_memories (content, embedding, source_type, source_id, source_title, domain, tags, strength)
-               VALUES (?, ?, 'dream_insight', ?, ?, ?, 'dream_insight', 0.5)""",
+            """INSERT INTO ltm_memories (content, embedding, source_type, source_id, source_title, domain, tags, strength, stability, difficulty)
+               VALUES (?, ?, 'dream_insight', ?, ?, ?, 'dream_insight', 0.5, ?, ?)""",
             (insight_content, blob,
              f"{mem_a['store']}:{mem_a['id']},{mem_b['store']}:{mem_b['id']}",
              f"Dream: {title_a[:30]} <-> {title_b[:30]}",
-             domain_str)
+             domain_str,
+             *initial_memory_profile("dream_insight", store="ltm"))
         )
         insight_id = cur.lastrowid
 

package/src/cognitive/_ingest.py

@@ -7,6 +7,7 @@ from cognitive._core import (
     _get_db, embed, cosine_similarity, _blob_to_array, _array_to_blob,
     redact_secrets, extract_temporal_date, EMBEDDING_DIM,
     PE_GATE_REJECT, PE_GATE_REFINE, _gate_stats,
+    initial_memory_profile, rehearsal_profile_update,
 )
 
 
@@ -76,6 +77,7 @@ def ingest(
     vec = embed(clean_content)
     blob = _array_to_blob(vec)
     temporal = extract_temporal_date(content)
+    stability, difficulty = initial_memory_profile(source_type, store="stm")
 
     # Auto-pin: corrections and blocking learnings get pinned (zero decay, +0.2 boost)
     # This ensures user's corrections NEVER fade away
@@ -94,9 +96,9 @@ def ingest(
         db.commit()
         # Now actually store in STM
         cur2 = db.execute(
-            """INSERT INTO stm_memories (content, embedding, source_type, source_id, source_title, domain, redaction_applied, temporal_date, lifecycle_state)
-               VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)""",
-            (clean_content, blob, source_type, source_id, source_title, domain, was_redacted, temporal, _pin_lifecycle)
+            """INSERT INTO stm_memories (content, embedding, source_type, source_id, source_title, domain, redaction_applied, temporal_date, lifecycle_state, stability, difficulty)
+               VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
+            (clean_content, blob, source_type, source_id, source_title, domain, was_redacted, temporal, _pin_lifecycle, stability, difficulty)
         )
         db.commit()
         _hnsw_notify_insert("stm", cur2.lastrowid, vec)
@@ -105,9 +107,9 @@ def ingest(
     # skip_quarantine = direct STM (backward compatibility)
     if skip_quarantine:
         cur = db.execute(
-            """INSERT INTO stm_memories (content, embedding, source_type, source_id, source_title, domain, redaction_applied, temporal_date, lifecycle_state)
-               VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)""",
-            (clean_content, blob, source_type, source_id, source_title, domain, was_redacted, temporal, _pin_lifecycle)
+            """INSERT INTO stm_memories (content, embedding, source_type, source_id, source_title, domain, redaction_applied, temporal_date, lifecycle_state, stability, difficulty)
+               VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
+            (clean_content, blob, source_type, source_id, source_title, domain, was_redacted, temporal, _pin_lifecycle, stability, difficulty)
         )
         db.commit()
         _hnsw_notify_insert("stm", cur.lastrowid, vec)
@@ -246,10 +248,11 @@ def ingest_to_ltm(
     was_redacted = 1 if clean_content != content else 0
     vec = embed(clean_content)
     blob = _array_to_blob(vec)
+    stability, difficulty = initial_memory_profile(source_type, store="ltm")
     cur = db.execute(
-        """INSERT INTO ltm_memories (content, embedding, source_type, source_id, source_title, domain, tags, redaction_applied)
-           VALUES (?, ?, ?, ?, ?, ?, ?, ?)""",
-        (clean_content, blob, source_type, source_id, source_title, domain, tags, was_redacted)
+        """INSERT INTO ltm_memories (content, embedding, source_type, source_id, source_title, domain, tags, redaction_applied, stability, difficulty)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
+        (clean_content, blob, source_type, source_id, source_title, domain, tags, was_redacted, stability, difficulty)
     )
     db.commit()
     return cur.lastrowid
@@ -267,10 +270,11 @@ def ingest_sensory(
     vec = embed(clean_content)
     blob = _array_to_blob(vec)
     ts = created_at or datetime.utcnow().isoformat()
+    stability, difficulty = initial_memory_profile("sensory", store="stm")
     cur = db.execute(
-        """INSERT INTO stm_memories (content, embedding, source_type, source_id, domain, created_at, redaction_applied)
-           VALUES (?, ?, 'sensory', ?, ?, ?, ?)""",
-        (clean_content, blob, source_id, domain, ts, was_redacted)
+        """INSERT INTO stm_memories (content, embedding, source_type, source_id, domain, created_at, redaction_applied, stability, difficulty)
+           VALUES (?, ?, 'sensory', ?, ?, ?, ?, ?, ?)""",
+        (clean_content, blob, source_id, domain, ts, was_redacted, stability, difficulty)
     )
     db.commit()
     return cur.lastrowid
@@ -386,6 +390,12 @@ def _refine_memory(match_info: dict, new_content: str) -> int:
     db = _get_db()
     table = "stm_memories" if match_info["store"] == "stm" else "ltm_memories"
     memory_id = match_info["id"]
+    profile_row = db.execute(
+        f"SELECT stability, difficulty FROM {table} WHERE id = ?",
+        (memory_id,),
+    ).fetchone()
+    current_stability = profile_row["stability"] if profile_row else 1.0
+    current_difficulty = profile_row["difficulty"] if profile_row else 0.5
 
     # Check word-level diff to avoid appending near-identical text
     existing_words = set(match_info["content"].lower().split())
@@ -395,10 +405,16 @@ def _refine_memory(match_info: dict, new_content: str) -> int:
     if len(unique_new) < 3:
         # Almost no new words -- just strengthen the existing memory
         now = datetime.utcnow().isoformat()
+        new_stability, new_difficulty = rehearsal_profile_update(
+            current_stability,
+            current_difficulty,
+            score=0.7,
+            refinement=True,
+        )
         db.execute(
             f"UPDATE {table} SET strength = MIN(1.0, strength + 0.1), "
-            f"access_count = access_count + 1, last_accessed = ? WHERE id = ?",
-            (now, memory_id)
+            f"access_count = access_count + 1, last_accessed = ?, stability = ?, difficulty = ? WHERE id = ?",
+            (now, new_stability, new_difficulty, memory_id)
         )
         db.commit()
         return memory_id
@@ -408,11 +424,17 @@ def _refine_memory(match_info: dict, new_content: str) -> int:
     new_vec = embed(merged_content)
     new_blob = _array_to_blob(new_vec)
     now = datetime.utcnow().isoformat()
+    new_stability, new_difficulty = rehearsal_profile_update(
+        current_stability,
+        current_difficulty,
+        score=0.82,
+        refinement=True,
+    )
 
     db.execute(
         f"UPDATE {table} SET content = ?, embedding = ?, strength = MIN(1.0, strength + 0.15), "
-        f"access_count = access_count + 1, last_accessed = ? WHERE id = ?",
-        (merged_content, new_blob, now, memory_id)
+        f"access_count = access_count + 1, last_accessed = ?, stability = ?, difficulty = ? WHERE id = ?",
+        (merged_content, new_blob, now, new_stability, new_difficulty, memory_id)
     )
     db.commit()
     return memory_id
@@ -614,10 +636,10 @@ def process_quarantine() -> dict:
         if should_promote:
             # Promote to STM
             cur = db.execute(
-                """INSERT INTO stm_memories (content, embedding, source_type, source_id, source_title, domain, redaction_applied)
-                   VALUES (?, ?, ?, ?, ?, ?, 0)""",
+                """INSERT INTO stm_memories (content, embedding, source_type, source_id, source_title, domain, redaction_applied, stability, difficulty)
+                   VALUES (?, ?, ?, ?, ?, ?, 0, ?, ?)""",
                 (content, row["embedding"], row["source_type"], row["source_id"],
-                 row["source_title"], row["domain"])
+                 row["source_title"], row["domain"], *initial_memory_profile(row["source_type"], store="stm"))
             )
             db.execute(
                 "UPDATE quarantine SET status = 'promoted', promoted_at = datetime('now'), confidence = 1.0 WHERE id = ?",
@@ -689,10 +711,10 @@ def quarantine_promote(quarantine_id: int) -> str:
 
     # Insert into STM
     db.execute(
-        """INSERT INTO stm_memories (content, embedding, source_type, source_id, source_title, domain, redaction_applied)
-           VALUES (?, ?, ?, ?, ?, ?, 0)""",
+        """INSERT INTO stm_memories (content, embedding, source_type, source_id, source_title, domain, redaction_applied, stability, difficulty)
+           VALUES (?, ?, ?, ?, ?, ?, 0, ?, ?)""",
         (row["content"], row["embedding"], row["source_type"], row["source_id"],
-         row["source_title"], row["domain"])
+         row["source_title"], row["domain"], *initial_memory_profile(row["source_type"], store="stm"))
     )
     db.execute(
         "UPDATE quarantine SET status = 'promoted', promoted_at = datetime('now'), confidence = 1.0 WHERE id = ?",

package/src/cognitive/_memory.py

@@ -406,6 +406,10 @@ def get_stats() -> dict:
 
     avg_stm = db.execute("SELECT AVG(strength) FROM stm_memories WHERE lifecycle_state IN ('active', 'pinned') AND promoted_to_ltm = 0").fetchone()[0] or 0.0
     avg_ltm = db.execute("SELECT AVG(strength) FROM ltm_memories WHERE is_dormant = 0").fetchone()[0] or 0.0
+    avg_stm_stability = db.execute("SELECT AVG(stability) FROM stm_memories WHERE lifecycle_state IN ('active', 'pinned') AND promoted_to_ltm = 0").fetchone()[0] or 0.0
+    avg_ltm_stability = db.execute("SELECT AVG(stability) FROM ltm_memories WHERE is_dormant = 0").fetchone()[0] or 0.0
+    avg_stm_difficulty = db.execute("SELECT AVG(difficulty) FROM stm_memories WHERE lifecycle_state IN ('active', 'pinned') AND promoted_to_ltm = 0").fetchone()[0] or 0.0
+    avg_ltm_difficulty = db.execute("SELECT AVG(difficulty) FROM ltm_memories WHERE is_dormant = 0").fetchone()[0] or 0.0
 
     total_retrievals = db.execute("SELECT COUNT(*) FROM retrieval_log").fetchone()[0]
     avg_retrieval_score = db.execute("SELECT AVG(top_score) FROM retrieval_log").fetchone()[0] or 0.0
@@ -428,6 +432,10 @@ def get_stats() -> dict:
         "ltm_dormant": ltm_dormant,
         "avg_stm_strength": round(avg_stm, 3),
         "avg_ltm_strength": round(avg_ltm, 3),
+        "avg_stm_stability": round(avg_stm_stability, 3),
+        "avg_ltm_stability": round(avg_ltm_stability, 3),
+        "avg_stm_difficulty": round(avg_stm_difficulty, 3),
+        "avg_ltm_difficulty": round(avg_ltm_difficulty, 3),
         "total_retrievals": total_retrievals,
         "avg_retrieval_score": round(avg_retrieval_score, 3),
         "top_domains_stm": [(r["domain"], r["cnt"]) for r in top_domains_stm],

package/src/cognitive/_search.py

@@ -1,9 +1,14 @@
 """NEXO Cognitive — Search, retrieval, ranking."""
 import math
+import re
 import sqlite3
 import numpy as np
 from datetime import datetime
-from cognitive._core import _get_db, embed, cosine_similarity, _blob_to_array, _array_to_blob, _get_model, _get_reranker, rerank_results, EMBEDDING_DIM
+from cognitive._core import (
+    _get_db, embed, cosine_similarity, _blob_to_array, _array_to_blob,
+    _get_model, _get_reranker, rerank_results, EMBEDDING_DIM,
+    rehearsal_profile_update,
+)
 
 def bm25_search(query_text: str, stores: str = "both", top_k: int = 20,
                 source_type_filter: str = "") -> list[dict]:
@@ -151,6 +156,10 @@ _HISTORICAL_CUES = frozenset({
     "cuando", "hace", "meses", "año", "anterior", "antes",
 })
 
+_EXACT_LOOKUP_RE = re.compile(
+    r"(/|\\|::|\.[A-Za-z0-9]+|#L\d+|line \d+|error[: ]|exception|traceback|0x[0-9a-fA-F]+|[A-Z]{2,}-\d+)"
+)
+
 
 def _apply_temporal_boost(results: list[dict], query_text: str) -> list[dict]:
     """Apply bounded temporal boost to retrieval results.
@@ -209,6 +218,42 @@ def _apply_temporal_boost(results: list[dict], query_text: str) -> list[dict]:
     return results
 
 
+def _looks_like_exact_lookup(query_text: str) -> bool:
+    query = str(query_text or "").strip()
+    if not query:
+        return False
+    lowered = query.lower()
+    if _EXACT_LOOKUP_RE.search(query):
+        return True
+    if any(token in lowered for token in ("file ", "path ", "port ", "localhost", "grep ", "rg ", "exact", "literal")):
+        return True
+    if any(ch in query for ch in ('"', "'", "`", "=", "[", "]")):
+        return True
+    return False
+
+
+def _auto_use_hyde(query_text: str, source_type_filter: str = "") -> bool:
+    query = str(query_text or "").strip()
+    if not query or source_type_filter:
+        return False
+    if len(query) < 18 or _looks_like_exact_lookup(query):
+        return False
+    intent = _classify_query_intent(query)
+    return intent in {"howto", "definition", "reasoning"} or (intent == "lookup" and len(query.split()) >= 4)
+
+
+def _auto_spreading_depth(query_text: str, source_type_filter: str = "") -> int:
+    query = str(query_text or "").strip().lower()
+    if not query or source_type_filter or _looks_like_exact_lookup(query):
+        return 0
+    intent = _classify_query_intent(query)
+    if intent in {"howto", "definition", "reasoning"}:
+        return 1
+    if any(connector in query for connector in (" and ", " because ", " related ", " connect ", " why ", " how ")):
+        return 1
+    return 0
+
+
 # ============================================================================
 # FEATURE 0.5: Knowledge Graph Boost
 # Memories connected to more KG nodes (files, areas, other learnings) are
@@ -614,9 +659,18 @@ def _rehearse_results(results: list[dict], skip_ids: set = None):
         if (r["store"], r["id"]) in skip:
             continue
         table = "stm_memories" if r["store"] == "stm" else "ltm_memories"
+        current = db.execute(
+            f"SELECT stability, difficulty FROM {table} WHERE id = ?",
+            (r["id"],),
+        ).fetchone()
+        new_stability, new_difficulty = rehearsal_profile_update(
+            current["stability"] if current else 1.0,
+            current["difficulty"] if current else 0.5,
+            score=r.get("score", 0.6),
+        )
         db.execute(
-            f"UPDATE {table} SET strength = MIN(1.0, strength + 0.08), access_count = access_count + 1, last_accessed = ? WHERE id = ?",
-            (now, r["id"])
+            f"UPDATE {table} SET strength = MIN(1.0, strength + 0.08), access_count = access_count + 1, last_accessed = ?, stability = ?, difficulty = ? WHERE id = ?",
+            (now, new_stability, new_difficulty, r["id"])
         )
     db.commit()
 
@@ -630,18 +684,18 @@ def search(
     rehearse: bool = True,
     source_type_filter: str = "",
     include_archived: bool = False,
-    use_hyde: bool = False,
+    use_hyde: bool | None = None,
     hybrid: bool = True,
     hybrid_alpha: float = 0.6,
-    spreading_depth: int = 0,
+    spreading_depth: int | None = None,
     decompose: bool = True,
     exclude_dreams: bool = True,
 ) -> list[dict]:
     """Full vector search across STM and/or LTM with rehearsal and dormant reactivation.
 
     Args:
-        use_hyde: If True, use HyDE query expansion for richer embedding (default False)
-        spreading_depth: If >0, fetch co-activated neighbors and boost their scores (default 0)
+        use_hyde: If True, force HyDE on; if False, force it off; if None, auto-enable for conceptual queries.
+        spreading_depth: If >0, fetch co-activated neighbors and boost their scores. If None, use a shallow auto-default for multi-hop queries.
         exclude_dreams: If True (default), exclude dream_insight memories from results.
                         Dream insights are 21% of LTM and dilute search precision.
                         Set to False only when explicitly looking for cross-domain patterns.
@@ -677,6 +731,8 @@ def search(
                     return merged
 
     db = _get_db()
+    resolved_use_hyde = _auto_use_hyde(query_text, source_type_filter) if use_hyde is None else bool(use_hyde)
+    resolved_spreading_depth = _auto_spreading_depth(query_text, source_type_filter) if spreading_depth is None else max(0, int(spreading_depth))
 
     # Detect temporal queries — boost results with temporal_date
     _temporal_keywords = {"when", "date", "time", "first", "last", "before", "after",
@@ -684,7 +740,7 @@ def search(
     query_lower = query_text.lower().split()
     is_temporal_query = bool(_temporal_keywords & set(query_lower))
 
-    if use_hyde:
+    if resolved_use_hyde:
         query_vec = hyde_expand_query(query_text)
     else:
         query_vec = embed(query_text)
@@ -855,9 +911,9 @@ def search(
 
     # Spreading activation: boost co-activated neighbors (Feature 2)
     co_activation_applied = False
-    if spreading_depth > 0 and results:
+    if resolved_spreading_depth > 0 and results:
         memory_ids = [(r["store"], r["id"]) for r in results]
-        neighbor_boosts = _get_co_activated_neighbors(memory_ids, depth=spreading_depth)
+        neighbor_boosts = _get_co_activated_neighbors(memory_ids, depth=resolved_spreading_depth)
 
         if neighbor_boosts:
             co_activation_applied = True
@@ -911,7 +967,7 @@ def search(
         reactivated = r.get("reactivated", False)
 
         ranking_desc = "semantic_similarity"
-        if use_hyde:
+        if resolved_use_hyde:
             ranking_desc = "hyde_centroid_similarity"
         parts = [f"Ranked #{rank}: {ranking_desc}={score:.3f}"]
         parts.append(f"store={store}, strength={strength:.2f}, accesses={access_count}")
@@ -919,6 +975,10 @@ def search(
             parts.append(f"kg_boost=+{r['kg_boost']:.3f} ({r.get('kg_connections', 0)} edges)")
         if r.get("co_activation_boost"):
             parts.append(f"co_activation_boost=+{r['co_activation_boost']:.3f}")
+        if use_hyde is None and resolved_use_hyde:
+            parts.append("hyde=auto")
+        if spreading_depth is None and resolved_spreading_depth > 0:
+            parts.append(f"spreading=auto:{resolved_spreading_depth}")
         if created:
             parts.append(f"created={created[:10]}")
         if tags:

package/src/dashboard/app.py

@@ -28,6 +28,8 @@ _PARENT = str(Path(__file__).resolve().parent.parent)
 if _PARENT not in sys.path:
     sys.path.insert(0, _PARENT)
 
+from agent_runner import AgentRunnerError, build_followup_terminal_shell_command
+
 app = FastAPI(title="NEXO Brain Dashboard", version="3.0.0")
 
 TEMPLATES_DIR = Path(__file__).resolve().parent / "templates"
@@ -137,7 +139,7 @@ class ChatMessage(BaseModel):
 
 def _cognitive_db():
     """Direct connection to cognitive.db."""
-    nexo_home = os.environ.get("NEXO_HOME", str(Path.home() / "claude"))
+    nexo_home = os.environ.get("NEXO_HOME", str(Path.home() / ".nexo"))
     db_path = Path(nexo_home) / "data" / "cognitive.db"
     conn = sqlite3.connect(str(db_path))
     conn.row_factory = sqlite3.Row
@@ -145,7 +147,8 @@ def _cognitive_db():
 
 def _email_db():
     """Direct connection to nexo-email.db."""
-    db_path = Path.home() / "claude" / "nexo-email" / "nexo-email.db"
+    nexo_home = Path(os.environ.get("NEXO_HOME", str(Path.home() / ".nexo")))
+    db_path = nexo_home / "nexo-email" / "nexo-email.db"
     if not db_path.exists():
         return None
     conn = sqlite3.connect(str(db_path))
@@ -420,7 +423,7 @@ async def api_sessions(limit: int = Query(10, ge=1, le=50)):
     conn = db.get_db()
     # Active sessions (from sessions table, not diaries)
     active_rows = conn.execute(
-        "SELECT sid as session_id, task, last_update_epoch, claude_session_id "
+        "SELECT sid as session_id, task, last_update_epoch, claude_session_id, external_session_id, session_client "
         "FROM sessions WHERE last_update_epoch > (strftime('%s','now') - 900) "
         "ORDER BY last_update_epoch DESC"
     ).fetchall()
@@ -716,7 +719,7 @@ async def api_ops_move(body: MoveRequest):
 
 @app.post("/api/ops/execute/{fid}")
 async def api_ops_execute(fid: str):
-    """Execute a followup by opening Terminal with claude command."""
+    """Execute a followup by opening Terminal with the configured NEXO client."""
     db = _db()
     conn = db.get_db()
     row = conn.execute("SELECT * FROM followups WHERE id = ?", (fid,)).fetchone()
@@ -734,9 +737,13 @@ async def api_ops_execute(fid: str):
     tmp = tempfile.NamedTemporaryFile(mode="w", suffix=".txt", prefix="nexo-followup-", delete=False)
     tmp.write(fid)
     tmp.close()
-    # The claude command reads the followup ID from the temp file — no shell interpolation of description
-    claude_cmd = f'claude \\"NEXO: execute followup from file $(cat {tmp.name})\\"'
-    script = f'tell application "Terminal" to do script "{claude_cmd}"'
+    # The selected terminal client reads the followup ID from the temp file — no shell interpolation of description
+    try:
+        _, shell_cmd = build_followup_terminal_shell_command(tmp.name)
+    except AgentRunnerError as exc:
+        return JSONResponse({"error": str(exc)}, status_code=503)
+    escaped = shell_cmd.replace("\\", "\\\\").replace('"', '\\"')
+    script = f'tell application "Terminal" to do script "{escaped}"'
     subprocess.Popen(["osascript", "-e", script])
     return {"success": True, "followup_id": fid}
 
@@ -1388,7 +1395,7 @@ async def api_credentials():
 
 @app.get("/api/backups")
 async def api_backups():
-    nexo_home = Path(os.environ.get("NEXO_HOME", str(Path.home() / "claude")))
+    nexo_home = Path(os.environ.get("NEXO_HOME", str(Path.home() / ".nexo")))
     backup_dir = nexo_home / "backups"
     data_dir = nexo_home / "data"
     backups = []

package/src/db/_schema.py

@@ -256,6 +256,15 @@ def _m13_claude_session_id(conn):
     conn.commit()
 
 
+def _m21_external_session_fields(conn):
+    """Generalize session linkage beyond Claude-specific naming."""
+    _migrate_add_column(conn, "sessions", "external_session_id", "TEXT DEFAULT ''")
+    _migrate_add_column(conn, "sessions", "session_client", "TEXT DEFAULT ''")
+    _migrate_add_index(conn, "idx_sessions_external_sid", "sessions", "external_session_id")
+    _migrate_add_index(conn, "idx_sessions_client", "sessions", "session_client")
+    conn.commit()
+
+
 def _m14_learnings_priority_weight(conn):
     """Add priority, weight, and guard usage tracking to learnings + followup priority."""
     _migrate_add_column(conn, "learnings", "priority", "TEXT DEFAULT 'medium'")
@@ -445,6 +454,7 @@ MIGRATIONS = [
     (18, "skills_steps_column", _m18_skills_steps),
     (19, "skills_v2", _m19_skills_v2),
     (20, "personal_scripts_registry", _m20_personal_scripts_registry),
+    (21, "external_session_fields", _m21_external_session_fields),
 ]
 
 

package/src/db/_sessions.py

@@ -34,18 +34,26 @@ def _validate_sid(sid: str) -> str:
     raise ValueError(f"Invalid SID format: {sid[:80]}")
 
 
-def register_session(sid: str, task: str, claude_session_id: str = "") -> dict:
+def register_session(
+    sid: str,
+    task: str,
+    claude_session_id: str = "",
+    *,
+    external_session_id: str = "",
+    session_client: str = "",
+) -> dict:
     """Register or re-register a session."""
     sid = _validate_sid(sid)
     conn = get_db()
     now = now_epoch()
+    linked_session_id = (external_session_id or claude_session_id or "").strip()
     conn.execute(
-        "INSERT OR REPLACE INTO sessions (sid, task, started_epoch, last_update_epoch, local_time, claude_session_id) "
-        "VALUES (?, ?, ?, ?, ?, ?)",
-        (sid, task, now, now, local_time_str(), claude_session_id)
+        "INSERT OR REPLACE INTO sessions (sid, task, started_epoch, last_update_epoch, local_time, claude_session_id, external_session_id, session_client) "
+        "VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
+        (sid, task, now, now, local_time_str(), linked_session_id, linked_session_id, (session_client or "").strip())
     )
     conn.commit()
-    return {"sid": sid, "task": task}
+    return {"sid": sid, "task": task, "external_session_id": linked_session_id, "session_client": (session_client or "").strip()}
 
 
 def update_session(sid: str, task: str | None) -> dict:
@@ -320,4 +328,3 @@ def _expire_old_questions(conn: sqlite3.Connection):
         (cutoff,)
     )
 
-