memstack-skill-loader 4.10.0__tar.gz → 4.11.0__tar.gz

{memstack_skill_loader-4.10.0/src/memstack_skill_loader.egg-info → memstack_skill_loader-4.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memstack-skill-loader
-Version: 4.10.0
+Version: 4.11.0
 Summary: MCP server that vector-indexes MemStack Pro skills for on-demand loading
 Requires-Python: >=3.10
 Requires-Dist: mcp>=1.0.0

{memstack_skill_loader-4.10.0 → memstack_skill_loader-4.11.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "memstack-skill-loader"
-version = "4.10.0"
+version = "4.11.0"
 description = "MCP server that vector-indexes MemStack Pro skills for on-demand loading"
 requires-python = ">=3.10"
 dependencies = [
@@ -23,4 +23,4 @@ memstack-index = "memstack_skill_loader.indexer:main"
 where = ["src"]
 
 [tool.setuptools.package-data]
-memstack_skill_loader = ["dashboard.html"]
+memstack_skill_loader = ["dashboard.html", "skill_descriptions.json"]

{memstack_skill_loader-4.10.0 → memstack_skill_loader-4.11.0}/src/memstack_skill_loader/__init__.py

@@ -1,3 +1,3 @@
 """MemStack Skill Loader — MCP server for semantic skill search."""
 
-__version__ = "4.10.0"
+__version__ = "4.11.0"

{memstack_skill_loader-4.10.0 → memstack_skill_loader-4.11.0}/src/memstack_skill_loader/agent_runner.py

@@ -156,6 +156,35 @@ SYSTEM_PROMPTS = {
         "or update a .env.example file with the variable name and a placeholder value.\n"
         "- Do NOT run git add, git commit, or any git commands. Only make file changes."
     ),
+    "advisor": (
+        "You are an Advisor agent. You are called in ONLY when a Builder agent has failed "
+        "three consecutive review cycles on the SAME subtask. The approach being used is not "
+        "working and will not start working by trying harder — it needs to change.\n\n"
+        "You receive:\n"
+        "- The original subtask specification.\n"
+        "- The full history of Builder attempts and the Reviewer's REVISE feedback for each.\n\n"
+        "Your job:\n"
+        "1. DIAGNOSE the root cause. Identify the single recurring reason the attempts keep "
+        "failing review — look for the pattern across all attempts, not just the last one.\n"
+        "2. PRESCRIBE a DIFFERENT fundamental approach. It MUST be materially different from "
+        "what has already been tried — a different file, a different mechanism, a different "
+        "sequence, or a different technique. Do NOT restate, rephrase, or lightly tweak the "
+        "approach that already failed.\n\n"
+        "Hard rules:\n"
+        "- Do NOT use tools. Reason only from the text provided.\n"
+        "- Do NOT repeat the failed approach. If your recommendation resembles what was already "
+        "tried, it is wrong — find another angle.\n"
+        "- Be concrete and file-specific. The Builder will act on this directly.\n"
+        "- Be concise. This output is injected into the Builder's next prompt.\n\n"
+        "Output EXACTLY this structure:\n"
+        "ROOT CAUSE: <one or two sentences naming why every attempt failed>\n"
+        "DIFFERENT APPROACH: <the new approach, explicitly different from what failed>\n"
+        "CONCRETE STEPS:\n"
+        "- <step 1>\n"
+        "- <step 2>\n"
+        "- <step 3 (add more only if needed)>\n"
+        "AVOID: <the specific thing the Builder must stop doing>"
+    ),
     "reviewer": (
         "You are a Reviewer agent. You evaluate the Builder's changes against the original task "
         "specification using a structured 4-perspective review.\n\n"
@@ -1016,6 +1045,119 @@ def _invoke_api_agent(name: str, prompt: str, system_prompt: str,
     return output, total_input_tokens, output_tokens
 
 
+# ---------------------------------------------------------------------------
+# Advisor consult (direct API — no file tools; fires after 3 REVISE strikes)
+# ---------------------------------------------------------------------------
+
+def _consult_advisor(session: "Session", spec: str, attempts_history: str,
+                     log_path: Optional[Path] = None, model: str = "",
+                     display_name: str = "Advisor") -> str:
+    """Consult the Advisor after 3 consecutive Reviewer-REVISE strikes on one subtask.
+
+    Runs via the direct Anthropic API (_invoke_api_agent) — no file tools. Returns a
+    formatted intervention block to fold into the next Builder prompt, or "" on any
+    failure so the caller degrades gracefully to normal revision. Advisor token usage
+    is written to advisor.log only; it is intentionally NOT tracked in session.agents.
+    """
+    advisor_input = (
+        f"Subtask specification:\n{spec}\n\n"
+        "The Builder has now failed three consecutive review cycles on this subtask. "
+        "Here is the full history of attempts and the Reviewer's REVISE feedback:\n\n"
+        f"{attempts_history}\n\n"
+        "Diagnose the recurring root cause and prescribe a DIFFERENT fundamental approach."
+    )
+    try:
+        advisor_output, _a_in, _a_out = _invoke_api_agent(
+            "advisor", advisor_input,
+            system_prompt=SYSTEM_PROMPTS["advisor"],
+            log_path=log_path,
+            timeout=session.timeout,
+            model=model,
+            session_id=session.session_id,
+            working_dir=session.working_dir,
+            display_name=display_name,
+        )
+    except Exception as exc:
+        session.add_message("system", "all", f"Advisor consult failed ({exc}); continuing with normal revision")
+        return ""
+    if not (advisor_output or "").strip():
+        return ""
+    # Decision 3: post under the already-registered "system" role, not a new author.
+    session.add_message("system", "builder", advisor_output)
+    return (
+        "=== ADVISOR INTERVENTION (after 3 failed attempts) ===\n"
+        "The previous approach has failed repeatedly. Do NOT repeat it. "
+        "Follow this alternative approach instead:\n"
+        f"{advisor_output}\n"
+        "=== END ADVISOR INTERVENTION ==="
+    )
+
+
+# ---------------------------------------------------------------------------
+# Failed-approaches memory (best-effort; never interrupts a run)
+# ---------------------------------------------------------------------------
+
+_FA_STORE_SLICE = 1200   # max chars persisted per approach / feedback
+_FA_SHOW_SLICE = 500     # max chars shown per field in the read-back block
+_FA_TOPK = 3
+
+
+def _record_failed_approach(session: "Session", task_text: str,
+                            title: Optional[str], spec: Optional[str],
+                            builder_output: str, reviewer_output: str,
+                            iteration: int) -> None:
+    """Persist one Reviewer-REVISE failure. Best-effort; never raises."""
+    try:
+        from .memory_db import record_failed_approach
+        record_failed_approach(
+            project_dir=session.working_dir,
+            task_text=task_text or "",
+            approach_summary=(builder_output or "")[:_FA_STORE_SLICE],
+            reviewer_feedback=(reviewer_output or "")[:_FA_STORE_SLICE],
+            iteration=iteration,
+            subtask_title=title,
+            subtask_spec=spec,
+            session_id=session.session_id,
+        )
+    except Exception as exc:
+        print(f"[agent-runner] record_failed_approach failed: {exc}", file=sys.stderr)
+
+
+def _failed_approaches_block(session: "Session", task_text: str,
+                             title: Optional[str] = None,
+                             spec: Optional[str] = None) -> str:
+    """Return a 'previously failed approaches' block, or '' if none / on error."""
+    try:
+        from .memory_db import query_failed_approaches
+        key = " ".join(p for p in (task_text, title, spec) if p)
+        rows = query_failed_approaches(
+            key, project_dir=session.working_dir, top_k=_FA_TOPK
+        )
+        if not rows:
+            return ""
+        lines = [
+            "=== PREVIOUSLY FAILED APPROACHES ON SIMILAR TASKS ===",
+            "These were tried on similar work and REJECTED by the reviewer. "
+            "Do NOT repeat them; learn from why they failed.",
+            "",
+        ]
+        for i, r in enumerate(rows, 1):
+            t = r.get("subtask_title") or "(whole task)"
+            lines.append(f"[{i}] (attempt {r.get('iteration')}) {t}")
+            lines.append(
+                f"    Approach tried: {(r.get('approach_summary') or '')[:_FA_SHOW_SLICE]}"
+            )
+            lines.append(
+                f"    Why it failed: {(r.get('reviewer_feedback') or '')[:_FA_SHOW_SLICE]}"
+            )
+            lines.append("")
+        lines.append("=== END PREVIOUSLY FAILED APPROACHES ===")
+        return "\n".join(lines)
+    except Exception as exc:
+        print(f"[agent-runner] failed_approaches lookup failed: {exc}", file=sys.stderr)
+        return ""
+
+
 # ---------------------------------------------------------------------------
 # CC subprocess invocation (Builder — needs file tools)
 # ---------------------------------------------------------------------------
@@ -1532,6 +1674,9 @@ def _orchestrate(session: Session) -> None:
                 session.add_message("system", "all", f"Starting subtask {idx} of {len(subtasks)}: {title}")
                 builder_input = spec
                 subtask_passed = False
+                fail_streak = 0          # consecutive Reviewer-REVISE strikes on THIS subtask
+                advisor_used = False     # cap: at most one Advisor consult per subtask
+                attempts_history: list[str] = []
 
                 for iteration in range(1, MAX_ITERATIONS + 1):
                     if session.status == "stopped":
@@ -1551,9 +1696,15 @@ def _orchestrate(session: Session) -> None:
                     session.agents["builder"]["last_output"] = ""
                     session._save_state()
 
+                    fa_block = ""
+                    if iteration == 1:
+                        fa_block = _failed_approaches_block(
+                            session, session.task, title, spec
+                        )
                     builder_prompt = (
                         SYSTEM_PROMPTS["builder"].format(working_dir=session.working_dir)
                         + "\n\n" + context
+                        + (("\n\n" + fa_block) if fa_block else "")
                         + f"\n\nOriginal task:\n{session.task}"
                         + (f"\n\nAdditional context from user:\n{session.context}" if session.context else "")
                         + f"\n\nBuild specification:\n{builder_input}"
@@ -1741,10 +1892,37 @@ def _orchestrate(session: Session) -> None:
                         session.add_message("system", "all", f"Subtask {idx} of {len(subtasks)} approved: {title}")
                         break
 
+                    # Reviewer requested changes (REVISE) — a retryable strike. Hard-fails
+                    # never reach here; they break out of the iteration loop above.
+                    fail_streak += 1
+                    attempts_history.append(
+                        f"--- Attempt {iteration} ---\n"
+                        f"Builder did:\n{(builder_output or '')[:1500]}\n"
+                        f"Reviewer REVISE feedback:\n{(reviewer_output or '')[:1500]}"
+                    )
+                    _record_failed_approach(
+                        session, session.task, title, spec,
+                        builder_output, reviewer_output, iteration,
+                    )
+                    advisor_block = ""
+                    if fail_streak >= 3 and not advisor_used:
+                        advisor_used = True
+                        session.add_message(
+                            "system", "all",
+                            f"Subtask {idx} of {len(subtasks)}: Builder stuck after "
+                            f"{fail_streak} attempts — consulting Advisor for a new approach",
+                        )
+                        advisor_block = _consult_advisor(
+                            session, spec, "\n\n".join(attempts_history),
+                            log_path=session_log_dir / "advisor.log",
+                            model=session.models.get("advisor", ""),
+                            display_name=display_names.get("advisor", "Advisor"),
+                        )
                     builder_input = (
                         f"The reviewer requested changes:\n{reviewer_output}\n\n"
                         f"Original subtask specification:\n{spec}\n\n"
-                        "Please address the reviewer's feedback."
+                        + (advisor_block + "\n\n" if advisor_block else "")
+                        + "Please address the reviewer's feedback."
                     )
                 else:
                     if not subtask_passed:
@@ -1826,6 +2004,9 @@ def _orchestrate(session: Session) -> None:
 
         # Step 2-3: Builder/Reviewer loop
         builder_input = manager_output
+        fail_streak = 0          # consecutive Reviewer-REVISE strikes on this task
+        advisor_used = False     # cap: at most one Advisor consult per task
+        attempts_history: list[str] = []
 
         for iteration in range(1, MAX_ITERATIONS + 1):
             if session.status == "stopped":
@@ -1845,9 +2026,13 @@ def _orchestrate(session: Session) -> None:
             session.agents["builder"]["last_output"] = ""
             session._save_state()
 
+            fa_block = ""
+            if iteration == 1:
+                fa_block = _failed_approaches_block(session, session.task)
             builder_prompt = (
                 SYSTEM_PROMPTS["builder"].format(working_dir=session.working_dir)
                 + "\n\n" + context
+                + (("\n\n" + fa_block) if fa_block else "")
                 + f"\n\nOriginal task:\n{session.task}"
                 + (f"\n\nAdditional context from user:\n{session.context}" if session.context else "")
                 + f"\n\nBuild specification:\n{builder_input}"
@@ -2088,11 +2273,37 @@ def _orchestrate(session: Session) -> None:
                 session._save_state()
                 return
 
-            # Changes requested — feed back to builder
+            # Changes requested — feed back to builder. Retryable REVISE strike;
+            # hard-fails return out above and never reach here.
+            fail_streak += 1
+            attempts_history.append(
+                f"--- Attempt {iteration} ---\n"
+                f"Builder did:\n{(builder_output or '')[:1500]}\n"
+                f"Reviewer REVISE feedback:\n{(reviewer_output or '')[:1500]}"
+            )
+            _record_failed_approach(
+                session, session.task, None, None,
+                builder_output, reviewer_output, iteration,
+            )
+            advisor_block = ""
+            if fail_streak >= 3 and not advisor_used:
+                advisor_used = True
+                session.add_message(
+                    "system", "all",
+                    f"Builder stuck after {fail_streak} attempts — "
+                    "consulting Advisor for a new approach",
+                )
+                advisor_block = _consult_advisor(
+                    session, manager_output, "\n\n".join(attempts_history),
+                    log_path=session_log_dir / "advisor.log",
+                    model=session.models.get("advisor", ""),
+                    display_name=display_names.get("advisor", "Advisor"),
+                )
             builder_input = (
                 f"The reviewer requested changes:\n{reviewer_output}\n\n"
                 f"Original manager specification:\n{manager_output}\n\n"
-                "Please address the reviewer's feedback."
+                + (advisor_block + "\n\n" if advisor_block else "")
+                + "Please address the reviewer's feedback."
             )
 
         session.status = "completed"

{memstack_skill_loader-4.10.0 → memstack_skill_loader-4.11.0}/src/memstack_skill_loader/dashboard.html

@@ -3599,7 +3599,7 @@ async function resetAgentUI() {
   // Restore working directory from localStorage (user likely wants same project)
   const cachedWd = localStorage.getItem('memstack-last-workdir');
   const wdInput = document.getElementById('agent-workdir-input');
-  if (cachedWd) { wdInput.value = cachedWd; fetchMcpServers(cachedWd); fetchBranches(cachedWd); fetchAgentWorkflow(cachedWd); }
+  if (cachedWd) { wdInput.value = cachedWd; refreshWorkdir(cachedWd); }
 }
 
 async function startAgentTask() {
@@ -3636,12 +3636,16 @@ async function startAgentTask() {
         await fetchBranches(workDir);
       }
     }
+    // Repopulate the branch dropdown from the ACTUAL working dir on every run
+    // start (not only the git-init path above), so the options, pre-selected
+    // branch, and dataset.currentBranch reflect this repo — never a stale
+    // dropdown left over from a previously-loaded directory.
+    if (workDir) await fetchBranches(workDir);
     const branchSel = document.getElementById('agent-branch-select');
     const branchRow = document.getElementById('agent-branch-row');
     const selectedBranch = (branchRow && branchRow.style.display !== 'none' && branchSel && branchSel.value) ? branchSel.value : '';
     if (selectedBranch && workDir) {
-      const curOpt = branchSel.querySelector('option[selected]');
-      const currentBranch = curOpt ? curOpt.value : '';
+      const currentBranch = branchSel.dataset.currentBranch || '';
       if (selectedBranch !== currentBranch) {
         btn.textContent = 'Checking out branch...';
         const coRes = await fetch('/api/git-checkout', {method:'POST', headers: AUTH_HEADERS, body: JSON.stringify({workdir: workDir, branch: selectedBranch})});
@@ -3720,9 +3724,17 @@ async function loadAgentMonitor() {
     wdInput._mcpBound = true;
     wdInput.addEventListener('blur', () => {
       const wd = wdInput.value.trim();
-      fetchMcpServers(wd);
-      fetchBranches(wd);
-      fetchAgentWorkflow(wd);
+      refreshWorkdir(wd);
+    });
+    // Also refresh when the user types/pastes a new path (debounced), so the
+    // branch dropdown updates without waiting for the field to lose focus.
+    let _wdInputTimer = null;
+    wdInput.addEventListener('input', () => {
+      clearTimeout(_wdInputTimer);
+      _wdInputTimer = setTimeout(() => {
+        const wd = wdInput.value.trim();
+        refreshWorkdir(wd);
+      }, 400);
     });
   }
   fetchAgentStatus();
@@ -3734,11 +3746,6 @@ async function loadAgentMonitor() {
 }
 
 async function loadLastWorkdir() {
-  function _initWorkdir(path) {
-    fetchMcpServers(path);
-    fetchBranches(path);
-    fetchAgentWorkflow(path);
-  }
   try {
     const input = document.getElementById('agent-workdir-input');
     if (input.value.trim()) return;
@@ -3747,16 +3754,16 @@ async function loadLastWorkdir() {
     if (data.path) {
       input.value = data.path;
       localStorage.setItem('memstack-last-workdir', data.path);
-      _initWorkdir(data.path);
+      refreshWorkdir(data.path);
     } else {
       const cached = localStorage.getItem('memstack-last-workdir');
-      if (cached) { input.value = cached; _initWorkdir(cached); }
+      if (cached) { input.value = cached; refreshWorkdir(cached); }
     }
   } catch(e) {
     const cached = localStorage.getItem('memstack-last-workdir');
     if (cached) {
       const input = document.getElementById('agent-workdir-input');
-      if (!input.value.trim()) { input.value = cached; _initWorkdir(cached); }
+      if (!input.value.trim()) { input.value = cached; refreshWorkdir(cached); }
     }
   }
 }
@@ -3772,6 +3779,12 @@ function updateMcpToolsSummaryLabel() {
   el.textContent = name + ' MCP Tools';
 }
 
+function refreshWorkdir(path) {
+  fetchMcpServers(path);
+  fetchBranches(path);
+  fetchAgentWorkflow(path);
+}
+
 async function fetchMcpServers(workdir) {
   const listEl = document.getElementById('mcp-tools-list');
   const emptyEl = document.getElementById('mcp-tools-empty');
@@ -3953,9 +3966,9 @@ async function fetchBranches(workdir) {
   if (!workdir) { row.style.display = 'none'; sel.innerHTML = ''; return; }
   try {
     const res = await fetch('/api/git-branches?workdir=' + encodeURIComponent(workdir), {headers: AUTH_GET});
-    if (!res.ok) { row.style.display = 'none'; return; }
+    if (!res.ok) { sel.innerHTML = ''; row.style.display = 'none'; return; }
     const d = await res.json();
-    if (!d.branches || !d.branches.length) { row.style.display = 'none'; return; }
+    if (!d.branches || !d.branches.length) { sel.innerHTML = ''; row.style.display = 'none'; return; }
     sel.innerHTML = '';
     for (const b of d.branches) {
       const opt = document.createElement('option');
@@ -3963,8 +3976,14 @@ async function fetchBranches(workdir) {
       if (b === d.current) opt.selected = true;
       sel.appendChild(opt);
     }
+    // Pre-select the repo's actual current branch and record it so the run
+    // path can read the selection reliably (branchSel.value) and compare it
+    // against the true current branch (dataset), not a [selected] attribute
+    // that opt.selected = true never sets.
+    if (d.current) sel.value = d.current;
+    sel.dataset.currentBranch = d.current || '';
     row.style.display = 'block';
-  } catch(e) { row.style.display = 'none'; }
+  } catch(e) { sel.innerHTML = ''; row.style.display = 'none'; }
 }
 
 async function fetchAgentWorkflow(workdir) {
@@ -4317,7 +4336,7 @@ function closeDirBrowser() {
 function selectDirBrowser() {
   document.getElementById('agent-workdir-input').value = dirBrowserCurrentPath;
   closeDirBrowser();
-  fetchMcpServers(dirBrowserCurrentPath);
+  refreshWorkdir(dirBrowserCurrentPath);
 }
 
 function dirBrowserBack() {

{memstack_skill_loader-4.10.0 → memstack_skill_loader-4.11.0}/src/memstack_skill_loader/memory_db.py

@@ -11,9 +11,22 @@ DB_PATH = Path.home() / ".memstack" / "memory.db"
 SCHEMA_VERSION = 1
 
 
+def _resolve_db_path() -> Path:
+    """Resolve the memory DB path at call time.
+
+    Honors the ``MEMSTACK_DB_PATH`` environment override (used by tests to
+    redirect writes away from the real ~/.memstack/memory.db); otherwise falls
+    back to the module-level ``DB_PATH`` default. Behavior is identical to the
+    old hardcoded path when the env var is absent.
+    """
+    override = os.environ.get("MEMSTACK_DB_PATH")
+    return Path(override) if override else DB_PATH
+
+
 def _get_conn() -> sqlite3.Connection:
-    DB_PATH.parent.mkdir(parents=True, exist_ok=True)
-    conn = sqlite3.connect(str(DB_PATH), timeout=5)
+    db_path = _resolve_db_path()
+    db_path.parent.mkdir(parents=True, exist_ok=True)
+    conn = sqlite3.connect(str(db_path), timeout=5)
     conn.row_factory = sqlite3.Row
     conn.execute("PRAGMA journal_mode=WAL")
     _init_tables(conn)
@@ -124,6 +137,36 @@ def _init_tables(conn: sqlite3.Connection) -> None:
         """
     )
 
+    cur.execute(
+        """
+        CREATE TABLE IF NOT EXISTS failed_approaches (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            project_dir TEXT NOT NULL,
+            session_id TEXT,
+            task_text TEXT NOT NULL,
+            subtask_title TEXT,
+            subtask_spec TEXT,
+            approach_summary TEXT NOT NULL,
+            reviewer_feedback TEXT NOT NULL,
+            iteration INTEGER,
+            created_at TEXT NOT NULL DEFAULT (datetime('now'))
+        )
+        """
+    )
+    cur.execute(
+        "CREATE INDEX IF NOT EXISTS idx_failed_project "
+        "ON failed_approaches(project_dir)"
+    )
+    cur.execute(
+        """
+        CREATE VIRTUAL TABLE IF NOT EXISTS failed_approaches_fts USING fts5(
+            match_text,
+            source_id,
+            project_dir
+        )
+        """
+    )
+
     conn.commit()
 
 
@@ -228,23 +271,31 @@ def insert_lesson(
     project_dir: str | None = None,
     global_: bool = False,
     stack_tags: list[str] | None = None,
+    *,
+    created_at: str | None = None,
 ) -> int | None:
     try:
         conn = _get_conn()
         try:
             pdir = None if global_ else project_dir
-            cur = conn.execute(
-                "INSERT INTO procedural_memory "
-                "(project_dir, category, title, content, stack_tags) "
-                "VALUES (?, ?, ?, ?, ?)",
-                (
-                    pdir,
-                    category,
-                    title,
-                    content,
-                    json.dumps(stack_tags) if stack_tags else None,
-                ),
-            )
+            tags_json = json.dumps(stack_tags) if stack_tags else None
+            if created_at:
+                # Caller-supplied timestamp: bind it (never string-format it in).
+                cur = conn.execute(
+                    "INSERT INTO procedural_memory "
+                    "(project_dir, category, title, content, stack_tags, created_at) "
+                    "VALUES (?, ?, ?, ?, ?, ?)",
+                    (pdir, category, title, content, tags_json, created_at),
+                )
+            else:
+                # Default path: omit created_at so the column DEFAULT
+                # (datetime('now')) applies. Byte-identical to prior behavior.
+                cur = conn.execute(
+                    "INSERT INTO procedural_memory "
+                    "(project_dir, category, title, content, stack_tags) "
+                    "VALUES (?, ?, ?, ?, ?)",
+                    (pdir, category, title, content, tags_json),
+                )
             row_id = cur.lastrowid
             _index_fts(conn, "procedural_memory", row_id,
                         f"{title} {content}", pdir or "")
@@ -298,6 +349,98 @@ def insert_fact(
         return None
 
 
+# ---------------------------------------------------------------------------
+# Failed-approaches memory
+# ---------------------------------------------------------------------------
+
+def record_failed_approach(
+    project_dir: str,
+    task_text: str,
+    approach_summary: str,
+    reviewer_feedback: str,
+    iteration: int,
+    subtask_title: str | None = None,
+    subtask_spec: str | None = None,
+    session_id: str | None = None,
+) -> int | None:
+    try:
+        conn = _get_conn()
+        try:
+            cur = conn.execute(
+                "INSERT INTO failed_approaches "
+                "(project_dir, session_id, task_text, subtask_title, subtask_spec, "
+                "approach_summary, reviewer_feedback, iteration) "
+                "VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
+                (project_dir, session_id, task_text, subtask_title, subtask_spec,
+                 approach_summary, reviewer_feedback, iteration),
+            )
+            row_id = cur.lastrowid
+            match_text = " ".join(
+                p for p in (task_text, subtask_title, subtask_spec) if p
+            )
+            conn.execute(
+                "INSERT INTO failed_approaches_fts (match_text, source_id, project_dir) "
+                "VALUES (?, ?, ?)",
+                (match_text, str(row_id), project_dir),
+            )
+            conn.commit()
+            return row_id
+        finally:
+            conn.close()
+    except Exception as exc:
+        print(f"[memstack-memory] record_failed_approach failed: {exc}", file=sys.stderr)
+        return None
+
+
+def _fts_or_query(text: str) -> str:
+    """Free text -> safe FTS5 OR-query of unique alphanumeric tokens.
+
+    Strips punctuation (which FTS5 would treat as query syntax and raise on),
+    drops tokens shorter than 3 chars, dedupes, and caps length. Returns "" if
+    no usable tokens remain so callers can skip the MATCH entirely.
+    """
+    import re
+    tokens = re.findall(r"[A-Za-z0-9]+", (text or "").lower())
+    seen: list[str] = []
+    for t in tokens:
+        if len(t) >= 3 and t not in seen:
+            seen.append(t)
+    return " OR ".join(seen[:40])
+
+
+def query_failed_approaches(
+    task_text: str, project_dir: str | None = None, top_k: int = 3
+) -> list[dict]:
+    if top_k > 50:
+        top_k = 50
+    match = _fts_or_query(task_text)
+    if not match:
+        return []
+    try:
+        conn = _get_conn()
+        try:
+            sql = (
+                "SELECT f.id, f.subtask_title, f.subtask_spec, f.approach_summary, "
+                "f.reviewer_feedback, f.iteration, f.created_at "
+                "FROM failed_approaches_fts fa "
+                "JOIN failed_approaches f ON f.id = CAST(fa.source_id AS INTEGER) "
+                "WHERE failed_approaches_fts MATCH ?"
+            )
+            params: list = [match]
+            if project_dir:
+                sql += " AND fa.project_dir = ?"
+                params.append(project_dir)
+            sql += " ORDER BY fa.rank LIMIT ?"
+            params.append(top_k)
+            rows = conn.execute(sql, params).fetchall()
+            return [dict(r) for r in rows]
+        finally:
+            conn.close()
+    except Exception as exc:
+        print(f"[memstack-memory] query_failed_approaches failed: {exc}", file=sys.stderr)
+        return []
+
+
 # ---------------------------------------------------------------------------
 # Query functions
 # ---------------------------------------------------------------------------
@@ -307,7 +450,9 @@ def search_memory(
 ) -> list[dict]:
     if limit > 500:
         limit = 500
-    query = f'"{query}"'
+    match = _fts_or_query(query)
+    if not match:
+        return []
     try:
         conn = _get_conn()
         try:
@@ -315,7 +460,7 @@ def search_memory(
                 "SELECT content, source_table, source_id, project_dir, "
                 "rank FROM memory_fts WHERE memory_fts MATCH ?"
             )
-            params: list = [query]
+            params: list = [match]
             if project_dir:
                 sql += " AND project_dir = ?"
                 params.append(project_dir)