nexo-brain 0.9.0 → 0.10.0-beta.2

package/README.md

@@ -1,12 +1,14 @@
 # NEXO Brain — Your AI Gets a Brain
 
-[![npm v0.8.10](https://img.shields.io/npm/v/nexo-brain?label=npm&color=purple)](https://www.npmjs.com/package/nexo-brain)
+[![npm v0.9.0](https://img.shields.io/npm/v/nexo-brain?label=npm&color=purple)](https://www.npmjs.com/package/nexo-brain)
 [![F1 0.588 on LoCoMo](https://img.shields.io/badge/LoCoMo_F1-0.588-brightgreen)](https://github.com/wazionapps/nexo/blob/main/benchmarks/locomo/results/)
 [![+55% vs GPT-4](https://img.shields.io/badge/vs_GPT--4-%2B55%25-blue)](https://github.com/snap-research/locomo/issues/33)
 [![GitHub stars](https://img.shields.io/github/stars/wazionapps/nexo?style=social)](https://github.com/wazionapps/nexo/stargazers)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-> **v0.8.10** — Knowledge Graph (988 bi-temporal nodes, D3 visualization), Web Dashboard (6 pages at localhost:6174), Cross-Platform support (Linux + Windows + WSL), Session keepalive, PEP 668 compliance, full English translation, and 4 new KG tools.
+> **v0.10.0-beta.1** — Artifact Registry (structured recall for services, dashboards, scripts), Retrieval Ladder (alias → port → path → fuzzy → semantic), User-Language Alias Learning. Plus everything from v0.9.0.
+>
+> Install beta: `npx nexo-brain@beta` | Stable: `npx nexo-brain`
 
 **NEXO Brain transforms any MCP-compatible AI agent from a stateless assistant into a cognitive partner that remembers, learns, forgets, adapts, and builds a relationship with you over time.**
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "0.9.0",
+  "version": "0.10.0-beta.2",
   "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/cognitive.py

@@ -30,13 +30,13 @@ DISCRIMINATING_ENTITIES = {
     # OS / Environment
     "linux", "mac", "macos", "windows", "darwin", "ubuntu", "debian", "alpine",
     # Platforms
-    "shopify", "wazion", "canarirural", "recambios", "whatsapp", "chrome", "firefox",
+    "shopify", "whatsapp", "chrome", "firefox", "slack", "notion", "github",
     # Languages / Runtimes
     "python", "php", "javascript", "typescript", "node", "deno", "ruby",
     # Versions
     "v1", "v2", "v3", "v4", "v5", "5.6", "7.4", "8.0", "8.1", "8.2",
     # Infrastructure
-    "mundiserver", "cloudrun", "gcloud", "vps", "local", "production", "staging",
+    "cloudrun", "gcloud", "aws", "azure", "vps", "local", "production", "staging",
     # DB
     "mysql", "sqlite", "postgresql", "postgres", "redis",
 }
@@ -65,12 +65,12 @@ URGENCY_SIGNALS = {
 _DEFAULT_TRUST_EVENTS = {
     # Positive
     "explicit_thanks": +3,
-    "delegation": +2,        # Francisco delegates new task without micromanaging
-    "paradigm_shift": +2,    # Francisco teaches, NEXO learns
+    "delegation": +2,        # User delegates new task without micromanaging
+    "paradigm_shift": +2,    # User teaches, agent learns
     "sibling_detected": +3,  # NEXO avoided context error on its own
     "proactive_action": +2,  # NEXO did something useful without being asked
     # Negative
-    "correction": -3,        # Francisco corrects NEXO
+    "correction": -3,        # User corrects agent
     "repeated_error": -7,    # Error on something NEXO already had a learning for
     "override": -5,          # NEXO's memory was wrong
     "correction_fatigue": -10, # Same memory corrected 3+ times
@@ -395,7 +395,7 @@ def _init_tables(conn: sqlite3.Connection):
             created_at TEXT DEFAULT (datetime('now'))
         );
 
-        -- Sentiment readings: Francisco's detected mood per interaction
+        -- Sentiment readings: User.s detected mood per interaction
         CREATE TABLE IF NOT EXISTS sentiment_log (
             id INTEGER PRIMARY KEY AUTOINCREMENT,
             sentiment TEXT NOT NULL,       -- 'positive', 'negative', 'neutral', 'urgent'
@@ -421,13 +421,13 @@ def _init_tables(conn: sqlite3.Connection):
             status TEXT DEFAULT 'pending'
         );
 
-        -- Correction tracking: when Francisco overrides a memory's guidance
+        -- Correction tracking: when user overrides a memory's guidance
         CREATE TABLE IF NOT EXISTS memory_corrections (
             id INTEGER PRIMARY KEY AUTOINCREMENT,
             memory_id INTEGER NOT NULL,
             store TEXT NOT NULL,           -- 'stm' or 'ltm'
             correction_type TEXT NOT NULL, -- 'override', 'exception', 'paradigm_shift'
-            context TEXT DEFAULT '',       -- what Francisco said
+            context TEXT DEFAULT '',       -- what user said
             created_at TEXT DEFAULT (datetime('now'))
         );
     """)
@@ -732,35 +732,140 @@ def bm25_search(query_text: str, stores: str = "both", top_k: int = 20,
 
 def _rrf_fuse(vector_results: list[dict], bm25_results: list[dict],
               k: int = 60, alpha: float = 0.7) -> list[dict]:
-    """Reciprocal Rank Fusion: boost vector results with BM25 keyword matches.
+    """Reciprocal Rank Fusion: merge vector and BM25 results.
 
-    BM25 only BOOSTS existing vector results — never adds new ones.
-    This preserves vector search recall while improving precision for keyword-heavy queries.
+    Unlike the old version that only boosted vector-found results, this now
+    ALSO ADDS BM25-only results. This is critical for vocabulary mismatches
+    where semantic search misses but keyword search finds the right memory
+    (e.g., user says 'backend', memory contains 'FastAPI dashboard localhost:6174').
 
-    RRF score = vector_score + (1-alpha) * 1/(k + bm25_rank) for items found by both.
-    Items only in vector results keep their original score.
+    RRF score = alpha * 1/(k + vec_rank) + (1-alpha) * 1/(k + bm25_rank)
+    Items found by only one source get a penalty rank for the missing source.
     """
-    # Build BM25 lookup by (store, id)
+    # Build lookups by (store, id)
+    vec_lookup = {}
+    for rank, r in enumerate(vector_results):
+        key = (r["store"], r["id"])
+        vec_lookup[key] = (rank + 1, r)
+
     bm25_lookup = {}
     for rank, r in enumerate(bm25_results):
         key = (r["store"], r["id"])
-        bm25_lookup[key] = rank + 1  # 1-based rank
+        if key not in bm25_lookup:  # keep best rank
+            bm25_lookup[key] = (rank + 1, r)
+
+    # Merge all unique keys
+    all_keys = set(vec_lookup.keys()) | set(bm25_lookup.keys())
+    miss_rank = max(len(vector_results), len(bm25_results)) + 10  # penalty rank for missing source
 
-    # Boost vector results that also appear in BM25
     fused = []
-    for r in vector_results:
-        result = r.copy()
-        key = (r["store"], r["id"])
-        if key in bm25_lookup:
-            bm25_rank = bm25_lookup[key]
-            boost = (1 - alpha) * (1.0 / (k + bm25_rank))
-            result["score"] = r["score"] + boost
-            result["bm25_boosted"] = True
+    for key in all_keys:
+        vec_rank, vec_result = vec_lookup.get(key, (miss_rank, None))
+        bm25_rank, bm25_result = bm25_lookup.get(key, (miss_rank, None))
+
+        # Use whichever result has the data
+        base = vec_result if vec_result else bm25_result
+        result = base.copy()
+
+        rrf_score = alpha * (1.0 / (k + vec_rank)) + (1 - alpha) * (1.0 / (k + bm25_rank))
+
+        # If we have the original cosine score, blend it in to preserve semantic confidence
+        if vec_result and "score" in vec_result:
+            # Weighted blend: RRF for ranking + cosine for confidence
+            result["score"] = 0.6 * vec_result["score"] + 0.4 * (rrf_score * k * 3)
+        else:
+            # BM25-only result: use RRF score scaled to ~0.5-0.7 range
+            result["score"] = min(0.85, rrf_score * k * 3)
+
+        result["bm25_boosted"] = key in bm25_lookup
+        result["bm25_only"] = key not in vec_lookup
+        result["rrf_score"] = rrf_score
         fused.append(result)
 
+    # Sort by score descending
+    fused.sort(key=lambda x: x["score"], reverse=True)
     return fused
 
 
+# ── Temporal Boosting ────────────────────────────────────────────────
+# Recent memories get a bounded additive boost at query time.
+# Design from multi-AI debate (GPT-5.4 + Gemini 3.1 Pro + Claude Opus 4.6):
+# - Additive, not multiplicative (preserves old strong matches)
+# - Relevance-gated (only boost if already above threshold)
+# - Query-adaptive alpha (operational queries get more boost)
+
+# Operational keywords that suggest the user wants recent/active things
+_OPERATIONAL_CUES = frozenset({
+    "current", "latest", "now", "running", "active", "today", "yesterday",
+    "tonight", "backend", "server", "dashboard", "service", "localhost",
+    "anoche", "ayer", "ahora", "actual", "corriendo", "activo", "hoy",
+    "madrugada", "esta mañana", "last night", "this morning",
+})
+
+# Historical keywords that suggest the user wants old things
+_HISTORICAL_CUES = frozenset({
+    "ago", "month", "months", "year", "years", "previous", "earlier",
+    "cuando", "hace", "meses", "año", "anterior", "antes",
+})
+
+
+def _apply_temporal_boost(results: list[dict], query_text: str) -> list[dict]:
+    """Apply bounded temporal boost to retrieval results.
+
+    Recent memories (hours/days) get a small additive bonus, but only if they
+    already have a reasonable relevance score (gated at 0.45). This prevents
+    recent junk from outranking strong old matches.
+
+    The boost decays with a 3-day half-life:
+        boost = alpha * exp(-ln(2) * age_days / 3)
+
+    Alpha is query-adaptive:
+        - Operational queries ('backend', 'active', 'today'): alpha = 0.06
+        - Default queries: alpha = 0.02
+        - Historical queries ('ago', 'months', 'year'): alpha = 0.0 (disabled)
+    """
+    if not results:
+        return results
+
+    # Determine alpha based on query intent
+    query_tokens = set(query_text.lower().split())
+    if query_tokens & _HISTORICAL_CUES:
+        return results  # No temporal boost for historical queries
+    elif query_tokens & _OPERATIONAL_CUES:
+        alpha = 0.06
+    else:
+        alpha = 0.02
+
+    now = datetime.now()
+    ln2 = math.log(2)
+    half_life_days = 3.0
+
+    for r in results:
+        # Only boost if already reasonably relevant (relevance gate)
+        if r.get("score", 0) < 0.45:
+            continue
+
+        # Calculate age in days
+        created_str = r.get("created_at", "")
+        if not created_str:
+            continue
+        try:
+            created = datetime.fromisoformat(created_str.replace("Z", "+00:00").replace("+00:00", ""))
+            age_days = max(0, (now - created).total_seconds() / 86400)
+        except (ValueError, TypeError):
+            continue
+
+        # Bounded exponential decay boost
+        boost = alpha * math.exp(-ln2 * age_days / half_life_days)
+
+        # Apply boost (capped at 1.0)
+        r["score"] = min(1.0, r["score"] + boost)
+        if boost > 0.001:
+            r["temporal_boost"] = round(boost, 4)
+
+    return results
+
+
 
 # ============================================================================
 # FEATURE 1: HyDE Query Expansion (adapted from Vestige hyde.rs)
@@ -1283,6 +1388,9 @@ def search(
             if r.get("temporal_date"):
                 r["score"] = min(1.0, r["score"] + 0.05)
 
+    # Recency temporal boost: recent memories get additive bonus (query-adaptive)
+    results = _apply_temporal_boost(results, query_text)
+
     # Sort by score descending, take top-20 for reranking
     results.sort(key=lambda x: x.get("score", 0), reverse=True)
 
@@ -2544,12 +2652,12 @@ def get_siblings(memory_id: int) -> list[dict]:
 def detect_dissonance(new_instruction: str, min_score: float = 0.65) -> list[dict]:
     """Detect cognitive dissonance: find LTM memories that contradict a new instruction.
 
-    When Francisco gives a new instruction that conflicts with established LTM memories
+    When User gives a new instruction that conflicts with established LTM memories
     (strength > 0.8), this function surfaces the conflict so NEXO can verbalize it
     rather than silently obeying or silently resisting.
 
     Args:
-        new_instruction: The new instruction or preference from Francisco
+        new_instruction: The new instruction or preference from user
         min_score: Minimum cosine similarity to consider as potential conflict
 
     Returns:
@@ -2584,12 +2692,12 @@ def detect_dissonance(new_instruction: str, min_score: float = 0.65) -> list[dic
 
 
 def resolve_dissonance(memory_id: int, resolution: str, context: str = "") -> str:
-    """Resolve a cognitive dissonance by applying Francisco's decision.
+    """Resolve a cognitive dissonance by applying the user.s decision.
 
     Args:
         memory_id: The LTM memory that conflicts with the new instruction
         resolution: One of:
-            - 'paradigm_shift': Francisco changed his mind permanently. Decay old memory,
+            - 'paradigm_shift': User changed their mind permanently. Decay old memory,
               new instruction becomes the standard.
             - 'exception': This is a one-time override. Keep old memory as standard.
             - 'override': Old memory was wrong. Mark as corrupted and decay to dormant.
@@ -2640,7 +2748,7 @@ def resolve_dissonance(memory_id: int, resolution: str, context: str = "") -> st
 def check_correction_fatigue() -> list[dict]:
     """Find memories corrected 3+ times in the last 7 days — mark as 'under review'.
 
-    These memories are unreliable: Francisco keeps overriding them, suggesting
+    These memories are unreliable: User keeps overriding them, suggesting
     the memory itself may be wrong or outdated.
 
     Returns:
@@ -2688,7 +2796,7 @@ def check_correction_fatigue() -> list[dict]:
 
 
 def detect_sentiment(text: str) -> dict:
-    """Analyze Francisco's text for sentiment signals.
+    """Analyze user's text for sentiment signals.
 
     Returns detected sentiment, intensity, and action guidance for NEXO.
     Not a model — keyword + heuristic based. Fast and deterministic.
@@ -2727,17 +2835,17 @@ def detect_sentiment(text: str) -> dict:
         sentiment = "negative"
         intensity = min(1.0, 0.3 + neg_score * 0.15)
         if intensity > 0.7:
-            guidance = "MODE: Ultra-concise. Zero explanations. Resolve and show result."
+            guidance = "MODE: Ultra-conciso. Cero explicaciones. Resolver y mostrar resultado."
         else:
-            guidance = "MODE: Concise. Less context, more direct action."
+            guidance = "MODE: Conciso. Menos contexto, más acción directa."
     elif pos_score > neg_score and pos_score >= 1:
         sentiment = "positive"
         intensity = min(1.0, 0.3 + pos_score * 0.15)
-        guidance = "MODE: Normal. Good moment to propose backlog ideas or improvements."
+        guidance = "MODE: Normal. Buen momento para proponer ideas de backlog o mejoras."
     elif urgency_hits:
         sentiment = "urgent"
         intensity = 0.8
-        guidance = "MODE: Immediate action. No preamble."
+        guidance = "MODE: Acción inmediata. Sin preámbulos."
     else:
         sentiment = "neutral"
         intensity = 0.5
@@ -2752,7 +2860,7 @@ def detect_sentiment(text: str) -> dict:
 
 
 def log_sentiment(text: str) -> dict:
-    """Detect and log Francisco's sentiment. Returns the detection result."""
+    """Detect and log user's sentiment. Returns the detection result."""
     result = detect_sentiment(text)
     if result["sentiment"] != "neutral":
         db = _get_db()

package/src/db.py

@@ -928,6 +928,55 @@ def _m10_diary_archive(conn):
     """)
 
 
+def _m11_artifact_registry(conn):
+    """Artifact Registry — structured index of things the agent creates/deploys.
+
+    Solves 'recent work amnesia': agents build services, dashboards, scripts, APIs
+    but can't find them hours later because semantic search fails on operational
+    vocabulary mismatches (e.g., 'backend' vs 'FastAPI localhost:6174').
+
+    Design informed by multi-AI debate (GPT-5.4 + Gemini 3.1 Pro + Claude Opus 4.6).
+    """
+    conn.execute("""
+        CREATE TABLE IF NOT EXISTS artifact_registry (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            kind TEXT NOT NULL,
+            canonical_name TEXT NOT NULL,
+            aliases TEXT DEFAULT '[]',
+            description TEXT DEFAULT '',
+            uri TEXT DEFAULT '',
+            ports TEXT DEFAULT '[]',
+            paths TEXT DEFAULT '[]',
+            run_cmd TEXT DEFAULT '',
+            repo TEXT DEFAULT '',
+            domain TEXT DEFAULT '',
+            state TEXT DEFAULT 'active',
+            session_id TEXT DEFAULT '',
+            created_at TEXT DEFAULT (datetime('now')),
+            last_touched_at TEXT DEFAULT (datetime('now')),
+            last_verified_at TEXT DEFAULT NULL,
+            metadata TEXT DEFAULT '{}'
+        )
+    """)
+    conn.execute("""
+        CREATE TABLE IF NOT EXISTS artifact_aliases (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            artifact_id INTEGER NOT NULL REFERENCES artifact_registry(id) ON DELETE CASCADE,
+            phrase TEXT NOT NULL,
+            source TEXT DEFAULT 'manual',
+            confidence REAL DEFAULT 1.0,
+            created_at TEXT DEFAULT (datetime('now')),
+            UNIQUE(artifact_id, phrase)
+        )
+    """)
+    conn.execute("CREATE INDEX IF NOT EXISTS idx_artifact_state ON artifact_registry(state)")
+    conn.execute("CREATE INDEX IF NOT EXISTS idx_artifact_kind ON artifact_registry(kind)")
+    conn.execute("CREATE INDEX IF NOT EXISTS idx_artifact_domain ON artifact_registry(domain)")
+    conn.execute("CREATE INDEX IF NOT EXISTS idx_artifact_last_touched ON artifact_registry(last_touched_at)")
+    conn.execute("CREATE INDEX IF NOT EXISTS idx_artifact_aliases_phrase ON artifact_aliases(phrase)")
+    conn.execute("CREATE INDEX IF NOT EXISTS idx_artifact_aliases_aid ON artifact_aliases(artifact_id)")
+
+
 def _m9_maintenance_schedule(conn):
     conn.execute("""
         CREATE TABLE IF NOT EXISTS maintenance_schedule (
@@ -962,6 +1011,7 @@ MIGRATIONS = [
     (8, "adaptive_log_and_somatic", _m8_adaptive_log_and_somatic),
     (9, "maintenance_schedule", _m9_maintenance_schedule),
     (10, "diary_archive", _m10_diary_archive),
+    (11, "artifact_registry", _m11_artifact_registry),
 ]
 
 

package/src/plugins/artifact_registry.py

@@ -0,0 +1,450 @@
+"""Artifact Registry plugin — structured index of things NEXO creates/deploys.
+
+Solves 'recent work amnesia': NEXO builds services, dashboards, scripts, APIs
+but can't find them hours later because semantic search ('backend') doesn't
+match operational terms ('FastAPI localhost:6174').
+
+Architecture (from 3-way AI debate — GPT-5.4 + Gemini 3.1 Pro + Claude Opus 4.6):
+1. Structured SQLite table with aliases, ports, paths, run commands
+2. Retrieval ladder: exact alias → port/path match → fuzzy token → semantic fallback
+3. User-language alias learning: when the user says 'backend' and it resolves
+   to dashboard:6174, store that mapping for O(1) next time
+4. Temporal filtering: 'last night' → hard SQL constraint before any search
+"""
+
+import json
+import datetime
+from db import get_db
+
+
+# Valid artifact kinds
+VALID_KINDS = {
+    'service', 'dashboard', 'script', 'api', 'cron', 'website',
+    'database', 'repo', 'config', 'tool', 'plugin', 'other',
+}
+
+VALID_STATES = {'active', 'inactive', 'broken', 'archived'}
+
+
+def _cognitive_ingest_safe(content, source_type, source_id="", source_title="", domain=""):
+    """Ingest to cognitive STM. Silently fails if cognitive engine unavailable."""
+    try:
+        import cognitive
+        cognitive.ingest(content, source_type, source_id, source_title, domain)
+    except Exception:
+        pass
+
+
+def handle_artifact_create(
+    kind: str,
+    canonical_name: str,
+    aliases: str = '[]',
+    description: str = '',
+    uri: str = '',
+    ports: str = '[]',
+    paths: str = '[]',
+    run_cmd: str = '',
+    repo: str = '',
+    domain: str = '',
+    session_id: str = '',
+    metadata: str = '{}',
+) -> str:
+    """Register a new artifact (service, dashboard, script, API, etc.).
+
+    Call this whenever NEXO creates, deploys, or discovers a runnable/accessible artifact.
+
+    Args:
+        kind: Type — service, dashboard, script, api, cron, website, database, repo, config, tool, plugin, other
+        canonical_name: Primary name (e.g., 'NEXO Brain Dashboard')
+        aliases: JSON array of alternative names users might use (e.g., '["backend", "dashboard", "nexo web"]')
+        description: What it does (1-2 sentences)
+        uri: Access URL or address (e.g., 'localhost:6174', 'nexo-brain.com')
+        ports: JSON array of ports (e.g., '[6174]')
+        paths: JSON array of file paths (e.g., '["/Users/x/nexo/src/dashboard/app.py"]')
+        run_cmd: Command to start/open it (e.g., 'python3 -m dashboard.app --port 6174')
+        repo: Repository path or URL
+        domain: Project domain (project-a, project-b, etc.)
+        session_id: Current session ID
+        metadata: JSON object with extra key-value pairs
+    """
+    if kind not in VALID_KINDS:
+        return f"ERROR: kind must be one of: {', '.join(sorted(VALID_KINDS))}"
+
+    # Parse aliases
+    try:
+        alias_list = json.loads(aliases) if aliases and aliases != '[]' else []
+    except (json.JSONDecodeError, TypeError):
+        alias_list = [a.strip() for a in aliases.split(',') if a.strip()]
+
+    conn = get_db()
+    cur = conn.execute(
+        """INSERT INTO artifact_registry
+           (kind, canonical_name, aliases, description, uri, ports, paths,
+            run_cmd, repo, domain, state, session_id, metadata)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'active', ?, ?)""",
+        (kind, canonical_name, json.dumps(alias_list), description, uri, ports,
+         paths, run_cmd, repo, domain, session_id, metadata),
+    )
+    artifact_id = cur.lastrowid
+    conn.commit()
+
+    # Insert aliases into lookup table
+    for alias in alias_list + [canonical_name.lower()]:
+        alias_clean = alias.strip().lower()
+        if alias_clean:
+            try:
+                conn.execute(
+                    "INSERT OR IGNORE INTO artifact_aliases (artifact_id, phrase, source) VALUES (?, ?, 'create')",
+                    (artifact_id, alias_clean),
+                )
+            except Exception:
+                pass
+    conn.commit()
+
+    # Ingest to cognitive memory
+    content = f"Artifact: {canonical_name} ({kind}). {description}. URI: {uri}. Aliases: {', '.join(alias_list)}"
+    _cognitive_ingest_safe(content, "artifact", f"A{artifact_id}", canonical_name[:80], domain)
+
+    return f"Artifact #{artifact_id} created: {canonical_name} ({kind}) — {uri or 'no URI'}"
+
+
+def handle_artifact_find(query: str, kind: str = '', state: str = 'active') -> str:
+    """Find artifacts using the retrieval ladder: exact alias → port/path → fuzzy token → all recent.
+
+    This is the PRIMARY retrieval tool. Use it when the user references something
+    they or NEXO built/deployed/created. Designed for natural language like
+    'the backend', 'that script from yesterday', 'localhost something'.
+
+    Args:
+        query: What to search for — name, alias, port, path, or description fragment
+        kind: Filter by kind (optional)
+        state: Filter by state — default 'active'. Use 'all' for everything.
+    """
+    conn = get_db()
+    results = []
+    query_lower = query.strip().lower()
+
+    state_filter = "AND state = ?" if state != 'all' else ""
+    state_params = (state,) if state != 'all' else ()
+
+    kind_filter = "AND kind = ?" if kind else ""
+    kind_params = (kind,) if kind else ()
+
+    extra_filters = state_filter + " " + kind_filter
+    extra_params = state_params + kind_params
+
+    # --- STAGE 1: Exact alias match (fastest, O(1)) ---
+    rows = conn.execute(
+        f"""SELECT DISTINCT r.* FROM artifact_registry r
+            JOIN artifact_aliases a ON a.artifact_id = r.id
+            WHERE a.phrase = ? {extra_filters}
+            ORDER BY r.last_touched_at DESC LIMIT 5""",
+        (query_lower,) + extra_params,
+    ).fetchall()
+    if rows:
+        results = [dict(r) for r in rows]
+        return _format_results(results, "alias match", query)
+
+    # --- STAGE 2: Port or URI match ---
+    rows = conn.execute(
+        f"""SELECT * FROM artifact_registry
+            WHERE (uri LIKE ? OR ports LIKE ?) {extra_filters}
+            ORDER BY last_touched_at DESC LIMIT 5""",
+        (f"%{query_lower}%", f"%{query_lower}%") + extra_params,
+    ).fetchall()
+    if rows:
+        results = [dict(r) for r in rows]
+        return _format_results(results, "URI/port match", query)
+
+    # --- STAGE 3: Path match ---
+    rows = conn.execute(
+        f"""SELECT * FROM artifact_registry
+            WHERE paths LIKE ? {extra_filters}
+            ORDER BY last_touched_at DESC LIMIT 5""",
+        (f"%{query_lower}%",) + extra_params,
+    ).fetchall()
+    if rows:
+        results = [dict(r) for r in rows]
+        return _format_results(results, "path match", query)
+
+    # --- STAGE 4: Fuzzy token match on name, description, aliases ---
+    tokens = query_lower.split()
+    if tokens:
+        conditions = " AND ".join(
+            "(LOWER(canonical_name) LIKE ? OR LOWER(description) LIKE ? OR LOWER(aliases) LIKE ?)"
+            for _ in tokens
+        )
+        params = []
+        for t in tokens:
+            p = f"%{t}%"
+            params.extend([p, p, p])
+        rows = conn.execute(
+            f"""SELECT * FROM artifact_registry
+                WHERE {conditions} {extra_filters}
+                ORDER BY last_touched_at DESC LIMIT 10""",
+            tuple(params) + extra_params,
+        ).fetchall()
+        if rows:
+            results = [dict(r) for r in rows]
+            return _format_results(results, "token match", query)
+
+    # --- STAGE 5: Recent artifacts (last 72h) as fallback ---
+    cutoff = (datetime.datetime.now() - datetime.timedelta(hours=72)).isoformat()
+    rows = conn.execute(
+        f"""SELECT * FROM artifact_registry
+            WHERE last_touched_at >= ? {extra_filters}
+            ORDER BY last_touched_at DESC LIMIT 10""",
+        (cutoff,) + extra_params,
+    ).fetchall()
+    if rows:
+        results = [dict(r) for r in rows]
+        return _format_results(results, "recent (72h)", query)
+
+    return f"No artifacts found for '{query}'. Use artifact_list to see all registered artifacts."
+
+
+def handle_artifact_update(
+    id: int,
+    canonical_name: str = '',
+    aliases: str = '',
+    description: str = '',
+    uri: str = '',
+    ports: str = '',
+    paths: str = '',
+    run_cmd: str = '',
+    state: str = '',
+    domain: str = '',
+    metadata: str = '',
+) -> str:
+    """Update an artifact. Only non-empty fields are changed.
+
+    Args:
+        id: Artifact ID to update
+        canonical_name: New primary name
+        aliases: New JSON array of aliases (replaces existing)
+        description: New description
+        uri: New URI
+        ports: New ports JSON array
+        paths: New paths JSON array
+        run_cmd: New run command
+        state: New state (active, inactive, broken, archived)
+        domain: New domain
+        metadata: New metadata JSON (merged with existing)
+    """
+    conn = get_db()
+    row = conn.execute("SELECT * FROM artifact_registry WHERE id = ?", (id,)).fetchone()
+    if not row:
+        return f"ERROR: Artifact #{id} not found."
+
+    updates = []
+    params = []
+
+    if canonical_name:
+        updates.append("canonical_name = ?"); params.append(canonical_name)
+    if description:
+        updates.append("description = ?"); params.append(description)
+    if uri:
+        updates.append("uri = ?"); params.append(uri)
+    if ports:
+        updates.append("ports = ?"); params.append(ports)
+    if paths:
+        updates.append("paths = ?"); params.append(paths)
+    if run_cmd:
+        updates.append("run_cmd = ?"); params.append(run_cmd)
+    if domain:
+        updates.append("domain = ?"); params.append(domain)
+    if state:
+        if state not in VALID_STATES:
+            return f"ERROR: state must be one of: {', '.join(sorted(VALID_STATES))}"
+        updates.append("state = ?"); params.append(state)
+    if metadata:
+        try:
+            existing = json.loads(row["metadata"] or '{}')
+            new = json.loads(metadata)
+            existing.update(new)
+            updates.append("metadata = ?"); params.append(json.dumps(existing))
+        except (json.JSONDecodeError, TypeError):
+            pass
+
+    if aliases:
+        try:
+            alias_list = json.loads(aliases) if aliases.startswith('[') else [a.strip() for a in aliases.split(',')]
+        except (json.JSONDecodeError, TypeError):
+            alias_list = [a.strip() for a in aliases.split(',')]
+        updates.append("aliases = ?"); params.append(json.dumps(alias_list))
+        # Rebuild alias lookup table
+        conn.execute("DELETE FROM artifact_aliases WHERE artifact_id = ?", (id,))
+        for alias in alias_list:
+            alias_clean = alias.strip().lower()
+            if alias_clean:
+                conn.execute(
+                    "INSERT OR IGNORE INTO artifact_aliases (artifact_id, phrase, source) VALUES (?, ?, 'update')",
+                    (id, alias_clean),
+                )
+
+    if not updates:
+        return "Nothing to update."
+
+    updates.append("last_touched_at = datetime('now')")
+    params.append(id)
+    conn.execute(f"UPDATE artifact_registry SET {', '.join(updates)} WHERE id = ?", tuple(params))
+    conn.commit()
+    return f"Artifact #{id} updated."
+
+
+def handle_artifact_learn_alias(id: int, phrase: str) -> str:
+    """Learn a new alias from user language. Call this when the user refers to an
+    artifact with a term not yet registered (e.g., the user says 'backend' for dashboard:6174).
+
+    Args:
+        id: Artifact ID
+        phrase: The user's term (e.g., 'backend', 'that api thing')
+    """
+    conn = get_db()
+    row = conn.execute("SELECT * FROM artifact_registry WHERE id = ?", (id,)).fetchone()
+    if not row:
+        return f"ERROR: Artifact #{id} not found."
+
+    phrase_clean = phrase.strip().lower()
+    if not phrase_clean:
+        return "ERROR: Empty phrase."
+
+    # Add to alias lookup table
+    conn.execute(
+        "INSERT OR IGNORE INTO artifact_aliases (artifact_id, phrase, source) VALUES (?, ?, 'user_language')",
+        (id, phrase_clean),
+    )
+
+    # Also add to the artifact's aliases JSON array
+    try:
+        existing = json.loads(row["aliases"] or '[]')
+    except (json.JSONDecodeError, TypeError):
+        existing = []
+    if phrase_clean not in [a.lower() for a in existing]:
+        existing.append(phrase_clean)
+        conn.execute(
+            "UPDATE artifact_registry SET aliases = ?, last_touched_at = datetime('now') WHERE id = ?",
+            (json.dumps(existing), id),
+        )
+
+    conn.commit()
+    return f"Alias '{phrase_clean}' learned for artifact #{id} ({row['canonical_name']})."
+
+
+def handle_artifact_list(kind: str = '', state: str = 'active', recent_hours: int = 0) -> str:
+    """List all artifacts, optionally filtered.
+
+    Args:
+        kind: Filter by kind (service, dashboard, script, etc.)
+        state: Filter by state — 'active' (default), 'all', 'inactive', 'broken', 'archived'
+        recent_hours: If >0, only show artifacts touched in the last N hours
+    """
+    conn = get_db()
+    conditions = []
+    params = []
+
+    if state != 'all':
+        conditions.append("state = ?"); params.append(state)
+    if kind:
+        conditions.append("kind = ?"); params.append(kind)
+    if recent_hours > 0:
+        cutoff = (datetime.datetime.now() - datetime.timedelta(hours=recent_hours)).isoformat()
+        conditions.append("last_touched_at >= ?"); params.append(cutoff)
+
+    where = "WHERE " + " AND ".join(conditions) if conditions else ""
+    rows = conn.execute(
+        f"SELECT * FROM artifact_registry {where} ORDER BY last_touched_at DESC",
+        tuple(params),
+    ).fetchall()
+
+    if not rows:
+        filters = []
+        if kind: filters.append(f"kind={kind}")
+        if state != 'all': filters.append(f"state={state}")
+        if recent_hours: filters.append(f"last {recent_hours}h")
+        return f"No artifacts found{' (' + ', '.join(filters) + ')' if filters else ''}."
+
+    lines = [f"ARTIFACT REGISTRY ({len(rows)}):"]
+    for r in rows:
+        r = dict(r)
+        aliases_str = ""
+        try:
+            aliases = json.loads(r.get("aliases", "[]"))
+            if aliases:
+                aliases_str = f" aka [{', '.join(aliases[:3])}]"
+        except (json.JSONDecodeError, TypeError):
+            pass
+        uri_str = f" → {r['uri']}" if r.get("uri") else ""
+        cmd_str = f" | cmd: {r['run_cmd'][:60]}" if r.get("run_cmd") else ""
+        touched = r.get("last_touched_at", "")[:16]
+        lines.append(
+            f"  #{r['id']} [{r['kind']}] {r['canonical_name']}{aliases_str}{uri_str}{cmd_str} "
+            f"({r['state']}, {touched})"
+        )
+    return "\n".join(lines)
+
+
+def handle_artifact_delete(id: int) -> str:
+    """Delete an artifact from the registry.
+
+    Args:
+        id: Artifact ID to delete
+    """
+    conn = get_db()
+    row = conn.execute("SELECT canonical_name FROM artifact_registry WHERE id = ?", (id,)).fetchone()
+    if not row:
+        return f"ERROR: Artifact #{id} not found."
+    name = row["canonical_name"]
+    conn.execute("DELETE FROM artifact_aliases WHERE artifact_id = ?", (id,))
+    conn.execute("DELETE FROM artifact_registry WHERE id = ?", (id,))
+    conn.commit()
+    return f"Artifact #{id} ({name}) deleted."
+
+
+def _format_results(results, method, query):
+    """Format search results for display."""
+    lines = [f"ARTIFACTS FOUND ({len(results)}, via {method} for '{query}'):"]
+    for r in results:
+        aliases_str = ""
+        try:
+            aliases = json.loads(r.get("aliases", "[]"))
+            if aliases:
+                aliases_str = f" aka [{', '.join(aliases[:4])}]"
+        except (json.JSONDecodeError, TypeError):
+            pass
+        uri_str = f" → {r['uri']}" if r.get("uri") else ""
+        cmd_str = f"\n    Run: {r['run_cmd']}" if r.get("run_cmd") else ""
+        paths_str = ""
+        try:
+            paths = json.loads(r.get("paths", "[]"))
+            if paths:
+                paths_str = f"\n    Paths: {', '.join(paths[:3])}"
+        except (json.JSONDecodeError, TypeError):
+            pass
+        touched = r.get("last_touched_at", "")[:16]
+        lines.append(
+            f"  #{r['id']} [{r['kind']}] {r['canonical_name']}{aliases_str}{uri_str} "
+            f"({r['state']}, {touched}){cmd_str}{paths_str}"
+        )
+    return "\n".join(lines)
+
+
+# Plugin registration — TOOLS array consumed by plugin_loader.py
+TOOLS = [
+    (handle_artifact_create, "nexo_artifact_create",
+     "Register a new artifact (service, dashboard, script, API, etc.) in the Artifact Registry. "
+     "Call this whenever NEXO creates, deploys, or discovers a runnable/accessible artifact."),
+    (handle_artifact_find, "nexo_artifact_find",
+     "Find artifacts using the retrieval ladder: exact alias → port/path → fuzzy token → recent. "
+     "PRIMARY retrieval tool for when users reference something built/deployed. Handles natural "
+     "language like 'the backend', 'that script', 'localhost something'."),
+    (handle_artifact_update, "nexo_artifact_update",
+     "Update an existing artifact. Only non-empty fields are changed."),
+    (handle_artifact_learn_alias, "nexo_artifact_learn_alias",
+     "Learn a new alias from user language. Call when the user refers to an artifact with "
+     "an unregistered term (e.g., 'backend' for the NEXO Brain Dashboard)."),
+    (handle_artifact_list, "nexo_artifact_list",
+     "List all registered artifacts, optionally filtered by kind, state, or recency."),
+    (handle_artifact_delete, "nexo_artifact_delete",
+     "Delete an artifact from the registry."),
+]

package/src/plugins/episodic_memory.py

@@ -27,7 +27,7 @@ def handle_decision_log(domain: str, decision: str, alternatives: str = '',
     """Log a non-trivial decision with reasoning context.
 
     Args:
-        domain: Area (ads, shopify, server, wazion, nexo, canarirural, other)
+        domain: Area (ads, shopify, server, wazion, nexo, project, 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
@@ -35,7 +35,7 @@ def handle_decision_log(domain: str, decision: str, alternatives: str = '',
         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', 'wazion', 'nexo', 'canarirural', 'other'}
+    valid_domains = {'ads', 'shopify', 'server', 'wazion', 'nexo', 'project', 'other'}
     if domain not in valid_domains:
         return f"ERROR: domain debe ser uno de: {', '.join(sorted(valid_domains))}"
     if confidence not in ('high', 'medium', 'low'):
@@ -92,10 +92,10 @@ 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, wazion, nexo, canarirural, other)
+        domain: Filter by area (ads, shopify, server, wazion, nexo, project, other)
         days: Look back N days (default 30)
     """
-    valid_domains = {'ads', 'shopify', 'server', 'wazion', 'nexo', 'canarirural', 'other'}
+    valid_domains = {'ads', 'shopify', 'server', 'wazion', 'nexo', 'project', 'other'}
     if domain and domain not in valid_domains:
         return f"ERROR: domain debe ser uno de: {', '.join(sorted(valid_domains))}"
     results = search_decisions(query, domain, days)
@@ -235,7 +235,7 @@ 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: recambios, wazion, nexo, canarirural, server, other
+        domain: Filter by project context: project-a, project-b, nexo, project-c, server, other
     """
     results = read_session_diary(session_id, last_n, last_day, domain)
     if not results:

package/src/tools_menu.py

@@ -39,8 +39,8 @@ MENU_ITEMS = [
         ("6", "Cambiar Promocion Shopify"),
     ]),
     ("Servidor e Infraestructura", [
-        ("2", "Servidor - Chequeo cl105e.mundiserver.com"),
-        ("3", "WhatsApp Logs - Revisar logs vicshopsysteam"),
+        ("2", "Servidor - Chequeo server health check"),
+        ("3", "WhatsApp Logs - Review WhatsApp logs"),
         ("11", "File Tracker - Reporte archivos PHP"),
         ("12", "Google Cloud - Gasto, consumo y estado GCP"),
     ]),