03 Integration Guide

Integration Guide

Complete guide for integrating MCP Memory Service with Claude Desktop, Claude Code, VS Code, and other AI development tools.

🧠 Claude Desktop Integration

Basic Claude Desktop Setup

1. Install MCP Memory Service:

# Install with Claude Desktop support
python install.py --claude-desktop

# Or standard installation
python install.py

2. Configure Claude Desktop:

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "memory": {
      "command": "uv",
      "args": [
        "--directory", "/path/to/mcp-memory-service",
        "run", "memory", "server"
      ],
      "env": {
        "MCP_MEMORY_STORAGE_BACKEND": "sqlite_vec"
      }
    }
  }
}

3. Verify Connection: Restart Claude Desktop and look for the memory tools in the tool list. You should see:

store_memory
retrieve_memory
search_by_tag
delete_memory
check_database_health

Advanced Claude Desktop Configuration

Multiple Storage Backends:

{
  "mcpServers": {
    "memory-sqlite": {
      "command": "uv",
      "args": ["--directory", "/path/to/mcp-memory-service", "run", "memory", "server"],
      "env": {
        "MCP_MEMORY_STORAGE_BACKEND": "sqlite_vec",
        "MCP_MEMORY_SQLITE_PATH": "~/.mcp_memory/personal.db"
      }
    },
    "memory-shared": {
      "command": "uv", 
      "args": ["--directory", "/path/to/mcp-memory-service", "run", "memory", "server"],
      "env": {
        "MCP_MEMORY_STORAGE_BACKEND": "chroma",
        "MCP_MEMORY_CHROMA_PATH": "/shared/team-memory"
      }
    }
  }
}

Remote Server Configuration:

For connecting Claude Desktop to a remote MCP Memory Service instance (running on a VPS, server, or different machine), use the HTTP-to-MCP bridge:

{
  "mcpServers": {
    "memory": {
      "command": "node",
      "args": ["/path/to/mcp-memory-service/examples/http-mcp-bridge.js"],
      "env": {
        "MCP_MEMORY_HTTP_ENDPOINT": "https://your-server:8000/api",
        "MCP_MEMORY_API_KEY": "your-secure-api-key"
      }
    }
  }
}

Setup Steps:

Download examples/http-mcp-bridge.js to your local machine
Replace /path/to/mcp-memory-service/examples/http-mcp-bridge.js with the actual file path
Replace https://your-server:8000/api with your server's endpoint
Replace your-secure-api-key with your actual API key
Restart Claude Desktop

Configuration Options:

MCP_MEMORY_HTTP_ENDPOINT: Remote server API endpoint
MCP_MEMORY_API_KEY: Authentication token
MCP_MEMORY_AUTO_DISCOVER: Enable mDNS service discovery (true/false)
MCP_MEMORY_PREFER_HTTPS: Prefer HTTPS over HTTP when discovering (true/false)

Troubleshooting Remote Connections:

Connection refused: Verify server is running and accessible, check firewall rules
SSL issues: Bridge automatically accepts self-signed certificates
Auth failed: Verify API key is correctly set on both server and bridge
No logs: Bridge logs appear in Claude Desktop's console/stderr

Complete examples: claude-desktop-http-config.json

💻 Claude Code Integration

Phase 1: Basic Memory Commands

Essential Memory Commands:

# Store memories during development
claude /memory-store "Fixed race condition in user authentication by adding proper mutex locks"

# Recall context
claude /memory-recall "authentication race condition solutions"

# Check memory health
claude /memory-health

# Search by context
claude /memory-context

Phase 1.5: Claude Code HTTP Transport (v7.0.0+)

Zero-Configuration OAuth Setup:

With v7.0.0, Claude Code can connect via HTTP transport with automatic OAuth 2.1 authentication:

# Add HTTP transport MCP server
claude mcp add --transport http memory-service http://localhost:8000/mcp

# Claude Code will automatically:
# 1. Discover OAuth endpoints via /.well-known/oauth-authorization-server/mcp
# 2. Register as an OAuth client
# 3. Complete authorization flow
# 4. Use JWT tokens for all requests

Manual Configuration (if needed):

{
  "memoryService": {
    "protocol": "http",
    "http": {
      "endpoint": "http://localhost:8000",
      "oauth": {
        "enabled": true,
        "discoveryUrl": "http://localhost:8000/.well-known/oauth-authorization-server/mcp"
      }
    }
  }
}

Benefits of HTTP Transport:

✅ Team Collaboration: Multiple Claude Code instances can share memories
✅ Zero Configuration: Automatic OAuth discovery and registration
✅ Enterprise Ready: JWT authentication with proper scope validation
✅ Seamless Experience: Transparent authentication, just like MCP protocol

Start HTTP Server:

# Enable OAuth and start HTTP server
export MCP_OAUTH_ENABLED=true
export MCP_HTTPS_ENABLED=true  # Recommended for team use
uv run memory server --http

# Server will be available at:
# - HTTP API: http://localhost:8000/api/*
# - MCP-over-HTTP: http://localhost:8000/mcp
# - OAuth Discovery: http://localhost:8000/.well-known/oauth-authorization-server/mcp

Phase 2: Memory Awareness Hooks (Advanced)

Automatic Memory Integration:

Memory Hooks & Natural Triggers

For complete automatic memory awareness, see the consolidated guide:

📖 Memory Hooks & Natural Triggers - Complete Guide

Quick Installation:

# Install with Natural Memory Triggers (v7.1.4)
cd mcp-memory-service/claude-hooks
python install_hooks.py --natural-triggers

# Test installation
node ~/.claude/hooks/memory-mode-controller.js status

The consolidated guide covers:

✅ Natural Memory Triggers with 85%+ accuracy
✅ Mid-conversation hooks for real-time updates
✅ Performance profiles and CLI management
✅ Complete troubleshooting and configuration
✅ Migration from legacy hooks

Legacy Installation (Deprecated)

For compatibility with existing setups:

# Install legacy Claude Code hooks
python scripts/install_claude_hooks.py

# Verify installation
python scripts/test_claude_hooks.py

Legacy Hook Features:

Automatic context loading based on conversation topics
Cross-session memory continuity - remembers project context
Intelligent memory injection at optimal conversation points
Topic detection for relevant memory retrieval
Project-specific memory scoping

Hook Configuration:

{
  "hooks": {
    "prePromptSubmit": [
      "python /path/to/claude-hooks/pre_prompt_submit.py"
    ],
    "postPromptSubmit": [
      "python /path/to/claude-hooks/post_prompt_submit.py"
    ]
  },
  "memoryConfig": {
    "autoLoad": true,
    "maxMemories": 10,
    "relevanceThreshold": 0.7,
    "topicDetection": true
  }
}

Development Workflow with Memory

Project Setup Pattern:

# Start new project context
claude /memory-store "Starting project: E-commerce API redesign. Goals: improve performance, add GraphQL, migrate to microservices"

# Store architectural decisions
claude /memory-store "Architecture decision: Using FastAPI + PostgreSQL + Redis for session management. Decided against MongoDB due to transaction requirements"

# Document important discoveries
claude /memory-store "Performance issue found: N+1 query in user.orders relationship. Fixed with select_related. 10x improvement in response time"

Daily Development Pattern:

# Morning context loading
claude /memory-recall "what was I working on yesterday"

# During development - automatic memory awareness
# (Hooks automatically inject relevant context)

# End of day summary
claude /memory-store "Daily summary: Completed user authentication refactor, identified database indexing issues, next: implement GraphQL mutations"

🔧 VS Code Extension Integration

VS Code MCP Extension

Install VS Code MCP Extension:

Install the "MCP" extension from VS Code marketplace
Configure extension settings

VS Code Settings (settings.json):

{
  "mcp.servers": {
    "memory": {
      "command": "uv",
      "args": ["--directory", "/path/to/mcp-memory-service", "run", "memory", "server"],
      "env": {
        "MCP_MEMORY_STORAGE_BACKEND": "sqlite_vec"
      }
    }
  },
  "mcp.autoStart": true,
  "mcp.enableLogging": true
}

VS Code Memory Commands

Command Palette Integration:

MCP Memory: Store Selection - Store selected code/text
MCP Memory: Search Memories - Search existing memories
MCP Memory: Recall by Tags - Filter by tags
MCP Memory: Insert Memory - Insert memory content at cursor

Keybindings (keybindings.json):

[
  {
    "key": "ctrl+shift+m s",
    "command": "mcp.memory.store",
    "when": "editorHasSelection"
  },
  {
    "key": "ctrl+shift+m r", 
    "command": "mcp.memory.recall"
  },
  {
    "key": "ctrl+shift+m t",
    "command": "mcp.memory.searchByTags"
  }
]

🔗 Other IDE Integrations

Cursor Integration

Cursor Rules Configuration:

# .cursorrules file

## Memory Integration
When working on code, automatically:
1. Store important architectural decisions
2. Remember bug fixes and solutions  
3. Track configuration changes
4. Document API changes

Use MCP Memory Service for persistence:
- Store: Complex solutions, architectural decisions
- Recall: Previous solutions to similar problems
- Tag: By technology, project area, issue type

## Memory Commands Available:
- `/memory-store "content"` - Store information
- `/memory-recall "query"` - Find relevant memories
- `/memory-health` - Check system status

Continue.dev Integration

Continue Configuration (.continue/config.json):

{
  "models": [
    {
      "title": "Claude with Memory",
      "provider": "anthropic",
      "model": "claude-3-sonnet-20240229",
      "contextLength": 100000,
      "completionOptions": {
        "temperature": 0.1
      }
    }
  ],
  "customCommands": [
    {
      "name": "store-memory",
      "description": "Store current context in MCP Memory", 
      "prompt": "Store this code/solution in MCP Memory Service with relevant tags: {{{input}}}"
    },
    {
      "name": "recall-memory",
      "description": "Recall relevant memories",
      "prompt": "Search MCP Memory Service for: {{{input}}}"
    }
  ],
  "mcpServers": {
    "memory": {
      "command": "uv",
      "args": ["run", "memory", "server"],
      "cwd": "/path/to/mcp-memory-service"
    }
  }
}

Neovim Integration

Neovim MCP Plugin Setup:

-- ~/.config/nvim/lua/mcp-memory.lua
local M = {}

function M.store_memory()
  local content = vim.fn.input("Store memory: ")
  if content ~= "" then
    vim.fn.system("uv run memory store '" .. content .. "'")
    print("Memory stored!")
  end
end

function M.recall_memory()
  local query = vim.fn.input("Recall query: ")
  if query ~= "" then
    local result = vim.fn.system("uv run memory recall '" .. query .. "'")
    -- Display result in floating window
    local lines = vim.split(result, "\n")
    local buf = vim.api.nvim_create_buf(false, true)
    vim.api.nvim_buf_set_lines(buf, 0, -1, false, lines)
    
    local win = vim.api.nvim_open_win(buf, true, {
      relative = "center",
      width = 80,
      height = 20,
      style = "minimal",
      border = "rounded"
    })
  end
end

return M

Key Mappings:

-- ~/.config/nvim/init.lua
local mcp_memory = require('mcp-memory')

vim.keymap.set('n', '<leader>ms', mcp_memory.store_memory, { desc = 'Store memory' })
vim.keymap.set('n', '<leader>mr', mcp_memory.recall_memory, { desc = 'Recall memory' })

🌐 Web Interface Integration

HTTP API Access

Start HTTP Server:

# Start with HTTP API enabled
uv run memory server --http

# Access web dashboard
open https://localhost:8000

API Endpoints:

# Health check
curl -k https://localhost:8000/api/health

# Store memory
curl -k -X POST https://localhost:8000/api/memories \
  -H "Content-Type: application/json" \
  -d '{"content": "API integration test", "tags": ["api", "test"]}'

# Search memories  
curl -k -X POST https://localhost:8000/api/search \
  -H "Content-Type: application/json" \
  -d '{"query": "integration test", "n_results": 5}'

# Search by tags
curl -k -X POST https://localhost:8000/api/search/by-tag \
  -H "Content-Type: application/json" \
  -d '{"tags": ["api"], "match_all": false}'

JavaScript/TypeScript Integration

Node.js Client:

// memory-client.js
const https = require('https');

class MCPMemoryClient {
  constructor(baseUrl = 'https://localhost:8000', apiKey = null) {
    this.baseUrl = baseUrl;
    this.apiKey = apiKey;
    // Disable SSL verification for self-signed certs
    process.env["NODE_TLS_REJECT_UNAUTHORIZED"] = 0;
  }

  async storeMemory(content, tags = [], memoryType = null) {
    const response = await fetch(`${this.baseUrl}/api/memories`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        ...(this.apiKey && { 'Authorization': `Bearer ${this.apiKey}` })
      },
      body: JSON.stringify({ content, tags, memory_type: memoryType })
    });
    return await response.json();
  }

  async searchMemories(query, nResults = 10) {
    const response = await fetch(`${this.baseUrl}/api/search`, {
      method: 'POST', 
      headers: {
        'Content-Type': 'application/json',
        ...(this.apiKey && { 'Authorization': `Bearer ${this.apiKey}` })
      },
      body: JSON.stringify({ query, n_results: nResults })
    });
    return await response.json();
  }

  async searchByTags(tags, matchAll = false) {
    const response = await fetch(`${this.baseUrl}/api/search/by-tag`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json', 
        ...(this.apiKey && { 'Authorization': `Bearer ${this.apiKey}` })
      },
      body: JSON.stringify({ tags, match_all: matchAll })
    });
    return await response.json();
  }
}

// Usage
const client = new MCPMemoryClient();

// Store a memory
await client.storeMemory(
  "Learned how to integrate MCP Memory Service with Node.js", 
  ["nodejs", "integration", "learning"]
);

// Search memories
const results = await client.searchMemories("nodejs integration");
console.log(results);

🔄 Multi-Client Synchronization

Shared Memory Setup

ChromaDB Backend for Team Sharing:

# Setup shared ChromaDB instance
export MCP_MEMORY_STORAGE_BACKEND=chroma
export MCP_MEMORY_CHROMA_PATH=/shared/team-memory

# All team members use same path
python install.py --shared

Network Service for Remote Access:

# Start as network service
uv run memory server --http --host 0.0.0.0 --port 8000

# Team members connect via HTTP API
export MCP_MEMORY_HTTP_ENDPOINT=http://team-server:8000

Distributed Synchronization

Litestream for Database Replication:

# litestream.yml
dbs:
  - path: ~/.mcp_memory/sqlite_vec.db
    replicas:
      - type: file
        path: /shared/backup/sqlite_vec.db
        sync-interval: 1m

Git-based Memory Sharing:

# Export memories to git repository
uv run memory export --format git-repo --output team-memories/

# Import from shared repository
uv run memory import --from git-repo --source team-memories/

📊 Integration Monitoring

Health Checks

Automated Health Monitoring:

#!/bin/bash
# health_check.sh

# Check MCP Memory Service health
echo "Checking MCP Memory Service health..."
uv run memory health

# Check API endpoint (if HTTP enabled) 
if curl -f -k https://localhost:8000/api/health > /dev/null 2>&1; then
    echo "✅ HTTP API is healthy"
else
    echo "❌ HTTP API is down"
fi

# Check memory operations
echo "Testing memory operations..."
uv run memory store "Health check test $(date)"
uv run memory recall "health check"

Integration with Monitoring Systems:

# Prometheus metrics endpoint
curl https://localhost:8000/metrics

# Grafana dashboard configuration
# Import dashboard from monitoring/grafana-dashboard.json

🚨 Integration Troubleshooting

Common Integration Issues

Claude Desktop not detecting memory tools:

Check Claude Desktop config file syntax
Verify file paths are correct
Restart Claude Desktop after config changes
Check MCP Memory Service logs

VS Code extension connection errors:

Verify VS Code MCP extension is installed
Check extension settings configuration
Restart VS Code after changes
Check VS Code developer console for errors

HTTP API connection refused:

# Check if service is running
curl -k https://localhost:8000/api/health

# Check firewall settings
# Check if port 8000 is available
lsof -i :8000

# Verify SSL certificates
openssl s_client -connect localhost:8000

Claude Code OAuth connection issues:

# Test OAuth discovery endpoint
curl http://localhost:8000/.well-known/oauth-authorization-server/mcp

# Verify OAuth is enabled
echo $MCP_OAUTH_ENABLED  # Should be 'true'

# Check OAuth client registration
curl -X POST http://localhost:8000/oauth/register \
     -H "Content-Type: application/json" \
     -d '{"client_name": "Test Client"}'

# Check server logs for OAuth errors
tail -f logs/mcp-memory-service.log | grep -i oauth

Debug Mode

Enable Debug Logging:

# Start with debug logging
export LOG_LEVEL=DEBUG
uv run memory server --http --debug

# Check logs
tail -f ~/.mcp_memory_service/logs/debug.log

Test MCP Protocol Connection:

# Test MCP protocol directly
npx @modelcontextprotocol/inspector uv run memory server

# This opens the MCP Inspector for direct protocol testing

📋 Integration Checklist

Pre-Integration Setup

MCP Memory Service installed and working
Storage backend configured and tested
API key generated (if using HTTP API)
Network connectivity verified

Claude Desktop Integration

Claude Desktop config file updated
File paths corrected for your system
Claude Desktop restarted
Memory tools appear in tool list
Basic memory operations tested

Claude Code Integration

Memory commands working (/memory-store, /memory-recall)
Memory awareness hooks installed (optional)
Hook functionality tested
Project context loading verified

IDE Integration

IDE-specific extension/plugin installed
Configuration files updated
Keybindings configured
Memory commands accessible
Integration tested with sample operations

API Integration

HTTP server started and accessible
API endpoints responding correctly
Authentication working (if configured)
Client libraries/scripts tested
Error handling implemented

For specific integration issues, see our Troubleshooting Guide or Claude Code Quick Reference.

Uh oh!

03 Integration Guide

Integration Guide

🧠 Claude Desktop Integration

Basic Claude Desktop Setup

Advanced Claude Desktop Configuration

💻 Claude Code Integration

Phase 1: Basic Memory Commands

Phase 1.5: Claude Code HTTP Transport (v7.0.0+)

Phase 2: Memory Awareness Hooks (Advanced)

Memory Hooks & Natural Triggers

Legacy Installation (Deprecated)

Development Workflow with Memory

🔧 VS Code Extension Integration

VS Code MCP Extension

VS Code Memory Commands

🔗 Other IDE Integrations

Cursor Integration

Continue.dev Integration

Neovim Integration

🌐 Web Interface Integration

HTTP API Access

JavaScript/TypeScript Integration

🔄 Multi-Client Synchronization

Shared Memory Setup

Distributed Synchronization

📊 Integration Monitoring

Health Checks

🚨 Integration Troubleshooting

Common Integration Issues

Debug Mode

📋 Integration Checklist

Pre-Integration Setup

Claude Desktop Integration

Claude Code Integration

IDE Integration

API Integration

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally