Skip to content

08 FAQ

Jump to bottom
Henry edited this page Aug 23, 2025 · 1 revision

Frequently Asked Questions

Common questions and answers about MCP Memory Service usage, configuration, and troubleshooting.

Table of Contents

General Questions

What is MCP Memory Service?

MCP Memory Service is a Model Context Protocol server that provides semantic memory and persistent storage capabilities for AI assistants like Claude. It allows you to store, search, and retrieve information across conversations and sessions.

What storage backends are supported?

  • SQLite-vec (recommended): Fast, single-file database perfect for individual use
  • ChromaDB: Great for multi-client scenarios and team collaboration
  • Cloudflare: Production-ready distributed storage for enterprise use

How does semantic search work?

MCP Memory Service uses sentence transformers to convert your content into vector embeddings. When you search, it finds semantically similar content, not just exact text matches. This means searching for "authentication issues" will also find memories about "login problems" or "JWT errors."

Can I use this with other AI tools besides Claude?

Yes! MCP Memory Service implements the standard Model Context Protocol, so it works with any MCP-compatible client. It also provides REST APIs for custom integrations.

Is my data secure?

Yes. Data is stored locally by default (SQLite-vec backend), or in your chosen infrastructure (ChromaDB, Cloudflare). The service supports HTTPS, API key authentication, and you have full control over your data.

Installation & Setup

What are the system requirements?

  • Python: 3.10+ (with sentence-transformers support)
  • Memory: 2GB+ recommended for embedding models
  • Disk Space: Varies by usage (~1GB for 100K memories)
  • OS: Windows, macOS, Linux supported

Do I need GPU for good performance?

No, but it helps. MCP Memory Service automatically detects and uses:

  • CUDA (NVIDIA GPUs)
  • MPS (Apple Silicon M1/M2)
  • DirectML (Windows GPU acceleration)
  • CPU fallback for systems without GPU support

How do I migrate from one backend to another?

# Export from current backend
python scripts/export_memories.py --format json > backup.json

# Switch backend in config
export MCP_MEMORY_STORAGE_BACKEND=sqlite_vec

# Import to new backend
python scripts/import_memories.py --file backup.json

Can I run this on a server for team access?

Yes! Enable the HTTP server and configure for multi-client access:

export MCP_HTTP_ENABLED=true
export MCP_HTTPS_ENABLED=true
export MCP_HTTP_PORT=8443
export MCP_MEMORY_STORAGE_BACKEND=chroma  # Better for multi-client

Performance & Scaling

How fast are search queries?

Performance varies by backend:

  • SQLite-vec: ~5ms average
  • ChromaDB: ~15ms average
  • Cloudflare: Network dependent

How much memory does it use?

  • Base service: ~500MB
  • Embedding models: ~1GB
  • Memory cache: ~200MB per 1000 memories
  • Total: 2GB typical for active development use

Can I limit resource usage?

Yes, configure resource limits:

export MCP_MAX_MEMORY_MB=2048
export MCP_MAX_CONCURRENT_OPERATIONS=10
export MCP_EMBEDDING_BATCH_SIZE=50

How do I handle large numbers of memories?

  • Use appropriate result limits in searches
  • Implement memory cleanup routines
  • Consider database partitioning for >1M memories
  • Monitor performance with built-in metrics

Claude Code Integration

How do I install Claude Code hooks?

  1. Download the hook system from the MCP Memory Service repository
  2. Configure claude-hooks/config.json with your settings
  3. Test with node test-hooks.js
  4. Start using Claude Code normally

Why isn't my context loading automatically?

Check these common issues:

  • Memory service not running: curl -k https://localhost:8443/api/health
  • Hook configuration error: Check claude-hooks/config.json
  • Project not detected: Verify git repository and package files
  • No memories found: Check if you have relevant memories stored

How does the memory scoring algorithm work?

The algorithm uses four factors:

  • Time decay (25%): Recent memories weighted higher
  • Tag relevance (35%): Project and technology tag matches
  • Content relevance (15%): Semantic similarity to current context
  • Conversation relevance (25%): Related to ongoing conversation

Can I customize which memories are loaded?

Yes! Configure in claude-hooks/config.json:

{
  "memoryService": {
    "maxMemoriesPerSession": 8,
    "minRelevanceScore": 0.3
  },
  "memoryScoring": {
    "weights": {
      "timeDecay": 0.25,
      "tagRelevance": 0.35,
      "contentRelevance": 0.15,
      "conversationRelevance": 0.25
    }
  }
}

Troubleshooting

The service won't start

Common causes:

  1. Port conflict: Check if port 8443 is in use 
    netstat -tlnp | grep 8443
  2. Missing dependencies: Reinstall with python install.py
  3. Python version: Requires Python 3.10+ 
    python --version
  4. Disk space: Ensure sufficient space for models and data

Search returns no results

Troubleshooting steps:

  1. Check if memories exist: 
    curl -k "https://localhost:8443/api/memories/count"
  2. Try exact text search: Use quotes for exact matching
  3. Check tag search: search_by_tags(["your-tag"])
  4. Verify embedding model: Check if sentence transformers loaded correctly

"Database is locked" error

This typically happens with SQLite-vec under high load:

# Enable WAL mode for better concurrent access
sqlite3 your_db.db "PRAGMA journal_mode=WAL;"

# Check for hanging connections
lsof | grep your_db.db

# Restart service if needed
systemctl restart mcp-memory-service

Memory usage keeps growing

Solutions:

  1. Reduce cache sizes: 
    export MCP_EMBEDDING_CACHE_SIZE=500
export MCP_QUERY_CACHE_SIZE=50
  2. Enable garbage collection: 
    import gc
gc.collect()  # Add to periodic maintenance
  3. Implement memory cleanup: 
    # Remove old temporary memories
python scripts/cleanup_memories.py --older-than 30 --tag temporary

Claude Code hooks not working

Debug checklist:

  1. Verify hook installation: 
    node claude-hooks/test-hooks.js
  2. Check Claude Code CLI version: 
    claude --version  # Should be recent version
  3. Test memory service connection: 
    curl -k https://localhost:8443/api/health
  4. Enable debug logging: 
    {
  "logging": {
    "level": "debug",
    "enableDebug": true,
    "logToFile": true
  }
}

Performance is slow

Optimization steps:

  1. Check backend choice: SQLite-vec is fastest for single users
  2. Optimize search queries: Use specific terms, not vague searches
  3. Limit result sizes: Don't retrieve more than you need
  4. Enable hardware acceleration: GPU/MPS if available
  5. Monitor resource usage: 
    htop  # Check CPU and memory usage
iotop  # Check disk I/O

Can't connect to remote instance

Network troubleshooting:

  1. Check firewall: Ensure port 8443 is open
  2. Verify HTTPS certificates: Use -k flag for self-signed
  3. Test connectivity: 
    telnet your-server 8443
  4. Check DNS resolution: 
    nslookup your-server

Import/Export issues

Common solutions:

  1. JSON format validation: 
    python -m json.tool < export.json
  2. Check file permissions: Ensure read/write access
  3. Memory limits: Large imports may need increased memory
  4. Backup before import: Always backup existing data

Getting help

If you're still having issues:

  1. Check the Troubleshooting Guide
  2. Search existing GitHub issues
  3. Create a new issue with:
    • Operating system and Python version
    • Configuration files (remove sensitive data)
    • Error logs and stack traces
    • Steps to reproduce the problem

Best practices to avoid issues

  1. Regular maintenance: Weekly cleanup and optimization
  2. Monitor resources: Keep an eye on memory and disk usage
  3. Backup data: Regular exports of important memories
  4. Update regularly: Keep service and dependencies updated
  5. Use appropriate backends: Choose based on your use case
Clone this wiki locally