eagle-mem 3.0.1 → 3.0.2

package/hooks/post-tool-use.sh

@@ -2,7 +2,7 @@
 # ═══════════════════════════════════════════════════════════
 # Eagle Mem — PostToolUse hook
 # Fires after every tool use
-# Captures file read/write operations as lightweight observations
+# Captures observations + dispatches to extracted responsibilities
 # ═══════════════════════════════════════════════════════════
 set +e
 
@@ -11,6 +11,7 @@ LIB_DIR="$SCRIPT_DIR/../lib"
 
 . "$LIB_DIR/common.sh"
 . "$LIB_DIR/db.sh"
+. "$LIB_DIR/hooks-posttool.sh"
 
 input=$(eagle_read_stdin)
 [ -z "$input" ] && exit 0
@@ -35,6 +36,9 @@ project=$(eagle_project_from_cwd "$cwd")
 # PostToolUse can race SessionStart — the session row might not exist yet.
 eagle_upsert_session "$session_id" "$project" "$cwd" "" ""
 
+# ─── Extract observation data from tool call ──────────────
+
+fp=""
 files_read="[]"
 files_modified="[]"
 tool_summary=""
@@ -63,14 +67,12 @@ case "$tool_name" in
         cmd=$(echo "$cmd" | eagle_redact)
         tool_summary="Bash: $cmd"
 
-        # Output metrics
         tool_output=$(echo "$input" | jq -r '.tool_result.stdout // empty' 2>/dev/null)
         if [ -n "$tool_output" ]; then
             output_bytes=${#tool_output}
             output_lines=$(echo "$tool_output" | wc -l | tr -d ' ')
         fi
 
-        # Command category extraction
         first_word=$(echo "$cmd" | awk '{print $1}' | sed 's|.*/||')
         case "$first_word" in
             git|gh) command_category="git" ;;
@@ -95,151 +97,14 @@ case "$tool_name" in
         ;;
 esac
 
-# ─── Claude memory + plan mirror ─────────────────────────
-# Intercept writes to Claude Code's auto-memory and plan files
-case "$tool_name" in
-    Write|Edit)
-        if [ -n "$fp" ]; then
-            # Reject path traversal: bash case `*` matches `/`, so
-            # patterns like projects/*/memory/*.md would match paths
-            # containing /../ segments. Block any path with `..` first.
-            case "$fp" in
-                *..*) ;; # path traversal — skip
-                "$HOME/.claude/projects"/*/memory/*.md)
-                    mem_base=$(basename "$fp")
-                    if [ "$mem_base" != "MEMORY.md" ] && [ -f "$fp" ]; then
-                        eagle_capture_claude_memory "$fp" "$session_id" "$project"
-                    fi
-                    ;;
-                "$HOME/.claude/plans/"*.md)
-                    if [ -f "$fp" ]; then
-                        eagle_capture_claude_plan "$fp" "$session_id" "$project"
-                    fi
-                    ;;
-            esac
-        fi
-        ;;
-esac
-
-# ─── Claude task mirror ─────────────────────────────────
-# Intercept TaskCreate/TaskUpdate and capture the resulting JSON files
-case "$tool_name" in
-    TaskCreate|TaskUpdate)
-        if eagle_validate_session_id "$session_id"; then
-            task_dir="$HOME/.claude/tasks/$session_id"
-            if [ -d "$task_dir" ]; then
-                task_id=$(echo "$input" | jq -r '.tool_input.id // empty')
-                if [ -z "$task_id" ]; then
-                    newest=$(ls -t "$task_dir"/*.json 2>/dev/null | head -1)
-                    [ -n "$newest" ] && [ -f "$newest" ] && eagle_capture_claude_task "$newest" "$session_id" "$project"
-                elif eagle_validate_session_id "$task_id"; then
-                    task_json="$task_dir/$task_id.json"
-                    [ -f "$task_json" ] && eagle_capture_claude_task "$task_json" "$session_id" "$project"
-                fi
-            fi
-        fi
-        ;;
-esac
+# ─── Dispatch to extracted responsibilities ───────────────
 
-# ─── Stale memory hint ──────────────────────────────────
-# After editing a project file, FTS5-search memories for the filename.
-# If a memory mentions this file, remind Claude to check for staleness.
-case "$tool_name" in
-    Write|Edit)
-        if [ -n "$fp" ]; then
-            fname=$(basename "$fp")
-            fname_stem="${fname%.*}"
-            case "$fp" in
-                "$HOME/.claude/"*) ;; # skip Claude config files
-                *)
-                    if [ ${#fname_stem} -ge 3 ]; then
-                        fts_query=$(eagle_fts_sanitize "$fname_stem")
-                        if [ -n "$fts_query" ]; then
-                            fts_esc=$(eagle_sql_escape "$fts_query")
-                            p_esc=$(eagle_sql_escape "$project")
-                            stale_hit=$(eagle_db "SELECT m.memory_name
-                                FROM claude_memories m
-                                JOIN claude_memories_fts f ON f.rowid = m.id
-                                WHERE claude_memories_fts MATCH '$fts_esc'
-                                AND m.project = '$p_esc'
-                                LIMIT 1;")
-                            if [ -n "$stale_hit" ]; then
-                                stale_msg="Eagle Mem: Memory '${stale_hit}' may reference '${fname}'. If your edit contradicts it, update the memory."
-                                jq -nc --arg ctx "$stale_msg" '{"hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":$ctx}}'
-                            fi
-                        fi
-                    fi
-                    ;;
-            esac
-        fi
-        ;;
-esac
+eagle_posttool_mirror_writes "$tool_name" "$fp" "$session_id" "$project"
+eagle_posttool_mirror_tasks "$tool_name" "$session_id" "$project" "$input"
+eagle_posttool_stale_hint "$tool_name" "$fp" "$project"
+eagle_posttool_decision_surface "$tool_name" "$fp" "$project"
 
-# ─── Decision + feature surfacing on Read ──────────────────
-# When Claude reads a file, surface past decisions and feature pipeline context.
-case "$tool_name" in
-    Read)
-        if [ -n "$fp" ]; then
-            fname=$(basename "$fp")
-            fname_stem="${fname%.*}"
-            read_context=""
-            case "$fp" in
-                "$HOME/.claude/"*) ;; # skip Claude config files
-                *)
-                    p_esc=$(eagle_sql_escape "$project")
-
-                    # Decision history from summaries
-                    if [ ${#fname_stem} -ge 3 ]; then
-                        fts_query=$(eagle_fts_sanitize "$fname_stem")
-                        if [ -n "$fts_query" ]; then
-                            fts_esc=$(eagle_sql_escape "$fts_query")
-                            decision_hit=$(eagle_db "SELECT s.decisions
-                                FROM summaries s
-                                JOIN summaries_fts f ON f.rowid = s.id
-                                WHERE summaries_fts MATCH '$fts_esc'
-                                AND s.project = '$p_esc'
-                                AND s.decisions IS NOT NULL
-                                AND s.decisions != ''
-                                ORDER BY s.created_at DESC
-                                LIMIT 1;")
-                            if [ -n "$decision_hit" ]; then
-                                read_context+="Eagle Mem decision history for '${fname}': ${decision_hit} — Do not revert without explicit user request. "
-                            fi
-                        fi
-                    fi
-
-                    # Feature pipeline context
-                    feature_hit=$(eagle_find_features_for_file "$project" "$fp")
-                    if [ -n "$feature_hit" ]; then
-                        while IFS='|' read -r feat_name feat_desc feat_verified _role feat_deps feat_other_files feat_smoke; do
-                            [ -z "$feat_name" ] && continue
-                            read_context+="Eagle Mem: '${fname}' is part of feature '${feat_name}'"
-                            [ -n "$feat_desc" ] && read_context+=" ($feat_desc)"
-                            read_context+="."
-                            if [ -n "$feat_verified" ]; then
-                                read_context+=" Last verified: ${feat_verified}."
-                            fi
-                            if [ -n "$feat_deps" ]; then
-                                read_context+=" Dependencies: ${feat_deps}."
-                            fi
-                            if [ -n "$feat_other_files" ]; then
-                                read_context+=" Other files in pipeline: ${feat_other_files}."
-                            fi
-                            if [ -n "$feat_smoke" ]; then
-                                read_context+=" Smoke tests: ${feat_smoke}."
-                            fi
-                            read_context+=" Changes require re-testing after deploy. "
-                        done <<< "$feature_hit"
-                    fi
-
-                    if [ -n "$read_context" ]; then
-                        jq -nc --arg ctx "$read_context" '{"hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":$ctx}}'
-                    fi
-                    ;;
-            esac
-        fi
-        ;;
-esac
+# ─── Record observation ──────────────────────────────────
 
 if ! eagle_insert_observation "$session_id" "$project" "$tool_name" "$tool_summary" "$files_read" "$files_modified" "$output_bytes" "$output_lines" "$command_category"; then
     eagle_log "ERROR" "PostToolUse: observation insert failed for session=$session_id tool=$tool_name"

package/hooks/pre-tool-use.sh

@@ -27,7 +27,6 @@ cmd=$(echo "$input" | jq -r '.tool_input.command // empty')
 session_id=$(echo "$input" | jq -r '.session_id // empty')
 cwd=$(echo "$input" | jq -r '.cwd // empty')
 project=$(eagle_project_from_cwd "$cwd")
-p_esc=$(eagle_sql_escape "$project")
 
 context=""
 
@@ -35,7 +34,7 @@ context=""
 
 case "$cmd" in
     *"git push"*|*"gh pr create"*)
-        has_features=$(eagle_db "SELECT COUNT(*) FROM features WHERE project = '$p_esc' AND status = 'active';")
+        has_features=$(eagle_count_active_features "$project")
         if [ "${has_features:-0}" -gt 0 ]; then
             changed_files=""
             if [ -n "$cwd" ] && [ -d "$cwd" ]; then
@@ -49,19 +48,8 @@ case "$cmd" in
                     [ -z "$changed_file" ] && continue
                     fname=$(basename "$changed_file")
                     fname_esc=$(eagle_sql_escape "$fname")
-                    fname_like=$(eagle_like_escape "$fname_esc")
-
-                    feature_hits=$(eagle_db "SELECT DISTINCT f.name,
-                        (SELECT GROUP_CONCAT(fst.command, '; ')
-                         FROM feature_smoke_tests fst WHERE fst.feature_id = f.id) as smoke,
-                        (SELECT GROUP_CONCAT(fd.target || ':' || fd.name, ', ')
-                         FROM feature_dependencies fd WHERE fd.feature_id = f.id) as deps,
-                        f.last_verified_at
-                        FROM features f
-                        JOIN feature_files ff ON ff.feature_id = f.id
-                        WHERE f.project = '$p_esc'
-                        AND f.status = 'active'
-                        AND (ff.file_path LIKE '%$fname_like' ESCAPE '\\' OR ff.file_path LIKE '%$fname_like%' ESCAPE '\\');")
+
+                    feature_hits=$(eagle_find_feature_for_push "$project" "$fname_esc")
 
                     while IFS='|' read -r feat_name feat_smoke feat_deps feat_verified; do
                         [ -z "$feat_name" ] && continue
@@ -93,16 +81,8 @@ esac
 
 # Extract the base command for rule matching
 base_cmd=$(echo "$cmd" | awk '{print $1}' | sed 's|.*/||')
-cmd_esc=$(eagle_sql_escape "$base_cmd")
-
-rule=$(eagle_db "SELECT strategy, max_lines, reason
-    FROM command_rules
-    WHERE enabled = 1
-    AND (project = '$p_esc' OR project IS NULL)
-    AND ('$cmd_esc' LIKE pattern OR '$cmd_esc' = pattern)
-    ORDER BY
-        CASE WHEN project IS NOT NULL THEN 0 ELSE 1 END
-    LIMIT 1;")
+
+rule=$(eagle_get_command_rule "$project" "$base_cmd")
 
 if [ -n "$rule" ]; then
     IFS='|' read -r strategy max_lines reason <<< "$rule"

package/hooks/session-end.sh

@@ -25,7 +25,7 @@ project=$(eagle_project_from_cwd "$cwd")
 # Final sweep: re-capture all task files to catch status changes
 # Claude Code may update task status without triggering PostToolUse
 if eagle_validate_session_id "$session_id"; then
-    task_dir="$HOME/.claude/tasks/$session_id"
+    task_dir="$EAGLE_CLAUDE_TASKS_DIR/$session_id"
     if [ -d "$task_dir" ]; then
         for task_file in "$task_dir"/*.json; do
             [ ! -f "$task_file" ] && continue

package/hooks/session-start.sh

@@ -33,10 +33,7 @@ eagle_upsert_session "$session_id" "$project" "$cwd" "$model" "$source_type"
 # ─── Sweep stuck sessions (no activity for 7 days) ─────────
 # Uses last_activity_at (updated by trigger on every observation insert)
 # so long-lived sessions with regular compactions aren't falsely abandoned
-eagle_db "UPDATE sessions SET status = 'abandoned'
-    WHERE status = 'active'
-    AND id != '$(eagle_sql_escape "$session_id")'
-    AND COALESCE(last_activity_at, started_at) < strftime('%Y-%m-%dT%H:%M:%fZ', 'now', '-7 days');"
+eagle_abandon_stale_sessions "$session_id"
 
 # ─── Version check (non-blocking) ────────────────────────────
 
@@ -68,30 +65,27 @@ fi
 
 # ─── Gather stats ───────────────────────────────────────────
 
-p_esc=$(eagle_sql_escape "$project")
-
-stat_sessions=$(eagle_db "SELECT COUNT(*) FROM sessions WHERE project = '$p_esc';")
-stat_summaries=$(eagle_db "SELECT COUNT(*) FROM summaries WHERE project = '$p_esc';")
-stat_memories=$(eagle_db "SELECT COUNT(*) FROM claude_memories WHERE project = '$p_esc';")
-stat_tasks_pending=$(eagle_db "SELECT COUNT(*) FROM claude_tasks WHERE project = '$p_esc' AND status = 'pending';")
-stat_tasks_progress=$(eagle_db "SELECT COUNT(*) FROM claude_tasks WHERE project = '$p_esc' AND status = 'in_progress';")
-stat_tasks_done=$(eagle_db "SELECT COUNT(*) FROM claude_tasks WHERE project = '$p_esc' AND status = 'completed';")
-stat_chunks=$(eagle_db "SELECT COUNT(*) FROM code_chunks WHERE project = '$p_esc';")
-stat_observations=$(eagle_db "SELECT COUNT(*) FROM observations WHERE session_id IN (SELECT id FROM sessions WHERE project = '$p_esc');")
-stat_plans=$(eagle_db "SELECT COUNT(*) FROM claude_plans WHERE project = '$p_esc';")
-stat_last_active=$(eagle_db "SELECT COALESCE(MAX(date(COALESCE(last_activity_at, started_at))), 'never') FROM sessions WHERE project = '$p_esc';")
-stat_last_summary=$(eagle_db "SELECT request FROM summaries WHERE project = '$p_esc' ORDER BY created_at DESC LIMIT 1;")
-
-# Trim to defaults
-stat_sessions="${stat_sessions:-0}"
-stat_summaries="${stat_summaries:-0}"
-stat_memories="${stat_memories:-0}"
-stat_tasks_pending="${stat_tasks_pending:-0}"
-stat_tasks_progress="${stat_tasks_progress:-0}"
-stat_tasks_done="${stat_tasks_done:-0}"
-stat_chunks="${stat_chunks:-0}"
-stat_observations="${stat_observations:-0}"
-stat_plans="${stat_plans:-0}"
+stat_sessions=0; stat_summaries=0; stat_with_summaries=0; stat_memories=0
+stat_tasks_pending=0; stat_tasks_progress=0; stat_tasks_done=0
+stat_chunks=0; stat_observations=0; stat_plans=0
+stat_last_active="never"; stat_last_summary=""
+
+while IFS='|' read -r key val; do
+    case "$key" in
+        sessions)        stat_sessions="$val" ;;
+        summaries)       stat_summaries="$val" ;;
+        with_summaries)  stat_with_summaries="$val" ;;
+        memories)        stat_memories="$val" ;;
+        plans)           stat_plans="$val" ;;
+        tasks_pending)   stat_tasks_pending="$val" ;;
+        tasks_progress)  stat_tasks_progress="$val" ;;
+        tasks_done)      stat_tasks_done="$val" ;;
+        chunks)          stat_chunks="$val" ;;
+        observations)    stat_observations="$val" ;;
+        last_active)     stat_last_active="$val" ;;
+        last_summary)    stat_last_summary="$val" ;;
+    esac
+done <<< "$(eagle_get_project_stats "$project")"
 
 # Build task summary line
 task_parts=""
@@ -117,7 +111,7 @@ eagle_banner="======================================
        Eagle Mem Loaded
 ======================================
  Project      | $project
- Sessions     | $stat_sessions total ($stat_summaries with summaries)
+ Sessions     | $stat_sessions total ($stat_with_summaries with summaries)
  Memories     | $stat_memories stored
  Plans        | $stat_plans saved
  Tasks        | $task_parts

package/hooks/stop.sh

@@ -116,7 +116,7 @@ fi
 if [ -z "$request" ] && [ -n "$transcript_path" ] && [ -f "$transcript_path" ]; then
     # Skip heuristic if we already have a summary for this session.
     # Stop fires every turn -- without this guard, each turn creates a duplicate row.
-    existing_count=$(eagle_db "SELECT COUNT(*) FROM summaries WHERE session_id = '$(eagle_sql_escape "$session_id")';")
+    existing_count=$(eagle_count_session_summaries "$session_id")
     if [ "${existing_count:-0}" -gt 0 ]; then
         eagle_log "INFO" "Stop: skipping heuristic — summary already exists for session=$session_id (count=$existing_count)"
     else

package/lib/common.sh

@@ -9,6 +9,9 @@ EAGLE_MEM_DB="$EAGLE_MEM_DIR/memory.db"
 EAGLE_MEM_LOG="$EAGLE_MEM_DIR/eagle-mem.log"
 EAGLE_SETTINGS="${EAGLE_SETTINGS:-$HOME/.claude/settings.json}"
 EAGLE_SKILLS_DIR="$HOME/.claude/skills"
+EAGLE_CLAUDE_PROJECTS_DIR="$HOME/.claude/projects"
+EAGLE_CLAUDE_PLANS_DIR="$HOME/.claude/plans"
+EAGLE_CLAUDE_TASKS_DIR="$HOME/.claude/tasks"
 
 eagle_log() {
     local level="$1"

package/lib/db-backfill.sh

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+# ═══════════════════════════════════════════════════════════
+# Eagle Mem — Backfill + orphan cleanup helpers
+# ═══════════════════════════════════════════════════════════
+[ -n "${_EAGLE_DB_BACKFILL_LOADED:-}" ] && return 0
+_EAGLE_DB_BACKFILL_LOADED=1
+
+eagle_build_session_project_map() {
+    local claude_projects_dir="$EAGLE_CLAUDE_PROJECTS_DIR"
+    [ ! -d "$claude_projects_dir" ] && return 0
+
+    for proj_dir in "$claude_projects_dir"/*/; do
+        [ ! -d "$proj_dir" ] && continue
+
+        local project=""
+        local sample_jsonl
+        sample_jsonl=$(ls "$proj_dir"*.jsonl 2>/dev/null | head -1)
+        if [ -n "$sample_jsonl" ] && [ -f "$sample_jsonl" ]; then
+            local cwd
+            cwd=$(head -10 "$sample_jsonl" | jq -r 'select(.cwd != null) | .cwd' 2>/dev/null | head -1)
+            if [ -n "$cwd" ]; then
+                project=$(eagle_project_from_cwd "$cwd")
+            fi
+        fi
+        [ -z "$project" ] && continue
+
+        for jsonl in "$proj_dir"*.jsonl; do
+            [ ! -f "$jsonl" ] && continue
+            local sid
+            sid=$(basename "$jsonl" .jsonl)
+            echo "$sid|$project"
+        done
+    done
+}
+
+eagle_backfill_projects() {
+    local updated=0
+    local map
+    map=$(eagle_build_session_project_map)
+    [ -z "$map" ] && echo "0" && return 0
+
+    while IFS='|' read -r sid project; do
+        [ -z "$sid" ] || [ -z "$project" ] && continue
+        local sid_sql proj_sql
+        sid_sql=$(eagle_sql_escape "$sid")
+        proj_sql=$(eagle_sql_escape "$project")
+
+        # All six tables updated atomically per session to prevent
+        # partial backfill if the process is interrupted.
+        # Note: total_changes() includes FTS trigger changes, so the
+        # reported count may be higher than actual rows updated.
+        local ch
+        ch=$(eagle_db_pipe <<SQL
+BEGIN;
+UPDATE sessions SET project = '$proj_sql' WHERE id = '$sid_sql' AND (project = '' OR project != '$proj_sql');
+UPDATE claude_tasks SET project = '$proj_sql' WHERE source_session_id = '$sid_sql' AND (project = '' OR project != '$proj_sql');
+UPDATE claude_memories SET project = '$proj_sql' WHERE origin_session_id = '$sid_sql' AND (project = '' OR project != '$proj_sql');
+UPDATE claude_plans SET project = '$proj_sql' WHERE origin_session_id = '$sid_sql' AND (project = '' OR project != '$proj_sql');
+UPDATE summaries SET project = '$proj_sql' WHERE session_id = '$sid_sql' AND (project = '' OR project != '$proj_sql');
+UPDATE observations SET project = '$proj_sql' WHERE session_id = '$sid_sql' AND (project = '' OR project != '$proj_sql');
+SELECT total_changes();
+COMMIT;
+SQL
+)
+        [ "${ch:-0}" -gt 0 ] && updated=$((updated + ch))
+    done <<< "$map"
+
+    echo "$updated"
+}
+
+eagle_prune_orphan_chunks() {
+    local project; project=$(eagle_sql_escape "$1")
+    local target_dir="$2"
+
+    local paths
+    paths=$(eagle_db "SELECT DISTINCT file_path FROM code_chunks WHERE project = '$project';")
+
+    local removed=0
+    local txn_sql="BEGIN;"
+    while IFS= read -r fpath; do
+        [ -z "$fpath" ] && continue
+        if [ ! -f "$target_dir/$fpath" ]; then
+            local fpath_sql; fpath_sql=$(eagle_sql_escape "$fpath")
+            txn_sql+="
+DELETE FROM code_chunks WHERE project = '$project' AND file_path = '$fpath_sql';"
+            removed=$((removed + 1))
+        fi
+    done <<< "$paths"
+    txn_sql+="
+COMMIT;"
+
+    if [ "$removed" -gt 0 ]; then
+        eagle_db_pipe <<< "$txn_sql"
+    fi
+    echo "$removed"
+}

package/lib/db-core.sh

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+# ═══════════════════════════════════════════════════════════
+# Eagle Mem — Database primitives
+# ═══════════════════════════════════════════════════════════
+[ -n "${_EAGLE_DB_CORE_LOADED:-}" ] && return 0
+_EAGLE_DB_CORE_LOADED=1
+
+EAGLE_DB_SETUP=".headers off
+.output /dev/null
+PRAGMA journal_mode=WAL;
+PRAGMA synchronous=NORMAL;
+PRAGMA busy_timeout=5000;
+PRAGMA foreign_keys=ON;
+PRAGMA trusted_schema=ON;
+.output stdout"
+
+eagle_db() {
+    local _eagle_db_err
+    _eagle_db_err=$(mktemp 2>/dev/null || echo "/tmp/_eagle_db_err.$$")
+    local _eagle_db_out
+    _eagle_db_out=$({ echo "$EAGLE_DB_SETUP"; echo "$*"; } | sqlite3 "$EAGLE_MEM_DB" 2>"$_eagle_db_err")
+    local _eagle_db_rc=$?
+    if [ -s "$_eagle_db_err" ]; then
+        cat "$_eagle_db_err" >> "$EAGLE_MEM_LOG" 2>/dev/null
+    fi
+    rm -f "$_eagle_db_err" 2>/dev/null
+    [ -n "$_eagle_db_out" ] && printf '%s\n' "$_eagle_db_out"
+    return $_eagle_db_rc
+}
+
+eagle_db_pipe() {
+    local _eagle_db_err
+    _eagle_db_err=$(mktemp 2>/dev/null || echo "/tmp/_eagle_db_pipe_err.$$")
+    local _eagle_db_out
+    _eagle_db_out=$({ echo "$EAGLE_DB_SETUP"; echo ".bail on"; cat; } | sqlite3 "$EAGLE_MEM_DB" 2>"$_eagle_db_err")
+    local _eagle_db_rc=$?
+    if [ -s "$_eagle_db_err" ]; then
+        cat "$_eagle_db_err" >> "$EAGLE_MEM_LOG" 2>/dev/null
+    fi
+    rm -f "$_eagle_db_err" 2>/dev/null
+    [ -n "$_eagle_db_out" ] && printf '%s\n' "$_eagle_db_out"
+    return $_eagle_db_rc
+}
+
+eagle_db_json() {
+    local _eagle_db_err
+    _eagle_db_err=$(mktemp 2>/dev/null || echo "/tmp/_eagle_db_json_err.$$")
+    local _eagle_db_out
+    _eagle_db_out=$({ echo "$EAGLE_DB_SETUP"; echo ".mode json"; echo "$*"; } | sqlite3 "$EAGLE_MEM_DB" 2>"$_eagle_db_err")
+    local _eagle_db_rc=$?
+    if [ -s "$_eagle_db_err" ]; then
+        cat "$_eagle_db_err" >> "$EAGLE_MEM_LOG" 2>/dev/null
+    fi
+    rm -f "$_eagle_db_err" 2>/dev/null
+    [ -n "$_eagle_db_out" ] && printf '%s\n' "$_eagle_db_out"
+    return $_eagle_db_rc
+}
+
+eagle_ensure_db() {
+    if [ ! -f "$EAGLE_MEM_DB" ]; then
+        local script_dir
+        script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/../db" && pwd)"
+        "$script_dir/migrate.sh"
+    fi
+}