Troubleshooting. The shortlist.

• ProblemSolution
• "OCTAMEM_API_KEY is not set"
  Add your API key in the host you are using (Claude Desktop: Settings → Extensions → OctaMem; Cursor: Settings → MCP / Tools). For the Python SDK you can export OCTAMEM_API_KEY in your shell; for the JS SDK pass the key to the OctaMem constructor or load it from your own env / config.
• "API key is invalid or expired" / 401
  Generate a new key at platform.octamem.com and update it everywhere the old key was stored.
• Rate limited (429) / too many requests
  Wait and retry. Official SDKs retry with backoff; avoid tight loops calling search or add. If you are on a free or team plan, check usage on the platform dashboard.
• Insufficient balance (402) or wallet errors
  search and add calls consume tokens from your wallet. Add credits or upgrade your plan from platform.octamem.com.
• Storage full / would exceed storage limit
  Free up space (remove old memories in the product, if available) or move to a plan with higher storage. The JavaScript SDK surfaces this as StorageFullError; the Python SDK reports a validation or API error depending on the response.
• "Could not reach OctaMem" / network errors
  Check your internet connection, VPN, firewall, and corporate proxy. OctaMem is a remote API; the default base URL is https://platform.octamem.com.
• Tool not appearing (MCP)
  Restart the host app after installing or editing the MCP config. Confirm the OctaMem MCP server entry points to the correct command / package and that your API key is present in env or config.
• Assistant cannot use tools / permission denied
  Some clients require you to approve MCP tools per session or in settings. Enable OctaMem tools when prompted, or check security and automation settings in your client.
• Memory not persisting
  Verify the API key matches the account where you expect memory to live. For MCP, confirm tools are enabled and try "What OctaMem tools do you have?". For SDKs, call details() and ensure search / add return success without errors.
• JavaScript SDK: fetch is not defined
  Use Node.js 18+ (recommended) for native fetch, or run in an environment that provides fetch (modern browsers, Deno, Bun). Node 16 may need a fetch polyfill.

Still stuck after working through the list? Email [email protected] with a brief reproduction, the API key prefix (not the full key), and any error messages from the client. We’ll get back to you quickly.