// Diagnostic and troubleshooting workflow for agent-memory. Guides users through common install/config/daemon/ingest issues. Requires confirmation before any edits or restarts. Provides verification commands only.
| name | memory-troubleshoot |
| description | Diagnostic and troubleshooting workflow for agent-memory. Guides users through common install/config/daemon/ingest issues. Requires confirmation before any edits or restarts. Provides verification commands only. |
| license | MIT |
| metadata | {"version":"1.0.0","author":"SpillwaveSolutions"} |
Diagnose and resolve common agent-memory issues safely. This skill never runs verification commands automatically and always asks for confirmation before edits or restarts.
Which issue are you seeing?
1. "command not found" for memory-daemon or memory-ingest
2. "connection refused" or cannot query daemon
3. Daemon starts then stops
4. No events captured
5. Summarization not working
6. Other / not sure
Enter selection [1-6]:
1) Command not found
which memory-daemon
which memory-ingest
echo $PATH
2) Connection refused
memory-daemon status
lsof -i :50051
memory-daemon query --endpoint http://[::1]:50051 root
3) Daemon stops immediately
memory-daemon status
tail -50 ~/Library/Logs/memory-daemon/daemon.log
tail -50 ~/.local/state/memory-daemon/daemon.log
4) No events captured
grep -n "memory-ingest" ~/.claude/hooks.yaml
which memory-ingest
memory-daemon status
5) Summarization failing
echo "OPENAI: ${OPENAI_API_KEY:+set}"
echo "ANTHROPIC: ${ANTHROPIC_API_KEY:+set}"
For each fix, ask:
I can apply the following fix:
[describe the change]
Proceed? (yes/no)
Examples:
PATH update
Add ~/.local/bin to PATH in your shell profile
Restart daemon
Stop and restart the daemon:
memory-daemon stop
memory-daemon start
Fix hooks file
Add memory-ingest handler to ~/.claude/hooks.yaml
memory-daemon status
memory-daemon query --endpoint http://[::1]:50051 root
memory-installgrpc_port in config if neededmemory-ingestmemory-ingest is on PATHIf diagnostics do not resolve the issue, recommend:
memory-verify for a full checkmemory-install with a fresh setupBM25 keyword search for agent-memory. Use when asked to "find exact terms", "keyword search", "search for specific function names", "locate exact phrase", or when semantic search returns too many results. Provides fast BM25 full-text search via Tantivy index.
Query past conversations from the agent-memory system. Use when asked to "recall what we discussed", "search conversation history", "find previous session", "what did we talk about last week", or "get context from earlier". Provides tier-aware retrieval with automatic fallback chains, intent-based routing, and full explainability. Includes command-equivalent instructions for search, recent, and context operations.
Agent retrieval policy for intelligent memory search. Use when implementing memory queries to detect capabilities, classify intent, route through optimal layers, and handle fallbacks. Provides tier detection, intent classification, fallback chains, and full explainability for all retrieval operations.
Topic graph exploration for agent-memory. Use when asked to "explore topics", "show related concepts", "what themes have I discussed", "find topic connections", or "discover patterns in conversations". Provides semantic topic extraction with time-decayed importance scoring.
Semantic vector search for agent-memory. Use when asked to "find similar discussions", "semantic search", "find related topics", "what's conceptually related to X", or when keyword search returns poor results. Provides vector similarity search and hybrid BM25+vector fusion.
Wizard-style configuration guidance for a single-agent agent-memory setup. Shows defaults inline, provides a full sample config, and includes a dry-run config check step. Always confirm before creating or editing files.