eagle-mem 4.8.0 → 4.8.2

package/README.md

@@ -1,16 +1,29 @@
 ```
 ======================================
        Eagle Mem
-  context that survives /compact
+ shared memory | guardrails | lanes
 ======================================
 ```
 
 # Eagle Mem
 
-**Context that survives `/compact`.**
+**Shared memory, release guardrails, and worker lanes for Claude Code and Codex.**
 
-**v4.8.0 ships first-class cross-agent orchestration, compact Codex hook recall, enforced anti-regression checks, and configurable RTK token guardrails.**
-Claude Code and Codex can now share the same local Eagle Mem database, while every captured row records which agent created it.
+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.2 ships Codex output polish:** Codex final replies now stay clean by default instead of printing large `<eagle-summary>` capture blocks. Eagle Mem still captures summaries from the Stop transcript, while Claude Code can keep using the richer explicit summary path where it behaves cleanly.
+
+**Website:** [Product](https://eagleisbatman.github.io/eagle-mem/) |
+[Architecture](https://eagleisbatman.github.io/eagle-mem/architecture.html) |
+[About](https://eagleisbatman.github.io/eagle-mem/about.html)
+
+## Why People Install It
+
+- **Start warmer** - every new session can recall project overviews, decisions, gotchas, summaries, hot files, mirrored memories, plans, and tasks.
+- **Ship safer** - feature-mapped changes create pending verification records, and release-boundary commands stay blocked until the current diff is verified or waived.
+- **Waste fewer tokens** - Eagle Mem injects compact context, nudges duplicate reads, and can route noisy shell output through RTK.
+- **Coordinate agents** - Codex and Claude Code can share one project memory while worker lanes record owner, model, effort, worktree, logs, validation, and handoff.
+- **Stay local** - no daemon, no hosted memory service, no vector database. The core is hooks plus SQLite/FTS5.
 
 ## The Problem
 
@@ -18,9 +31,17 @@ Claude Code and Codex start every session with amnesia. They don't remember what
 
 The longer you work with Claude Code, the worse this gets. Projects accumulate history — decisions, gotchas, architectural patterns, feature dependencies — and none of it survives across sessions.
 
-## The Solution
+## The Product
+
+Eagle Mem is a local runtime layer for AI coding agents. It adds three things that ordinary agent sessions do not have by default:
 
-Eagle Mem is a recall and regression-control layer for Claude Code and Codex. Every session starts with context from previous sessions — summaries, decisions, memories, tasks, project overviews, and relevant code — injected automatically via hooks. Both agents share the same SQLite database at `~/.eagle-mem/memory.db`, and captured rows are source-attributed as `Claude Code` or `Codex`.
+| Layer | What users feel | What Eagle Mem does |
+|-------|-----------------|---------------------|
+| **Recall** | "The agent remembers this repo." | Loads project overviews, summaries, decisions, memories, tasks, plans, and relevant indexed code. |
+| **Guardrails** | "The agent cannot casually undo known decisions or push unverified feature changes." | Surfaces decisions before edits and enforces feature verification on push, PR, and publish boundaries. |
+| **Lanes** | "A big task can survive compaction and split across agents." | Persists orchestrations, worker lanes, worktrees, logs, validation commands, and handoffs. |
+
+Both agents share the same SQLite database at `~/.eagle-mem/memory.db`, and captured rows are source-attributed as `Claude Code` or `Codex`.
 
 **Zero per-instance overhead.** No daemon, no vector DB, no MCP server. Just bash scripts, sqlite3 (WAL mode, FTS5 full-text search), and jq.
 
@@ -128,6 +149,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.2 Patch
+
+Codex no longer gets instructed to print large user-visible `<eagle-summary>` XML blocks. The installer/update path rewrites existing `~/.codex/AGENTS.md` Eagle Mem instructions to the clean-output contract, context-pressure nudges use normal prose, and Codex-oriented skills/worker prompts avoid raw capture templates.
+
+### v4.8.1 Patch
+
+`eagle-mem memories sync` is now safe on large Claude Code/Codex memory files. The memory mirror parser no longer uses early-exit pipelines under `pipefail`, avoiding exit `141` during sync.
+
 ### Search Modes
 
 ```bash

package/hooks/session-start.sh

@@ -171,7 +171,7 @@ fi
 if [ "$agent" = "codex" ] && [ "${stat_with_summaries:-0}" -eq 0 ] 2>/dev/null; then
     context+="
 === Eagle Mem: Codex Capture Warming Up ===
-Codex hooks are active. End important turns with an <eagle-summary> block so future Claude Code and Codex sessions can recall decisions, gotchas, key files, and next steps from this project.
+Codex hooks are active. Keep final replies clean; Eagle Mem will capture decisions, gotchas, key files, and next steps from the transcript automatically.
 "
 fi
 
@@ -439,7 +439,7 @@ fi
 if [ "$agent" = "codex" ]; then
     context+="
 === Eagle Mem: Active ===
-Memory active for '$project'. Emit <eagle-summary> in final responses with request, completed, learned, decisions, gotchas, next_steps, key_files, files_read, files_modified, affected_features, verified_features, and regression_risks.
+Memory active for '$project'. Keep user-facing Codex replies clean: do not print Eagle Mem summary capture blocks, XML, JSON hook payloads, or internal templates unless the user explicitly asks. The Stop hook captures summaries from the transcript automatically.
 "
 elif [ "$source_type" = "compact" ] || [ "$source_type" = "clear" ]; then
     context+="

package/hooks/stop.sh

@@ -238,7 +238,7 @@ if [ "$needs_enrichment" -eq 1 ]; then
     if [ "$provider" != "none" ] && [ -n "$text_content" ]; then
         excerpt=$(echo "$text_content" | tail -c 3000)
 
-        enrich_prompt="Extract facts from this Claude Code session. Only include items with clear evidence in the session text. Do NOT invent or repeat example content.
+        enrich_prompt="Extract facts from this AI coding session. Only include items with clear evidence in the session text. Do NOT invent or repeat example content.
 
 Respond with EXACTLY these sections (omit sections with no evidence):
 
@@ -263,7 +263,7 @@ Each as: <filepath>
 SESSION TEXT:
 $excerpt"
 
-        enrich_system="You extract structured facts from development sessions. Output format for decisions: '- Did X — why: Y'. Output format for gotchas: '- Gotcha description'. Be concise. Only include items with clear evidence in the session text. Never fabricate content."
+        enrich_system="You extract structured facts from Claude Code and Codex development sessions. Output format for decisions: '- Did X — why: Y'. Output format for gotchas: '- Gotcha description'. Be concise. Only include items with clear evidence in the session text. Never fabricate content."
         enrich_result=$(eagle_llm_call "$enrich_prompt" "$enrich_system" 768 2>/dev/null)
         llm_rc=$?
 

package/hooks/user-prompt-submit.sh

@@ -44,18 +44,32 @@ if [ -n "$session_id" ] && eagle_validate_session_id "$session_id"; then
     eagle_log "INFO" "UserPromptSubmit: turn=$turn_count session=$session_id"
 
     if [ "$turn_count" -ge 30 ]; then
-        context+="
+        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.
+"
+        else
+            context+="
 === Eagle Mem: Context Pressure Critical ($turn_count turns since compact) ===
 IMMEDIATELY emit a detailed <eagle-summary> covering ALL work this session.
 Tell the user to run /compact NOW to avoid losing context.
 "
+        fi
         echo "$turn_count" > "$EAGLE_MEM_DIR/.context-pressure"
     elif [ "$turn_count" -ge 20 ]; then
-        context+="
+        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.
+"
+        else
+            context+="
 === Eagle Mem: Context Pressure High ($turn_count turns since compact) ===
 Include a thorough <eagle-summary> in your next response — capture all decisions, gotchas, and learned context before compaction.
 Suggest the user run /compact to free context for continued work.
 "
+        fi
         echo "$turn_count" > "$EAGLE_MEM_DIR/.context-pressure"
     else
         rm -f "$EAGLE_MEM_DIR/.context-pressure" 2>/dev/null

package/lib/common.sh

@@ -659,10 +659,7 @@ eagle_patch_claude_md() {
                 skip && /^## / { skip=0 }
                 !skip { print }
             ' "$claude_md" > "$tmp_md"
-            # Remove trailing blank lines left by section removal
-            sed -e :a -e '/^[[:space:]]*$/{ $d; N; ba; }' "$tmp_md" > "${tmp_md}.clean"
-            mv "${tmp_md}.clean" "$claude_md"
-            rm -f "$tmp_md"
+            mv "$tmp_md" "$claude_md"
             _eagle_claude_md_section >> "$claude_md"
             return 0
         fi
@@ -692,30 +689,13 @@ _eagle_codex_agents_section() {
 
 Eagle Mem hooks are active for Codex in this project. SessionStart and UserPromptSubmit inject project recall from the shared Eagle Mem database at `~/.eagle-mem/memory.db`. PostToolUse records observations and marks affected features for verification.
 
-**Rule:** Before your final response in every session, emit an `<eagle-summary>` block so the Stop hook can capture a rich summary.
-
-```
-<eagle-summary>
-request: [what user asked]
-completed: [what shipped]
-learned: [non-obvious discoveries]
-decisions: [choice — why]
-gotchas: [what surprised]
-next_steps: [concrete actions]
-key_files: [path — role]
-files_read: [path, ...]
-files_modified: [path, ...]
-affected_features: [feature, ...]
-verified_features: [feature, ...]
-regression_risks: [risk, ...]
-</eagle-summary>
-```
+**User-visible output rule:** Keep Codex final answers clean. Do not print Eagle Mem summary capture blocks, XML, JSON hook payloads, or internal templates to the user unless the user explicitly asks for raw Eagle Mem internals. The Stop hook captures Codex summaries from the transcript automatically.
 
 **How to apply:**
 - Attribute recalled context as "Eagle Mem recalls:" when it is injected
 - Use the Eagle Mem skills when relevant: `eagle-mem-search`, `eagle-mem-overview`, `eagle-mem-memories`, `eagle-mem-tasks`, and `eagle-mem-orchestrate`
 - For broad multi-agent work, YOU run `eagle-mem orchestrate`; do not ask the user to run these commands
-- For important decisions, preferences, gotchas, or durable project facts, explicitly include them in the `<eagle-summary>` block so Codex-originated memories become available to future Claude Code and Codex sessions
+- For important decisions, preferences, gotchas, or durable project facts, include them briefly in normal prose. Eagle Mem will extract them from the transcript.
 - Do not revert Eagle Mem-surfaced decisions without asking the user
 - If Eagle Mem reports pending feature verification, verify or waive it before push/PR/publish
 - Never put raw secrets in summaries
@@ -729,6 +709,23 @@ eagle_patch_codex_agents_md() {
     mkdir -p "$(dirname "$agents_md")"
 
     if [ -f "$agents_md" ] && grep -qF "$marker" "$agents_md" 2>/dev/null; then
+        if grep -qF 'emit an `<eagle-summary>` block' "$agents_md" 2>/dev/null \
+            || grep -qF 'emit an <eagle-summary> block' "$agents_md" 2>/dev/null \
+            || grep -qF 'explicitly include them in the `<eagle-summary>` block' "$agents_md" 2>/dev/null \
+            || grep -qF 'explicitly include them in the <eagle-summary> block' "$agents_md" 2>/dev/null \
+            || ! grep -qF 'Keep Codex final answers clean' "$agents_md" 2>/dev/null; then
+            local tmp_md
+            tmp_md=$(mktemp)
+            awk -v marker="$marker" '
+                $0 ~ marker { skip=1; next }
+                skip && /^---$/ { skip=0; next }
+                skip && /^## / { skip=0 }
+                !skip { print }
+            ' "$agents_md" > "$tmp_md"
+            mv "$tmp_md" "$agents_md"
+            _eagle_codex_agents_section >> "$agents_md"
+            return 0
+        fi
         if ! grep -qF 'eagle-mem orchestrate' "$agents_md" 2>/dev/null; then
             local tmp_md
             tmp_md=$(mktemp)

package/lib/db-mirrors.sh

@@ -23,7 +23,7 @@ eagle_capture_agent_memory() {
         body=$(cat "$file_path")
     fi
 
-    _fm_field() { printf '%s\n' "$fm" | awk -F': *' -v k="$1" '$1==k{sub(/^[^:]+: */,""); gsub(/^"|"$/,""); print; exit}'; }
+    _fm_field() { awk -F': *' -v k="$1" '$1==k{sub(/^[^:]+: */,""); gsub(/^"|"$/,""); print; exit}' <<< "$fm"; }
 
     local mname mdesc mtype morigin
     mname=$(_fm_field "name")
@@ -41,7 +41,14 @@ eagle_capture_agent_memory() {
     fi
     [ -z "$mtype" ] && mtype="$agent"
     if [ -z "$mdesc" ]; then
-        mdesc=$(printf '%s\n' "$body" | sed '/^[[:space:]]*$/d' | head -1 | cut -c1-200)
+        mdesc=$(awk '
+            /^[[:space:]]*$/ { next }
+            {
+                line = substr($0, 1, 200)
+                print line
+                exit
+            }
+        ' <<< "$body")
     fi
 
     local fp_sql proj_sql name_sql desc_sql type_sql content_sql hash_sql origin_sql agent_sql

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "eagle-mem",
-  "version": "4.8.0",
-  "description": "Context that survives /compact for Claude Code and Codex — SQLite + FTS5, no daemon, no bloat",
+  "version": "4.8.2",
+  "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

@@ -13,24 +13,35 @@ version=$(jq -r .version "$PACKAGE_DIR/package.json" 2>/dev/null || echo "unknow
 eagle_banner
 
 echo -e "  ${BOLD}Eagle Mem${RESET} ${DIM}v${version}${RESET}"
-echo -e "  ${DIM}Context that survives /compact for Claude Code and Codex${RESET}"
+echo -e "  ${DIM}Shared memory, release guardrails, RTK token protection, and worker lanes${RESET}"
+echo -e "  ${DIM}for Claude Code and Codex.${RESET}"
 echo ""
-echo -e "  ${BOLD}Commands:${RESET}"
+echo -e "  ${BOLD}Core commands:${RESET}"
 echo -e "    ${CYAN}install${RESET}     First-time setup: hooks, database, skills"
 echo -e "    ${CYAN}update${RESET}      Re-deploy hooks and run migrations"
 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}config${RESET}      View or change provider and token-guard settings"
-echo -e "    ${CYAN}guard${RESET}       Manage regression guardrails for files"
 echo -e "    ${CYAN}overview${RESET}    Build or view project overview"
 echo -e "    ${CYAN}memories${RESET}    View/sync agent memories"
 echo -e "    ${CYAN}tasks${RESET}       View mirrored tasks"
-echo -e "    ${CYAN}orchestrate${RESET} Durable worker-lane coordination"
+echo ""
+echo -e "  ${BOLD}Safety and token controls:${RESET}"
+echo -e "    ${CYAN}feature${RESET}     Track, verify, and unblock feature changes"
+echo -e "    ${CYAN}guard${RESET}       Manage regression guardrails for files"
+echo -e "    ${CYAN}config${RESET}      View/change providers, RTK, and token guard settings"
+echo ""
+echo -e "  ${BOLD}Automation and coordination:${RESET}"
 echo -e "    ${CYAN}curate${RESET}      Run curator (co-edits, hot files, guardrails)"
-echo -e "    ${CYAN}feature${RESET}     Track, verify, and unblock features"
+echo -e "    ${CYAN}orchestrate${RESET} Durable worker-lane coordination"
 echo -e "    ${CYAN}prune${RESET}       Clean old sessions and stale data"
 echo ""
+echo -e "  ${BOLD}What it protects:${RESET}"
+echo -e "    ${DIM}Recall${RESET}       Project overview, summaries, memories, plans, tasks, code index"
+echo -e "    ${DIM}Guardrails${RESET}   Decisions, gotchas, feature verification, stale memory warnings"
+echo -e "    ${DIM}Tokens${RESET}       Compact hook recall and optional RTK shell-output routing"
+echo -e "    ${DIM}Lanes${RESET}        Cross-agent worker status, worktrees, logs, validation, handoffs"
+echo ""
 echo -e "  ${BOLD}Search modes:${RESET}"
 echo -e "    ${DIM}\$${RESET} eagle-mem search \"auth bug\"    ${DIM}# keyword search${RESET}"
 echo -e "    ${DIM}\$${RESET} eagle-mem search --timeline     ${DIM}# recent sessions${RESET}"

package/scripts/orchestrate.sh

@@ -301,7 +301,7 @@ Rules:
 - If blocked, run: eagle-mem orchestrate lane --project "$project" --name "$name" block "$lane_key" --notes "<concrete blocker>"
 - If you finish manually before the wrapper updates status, run: eagle-mem orchestrate lane --project "$project" --name "$name" complete "$lane_key" --notes "<validation result>"
 - Run the validation command when one is provided and it is safe for the lane.
-- Before final response, emit an <eagle-summary> with request, completed, learned, decisions, gotchas, next_steps, key_files, files_read, files_modified, affected_features, verified_features, and regression_risks.
+- Keep user-facing final responses clean. Claude Code workers may emit an Eagle Mem summary block when their UI handles it cleanly; Codex workers should not print XML, JSON, or internal capture blocks unless the user explicitly asks. Eagle Mem Stop hooks capture Codex summaries from the transcript automatically.
 PROMPT
 }
 

package/scripts/style.sh

@@ -18,7 +18,7 @@ CROSS="${RED}✗${RESET}"
 ARROW="${CYAN}→${RESET}"
 DOT="${DIM}·${RESET}"
 EAGLE_RULE="======================================"
-EAGLE_TAGLINE="context that survives /compact"
+EAGLE_TAGLINE="shared memory | guardrails | lanes"
 
 eagle_header() {
     echo ""

package/skills/eagle-mem-memories/SKILL.md

@@ -68,7 +68,7 @@ eagle-mem memories tasks show <file_path>
 
 Two paths feed the mirror:
 
-**Real-time hooks.** Claude Code memory/plan/task files are mirrored when written. Codex sessions are captured through SessionStart/UserPromptSubmit/PostToolUse/Stop hooks, and important durable facts should be placed in `<eagle-summary>` so they become shared recall.
+**Real-time hooks.** Claude Code memory/plan/task files are mirrored when written. Codex sessions are captured through SessionStart/UserPromptSubmit/PostToolUse/Stop hooks. In Codex, keep user-facing replies clean and put important durable facts in normal prose; Eagle Mem extracts them from the transcript.
 
 **Backfill (sync command).** For memories, plans, and tasks that existed before Eagle Mem was installed, or that were written outside a hooked session:
 ```bash

package/skills/eagle-mem-orchestrate/SKILL.md

@@ -129,8 +129,10 @@ ending a broad session.
 - Every lane should have a validation command when one is obvious.
 - If a lane is blocked, update the lane with a concrete note rather than
   silently stopping.
-- After completing a lane, emit an `<eagle-summary>` so Eagle Mem captures the
-  decision and files touched.
+- After completing a lane, keep the user-facing final response clean. Claude Code
+  may use the Eagle Mem summary block when that UI handles it cleanly; Codex
+  should record durable decisions in normal prose and let the Stop hook capture
+  the transcript.
 
 ## Reference
 

package/skills/eagle-mem-tasks/SKILL.md

@@ -66,7 +66,7 @@ Mark the current task in progress (`TaskUpdate(in_progress)` in Claude Code, or
 
 ### 4. Complete — record what happened
 
-Mark the task completed (`TaskUpdate(completed)` in Claude Code, or `eagle-mem tasks complete <id> --agent codex` in Codex). Emit `<eagle-summary>` so Eagle Mem captures what was accomplished.
+Mark the task completed (`TaskUpdate(completed)` in Claude Code, or `eagle-mem tasks complete <id> --agent codex` in Codex). In Claude Code, use the Eagle Mem summary block when that UI handles it cleanly. In Codex, keep the final reply clean and record durable decisions in normal prose; Eagle Mem captures the transcript automatically.
 
 If the task produced decisions that downstream tasks need, update those task descriptions now:
 ```