Skip to content

troubleshooting.md

Latest commit

 

History

History
485 lines (363 loc) · 11.6 KB

troubleshooting.md

File metadata and controls

485 lines (363 loc) · 11.6 KB

Troubleshooting & Support

Common issues, solutions, and debugging guidance for the Chat Memory MCP Server.

Common Issues

Installation & Setup Issues

1. "Advanced tool 'X' is not enabled"

Problem: Trying to use advanced tools (tags, groups, import, export) when they're disabled.

Solution:

# Add to your MCP configuration environment:
"MEMCORD_ENABLE_ADVANCED": "true"

# Or check current mode by trying memcord_list_tags
# If it returns an error, advanced tools are disabled

Advanced tools requiring this setting:

  • memcord_tag, memcord_list_tags, memcord_group
  • memcord_import, memcord_merge
  • memcord_export, memcord_share

2. "No memory slot selected"

Problem: Trying to save or read memory without selecting a slot first.

Solution:

# Option A: Create/select a slot explicitly
memcord_name "my_project"
memcord_save "conversation content"

# Option B: Initialize a .memcord binding for the project (one-time setup)
# After this, all operations auto-detect the slot — no memcord_use needed
memcord_init "." "my_project"

All operations (memcord_save, memcord_save_progress, memcord_configure, memcord_read) share the same slot resolution order: explicit argument → active slot → .memcord binding in cwd. If the .memcord file is found and the slot exists, it is also auto-activated for the session.

2. "Memory slot not found"

Problem: Referencing a memory slot that doesn't exist.

Solutions:

  • Check available slots: memcord_list
  • Verify slot name spelling (case-sensitive)
  • Create the slot if needed: memcord_name "slot_name"

3. Server not starting

Problem: MCP server fails to launch.

Troubleshooting steps:

  1. Check Python version: python --version (3.10+ required)
  2. Verify installation: uv run memcord --help
  3. Check file permissions in the project directory
  4. Verify PYTHONPATH environment variable

Common fixes:

# Reinstall dependencies
uv pip install -e .

# Check MCP configuration
claude mcp list
claude mcp get memcord

# Run with debug output
PYTHONPATH=src python -m memcord.server --debug

4. "Command not found: uv"

Problem: uv package manager not installed.

Solution:

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or use pip instead
pip install -e .
uv run memcord

Search & Query Issues

5. "No search results found"

Problem: Search queries return no results despite having relevant content.

Troubleshooting:

  • Check spelling and try different keywords
  • Use broader search terms
  • Try natural language queries: memcord_query "question"
  • Verify content exists: memcord_list

Search tips:

# Try different approaches
memcord_search "database"          # Single term
memcord_search "database OR db"    # Alternative terms  
memcord_search "data*"            # Partial matching
memcord_query "What about databases?" # Natural language

6. "Search is slow"

Problem: Search operations take too long.

Causes & Solutions:

  • Large memory collection: Search index builds on startup
  • First query: Index may need initialization
  • Complex queries: Use simpler terms or add filters

Performance improvements:

# Use tag/group filters to narrow results
memcord_search "meeting" --include-tags "urgent"
memcord_search "project" --max-results 10

# Restart server to rebuild index
claude mcp restart memcord

7. "Tags not working"

Problem: Tag operations failing or not filtering correctly.

Troubleshooting:

  • Ensure tags are added: memcord_tag add "tag1 tag2"
  • Check existing tags: memcord_list_tags
  • Remember tags are case-insensitive (stored lowercase)
  • Verify tag spelling in filter commands

Configuration Issues

8. "MCP server not found in Claude Code"

Problem: Server not appearing in Claude Code.

Solution:

# Verify server is added
claude mcp list

# Add if missing
claude mcp add memcord uv --directory /path/to/memcord run memcord -e PYTHONPATH=/path/to/memcord/src

# Check configuration
claude mcp get memcord

9. "Permission denied" errors

Problem: File system permission issues.

Solutions:

  • Check directory permissions: ls -la
  • Ensure write access to memory_slots/ directory
  • Verify user ownership of project files
  • Run with appropriate user permissions

10. "Invalid compression ratio"

Problem: Summary compression fails with invalid ratio.

Solution:

  • Use values between 0.05 and 0.5
  • Default is 0.15 (15% compression)
  • Examples: memcord_save_progress "content" 0.1 (10% compression)

11. memcord_save_progress fails — "NLTK tokenizers are missing"

Problem: save_progress errors with a message like:

Resource punkt_tab not found.
Download them by running: python -c "import nltk; nltk.download('punkt')"

Cause: The nltk and sumy summarizer backends require NLTK tokenizer data (punkt_tab) which must be downloaded separately. This data is missing from the Python environment the MCP server is running in.

Solution: Download the data into the correct environment — the venv used by the MCP server (not the dev venv):

# Find your memcord install path (shown in `claude mcp get memcord`)
# Then run:
/path/to/memcord/.venv/Scripts/python -c "import nltk; nltk.download('punkt_tab')"

# On macOS/Linux:
/path/to/memcord/.venv/bin/python -c "import nltk; nltk.download('punkt_tab')"

No restart required — the data is loaded at runtime.

Alternative: Switch to the semantic summarizer backend which does not use NLTK:

memcord_configure action="set" key="summarizer_backend" value="semantic"

Note: semantic requires sentence-transformers (~80 MB) installed in the server venv:

/path/to/memcord/.venv/Scripts/pip install sentence-transformers

Then restart Claude Code to pick up the new package.

Debug Mode

Enabling Debug Output

# Run server with debug logging
PYTHONPATH=src python -m memcord.server --debug

# Set log level
export LOG_LEVEL=DEBUG
uv run memcord

# Check specific component
python -c "from src.memcord.search import SearchEngine; print('Search OK')"

Debug Information

Debug mode provides:

  • Detailed error messages
  • Search query analysis
  • Index statistics
  • Performance metrics
  • File operation logs

Log File Locations

# Check system logs
tail -f ~/.local/share/claude/logs/mcp.log

# Application-specific logs (if configured)
tail -f ./logs/chat_memory.log

Performance Troubleshooting

Memory Usage Issues

Symptoms: High memory usage, slow operations

Solutions:

  1. Limit result sets:

    memcord_search "query" --max-results 20

  2. Clean up large memory slots:

    # Export and archive old content
memcord_export "old_slot" "json"
# Then delete or summarize

  3. Optimize search index:

    # Restart server to rebuild index
claude mcp restart memcord

Disk Space Issues

Symptoms: "No space left on device" errors

Solutions:

  1. Check disk usage:

    du -sh memory_slots/
du -sh shared_memories/

  2. Clean up exports:

    rm shared_memories/*.txt
rm shared_memories/*.md
# Keep JSON exports for data integrity

  3. Archive old memories:

    # Move old slots to archive directory
mkdir archive/
mv memory_slots/old_* archive/

Data Recovery

Corrupted Memory Slots

Symptoms: JSON parsing errors, missing data

Recovery steps:

  1. Check for backup files:

    ls memory_slots/*.backup
ls memory_slots/*.bak

  2. Validate JSON structure:

    python -m json.tool memory_slots/slot_name.json

  3. Restore from export:

    # If JSON export exists
cp shared_memories/slot_name.json memory_slots/

Lost Search Index

Symptoms: No search results, index errors

Recovery:

# Delete index cache
rm -rf .cache/search_index.json
rm -rf .cache/term_frequencies.json

# Restart server to rebuild
claude mcp restart memcord

Network & Connectivity

MCP Connection Issues

Symptoms: Tools not available, connection timeouts

Troubleshooting:

  1. Check MCP server status:

    claude mcp status memcord

  2. Restart MCP server:

    claude mcp restart memcord

  3. Verify configuration:

    claude mcp get memcord
cat ~/.mcp.json  # Check project config

Merge Operation Errors

11. "Merge operation failed: 'MemorySlot' object has no attribute 'content'"

Problem: Memory slot merging fails with attribute errors after code updates.

Root Cause: MCP server needs to reload after code changes to reflect updated merger functionality.

Solutions:

  1. Complete restart (Recommended):

    # Exit Claude Code and restart
# Press Ctrl+D to exit Claude Code
# Then restart Claude Code

  2. Remove and re-add server:

    # Remove the server
claude mcp remove memcord

# Re-add the server  
claude mcp add memcord uv --directory /path/to/memcord run memcord -e PYTHONPATH=/path/to/memcord/src

  3. MCP Hot Reload Server (Advanced):

    # Install hot reload capability for seamless restarts
git clone https://github.com/claude-code-mcp-reload/mcp-hot-reload.git
pip install -e .

# Configure in .mcp.json:
# "memcord-hot": {
#   "command": "mcp-hot-reload", 
#   "args": ["wrap", "--name", "memcord", "--", "uv", "run", "memcord"]
# }

Note: This is a known limitation where MCP servers need manual restart after code changes. There's an active feature request for automatic reload functionality in Claude Code.

Validation & Testing

Test Server Functionality

# Test search functionality
python -c "
from src.memcord.search import SearchEngine
engine = SearchEngine()
print('Search engine: OK')
"

# Test query processing
python -c "
from src.memcord.query import SimpleQueryProcessor
processor = SimpleQueryProcessor()
print('Query processor: OK')
"

# Validate data models
python -c "
from src.memcord.models import MemorySlot, SearchQuery
print('Data models: OK')
"

Run Tests (if available)

# Install dev dependencies
uv pip install -e ".[dev]"

# Run test suite
pytest

# Run specific tests
pytest tests/test_search.py
pytest tests/test_storage.py

Getting Help

Before Reporting Issues

  1. Check this troubleshooting guide
  2. Verify your setup matches installation requirements
  3. Try debug mode to get detailed error information
  4. Check recent changes to your configuration

Reporting Issues

When reporting problems, include:

  1. System information:

    • Operating system and version
    • Python version (python --version)
    • uv version (uv --version)

  2. Error details:

    • Complete error message
    • Debug output (if available)
    • Steps to reproduce

  3. Configuration:

    • MCP server configuration
    • Environment variables
    • Project structure

Support Channels

  • GitHub Issues: For bug reports and feature requests
  • Documentation: Check docs/ directory for detailed guides
  • Debug Output: Use debug mode for detailed diagnostics

Emergency Recovery

If all else fails:

  1. Backup current data:

    cp -r memory_slots/ backup_$(date +%Y%m%d)/

  2. Reinstall fresh:

    uv pip uninstall memcord
uv pip install -e .

  3. Restore data:

    cp backup_*/memory_slots/* memory_slots/

  4. Rebuild index:

    rm -rf .cache/
claude mcp restart memcord