eagle-mem 4.9.6 → 4.9.7

package/bin/eagle-mem

@@ -21,6 +21,7 @@ case "$command" in
     uninstall)  bash "$SCRIPTS_DIR/uninstall.sh" "$@" ;;
     search)     bash "$SCRIPTS_DIR/search.sh" "$@" ;;
     health)     bash "$SCRIPTS_DIR/health.sh" "$@" ;;
+    doctor)     bash "$SCRIPTS_DIR/doctor.sh" "$PACKAGE_DIR" "$@" ;;
     config)     bash "$SCRIPTS_DIR/config.sh" "$@" ;;
     updates)    bash "$SCRIPTS_DIR/updates.sh" "$@" ;;
     statusline) "$SCRIPTS_DIR/statusline-em.sh" "$@" ;;

package/db/migrate.sh

@@ -44,7 +44,18 @@ run_migration() {
 
         # Set connection PRAGMAs, then run migration body + tracking insert atomically
         # .bail on ensures sqlite3 stops on the first error instead of continuing
-        { echo ".bail on"; echo "PRAGMA trusted_schema=ON;"; echo "PRAGMA foreign_keys=ON;"; echo "PRAGMA busy_timeout=5000;"; echo "BEGIN;"; echo "$body"; echo "INSERT INTO _migrations (name) VALUES ('$name');"; echo "COMMIT;"; } | "$SQLITE_BIN" "$DB"
+        {
+            echo ".bail on"
+            echo ".output /dev/null"
+            echo "PRAGMA trusted_schema=ON;"
+            echo "PRAGMA foreign_keys=ON;"
+            echo "PRAGMA busy_timeout=5000;"
+            echo ".output stdout"
+            echo "BEGIN;"
+            echo "$body"
+            echo "INSERT INTO _migrations (name) VALUES ('$name');"
+            echo "COMMIT;"
+        } | "$SQLITE_BIN" "$DB"
         echo "  applied: $name"
     fi
 }
@@ -57,7 +68,7 @@ run_migration() {
 );"
 
 # Set PRAGMAs (these must be set on every connection)
-"$SQLITE_BIN" "$DB" "PRAGMA journal_mode = WAL; PRAGMA synchronous = NORMAL; PRAGMA busy_timeout = 5000; PRAGMA foreign_keys = ON;"
+"$SQLITE_BIN" "$DB" "PRAGMA journal_mode = WAL; PRAGMA synchronous = NORMAL; PRAGMA busy_timeout = 5000; PRAGMA foreign_keys = ON;" >/dev/null
 
 # ─── Migration 001: Initial schema (special name) ──────────
 run_migration "001_initial_schema" "$SCRIPT_DIR/schema.sql"

package/docs/visible-surface-ux-contract.md

@@ -0,0 +1,53 @@
+# Eagle Mem Visible Surface UX Contract
+
+Eagle Mem has two audiences for visible output:
+
+- The user, who should see a calm product surface.
+- The active agent, which needs compact operational context without raw internals.
+
+Default output must be useful without exposing implementation details. Raw database
+IDs, file paths, session IDs, backing JSON, hook payloads, and source file content
+belong behind `--raw`, `--debug`, or `--json`.
+
+## Output Modes
+
+| Mode | Purpose | Allowed Content |
+| --- | --- | --- |
+| Default | Human product UX | Brand, status, concise summaries, freshness, next action |
+| `--json` | Machine-readable automation | Structured complete fields |
+| `--raw` | Developer inspection | IDs, source paths, backing files, raw task JSON |
+| `--debug` | Troubleshooting | Same as `--raw`, plus diagnostic hints where useful |
+
+## Visible Surfaces
+
+| Surface | User Sees It? | Default Standard |
+| --- | --- | --- |
+| `SessionStart` | Yes, in agent transcript | Branded compact briefing: project, memory, relevant now, work state, guardrails |
+| `UserPromptSubmit` | Yes, in agent transcript | `Eagle Mem recalls` with 1-2 useful bullets and relevant code |
+| `PreToolUse` | Sometimes, when blocking | Calm explanation, recommended fix, one-off bypass if appropriate |
+| `PostToolUse` | Sometimes, after reads/edits | Structured memory/decision/feature notes, no separator blocks for Codex |
+| `statusline` | Yes | Short branded status: version, sessions, memories, turn |
+| `search` | Yes | Freshness-aware results, no raw IDs in headings |
+| `memories` | Yes | Project-scoped list by default, no source paths unless raw/debug |
+| `tasks` | Yes | Task subject/status/source, no session/task IDs unless raw/debug |
+| `feature` | Yes | Pending work grouped by action, raw diff fingerprints only when needed |
+| `health` | Yes | Overall verdict first, then sectioned checks and next action |
+| `install/update/uninstall` | Yes | Explain changed footprint, reversibility, backups, and success/failure plainly |
+| `doctor` | Yes | Trust report: installed runtime, hooks, SQLite/FTS5, install manifest, drift, uninstall coverage |
+
+## Product Voice
+
+- Use `Eagle Mem` or `Eagle`; avoid cryptic `EM` in user-facing output.
+- Prefer headings like `Relevant now`, `Work state`, `Guardrail`, and `Next`.
+- Prefer freshness labels like `Fresh`, `Recent`, `Older`, or `may be stale`.
+- Avoid dumping raw hook payloads, XML templates, SQL results, or JSON unless the user requested raw/debug output.
+- Keep Codex transcript injections more compact than Claude Code injections.
+
+## Install/Update/Uninstall Standard
+
+- Before mutating user config or runtime files, show a short "What will change" plan.
+- Treat `--dry-run` as a first-class product path for destructive or cleanup commands.
+- Back up user-owned config files before editing `~/.claude` or `~/.codex` state.
+- Preserve `~/.eagle-mem/memory.db` by default; require explicit confirmation before deleting stored memory.
+- After install/update, write a manifest with runtime file metadata so `doctor` can verify drift without noisy shell dumps.
+- Prefer one clear verdict first (`Healthy`, `Needs attention`, or `Broken`), then details.

package/hooks/post-tool-use.sh

@@ -200,8 +200,8 @@ esac
 
 eagle_posttool_mirror_writes "$tool_name" "$fp" "$session_id" "$project" "$agent"
 eagle_posttool_mirror_tasks "$tool_name" "$session_id" "$project" "$input" "$agent"
-eagle_posttool_stale_hint "$tool_name" "$fp" "$project"
-eagle_posttool_decision_surface "$tool_name" "$fp" "$project"
+eagle_posttool_stale_hint "$tool_name" "$fp" "$project" "$agent"
+eagle_posttool_decision_surface "$tool_name" "$fp" "$project" "$agent"
 
 # ─── Record observation ──────────────────────────────────
 

package/hooks/pre-tool-use.sh

@@ -96,12 +96,12 @@ Pending checks:"
     rtk_cmd=$(eagle_rtk_rewrite_command "$cmd")
     if [ -n "$rtk_cmd" ]; then
         if [ "$agent" = "codex" ] && [ "$raw_bash_mode" != "allow" ] && ! eagle_raw_bash_unlock_active; then
-            reason="Eagle Mem token guard blocked raw shell output.
+            reason="Eagle Mem blocked raw shell output to keep Codex context clean.
 
-Use RTK so large output is compact before it enters context:
+Recommended compact command:
   $rtk_cmd
 
-Temporary escape hatch for one-off raw output:
+One-off developer bypass:
   touch $EAGLE_RAW_BASH_UNLOCK"
             jq -nc --arg reason "$reason" '{
                 "decision":"block",
@@ -120,15 +120,15 @@ Temporary escape hatch for one-off raw output:
             context+="Eagle Mem token guard: rewrote raw shell command through RTK to reduce context load: ${rtk_cmd}. "
         fi
     elif [ "$rtk_mode" = "enforce" ] && ! command -v rtk >/dev/null 2>&1 && eagle_raw_output_command_needs_guard "$cmd" && ! eagle_raw_bash_unlock_active; then
-        reason="Eagle Mem token guard is set to enforce, but RTK is not installed or not on PATH.
+        reason="Eagle Mem blocked this command because RTK enforcement is on, but RTK is not installed or not on PATH.
 
 This command can dump raw output into agent context:
   $cmd
 
-Install RTK or disable enforcement:
+Install RTK or switch enforcement to auto:
   eagle-mem config set token_guard.rtk auto
 
-Temporary escape hatch:
+One-off developer bypass:
   touch $EAGLE_RAW_BASH_UNLOCK"
         jq -nc --arg reason "$reason" '{
             "decision":"block",

package/hooks/session-start.sh

@@ -139,6 +139,186 @@ eagle_banner+="
 context="$eagle_banner
 "
 
+if [ "$codex_compact" -eq 1 ]; then
+    codex_context="Eagle Mem Recall Ready
+Project: $project | Agent: $agent_label
+Memory: $stat_sessions sessions"
+    [ "$stat_with_summaries" -gt 0 ] && codex_context+=", $stat_with_summaries summarized"
+    [ "$stat_memories" -gt 0 ] && codex_context+=", $stat_memories memories"
+    [ "$stat_chunks" -gt 0 ] && codex_context+=", $stat_chunks code chunks"
+    codex_context+="
+"
+
+    if [ -n "$update_notice" ]; then
+        codex_context+="
+Update: $(eagle_trim_text "$update_notice" 180)
+"
+    fi
+
+    if [ "${stat_with_summaries:-0}" -eq 0 ] 2>/dev/null; then
+        codex_context+="
+Capture: Codex hooks are active. Eagle Mem will summarize decisions and gotchas from the transcript automatically.
+"
+    fi
+
+    overview=$(eagle_get_overview "$project")
+    if [ -n "$overview" ]; then
+        codex_context+="
+Project brief: $(eagle_trim_text "$overview" 260)
+"
+    else
+        codex_context+="
+Project brief: no overview yet; background scan is running.
+"
+    fi
+
+    recent=$(eagle_get_recent_summaries "$project" 1)
+    if [ -n "$recent" ]; then
+        codex_context+="
+Relevant now:
+"
+        while IFS='|' read -r request completed learned _next_steps created_at _decisions gotchas _key_files summary_agent; do
+            [ -z "$request" ] && [ -z "$completed" ] && continue
+            summary_agent_label=$(eagle_agent_label "$summary_agent")
+            recent_line="$completed"
+            [ -z "$recent_line" ] && recent_line="$request"
+            codex_context+="- Recent [$summary_agent_label]: $(eagle_trim_text "$recent_line" 180)
+"
+            [ -n "$learned" ] && codex_context+="  Learned: $(eagle_trim_text "$learned" 140)
+"
+            [ -n "$gotchas" ] && codex_context+="  Watch: $(eagle_trim_text "$gotchas" 120)
+"
+        done <<< "$recent"
+    fi
+
+    memories=$(eagle_db "SELECT memory_name, memory_type, description, origin_agent,
+        CAST(julianday('now') - julianday(updated_at) AS INTEGER) as days_ago
+        FROM agent_memories
+        WHERE project = '$p_esc'
+        ORDER BY
+            CASE
+                WHEN lower(memory_name) LIKE 'current status%' THEN 4
+                WHEN memory_type IN ('feedback', 'user', 'reference') THEN 0
+                WHEN memory_type = 'project' THEN 1
+                ELSE 2
+            END,
+            updated_at DESC
+        LIMIT 2;")
+    if [ -n "$memories" ]; then
+        [ -z "$recent" ] && codex_context+="
+Relevant now:
+"
+        while IFS='|' read -r mname mtype mdesc morigin days_ago; do
+            [ -z "$mname" ] && continue
+            origin_label=$(eagle_agent_label "$morigin")
+            age_label="fresh"
+            if [ -n "$days_ago" ] && [ "$days_ago" -gt 14 ] 2>/dev/null; then
+                age_label="older"
+            elif [ -n "$days_ago" ] && [ "$days_ago" -gt 0 ] 2>/dev/null; then
+                age_label="${days_ago}d old"
+            fi
+            codex_context+="- Memory [$mtype][$origin_label][$age_label]: $mname"
+            [ -n "$mdesc" ] && codex_context+=" — $(eagle_trim_text "$mdesc" 120)"
+            codex_context+="
+"
+        done <<< "$memories"
+    fi
+
+    synced_tasks=$(eagle_db "SELECT subject, status, blocked_by, origin_agent FROM agent_tasks
+        WHERE project = '$p_esc'
+        AND status IN ('in_progress', 'pending')
+        AND source_session_id != 'orchestration'
+        AND updated_at > strftime('%Y-%m-%dT%H:%M:%fZ', 'now', '-7 days')
+        ORDER BY CASE status WHEN 'in_progress' THEN 0 ELSE 1 END, updated_at DESC
+        LIMIT 3;")
+    orchestration_lanes=$(eagle_db "SELECT o.name, l.lane_key, l.title, l.agent, l.status
+        FROM orchestration_lanes l
+        JOIN orchestrations o ON o.id = l.orchestration_id
+        WHERE l.project = '$p_esc'
+          AND o.status = 'active'
+          AND l.status IN ('in_progress', 'pending', 'blocked')
+        ORDER BY CASE l.status WHEN 'in_progress' THEN 0 WHEN 'blocked' THEN 1 ELSE 2 END, l.updated_at DESC
+        LIMIT 3;" 2>/dev/null)
+    if [ -n "$synced_tasks" ] || [ -n "$orchestration_lanes" ]; then
+        codex_context+="
+Work state:
+"
+        while IFS='|' read -r tsubject tstatus tblocked torigin; do
+            [ -z "$tsubject" ] && continue
+            origin_label=$(eagle_agent_label "$torigin")
+            block_marker=""
+            [ "$tblocked" != "[]" ] && [ -n "$tblocked" ] && block_marker=" blocked"
+            codex_context+="- Task [$tstatus][$origin_label$block_marker]: $(eagle_trim_text "$tsubject" 130)
+"
+        done <<< "$synced_tasks"
+        while IFS='|' read -r oname lkey ltitle lagent lstatus; do
+            [ -z "$lkey" ] && continue
+            origin_label=$(eagle_agent_label "$lagent")
+            codex_context+="- Lane [$lstatus][$origin_label]: $lkey"
+            [ -n "$ltitle" ] && codex_context+=" — $(eagle_trim_text "$ltitle" 100)"
+            [ -n "$oname" ] && codex_context+=" ($oname)"
+            codex_context+="
+"
+        done <<< "$orchestration_lanes"
+        [ -n "$orchestration_lanes" ] && codex_context+="  Agent rule: you update lane status with eagle-mem orchestrate; do not ask the user to run it.
+"
+    fi
+
+    pending_features=$(eagle_list_pending_feature_verifications "$project" 3 2>/dev/null)
+    if [ -n "$pending_features" ]; then
+        codex_context+="
+Guardrail:
+"
+        while IFS='|' read -r pf_id pf_name pf_file pf_reason _pf_trigger _pf_created pf_smoke _pfingerprint; do
+            [ -z "$pf_id" ] && continue
+            codex_context+="- Pending verification #$pf_id: $pf_name"
+            [ -n "$pf_file" ] && codex_context+=" ($pf_file)"
+            [ -n "$pf_reason" ] && codex_context+=" — $(eagle_trim_text "$pf_reason" 90)"
+            [ -n "$pf_smoke" ] && codex_context+=" | smoke: $(eagle_trim_text "$pf_smoke" 100)"
+            codex_context+="
+"
+        done <<< "$pending_features"
+        codex_context+="  Release commands are blocked until these are verified or waived.
+"
+    fi
+
+    hot_files=$(eagle_get_hot_files "$project")
+    if [ -n "$hot_files" ]; then
+        core_files=""
+        IFS=',' read -ra hf_arr <<< "$hot_files"
+        hf_count=0
+        for hf in "${hf_arr[@]}"; do
+            [ "$hf_count" -ge 5 ] && break
+            [ -z "$hf" ] && continue
+            [ -n "$core_files" ] && core_files+=", "
+            core_files+="$(basename "$hf")"
+            hf_count=$((hf_count + 1))
+        done
+        [ -n "$core_files" ] && codex_context+="
+Core files: $core_files
+"
+    fi
+
+    if [ "$source_type" = "compact" ] || [ "$source_type" = "clear" ]; then
+        working_set=$(eagle_get_working_set "$session_id")
+        if [ -n "$working_set" ]; then
+            codex_context+="
+Working set:
+"
+            while IFS='|' read -r ws_path ws_edits; do
+                [ -z "$ws_path" ] && continue
+                codex_context+="- $(basename "$ws_path") (${ws_edits} edits)
+"
+            done <<< "$working_set"
+        fi
+    fi
+
+    codex_context+="
+Use recalled context only when relevant. Keep user-facing replies clean; do not print raw Eagle Mem internals."
+    eagle_emit_context_for_agent "$agent" "SessionStart" "$codex_context"
+    exit 0
+fi
+
 if [ -n "$update_notice" ]; then
     context+="
 === Eagle Mem: Update Available ===
@@ -236,7 +416,14 @@ memories=$(eagle_db "SELECT memory_name, memory_type, description, file_path, up
     CAST(julianday('now') - julianday(updated_at) AS INTEGER) as days_ago
     FROM agent_memories
     WHERE project = '$p_esc'
-    ORDER BY updated_at DESC
+    ORDER BY
+        CASE
+            WHEN lower(memory_name) LIKE 'current status%' THEN 4
+            WHEN memory_type IN ('feedback', 'user', 'reference') THEN 0
+            WHEN memory_type = 'project' THEN 1
+            ELSE 2
+        END,
+        updated_at DESC
     LIMIT $memory_limit;")
 if [ -n "$memories" ]; then
     context+="

package/hooks/user-prompt-submit.sh

@@ -46,8 +46,10 @@ if [ -n "$session_id" ] && eagle_validate_session_id "$session_id"; then
     if [ "$turn_count" -ge 30 ]; then
         if [ "$codex_compact" -eq 1 ]; then
             context+="
-=== Eagle Mem: Context Pressure Critical ($turn_count turns since compact) ===
-Keep the next Codex reply user-clean. Do not print Eagle Mem summary capture blocks or other internals. Include a short normal handoff note if useful, then ask the user to run /compact.
+Eagle Mem context pressure: critical ($turn_count turns since compact)
+- Keep the next Codex reply user-clean.
+- Do not print Eagle Mem summary blocks or internals.
+- Add a short normal handoff note if useful, then ask the user to run /compact.
 "
         else
             context+="
@@ -60,8 +62,10 @@ Tell the user to run /compact NOW to avoid losing context.
     elif [ "$turn_count" -ge 20 ]; then
         if [ "$codex_compact" -eq 1 ]; then
             context+="
-=== Eagle Mem: Context Pressure High ($turn_count turns since compact) ===
-Keep the next Codex reply clean. Do not print Eagle Mem summary capture blocks or other internals. Summarize any durable decisions in normal prose only.
+Eagle Mem context pressure: high ($turn_count turns since compact)
+- Keep the next Codex reply clean.
+- Do not print Eagle Mem summary blocks or internals.
+- Summarize durable decisions in normal prose only.
 "
         else
             context+="
@@ -106,8 +110,10 @@ fi
 lower_prompt=$(printf '%s' "$user_prompt" | tr '[:upper:]' '[:lower:]')
 if printf '%s\n' "$lower_prompt" | grep -Eq '(orchestrat|worker|parallel|multi-agent|multi agent|split|lane|scope out|plan and get started|broad|full codebase|release|publish|ship)'; then
     if [ "$codex_compact" -eq 1 ]; then
-        context+="=== Eagle Mem: Orchestration Protocol ===
-For broad work, you run eagle-mem orchestrate yourself. Use durable lanes, opposite-agent workers, and concise user-visible status.
+        context+="
+Eagle Mem orchestration:
+- For broad work, you run eagle-mem orchestrate yourself.
+- Use durable lanes, opposite-agent workers, and concise user-visible status.
 "
     else
         context+="=== Eagle Mem: Orchestration Protocol ===
@@ -134,8 +140,14 @@ fi
 results=$(eagle_search_summaries "$fts_query" "$project" "$summary_limit")
 
 if [ -n "$results" ]; then
-    context+="=== Eagle Mem: Relevant Recall ===
+    if [ "$codex_compact" -eq 1 ]; then
+        context+="
+Eagle Mem recalls:
 "
+    else
+        context+="=== Eagle Mem: Relevant Recall ===
+"
+    fi
     while IFS='|' read -r req completed learned _next_steps created_at _proj decisions gotchas key_files summary_agent; do
         [ -z "$req" ] && [ -z "$completed" ] && continue
         origin_label=$(eagle_agent_label "$summary_agent")
@@ -143,13 +155,14 @@ if [ -n "$results" ]; then
             req=$(eagle_trim_text "$req" 90)
             completed=$(eagle_trim_text "$completed" 150)
             learned=$(eagle_trim_text "$learned" 110)
-            context+="- [$origin_label] "
+            context+="- Recent [$origin_label]: "
             if [ -n "$completed" ]; then
                 context+="$completed"
             else
                 context+="$req"
             fi
-            [ -n "$learned" ] && context+=" | learned: $learned"
+            [ -n "$learned" ] && context+="
+  Learned: $learned"
             context+="
 "
         else
@@ -181,11 +194,21 @@ if [ "${has_chunks:-0}" -gt 0 ]; then
     code_results=$(eagle_search_code_chunks "$fts_query" "$project" "$code_limit")
 
     if [ -n "$code_results" ]; then
-        context+="=== Eagle Mem: Relevant Code ===
+        if [ "$codex_compact" -eq 1 ]; then
+            context+="
+Relevant code:
+"
+        else
+            context+="=== Eagle Mem: Relevant Code ===
 "
+        fi
         while IFS='|' read -r fpath sline eline lang; do
             [ -z "$fpath" ] && continue
-            context+="$fpath:${sline}-${eline}"
+            if [ "$codex_compact" -eq 1 ]; then
+                context+="- $fpath:${sline}-${eline}"
+            else
+                context+="$fpath:${sline}-${eline}"
+            fi
             [ -n "$lang" ] && context+=" ($lang)"
             context+="
 "
@@ -197,7 +220,7 @@ fi
 
 if [ "$codex_compact" -eq 1 ]; then
     context+="
-Use only if directly useful. If you mention it to the user, keep Eagle Mem attribution to one short line.
+Note: use only if directly useful. If you mention it to the user, keep Eagle Mem attribution to one short line.
 "
 else
     context+="