eagle-mem 1.0.0

package/hooks/session-start.sh

@@ -0,0 +1,161 @@
+#!/usr/bin/env bash
+# ═══════════════════════════════════════════════════════════
+# Eagle Mem — SessionStart hook
+# Fires on: startup, resume, clear, compact
+# Injects project memory + pending tasks into Claude's context
+# ═══════════════════════════════════════════════════════════
+set +e
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+LIB_DIR="$SCRIPT_DIR/../lib"
+
+. "$LIB_DIR/common.sh"
+. "$LIB_DIR/db.sh"
+
+eagle_ensure_db
+
+input=$(eagle_read_stdin)
+[ -z "$input" ] && exit 0
+
+session_id=$(echo "$input" | jq -r '.session_id // empty')
+cwd=$(echo "$input" | jq -r '.cwd // empty')
+source_type=$(echo "$input" | jq -r '.source // empty')
+model=$(echo "$input" | jq -r '.model // empty')
+
+[ -z "$session_id" ] && exit 0
+
+project=$(eagle_project_from_cwd "$cwd")
+project_sql=$(eagle_sql_escape "$project")
+
+eagle_log "INFO" "SessionStart: session=$session_id project=$project source=$source_type"
+
+eagle_upsert_session "$session_id" "$project" "$cwd" "$model" "$source_type"
+
+# ─── Build context injection ────────────────────────────────
+
+context=""
+
+# Project overview (if one exists)
+overview=$(eagle_get_overview "$project")
+if [ -n "$overview" ]; then
+    context+="=== EAGLE MEM — Project Overview ===
+$overview
+
+"
+fi
+
+# Recent summaries for this project (last 5 sessions)
+recent=$(eagle_db "
+    SELECT s.request, s.completed, s.learned, s.next_steps, s.created_at
+    FROM summaries s
+    WHERE s.project = '$project_sql'
+    ORDER BY s.created_at DESC
+    LIMIT 5;
+")
+
+if [ -n "$recent" ]; then
+    context+="=== EAGLE MEM ===
+Recent sessions for project '$project':
+"
+    while IFS='|' read -r request completed learned next_steps created_at; do
+        [ -z "$request" ] && [ -z "$completed" ] && continue
+        context+="
+--- $created_at ---"
+        [ -n "$request" ] && context+="
+Request: $request"
+        [ -n "$completed" ] && context+="
+Completed: $completed"
+        [ -n "$learned" ] && context+="
+Learned: $learned"
+        [ -n "$next_steps" ] && context+="
+Next steps: $next_steps"
+    done <<< "$recent"
+    context+="
+"
+fi
+
+# Pending tasks from TaskAware loop
+pending_tasks=$(eagle_db "
+    SELECT id, title, instructions, status
+    FROM tasks
+    WHERE project = '$project_sql' AND status IN ('pending', 'active')
+    ORDER BY ordinal ASC, id ASC
+    LIMIT 10;
+")
+
+if [ -n "$pending_tasks" ]; then
+    context+="
+=== EAGLE MEM — Tasks ===
+Pending tasks for '$project':
+"
+    first_pending=""
+    while IFS='|' read -r tid title instructions status; do
+        [ -z "$tid" ] && continue
+        local_marker=""
+        if [ "$status" = "active" ]; then
+            local_marker=" [ACTIVE]"
+        elif [ -z "$first_pending" ]; then
+            local_marker=" [NEXT]"
+            first_pending="$tid"
+        fi
+        context+="  $tid. $title$local_marker"
+        [ -n "$instructions" ] && context+=" — $instructions"
+        context+="
+"
+    done <<< "$pending_tasks"
+
+    # Load context snapshot for the active/next task
+    active_task=$(eagle_db "
+        SELECT id, title, instructions, context_snapshot
+        FROM tasks
+        WHERE project = '$project_sql' AND status = 'active'
+        ORDER BY ordinal ASC, id ASC
+        LIMIT 1;
+    ")
+
+    if [ -z "$active_task" ] && [ -n "$first_pending" ]; then
+        # Auto-activate the next pending task
+        eagle_db "UPDATE tasks SET status = 'active', started_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now') WHERE id = $first_pending;"
+        active_task=$(eagle_db "
+            SELECT id, title, instructions, context_snapshot
+            FROM tasks
+            WHERE id = $first_pending;
+        ")
+    fi
+
+    if [ -n "$active_task" ]; then
+        IFS='|' read -r atid atitle ainstructions asnapshot <<< "$active_task"
+        context+="
+Current task (#$atid): $atitle
+"
+        [ -n "$ainstructions" ] && context+="Instructions: $ainstructions
+"
+        [ -n "$asnapshot" ] && context+="Context: $asnapshot
+"
+        context+="When done, tell the user to run /compact so Eagle Mem can save progress and load the next task.
+"
+    fi
+fi
+
+# Emit the eagle-summary instruction
+context+="
+=== EAGLE MEM INSTRUCTIONS ===
+Before your final response in this session, emit a summary block:
+<eagle-summary>
+request: What the user asked for
+investigated: Key files/areas explored
+learned: Non-obvious discoveries
+completed: What was accomplished
+next_steps: What should happen next
+files_read: [list of files read]
+files_modified: [list of files modified]
+</eagle-summary>
+This helps Eagle Mem track what happened for future sessions.
+"
+
+# Output context (plain text stdout = additionalContext for SessionStart)
+if [ -n "$context" ]; then
+    echo "$context"
+fi
+
+exit 0

package/hooks/stop.sh

@@ -0,0 +1,147 @@
+#!/usr/bin/env bash
+# ═══════════════════════════════════════════════════════════
+# Eagle Mem — Stop hook
+# Fires when Claude's turn ends
+# Parses <eagle-summary> from transcript, saves to DB
+# Falls back to heuristic extraction if no summary block
+# ═══════════════════════════════════════════════════════════
+set +e
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+LIB_DIR="$SCRIPT_DIR/../lib"
+
+. "$LIB_DIR/common.sh"
+. "$LIB_DIR/db.sh"
+
+eagle_ensure_db
+
+input=$(eagle_read_stdin)
+[ -z "$input" ] && exit 0
+
+session_id=$(echo "$input" | jq -r '.session_id // empty')
+cwd=$(echo "$input" | jq -r '.cwd // empty')
+transcript_path=$(echo "$input" | jq -r '.transcript_path // empty')
+
+[ -z "$session_id" ] && exit 0
+
+# Skip subagent contexts
+agent_type=$(echo "$input" | jq -r '.agent_type // empty')
+[ -n "$agent_type" ] && [ "$agent_type" != "main" ] && exit 0
+
+project=$(eagle_project_from_cwd "$cwd")
+project_sql=$(eagle_sql_escape "$project")
+
+eagle_log "INFO" "Stop: session=$session_id project=$project transcript=$transcript_path"
+
+# Ensure session exists (may not if SessionStart didn't fire)
+eagle_upsert_session "$session_id" "$project" "$cwd" "" ""
+
+# ─── Try to parse <eagle-summary> from transcript ──────────
+
+summary_block=""
+if [ -n "$transcript_path" ] && [ -f "$transcript_path" ]; then
+    # Extract all text from the last assistant message using jq on JSONL
+    # Real transcript format: top-level .type == "assistant", content in .message.content[]
+    text_content=$(jq -rs '
+        [.[] | select(.type == "assistant")] | last |
+        if . then
+            [.message.content[]? | select(.type == "text") | .text] | join("\n")
+        else "" end
+    ' "$transcript_path" 2>/dev/null)
+
+    # Strip <private>...</private> blocks before processing
+    text_content=$(echo "$text_content" | sed '/<private>/,/<\/private>/d')
+
+    # Parse <eagle-summary> block
+    if [ -n "$text_content" ] && echo "$text_content" | grep -q '<eagle-summary>' 2>/dev/null; then
+        summary_block=$(echo "$text_content" | sed -n '/<eagle-summary>/,/<\/eagle-summary>/p' | sed '1d;$d')
+    fi
+fi
+
+# ─── Extract fields from summary block ─────────────────────
+
+parse_field() {
+    local block="$1"
+    local field="$2"
+    echo "$block" | awk -v f="$field" '
+        BEGIN { IGNORECASE=1; found=0 }
+        $0 ~ "^"f":" {
+            sub("^"f":[[:space:]]*", ""); found=1; val=$0; next
+        }
+        found && /^(request|investigated|learned|completed|next_steps|files_read|files_modified|notes):/ { exit }
+        found { val = val " " $0 }
+        END { if (found) print val }
+    '
+}
+
+request=""
+investigated=""
+learned=""
+completed=""
+next_steps=""
+files_read="[]"
+files_modified="[]"
+notes=""
+
+if [ -n "$summary_block" ]; then
+    request=$(parse_field "$summary_block" "request")
+    investigated=$(parse_field "$summary_block" "investigated")
+    learned=$(parse_field "$summary_block" "learned")
+    completed=$(parse_field "$summary_block" "completed")
+    next_steps=$(parse_field "$summary_block" "next_steps")
+
+    raw_fr=$(parse_field "$summary_block" "files_read")
+    raw_fm=$(parse_field "$summary_block" "files_modified")
+
+    # Convert bracket-list to JSON array (handles special chars safely)
+    to_json_array() {
+        local raw="$1"
+        raw=$(echo "$raw" | sed 's/^\[//;s/\]$//')
+        echo "$raw" | tr ',' '\n' | sed 's/^[[:space:]]*//;s/[[:space:]]*$//' | grep -v '^$' | jq -Rsc 'split("\n") | map(select(. != ""))'
+    }
+
+    [ -n "$raw_fr" ] && files_read=$(to_json_array "$raw_fr")
+    [ -n "$raw_fm" ] && files_modified=$(to_json_array "$raw_fm")
+
+    eagle_log "INFO" "Stop: parsed eagle-summary block"
+fi
+
+# ─── Heuristic fallback: extract from tool calls ───────────
+
+if [ -z "$request" ] && [ -n "$transcript_path" ] && [ -f "$transcript_path" ]; then
+    eagle_log "INFO" "Stop: no eagle-summary found, using heuristic fallback"
+
+    # Extract first user prompt as "request"
+    request=$(jq -r 'select(.type == "user") | .message.content | if type == "string" then . elif type == "array" then [.[] | select(.type == "text") | .text] | join(" ") else "" end' "$transcript_path" 2>/dev/null | head -1 | cut -c1-500)
+
+    # Extract files from Read/Write/Edit tool calls
+    heuristic_reads=$(jq -r 'select(.type == "assistant") | .message.content[]? | select(.type == "tool_use") | select(.name == "Read") | .input.file_path // empty' "$transcript_path" 2>/dev/null | sort -u | head -20)
+    heuristic_writes=$(jq -r 'select(.type == "assistant") | .message.content[]? | select(.type == "tool_use") | select(.name == "Write" or .name == "Edit") | .input.file_path // empty' "$transcript_path" 2>/dev/null | sort -u | head -20)
+
+    if [ -n "$heuristic_reads" ]; then
+        files_read=$(echo "$heuristic_reads" | jq -Rsc 'split("\n") | map(select(. != ""))')
+    fi
+    if [ -n "$heuristic_writes" ]; then
+        files_modified=$(echo "$heuristic_writes" | jq -Rsc 'split("\n") | map(select(. != ""))')
+    fi
+
+    completed="(auto-captured from tool usage)"
+fi
+
+# ─── Write to database ─────────────────────────────────────
+
+if [ -n "$request" ] || [ -n "$completed" ] || [ -n "$learned" ]; then
+    eagle_insert_summary "$session_id" "$project" "$request" "$investigated" "$learned" "$completed" "$next_steps" "$files_read" "$files_modified" "$notes"
+    eagle_log "INFO" "Stop: summary saved for session=$session_id"
+fi
+
+# Mark active task as done if eagle-summary mentions completion
+if [ -n "$completed" ]; then
+    active_task_id=$(eagle_db "SELECT id FROM tasks WHERE project = '$project_sql' AND status = 'active' LIMIT 1;")
+    if [ -n "$active_task_id" ]; then
+        eagle_db "UPDATE tasks SET status = 'done', completed_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now') WHERE id = $active_task_id;"
+        eagle_log "INFO" "Stop: marked task #$active_task_id as done"
+    fi
+fi
+
+exit 0

package/hooks/user-prompt-submit.sh

@@ -0,0 +1,102 @@
+#!/usr/bin/env bash
+# ═══════════════════════════════════════════════════════════
+# Eagle Mem — UserPromptSubmit hook
+# Fires when the user submits a prompt
+# Searches memory for relevant context and injects it
+# ═══════════════════════════════════════════════════════════
+set +e
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+LIB_DIR="$SCRIPT_DIR/../lib"
+
+. "$LIB_DIR/common.sh"
+. "$LIB_DIR/db.sh"
+
+[ ! -f "$EAGLE_MEM_DB" ] && exit 0
+
+input=$(eagle_read_stdin)
+[ -z "$input" ] && exit 0
+
+session_id=$(echo "$input" | jq -r '.session_id // empty')
+cwd=$(echo "$input" | jq -r '.cwd // empty')
+user_prompt=$(echo "$input" | jq -r '.prompt // empty')
+
+[ -z "$user_prompt" ] && exit 0
+
+project=$(eagle_project_from_cwd "$cwd")
+project_sql=$(eagle_sql_escape "$project")
+
+# Skip short prompts — not enough signal for meaningful search
+word_count=$(echo "$user_prompt" | wc -w | tr -d ' ')
+[ "$word_count" -lt 3 ] && exit 0
+
+# Build FTS5 query from significant words (drop stop words, take first 6)
+fts_query=$(echo "$user_prompt" | tr -cs '[:alnum:]' ' ' | tr '[:upper:]' '[:lower:]' | \
+    awk '{
+        split("the a an is are was were be been being have has had do does did will would shall should may might can could of in to for on with at by from", sw, " ")
+        for (i in sw) stop[sw[i]]=1
+        n=0
+        for (i=1; i<=NF && n<6; i++) {
+            if (length($i) > 2 && !($i in stop)) {
+                printf "%s%s", (n>0?" OR ":""), $i; n++
+            }
+        }
+    }')
+
+[ -z "$fts_query" ] && exit 0
+
+fts_query_escaped=$(eagle_sql_escape "$fts_query")
+
+# Search for relevant past summaries (cross-session)
+results=$(eagle_db "SELECT s.request, s.learned, s.completed, s.created_at
+                    FROM summaries s
+                    JOIN summaries_fts f ON f.rowid = s.id
+                    WHERE summaries_fts MATCH '$fts_query_escaped'
+                    AND s.project = '$project_sql'
+                    ORDER BY rank
+                    LIMIT 3;")
+
+context=""
+
+if [ -n "$results" ]; then
+    context+="=== EAGLE MEM — Relevant Memory ===
+"
+    while IFS='|' read -r req learned completed created_at; do
+        [ -z "$req" ] && [ -z "$completed" ] && continue
+        context+="[$created_at] "
+        [ -n "$req" ] && context+="$req"
+        [ -n "$completed" ] && context+=" → $completed"
+        [ -n "$learned" ] && context+=" (Learned: $learned)"
+        context+="
+"
+    done <<< "$results"
+fi
+
+# Search indexed code chunks (if any exist for this project)
+has_chunks=$(eagle_db "SELECT COUNT(*) FROM code_chunks WHERE project = '$project_sql' LIMIT 1;")
+if [ "${has_chunks:-0}" -gt 0 ]; then
+    code_results=$(eagle_db "SELECT c.file_path, c.start_line, c.end_line, c.language
+                             FROM code_chunks c
+                             JOIN code_chunks_fts f ON f.rowid = c.id
+                             WHERE code_chunks_fts MATCH '$fts_query_escaped'
+                             AND c.project = '$project_sql'
+                             ORDER BY rank
+                             LIMIT 5;")
+
+    if [ -n "$code_results" ]; then
+        context+="=== EAGLE MEM — Relevant Code ===
+"
+        while IFS='|' read -r fpath sline eline lang; do
+            [ -z "$fpath" ] && continue
+            context+="$fpath:${sline}-${eline}"
+            [ -n "$lang" ] && context+=" ($lang)"
+            context+="
+"
+        done <<< "$code_results"
+    fi
+fi
+
+[ -z "$context" ] && exit 0
+
+echo "$context"
+exit 0

package/lib/common.sh

@@ -0,0 +1,63 @@
+#!/usr/bin/env bash
+# ═══════════════════════════════════════════════════════════
+# Eagle Mem — Shared constants and helpers
+# Source this file: . "$(dirname "$0")/../lib/common.sh"
+# ═══════════════════════════════════════════════════════════
+
+EAGLE_MEM_DIR="${EAGLE_MEM_DIR:-$HOME/.eagle-mem}"
+EAGLE_MEM_DB="$EAGLE_MEM_DIR/memory.db"
+EAGLE_MEM_LOG="$EAGLE_MEM_DIR/eagle-mem.log"
+
+eagle_log() {
+    local level="$1"
+    shift
+    echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] [$level] $*" >> "$EAGLE_MEM_LOG" 2>/dev/null || true
+}
+
+eagle_project_from_cwd() {
+    local cwd="${1:-$(pwd)}"
+    basename "$cwd"
+}
+
+eagle_sql_escape() {
+    printf '%s' "$1" | sed "s/'/''/g"
+}
+
+eagle_read_stdin() {
+    local input=""
+    if [ ! -t 0 ]; then
+        input=$(cat)
+    fi
+    echo "$input"
+}
+
+# Collect project files into a destination file.
+# Uses git ls-files when available, falls back to find with common exclusions.
+# Usage: eagle_collect_files <target_dir> <output_file>
+eagle_collect_files() {
+    local target_dir="$1"
+    local output_file="$2"
+
+    if git -C "$target_dir" rev-parse --is-inside-work-tree &>/dev/null; then
+        git -C "$target_dir" ls-files --cached --others --exclude-standard > "$output_file"
+    else
+        (cd "$target_dir" && find . -type f \
+            -not -path '*/node_modules/*' \
+            -not -path '*/.git/*' \
+            -not -path '*/dist/*' \
+            -not -path '*/build/*' \
+            -not -path '*/.next/*' \
+            -not -path '*/target/*' \
+            -not -path '*/vendor/*' \
+            -not -path '*/__pycache__/*' \
+            -not -path '*/.venv/*' \
+            -not -path '*/venv/*' \
+            -not -path '*/.egg-info/*' \
+            -not -name '*.pyc' \
+            -not -name '*.lock' \
+            -not -name 'package-lock.json' \
+            -not -name 'yarn.lock' \
+            -not -name 'pnpm-lock.yaml' \
+            | sed 's|^\./||') > "$output_file"
+    fi
+}

package/lib/db.sh

@@ -0,0 +1,186 @@
+#!/usr/bin/env bash
+# ═══════════════════════════════════════════════════════════
+# Eagle Mem — Database helpers
+# Source after common.sh: . "$(dirname "$0")/../lib/db.sh"
+# ═══════════════════════════════════════════════════════════
+
+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() {
+    { echo "$EAGLE_DB_SETUP"; echo "$*"; } | sqlite3 "$EAGLE_MEM_DB" 2>/dev/null
+}
+
+eagle_db_pipe() {
+    { echo "$EAGLE_DB_SETUP"; cat; } | sqlite3 "$EAGLE_MEM_DB" 2>/dev/null
+}
+
+eagle_db_json() {
+    { echo "$EAGLE_DB_SETUP"; echo ".mode json"; echo "$*"; } | sqlite3 "$EAGLE_MEM_DB" 2>/dev/null
+}
+
+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
+}
+
+eagle_upsert_session() {
+    local session_id="$1"
+    local project; project=$(eagle_sql_escape "$2")
+    local cwd; cwd=$(eagle_sql_escape "${3:-}")
+    local model; model=$(eagle_sql_escape "${4:-}")
+    local source; source=$(eagle_sql_escape "${5:-}")
+
+    eagle_db "INSERT INTO sessions (id, project, cwd, model, source)
+              VALUES ('$session_id', '$project', '$cwd', '$model', '$source')
+              ON CONFLICT(id) DO UPDATE SET
+                  cwd = COALESCE(excluded.cwd, sessions.cwd),
+                  model = COALESCE(excluded.model, sessions.model),
+                  source = COALESCE(excluded.source, sessions.source);"
+}
+
+eagle_end_session() {
+    local session_id="$1"
+    eagle_db "UPDATE sessions SET status = 'completed', ended_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now') WHERE id = '$session_id';"
+}
+
+eagle_insert_observation() {
+    local session_id="$1"
+    local project; project=$(eagle_sql_escape "$2")
+    local tool_name; tool_name=$(eagle_sql_escape "$3")
+    local tool_input_summary; tool_input_summary=$(eagle_sql_escape "$4")
+    local files_read="$5"
+    local files_modified="$6"
+
+    eagle_db "INSERT INTO observations (session_id, project, tool_name, tool_input_summary, files_read, files_modified)
+              VALUES ('$session_id', '$project', '$tool_name', '$tool_input_summary', '$files_read', '$files_modified');"
+}
+
+eagle_insert_summary() {
+    local session_id; session_id=$(eagle_sql_escape "$1")
+    local project; project=$(eagle_sql_escape "$2")
+    local request; request=$(eagle_sql_escape "$3")
+    local investigated; investigated=$(eagle_sql_escape "$4")
+    local learned; learned=$(eagle_sql_escape "$5")
+    local completed; completed=$(eagle_sql_escape "$6")
+    local next_steps; next_steps=$(eagle_sql_escape "$7")
+    local files_read; files_read=$(eagle_sql_escape "$8")
+    local files_modified; files_modified=$(eagle_sql_escape "$9")
+    local notes; notes=$(eagle_sql_escape "${10:-}")
+
+    eagle_db_pipe <<SQL
+INSERT INTO summaries (session_id, project, request, investigated, learned, completed, next_steps, files_read, files_modified, notes)
+VALUES (
+    '$session_id',
+    '$project',
+    '$request',
+    '$investigated',
+    '$learned',
+    '$completed',
+    '$next_steps',
+    '$files_read',
+    '$files_modified',
+    '$notes'
+);
+SQL
+}
+
+eagle_get_recent_summaries() {
+    local project; project=$(eagle_sql_escape "$1")
+    local limit="${2:-5}"
+
+    eagle_db "SELECT s.request, s.completed, s.learned, s.next_steps, s.created_at
+              FROM summaries s
+              WHERE s.project = '$project'
+              ORDER BY s.created_at DESC
+              LIMIT $limit;"
+}
+
+eagle_search_summaries() {
+    local query; query=$(eagle_sql_escape "$1")
+    local project="${2:-}"
+    local limit="${3:-10}"
+
+    local where_clause=""
+    if [ -n "$project" ]; then
+        project=$(eagle_sql_escape "$project")
+        where_clause="AND s.project = '$project'"
+    fi
+
+    eagle_db "SELECT s.request, s.completed, s.learned, s.next_steps, s.created_at, s.project
+              FROM summaries s
+              JOIN summaries_fts f ON f.rowid = s.id
+              WHERE summaries_fts MATCH '$query'
+              $where_clause
+              ORDER BY rank
+              LIMIT $limit;"
+}
+
+eagle_get_pending_tasks() {
+    local project; project=$(eagle_sql_escape "$1")
+
+    eagle_db "SELECT id, title, instructions, status, ordinal
+              FROM tasks
+              WHERE project = '$project' AND status IN ('pending', 'active')
+              ORDER BY ordinal ASC, id ASC;"
+}
+
+eagle_get_next_task() {
+    local project; project=$(eagle_sql_escape "$1")
+
+    eagle_db "SELECT id, title, instructions, context_snapshot
+              FROM tasks
+              WHERE project = '$project' AND status = 'pending'
+              ORDER BY ordinal ASC, id ASC
+              LIMIT 1;"
+}
+
+eagle_get_active_files() {
+    local project; project=$(eagle_sql_escape "$1")
+    local limit="${2:-20}"
+
+    eagle_db "SELECT json_each.value
+              FROM observations, json_each(observations.files_modified)
+              WHERE observations.project = '$project'
+              GROUP BY json_each.value
+              ORDER BY MAX(observations.created_at) DESC
+              LIMIT $limit;"
+}
+
+eagle_observation_exists() {
+    local session_id="$1"
+    local tool_name; tool_name=$(eagle_sql_escape "$2")
+    local tool_summary; tool_summary=$(eagle_sql_escape "$3")
+
+    eagle_db "SELECT COUNT(*) FROM observations
+              WHERE session_id = '$session_id'
+              AND tool_name = '$tool_name'
+              AND tool_input_summary = '$tool_summary'
+              AND created_at > strftime('%Y-%m-%dT%H:%M:%fZ', 'now', '-5 seconds');"
+}
+
+eagle_upsert_overview() {
+    local project; project=$(eagle_sql_escape "$1")
+    local content; content=$(eagle_sql_escape "$2")
+
+    eagle_db "INSERT INTO overviews (project, content, updated_at)
+              VALUES ('$project', '$content', strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
+              ON CONFLICT(project) DO UPDATE SET
+                  content = excluded.content,
+                  updated_at = excluded.updated_at;"
+}
+
+eagle_get_overview() {
+    local project; project=$(eagle_sql_escape "$1")
+
+    eagle_db "SELECT content FROM overviews WHERE project = '$project';"
+}