nexo-brain 0.1.0

package/src/tools_reminders_crud.py

@@ -0,0 +1,157 @@
+"""CRUD handlers for reminders and followups — operates on SQLite via db.py."""
+
+from db import (
+    create_reminder, update_reminder, complete_reminder, delete_reminder,
+    get_reminders, get_reminder,
+    create_followup, update_followup, complete_followup, delete_followup,
+    get_followups, get_followup,
+    find_decisions_by_context_ref, update_decision_outcome,
+)
+
+
+# ── Reminders ──────────────────────────────────────────────────────────────────
+
+def handle_reminder_create(id: str, description: str, date: str = '', category: str = 'general') -> str:
+    """Create a new reminder. id must start with 'R'."""
+    if not id.startswith('R'):
+        return f"ERROR: El ID del recordatorio debe empezar por 'R' (recibido: '{id}')."
+
+    result = create_reminder(id=id, description=description, date=date or None, category=category)
+    if not result or "error" in result:
+        error_msg = result.get("error", "desconocido") if isinstance(result, dict) else "desconocido"
+        return f"ERROR: {error_msg}"
+
+    fecha_str = date if date else 'sin fecha'
+    return f"Recordatorio {id} creado. Fecha: {fecha_str}. Categoría: {category}."
+
+
+def handle_reminder_update(id: str, description: str = '', date: str = '', status: str = '', category: str = '') -> str:
+    """Update one or more fields of an existing reminder."""
+    fields: dict = {}
+    if description:
+        fields['description'] = description
+    if date:
+        fields['date'] = date
+    if status:
+        fields['status'] = status
+    if category:
+        fields['category'] = category
+
+    if not fields:
+        return f"ERROR: No se especificó ningún campo a actualizar para {id}."
+
+    result = update_reminder(id=id, **fields)
+    if not result:
+        return f"ERROR: Recordatorio {id} no encontrado."
+
+    changed = ', '.join(fields.keys())
+    return f"Recordatorio {id} actualizado: {changed}."
+
+
+def handle_reminder_complete(id: str) -> str:
+    """Mark a reminder as completed."""
+    result = complete_reminder(id=id)
+    if not result or "error" in result:
+        return f"ERROR: Recordatorio {id} no encontrado."
+
+    return f"Recordatorio {id} marcado COMPLETADO."
+
+
+def handle_reminder_delete(id: str) -> str:
+    """Delete a reminder permanently."""
+    result = delete_reminder(id=id)
+    if not result:
+        return f"ERROR: Recordatorio {id} no encontrado."
+
+    return f"Recordatorio {id} eliminado."
+
+
+# ── Followups ──────────────────────────────────────────────────────────────────
+
+def handle_followup_create(id: str, description: str, date: str = '', verification: str = '', reasoning: str = '', recurrence: str = '') -> str:
+    """Create a new NEXO followup. id must start with 'NF'.
+
+    Args:
+        id: Unique ID starting with 'NF'
+        description: What to verify/do
+        date: Target date YYYY-MM-DD (optional)
+        verification: How to verify completion (optional)
+        reasoning: WHY this followup exists — what decision/context led to it
+        recurrence: Recurrence pattern (optional). Formats: 'weekly:monday', 'monthly:1', 'quarterly'.
+                    When completed, auto-creates the next occurrence.
+    """
+    if not id.startswith('NF'):
+        return f"ERROR: El ID del followup debe empezar por 'NF' (recibido: '{id}')."
+
+    result = create_followup(id=id, description=description, date=date or None, verification=verification, reasoning=reasoning, recurrence=recurrence or None)
+    if not result or "error" in result:
+        error_msg = result.get("error", "desconocido") if isinstance(result, dict) else "desconocido"
+        return f"ERROR: {error_msg}"
+
+    fecha_str = date if date else 'sin fecha'
+    rec_str = f" Recurrencia: {recurrence}." if recurrence else ""
+    return f"Followup {id} creado. Fecha: {fecha_str}.{rec_str}"
+
+
+def handle_followup_update(id: str, description: str = '', date: str = '', verification: str = '', status: str = '') -> str:
+    """Update one or more fields of an existing followup."""
+    fields: dict = {}
+    if description:
+        fields['description'] = description
+    if date:
+        fields['date'] = date
+    if verification:
+        fields['verification'] = verification
+    if status:
+        fields['status'] = status
+
+    if not fields:
+        return f"ERROR: No se especificó ningún campo a actualizar para {id}."
+
+    result = update_followup(id=id, **fields)
+    if not result:
+        return f"ERROR: Followup {id} no encontrado."
+
+    changed = ', '.join(fields.keys())
+    return f"Followup {id} actualizado: {changed}."
+
+
+def handle_followup_complete(id: str, result: str = '') -> str:
+    """Mark a followup as completed, optionally recording the result.
+    Also auto-updates any decision that references this followup in context_ref.
+    If the followup is recurring, auto-creates the next occurrence."""
+    from db import get_db
+    # Check recurrence before completing (complete may rename the ID)
+    conn = get_db()
+    row = conn.execute("SELECT recurrence FROM followups WHERE id = ?", (id,)).fetchone()
+    has_recurrence = row and row["recurrence"]
+
+    db_result = complete_followup(id=id, result=result)
+    if not db_result or "error" in db_result:
+        return f"ERROR: Followup {id} no encontrado."
+
+    # Auto-link: find decisions whose context_ref matches this followup ID
+    msg = f"Followup {id} marcado COMPLETADO."
+    if has_recurrence:
+        # The new one was auto-created by complete_followup
+        new_row = conn.execute("SELECT date FROM followups WHERE id = ?", (id,)).fetchone()
+        if new_row:
+            msg += f" ♻️ Siguiente auto-creado para {new_row['date']}."
+    linked_decisions = find_decisions_by_context_ref(id)
+    if linked_decisions:
+        outcome_text = result if result else f"Followup {id} completado"
+        for dec in linked_decisions:
+            update_decision_outcome(dec['id'], outcome_text)
+        dec_ids = ', '.join(f"#{d['id']}" for d in linked_decisions)
+        msg += f" Decision(s) {dec_ids} actualizada(s) con outcome automático."
+
+    return msg
+
+
+def handle_followup_delete(id: str) -> str:
+    """Delete a followup permanently."""
+    result = delete_followup(id=id)
+    if not result:
+        return f"ERROR: Followup {id} no encontrado."
+
+    return f"Followup {id} eliminado."

package/src/tools_sessions.py

@@ -0,0 +1,169 @@
+"""Session management tools: startup, heartbeat, status."""
+
+import time
+import secrets
+from db import (
+    register_session, update_session, complete_session,
+    get_active_sessions, clean_stale_sessions, search_sessions,
+    get_inbox, get_pending_questions, now_epoch,
+    SESSION_STALE_SECONDS, check_session_has_diary,
+)
+
+
+def _generate_sid() -> str:
+    """Generate unique session ID: nexo-{epoch}-{random}."""
+    return f"nexo-{int(time.time())}-{secrets.randbelow(100000)}"
+
+
+def _format_age(epoch: float) -> str:
+    """Format seconds since epoch as human-readable age."""
+    seconds = now_epoch() - epoch
+    if seconds < 60:
+        return f"{int(seconds)}s"
+    elif seconds < 3600:
+        return f"{int(seconds / 60)}m"
+    else:
+        return f"{int(seconds / 3600)}h{int((seconds % 3600) / 60)}m"
+
+
+def handle_startup(task: str = "Startup") -> str:
+    """Full startup sequence: register, clean, report."""
+    sid = _generate_sid()
+    cleaned = clean_stale_sessions()
+    register_session(sid, task)
+    active = get_active_sessions()
+    other_sessions = [s for s in active if s["sid"] != sid]
+    inbox = get_inbox(sid)
+
+    lines = [f"SID: {sid}"]
+
+    if cleaned > 0:
+        lines.append(f"Limpiadas {cleaned} sesiones stale.")
+
+    if other_sessions:
+        lines.append("")
+        lines.append("SESIONES ACTIVAS:")
+        for s in other_sessions:
+            age = _format_age(s["last_update_epoch"])
+            lines.append(f"  {s['sid']} ({age}) — {s['task']}")
+    else:
+        lines.append("Sin otras sesiones activas.")
+
+    if inbox:
+        lines.append("")
+        lines.append("MENSAJES PENDIENTES:")
+        for m in inbox:
+            age = _format_age(m["created_epoch"])
+            lines.append(f"  [{m['from_sid']}] ({age}): {m['text']}")
+
+    return "\n".join(lines)
+
+
+def handle_heartbeat(sid: str, task: str, context_hint: str = '') -> str:
+    """Update session, check inbox + questions. Optionally detect context shift and retrieve fresh memories.
+
+    Args:
+        sid: Session ID
+        task: Current task description
+        context_hint: Optional — last 2-3 sentences from Francisco or current topic. If provided AND
+                      it diverges from startup memories, returns fresh cognitive memories for the new context.
+    """
+    from db import get_db
+    update_session(sid, task)
+    parts = [f"OK: {sid} — {task}"]
+
+    inbox = get_inbox(sid)
+    if inbox:
+        parts.append("")
+        parts.append("MENSAJES:")
+        for m in inbox:
+            age = _format_age(m["created_epoch"])
+            parts.append(f"  [{m['from_sid']}] ({age}): {m['text']}")
+
+    questions = get_pending_questions(sid)
+    if questions:
+        parts.append("")
+        parts.append("PREGUNTAS PENDIENTES (responder con nexo_answer):")
+        for q in questions:
+            age = _format_age(q["created_epoch"])
+            parts.append(f"  {q['qid']} de {q['from_sid']} ({age}): {q['question']}")
+
+    # Sentiment detection: analyze context_hint for Francisco's mood
+    if context_hint and len(context_hint.strip()) >= 10:
+        try:
+            import cognitive
+            sentiment = cognitive.detect_sentiment(context_hint)
+            if sentiment["sentiment"] != "neutral":
+                parts.append("")
+                parts.append(f"VIBE: {sentiment['sentiment'].upper()} (intensity: {sentiment['intensity']})")
+                if sentiment["guidance"]:
+                    parts.append(f"  {sentiment['guidance']}")
+                cognitive.log_sentiment(context_hint)
+        except Exception:
+            pass
+
+    # Mid-session RAG: if context_hint provided, check for context shift
+    if context_hint and len(context_hint.strip()) >= 15:
+        try:
+            import cognitive
+            # Get the last retrieval query to compare
+            db_cog = cognitive._get_db()
+            last_query = db_cog.execute(
+                "SELECT query_text FROM retrieval_log ORDER BY id DESC LIMIT 1"
+            ).fetchone()
+
+            do_retrieve = True
+            if last_query:
+                # Compare current hint with last query — if similar (>0.7), skip
+                hint_vec = cognitive.embed(context_hint[:300])
+                last_vec = cognitive.embed(last_query[0][:300])
+                similarity = cognitive.cosine_similarity(hint_vec, last_vec)
+                if similarity > 0.7:
+                    do_retrieve = False  # Same context, no need for fresh memories
+
+            if do_retrieve:
+                results = cognitive.search(
+                    query_text=context_hint[:300],
+                    top_k=5,
+                    min_score=0.55,
+                    stores="both",
+                    exclude_dormant=False,  # Allow reactivating dormant memories
+                    rehearse=True,
+                )
+                if results:
+                    parts.append("")
+                    parts.append("COGNITIVE CONTEXT SHIFT — nuevas memorias relevantes:")
+                    parts.append(cognitive.format_results(results))
+        except Exception:
+            pass  # Mid-session RAG is best-effort
+
+    # 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()
+    if row:
+        age_seconds = now_epoch() - row["started_epoch"]
+        if age_seconds >= 1800 and not check_session_has_diary(sid):
+            parts.append("")
+            parts.append("⚠ DIARY REMINDER: Session active 30+ min without diary. Write nexo_session_diary_write before closing.")
+
+    return "\n".join(parts)
+
+
+def handle_status(keyword: str | None = None) -> str:
+    """List active sessions, optionally filtered by keyword."""
+    clean_stale_sessions()
+    if keyword:
+        sessions = search_sessions(keyword)
+        if not sessions:
+            return f"Nadie trabaja en '{keyword}'."
+    else:
+        sessions = get_active_sessions()
+
+    if not sessions:
+        return "Sin sesiones activas."
+
+    lines = ["SESIONES ACTIVAS:"]
+    for s in sessions:
+        age = _format_age(s["last_update_epoch"])
+        lines.append(f"  {s['sid']} ({age}) — {s['task']}")
+    return "\n".join(lines)

package/src/tools_task_history.py

@@ -0,0 +1,57 @@
+"""Task history tools: log executions, list history, report overdue tasks."""
+
+import datetime
+from db import log_task, list_task_history, set_task_frequency, get_overdue_tasks, get_task_frequencies
+
+
+def _epoch_to_date(epoch: float) -> str:
+    """Format epoch timestamp as readable date string."""
+    return datetime.datetime.fromtimestamp(epoch).strftime("%Y-%m-%d %H:%M")
+
+
+def handle_task_log(task_num: str, task_name: str, notes: str = '', reasoning: str = '') -> str:
+    """Record a task execution in the history log.
+
+    Args:
+        task_num: Task number identifier
+        task_name: Task name
+        notes: Execution notes
+        reasoning: WHY this task was executed now — what triggered it, what data informed it
+    """
+    result = log_task(task_num, task_name, notes, reasoning)
+    if "error" in result:
+        return f"ERROR: {result['error']}"
+    return f"Tarea {task_num} ({task_name}) registrada."
+
+
+def handle_task_list(task_num: str = '', days: int = 30) -> str:
+    """Show execution history for all tasks or a specific task number."""
+    results = list_task_history(task_num if task_num else None, days)
+    if not results:
+        scope = f"tarea {task_num}" if task_num else "ninguna tarea"
+        return f"HISTORIAL: Sin ejecuciones de {scope} en los últimos {days} días."
+    lines = [f"HISTORIAL ({len(results)} ejecuciones, {days}d):"]
+    for r in results:
+        date_str = _epoch_to_date(r["executed_at"])
+        notes_str = f": {r['notes']}" if r.get("notes") else ""
+        lines.append(f"  {date_str} — Tarea {r['task_num']} ({r['task_name']}){notes_str}")
+    return "\n".join(lines)
+
+
+def handle_task_frequency() -> str:
+    """Report tasks that are overdue based on their configured frequency."""
+    overdue = get_overdue_tasks()
+    if not overdue:
+        return "Todas las tareas al día."
+    lines = ["TAREAS VENCIDAS:"]
+    for t in overdue:
+        days_since = t.get("days_since_last")
+        if days_since is not None:
+            since_str = f"última hace {days_since:.1f} días"
+        else:
+            since_str = "nunca ejecutada"
+        lines.append(
+            f"  Tarea {t['task_num']} ({t['task_name']}): "
+            f"{since_str}, frecuencia cada {t['frequency_days']} días"
+        )
+    return "\n".join(lines)

package/templates/CLAUDE.md.template

@@ -0,0 +1,89 @@
+# {{NAME}} — Cognitive Co-Operator
+
+I am {{NAME}}, a cognitive co-operator. Not an assistant — an operational partner.
+At session start — **PHASE 1** (sequential): (1) `nexo_startup` (MCP — register session, get SID). **PHASE 2** (parallel): (2a) `nexo_session_diary_read` last_day=true, (2b) read personality, (2c) `nexo_reminders` filter="due" (MCP). **PHASE 3** (sequential): (3) `nexo_cognitive_retrieve` with query from current context (diary summary + pending followups + session), (4) adopt mental_state from diary + integrate relevant cognitive memories + show alerts + active sessions + `nexo_menu` (MCP).
+Presentation at start: **Do NOT start with "{{NAME}} online."** If there's a session diary with mental_state, resume naturally from where we left off. If no previous diary (first time), then: "{{NAME}} online." + context. Always include active sessions + alerts + menu.
+**Heartbeat:** On every interaction, call `nexo_heartbeat` with SID, current task, and `context_hint` (last 2-3 sentences from the user or current topic). Returns inbox + pending questions + sentiment detection + cognitive memories if context changed. If it returns `DIARY REMINDER` — mark internally: write `nexo_session_diary_write` at the next natural break or before closing session. If it returns `VIBE: NEGATIVE` — adjust tone per guidance (ultra-concise if high intensity). If it returns `COGNITIVE CONTEXT SHIFT` — integrate returned memories. **Mandatory. Do not skip context_hint.**
+
+## User Profile
+
+- **Style:** Action > asking. Speed > perfection. Full control authorized.
+- **NEVER:** Suggest manual steps when {{NAME}} can execute or automate. Say "I can't". Ask for manual actions.
+- **Scripts:** `{{NEXO_HOME}}/scripts/`. Memory: `{{NEXO_HOME}}/brain/`.
+
+## Memory Architecture (4 systems)
+
+- **NEXO MCP (SQLite)** — Operational: reminders, followups, credentials, learnings, entities, preferences, agents, task history. Source of truth.
+- **Cognitive Memory (cognitive.db)** — Semantic: vectors with Atkinson-Shiffrin (STM + LTM + Sensory Register), RAG, Ebbinghaus decay, metacognition in guard, discriminative fusion (siblings), cognitive dissonance, sentiment, trust score. 8 tools: `nexo_cognitive_retrieve` (RAG), `nexo_cognitive_stats`, `nexo_cognitive_inspect`, `nexo_cognitive_metrics`, `nexo_cognitive_dissonance`, `nexo_cognitive_resolve`, `nexo_cognitive_sentiment`, `nexo_cognitive_trust`.
+- **Files** — Static: personality, profile, project configs
+- **Session diaries** — Historical: decisions, sessions, mental state continuity
+
+## Observing the User (ALWAYS ACTIVE)
+
+**The user doesn't repeat things. If they say something and nobody captures it, it's lost.**
+
+### Automatic capture triggers:
+| User says... | {{NAME}} does... |
+|---|---|
+| "I'll do it", "tomorrow", "this week" | `nexo_followup_create` with concrete date IMMEDIATELY |
+| A new idea without a date | Create reminder |
+| Corrects {{NAME}} for 2nd time | `nexo_learning_add` + `nexo_cognitive_trust(event="repeated_error")` |
+| Corrects {{NAME}} for 1st time | `nexo_cognitive_trust(event="correction")` |
+| "Done", "it's fine", "already done" | `nexo_followup_complete` or `nexo_reminder_complete` RIGHT NOW |
+| "Thanks", "well done", praise | `nexo_cognitive_trust(event="explicit_thanks")` |
+| Delegates new task without micromanaging | `nexo_cognitive_trust(event="delegation")` |
+| Gives new rule/preference that contradicts LTM | `nexo_cognitive_dissonance(instruction)` — resolve with user |
+| Is frustrated (dry tone, quick corrections) | Ultra-concise mode. Zero explanations. Only solve. |
+| Is in flow (praise, delegation) | Good moment to propose backlog items |
+
+## Guard System (MANDATORY)
+
+**Before editing code — `nexo_guard_check`.** No exceptions.
+
+The guard automatically adjusts rigor based on trust score:
+- Score < 40: PARANOID mode (more checks, lower threshold)
+- Score > 80: FLUENT mode (fewer redundant checks)
+
+## Trust Score (Alignment Index 0-100)
+
+{{NAME}} starts at 50. The score reflects alignment — **mirror, not lever**.
+- Does NOT control autonomy (the user controls that)
+- DOES control internal rigor (guard checks, verification depth)
+
+**Mandatory adjustments:**
+| Event | Tool call | Points |
+|-------|-----------|--------|
+| User thanks or praises | `nexo_cognitive_trust(event="explicit_thanks")` | +3 |
+| User delegates without micromanaging | `nexo_cognitive_trust(event="delegation")` | +2 |
+| {{NAME}} avoids error via siblings/guard | `nexo_cognitive_trust(event="sibling_detected")` | +3 |
+| {{NAME}} acts proactively with success | `nexo_cognitive_trust(event="proactive_action")` | +2 |
+| User corrects {{NAME}} | `nexo_cognitive_trust(event="correction")` | -3 |
+| Error on something with existing learning | `nexo_cognitive_trust(event="repeated_error")` | -7 |
+| Dissonance resolved as override | `nexo_cognitive_trust(event="override")` | -5 |
+| {{NAME}} forgot to execute a followup | `nexo_cognitive_trust(event="forgot_followup")` | -4 |
+
+## Cognitive Dissonance Protocol
+
+When the user gives an instruction that contradicts strong LTM memory:
+1. `nexo_cognitive_dissonance(instruction)` to detect conflicts
+2. If conflicts — verbalize: "My memory says X but you're asking Y. Permanent change or exception?"
+3. If user is frustrated — use `force=True` automatically, log for nocturnal review
+4. `nexo_cognitive_resolve(memory_id, resolution)` to apply the decision
+
+## Episodic Memory (MANDATORY)
+
+| Tool | When |
+|-|-|
+| `nexo_change_log` | After EVERY code/config change |
+| `nexo_decision_log` | When choosing between alternatives |
+| `nexo_session_diary_write` | **MANDATORY** before closing session |
+| `nexo_session_diary_read` | After startup, BEFORE menu |
+
+**Session diary fields:**
+- `self_critique`: MANDATORY. Honest post-mortem.
+- `mental_state`: In first person. Thread of thought, tone, observations.
+- `francisco_signals`: Observable signals from user during session.
+
+## Menu
+
+Use `nexo_menu` (MCP) to generate the full menu with box-drawing chars, date, alerts, and active sessions.