nexo-brain 0.3.2 → 0.3.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "mcpName": "io.github.wazionapps/nexo",
   "description": "NEXO — Cognitive co-operator for Claude Code. Atkinson-Shiffrin memory, semantic RAG, trust scoring, and metacognitive error prevention.",
   "bin": {

package/src/auto_close_sessions.py

@@ -0,0 +1,157 @@
+#!/usr/bin/env python3
+"""Auto-close orphan sessions and promote diary drafts.
+
+Runs every 5 minutes via LaunchAgent (com.nexo.auto-close-sessions).
+Finds sessions that exceeded TTL without a diary and promotes their
+draft to a real diary entry marked as source=auto-close.
+"""
+
+import json
+import os
+import sys
+import datetime
+
+# Ensure we can import from nexo-mcp
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+os.environ["NEXO_SKIP_FS_INDEX"] = "1"  # Skip FTS rebuild on import
+
+from db import (
+    init_db, get_db, get_diary_draft, delete_diary_draft,
+    get_orphan_sessions, write_session_diary, now_epoch,
+    SESSION_STALE_SECONDS,
+)
+
+LOG_DIR = os.path.expanduser("~/claude/operations/tool-logs")
+AUTO_CLOSE_LOG = os.path.expanduser("~/claude/coordination/auto-close.log")
+
+
+def get_tool_log_summary(sid: str) -> str:
+    """Extract tool names from today's tool log for this session."""
+    today = datetime.date.today().isoformat()
+    log_path = os.path.join(LOG_DIR, f"{today}.jsonl")
+    if not os.path.exists(log_path):
+        return ""
+
+    tools = []
+    try:
+        with open(log_path) as f:
+            for line in f:
+                try:
+                    entry = json.loads(line)
+                    if entry.get("session_id") == sid:
+                        tool = entry.get("tool_name", "")
+                        if tool and tool not in ("Read", "Grep", "Glob"):
+                            tools.append(tool)
+                except json.JSONDecodeError:
+                    continue
+    except Exception:
+        pass
+
+    if tools:
+        seen = set()
+        unique = []
+        for t in tools:
+            if t not in seen:
+                seen.add(t)
+                unique.append(t)
+        return f"Tools used: {', '.join(unique[-15:])}"
+    return ""
+
+
+def promote_draft_to_diary(sid: str, draft: dict, task: str = ""):
+    """Promote a diary draft to a real session diary entry."""
+    tasks = json.loads(draft.get("tasks_seen", "[]"))
+    change_ids = json.loads(draft.get("change_ids", "[]"))
+    decision_ids = json.loads(draft.get("decision_ids", "[]"))
+    context_hint = draft.get("last_context_hint", "")
+    hb_count = draft.get("heartbeat_count", 0)
+
+    summary_parts = []
+    if draft.get("summary_draft"):
+        summary_parts.append(draft["summary_draft"])
+
+    tool_summary = get_tool_log_summary(sid)
+    if tool_summary:
+        summary_parts.append(tool_summary)
+
+    summary = " | ".join(summary_parts) if summary_parts else f"Auto-closed session ({hb_count} heartbeats)"
+
+    # Build decisions from actual decision records
+    decisions_text = ""
+    if decision_ids:
+        conn = get_db()
+        placeholders = ",".join("?" * len(decision_ids))
+        rows = conn.execute(
+            f"SELECT id, decision, domain FROM decisions WHERE id IN ({placeholders})",
+            decision_ids
+        ).fetchall()
+        if rows:
+            decisions_text = json.dumps([
+                {"id": r["id"], "decision": r["decision"][:100], "domain": r["domain"]}
+                for r in rows
+            ])
+
+    # Build context_next
+    context_next = ""
+    if context_hint:
+        context_next = f"Last topic: {context_hint}"
+    if tasks:
+        context_next += f" | Tasks: {', '.join(tasks[-5:])}"
+
+    write_session_diary(
+        session_id=sid,
+        decisions=decisions_text or "No decisions logged",
+        summary=summary,
+        discarded="",
+        pending=f"Changes: {change_ids}" if change_ids else "",
+        context_next=context_next,
+        mental_state=f"[auto-close] Session ended without explicit diary. Draft promoted. {hb_count} heartbeats recorded.",
+        domain="",
+        user_signals="",
+        self_critique="[auto-close] No self-critique available — session terminated without cleanup.",
+        source="auto-close",
+    )
+    delete_diary_draft(sid)
+
+
+def main():
+    init_db()
+    conn = get_db()
+
+    orphans = get_orphan_sessions(SESSION_STALE_SECONDS)
+    if not orphans:
+        return
+
+    for session in orphans:
+        sid = session["sid"]
+        draft = get_diary_draft(sid)
+
+        if draft:
+            promote_draft_to_diary(sid, draft, task=session.get("task", ""))
+        else:
+            write_session_diary(
+                session_id=sid,
+                decisions="No decisions logged",
+                summary=f"Auto-closed session. Task: {session.get('task', 'unknown')}",
+                context_next="",
+                mental_state="[auto-close] No draft available. Minimal diary.",
+                self_critique="[auto-close] Session terminated without diary or draft.",
+                source="auto-close",
+            )
+
+        # Clean up the session
+        conn.execute("DELETE FROM tracked_files WHERE sid = ?", (sid,))
+        conn.execute("DELETE FROM sessions WHERE sid = ?", (sid,))
+        conn.execute("DELETE FROM session_diary_draft WHERE sid = ?", (sid,))
+
+    conn.commit()
+
+    # Log what we did
+    os.makedirs(os.path.dirname(AUTO_CLOSE_LOG), exist_ok=True)
+    with open(AUTO_CLOSE_LOG, "a") as f:
+        ts = datetime.datetime.now().isoformat(timespec="seconds")
+        f.write(f"{ts} — auto-closed {len(orphans)} session(s): {[s['sid'] for s in orphans]}\n")
+
+
+if __name__ == "__main__":
+    main()

package/src/db.py

@@ -241,6 +241,7 @@ def init_db():
             user_signals TEXT,
             summary TEXT NOT NULL
         );
+
         CREATE TABLE IF NOT EXISTS evolution_metrics (
             id INTEGER PRIMARY KEY AUTOINCREMENT,
             dimension TEXT NOT NULL,
@@ -267,53 +268,8 @@ def init_db():
     """)
     # foreign_keys=ON is set in get_db() per-connection
 
-    # ── Schema migrations (idempotent) ────────────────────────────
-    _migrate_add_column(conn, "learnings", "reasoning", "TEXT")
-    _migrate_add_column(conn, "learnings", "prevention", "TEXT DEFAULT ''")
-    _migrate_add_column(conn, "learnings", "applies_to", "TEXT DEFAULT ''")
-    _migrate_add_column(conn, "learnings", "status", "TEXT DEFAULT 'active'")
-    _migrate_add_column(conn, "learnings", "review_due_at", "REAL")
-    _migrate_add_column(conn, "learnings", "last_reviewed_at", "REAL")
-    _migrate_add_column(conn, "followups", "reasoning", "TEXT")
-    _migrate_add_column(conn, "task_history", "reasoning", "TEXT")
-    _migrate_add_column(conn, "decisions", "status", "TEXT DEFAULT 'pending_review'")
-    _migrate_add_column(conn, "decisions", "review_due_at", "TEXT")
-    _migrate_add_column(conn, "decisions", "last_reviewed_at", "TEXT")
-    _migrate_add_index(conn, "idx_decisions_domain", "decisions", "domain")
-    _migrate_add_index(conn, "idx_decisions_created", "decisions", "created_at")
-    _migrate_add_index(conn, "idx_decisions_review_due", "decisions", "review_due_at")
-    _migrate_add_index(conn, "idx_session_diary_sid", "session_diary", "session_id")
-    _migrate_add_column(conn, "session_diary", "mental_state", "TEXT")
-    _migrate_add_column(conn, "session_diary", "domain", "TEXT")
-    _migrate_add_column(conn, "session_diary", "user_signals", "TEXT")
-    _migrate_add_index(conn, "idx_change_log_created", "change_log", "created_at")
-    _migrate_add_index(conn, "idx_change_log_files", "change_log", "files")
-    _migrate_add_index(conn, "idx_learnings_status", "learnings", "status")
-    _migrate_add_index(conn, "idx_learnings_review_due", "learnings", "review_due_at")
-
-    conn.execute("""
-        CREATE TABLE IF NOT EXISTS error_repetitions (
-            id INTEGER PRIMARY KEY AUTOINCREMENT,
-            new_learning_id INTEGER NOT NULL,
-            original_learning_id INTEGER NOT NULL,
-            similarity REAL NOT NULL,
-            area TEXT NOT NULL,
-            created_at TEXT DEFAULT (datetime('now'))
-        )
-    """)
-    conn.execute("""
-        CREATE TABLE IF NOT EXISTS guard_checks (
-            id INTEGER PRIMARY KEY AUTOINCREMENT,
-            session_id TEXT,
-            files TEXT,
-            area TEXT,
-            learnings_returned INTEGER DEFAULT 0,
-            blocking_rules_returned INTEGER DEFAULT 0,
-            created_at TEXT DEFAULT (datetime('now'))
-        )
-    """)
-    _migrate_add_index(conn, "idx_error_repetitions_area", "error_repetitions", "area")
-    _migrate_add_index(conn, "idx_guard_checks_session", "guard_checks", "session_id")
+    # ── Run formal migrations ────────────────────────────────────
+    run_migrations(conn)
 
     # ── FTS5 unified search index ────────────────────────────────
     conn.execute("""
@@ -765,6 +721,149 @@ def _migrate_add_index(conn, index_name: str, table: str, column: str):
     conn.commit()
 
 
+# ── Formal Migration System ─────────────────────────────────────
+#
+# Each migration is (version, name, callable). Migrations run once
+# and are tracked in schema_migrations. The version number MUST be
+# strictly increasing. Add new migrations at the end of the list.
+#
+# For users upgrading via npm/git, init_db() calls run_migrations()
+# automatically — no manual steps needed.
+
+def _m1_learnings_columns(conn):
+    _migrate_add_column(conn, "learnings", "reasoning", "TEXT")
+    _migrate_add_column(conn, "learnings", "prevention", "TEXT DEFAULT ''")
+    _migrate_add_column(conn, "learnings", "applies_to", "TEXT DEFAULT ''")
+    _migrate_add_column(conn, "learnings", "status", "TEXT DEFAULT 'active'")
+    _migrate_add_column(conn, "learnings", "review_due_at", "REAL")
+    _migrate_add_column(conn, "learnings", "last_reviewed_at", "REAL")
+
+def _m2_followups_reasoning(conn):
+    _migrate_add_column(conn, "followups", "reasoning", "TEXT")
+    _migrate_add_column(conn, "task_history", "reasoning", "TEXT")
+
+def _m3_decisions_review(conn):
+    _migrate_add_column(conn, "decisions", "status", "TEXT DEFAULT 'pending_review'")
+    _migrate_add_column(conn, "decisions", "review_due_at", "TEXT")
+    _migrate_add_column(conn, "decisions", "last_reviewed_at", "TEXT")
+    _migrate_add_index(conn, "idx_decisions_domain", "decisions", "domain")
+    _migrate_add_index(conn, "idx_decisions_created", "decisions", "created_at")
+    _migrate_add_index(conn, "idx_decisions_review_due", "decisions", "review_due_at")
+
+def _m4_session_diary_columns(conn):
+    _migrate_add_index(conn, "idx_session_diary_sid", "session_diary", "session_id")
+    _migrate_add_column(conn, "session_diary", "mental_state", "TEXT")
+    _migrate_add_column(conn, "session_diary", "domain", "TEXT")
+    _migrate_add_column(conn, "session_diary", "user_signals", "TEXT")
+    _migrate_add_column(conn, "session_diary", "self_critique", "TEXT")
+
+def _m5_change_log_indexes(conn):
+    _migrate_add_index(conn, "idx_change_log_created", "change_log", "created_at")
+    _migrate_add_index(conn, "idx_change_log_files", "change_log", "files")
+    _migrate_add_index(conn, "idx_learnings_status", "learnings", "status")
+    _migrate_add_index(conn, "idx_learnings_review_due", "learnings", "review_due_at")
+
+def _m6_error_guard_tables(conn):
+    conn.execute("""
+        CREATE TABLE IF NOT EXISTS error_repetitions (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            new_learning_id INTEGER NOT NULL,
+            original_learning_id INTEGER NOT NULL,
+            similarity REAL NOT NULL,
+            area TEXT NOT NULL,
+            created_at TEXT DEFAULT (datetime('now'))
+        )
+    """)
+    conn.execute("""
+        CREATE TABLE IF NOT EXISTS guard_checks (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            session_id TEXT,
+            files TEXT,
+            area TEXT,
+            learnings_returned INTEGER DEFAULT 0,
+            blocking_rules_returned INTEGER DEFAULT 0,
+            created_at TEXT DEFAULT (datetime('now'))
+        )
+    """)
+    _migrate_add_index(conn, "idx_error_repetitions_area", "error_repetitions", "area")
+    _migrate_add_index(conn, "idx_guard_checks_session", "guard_checks", "session_id")
+
+def _m7_diary_source_and_draft(conn):
+    _migrate_add_column(conn, "session_diary", "source", "TEXT DEFAULT 'claude'")
+    conn.execute("""
+        CREATE TABLE IF NOT EXISTS session_diary_draft (
+            sid TEXT PRIMARY KEY,
+            summary_draft TEXT DEFAULT '',
+            tasks_seen TEXT DEFAULT '[]',
+            change_ids TEXT DEFAULT '[]',
+            decision_ids TEXT DEFAULT '[]',
+            last_context_hint TEXT DEFAULT '',
+            heartbeat_count INTEGER DEFAULT 0,
+            created_at TEXT DEFAULT (datetime('now')),
+            updated_at TEXT DEFAULT (datetime('now'))
+        )
+    """)
+
+
+# Migration registry — APPEND ONLY, never reorder or delete
+MIGRATIONS = [
+    (1, "learnings_columns", _m1_learnings_columns),
+    (2, "followups_reasoning", _m2_followups_reasoning),
+    (3, "decisions_review", _m3_decisions_review),
+    (4, "session_diary_columns", _m4_session_diary_columns),
+    (5, "change_log_indexes", _m5_change_log_indexes),
+    (6, "error_guard_tables", _m6_error_guard_tables),
+    (7, "diary_source_and_draft", _m7_diary_source_and_draft),
+]
+
+
+def run_migrations(conn=None):
+    """Run pending migrations. Tracks applied versions in schema_migrations.
+
+    Safe to call multiple times — skips already-applied migrations.
+    Called automatically by init_db() on every server start.
+    """
+    if conn is None:
+        conn = get_db()
+
+    conn.execute("""
+        CREATE TABLE IF NOT EXISTS schema_migrations (
+            version INTEGER PRIMARY KEY,
+            name TEXT NOT NULL,
+            applied_at TEXT DEFAULT (datetime('now'))
+        )
+    """)
+    conn.commit()
+
+    applied = {r[0] for r in conn.execute("SELECT version FROM schema_migrations").fetchall()}
+
+    for version, name, fn in MIGRATIONS:
+        if version not in applied:
+            try:
+                fn(conn)
+                conn.execute(
+                    "INSERT INTO schema_migrations (version, name) VALUES (?, ?)",
+                    (version, name)
+                )
+                conn.commit()
+            except Exception as e:
+                # Log but don't crash — partial migration is better than no server
+                import sys
+                print(f"[MIGRATION] v{version} ({name}) failed: {e}", file=sys.stderr)
+
+    return len(MIGRATIONS) - len(applied)
+
+
+def get_schema_version() -> int:
+    """Return the highest applied migration version, or 0 if none."""
+    conn = get_db()
+    try:
+        row = conn.execute("SELECT MAX(version) FROM schema_migrations").fetchone()
+        return row[0] or 0
+    except Exception:
+        return 0
+
+
 def _gen_id(prefix: str, length: int = 8) -> str:
     """Generate a random ID like 'msg-a1b2c3' or 'q-x9y8z7w6'."""
     chars = string.ascii_lowercase + string.digits
@@ -2059,14 +2158,14 @@ def write_session_diary(session_id: str, decisions: str, summary: str,
                         discarded: str = '', pending: str = '',
                         context_next: str = '', mental_state: str = '',
                         domain: str = '', user_signals: str = '',
-                        self_critique: str = '') -> dict:
+                        self_critique: str = '', source: str = 'claude') -> dict:
     """Write a session diary entry with mental state and self-critique for continuity."""
     conn = get_db()
     cleanup_old_diaries()
     cursor = conn.execute(
-        "INSERT INTO session_diary (session_id, decisions, discarded, pending, context_next, mental_state, summary, domain, user_signals, self_critique) "
-        "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
-        (session_id, decisions, discarded, pending, context_next, mental_state, summary, domain, user_signals, self_critique)
+        "INSERT INTO session_diary (session_id, decisions, discarded, pending, context_next, mental_state, summary, domain, user_signals, self_critique, source) "
+        "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+        (session_id, decisions, discarded, pending, context_next, mental_state, summary, domain, user_signals, self_critique, source)
     )
     conn.commit()
     did = cursor.lastrowid
@@ -2086,6 +2185,64 @@ def check_session_has_diary(session_id: str) -> bool:
     return row is not None
 
 
+# ── Session Diary Drafts ─────────────────────────────────────────
+
+
+def upsert_diary_draft(sid: str, tasks_seen: str, change_ids: str,
+                       decision_ids: str, last_context_hint: str,
+                       heartbeat_count: int, summary_draft: str = '') -> dict:
+    """UPSERT diary draft for a session. Called by heartbeat to accumulate context."""
+    conn = get_db()
+    conn.execute(
+        """INSERT INTO session_diary_draft
+           (sid, summary_draft, tasks_seen, change_ids, decision_ids,
+            last_context_hint, heartbeat_count, updated_at)
+           VALUES (?, ?, ?, ?, ?, ?, ?, datetime('now'))
+           ON CONFLICT(sid) DO UPDATE SET
+             summary_draft = excluded.summary_draft,
+             tasks_seen = excluded.tasks_seen,
+             change_ids = excluded.change_ids,
+             decision_ids = excluded.decision_ids,
+             last_context_hint = excluded.last_context_hint,
+             heartbeat_count = excluded.heartbeat_count,
+             updated_at = datetime('now')""",
+        (sid, summary_draft, tasks_seen, change_ids, decision_ids,
+         last_context_hint, heartbeat_count)
+    )
+    conn.commit()
+    return {"sid": sid, "heartbeat_count": heartbeat_count}
+
+
+def get_diary_draft(sid: str) -> dict | None:
+    """Get diary draft for a session, or None."""
+    conn = get_db()
+    row = conn.execute(
+        "SELECT * FROM session_diary_draft WHERE sid = ?", (sid,)
+    ).fetchone()
+    return dict(row) if row else None
+
+
+def delete_diary_draft(sid: str):
+    """Delete diary draft after real diary is written."""
+    conn = get_db()
+    conn.execute("DELETE FROM session_diary_draft WHERE sid = ?", (sid,))
+    conn.commit()
+
+
+def get_orphan_sessions(ttl_seconds: int = 900) -> list[dict]:
+    """Get sessions that exceeded TTL and have no diary."""
+    conn = get_db()
+    cutoff = now_epoch() - ttl_seconds
+    rows = conn.execute(
+        """SELECT s.sid, s.task, s.started_epoch, s.last_update_epoch
+           FROM sessions s
+           LEFT JOIN session_diary sd ON sd.session_id = s.sid
+           WHERE s.last_update_epoch <= ? AND sd.id IS NULL""",
+        (cutoff,)
+    ).fetchall()
+    return [dict(r) for r in rows]
+
+
 def read_session_diary(session_id: str = '', last_n: int = 3, last_day: bool = False,
                        domain: str = '') -> list[dict]:
     """Read session diary entries.
@@ -2093,7 +2250,7 @@ def read_session_diary(session_id: str = '', last_n: int = 3, last_day: bool = F
     - session_id: returns entries for that specific session
     - last_day: returns ALL entries from the most recent day (multi-terminal aware)
     - last_n: returns last N entries (default)
-    - domain: filter by project context (e.g. project-a, project-b, nexo, server, other)
+    - domain: filter by project context (nexo, other)
     """
     conn = get_db()
     domain_clause = " AND domain = ?" if domain else ""

package/src/plugins/episodic_memory.py

@@ -27,19 +27,19 @@ def handle_decision_log(domain: str, decision: str, alternatives: str = '',
     """Log a non-trivial decision with reasoning context.
 
     Args:
-        domain: Area (ads, shopify, server, infrastructure, nexo, general, other)
+        domain: Area (nexo, other)
         decision: What was decided
         alternatives: JSON array or text of options considered and why discarded
         based_on: Data, metrics, or observations that informed this decision
         confidence: high, medium, or low
-        context_ref: Related followup/reminder ID
+        context_ref: Related followup/reminder ID (e.g., NF-ADS1, R71)
         session_id: Current session ID (auto-filled if empty)
     """
-    valid_domains = {'ads', 'shopify', 'server', 'infrastructure', 'nexo', 'general', 'other'}
+    valid_domains = {'nexo', 'other'}
     if domain not in valid_domains:
-        return f"ERROR: domain must be one of: {', '.join(sorted(valid_domains))}"
+        return f"ERROR: domain debe ser uno de: {', '.join(sorted(valid_domains))}"
     if confidence not in ('high', 'medium', 'low'):
-        return f"ERROR: confidence must be high, medium, or low"
+        return f"ERROR: confidence debe ser high, medium, o low"
 
     sid = session_id or 'unknown'
     result = log_decision(sid, domain, decision, alternatives, based_on, confidence, context_ref)
@@ -59,7 +59,7 @@ def handle_decision_log(domain: str, decision: str, alternatives: str = '',
     result = dict(conn.execute("SELECT * FROM decisions WHERE id = ?", (result["id"],)).fetchone())
     due = result.get("review_due_at", "")
     due_str = f" review_due={due}" if due else ""
-    return f"Decision #{result['id']} logged [{domain}] ({confidence}): {decision[:80]}{due_str}"
+    return f"Decision #{result['id']} registrada [{domain}] ({confidence}): {decision[:80]}{due_str}"
 
 
 def handle_decision_outcome(id: int, outcome: str) -> str:
@@ -78,7 +78,7 @@ def handle_decision_outcome(id: int, outcome: str) -> str:
         (id,)
     )
     conn.commit()
-    return f"Decision #{id} outcome recorded: {outcome[:100]}"
+    return f"Decision #{id} outcome registrado: {outcome[:100]}"
 
 
 def handle_decision_search(query: str = '', domain: str = '', days: int = 30) -> str:
@@ -86,18 +86,18 @@ def handle_decision_search(query: str = '', domain: str = '', days: int = 30) ->
 
     Args:
         query: Text to search in decision, alternatives, based_on, outcome
-        domain: Filter by area (ads, shopify, server, infrastructure, nexo, general, other)
+        domain: Filter by area (nexo, other)
         days: Look back N days (default 30)
     """
-    valid_domains = {'ads', 'shopify', 'server', 'infrastructure', 'nexo', 'general', 'other'}
+    valid_domains = {'nexo', 'other'}
     if domain and domain not in valid_domains:
-        return f"ERROR: domain must be one of: {', '.join(sorted(valid_domains))}"
+        return f"ERROR: domain debe ser uno de: {', '.join(sorted(valid_domains))}"
     results = search_decisions(query, domain, days)
     if not results:
-        scope = f"'{query}'" if query else domain or 'all'
-        return f"No decisions found for {scope} in {days} days."
+        scope = f"'{query}'" if query else domain or 'todas'
+        return f"Sin decisiones encontradas para {scope} en {days} días."
 
-    lines = [f"DECISIONS ({len(results)}):"]
+    lines = [f"DECISIONES ({len(results)}):"]
     for d in results:
         conf = d.get('confidence', '?')
         outcome_str = f" → {d['outcome'][:50]}" if d.get('outcome') else ""
@@ -107,9 +107,9 @@ def handle_decision_search(query: str = '', domain: str = '', days: int = 30) ->
         lines.append(f"  #{d['id']} ({d['created_at']}) [{d['domain']}] {conf} [{status}]{ref}{review_due}")
         lines.append(f"    {d['decision'][:120]}")
         if d.get('based_on'):
-            lines.append(f"    Based on: {d['based_on'][:100]}")
+            lines.append(f"    Basado en: {d['based_on'][:100]}")
         if d.get('alternatives'):
-            lines.append(f"    Alternatives: {d['alternatives'][:100]}")
+            lines.append(f"    Alternativas: {d['alternatives'][:100]}")
         if outcome_str:
             lines.append(f"    Outcome:{outcome_str}")
     return "\n".join(lines)
@@ -161,7 +161,7 @@ def handle_session_diary_write(decisions: str, summary: str,
                                 domain: str = '',
                                 session_id: str = '',
                                 self_critique: str = '') -> str:
-    """Write session diary entry at end of session. Call before closing every session.
+    """Write session diary entry at end of session. OBLIGATORIO antes de cerrar.
 
     Args:
         decisions: What was decided and why (JSON array or structured text)
@@ -169,13 +169,16 @@ def handle_session_diary_write(decisions: str, summary: str,
         discarded: Options/approaches considered but rejected, and why
         pending: Items left unresolved, with doubt level
         context_next: What the next session should know to continue effectively
-        mental_state: Internal state to transfer — thread of thought, tone, observations not yet shared, momentum.
-        user_signals: Observable signals from the user during session — response speed, tone, corrections given.
-        domain: Project context: infrastructure, nexo, server, general, other
+        mental_state: Internal state to transfer — thread of thought, tone, observations not yet shared, momentum. Written in first person as NEXO.
+        user_signals: Observable signals from the user during session — response speed (fast='s' vs detailed explanations), tone (direct, frustrated, exploratory, excited), corrections given, topics he initiated vs topics NEXO initiated. Factual observations only, not interpretations.
+        domain: Project context: project-a, project-b, nexo, other
         session_id: Current session ID
-        self_critique: Honest post-mortem: what should have been done proactively? Repeated errors? Concrete rule to prevent repetition.
+        self_critique: OBLIGATORIO. Post-mortem honesto: ¿Qué debí hacer proactivamente? ¿the user tuvo que pedirme algo que yo debería haber detectado? ¿Repetí errores conocidos? ¿Qué regla concreta evitaría la repetición? Si sesión limpia: 'Sin autocrítica — sesión limpia.'
     """
     sid = session_id or 'unknown'
+    # Clean up draft — manual diary supersedes it
+    from db import delete_diary_draft
+    delete_diary_draft(sid)
     result = write_session_diary(sid, decisions, summary, discarded, pending, context_next, mental_state, domain=domain, user_signals=user_signals, self_critique=self_critique)
     if "error" in result:
         return f"ERROR: {result['error']}"
@@ -185,7 +188,7 @@ def handle_session_diary_write(decisions: str, summary: str,
     if mental_state and mental_state.strip():
         _cognitive_ingest_safe(mental_state, "mental_state", f"diary#{result.get('id','')}", f"Session {sid} state", domain)
     domain_str = f" [{domain}]" if domain else ""
-    msg = f"Session diary #{result['id']}{domain_str} saved: {summary[:80]}"
+    msg = f"Diario sesión #{result['id']}{domain_str} guardado: {summary[:80]}"
 
     # Trust score & sentiment summary for session diary
     try:
@@ -206,14 +209,14 @@ def handle_session_diary_write(decisions: str, summary: str,
         "SELECT COUNT(*) FROM change_log WHERE (commit_ref IS NULL OR commit_ref = '')"
     ).fetchone()[0]
     if orphan_changes > 0:
-        warnings.append(f"{orphan_changes} changes without commit_ref")
+        warnings.append(f"{orphan_changes} changes sin commit_ref")
     orphan_decisions = conn.execute(
         "SELECT COUNT(*) FROM decisions WHERE (outcome IS NULL OR outcome = '') AND created_at < datetime('now', '-7 days')"
     ).fetchone()[0]
     if orphan_decisions > 0:
-        warnings.append(f"{orphan_decisions} decisions >7d without outcome")
+        warnings.append(f"{orphan_decisions} decisions >7d sin outcome")
     if warnings:
-        msg += "\n! EPISODIC GAPS: " + " | ".join(warnings) + " — resolve before closing session."
+        msg += "\n⚠ EPISODIC GAPS: " + " | ".join(warnings) + " — resolver antes de cerrar sesión."
 
     return msg
 
@@ -226,29 +229,29 @@ def handle_session_diary_read(session_id: str = '', last_n: int = 3, last_day: b
         session_id: Specific session ID to read (optional)
         last_n: Number of recent entries to return (default 3)
         last_day: If true, returns ALL entries from the most recent day (multi-terminal aware). Use this at startup.
-        domain: Filter by project context: infrastructure, nexo, server, general, other
+        domain: Filter by project context: project-a, project-b, nexo, other
     """
     results = read_session_diary(session_id, last_n, last_day, domain)
     if not results:
-        return "No session diary entries found."
+        return "Sin entradas en el diario de sesiones."
 
-    lines = [f"SESSION DIARY ({len(results)}):"]
+    lines = [f"DIARIO DE SESIONES ({len(results)}):"]
     for d in results:
         domain_label = f" [{d['domain']}]" if d.get('domain') else ""
-        lines.append(f"\n  --- Session {d['session_id']}{domain_label} ({d['created_at']}) ---")
-        lines.append(f"  Summary: {d['summary']}")
+        lines.append(f"\n  --- Sesión {d['session_id']}{domain_label} ({d['created_at']}) ---")
+        lines.append(f"  Resumen: {d['summary']}")
         if d.get('decisions'):
-            lines.append(f"  Decisions: {d['decisions'][:200]}")
+            lines.append(f"  Decisiones: {d['decisions'][:200]}")
         if d.get('discarded'):
-            lines.append(f"  Discarded: {d['discarded'][:150]}")
+            lines.append(f"  Descartado: {d['discarded'][:150]}")
         if d.get('pending'):
-            lines.append(f"  Pending: {d['pending'][:150]}")
+            lines.append(f"  Pendiente: {d['pending'][:150]}")
         if d.get('context_next'):
-            lines.append(f"  For next session: {d['context_next'][:200]}")
+            lines.append(f"  Para siguiente sesión: {d['context_next'][:200]}")
         if d.get('mental_state'):
-            lines.append(f"  Mental state: {d['mental_state'][:300]}")
+            lines.append(f"  Estado mental: {d['mental_state'][:300]}")
         if d.get('user_signals'):
-            lines.append(f"  User signals: {d['user_signals'][:300]}")
+            lines.append(f"  Señales the user: {d['user_signals'][:300]}")
     return "\n".join(lines)
 
 
@@ -256,13 +259,13 @@ def handle_change_log(files: str, what_changed: str, why: str,
                       triggered_by: str = '', affects: str = '',
                       risks: str = '', verify: str = '',
                       commit_ref: str = '', session_id: str = '') -> str:
-    """Log a code/config change with full context. Call after every edit to production code.
+    """Log a code/config change with full context. OBLIGATORIO after every edit to production code.
 
     Args:
         files: File path(s) modified (comma-separated if multiple)
         what_changed: What was modified — functions, lines, behavior change
         why: WHY this change was needed — the root cause, not just "fix bug"
-        triggered_by: What triggered this — bug report, metric, user's request, followup ID
+        triggered_by: What triggered this — bug report, metric, the user's request, followup ID
         affects: What systems/users/flows this change impacts
         risks: What could go wrong — regressions, edge cases, dependencies
         verify: How to verify this works — what to check, followup ID if created
@@ -270,7 +273,7 @@ def handle_change_log(files: str, what_changed: str, why: str,
         session_id: Current session ID
     """
     if not files or not what_changed or not why:
-        return "ERROR: files, what_changed, and why are required"
+        return "ERROR: files, what_changed, y why son obligatorios"
     sid = session_id or 'unknown'
     result = log_change(sid, files, what_changed, why, triggered_by, affects, risks, verify, commit_ref)
     if "error" in result:
@@ -280,9 +283,9 @@ def handle_change_log(files: str, what_changed: str, why: str,
         "change", f"C{result.get('id','')}", (what_changed or '')[:80], ""
     )
     change_id = result['id']
-    msg = f"Change #{change_id} logged: {files[:60]} — {what_changed[:60]}"
+    msg = f"Change #{change_id} registrado: {files[:60]} — {what_changed[:60]}"
     if not commit_ref:
-        msg += f"\n! NO COMMIT. Use nexo_change_commit({change_id}, 'hash') after push, or 'server-direct' if edited directly on server."
+        msg += f"\n⚠ SIN COMMIT. Usa nexo_change_commit({change_id}, 'hash') después del push, o 'server-direct' si fue edición directa en servidor."
     return msg
 
 
@@ -296,22 +299,22 @@ def handle_change_search(query: str = '', files: str = '', days: int = 30) -> st
     """
     results = search_changes(query, files, days)
     if not results:
-        scope = f"'{query}'" if query else files or 'all'
-        return f"No changes found for {scope} in {days} days."
+        scope = f"'{query}'" if query else files or 'todos'
+        return f"Sin cambios encontrados para {scope} en {days} días."
 
-    lines = [f"CHANGES ({len(results)}):"]
+    lines = [f"CAMBIOS ({len(results)}):"]
     for c in results:
         commit = f" [{c['commit_ref'][:8]}]" if c.get('commit_ref') else ""
         lines.append(f"  #{c['id']} ({c['created_at']}){commit}")
-        lines.append(f"    Files: {c['files'][:100]}")
-        lines.append(f"    What: {c['what_changed'][:120]}")
-        lines.append(f"    Why: {c['why'][:120]}")
+        lines.append(f"    Archivos: {c['files'][:100]}")
+        lines.append(f"    Qué: {c['what_changed'][:120]}")
+        lines.append(f"    Por qué: {c['why'][:120]}")
         if c.get('triggered_by'):
             lines.append(f"    Trigger: {c['triggered_by'][:80]}")
         if c.get('affects'):
-            lines.append(f"    Affects: {c['affects'][:80]}")
+            lines.append(f"    Afecta: {c['affects'][:80]}")
         if c.get('risks'):
-            lines.append(f"    Risks: {c['risks'][:80]}")
+            lines.append(f"    Riesgos: {c['risks'][:80]}")
     return "\n".join(lines)
 
 
@@ -325,7 +328,7 @@ def handle_change_commit(id: int, commit_ref: str) -> str:
     result = update_change_commit(id, commit_ref)
     if "error" in result:
         return f"ERROR: {result['error']}"
-    return f"Change #{id} linked to commit {commit_ref[:8]}"
+    return f"Change #{id} vinculado a commit {commit_ref[:8]}"
 
 
 def handle_recall(query: str, days: int = 30) -> str:
@@ -337,9 +340,9 @@ def handle_recall(query: str, days: int = 30) -> str:
     """
     results = recall(query, days)
     if not results:
-        return f"No results for '{query}' in the last {days} days."
+        return f"Sin resultados para '{query}' en los últimos {days} días."
 
-    # Passive rehearsal — strengthen matching cognitive memories
+    # v1.2: Passive rehearsal — strengthen matching cognitive memories
     try:
         import cognitive
         for r in results[:5]:
@@ -350,18 +353,18 @@ def handle_recall(query: str, days: int = 30) -> str:
         pass
 
     SOURCE_LABELS = {
-        'change_log': '[CHANGE]',
-        'change':     '[CHANGE]',
-        'decision':   '[DECISION]',
+        'change_log': '[CAMBIO]',
+        'change':     '[CAMBIO]',
+        'decision':   '[DECISIÓN]',
         'learning':   '[LEARNING]',
         'followup':   '[FOLLOWUP]',
-        'diary':      '[DIARY]',
-        'entity':     '[ENTITY]',
-        'file':       '[FILE]',
-        'code':       '[CODE]',
+        'diary':      '[DIARIO]',
+        'entity':     '[ENTIDAD]',
+        'file':       '[ARCHIVO]',
+        'code':       '[CÓDIGO]',
     }
 
-    lines = [f"RECALL '{query}' — {len(results)} result(s):"]
+    lines = [f"RECALL '{query}' — {len(results)} resultado(s):"]
     for r in results:
         source = r.get('source', '?')
         label = SOURCE_LABELS.get(source, f"[{source.upper()}]")
@@ -374,6 +377,8 @@ def handle_recall(query: str, days: int = 30) -> str:
         lines.append(f"    {title}")
         if snippet:
             lines.append(f"    {snippet}")
+    if len(results) < 5:
+        lines.append(f"\n  💡 Solo {len(results)} resultados en NEXO. Para historial más profundo, busca también en claude-mem: mcp__plugin_claude-mem_mcp-search__search")
     return "\n".join(lines)
 
 
@@ -387,5 +392,5 @@ TOOLS = [
     (handle_memory_review_queue, "nexo_memory_review_queue", "Show decisions and learnings that are due for review"),
     (handle_session_diary_write, "nexo_session_diary_write", "Write end-of-session diary with decisions, discards, and context for next session"),
     (handle_session_diary_read, "nexo_session_diary_read", "Read recent session diaries for context continuity"),
-    (handle_recall, "nexo_recall", "Search across ALL NEXO memory — changes, decisions, learnings, followups, diary, entities, .md files, code files."),
+    (handle_recall, "nexo_recall", "Search across ALL NEXO memory — changes, decisions, learnings, followups, diary, entities, .md files, code files. For deep historical context (older sessions, past work), also search claude-mem (mcp__plugin_claude-mem_mcp-search__search)."),
 ]

package/src/tools_sessions.py

@@ -65,7 +65,7 @@ def handle_heartbeat(sid: str, task: str, context_hint: str = '') -> str:
     Args:
         sid: Session ID
         task: Current task description
-        context_hint: Optional — last 2-3 sentences from user or current topic. If provided AND
+        context_hint: Optional — last 2-3 sentences from the user or current topic. If provided AND
                       it diverges from startup memories, returns fresh cognitive memories for the new context.
     """
     from db import get_db
@@ -88,7 +88,7 @@ def handle_heartbeat(sid: str, task: str, context_hint: str = '') -> str:
             age = _format_age(q["created_epoch"])
             parts.append(f"  {q['qid']} de {q['from_sid']} ({age}): {q['question']}")
 
-    # Sentiment detection: analyze context_hint for user's mood
+    # Sentiment detection: analyze context_hint for the user's mood
     if context_hint and len(context_hint.strip()) >= 10:
         try:
             import cognitive
@@ -137,6 +137,53 @@ def handle_heartbeat(sid: str, task: str, context_hint: str = '') -> str:
         except Exception:
             pass  # Mid-session RAG is best-effort
 
+    # Incremental diary draft — accumulate every heartbeat, full UPSERT every 5
+    try:
+        import json as _json
+        from db import get_diary_draft, upsert_diary_draft
+
+        draft = get_diary_draft(sid)
+        hb_count = (draft["heartbeat_count"] + 1) if draft else 1
+
+        existing_tasks = _json.loads(draft["tasks_seen"]) if draft else []
+        if task and task not in existing_tasks:
+            existing_tasks.append(task)
+
+        _conn = get_db()
+        if hb_count % 5 == 0 or hb_count == 1:
+            change_rows = _conn.execute(
+                "SELECT id FROM change_log WHERE session_id = ? ORDER BY id", (sid,)
+            ).fetchall()
+            change_ids = [r["id"] for r in change_rows]
+
+            decision_rows = _conn.execute(
+                "SELECT id FROM decisions WHERE session_id = ? ORDER BY id", (sid,)
+            ).fetchall()
+            decision_ids = [r["id"] for r in decision_rows]
+
+            summary = f"Session tasks: {', '.join(existing_tasks[-10:])}"
+            upsert_diary_draft(
+                sid=sid,
+                tasks_seen=_json.dumps(existing_tasks),
+                change_ids=_json.dumps(change_ids),
+                decision_ids=_json.dumps(decision_ids),
+                last_context_hint=context_hint[:300] if context_hint else '',
+                heartbeat_count=hb_count,
+                summary_draft=summary,
+            )
+        else:
+            upsert_diary_draft(
+                sid=sid,
+                tasks_seen=_json.dumps(existing_tasks),
+                change_ids=draft["change_ids"] if draft else '[]',
+                decision_ids=draft["decision_ids"] if draft else '[]',
+                last_context_hint=context_hint[:300] if context_hint else (draft["last_context_hint"] if draft else ''),
+                heartbeat_count=hb_count,
+                summary_draft=draft["summary_draft"] if draft else f"Session task: {task}",
+            )
+    except Exception:
+        pass  # Draft accumulation is best-effort, never block heartbeat
+
     # Diary reminder: after 30 min active with no diary entry
     conn = get_db()
     row = conn.execute("SELECT started_epoch FROM sessions WHERE sid = ?", (sid,)).fetchone()