nexo-brain 5.3.20 → 5.3.21

package/src/plugins/impact 2.py

@@ -0,0 +1,29 @@
+"""Impact scoring plugin — prioritize followups by expected impact, not only by date."""
+
+from __future__ import annotations
+
+import json
+
+from db import get_followup, score_followup
+
+
+def handle_impact_score(followup_id: str) -> str:
+    """Compute and persist Impact Scoring v1 for one followup."""
+    row = get_followup(followup_id)
+    if not row:
+        return f"ERROR: Followup {followup_id} not found."
+    scored = score_followup(followup_id)
+    if "error" in scored:
+        return f"ERROR: {scored['error']}"
+    payload = {
+        "followup_id": followup_id,
+        "impact_score": scored.get("impact_score", 0),
+        "factors": scored.get("impact_factors", {}),
+        "reasoning": scored.get("impact_reasoning", ""),
+    }
+    return json.dumps(payload, ensure_ascii=False, indent=2)
+
+
+TOOLS = [
+    (handle_impact_score, "nexo_impact_score", "Compute and persist Impact Scoring v1 for a followup so queues can prioritize by expected impact."),
+]

package/src/plugins/knowledge_graph_tools 2.py

@@ -0,0 +1,137 @@
+"""Knowledge Graph MCP tools — query, path, neighbors, stats."""
+import os
+import sys
+
+sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)), ".."))
+import knowledge_graph as kg
+
+
+def _find_node(node_type: str, node_ref: str):
+    """Find a node, trying both raw ref and type-prefixed ref (area:X, file:X)."""
+    node = kg.get_node(node_type, node_ref)
+    if not node:
+        node = kg.get_node(node_type, f"{node_type}:{node_ref}")
+    return node
+
+
+def handle_kg_query(node_type: str, node_ref: str, depth: int = 2, relation: str = "") -> str:
+    """Traverse the knowledge graph from a node up to `depth` hops."""
+    node = _find_node(node_type, node_ref)
+    if not node:
+        return f"Node not found: {node_type}/{node_ref}"
+    result = kg.traverse(node["id"], max_depth=depth, relation_filter=relation or None)
+    nodes = result["nodes"][:30]
+    edges = result["edges"][:30]
+    lines = [f"KG TRAVERSE — {node['label']} ({node_type}/{node_ref}) depth={depth}"]
+    lines.append(f"Nodes: {len(result['nodes'])}  Edges: {len(result['edges'])}")
+    lines.append("")
+    lines.append("NODES:")
+    for n in nodes:
+        indent = "  " * n.get("depth", 0)
+        lines.append(f"  {indent}[{n['id']}] ({n['node_type']}) {n['label']} — {n['node_ref']}")
+    lines.append("")
+    lines.append("EDGES:")
+    for e in edges[:20]:
+        lines.append(f"  [{e['source_id']}] --{e['relation']}--> [{e['target_id']}]  w={e['weight']}")
+    return "\n".join(lines)
+
+
+def handle_kg_path(from_type: str, from_ref: str, to_type: str, to_ref: str) -> str:
+    """Find the shortest path between two nodes in the knowledge graph."""
+    from_node = _find_node(from_type, from_ref)
+    if not from_node:
+        return f"Source node not found: {from_type}/{from_ref}"
+    to_node = _find_node(to_type, to_ref)
+    if not to_node:
+        return f"Target node not found: {to_type}/{to_ref}"
+    path_ids = kg.shortest_path(from_node["id"], to_node["id"])
+    if not path_ids:
+        return f"No path found between {from_ref} and {to_ref}"
+    lines = [f"PATH ({len(path_ids) - 1} hops): {from_ref} → {to_ref}"]
+    for i, nid in enumerate(path_ids):
+        node = kg.get_node_by_id(nid)
+        label = node["label"] if node else f"[{nid}]"
+        ntype = node["node_type"] if node else "?"
+        lines.append(f"  {i}. [{nid}] ({ntype}) {label}")
+    return "\n".join(lines)
+
+
+def handle_kg_neighbors(node_type: str, node_ref: str, relation: str = "") -> str:
+    """Get direct neighbors of a node, optionally filtered by relation type."""
+    node = _find_node(node_type, node_ref)
+    if not node:
+        return f"Node not found: {node_type}/{node_ref}"
+    neighbors = kg.get_neighbors(node["id"], relation=relation or None)
+    if not neighbors:
+        rel_info = f" (relation={relation})" if relation else ""
+        return f"No neighbors found for {node['label']}{rel_info}"
+    lines = [f"NEIGHBORS of [{node['id']}] {node['label']} ({len(neighbors)} total):"]
+    for n in neighbors[:30]:
+        direction = n.get("direction", "?")
+        arrow = "-->" if direction == "outgoing" else "<--"
+        lines.append(f"  {arrow} [{n['id']}] {n['label']} ({n['node_type']})  rel={n['relation']}  w={n['weight']}")
+    if len(neighbors) > 30:
+        lines.append(f"  ... +{len(neighbors) - 30} more")
+    return "\n".join(lines)
+
+
+def handle_kg_stats() -> str:
+    """Return knowledge graph statistics: node counts, edge counts, top connected nodes."""
+    s = kg.stats()
+    lines = ["KNOWLEDGE GRAPH STATS"]
+    lines.append(f"  Nodes: {s['nodes']}")
+    lines.append(f"  Edges (active): {s['edges_active']}")
+    lines.append(f"  Edges (historical): {s['edges_historical']}")
+    if s["node_types"]:
+        lines.append("\nNODE TYPES:")
+        for t, cnt in sorted(s["node_types"].items(), key=lambda x: -x[1]):
+            lines.append(f"  {t}: {cnt}")
+    if s["relation_types"]:
+        lines.append("\nRELATION TYPES:")
+        for r, cnt in sorted(s["relation_types"].items(), key=lambda x: -x[1])[:20]:
+            lines.append(f"  {r}: {cnt}")
+    if s["most_connected"]:
+        lines.append("\nMOST CONNECTED:")
+        for n in s["most_connected"][:10]:
+            lines.append(f"  [{n['id']}] {n['label']} ({n['node_type']}) — {n['connections']} connections")
+    return "\n".join(lines)
+
+
+def handle_kg_export(format: str = "jsonld", as_of: str = "") -> str:
+    """Export the bitemporal knowledge graph to a standard interchange format.
+
+    Closes Fase 5 item 1 of NEXO-AUDIT-2026-04-11. The KG was already
+    bitemporal (kg_edges has valid_from and valid_until and the
+    upsert/delete helpers maintain them), but had no way to emit the
+    graph in a format external tools can ingest. This tool wraps the
+    two canonical exporters in cognitive.knowledge_graph.
+
+    Args:
+        format: 'jsonld' (default, semantic web / human-readable) or
+                'graphml' (igraph, Gephi, NetworkX, Cytoscape).
+        as_of: Optional ISO timestamp. If empty, exports the active
+                snapshot. If provided, exports the historical snapshot
+                that was valid at that instant.
+    """
+    import json as _json
+    import knowledge_graph as kg
+
+    fmt = (format or "jsonld").strip().lower()
+    if fmt == "jsonld":
+        payload = kg.export_to_jsonld(as_of=as_of)
+        return _json.dumps(payload, ensure_ascii=False, indent=2)
+    if fmt == "graphml":
+        return kg.export_to_graphml(as_of=as_of)
+    return _json.dumps(
+        {"ok": False, "error": f"unsupported format: {format!r} (use jsonld or graphml)"},
+        ensure_ascii=False,
+    )
+
+
+TOOLS = [
+    (handle_kg_query, "nexo_kg_query", "Query knowledge graph — traverse from a node"),
+    (handle_kg_path, "nexo_kg_path", "Find shortest path between two nodes"),
+    (handle_kg_neighbors, "nexo_kg_neighbors", "Get direct neighbors of a node"),
+    (handle_kg_stats, "nexo_kg_stats", "Knowledge graph statistics"),
+    (handle_kg_export, "nexo_kg_export", "Export the bitemporal KG to JSON-LD or GraphML (active snapshot or historical via as_of)"),
+]

package/src/plugins/media_memory_tools 2.py

@@ -0,0 +1,98 @@
+"""Multimodal memory reference tools."""
+
+import media_memory
+
+
+def handle_media_memory_add(
+    file_path: str = "",
+    url: str = "",
+    title: str = "",
+    description: str = "",
+    tags: str = "",
+    domain: str = "",
+    source_type: str = "",
+    source_id: str = "",
+    metadata: str = "",
+) -> str:
+    result = media_memory.add_media_memory(
+        file_path=file_path,
+        url=url,
+        title=title,
+        description=description,
+        tags=tags,
+        domain=domain,
+        source_type=source_type,
+        source_id=source_id,
+        metadata=metadata,
+    )
+    if result.get("error"):
+        return f"ERROR: {result['error']}"
+    location = result.get("file_path") or result.get("url") or "n/a"
+    return f"Media memory #{result['id']} [{result['media_type']}] stored: {location}"
+
+
+def handle_media_memory_search(
+    query: str = "",
+    media_type: str = "",
+    domain: str = "",
+    tag: str = "",
+    limit: int = 20,
+) -> str:
+    items = media_memory.search_media_memories(
+        query=query,
+        media_type=media_type,
+        domain=domain,
+        tag=tag,
+        limit=limit,
+    )
+    if not items:
+        return "No media memories found."
+    lines = [f"MEDIA MEMORIES — {len(items)} result(s):", ""]
+    for item in items:
+        lines.append(f"  #{item['id']} [{item['media_type']}] {item['title'][:120]}")
+        lines.append(f"    {item.get('file_path') or item.get('url') or 'n/a'}")
+        if item.get("description"):
+            lines.append(f"    {item['description'][:180]}")
+        if item.get("tags"):
+            lines.append(f"    tags: {item['tags']}")
+    return "\n".join(lines)
+
+
+def handle_media_memory_get(media_id: int) -> str:
+    item = media_memory.get_media_memory(media_id)
+    if not item:
+        return f"Media memory #{media_id} not found."
+    lines = [
+        f"MEDIA MEMORY #{item['id']}",
+        f"  type: {item['media_type']}",
+        f"  title: {item['title']}",
+        f"  location: {item.get('file_path') or item.get('url') or 'n/a'}",
+        f"  domain: {item.get('domain') or 'n/a'}",
+        f"  source: {item.get('source_type') or 'n/a'}:{item.get('source_id') or ''}",
+    ]
+    if item.get("description"):
+        lines.append(f"  description: {item['description']}")
+    if item.get("tags"):
+        lines.append(f"  tags: {item['tags']}")
+    if item.get("metadata"):
+        lines.append(f"  metadata: {item['metadata']}")
+    return "\n".join(lines)
+
+
+def handle_media_memory_stats() -> str:
+    stats = media_memory.media_memory_stats()
+    return (
+        "MEDIA MEMORY STATS\n"
+        f"  total: {stats['total']}\n"
+        f"  backend: {stats['backend']}\n"
+        f"  by_type: {stats['by_type']}\n"
+        f"  by_domain: {stats['by_domain']}"
+    )
+
+
+TOOLS = [
+    (handle_media_memory_add, "nexo_media_memory_add", "Store a non-text artifact as first-class media memory metadata."),
+    (handle_media_memory_search, "nexo_media_memory_search", "Search media memories by text, type, tag, or domain."),
+    (handle_media_memory_get, "nexo_media_memory_get", "Inspect one stored media memory."),
+    (handle_media_memory_stats, "nexo_media_memory_stats", "Stats for the multimodal/media memory layer."),
+]

package/src/plugins/memory_export 2.py

@@ -0,0 +1,196 @@
+"""Readable export and auto-flush inspection tools."""
+
+from __future__ import annotations
+
+import json
+import os
+from datetime import datetime
+from pathlib import Path
+
+import cognitive
+import claim_graph
+import compaction_memory
+import media_memory
+import user_state_model
+from db import get_db
+from memory_backends import get_backend, list_backends
+
+
+def _nexo_home() -> Path:
+    return Path(os.environ.get("NEXO_HOME", str(Path.home() / ".nexo"))).expanduser()
+
+
+def _write(path: Path, text: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(text, encoding="utf-8")
+
+
+def handle_auto_flush_recent(limit: int = 20, session_id: str = "") -> str:
+    rows = compaction_memory.list_auto_flushes(session_id=session_id, limit=limit)
+    if not rows:
+        return "No auto-flush records."
+    lines = [f"AUTO-FLUSH — {len(rows)} record(s):", ""]
+    for row in rows:
+        lines.append(f"  #{row['id']} {row['created_at']} [{row.get('session_id','unknown')}]")
+        lines.append(f"    {row.get('summary','')[:220]}")
+        if row.get("next_step"):
+            lines.append(f"    next: {row['next_step'][:160]}")
+    return "\n".join(lines)
+
+
+def handle_auto_flush_stats(days: int = 7) -> str:
+    stats = compaction_memory.auto_flush_stats(days=days)
+    return (
+        f"AUTO-FLUSH STATS — {stats['window_days']}d\n"
+        f"  total: {stats['total']}\n"
+        f"  backend: {stats['backend']}\n"
+        f"  by_source: {stats['by_source']}"
+    )
+
+
+def handle_memory_backend_status() -> str:
+    active = get_backend()
+    backends = list_backends()
+    lines = [
+        f"MEMORY BACKEND: {active.key} — {active.label}",
+        f"Description: {active.description}",
+        f"Supports: {', '.join(active.supports)}",
+        "",
+        "Registered backends:",
+    ]
+    for item in backends:
+        marker = "*" if item["active"] else "-"
+        lines.append(f"  {marker} {item['key']} [{item['maturity']}] {item['label']}")
+    return "\n".join(lines)
+
+
+def handle_memory_export(format: str = "markdown", output_dir: str = "") -> str:
+    if format.strip().lower() != "markdown":
+        return "ERROR: only markdown export is supported for now."
+
+    stamp = datetime.now().strftime("%Y%m%d-%H%M%S")
+    root = Path(output_dir).expanduser() if output_dir.strip() else (_nexo_home() / "exports" / "memory" / stamp)
+    root.mkdir(parents=True, exist_ok=True)
+
+    conn = get_db()
+    learnings = [dict(r) for r in conn.execute("SELECT id, category, title, status, prevention, updated_at FROM learnings ORDER BY updated_at DESC LIMIT 50").fetchall()]
+    decisions = [dict(r) for r in conn.execute("SELECT id, domain, decision, confidence, status, created_at FROM decisions ORDER BY created_at DESC LIMIT 50").fetchall()]
+    claims = claim_graph.search_claims(limit=100)
+    claim_lint = claim_graph.lint_claims(limit=50)
+    media = media_memory.list_media_memories(limit=100)
+    flushes = compaction_memory.list_auto_flushes(limit=100)
+    user_state = user_state_model.build_user_state(days=7, persist=False)
+    user_history = user_state_model.list_user_state_snapshots(limit=30)
+    cognitive_stats = cognitive.get_stats()
+
+    _write(
+        root / "README.md",
+        "\n".join(
+            [
+                "# NEXO Memory Export",
+                "",
+                f"- Generated: {datetime.now().isoformat(timespec='seconds')}",
+                f"- Backend: {get_backend().key}",
+                f"- Learnings: {len(learnings)}",
+                f"- Decisions: {len(decisions)}",
+                f"- Claims: {len(claims)}",
+                f"- Media memories: {len(media)}",
+                f"- Auto-flush records: {len(flushes)}",
+                "",
+                "Files:",
+                "- `learnings.md`",
+                "- `decisions.md`",
+                "- `claims.md`",
+                "- `media.md`",
+                "- `auto-flush.md`",
+                "- `user-state.md`",
+                "- `cognitive.json`",
+            ]
+        ),
+    )
+    _write(
+        root / "learnings.md",
+        "\n".join(
+            ["# Learnings", ""]
+            + [
+                f"- #{item['id']} [{item.get('category','general')}] {item['title']} "
+                f"({item.get('status','active')}, updated {item.get('updated_at','')})"
+                for item in learnings
+            ]
+        ),
+    )
+    _write(
+        root / "decisions.md",
+        "\n".join(
+            ["# Decisions", ""]
+            + [
+                f"- #{item['id']} [{item.get('domain','other')}] {item['decision']} "
+                f"({item.get('confidence','medium')}, {item.get('status','pending_review')})"
+                for item in decisions
+            ]
+        ),
+    )
+    _write(
+        root / "claims.md",
+        "\n".join(
+            ["# Claims", ""]
+            + [
+                f"- #{item['id']} [{item.get('verification_status','unverified')}] "
+                f"{item.get('freshness_state','?')}({item.get('freshness_score',0)}): {item['text']}"
+                for item in claims
+            ]
+            + ["", "## Attention", ""]
+            + [
+                f"- #{item['id']} [{', '.join(item.get('lint_reasons', []))}] {item['text']}"
+                for item in claim_lint
+            ]
+        ),
+    )
+    _write(
+        root / "media.md",
+        "\n".join(
+            ["# Media Memory", ""]
+            + [
+                f"- #{item['id']} [{item['media_type']}] {item['title']} :: {item.get('file_path') or item.get('url') or 'n/a'}"
+                for item in media
+            ]
+        ),
+    )
+    _write(
+        root / "auto-flush.md",
+        "\n".join(
+            ["# Auto Flush", ""]
+            + [
+                f"- #{item['id']} [{item.get('session_id','unknown')}] {item.get('created_at','')}: "
+                f"{item.get('summary','')}"
+                for item in flushes
+            ]
+        ),
+    )
+    _write(
+        root / "user-state.md",
+        "\n".join(
+            [
+                "# User State",
+                "",
+                f"- Current: {user_state['state_label']} ({user_state['confidence']})",
+                f"- Trust: {user_state['trust_score']}",
+                f"- Guidance: {user_state['guidance']}",
+                "",
+                "## Signals",
+            ]
+            + [f"- {key}: {value}" for key, value in user_state["signals"].items()]
+            + ["", "## History", ""]
+            + [f"- {item['created_at']} :: {item['state_label']} ({item['confidence']})" for item in user_history]
+        ),
+    )
+    _write(root / "cognitive.json", json.dumps(cognitive_stats, indent=2, sort_keys=True))
+    return f"Memory export written to {root}"
+
+
+TOOLS = [
+    (handle_auto_flush_recent, "nexo_auto_flush_recent", "Show recent structured auto-flush records written before compaction."),
+    (handle_auto_flush_stats, "nexo_auto_flush_stats", "Stats for pre-compaction auto-flush activity."),
+    (handle_memory_backend_status, "nexo_memory_backend_status", "Show the active memory backend contract and registered backend list."),
+    (handle_memory_export, "nexo_memory_export", "Export a readable markdown snapshot of key NEXO memory layers."),
+]

package/src/plugins/outcomes 2.py

@@ -0,0 +1,130 @@
+"""Outcome tracker plugin — close action -> expected result -> actual result loops."""
+
+from __future__ import annotations
+
+import json
+
+from db import (
+    create_outcome,
+    get_outcome,
+    list_outcomes,
+    cancel_outcome,
+    evaluate_outcome,
+    list_outcome_pattern_candidates,
+    capture_outcome_pattern,
+)
+
+
+def _format_outcome_row(row: dict) -> str:
+    actual = row.get("actual_value")
+    actual_display = (
+        str(actual)
+        if actual is not None
+        else (row.get("actual_value_text") or "—")
+    )
+    return (
+        f"#{row['id']} [{row.get('status','pending')}] "
+        f"{row.get('action_type','custom')}:{row.get('action_id','—') or '—'} "
+        f"deadline={row.get('deadline','—')} "
+        f"expected={row.get('expected_result','')[:80]} "
+        f"actual={str(actual_display)[:80]}"
+    )
+
+
+def handle_outcome_register(
+    action_type: str,
+    description: str,
+    expected_result: str,
+    metric_source: str = "manual",
+    metric_query: str = "",
+    baseline: float | None = None,
+    target: float | None = None,
+    target_op: str = "gte",
+    deadline: str = "",
+    action_id: str = "",
+    session_id: str = "",
+    notes: str = "",
+) -> str:
+    """Register an expected outcome for an action so NEXO can verify it later."""
+    result = create_outcome(
+        action_type=action_type,
+        description=description,
+        expected_result=expected_result,
+        metric_source=metric_source,
+        metric_query=metric_query,
+        baseline_value=baseline,
+        target_value=target,
+        target_operator=target_op,
+        deadline=deadline,
+        action_id=action_id,
+        session_id=session_id,
+        notes=notes,
+    )
+    if "error" in result:
+        return f"ERROR: {result['error']}"
+    return (
+        f"Outcome #{result['id']} registered [{result['status']}]. "
+        f"deadline={result['deadline']} metric_source={result['metric_source']}"
+    )
+
+
+def handle_outcome_check(
+    id: int,
+    actual_value: float | None = None,
+    actual_value_text: str = "",
+    create_learning_on_miss: bool = True,
+) -> str:
+    """Check one outcome now and update its status using linked state or supplied evidence."""
+    result = evaluate_outcome(
+        int(id),
+        actual_value=actual_value,
+        actual_value_text=actual_value_text,
+        create_learning_on_miss=bool(create_learning_on_miss),
+    )
+    if "error" in result:
+        return f"ERROR: {result['error']}"
+    notes = result.get("notes") or ""
+    learning = f" learning_id={result.get('learning_id')}" if result.get("learning_id") else ""
+    return f"{_format_outcome_row(result)}{learning}\nnotes={notes[:300]}"
+
+
+def handle_outcome_list(status: str = "", action_type: str = "", limit: int = 20) -> str:
+    """List outcomes by status and/or action type."""
+    rows = list_outcomes(status=status, action_type=action_type, limit=limit)
+    if not rows:
+        scope = f"status={status or 'any'} action_type={action_type or 'any'}"
+        return f"No outcomes found ({scope})."
+    header = f"OUTCOMES ({len(rows)})"
+    return "\n".join([header] + [f"  {_format_outcome_row(row)}" for row in rows])
+
+
+def handle_outcome_cancel(id: int, reason: str = "") -> str:
+    """Cancel a pending outcome so it no longer blocks reviews or release loops."""
+    result = cancel_outcome(int(id), reason=reason)
+    if "error" in result:
+        return f"ERROR: {result['error']}"
+    return f"Outcome #{result['id']} cancelled."
+
+
+def handle_outcome_pattern_candidates(min_resolved: int = 3, limit: int = 10) -> str:
+    """List repeated resolved outcome patterns that are strong enough to become reusable knowledge."""
+    candidates = list_outcome_pattern_candidates(min_resolved=min_resolved, limit=limit)
+    return json.dumps({"ok": True, "candidates": candidates}, ensure_ascii=False, indent=2)
+
+
+def handle_outcome_pattern_capture(pattern_key: str, target: str = "learning", category: str = "outcomes") -> str:
+    """Materialize one repeated outcome pattern into a reusable artifact (currently a learning)."""
+    result = capture_outcome_pattern(pattern_key=pattern_key, target=target, category=category)
+    if "error" in result:
+        return json.dumps({"ok": False, "error": result["error"]}, ensure_ascii=False, indent=2)
+    return json.dumps(result, ensure_ascii=False, indent=2)
+
+
+TOOLS = [
+    (handle_outcome_register, "nexo_outcome_register", "Register an expected action outcome with metric source, deadline, and optional link to decision/followup/task."),
+    (handle_outcome_check, "nexo_outcome_check", "Check a tracked outcome now using linked state or supplied evidence; marks pending/met/missed and may create a learning on miss."),
+    (handle_outcome_list, "nexo_outcome_list", "List tracked outcomes filtered by status and/or action type."),
+    (handle_outcome_cancel, "nexo_outcome_cancel", "Cancel an outcome so it stops blocking pending/missed reviews."),
+    (handle_outcome_pattern_candidates, "nexo_outcome_pattern_candidates", "List repeated resolved outcome patterns from cortex-linked decisions that are consistent enough to become reusable knowledge."),
+    (handle_outcome_pattern_capture, "nexo_outcome_pattern_capture", "Capture one repeated outcome pattern as a reusable artifact (currently a learning) once the evidence is consistent."),
+]