63 lines
2.5 KiB
Markdown
63 lines
2.5 KiB
Markdown
---
|
|
name: bmad-memtrace-recovery
|
|
description: 'Memtrace MCP server recovery workflow. Use when the adapter emits MEMTRACE_MCP_ERROR_TIMEOUT (connection failure or timeout) to autonomously restart the server.'
|
|
---
|
|
|
|
# Memtrace MCP Server Recovery
|
|
|
|
## When to Use
|
|
|
|
Activate this skill when:
|
|
- The `memtrace-adapter.mjs` script exits with code 1 AND emits `MEMTRACE_MCP_ERROR_TIMEOUT` on STDOUT
|
|
- An MCP tool call fails with a connection/timeout error
|
|
- The Memtrace MCP server is unresponsive or hung
|
|
|
|
## Recovery Protocol
|
|
|
|
### Step 1: Run the Restart Script
|
|
|
|
Execute from the project root:
|
|
```bash
|
|
npm run memtrace:restart
|
|
```
|
|
|
|
**DO NOT** use raw OS commands (`taskkill`, `kill -9`, `pkill`). These are prohibited. Only `npm run memtrace:restart` is permitted.
|
|
|
|
### Step 2: Evaluate Result
|
|
|
|
**If exit code 0 (SUCCESS):**
|
|
- The stale processes were terminated
|
|
- A fresh memtrace instance is verified operational
|
|
- Proceed to Step 3
|
|
|
|
**If exit code 1 (FAILURE):**
|
|
- The server could not be recovered
|
|
- Halt the current task immediately
|
|
- Notify the Human Developer: "Memtrace MCP server recovery failed. Manual intervention required."
|
|
- Check that the file `.agents/skills/bmad-memtrace-fallback/SKILL.md` exists. If it does, load the `bmad-memtrace-fallback` skill and follow its Permission Protocol (Steps 1-3: Halt → Wait → Permission/Abandon). If the file does not exist, the fallback skill is missing — notify the developer: "Fallback skill file not found. Cannot proceed with legacy mode without the approved protocol."
|
|
|
|
### Step 3: Verify Index Freshness
|
|
|
|
After successful restart, verify the index is up-to-date. Run from the project root:
|
|
```bash
|
|
node _bmad/scripts/memtrace/memtrace-adapter.mjs --query list_repos
|
|
```
|
|
|
|
**If the adapter fails (exit code 1):** The restart may not have been sufficient. Halt and notify: "Memtrace server responded to initialize but adapter query failed. Manual investigation needed."
|
|
|
|
If the index is stale, re-index from the project root:
|
|
```bash
|
|
memtrace index --path .
|
|
```
|
|
Ensure you are in the project root directory before running this command (the path `.` is relative to CWD).
|
|
|
|
### Step 4: Resume Task
|
|
|
|
Once the server is verified online and the index is fresh, resume the original task from the last checkpoint. Do NOT restart the entire workflow — continue from where the timeout occurred.
|
|
|
|
## Confinement Rules
|
|
|
|
- **NEVER** use `taskkill`, `kill`, `pkill`, `tasklist`, or any raw OS process command
|
|
- **ALWAYS** use `npm run memtrace:restart` as the sole recovery interface
|
|
- **ALWAYS** halt and escalate to manual intervention if recovery fails
|