eagle-mem 4.8.5 → 4.8.6

package/README.md

@@ -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,10 @@ 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.
@@ -180,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eagle-mem",
-  "version": "4.8.5",
+  "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/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