Skip to content
n3wth docs

Troubleshooting

If r3 is not working as expected, start with the smallest failing step: installation, MCP connection, storage initialization, write, read, then restart. This page covers the common symptoms and fixes.

Installation fails on macOS with a GNU Make error

The embedded Redis dependency compiles from source when a prebuilt binary is not available. This needs GNU Make 4 or later, which is newer than the system default on some macOS versions.

Install a newer make with Homebrew:

Terminal window
brew install make

Confirm the version:

Terminal window
gmake --version

Then relaunch r3:

Terminal window
npx @n3wth/r3
MCP client does not discover r3 tools
  1. Restart the MCP client after editing configuration.
  2. Confirm the config file path matches your client (Claude Desktop, Claude Code, or Cursor).
  3. Verify the JSON contains "command": "npx" and "args": ["@n3wth/r3"].
  4. Check the client’s MCP log for stderr output. Add "DEBUG": "true" to the server’s env for a diagnostic run.
  5. Confirm the configured package is @n3wth/r3, not an unscoped r3 name.

Keep stdout reserved for MCP messages. Disabling quiet mode can let local logging reach stdout and interfere with the transport.

add_memory returns Saved but search finds nothing
  1. Confirm the intelligence mode. Try INTELLIGENCE_MODE=basic to rule out embedding model initialization failures.
  2. Call sync_status to check pending async operations.
  3. Call optimize_cache to refresh the cache and index.
  4. Verify you are querying with the same user_id you used for the write.

Saved can return before async processing finishes. Verify content through retrieval, not through the acknowledgement.

Memories do not persist across restart
  1. Restart from the same working directory. The vector index lives at ./data/vectra-index relative to the launch directory.
  2. Local Redis records have a 30-day TTL. The embedded backend does not configure durable persistence.
  3. Keep an independent copy of anything you cannot lose. Test the write, read, and restart cycle with disposable data first.

See Configuration for storage details.

Redis connection refused

This applies only when REDIS_URL points at an external Redis. Ensure that server is running and reachable from the r3 process.

For the local quickstart, leave REDIS_URL unset so r3 uses the embedded server.

Enhanced-mode tools are missing

extract_entities, get_knowledge_graph, and find_connections only register when INTELLIGENCE_MODE=enhanced (the default).

If they are missing, confirm you have not set INTELLIGENCE_MODE=basic, then check stderr for model download or embedding initialization errors. On failure the server continues in a degraded state and these tools stay hidden.