Skip to main content

Troubleshooting

Common issues and solutions for Tensorheart Memory MCP.

Connection Issues​

"Server not found" or "Failed to connect"​

Symptoms:

  • Claude Desktop shows "Server not found" error
  • Memory tools don't appear in Claude's available tools

Solutions:

  1. Check Configuration File Location

    # macOS
    cat ~/Library/Application\ Support/Claude/claude_desktop_config.json

    # Windows
    type %APPDATA%\Claude\claude_desktop_config.json

    # Linux
    cat ~/.config/Claude/claude_desktop_config.json

    Make sure the file exists and is valid JSON.

  2. Verify Python Path

    which python3
    # Should output: /path/to/python3

    Use this exact path in your config file.

  3. Test Installation

    python3 -m tensorheart_memory_mcp --version

    If this fails, reinstall:

    pip3 install --force-reinstall tensorheart-memory-mcp

  4. Restart Claude Desktop

    • Completely quit Claude Desktop (not just close window)
    • Reopen and check developer tools for errors

"Authentication failed" or 401 errors​

Symptoms:

  • Tools appear but return authentication errors
  • "Invalid API key" messages

Solutions:

  1. Verify API Key

    • Log in to Tensorheart Memory
    • Go to Settings → API Keys
    • Generate a new key if needed
    • Copy the key exactly (no extra spaces)

  2. Check Environment Variable

    echo $MEMORY_API_KEY

    Should output your API key. If empty:

    # Add to ~/.zshrc or ~/.bashrc
    export MEMORY_API_KEY="your-key-here"

    # Reload
    source ~/.zshrc  # or ~/.bashrc

  3. Verify Config File Make sure the key is set correctly:

    {
      "mcpServers": {
        "memory": {
          "command": "python3",
          "args": ["-m", "tensorheart_memory_mcp"],
          "env": {
            "MEMORY_API_KEY": "tmk_your_actual_key_here"
          }
        }
      }
    }

Performance Issues​

Slow query responses​

Symptoms:

  • Memory queries take more than 5 seconds
  • Timeouts when searching memories

Solutions:

  1. Increase Timeout

    {
      "mcpServers": {
        "memory": {
          "env": {
            "MEMORY_TIMEOUT": "60.0"
          }
        }
      }
    }

  2. Use More Specific Queries

    • Instead of: "show me everything"
    • Try: "Python authentication code from last week"

  3. Limit Results

    • Use max_memories parameter to limit results
    • Default is 10, which is usually sufficient

  4. Check Network Connection

    curl -I https://api.tensorheart.com
    # Should return: HTTP/2 200

Document ingestion takes too long​

Symptoms:

  • PDF uploads timeout
  • Large files fail to process

Solutions:

  1. Check File Size

    • Max recommended: 50 MB
    • For larger files, split into sections

  2. Increase Timeout

    {
      "env": {
        "MEMORY_TIMEOUT": "120.0"
      }
    }

  3. Use Smaller Files

    • Extract relevant pages from PDFs
    • Compress images before uploading

Memory Management Issues​

Duplicate memories created​

Symptoms:

  • Same information stored multiple times
  • Similar memories with slight variations

Solutions:

  1. Run Consolidation Ask Claude:

    Run consolidation on my memories with threshold 0.8

  2. Search Before Creating Before saving new information:

    Check if I already have information about [topic]

  3. Update Instead of Create If information exists:

    Update my memory about [topic] with this new information: [details]

Can't find saved memories​

Symptoms:

  • Memories were saved but queries don't return them
  • Search returns no results for known information

Solutions:

  1. Check Space

    • If you saved to a specific space, query that space:
    Search my "work-projects" space for [query]

  2. Use Different Query Terms

    • Try synonyms or related terms
    • Use more context in your query

  3. List Recent Memories

    Show me my recent memories

    This uses the memory://recent resource.

  4. Verify Memory Was Created

    • Check Claude's response when you created it
    • Should say "Saved!" or show success message

Spaces not organizing correctly​

Symptoms:

  • Memories appear in wrong spaces
  • Can't filter by space

Solutions:

  1. Verify Space Names

    List all my spaces

    Check exact spelling and formatting.

  2. Specify Space Explicitly When creating memories:

    Save this to my "project-alpha" space: [information]

  3. Move Memories Update the space for a memory:

    Move memory [id] to space "new-space"

Configuration Issues​

JSON syntax errors​

Symptoms:

  • Claude Desktop won't start after config changes
  • "Invalid configuration" errors

Solutions:

  1. Validate JSON Use a JSON validator:

    python3 -m json.tool < ~/Library/Application\ Support/Claude/claude_desktop_config.json

  2. Common JSON Mistakes

    • Missing commas between entries
    • Trailing comma after last entry
    • Unescaped backslashes in paths (Windows)
    • Smart quotes instead of straight quotes

  3. Use Template Start with the exact template from the Configuration guide.

Environment variables not loading​

Symptoms:

  • API key set in config but still getting auth errors
  • Other env vars not taking effect

Solutions:

  1. Check JSON Structure Env vars must be in env object:

    {
      "mcpServers": {
        "memory": {
          "command": "python3",
          "args": ["-m", "tensorheart_memory_mcp"],
          "env": {
            "MEMORY_API_KEY": "your-key"
          }
        }
      }
    }

  2. System vs Config Env Vars

    • Config file env overrides system environment variables
    • To use system variables, omit env section

  3. Restart Required

    • Changes require complete restart of Claude Desktop
    • Quit entirely and reopen

Advanced Troubleshooting​

Enable debug logging​

For development/testing:

{
  "mcpServers": {
    "memory": {
      "env": {
        "MEMORY_LOG_LEVEL": "DEBUG"
      }
    }
  }
}

Check logs in Claude Desktop developer tools (View → Developer → Developer Tools).

Check server health​

Test the MCP server directly:

# Set API key
export MEMORY_API_KEY="your-key"

# Run server
python3 -m tensorheart_memory_mcp

# Should start without errors
# Press Ctrl+C to stop

Verify API connectivity​

Test the Memory API directly:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.tensorheart.com/v1/memories

Should return JSON response with your memories.

Reset configuration​

If all else fails, start fresh:

  1. Backup current config

    cp ~/Library/Application\ Support/Claude/claude_desktop_config.json ~/claude_config_backup.json

  2. Remove MCP config Edit config file and remove the memory entry.

  3. Restart Claude Desktop Verify it works without MCP.

  4. Re-add MCP config Use the template from Configuration guide.

Getting Help​

If you're still experiencing issues:

  1. Check API Status

  2. Review Recent Changes

    • Did you update Claude Desktop recently?
    • Did you change your API key?
    • Did you modify the config file?

  3. Collect Information When reporting issues, include:

    • Operating system and version
    • Claude Desktop version
    • Python version (python3 --version)
    • tensorheart-memory-mcp version (pip3 show tensorheart-memory-mcp)
    • Relevant error messages from developer tools

  4. Contact Support

    • Email: support@tensorheart.com
    • Include the information above
    • Describe what you were trying to do
    • Include any error messages

Common Error Messages​

"ModuleNotFoundError: No module named 'tensorheart_memory_mcp'"​

Solution: Install or reinstall the package

pip3 install tensorheart-memory-mcp

"FileNotFoundError: [Errno 2] No such file or directory"​

Solution: Check that the Python path in config is correct

which python3

Use the full path in your config.

"JSONDecodeError: Expecting property name enclosed in double quotes"​

Solution: Fix JSON syntax in config file

  • Remove trailing commas
  • Use double quotes (not single quotes)
  • Validate with python3 -m json.tool

"RateLimitError: Too many requests"​

Solution: You've hit API rate limits

  • Wait a few minutes before retrying
  • Reduce frequency of requests
  • Contact support for rate limit increase if needed

"ValueError: Invalid file path"​

Solution: Check file path when using document ingestion

  • Use absolute paths: /Users/name/Documents/file.pdf
  • Ensure file exists and is readable
  • Check file size (max 50 MB recommended)

"MemoryNotFoundError: Memory with id 'xxx' not found"​

Solution: The memory was deleted or ID is incorrect

  • Use query_memories to find the correct memory
  • List recent memories to verify it exists