claude-mem Plugin

Knowledge base produces nothing; pending_messages piles up

Symptom: the observations table has 0 rows (no knowledge extracted over many days), pending_messages piles up all in pending state, sdk_sessions has no completed records, and worker_port is all None.

Cause: the worker's model channel went offline (e.g. claude-sonnet-4-5 returning 503), the SDK subprocess kept crashing, and the backlog was mistaken for "message queue garbage" and wiped in one click — permanently losing the raw knowledge material.

Fix:

1. Confirm pipeline status (mandatory before cleanup): observations at 0 means the pipeline is broken, not a "time to clean up" signal; a full pending backlog is an anomaly — check the worker before deleting
2. Change the model config: edit ~/.claude-mem/settings.json and switch the model to a currently available stable version

{
  "CLAUDE_MEM_MODEL": "claude-haiku-4-5-20251001"
}

3. Restart the worker: delete the old PID file rm ~/.claude-mem/worker.pid; the next hook trigger restarts it with the new config
4. Safe cleanup: only delete completed/failed messages — never delete pending messages

# Python safe-cleanup example
cur.execute("DELETE FROM pending_messages WHERE status IN ('completed', 'failed')")
conn.commit()

Table cheat sheet:

• pending_messages: the knowledge-extraction input queue (raw material) — don't delete it as garbage
• observations: extracted knowledge points (output); 0 means the pipeline is broken
• sdk_sessions: subprocess session state; all-None worker_port is an anomaly

On Windows, add sys.stdout.reconfigure(encoding='utf-8') when running Python, or Chinese text throws a GBK error.

Claude Code command hangs with no return — worker zombie

Symptom: after typing a command the terminal doesn't error but returns nothing for a long time, and Claude Code gets slower. curl http://127.0.0.1:37777/api/health connects at TCP but HTTP never returns; the port is listening but its PID process is gone.

Cause: after upgrading claude-mem, the old worker hung dead; port 37777 stays occupied but the process is dead, so the new worker misjudges "port in use" and keeps failing, and the hook times out on every tool call, slowing the whole CLI.

Detect:

curl -m 8 -sv http://127.0.0.1:37777/api/health
# TCP connects but HTTP doesn't return = zombie

Fix:

1. Clean up the leftover process and port

# PowerShell: find the PID using the port
Get-NetTCPConnection -LocalPort 37777 | Select-Object OwningProcess
# Kill the process
Stop-Process -Id <PID> -Force

If Stop-Process says the process doesn't exist, just end all leftover node.exe and python.exe processes in Task Manager.

2. Restart the worker from the correct directory

# Correct: the marketplaces directory
cd ~/.claude/plugins/marketplaces/thedotmack
npm run worker:status
npm run worker:restart

# Wrong: do not go into cache/, it has no worker script

3. Verify the fix

curl -m 5 -sv http://127.0.0.1:37777/api/health
# Normal: {"status":"ok","initialized":true,"mcpReady":true}

Two directories to distinguish:

• ~/.claude/plugins/marketplaces/thedotmack: plugin main dir, has the worker script
• ~/.claude/plugins/cache/thedotmack/claude-mem/<version>/: runtime dependency cache, no worker script

Prevention: when Claude Code slows down, check the worker first — don't blame the API or model; after upgrading claude-mem, proactively verify the health endpoint.