eagle-mem 4.10.3 → 4.10.4

package/CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes to the **Eagle Mem** project are documented here.
 
 ---
 
+## v4.10.4 Minor Release
+
+This release introduces native relational **Knowledge Graph Memories** and an automated background **Dream Cycle** curator to consolidate multi-agent developer context:
+
+- **Graph-based Memories**: Full integration of custom semantic code graph database primitives (`lib/db-graph.sh` and migrations `db/035_graph_memories.sql` and `db/036_graph_constraints.sql`) to link files, functions, variables, sessions, and memories.
+- **Background Dream Cycle Curation**: Structured offline compilation in `scripts/curate.sh` that merges redundant, overlapping memories into clean `--- Compiled Truth ---` with an underlying `--- Evidence Trail ---`.
+- **Database Firewalls**: Enforced strict enums check triggers on `node_type` and `edge_type` to guarantee complete data integrity.
+- **Sanitized FTS Wildcards**: Safe search query sanitization in `eagle_graph_search` to prevent SQLite MATCH syntax errors on special characters.
+- **Unified Global Porting**: Symlinked advanced nested specialist developer skills and HTTP Model Context Protocol (MCP) gateways natively into the Google Antigravity active configuration.
+
+---
+
 ## v4.10.2 Patch
 
 This release expands the Eagle Mem adapter layer and addresses multi-agent planning synchronization and gap remediations across all four supported agents:

package/README.md

@@ -11,7 +11,7 @@
 
 Eagle Mem turns AI coding sessions into compounding project knowledge. It gives Claude Code, Codex, and Google Antigravity hook-backed shared memory, gives Grok the same skills and CLI memory surface, labels which agent created each memory, blocks risky release commands until affected features are verified, and lets broad work split into durable worker lanes.
 
-**v4.10.2 and onward focuses on Grok, Google Antigravity support, and Compaction Survival:** Grok users get first-class skill linking and `eagle-mem grok-bootstrap`, while Antigravity users get native Python SDK hook integration via `google_antigravity_hook.py`. Claude Code, Codex, and Antigravity receive the deepest automatic lifecycle support through hooks; Grok currently uses the shared CLI and skill workflow.
+**v4.10.4 and onward focuses on Graph Memory, Dream Cycle Curation, Grok, Google Antigravity support, and Compaction Survival:** Grok users get first-class skill linking and `eagle-mem grok-bootstrap`, while Antigravity users get native Python SDK hook integration via `google_antigravity_hook.py`. Claude Code, Codex, and Antigravity receive the deepest automatic lifecycle support through hooks; Grok currently uses the shared CLI and skill workflow.
 
 **Website:** [Product](https://eagleisbatman.github.io/eagle-mem/) |
 [Architecture](https://eagleisbatman.github.io/eagle-mem/architecture.html) |

package/bin/eagle-mem

@@ -27,6 +27,7 @@ case "$command" in
     statusline) "$SCRIPTS_DIR/statusline-em.sh" "$@" ;;
     guard)      bash "$SCRIPTS_DIR/guard.sh" "$@" ;;
     overview)   bash "$SCRIPTS_DIR/overview.sh" "$@" ;;
+    graph)      bash "$SCRIPTS_DIR/memories.sh" graph "$@" ;;
     session|sessions)
                 bash "$SCRIPTS_DIR/session.sh" "$@" ;;
     memories)   bash "$SCRIPTS_DIR/memories.sh" "$@" ;;

package/db/035_graph_memories.sql

@@ -0,0 +1,65 @@
+-- ═══════════════════════════════════════════════════════════
+-- Migration 035: Graph-based memories (nodes and edges relational tables)
+-- ═══════════════════════════════════════════════════════════
+
+-- ─── Graph Nodes ───────────────────────────────────────────
+-- Represents semantic entities in the codebase (files, features, memories, tasks, sessions, tags, etc.)
+CREATE TABLE IF NOT EXISTS graph_nodes (
+    id              INTEGER PRIMARY KEY AUTOINCREMENT,
+    project         TEXT NOT NULL,
+    node_type       TEXT NOT NULL, -- 'file', 'feature', 'memory', 'task', 'session', 'tag', etc.
+    node_name       TEXT NOT NULL, -- e.g., 'lib/db-graph.sh', 'auth-middleware', 'agy-session-123'
+    node_value      TEXT,          -- Optional content, JSON payload, description, etc.
+    source_path     TEXT,          -- Optional filepath or link
+    created_at      TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+    updated_at      TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+    UNIQUE(project, node_type, node_name)
+);
+
+CREATE INDEX IF NOT EXISTS idx_graph_nodes_project ON graph_nodes(project);
+CREATE INDEX IF NOT EXISTS idx_graph_nodes_type_name ON graph_nodes(node_type, node_name);
+
+-- ─── Graph Edges ───────────────────────────────────────────
+-- Represents relationships between nodes with optional weights
+CREATE TABLE IF NOT EXISTS graph_edges (
+    id              INTEGER PRIMARY KEY AUTOINCREMENT,
+    project         TEXT NOT NULL,
+    source_node_id  INTEGER NOT NULL REFERENCES graph_nodes(id) ON DELETE CASCADE,
+    target_node_id  INTEGER NOT NULL REFERENCES graph_nodes(id) ON DELETE CASCADE,
+    edge_type       TEXT NOT NULL, -- 'imports', 'declares', 'references', 'verifies', 'contains', 'supersedes', 'co_edited', 'modified'
+    weight          REAL NOT NULL DEFAULT 1.0,
+    created_at      TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+    UNIQUE(project, source_node_id, target_node_id, edge_type)
+);
+
+CREATE INDEX IF NOT EXISTS idx_graph_edges_project ON graph_edges(project);
+CREATE INDEX IF NOT EXISTS idx_graph_edges_source ON graph_edges(source_node_id);
+CREATE INDEX IF NOT EXISTS idx_graph_edges_target ON graph_edges(target_node_id);
+
+-- ─── FTS5: Full-text search on graph nodes ──────────────────
+CREATE VIRTUAL TABLE IF NOT EXISTS graph_nodes_fts USING fts5(
+    node_name,
+    node_value,
+    content='graph_nodes',
+    content_rowid='id'
+);
+
+-- Triggers to keep FTS in sync
+CREATE TRIGGER IF NOT EXISTS graph_nodes_ai AFTER INSERT ON graph_nodes BEGIN
+    INSERT INTO graph_nodes_fts(rowid, node_name, node_value)
+    VALUES (new.id, new.node_name, new.node_value);
+END;
+
+CREATE TRIGGER IF NOT EXISTS graph_nodes_ad AFTER DELETE ON graph_nodes BEGIN
+    INSERT INTO graph_nodes_fts(graph_nodes_fts, rowid, node_name, node_value)
+    VALUES ('delete', old.id, old.node_name, old.node_value);
+END;
+
+CREATE TRIGGER IF NOT EXISTS graph_nodes_au
+AFTER UPDATE OF node_name, node_value ON graph_nodes
+BEGIN
+    INSERT INTO graph_nodes_fts(graph_nodes_fts, rowid, node_name, node_value)
+    VALUES ('delete', old.id, old.node_name, old.node_value);
+    INSERT INTO graph_nodes_fts(rowid, node_name, node_value)
+    VALUES (new.id, new.node_name, new.node_value);
+END;

package/db/036_graph_constraints.sql

@@ -0,0 +1,37 @@
+-- ═══════════════════════════════════════════════════════════
+-- Migration 036: Database-level enums constraints triggers
+-- ═══════════════════════════════════════════════════════════
+
+-- ─── Node Type Constraints ──────────────────────────────────
+CREATE TRIGGER IF NOT EXISTS val_graph_nodes_insert BEFORE INSERT ON graph_nodes
+BEGIN
+    SELECT CASE
+        WHEN NEW.node_type NOT IN ('project', 'file', 'feature', 'memory', 'task', 'session', 'tag', 'class', 'def')
+        THEN RAISE(ABORT, 'Data Integrity Error: Invalid node type. Must be one of project, file, feature, memory, task, session, tag, class, def')
+    END;
+END;
+
+CREATE TRIGGER IF NOT EXISTS val_graph_nodes_update BEFORE UPDATE OF node_type ON graph_nodes
+BEGIN
+    SELECT CASE
+        WHEN NEW.node_type NOT IN ('project', 'file', 'feature', 'memory', 'task', 'session', 'tag', 'class', 'def')
+        THEN RAISE(ABORT, 'Data Integrity Error: Invalid node type. Must be one of project, file, feature, memory, task, session, tag, class, def')
+    END;
+END;
+
+-- ─── Edge Type Constraints ──────────────────────────────────
+CREATE TRIGGER IF NOT EXISTS val_graph_edges_insert BEFORE INSERT ON graph_edges
+BEGIN
+    SELECT CASE
+        WHEN NEW.edge_type NOT IN ('imports', 'declares', 'references', 'verifies', 'contains', 'supersedes', 'co_edited', 'modified', 'read')
+        THEN RAISE(ABORT, 'Data Integrity Error: Invalid edge type. Must be one of imports, declares, references, verifies, contains, supersedes, co_edited, modified, read')
+    END;
+END;
+
+CREATE TRIGGER IF NOT EXISTS val_graph_edges_update BEFORE UPDATE OF edge_type ON graph_edges
+BEGIN
+    SELECT CASE
+        WHEN NEW.edge_type NOT IN ('imports', 'declares', 'references', 'verifies', 'contains', 'supersedes', 'co_edited', 'modified', 'read')
+        THEN RAISE(ABORT, 'Data Integrity Error: Invalid edge type. Must be one of imports, declares, references, verifies, contains, supersedes, co_edited, modified, read')
+    END;
+END;

package/lib/db-graph.sh

@@ -0,0 +1,138 @@
+#!/usr/bin/env bash
+# ═══════════════════════════════════════════════════════════
+# Eagle Mem — Graph memories helpers
+# Primitives for self-wiring codebase graph and relations
+# ═══════════════════════════════════════════════════════════
+[ -n "${_EAGLE_DB_GRAPH_LOADED:-}" ] && return 0
+_EAGLE_DB_GRAPH_LOADED=1
+
+eagle_graph_add_node() {
+    local project; project=$(eagle_sql_escape "$1")
+    local node_type; node_type=$(eagle_sql_escape "$2")
+    local node_name; node_name=$(eagle_sql_escape "$3")
+    local node_value; node_value=$(eagle_sql_escape "${4:-}")
+    local source_path; source_path=$(eagle_sql_escape "${5:-}")
+
+    eagle_db "INSERT INTO graph_nodes (project, node_type, node_name, node_value, source_path)
+        VALUES ('$project', '$node_type', '$node_name', '$node_value', '$source_path')
+        ON CONFLICT(project, node_type, node_name) DO UPDATE SET
+            node_value = CASE WHEN excluded.node_value != '' THEN excluded.node_value ELSE node_value END,
+            source_path = CASE WHEN excluded.source_path != '' THEN excluded.source_path ELSE source_path END,
+            updated_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now');"
+}
+
+eagle_graph_get_node_id() {
+    local project; project=$(eagle_sql_escape "$1")
+    local node_type; node_type=$(eagle_sql_escape "$2")
+    local node_name; node_name=$(eagle_sql_escape "$3")
+
+    eagle_db "SELECT id FROM graph_nodes
+        WHERE project = '$project'
+        AND node_type = '$node_type'
+        AND node_name = '$node_name'
+        LIMIT 1;"
+}
+
+eagle_graph_add_edge() {
+    local project; project=$(eagle_sql_escape "$1")
+    local source_id; source_id=$(eagle_sql_int "$2")
+    local target_id; target_id=$(eagle_sql_int "$3")
+    local edge_type; edge_type=$(eagle_sql_escape "$4")
+    local weight="${5:-1.0}"
+    if ! [[ "$weight" =~ ^[0-9]+(\.[0-9]+)?$ ]]; then
+        weight="1.0"
+    fi
+
+    [ -z "$source_id" ] || [ -z "$target_id" ] && return 1
+    [ "$source_id" = "$target_id" ] && return 0 # avoid self-loops
+
+    eagle_db "INSERT INTO graph_edges (project, source_node_id, target_node_id, edge_type, weight)
+        VALUES ('$project', $source_id, $target_id, '$edge_type', $weight)
+        ON CONFLICT(project, source_node_id, target_node_id, edge_type) DO UPDATE SET
+            weight = weight + excluded.weight;"
+}
+
+eagle_graph_query_neighbors() {
+    local node_id; node_id=$(eagle_sql_int "$1")
+    local direction="${2:-out}" # 'out', 'in', or 'both'
+
+    if [ "$direction" = "out" ]; then
+        eagle_db "SELECT e.edge_type, e.weight, n.id, n.node_type, n.node_name, n.node_value
+            FROM graph_edges e
+            JOIN graph_nodes n ON e.target_node_id = n.id
+            WHERE e.source_node_id = $node_id
+            ORDER BY e.weight DESC, n.node_name;"
+    elif [ "$direction" = "in" ]; then
+        eagle_db "SELECT e.edge_type, e.weight, n.id, n.node_type, n.node_name, n.node_value
+            FROM graph_edges e
+            JOIN graph_nodes n ON e.source_node_id = n.id
+            WHERE e.target_node_id = $node_id
+            ORDER BY e.weight DESC, n.node_name;"
+    else
+        eagle_db "SELECT 'out' as dir, e.edge_type, e.weight, n.id, n.node_type, n.node_name, n.node_value
+            FROM graph_edges e
+            JOIN graph_nodes n ON e.target_node_id = n.id
+            WHERE e.source_node_id = $node_id
+            UNION ALL
+            SELECT 'in' as dir, e.edge_type, e.weight, n.id, n.node_type, n.node_name, n.node_value
+            FROM graph_edges e
+            JOIN graph_nodes n ON e.source_node_id = n.id
+            WHERE e.target_node_id = $node_id
+            ORDER BY weight DESC;"
+    fi
+}
+
+eagle_graph_search() {
+    local project; project=$(eagle_sql_escape "$1")
+    local query; query=$(eagle_fts_sanitize "$2")
+    local type_filter="${3:-}"
+
+    local sql
+    if [ -n "$type_filter" ]; then
+        local t_esc; t_esc=$(eagle_sql_escape "$type_filter")
+        sql="SELECT n.id, n.node_type, n.node_name, n.node_value, n.source_path
+            FROM graph_nodes n
+            JOIN graph_nodes_fts f ON f.rowid = n.id
+            WHERE n.project = '$project'
+            AND n.node_type = '$t_esc'
+            AND graph_nodes_fts MATCH '$query'
+            ORDER BY rank;"
+    else
+        sql="SELECT n.id, n.node_type, n.node_name, n.node_value, n.source_path
+            FROM graph_nodes n
+            JOIN graph_nodes_fts f ON f.rowid = n.id
+            WHERE n.project = '$project'
+            AND graph_nodes_fts MATCH '$query'
+            ORDER BY rank;"
+    fi
+
+    eagle_db "$sql"
+}
+
+eagle_graph_get_node_by_id() {
+    local node_id; node_id=$(eagle_sql_int "$1")
+    eagle_db "SELECT id, node_type, node_name, node_value, source_path, created_at, updated_at
+        FROM graph_nodes
+        WHERE id = $node_id
+        LIMIT 1;"
+}
+
+eagle_graph_delete_node() {
+    local node_id; node_id=$(eagle_sql_int "$1")
+    eagle_db "DELETE FROM graph_nodes WHERE id = $node_id;"
+}
+
+eagle_graph_prune_orphans() {
+    local project; project=$(eagle_sql_escape "$1")
+    # Delete file nodes that no longer exist on disk
+    local result
+    result=$(eagle_db "SELECT id, node_name FROM graph_nodes WHERE project = '$project' AND node_type = 'file';")
+    [ -z "$result" ] && return 0
+
+    while IFS='|' read -r nid nname; do
+        [ -z "$nid" ] && continue
+        if [ ! -f "$nname" ]; then
+            eagle_graph_delete_node "$nid"
+        fi
+    done <<< "$result"
+}

package/lib/db.sh

@@ -17,3 +17,4 @@ _eagle_db_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 . "$_eagle_db_dir/db-hints.sh"
 . "$_eagle_db_dir/db-backfill.sh"
 . "$_eagle_db_dir/db-guardrails.sh"
+. "$_eagle_db_dir/db-graph.sh"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eagle-mem",
-  "version": "4.10.3",
+  "version": "4.10.4",
   "description": "Shared memory, release guardrails, RTK token protection, and worker lanes for Claude Code, Codex, Grok, and Google Antigravity",
   "bin": {
     "eagle-mem": "bin/eagle-mem"

package/scripts/curate.sh

@@ -521,7 +521,138 @@ else
     eagle_dim "  Not enough session data for hot file detection (need 3+ sessions, have ${total_sessions:-0})"
 fi
 
-# ─── 7. Session compression (--full only) ─────────────────
+# ─── 7. Knowledge Graph Wiring & Dream Cycle (Consolidation) ───
+
+eagle_info "Executing Dream Cycle (Knowledge Graph & Memory Consolidation)..."
+
+# 7.1 Wire co-edit edges in the graph
+if [ -n "$co_edit_data" ]; then
+    co_wire_count=0
+    while IFS='|' read -r f1 f2 co_sessions; do
+        [ -z "$f1" ] || [ -z "$f2" ] && continue
+        f1_id=$(eagle_graph_get_node_id "$project" "file" "$f1")
+        f2_id=$(eagle_graph_get_node_id "$project" "file" "$f2")
+        if [ -n "$f1_id" ] && [ -n "$f2_id" ]; then
+            if [ "$DRY_RUN" -eq 0 ]; then
+                eagle_graph_add_edge "$project" "$f1_id" "$f2_id" "co_edited" "$co_sessions"
+            fi
+            co_wire_count=$((co_wire_count + 1))
+        fi
+    done <<< "$co_edit_data"
+    eagle_ok "Wired $co_wire_count co-edited file edges"
+fi
+
+# 7.2 Wire session nodes and access edges
+recent_sessions=$(eagle_db "SELECT id, started_at, model FROM sessions WHERE project = '$p_esc' ORDER BY started_at DESC LIMIT 15;")
+if [ -n "$recent_sessions" ]; then
+    session_wire_count=0
+    while IFS='|' read -r sid sstart smodel; do
+        [ -z "$sid" ] && continue
+        if [ "$DRY_RUN" -eq 0 ]; then
+            eagle_graph_add_node "$project" "session" "$sid" "Session run on $sstart using $smodel" ""
+            sid_node=$(eagle_graph_get_node_id "$project" "session" "$sid")
+            if [ -n "$sid_node" ]; then
+                # Find read/modified files in this session from observations
+                session_files=$(eagle_db "SELECT files_read, files_modified FROM observations WHERE session_id = '$(eagle_sql_escape "$sid")';")
+                if [ -n "$session_files" ]; then
+                    while IFS='|' read -r f_read f_mod; do
+                        # Parse files_read JSON list
+                        if [ -n "$f_read" ] && [ "$f_read" != "[]" ]; then
+                            echo "$f_read" | grep -oE '"[^"]+"' | tr -d '"' | while read -r rf; do
+                                [ -z "$rf" ] && continue
+                                rfid=$(eagle_graph_get_node_id "$project" "file" "$rf")
+                                [ -n "$rfid" ] && eagle_graph_add_edge "$project" "$sid_node" "$rfid" "read" 1.0
+                            done
+                        fi
+                        # Parse files_modified JSON list
+                        if [ -n "$f_mod" ] && [ "$f_mod" != "[]" ]; then
+                            echo "$f_mod" | grep -oE '"[^"]+"' | tr -d '"' | while read -r mf; do
+                                [ -z "$mf" ] && continue
+                                mfid=$(eagle_graph_get_node_id "$project" "file" "$mf")
+                                [ -n "$mfid" ] && eagle_graph_add_edge "$project" "$sid_node" "$mfid" "modified" 2.0
+                            done
+                        fi
+                    done <<< "$session_files"
+                fi
+            fi
+        fi
+        session_wire_count=$((session_wire_count + 1))
+    done <<< "$recent_sessions"
+    eagle_ok "Wired $session_wire_count recent session nodes and edges"
+fi
+
+# 7.3 Offline Memory Consolidation (Compiled Truth vs Evidence)
+active_memories=$(eagle_db "SELECT memory_name, memory_type, description, content FROM agent_memories WHERE project = '$p_esc';")
+if [ -n "$active_memories" ]; then
+    consolidation_prompt="Analyze these mirrored agent memories for project '$project'. Identify any memories that are redundant, overlap in scope, or describe the same subsystem/gotcha/concept.
+    
+MEMORIES:
+$active_memories
+
+For any memories that should be consolidated, merge them into a single 'Compiled Truth' summary.
+The consolidated memory MUST be formatted exactly as:
+--- Compiled Truth ---
+<A structured, clear, up-to-date summary of the topic, gotten by merging the duplicate/overlapping memories. Keep it extremely precise.>
+
+--- Evidence Trail ---
+- <Original memory title 1>: <brief original description or timestamp>
+- <Original memory title 2>: <brief original description or timestamp>
+
+Format your output as a series of instructions:
+CONSOLIDATE: <original memory name 1>, <original memory name 2> -> <new consolidated memory name> | description: <new description> | value: <the merged compiled truth + evidence content>
+
+If no memories need consolidation, output: NONE"
+
+    consolidation_result=$(eagle_llm_call "$consolidation_prompt" "You consolidate software development memories into a single compiled truth. Be precise. Output CONSOLIDATE lines or NONE." 1024)
+
+    if [ -n "$consolidation_result" ] && ! echo "$consolidation_result" | grep -q "^NONE$"; then
+        cons_count=0
+        while IFS= read -r line; do
+            case "$line" in
+                CONSOLIDATE:*)
+                    cons_data=$(echo "$line" | sed 's/^CONSOLIDATE:[[:space:]]*//')
+                    
+                    # Parse matching: original_names -> new_name | description: desc | value: val
+                    names_part=$(echo "$cons_data" | cut -d'-' -f1 | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
+                    rest_part=$(echo "$cons_data" | cut -d'>' -f2-)
+                    new_name=$(echo "$rest_part" | cut -d'|' -f1 | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
+                    
+                    desc_part=$(echo "$rest_part" | grep -oE "description:[[:space:]]*[^|]+" | sed 's/description:[[:space:]]*//')
+                    val_part=$(echo "$rest_part" | grep -oE "value:[[:space:]]*.+" | sed 's/value:[[:space:]]*//')
+                    
+                    [ -z "$new_name" ] || [ -z "$names_part" ] && continue
+                    
+                    if [ "$DRY_RUN" -eq 1 ]; then
+                        eagle_info "  Would consolidate: $names_part → $new_name"
+                    else
+                        # 1. Add new consolidated memory node
+                        eagle_graph_add_node "$project" "memory" "$new_name" "$val_part" ""
+                        new_node_id=$(eagle_graph_get_node_id "$project" "memory" "$new_name")
+                        
+                        # 2. Wire supersedes edges from new node to old nodes, and mark old nodes as inactive/superseded
+                        IFS=',' read -ra name_arr <<< "$names_part"
+                        for old_n in "${name_arr[@]}"; do
+                            old_n=$(echo "$old_n" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
+                            [ -z "$old_n" ] && continue
+                            old_node_id=$(eagle_graph_get_node_id "$project" "memory" "$old_n")
+                            if [ -n "$old_node_id" ] && [ -n "$new_node_id" ]; then
+                                eagle_graph_add_edge "$project" "$new_node_id" "$old_node_id" "supersedes" 1.0
+                            fi
+                        done
+                        cons_count=$((cons_count + 1))
+                    fi
+                    ;;
+            esac
+        done <<< "$consolidation_result"
+        eagle_ok "Consolidated $cons_count sets of overlapping agent memories"
+    else
+        eagle_ok "Agent memories are fully consolidated and up to date"
+    fi
+else
+    eagle_dim "  No active agent memories to consolidate"
+fi
+
+# ─── 8. Session compression (--full only) ─────────────────
 
 if [ "$FULL" -eq 1 ]; then
     eagle_info "Compressing old sessions..."

package/scripts/index.sh

@@ -178,6 +178,50 @@ COMMIT;"
 
     eagle_db_pipe <<< "$txn_sql"
 
+    # Static syntax relation extraction & graph wiring
+    # Wire node & edge static parser
+    file_node_id=$(eagle_graph_get_node_id "$PROJECT" "file" "$file")
+    if [ -n "$file_node_id" ]; then
+        # 1. Parse function/class declarations
+        # e.g., "def name", "class name", "fn name", "function name", "func name"
+        declarations=$(grep -oE '\<(class|struct|function|def|fn|func)[[:space:]]+[A-Za-z0-9_]+' "$full_path" 2>/dev/null | awk '{print $1 ":" $2}' | sort -u || true)
+        if [ -n "$declarations" ]; then
+            while IFS=':' read -r dtype dname; do
+                [ -z "$dname" ] && continue
+                eagle_graph_add_node "$PROJECT" "$dtype" "$dname" "Declared in $file" "$file"
+                decl_node_id=$(eagle_graph_get_node_id "$PROJECT" "$dtype" "$dname")
+                if [ -n "$decl_node_id" ]; then
+                    eagle_graph_add_edge "$PROJECT" "$file_node_id" "$decl_node_id" "declares" 1.0
+                fi
+            done <<< "$declarations"
+        fi
+
+        # 2. Parse local relative imports/requires/sources
+        # Matches paths starting with dot (./ or ../) or sourcing .sh files
+        local_imports=$(grep -oE "['\"](\.[^'\"]+)['\"]" "$full_path" 2>/dev/null | tr -d "'\"" || true)
+        # Also grab shell source files
+        shell_sources=$(grep -E "^[[:space:]]*(\.|source) " "$full_path" 2>/dev/null | sed -E "s/^[[:space:]]*(\.|source)[[:space:]]+(.*)/\\2/" || true)
+        
+        all_refs=$(printf "%s\n%s\n" "$local_imports" "$shell_sources" | sort -u)
+        if [ -n "$all_refs" ]; then
+            while IFS= read -r ref; do
+                [ -z "$ref" ] && continue
+                # Clean up path variables in shell sources (e.g. $_eagle_db_dir/db-core.sh -> db-core.sh)
+                ref_clean=$(echo "$ref" | sed -E 's/.*\///; s/\.sh$//; s/\.js$//; s/\.ts$//')
+                [ -z "$ref_clean" ] && continue
+                
+                # Check if there is a known file node in our graph that matches this basename or path
+                matched_file=$(eagle_db "SELECT node_name FROM graph_nodes WHERE project = '$project_sql' AND node_type = 'file' AND (node_name LIKE '%/$ref_clean%' OR node_name = '$ref_clean') LIMIT 1;")
+                if [ -n "$matched_file" ]; then
+                    target_file_id=$(eagle_graph_get_node_id "$PROJECT" "file" "$matched_file")
+                    if [ -n "$target_file_id" ]; then
+                        eagle_graph_add_edge "$PROJECT" "$file_node_id" "$target_file_id" "imports" 1.0
+                    fi
+                fi
+            done <<< "$all_refs"
+        fi
+    fi
+
     file_count=$((file_count + 1))
 
     if [ $((file_count % 10)) -eq 0 ]; then

package/scripts/memories.sh

@@ -45,6 +45,9 @@ show_help() {
     echo -e "    eagle-mem memories tasks search ${CYAN}<query>${RESET}     ${DIM}# full-text search tasks${RESET}"
     echo -e "    eagle-mem memories tasks show ${CYAN}<file_path>${RESET}   ${DIM}# show a specific task${RESET}"
     echo -e "    eagle-mem memories sync                     ${DIM}# backfill memories + plans + tasks${RESET}"
+    echo -e "    eagle-mem memories graph                    ${DIM}# view codebase knowledge graph summary${RESET}"
+    echo -e "    eagle-mem memories graph query ${CYAN}<term>${RESET}      ${DIM}# search knowledge graph nodes${RESET}"
+    echo -e "    eagle-mem memories graph neighbors ${CYAN}<name>${RESET}  ${DIM}# view a node's local network connections${RESET}"
     echo ""
     echo -e "  ${BOLD}Options:${RESET}"
     echo -e "    ${CYAN}-p, --project${RESET} <name>  Filter by project (default: current project)"
@@ -62,6 +65,7 @@ show_help() {
 
 plan_action=""
 task_action=""
+graph_action=""
 
 case "$action" in
     --help|-h) show_help ;;
@@ -73,6 +77,10 @@ case "$action" in
         task_action="${1:-list}"
         shift 2>/dev/null || true
         ;;
+    graph)
+        graph_action="${1:-summary}"
+        shift 2>/dev/null || true
+        ;;
 esac
 
 while [ $# -gt 0 ]; do
@@ -858,6 +866,116 @@ EOF
     eagle_footer "Sync complete."
 }
 
+memories_graph() {
+    local sub_action="${graph_action:-summary}"
+
+    case "$sub_action" in
+        query)
+            local qstr="${query:-}"
+            if [ -z "$qstr" ]; then
+                eagle_err "Usage: eagle-mem memories graph query <search_term>"
+                exit 1
+            fi
+            eagle_header "Knowledge Graph Query"
+            eagle_info "Search Term: $qstr"
+            echo ""
+            
+            local nodes
+            nodes=$(eagle_graph_search "$project" "$qstr" "")
+            if [ -z "$nodes" ]; then
+                eagle_dim "No graph nodes found matching '$qstr'."
+                echo ""
+                return
+            fi
+            
+            while IFS='|' read -r nid ntype nname nval npath; do
+                [ -z "$nid" ] && continue
+                echo -e "  ${BOLD}${nname}${RESET}  ${CYAN}[${ntype}]${RESET} ${DIM}(ID: ${nid})${RESET}"
+                [ -n "$nval" ] && echo -e "    ${DIM}${nval}${RESET}"
+                [ -n "$npath" ] && echo -e "    ${DIM}Path: ${npath}${RESET}"
+                echo ""
+            done <<< "$nodes"
+            ;;
+        neighbors)
+            local target_name="${query:-}"
+            if [ -z "$target_name" ]; then
+                eagle_err "Usage: eagle-mem memories graph neighbors <node_name>"
+                exit 1
+            fi
+            
+            # Find node by name (fuzzy or exact)
+            local matched
+            matched=$(eagle_db "SELECT id, node_type, node_name FROM graph_nodes WHERE project = '$(eagle_sql_escape "$project")' AND (node_name = '$(eagle_sql_escape "$target_name")' OR node_name LIKE '%$(eagle_sql_escape "$target_name")%') LIMIT 1;")
+            if [ -z "$matched" ]; then
+                eagle_err "Node not found matching '$target_name'."
+                exit 1
+            fi
+            
+            IFS='|' read -r nid ntype nname <<< "$matched"
+            eagle_header "Graph Neighbors"
+            eagle_info "Node: ${BOLD}${nname}${RESET}  ${CYAN}[${ntype}]${RESET} (ID: ${nid})"
+            echo ""
+            
+            # Query inbound and outbound neighbors
+            eagle_info "Outbound Connections (Node interacts with/references/contains):"
+            local outbound
+            outbound=$(eagle_graph_query_neighbors "$nid" "out")
+            if [ -n "$outbound" ]; then
+                while IFS='|' read -r etype eweight target_id target_type target_name _; do
+                    [ -z "$target_id" ] && continue
+                    echo -e "  ${BOLD}───[ ${etype} ]───>${RESET} ${CYAN}${target_name}${RESET} [${target_type}] ${DIM}(weight: ${eweight})${RESET}"
+                done <<< "$outbound"
+            else
+                eagle_dim "  None"
+            fi
+            echo ""
+            
+            eagle_info "Inbound Connections (Other nodes reference/call/contain this node):"
+            local inbound
+            inbound=$(eagle_graph_query_neighbors "$nid" "in")
+            if [ -n "$inbound" ]; then
+                while IFS='|' read -r etype eweight source_id source_type source_name _; do
+                    [ -z "$source_id" ] && continue
+                    echo -e "  ${CYAN}${source_name}${RESET} [${source_type}] ${BOLD}───[ ${etype} ]───>${RESET} this ${DIM}(weight: ${eweight})${RESET}"
+                done <<< "$inbound"
+            else
+                eagle_dim "  None"
+            fi
+            echo ""
+            ;;
+        summary|*)
+            eagle_header "Knowledge Graph Summary"
+            echo ""
+            
+            local totals
+            totals=$(eagle_db "SELECT node_type, COUNT(*) FROM graph_nodes WHERE project = '$(eagle_sql_escape "$project")' GROUP BY node_type;")
+            
+            local total_edges
+            total_edges=$(eagle_db "SELECT COUNT(*) FROM graph_edges WHERE project = '$(eagle_sql_escape "$project")';")
+            
+            if [ -z "$totals" ]; then
+                eagle_dim "Graph is empty for this project."
+                eagle_dim "Run 'eagle-mem scan' or 'eagle-mem index' to auto-populate codebase nodes."
+                echo ""
+                return
+            fi
+            
+            eagle_info "Entities (Nodes):"
+            while IFS='|' read -r ntype count; do
+                [ -z "$ntype" ] && continue
+                eagle_kv "  ${ntype}:" "${count} nodes"
+            done <<< "$totals"
+            echo ""
+            eagle_kv "Total relationships (Edges):" "${total_edges:-0} edges"
+            echo ""
+            eagle_dim "Commands:"
+            eagle_dim "  eagle-mem memories graph query <search_term>     # search graph nodes"
+            eagle_dim "  eagle-mem memories graph neighbors <node_name>    # view neighbor connections"
+            echo ""
+            ;;
+    esac
+}
+
 # ─── Dispatch ────────────────────────────────────────────
 
 case "$action" in
@@ -880,6 +998,7 @@ case "$action" in
             *)       tasks_list ;;
         esac
         ;;
+    graph)   memories_graph "$@" ;;
     sync)    memories_sync ;;
     *)
         eagle_err "Unknown action: $action"

package/scripts/scan.sh

@@ -367,7 +367,29 @@ fi
 # Store in database
 eagle_upsert_overview "$PROJECT" "$overview" "scan"
 
-eagle_ok "Overview saved for project '$PROJECT'"
+# Populate/wire codebase knowledge graph
+eagle_graph_add_node "$PROJECT" "project" "$PROJECT" "$overview" ""
+project_node_id=$(eagle_graph_get_node_id "$PROJECT" "project" "$PROJECT")
+
+# Prune deleted/removed files from graph
+eagle_graph_prune_orphans "$PROJECT"
+
+file_node_count=0
+if [ -n "$project_node_id" ]; then
+    while IFS= read -r file; do
+        [ -z "$file" ] && continue
+        # Add file node
+        eagle_graph_add_node "$PROJECT" "file" "$file" "" "$TARGET_DIR/$file"
+        file_node_id=$(eagle_graph_get_node_id "$PROJECT" "file" "$file")
+        if [ -n "$file_node_id" ]; then
+            # Connect project containing this file
+            eagle_graph_add_edge "$PROJECT" "$project_node_id" "$file_node_id" "contains" 1.0
+        fi
+        file_node_count=$((file_node_count + 1))
+    done < "$TMPFILE"
+fi
+
+eagle_ok "Overview saved for project '$PROJECT' (wired $file_node_count files in knowledge graph)"
 echo ""
 
 echo -e "  ${BOLD}Generated overview:${RESET}"