.agents/skills/memory-debug/SKILL.md

name	description	user_invocable	arg_hint	builtin
memory-debug	Diagnose and fix Signet memory issues (daemon health, embeddings, search quality, and data integrity).	true	[symptom or query]	true

/memory-debug

Debug the Signet memory system when recall quality is poor, memories are missing, or remember/recall commands fail.

Use this skill when the user asks things like:

• "memory is broken"
• "recall isn't finding anything"
• "remember didn't save"
• "why are results low quality?"

syntax

/memory-debug
/memory-debug recall is empty
/memory-debug embeddings failing

workflow

Run these checks in order and stop when you find the root cause.

1) verify daemon + config

signet status
curl -s http://localhost:3850/health

If daemon is down or unresponsive, restart it:

# preferred: CLI commands
signet start          # start if not running
signet restart        # stop + start (graceful)

# if CLI restart doesn't work, kill and restart manually
signet stop
pkill -f "signet.*daemon"   # force kill if stop hangs
signet start

# if installed as a system service (launchd on macOS, systemd on Linux)
# macOS:
launchctl kickstart -k gui/$(id -u)/ai.signet.daemon
# Linux:
systemctl --user restart signet-daemon

After restart, confirm daemon is healthy:

signet status
curl -s http://localhost:3850/health

Then verify key files exist:

• ~/.agents/agent.yaml
• ~/.agents/memory/memories.db

2) verify write path (remember)

signet remember "memory-debug smoke test" -t debug,smoke -w claude-code

Expected: success response with embedded: true or a clear fallback message.

If save fails, capture exact CLI error and recommend the fix (daemon restart, permissions, missing config, etc.).

3) verify read path (recall)

signet recall "memory-debug smoke test" -l 5 --json

If no results:

• retry with simpler keyword query
• check search.min_score and search.alpha in ~/.agents/agent.yaml
• confirm the memory was actually written in step 2

4) check embedding health

If memories save but semantic recall is weak:

signet recall "memory-debug smoke test" --json

Inspect whether scores are keyword-heavy and whether embedding appears unavailable.

Then verify embedding provider configuration in ~/.agents/agent.yaml:

• embedding.provider
• embedding.model
• embedding.dimensions

Common fixes:

• provider offline (Ollama/OpenAI unreachable)
• wrong model name
• dimensions mismatch after model change

5) advanced diagnostics

Check daemon logs for hook and memory errors:

signet logs -c hooks
signet logs -c memory

Use direct API checks for deeper issues:

curl -s "http://localhost:3850/api/memory/search?q=debug&limit=5"
curl -s http://localhost:3850/api/status

response format

When reporting back, include:

1. what failed
2. exact command + error
3. likely root cause
4. concrete fix steps
5. verification command to confirm fix

Prefer minimal, reproducible checks over broad speculation.