Troubleshooting

Stack will not start

Check the basics:

• If you installed the desktop app, confirm Agent Brain is running and its embedded services are healthy
• If you are running the source or Compose stack, confirm Docker is running
• Enough memory is available
• At least 8 GB RAM is recommended

Then:

1. Open the Agent Brain dashboard.
2. Click Start Stack.
3. If a service stays red, check that service's logs.

MCP tools do not appear

Confirm the URL in your agent configuration is exactly:

http://localhost:3100/mcp

After updating configuration:

1. Restart the client.
2. Run /mcp if the client supports it.
3. Confirm the tool list refreshes.

REST calls fail

Check the brain-engine health endpoint:

curl http://localhost:9090/health

If it fails:

• Open the Agent Brain dashboard
• Confirm all stack services are green

First recall is slow

This is usually expected:

• The first embedding request warms up the local model
• Later calls are faster once the model is loaded

Ollama models are missing

Open the Agent Brain dashboard, navigate to Settings → Models, and trigger a model pull from there.

Cache misses too often

Check the configured similarity threshold.

• Very high thresholds improve precision
• Very high thresholds also reduce cache hits
• Start from the documented default and tune from there

Need help?

Join the community on Discord or email support@agentsoftware.dev.