nexo-brain 5.3.13 → 5.3.15

package/src/hooks/post-compact 2.sh

@@ -0,0 +1,152 @@
+#!/bin/bash
+# NEXO PostCompact Hook — Re-inject Core Memory Block after compaction
+# Reads the latest session checkpoint from SQLite and generates a structured
+# context block that preserves session continuity.
+set -uo pipefail
+
+NEXO_HOME="${NEXO_HOME:-$HOME/.nexo}"
+NEXO_DB="$NEXO_HOME/data/nexo.db"
+mkdir -p "$NEXO_HOME/data"
+TODAY=$(date +%Y-%m-%d)
+LOG_FILE="$NEXO_HOME/operations/tool-logs/${TODAY}.jsonl"
+LOG_LINES=0
+if [ -f "$LOG_FILE" ]; then
+    LOG_LINES=$(wc -l < "$LOG_FILE" | tr -d ' ')
+fi
+
+# Read checkpoint for the session that just compacted
+# PreCompact writes the SID to /tmp/nexo-compacting-sid
+TARGET_SID=""
+if [ -f /tmp/nexo-compacting-sid ]; then
+    RAW_SID=$(cat /tmp/nexo-compacting-sid 2>/dev/null || echo "")
+    rm -f /tmp/nexo-compacting-sid
+    # Validate SID format: must be nexo-DIGITS-DIGITS
+    if [[ "$RAW_SID" =~ ^nexo-[0-9]+-[0-9]+$ ]]; then
+        TARGET_SID="$RAW_SID"
+    fi
+fi
+
+CHECKPOINT=""
+if [ -f "$NEXO_DB" ]; then
+    if [ -n "$TARGET_SID" ]; then
+        # Read checkpoint for the specific session that compacted
+        CHECKPOINT=$(sqlite3 "$NEXO_DB" "
+            SELECT sid, task, task_status, active_files, current_goal,
+                   decisions_summary, errors_found, reasoning_thread,
+                   next_step, compaction_count
+            FROM session_checkpoints
+            WHERE sid = '$TARGET_SID'
+        " 2>/dev/null || echo "")
+    fi
+    # Fallback: if no target SID or no checkpoint found, use latest
+    if [ -z "$CHECKPOINT" ]; then
+        CHECKPOINT=$(sqlite3 "$NEXO_DB" "
+            SELECT sid, task, task_status, active_files, current_goal,
+                   decisions_summary, errors_found, reasoning_thread,
+                   next_step, compaction_count
+            FROM session_checkpoints
+            ORDER BY updated_at DESC LIMIT 1
+        " 2>/dev/null || echo "")
+    fi
+
+    if [ -n "$CHECKPOINT" ]; then
+        # Parse pipe-separated fields
+        SID=$(echo "$CHECKPOINT" | cut -d'|' -f1)
+        TASK=$(echo "$CHECKPOINT" | cut -d'|' -f2)
+        TASK_STATUS=$(echo "$CHECKPOINT" | cut -d'|' -f3)
+        ACTIVE_FILES=$(echo "$CHECKPOINT" | cut -d'|' -f4)
+        CURRENT_GOAL=$(echo "$CHECKPOINT" | cut -d'|' -f5)
+        DECISIONS=$(echo "$CHECKPOINT" | cut -d'|' -f6)
+        ERRORS=$(echo "$CHECKPOINT" | cut -d'|' -f7)
+        REASONING=$(echo "$CHECKPOINT" | cut -d'|' -f8)
+        NEXT_STEP=$(echo "$CHECKPOINT" | cut -d'|' -f9)
+        COMPACT_COUNT=$(echo "$CHECKPOINT" | cut -d'|' -f10)
+
+        # Increment compaction count
+        sqlite3 "$NEXO_DB" "
+            UPDATE session_checkpoints
+            SET compaction_count = compaction_count + 1, updated_at = datetime('now')
+            WHERE sid = '$SID'
+        " 2>/dev/null || true
+
+        # Read diary draft for extra context
+        DRAFT=$(sqlite3 "$NEXO_DB" "
+            SELECT tasks_seen, last_context_hint
+            FROM session_diary_draft
+            WHERE sid = '$SID'
+        " 2>/dev/null || echo "")
+
+        TASKS_SEEN=""
+        LAST_HINT=""
+        if [ -n "$DRAFT" ]; then
+            TASKS_SEEN=$(echo "$DRAFT" | cut -d'|' -f1)
+            LAST_HINT=$(echo "$DRAFT" | cut -d'|' -f2)
+        fi
+
+        # Build Core Memory Block
+        BLOCK="## SESSION CONTINUITY [auto-injected post-compaction #$((COMPACT_COUNT + 1))]"
+        BLOCK="$BLOCK\n**Session:** $SID"
+        BLOCK="$BLOCK\n**Task:** $TASK (status: $TASK_STATUS)"
+
+        if [ -n "$CURRENT_GOAL" ] && [ "$CURRENT_GOAL" != "$TASK" ]; then
+            BLOCK="$BLOCK\n**Goal:** $CURRENT_GOAL"
+        fi
+
+        if [ -n "$ACTIVE_FILES" ] && [ "$ACTIVE_FILES" != "[]" ]; then
+            BLOCK="$BLOCK\n**Files:** $ACTIVE_FILES"
+        fi
+
+        if [ -n "$DECISIONS" ]; then
+            BLOCK="$BLOCK\n**Decisions:** $DECISIONS"
+        fi
+
+        if [ -n "$ERRORS" ]; then
+            BLOCK="$BLOCK\n**Errors:** $ERRORS"
+        fi
+
+        if [ -n "$NEXT_STEP" ]; then
+            BLOCK="$BLOCK\n**Next:** $NEXT_STEP"
+        fi
+
+        if [ -n "$REASONING" ]; then
+            BLOCK="$BLOCK\n**Context:** $REASONING"
+        fi
+
+        if [ -n "$LAST_HINT" ]; then
+            BLOCK="$BLOCK\n**Last context:** $LAST_HINT"
+        fi
+
+        if [ -n "$TASKS_SEEN" ] && [ "$TASKS_SEEN" != "[]" ]; then
+            BLOCK="$BLOCK\n**Session tasks so far:** $TASKS_SEEN"
+        fi
+
+        BLOCK="$BLOCK\n**Tool logs:** ${NEXO_HOME}/operations/tool-logs/${TODAY}.jsonl ($LOG_LINES entries)"
+        BLOCK="$BLOCK\n\n**POST-COMPACTION INSTRUCTIONS:**"
+        BLOCK="$BLOCK\n1. Call nexo_heartbeat with the SID above to reconnect with the session"
+        BLOCK="$BLOCK\n2. If you need specific lost data, query tool logs with jq"
+        BLOCK="$BLOCK\n3. Continue the task from where it left off — do NOT start from zero"
+        BLOCK="$BLOCK\n4. MCP tools (nexo_*) have all persistent state"
+
+        # Escape for JSON
+        BLOCK_ESCAPED=$(echo -e "$BLOCK" | python3 -c "import sys,json; print(json.dumps(sys.stdin.read()))")
+
+        cat << HOOKEOF
+{
+  "systemMessage": $BLOCK_ESCAPED
+}
+HOOKEOF
+    else
+        # No checkpoint — fallback to basic message
+        cat << 'HOOKEOF'
+{
+  "systemMessage": "Post-compaction: no prior checkpoint found. Call nexo_heartbeat to reconnect session state."
+}
+HOOKEOF
+    fi
+else
+    cat << 'HOOKEOF'
+{
+  "systemMessage": "Post-compaction: nexo.db not found. Reconnect via nexo_startup."
+}
+HOOKEOF
+fi

package/src/hooks/pre-compact 2.sh

@@ -0,0 +1,169 @@
+#!/bin/bash
+# NEXO PreCompact Hook — Save checkpoint + inject preservation instructions
+# This runs BEFORE Claude Code compacts. It:
+# 1. Enriches the session checkpoint in SQLite with latest diary draft data
+# 2. Injects a systemMessage telling the operator to save any WIP via MCP tools
+set -uo pipefail
+
+HOOK_DIR="$(cd "$(dirname "$0")" && pwd)"
+NEXO_HOME="${NEXO_HOME:-$HOME/.nexo}"
+NEXO_DB="$NEXO_HOME/data/nexo.db"
+mkdir -p "$NEXO_HOME/data"
+TODAY=$(date +%Y-%m-%d)
+LOG_FILE="$NEXO_HOME/operations/tool-logs/${TODAY}.jsonl"
+LOG_LINES=0
+if [ -f "$LOG_FILE" ]; then
+    LOG_LINES=$(wc -l < "$LOG_FILE" | tr -d ' ')
+fi
+
+# Enrich checkpoint: copy diary draft context into checkpoint if exists
+if [ -f "$NEXO_DB" ]; then
+    # Get latest active session's diary draft
+    LATEST_SID=$(sqlite3 "$NEXO_DB" "
+        SELECT sid FROM sessions ORDER BY last_update_epoch DESC LIMIT 1
+    " 2>/dev/null || echo "")
+
+    if [ -n "$LATEST_SID" ] && [[ "$LATEST_SID" =~ ^nexo-[0-9]+-[0-9]+$ ]]; then
+        # Write SID to temp file so PostCompact knows which session compacted
+        echo "$LATEST_SID" > /tmp/nexo-compacting-sid
+        # Pull diary draft data into checkpoint
+        sqlite3 "$NEXO_DB" "
+            INSERT INTO session_checkpoints (sid, task, current_goal, updated_at)
+            SELECT s.sid, s.task, COALESCE(d.last_context_hint, s.task), datetime('now')
+            FROM sessions s
+            LEFT JOIN session_diary_draft d ON d.sid = s.sid
+            WHERE s.sid = '$LATEST_SID'
+            ON CONFLICT(sid) DO UPDATE SET
+                task = excluded.task,
+                current_goal = CASE
+                    WHEN excluded.current_goal != '' THEN excluded.current_goal
+                    ELSE session_checkpoints.current_goal
+                END,
+                updated_at = datetime('now')
+        " 2>/dev/null || true
+    fi
+fi
+
+# ── Layer 2: Emergency auto-diary before compaction ──────────────────
+# Write an actual session_diary entry (not draft) with mechanical summary
+# This is the parachute — if the LLM never wrote a diary, at least this exists
+if [ -f "$NEXO_DB" ]; then
+    python3 -c "
+import json, sqlite3, os, sys
+from datetime import datetime
+
+db_path = '$NEXO_DB'
+log_file = '$LOG_FILE'
+
+conn = sqlite3.connect(db_path, timeout=3)
+conn.row_factory = sqlite3.Row
+
+# Get latest active session
+row = conn.execute(
+    'SELECT sid, task FROM sessions ORDER BY last_update_epoch DESC LIMIT 1'
+).fetchone()
+if not row:
+    conn.close()
+    sys.exit(0)
+
+sid = row['sid']
+task = row['task'] or 'unknown'
+
+# Check if a real diary already exists for this session
+has_diary = conn.execute(
+    'SELECT id FROM session_diary WHERE session_id = ? LIMIT 1', (sid,)
+).fetchone()
+if has_diary:
+    conn.close()
+    sys.exit(0)  # LLM already wrote one, no need for emergency diary
+
+# Find last diary timestamp to know where to start reading logs
+last_diary = conn.execute(
+    'SELECT created_at FROM session_diary ORDER BY created_at DESC LIMIT 1'
+).fetchone()
+last_diary_ts = last_diary['created_at'] if last_diary else '1970-01-01T00:00:00Z'
+
+# Read tool log entries since last diary
+entries = []
+modified_files = []
+git_actions = []
+if os.path.isfile(log_file):
+    with open(log_file, 'r') as f:
+        for line in f:
+            try:
+                e = json.loads(line.strip())
+                ts = e.get('timestamp', '')
+                if ts < last_diary_ts:
+                    continue
+                name = e.get('tool_name', '?')
+                inp = e.get('tool_input', {}) or {}
+                brief = ''
+                if isinstance(inp, dict):
+                    for k, v in list(inp.items())[:1]:
+                        brief = str(v)[:80]
+                entries.append(f'{name}({brief})')
+                # Extract decisions from tool calls
+                if name in ('Edit', 'Write'):
+                    fp = inp.get('file_path', inp.get('path', ''))
+                    if fp:
+                        modified_files.append(fp.split('/')[-1])
+                if name == 'Bash':
+                    cmd = str(inp.get('command', ''))
+                    if 'git commit' in cmd or 'git push' in cmd:
+                        git_actions.append(cmd[:80])
+            except Exception:
+                pass
+
+if not entries:
+    conn.close()
+    sys.exit(0)
+
+# Build mechanical diary
+tools_summary = ', '.join(entries[-30:])[:500]
+summary = f'[EMERGENCY PRE-COMPACT] {len(entries)} tool calls since last diary. Tools: {tools_summary}'
+
+decisions = ''
+if modified_files:
+    decisions = 'Modified: ' + ', '.join(set(modified_files))[:300]
+if git_actions:
+    decisions += (' | Git: ' + ', '.join(git_actions))[:200]
+if not decisions:
+    decisions = 'No file modifications detected in tool logs'
+
+pending = f'Current task: {task[:200]}'
+context_next = 'COMPACTION HAPPENED. Read this diary to continue. Check session_checkpoints and tool-logs for full context.'
+
+# Write actual session_diary entry
+conn.execute('''
+    INSERT INTO session_diary
+        (session_id, decisions, discarded, pending, context_next,
+         mental_state, domain, user_signals, summary, source)
+    VALUES (?, ?, '', ?, ?, 'auto-generated', 'auto', '', ?, 'pre-compact-hook')
+''', (sid, decisions, pending, context_next, summary))
+conn.commit()
+
+# Layer 3: structured auto-flush for continuity and inspectability
+try:
+    import os
+    sys.path.insert(0, os.path.abspath(os.path.join('$HOOK_DIR', '..')))
+    import compaction_memory
+    compaction_memory.record_auto_flush(
+        session_id=sid,
+        task=task,
+        current_goal='',
+        log_file=log_file,
+        last_diary_ts=last_diary_ts,
+        source='pre-compact-hook',
+    )
+except Exception:
+    pass
+
+conn.close()
+" 2>/dev/null || true
+fi
+
+cat << HOOKEOF
+{
+  "systemMessage": "CONTEXT IS ABOUT TO BE COMPRESSED.\n\nOBLIGATORY ACTIONS BEFORE COMPACTION:\n1. Save critical state via MCP: nexo_checkpoint_save with current task, active files, decisions, errors, next step, and reasoning thread.\n2. If there is work in progress without a commit, save data via nexo_entity_create, nexo_preference_set, nexo_learning_add, nexo_followup_create.\n3. PERSISTENT TOOL LOGS: ${NEXO_HOME}/operations/tool-logs/${TODAY}.jsonl has ${LOG_LINES} entries.\n4. After compaction, the PostCompact hook will re-inject a Core Memory Block with the checkpoint.\n5. MCP tools (nexo_*) preserve all state — use them to recover context.\n6. EMERGENCY DIARY: An automatic diary was written by the pre-compact hook. The LLM can still write a better one via nexo_session_diary_write."
+}
+HOOKEOF

package/src/hooks/protocol-guardrail 2.sh

@@ -0,0 +1,10 @@
+#!/bin/bash
+# NEXO PostToolUse hook — conditioned file discipline guardrail
+
+INPUT=$(cat || true)
+[ -z "$INPUT" ] && exit 0
+
+NEXO_CODE="${NEXO_CODE:-${HOME}/.nexo}"
+NEXO_HOOK_PHASE=post python3 "$NEXO_CODE/hook_guardrails.py" <<< "$INPUT" 2>/dev/null || true
+
+exit 0

package/src/hooks/protocol-pretool-guardrail 2.sh

@@ -0,0 +1,9 @@
+#!/bin/bash
+# NEXO PreToolUse hook — strict protocol blocking before writes/deletes
+
+INPUT=$(cat || true)
+[ -z "$INPUT" ] && exit 0
+
+NEXO_CODE="${NEXO_CODE:-${HOME}/.nexo}"
+NEXO_HOOK_PHASE=pre python3 "$NEXO_CODE/hook_guardrails.py" <<< "$INPUT"
+exit $?

package/src/hooks/session-stop 2.sh

@@ -0,0 +1,52 @@
+#!/bin/bash
+# NEXO Memory Stop Hook (v8 — non-blocking, approve always)
+#
+# v5: used "approve" + systemMessage — AI never processed post-mortem.
+# v6: used "block" — but blocked ALL sessions including trivial ones.
+# v7: detects trivial sessions (<5 tool calls) and approves immediately.
+# v8: NEVER blocks. The Stop hook fires after EVERY Claude response (not just
+#     session close), so blocking causes mid-conversation interruptions.
+#     Post-mortem is now handled by:
+#       1. Claude detecting closing intent (any language) → diary inline
+#       2. auto_close_sessions.py → promotes draft for orphan sessions
+#
+# This hook only refreshes the diary draft with latest data (best-effort).
+set -uo pipefail
+
+NEXO_HOME="${NEXO_HOME:-$HOME/.nexo}"
+
+# Refresh diary draft with latest changes/decisions (best-effort)
+python3 -c "
+import sys, json, os
+nexo_home = os.environ.get('NEXO_HOME', os.path.expanduser('~/.nexo'))
+nexo_code = os.environ.get('NEXO_CODE', nexo_home)
+sys.path.insert(0, nexo_code)
+os.environ['NEXO_SKIP_FS_INDEX'] = '1'
+from db import init_db, get_db, get_active_sessions, upsert_diary_draft, get_diary_draft
+init_db()
+conn = get_db()
+sessions = get_active_sessions()
+for s in sessions:
+    sid = s['sid']
+    draft = get_diary_draft(sid)
+    if not draft:
+        continue
+    change_ids = [r[0] for r in conn.execute('SELECT id FROM change_log WHERE session_id = ?', (sid,)).fetchall()]
+    decision_ids = [r[0] for r in conn.execute('SELECT id FROM decisions WHERE session_id = ?', (sid,)).fetchall()]
+    upsert_diary_draft(
+        sid=sid,
+        tasks_seen=draft['tasks_seen'],
+        change_ids=json.dumps(change_ids),
+        decision_ids=json.dumps(decision_ids),
+        last_context_hint=draft['last_context_hint'],
+        heartbeat_count=draft['heartbeat_count'],
+        summary_draft=draft['summary_draft'],
+    )
+" 2>/dev/null || true
+
+# Always approve — never interrupt the conversation
+cat << 'HOOKEOF'
+{
+  "decision": "approve"
+}
+HOOKEOF

package/src/kg_populate 2.py

@@ -0,0 +1,292 @@
+"""NEXO KG Auto-Population — backfill from nexo.db + incremental hooks."""
+
+import json
+import os
+import sqlite3
+from typing import Optional
+
+import knowledge_graph as kg
+from db import get_db
+
+
+# ─── helpers ────────────────────────────────────────────────────────────────
+
+def _cognitive_db():
+    """Direct cognitive.db connection (for somatic_markers)."""
+    nexo_home = os.environ.get("NEXO_HOME", os.path.expanduser("~/.nexo"))
+    data_dir = os.path.join(nexo_home, "data")
+    os.makedirs(data_dir, exist_ok=True)
+    path = os.path.join(data_dir, "cognitive.db")
+    conn = sqlite3.connect(path)
+    conn.row_factory = sqlite3.Row
+    return conn
+
+
+def _parse_files(files_str: str) -> list[str]:
+    """Extract individual file paths from a comma/newline-separated string."""
+    if not files_str:
+        return []
+    parts = [p.strip() for p in files_str.replace("\n", ",").split(",")]
+    return [p for p in parts if p]
+
+
+# ─── backfill functions ──────────────────────────────────────────────────────
+
+def backfill_entities() -> int:
+    """Read entities table → create entity nodes in KG."""
+    db = get_db()
+    rows = db.execute("SELECT id, name, type, value, notes FROM entities").fetchall()
+    count = 0
+    for row in rows:
+        props = {}
+        if row["value"]:
+            props["value"] = row["value"]
+        if row["notes"]:
+            props["notes"] = row["notes"]
+        kg.upsert_node(
+            node_type="entity",
+            node_ref=f"entity:{row['id']}",
+            label=row["name"],
+            properties={"entity_type": row["type"], **props},
+        )
+        count += 1
+    return count
+
+
+def backfill_learnings() -> int:
+    """Read learnings → create learning nodes + file/area edges."""
+    db = get_db()
+    rows = db.execute(
+        "SELECT id, category, title, applies_to FROM learnings WHERE status != 'deleted'"
+    ).fetchall()
+    count = 0
+    for row in rows:
+        learning_ref = f"learning:{row['id']}"
+        kg.upsert_node(
+            node_type="learning",
+            node_ref=learning_ref,
+            label=row["title"] or f"Learning #{row['id']}",
+            properties={"category": row["category"]},
+        )
+        # edge: learning → category/area
+        if row["category"]:
+            kg.upsert_edge(
+                source_type="learning", source_ref=learning_ref,
+                relation="belongs_to",
+                target_type="area", target_ref=f"area:{row['category']}",
+                weight=1.0,
+            )
+        # edge: learning → file (from applies_to)
+        applies = row["applies_to"] or ""
+        for fpath in _parse_files(applies):
+            if fpath:
+                kg.upsert_edge(
+                    source_type="learning", source_ref=learning_ref,
+                    relation="applies_to_file",
+                    target_type="file", target_ref=f"file:{fpath}",
+                    weight=0.8,
+                )
+        count += 1
+    return count
+
+
+def backfill_changes() -> int:
+    """Read change_log → create file nodes + file→area edges."""
+    db = get_db()
+    rows = db.execute("SELECT id, files, what_changed FROM change_log").fetchall()
+    count = 0
+    for row in rows:
+        change_ref = f"change:{row['id']}"
+        kg.upsert_node(
+            node_type="change",
+            node_ref=change_ref,
+            label=f"Change #{row['id']}",
+            properties={"summary": (row["what_changed"] or "")[:120]},
+        )
+        for fpath in _parse_files(row["files"] or ""):
+            file_ref = f"file:{fpath}"
+            kg.upsert_node(
+                node_type="file",
+                node_ref=file_ref,
+                label=os.path.basename(fpath) or fpath,
+            )
+            kg.upsert_edge(
+                source_type="change", source_ref=change_ref,
+                relation="touched",
+                target_type="file", target_ref=file_ref,
+                weight=1.0,
+            )
+        count += 1
+    return count
+
+
+def backfill_decisions() -> int:
+    """Read decisions → create decision nodes + decision→area edges."""
+    db = get_db()
+    rows = db.execute("SELECT id, domain, decision, status FROM decisions").fetchall()
+    count = 0
+    for row in rows:
+        decision_ref = f"decision:{row['id']}"
+        kg.upsert_node(
+            node_type="decision",
+            node_ref=decision_ref,
+            label=(row["decision"] or "")[:80] or f"Decision #{row['id']}",
+            properties={"domain": row["domain"], "status": row["status"]},
+        )
+        if row["domain"]:
+            kg.upsert_edge(
+                source_type="decision", source_ref=decision_ref,
+                relation="in_domain",
+                target_type="area", target_ref=f"area:{row['domain']}",
+                weight=1.0,
+            )
+        count += 1
+    return count
+
+
+def backfill_somatic() -> int:
+    """Read somatic_markers from cognitive.db → create file/area nodes with risk."""
+    cdb = _cognitive_db()
+    try:
+        rows = cdb.execute(
+            "SELECT target, target_type, risk_score, incident_count FROM somatic_markers"
+        ).fetchall()
+        count = 0
+        for row in rows:
+            target_type = row["target_type"] or "file"
+            node_ref = f"{target_type}:{row['target']}"
+            kg.upsert_node(
+                node_type=target_type,
+                node_ref=node_ref,
+                label=os.path.basename(row["target"]) or row["target"],
+                properties={
+                    "risk_score": row["risk_score"],
+                    "incident_count": row["incident_count"],
+                },
+            )
+            count += 1
+        return count
+    finally:
+        cdb.close()
+
+
+def run_full_backfill() -> dict:
+    """Run all backfill functions. Idempotent (upsert-based)."""
+    results = {}
+    results["entities"] = backfill_entities()
+    results["learnings"] = backfill_learnings()
+    results["changes"] = backfill_changes()
+    results["decisions"] = backfill_decisions()
+    results["somatic"] = backfill_somatic()
+    results["total"] = sum(results.values())
+    return results
+
+
+# ─── incremental hooks ───────────────────────────────────────────────────────
+
+def on_learning_add(learning_id: int, category: str, title: str, applies_to: str = "") -> None:
+    try:
+        learning_ref = f"learning:{learning_id}"
+        kg.upsert_node(
+            node_type="learning",
+            node_ref=learning_ref,
+            label=title or f"Learning #{learning_id}",
+            properties={"category": category},
+        )
+        if category:
+            kg.upsert_edge(
+                source_type="learning", source_ref=learning_ref,
+                relation="belongs_to",
+                target_type="area", target_ref=f"area:{category}",
+                weight=1.0,
+            )
+        for fpath in _parse_files(applies_to or ""):
+            if fpath:
+                kg.upsert_edge(
+                    source_type="learning", source_ref=learning_ref,
+                    relation="applies_to_file",
+                    target_type="file", target_ref=f"file:{fpath}",
+                    weight=0.8,
+                )
+    except Exception:
+        pass
+
+
+def on_change_log(change_id: int, files: str, system: str = "") -> None:
+    try:
+        change_ref = f"change:{change_id}"
+        kg.upsert_node(
+            node_type="change",
+            node_ref=change_ref,
+            label=f"Change #{change_id}",
+        )
+        for fpath in _parse_files(files or ""):
+            file_ref = f"file:{fpath}"
+            kg.upsert_node(
+                node_type="file",
+                node_ref=file_ref,
+                label=os.path.basename(fpath) or fpath,
+            )
+            kg.upsert_edge(
+                source_type="change", source_ref=change_ref,
+                relation="touched",
+                target_type="file", target_ref=file_ref,
+                weight=1.0,
+            )
+        if system:
+            kg.upsert_edge(
+                source_type="change", source_ref=change_ref,
+                relation="in_system",
+                target_type="area", target_ref=f"area:{system}",
+                weight=1.0,
+            )
+    except Exception:
+        pass
+
+
+def on_decision_log(decision_id: int, domain: str, decision_text: str) -> None:
+    try:
+        decision_ref = f"decision:{decision_id}"
+        kg.upsert_node(
+            node_type="decision",
+            node_ref=decision_ref,
+            label=(decision_text or "")[:80] or f"Decision #{decision_id}",
+            properties={"domain": domain},
+        )
+        if domain:
+            kg.upsert_edge(
+                source_type="decision", source_ref=decision_ref,
+                relation="in_domain",
+                target_type="area", target_ref=f"area:{domain}",
+                weight=1.0,
+            )
+    except Exception:
+        pass
+
+
+def on_entity_create(entity_id: int, name: str, entity_type: str) -> None:
+    try:
+        kg.upsert_node(
+            node_type="entity",
+            node_ref=f"entity:{entity_id}",
+            label=name,
+            properties={"entity_type": entity_type},
+        )
+    except Exception:
+        pass
+
+
+# ─── main ────────────────────────────────────────────────────────────────────
+
+if __name__ == "__main__":
+    print("Running full KG backfill...")
+    results = run_full_backfill()
+    print("\nBackfill complete:")
+    for key, val in results.items():
+        if key != "total":
+            print(f"  {key:12s}: {val:4d} records")
+    print(f"  {'TOTAL':12s}: {results['total']:4d} nodes/edges processed")
+
+    # Show KG stats
+    s = kg.stats()
+    print(f"\nKG state: {s['nodes']} nodes, {s['edges_active']} active edges")