Troubleshooting Guide

Solutions for common Memo issues.

1. Port Conflicts

Symptom: Memo fails to start with "address already in use" errors.

Solution:

1. Check which process is using the port: lsof -i :8080 (Linux/macOS) or netstat -ano | findstr :8080 (Windows).
2. Kill the conflicting process or change Memo's port in Settings → Remote Access → API Port.
3. If the llama port conflicts, set a fixed port in config.yaml under llama.port.

2. VRAM / GPU Issues

Symptom: Model loads but responses are very slow, or CUDA errors appear in logs.

Solution:

1. Reduce GPU layers in Settings → Model Parameters → GPU Layers. Try 0 for CPU-only.
2. Choose a smaller model from the Model Store (look for lower parameter counts).
3. Close other GPU-intensive applications before running Memo.
4. Ensure CUDA drivers are up to date: nvidia-smi to verify.

3. Llama Server Not Found

Symptom: "llama server not found" or "failed to connect to llama" errors.

Solution:

1. Verify the model file exists at the configured path in config.yaml → llama.model_path.
2. Check that the llama.cpp server binary is in your PATH or alongside the Memo binary.
3. Look for crash logs in ~/.memo/logs/llama.log.
4. Try removing ~/.memo/llama.lock if a previous instance didn't shut down cleanly.

4. Blank Frontend

Symptom: Web UI loads but shows a white screen.

Solution:

1. Open browser developer tools (F12) and check the Console tab for errors.
2. Hard refresh with Ctrl+Shift+R (or Cmd+Shift+R on macOS).
3. Clear browser cache and local storage for the Memo origin.
4. Verify the Flutter web build is not corrupted — reinstall or rebuild if necessary.

5. Memory Retrieval Failures

Symptom: Memo doesn't recall past conversations or facts.

Solution:

1. Ensure memory is enabled in Settings → Memory.
2. Check that memory.auto_embed is true in config.yaml.
3. Verify the embedding model is downloaded: look in ~/.memo/models/ for the configured embedding_model.
4. If the vec0 SQLite extension failed to load, the Go fallback is used — performance may be lower but retrieval should still work.
5. Rebuild the vector index by deleting ~/.memo/memo.db and restarting (conversations will be lost).

6. External Provider Connection Issues

Symptom: "provider connection failed" or timeout errors with external APIs.

Solution:

1. Verify your API key is correct and hasn't expired in Settings → API Providers.
2. Check your internet connection — external providers require network access.
3. Ensure the API base URL is correct (defaults are pre-configured for each provider).
4. Look for proxy or firewall settings that may block outbound HTTPS on port 443.
5. Check the provider's status page for outages.

7. Agent Mode Not Working

Symptom: Agent mode errors or tools don't execute.

Solution:

1. Ensure the agent is enabled in Settings → Orchestra.
2. Verify the workspace directory exists and is writable.
3. Check tool permissions — some tools require explicit opt-in.
4. Agent mode requires a capable model (7B+ parameters recommended). Smaller models may not produce valid tool calls.
5. Look for sandbox errors in ~/.memo/logs/agent.log.