eagle-mem 4.8.4 → 4.8.6

package/README.md

@@ -11,7 +11,7 @@
 
 Eagle Mem turns AI coding sessions into compounding project knowledge. It gives Claude Code and Codex the same local memory, 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.8.4 proves the worker-lane path end to end:** Codex can create an orchestration, route a lane to Claude Code by default, launch the Claude worker in an isolated worktree, mirror the lane into `agent_tasks`, and generate a durable handoff without crashing on Bash 3.2.
+**v4.8.5 hardens first-run setup:** `eagle-mem config init` now falls through cleanly when Ollama is not running, and DB-backed commands fail loudly when the active `sqlite3` lacks FTS5 support.
 
 **Website:** [Product](https://eagleisbatman.github.io/eagle-mem/) |
 [Architecture](https://eagleisbatman.github.io/eagle-mem/architecture.html) |
@@ -140,6 +140,7 @@ Eagle Mem prevents Claude from repeating past mistakes:
 | `eagle-mem config` | View or change LLM provider and token-guard settings |
 | `eagle-mem guard` | Manage regression guardrails for files |
 | `eagle-mem overview` | Build or view project overview |
+| `eagle-mem session` | Save a manual fallback session summary |
 | `eagle-mem memories` | View/sync agent memories |
 | `eagle-mem tasks` | View mirrored tasks |
 | `eagle-mem orchestrate` | Coordinate durable worker lanes across agents |
@@ -149,6 +150,14 @@ Eagle Mem prevents Claude from repeating past mistakes:
 | `eagle-mem scan` | Scan codebase and generate overview |
 | `eagle-mem index` | Index source files for FTS5 code search |
 
+### v4.8.6 Patch
+
+`eagle-mem session save --summary "..."` now exists as a clean manual fallback for agents that need to persist an explicit session note. It writes through the same `sessions` and `summaries` tables used by Stop hooks, keeps Claude Code/Codex source attribution, and is immediately searchable through normal recall.
+
+### v4.8.5 Patch
+
+First-run configuration no longer exits silently when Ollama is not listening on `localhost:11434`; Eagle Mem falls through to the installed Codex/Claude CLI provider or API-key providers. SQLite/FTS5 failures are now surfaced before DB-backed commands run, including the exact `sqlite3` binary being used and PATH guidance for common macOS Android SDK shadowing. Worker worktree paths are also canonicalized back to the main project key so backfill cannot move feature guardrails into disposable orchestration worktrees.
+
 ### v4.8.4 Patch
 
 The orchestration handoff path is now Bash 3.2-safe, so `eagle-mem orchestrate handoff` works even when no lane options are present. This patch was verified with a real Codex coordinator -> Claude Code worker proof lane using `claude-opus-4-7` at `xhigh`; the completed lane is visible through `eagle-mem orchestrate --json`, `eagle-mem tasks completed`, and the generated handoff output. Release-boundary detection also ignores Eagle Mem's own `feature verify`/`waive` commands, so verification notes can mention dry-run checks without blocking themselves.
@@ -176,6 +185,7 @@ eagle-mem search --tasks           # in-flight tasks (pending/in-progress)
 eagle-mem search --files           # most frequently modified files
 eagle-mem search --stats           # project statistics
 eagle-mem search --session <id>    # full observation trail for one session
+eagle-mem session save --summary "fixed auth flow"  # manual fallback capture
 ```
 
 ### Feature Verification

package/bin/eagle-mem

@@ -24,6 +24,8 @@ case "$command" in
     config)     bash "$SCRIPTS_DIR/config.sh" "$@" ;;
     guard)      bash "$SCRIPTS_DIR/guard.sh" "$@" ;;
     overview)   bash "$SCRIPTS_DIR/overview.sh" "$@" ;;
+    session|sessions)
+                bash "$SCRIPTS_DIR/session.sh" "$@" ;;
     memories)   bash "$SCRIPTS_DIR/memories.sh" "$@" ;;
     tasks)      bash "$SCRIPTS_DIR/tasks.sh" "$@" ;;
     orchestrate) bash "$SCRIPTS_DIR/orchestrate.sh" "$@" ;;

package/db/migrate.sh

@@ -9,6 +9,20 @@ EAGLE_MEM_DIR="${EAGLE_MEM_DIR:-$HOME/.eagle-mem}"
 DB="$EAGLE_MEM_DIR/memory.db"
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 
+COMMON_SH="$SCRIPT_DIR/../lib/common.sh"
+if [ -f "$COMMON_SH" ]; then
+    . "$COMMON_SH"
+    eagle_require_sqlite_fts5 || exit 1
+else
+    sqlite_path=$(command -v sqlite3 2>/dev/null || true)
+    if [ -z "$sqlite_path" ] || ! sqlite3 :memory: "CREATE VIRTUAL TABLE eagle_mem_fts5_probe USING fts5(value);" >/dev/null 2>&1; then
+        echo "Eagle Mem requires SQLite FTS5, but the active sqlite3 does not support it." >&2
+        [ -n "$sqlite_path" ] && echo "Detected sqlite3: $sqlite_path" >&2
+        echo "Fix PATH so an FTS5-capable sqlite3 is first, then re-run the command." >&2
+        exit 1
+    fi
+fi
+
 # Restrict permissions: DB and config contain session data and may contain
 # residual secrets despite redaction. Owner-only access (700 dir, 600 files).
 umask 077

package/lib/common.sh

@@ -20,6 +20,47 @@ EAGLE_CODEX_SKILLS_DIR="${EAGLE_CODEX_SKILLS_DIR:-$EAGLE_CODEX_DIR/skills}"
 EAGLE_CODEX_MEMORIES_DIR="${EAGLE_CODEX_MEMORIES_DIR:-$EAGLE_CODEX_DIR/memories}"
 EAGLE_RAW_BASH_UNLOCK="${EAGLE_RAW_BASH_UNLOCK:-/tmp/eagle-mem-raw-bash-unlock}"
 
+eagle_sqlite_path() {
+    command -v sqlite3 2>/dev/null || true
+}
+
+eagle_sqlite_version() {
+    sqlite3 --version 2>/dev/null | awk '{print $1}'
+}
+
+eagle_sqlite_supports_fts5() {
+    command -v sqlite3 >/dev/null 2>&1 || return 1
+    sqlite3 :memory: "CREATE VIRTUAL TABLE eagle_mem_fts5_probe USING fts5(value);" >/dev/null 2>&1
+}
+
+eagle_print_sqlite_fts5_error() {
+    local sqlite_path sqlite_version probe_error
+    sqlite_path=$(eagle_sqlite_path)
+    sqlite_version=$(eagle_sqlite_version)
+    probe_error=$(sqlite3 :memory: "CREATE VIRTUAL TABLE eagle_mem_fts5_probe USING fts5(value);" 2>&1 >/dev/null || true)
+
+    printf '%s\n' "Eagle Mem requires SQLite FTS5, but the active sqlite3 does not support it." >&2
+    if [ -n "$sqlite_path" ]; then
+        printf '%s\n' "Detected sqlite3: $sqlite_path" >&2
+    else
+        printf '%s\n' "Detected sqlite3: not found on PATH" >&2
+    fi
+    [ -n "$sqlite_version" ] && printf '%s\n' "SQLite version: $sqlite_version" >&2
+    [ -n "$probe_error" ] && printf '%s\n' "SQLite error: $probe_error" >&2
+    printf '%s\n' "Fix: put an FTS5-capable sqlite3 earlier in PATH, then re-run the command." >&2
+    printf '%s\n' "macOS: check 'command -v sqlite3'; /usr/bin/sqlite3 usually has FTS5. If Android SDK platform-tools is first, move it later in PATH." >&2
+    printf '%s\n' "Homebrew: install sqlite and prepend its bin directory, for example: export PATH=\"/opt/homebrew/opt/sqlite/bin:\$PATH\"" >&2
+    printf '%s\n' "Linux: install a sqlite3 package compiled with ENABLE_FTS5." >&2
+}
+
+eagle_require_sqlite_fts5() {
+    if eagle_sqlite_supports_fts5; then
+        return 0
+    fi
+    eagle_print_sqlite_fts5_error
+    return 1
+}
+
 eagle_log() {
     local level="$1"
     shift
@@ -51,6 +92,23 @@ eagle_project_from_cwd() {
         "$HOME/Desktop"|"$HOME/Desktop/"*) echo ""; return ;;
     esac
 
+    # Eagle Mem worker lanes run in sibling git worktrees under
+    # <parent>/.eagle-worktrees/<repo>/<lane>. Keep their observations attached
+    # to the real project, not to the disposable worktree path.
+    case "$resolved" in
+        "$HOME"/*/.eagle-worktrees/*)
+            local worktree_parent worktree_tail worktree_repo worktree_project
+            worktree_parent="${resolved%%/.eagle-worktrees/*}"
+            worktree_tail="${resolved#"$worktree_parent/.eagle-worktrees/"}"
+            worktree_repo="${worktree_tail%%/*}"
+            worktree_project="$worktree_parent/$worktree_repo"
+            if [ -n "$worktree_repo" ] && [ -d "$worktree_project" ]; then
+                echo "${worktree_project#$HOME/}"
+                return
+            fi
+            ;;
+    esac
+
     local target_dir
     local git_root
     git_root=$(git -C "$cwd" rev-parse --show-toplevel 2>/dev/null)

package/lib/db-core.sh

@@ -57,6 +57,8 @@ eagle_db_json() {
 }
 
 eagle_ensure_db() {
+    eagle_require_sqlite_fts5 || return 1
+
     if [ ! -f "$EAGLE_MEM_DB" ]; then
         local script_dir
         script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/../db" && pwd)"

package/lib/provider.sh

@@ -124,10 +124,10 @@ eagle_config_init() {
     local ollama_model="mistral"
 
     local ollama_response
-    ollama_response=$(eagle_detect_ollama "$ollama_url")
+    ollama_response=$(eagle_detect_ollama "$ollama_url" || true)
     if [ -n "$ollama_response" ]; then
         provider="ollama"
-        model=$(eagle_ollama_best_model "$ollama_url")
+        model=$(eagle_ollama_best_model "$ollama_url" || true)
         ollama_model="$model"
     elif command -v codex &>/dev/null || command -v claude &>/dev/null; then
         provider="agent_cli"

package/package.json

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

package/scripts/help.sh

@@ -23,6 +23,7 @@ echo -e "    ${CYAN}uninstall${RESET}   Remove hooks and optionally delete data"
 echo -e "    ${CYAN}search${RESET}      Search past sessions, memories, and code"
 echo -e "    ${CYAN}health${RESET}      Diagnose pipeline health and background automation"
 echo -e "    ${CYAN}overview${RESET}    Build or view project overview"
+echo -e "    ${CYAN}session${RESET}     Save a manual session summary"
 echo -e "    ${CYAN}memories${RESET}    View/sync agent memories"
 echo -e "    ${CYAN}tasks${RESET}       View mirrored tasks"
 echo ""
@@ -50,6 +51,7 @@ echo -e "    ${DIM}\$${RESET} eagle-mem search --memories     ${DIM}# mirrored m
 echo -e "    ${DIM}\$${RESET} eagle-mem search --tasks        ${DIM}# in-flight tasks${RESET}"
 echo -e "    ${DIM}\$${RESET} eagle-mem search --files        ${DIM}# hot files${RESET}"
 echo -e "    ${DIM}\$${RESET} eagle-mem search --stats        ${DIM}# project stats${RESET}"
+echo -e "    ${DIM}\$${RESET} eagle-mem session save --summary \"fixed auth\""
 echo ""
 echo -e "  ${BOLD}Anti-regression:${RESET}"
 echo -e "    ${DIM}\$${RESET} eagle-mem feature pending       ${DIM}# pending release blockers${RESET}"

package/scripts/install.sh

@@ -81,12 +81,19 @@ fi
 
 # FTS5 support
 if command -v sqlite3 &>/dev/null; then
-    if sqlite3 :memory: "SELECT sqlite_compileoption_used('ENABLE_FTS5');" 2>/dev/null | grep -q "1"; then
-        eagle_ok "FTS5 support"
+    sqlite_path=$(eagle_sqlite_path)
+    if eagle_sqlite_supports_fts5; then
+        eagle_ok "FTS5 support ${DIM}($sqlite_path)${RESET}"
     else
         eagle_fail "SQLite was compiled without FTS5 support"
-        eagle_dim "On macOS: brew install sqlite3 (system sqlite3 includes FTS5)"
-        eagle_dim "On Linux: install libsqlite3-dev or rebuild with --enable-fts5"
+        eagle_dim "Detected sqlite3: $sqlite_path"
+        sqlite_version=$(eagle_sqlite_version)
+        [ -n "$sqlite_version" ] && eagle_dim "SQLite version: $sqlite_version"
+        eagle_dim "Run: command -v sqlite3"
+        eagle_dim "Fix PATH so an FTS5-capable sqlite3 is first."
+        eagle_dim "macOS: /usr/bin/sqlite3 usually has FTS5; move Android SDK platform-tools later if it shadows sqlite3."
+        eagle_dim "Homebrew: brew install sqlite, then prepend /opt/homebrew/opt/sqlite/bin or /usr/local/opt/sqlite/bin."
+        eagle_dim "Linux: install a sqlite3 package compiled with ENABLE_FTS5."
         prereqs_ok=false
     fi
 fi

package/scripts/session.sh

@@ -0,0 +1,220 @@
+#!/usr/bin/env bash
+# ═══════════════════════════════════════════════════════════
+# Eagle Mem — Manual session capture
+# ═══════════════════════════════════════════════════════════
+set -euo pipefail
+
+SCRIPTS_DIR="$(cd "$(dirname "$0")" && pwd)"
+LIB_DIR="$SCRIPTS_DIR/../lib"
+
+. "$SCRIPTS_DIR/style.sh"
+. "$LIB_DIR/common.sh"
+. "$LIB_DIR/db.sh"
+
+show_help() {
+    echo -e "  ${BOLD}eagle-mem session${RESET} — Save or inspect session records"
+    echo ""
+    echo -e "  ${BOLD}Usage:${RESET}"
+    echo -e "    eagle-mem session ${CYAN}save --summary <text>${RESET}"
+    echo -e "    eagle-mem session ${CYAN}save <text>${RESET}"
+    echo ""
+    echo -e "  ${BOLD}Options for save:${RESET}"
+    echo -e "    ${CYAN}--summary${RESET} <text>       Summary to store"
+    echo -e "    ${CYAN}--request${RESET} <text>       User request that caused the work"
+    echo -e "    ${CYAN}--learned${RESET} <text>       Non-obvious discoveries"
+    echo -e "    ${CYAN}--decisions${RESET} <text>     Decisions and why"
+    echo -e "    ${CYAN}--gotchas${RESET} <text>       Surprises or pitfalls"
+    echo -e "    ${CYAN}--next-steps${RESET} <text>    Follow-up work"
+    echo -e "    ${CYAN}--key-files${RESET} <text>     Important files"
+    echo -e "    ${CYAN}--notes${RESET} <text>         Extra notes"
+    echo -e "    ${CYAN}-p, --project${RESET} <name>   Project name (default: current git root)"
+    echo -e "    ${CYAN}--agent${RESET} <name>         Source agent: codex or claude-code"
+    echo -e "    ${CYAN}--cwd${RESET} <path>           Working directory for project detection"
+    echo -e "    ${CYAN}--json${RESET}                 Output JSON"
+    echo ""
+    echo -e "  ${DIM}This command is mainly for agent fallbacks. Normal sessions are captured${RESET}"
+    echo -e "  ${DIM}automatically by hooks when Claude Code or Codex stops a turn.${RESET}"
+    echo ""
+}
+
+require_value() {
+    local flag="$1"
+    if [ $# -lt 2 ] || [ -z "${2:-}" ]; then
+        eagle_err "$flag requires a value"
+        exit 1
+    fi
+}
+
+json_string() {
+    jq -Rn --arg v "${1:-}" '$v'
+}
+
+save_session() {
+    local summary=""
+    local request="Manual session save"
+    local learned=""
+    local decisions=""
+    local gotchas=""
+    local next_steps=""
+    local key_files=""
+    local notes=""
+    local project=""
+    local cwd
+    cwd="$(pwd)"
+    local agent=""
+    local json_output=false
+
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --summary)
+                require_value "$1" "${2:-}"
+                summary="$2"
+                shift 2
+                ;;
+            --request)
+                require_value "$1" "${2:-}"
+                request="$2"
+                shift 2
+                ;;
+            --learned)
+                require_value "$1" "${2:-}"
+                learned="$2"
+                shift 2
+                ;;
+            --decisions)
+                require_value "$1" "${2:-}"
+                decisions="$2"
+                shift 2
+                ;;
+            --gotchas)
+                require_value "$1" "${2:-}"
+                gotchas="$2"
+                shift 2
+                ;;
+            --next-steps)
+                require_value "$1" "${2:-}"
+                next_steps="$2"
+                shift 2
+                ;;
+            --key-files)
+                require_value "$1" "${2:-}"
+                key_files="$2"
+                shift 2
+                ;;
+            --notes)
+                require_value "$1" "${2:-}"
+                notes="$2"
+                shift 2
+                ;;
+            --project|-p)
+                require_value "$1" "${2:-}"
+                project="$2"
+                shift 2
+                ;;
+            --cwd)
+                require_value "$1" "${2:-}"
+                cwd="$2"
+                shift 2
+                ;;
+            --agent)
+                require_value "$1" "${2:-}"
+                agent="$2"
+                shift 2
+                ;;
+            --json|-j)
+                json_output=true
+                shift
+                ;;
+            --help|-h)
+                show_help
+                exit 0
+                ;;
+            --)
+                shift
+                if [ $# -gt 0 ]; then
+                    summary="${summary}${summary:+ }$*"
+                    shift $#
+                fi
+                ;;
+            -*)
+                eagle_err "Unknown option for session save: $1"
+                exit 1
+                ;;
+            *)
+                summary="${summary}${summary:+ }$1"
+                shift
+                ;;
+        esac
+    done
+
+    if [ -z "$summary" ]; then
+        eagle_err "Nothing to save. Pass --summary <text>."
+        exit 1
+    fi
+
+    [ -z "$project" ] && project=$(eagle_project_from_cwd "$cwd")
+    if [ -z "$project" ]; then
+        eagle_err "Could not determine project. Re-run with --project <name>."
+        exit 1
+    fi
+
+    if [ -z "$agent" ]; then
+        agent=$(eagle_agent_source)
+    else
+        case "$agent" in
+            codex|openai-codex) agent="codex" ;;
+            claude|claude-code|cloud-code) agent="claude-code" ;;
+            *)
+                eagle_err "--agent must be codex or claude-code"
+                exit 1
+                ;;
+        esac
+    fi
+
+    summary=$(printf '%s' "$summary" | eagle_redact)
+    request=$(printf '%s' "$request" | eagle_redact)
+    learned=$(printf '%s' "$learned" | eagle_redact)
+    decisions=$(printf '%s' "$decisions" | eagle_redact)
+    gotchas=$(printf '%s' "$gotchas" | eagle_redact)
+    next_steps=$(printf '%s' "$next_steps" | eagle_redact)
+    key_files=$(printf '%s' "$key_files" | eagle_redact)
+    notes=$(printf '%s' "$notes" | eagle_redact)
+
+    eagle_ensure_db
+
+    local stamp session_id
+    stamp=$(date -u +%Y%m%dT%H%M%SZ)
+    session_id="manual-${stamp}-$$-${RANDOM:-0}"
+
+    eagle_upsert_session "$session_id" "$project" "$cwd" "" "manual" "$agent"
+    eagle_insert_summary "$session_id" "$project" "$request" "" "$learned" "$summary" "$next_steps" "[]" "[]" "$notes" "$decisions" "$gotchas" "$key_files" "$agent"
+    eagle_end_session "$session_id"
+
+    if [ "$json_output" = true ]; then
+        printf '{'
+        printf '"session_id":%s,' "$(json_string "$session_id")"
+        printf '"project":%s,' "$(json_string "$project")"
+        printf '"agent":%s,' "$(json_string "$agent")"
+        printf '"summary":%s' "$(json_string "$summary")"
+        printf '}\n'
+    else
+        eagle_ok "Session summary saved"
+        eagle_kv "Project:" "$project"
+        eagle_kv "Source:" "$(eagle_agent_label "$agent")"
+        eagle_kv "Session:" "$session_id"
+    fi
+}
+
+command="${1:-help}"
+shift 2>/dev/null || true
+
+case "$command" in
+    save) save_session "$@" ;;
+    help|--help|-h) show_help ;;
+    *)
+        eagle_err "Unknown session command: $command"
+        echo ""
+        show_help
+        exit 1
+        ;;
+esac