From ad9cbe1fdca663d41ac037bfdbdcca7546677156 Mon Sep 17 00:00:00 2001
From: Story Crater Bot <19826264+Riotpiaole@users.noreply.github.com>
Date: Fri, 28 Aug 2026 08:05:14 -0700
Subject: [PATCH] docs: add mem sig explain command documentation with CLI
 examples

---
 memory-flow.md | 89 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 89 insertions(+)

diff --git a/memory-flow.md b/memory-flow.md
index b2ffe46..4cf5210 100644
--- a/memory-flow.md
+++ b/memory-flow.md
@@ -652,6 +652,58 @@ spec:
 
 **Purpose:** Reduce failure logs to canonical signatures that are byte-identical across runs.
 
+**CLI Command: `mem sig --tool=<TOOL> --file=<LOG>`**
+
+Extract and explain a failure signature from any log file:
+
+```bash
+# Extract signature from file
+mem sig --tool=npm --file=ci-logs/npm-install-failed.txt
+
+# Or from stdin
+cat failure.log | mem sig --tool=cargo
+
+# Output:
+# {
+#   "tool": "npm",
+#   "raw": "npm ERR! code ERESOLVE unable to resolve dependency tree",
+#   "normalised": "npm error eresolve dependency tree",
+#   "sig_sha": "abc123def456789abcdef456789abc123def456",
+#   "rule": "npm_error_line",
+#   "confidence": 0.95,
+#   "matched_line": 42,
+#   "context": [
+#     "npm ERR! npm ERR! code ERESOLVE",
+#     "npm ERR! [... 100+ lines of consequence ...]",
+#     "npm ERR! npm ERR! Could not resolve dependency:",
+#   ]
+# }
+```
+
+**Example Usage in CI/CD:**
+
+```bash
+# GitHub Actions: capture failure and explain
+if [ $? -ne 0 ]; then
+  echo "=== FAILURE SIGNATURE ==="
+  mem sig --tool=npm --file=$LOG_FILE >> $GITHUB_STEP_SUMMARY
+  exit 1
+fi
+
+# Kubernetes: explain pod logs
+kubectl logs <pod> | mem sig --tool=kubectl
+
+# Local development: diagnose build errors
+cargo build 2>&1 | mem sig --tool=cargo
+```
+
+**Key Features:**
+- ✅ **Deterministic:** Same failure always produces identical sig_sha
+- ✅ **Tool-aware:** npm ERR vs cargo error vs kubectl message handling
+- ✅ **Noise-resistant:** Strips timestamps, paths, SHAs, addresses
+- ✅ **Root-cause detection:** Picks root error, skips consequence lines
+- ✅ **Fast:** <50ms on 50KB logs (rule-based, no LLM)
+
 ```
 Failure Log (50KB, noisy):
   2026-08-21T10:02:11.482Z
@@ -792,6 +844,43 @@ Response:
 
 ---
 
+### CLI: `mem sig explain` — Query Signature Database
+
+Once signatures are extracted and stored, query by signature to find past solutions:
+
+```bash
+# Find all solutions for npm ERESOLVE errors
+mem sig explain --sig-sha=abc123def456789abcdef456789abc123def456
+
+# Or by tool + normalized query
+mem sig explain --tool=npm --query="unable to resolve dependency"
+
+# Output:
+# {
+#   "found": true,
+#   "sig_sha": "abc123...",
+#   "count": 3,
+#   "solutions": [
+#     {
+#       "source": "GH Action #1234",
+#       "timestamp": "2026-08-20T15:30:00Z",
+#       "solution": "npm ci instead of npm install",
+#       "success_rate": 0.95
+#     },
+#     ...
+#   ]
+# }
+```
+
+**Workflow Integration:**
+1. CI/CD captures failure log
+2. `mem sig --tool=npm --file=log.txt` extracts sig_sha
+3. `mem sig explain --sig-sha=<sha>` finds past solutions
+4. If found → apply solution, skip manual debugging
+5. If not found → fall back to M3.7.4 context endpoint (hybrid search)
+
+---
+
 ### M3.7.8 Implementation Plan
 
 **Files to create:**