Remember Me MCP Server

A powerful Model Context Protocol (MCP) server that provides persistent memory capabilities for Claude Desktop, enabling Claude to remember and recall information across conversations.

Features

• Persistent Memory: Store and retrieve memories across Claude Desktop sessions
• Semantic Search: OpenAI embeddings with vector similarity search for intelligent memory retrieval
• Automatic Pattern Detection: Intelligently detects memory-worthy content from conversations
• Smart Updates: Updates existing memories instead of creating duplicates using update keys
• Async Processing: Memories stored instantly, embeddings generated in background
• Memory Categories: Organize by type (fact, conversation, context, preference) and category (personal, project, business)
• Priority System: Memories prioritized as low, medium, high, or critical
• PostgreSQL + pgvector: Robust database with vector operations for semantic search
• HTTP API: RESTful API with authentication for third-party integrations
• Comprehensive Testing: Full test coverage for all components

Quick Start

Option 1: Claude Desktop Extension (Easiest)

1. Download the latest remember-me.dxt from Releases
2. Open Claude Desktop → Extensions → Add Extension
3. Select the downloaded remember-me.dxt file
4. Configure your API URL and API Key
5. Start using Remember Me!

For detailed extension instructions, see the extension README.

Option 2: One-Command Setup (Recommended for Self-Hosting)

curl -sSL https://raw.githubusercontent.com/ksred/remember-me-mcp/main/scripts/setup.sh | bash

Option 3: Development Setup (Recommended for Development)

git clone https://github.com/ksred/remember-me-mcp.git
cd remember-me-mcp
make dev-setup

This sets up PostgreSQL in Docker while running the MCP server locally.

Option 4: Docker Setup (Full Containerized)

git clone https://github.com/ksred/remember-me-mcp.git
cd remember-me-mcp
make docker-setup

Option 5: Manual Installation

1. Prerequisites: PostgreSQL 15+, Go 1.21+, pgvector extension
2. Clone and build:

   git clone https://github.com/ksred/remember-me-mcp.git
   cd remember-me-mcp
   make build
   sudo make install
   

3. Configure Claude Desktop: Add to ~/Library/Application Support/Claude/claude_desktop_config.json
4. Restart Claude Desktop: Required for configuration changes to take effect

Configuration

The server can be configured through environment variables or a YAML configuration file:

Environment Variables

# Database
DATABASE_URL=postgres://user:pass@localhost:5432/remember_me
REMEMBER_ME_DATABASE_HOST=localhost
REMEMBER_ME_DATABASE_PORT=5432
REMEMBER_ME_DATABASE_USER=postgres
REMEMBER_ME_DATABASE_PASSWORD=your-password
REMEMBER_ME_DATABASE_DBNAME=remember_me

# OpenAI
OPENAI_API_KEY=your-api-key-here

# Server
LOG_LEVEL=info
DEBUG=false

Configuration File

Create ~/.config/remember-me-mcp/config.yaml:

database:
  host: localhost
  port: 5432
  user: postgres
  password: your-password
  dbname: remember_me
  sslmode: disable

openai:
  api_key: your-api-key-here
  model: text-embedding-3-small

memory:
  max_memories: 1000
  similarity_threshold: 0.7

server:
  log_level: info
  debug: false

Claude Desktop Integration

Configure Claude Desktop by editing the configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/claude-desktop/claude_desktop_config.json

Add the following configuration:

{
  "mcpServers": {
    "remember-me": {
      "command": "/usr/local/bin/remember-me-mcp",
      "env": {
        "REMEMBER_ME_DATABASE_HOST": "localhost",
        "REMEMBER_ME_DATABASE_PORT": "5432",
        "REMEMBER_ME_DATABASE_USER": "postgres",
        "REMEMBER_ME_DATABASE_PASSWORD": "your-database-password",
        "REMEMBER_ME_DATABASE_DBNAME": "remember_me",
        "REMEMBER_ME_DATABASE_SSLMODE": "disable",
        "OPENAI_API_KEY": "your-openai-api-key-here",
        "LOG_LEVEL": "info"
      }
    }
  }
}

Important: After updating the configuration file, restart Claude Desktop for the changes to take effect.

MCP Tools

The server provides three MCP tools:

1. store_memory

Store a new memory or update an existing one.

Parameters:

• content (required): The memory content
• type (required): Memory type (fact, conversation, context, preference)
• category (required): Memory category (personal, project, business)
• tags (optional): Array of tags
• metadata (optional): Additional metadata object

Example:

{
  "content": "User prefers email communication over Slack",
  "type": "preference",
  "category": "business",
  "tags": ["communication", "preferences"],
  "metadata": {
    "source": "user_feedback",
    "priority": "high"
  }
}

2. search_memories

Search for memories using keyword or semantic search.

Parameters:

• query (optional): Search query
• category (optional): Filter by category
• type (optional): Filter by type
• limit (optional): Maximum results (default: 10)
• use_semantic_search (optional): Use vector search (default: false)

Example:

{
  "query": "email preferences",
  "category": "business",
  "use_semantic_search": true,
  "limit": 5
}

3. delete_memory

Delete a memory by ID.

Parameters:

• id (required): Memory ID to delete

Example:

{
  "id": 123
}

Memory Types

• fact: Factual information about the user or context
• conversation: Important conversation history
• context: Contextual information for better understanding
• preference: User preferences and settings

Memory Categories

• personal: Personal information and preferences
• project: Project-related memories
• business: Business and professional context

API Examples

Claude Desktop Usage

Once installed, you can use the memory system naturally in Claude Desktop:

User: "Remember that I prefer TypeScript over JavaScript for new projects"
Claude: I'll remember that you prefer TypeScript over JavaScript for new projects.
[Memory stored instantly, embedding generated in background]

User: "What are my programming preferences?"
Claude: Based on what I remember about your programming preferences:
- You prefer TypeScript over JavaScript for new projects
[Uses keyword search immediately, semantic search available after embedding is ready]

How it works:

• Instant Storage: Memories are stored immediately without waiting for OpenAI API
• Background Processing: Embeddings are generated asynchronously for semantic search
• Dual Search: Keyword search works instantly, semantic search enabled once embeddings are ready
• No Timeouts: Memory storage is never blocked by API timeouts

Direct API Usage

# Store a memory
echo '{"content": "Meeting with John on Friday", "type": "context", "category": "business"}' | \
  ./remember-me-mcp

# Search memories
echo '{"query": "John", "use_semantic_search": true}' | \
  ./remember-me-mcp

HTTP API Server

The Remember Me MCP server can also run as a standalone HTTP API server, allowing third-party applications to integrate with the memory system.

Running the HTTP Server

# Using make
make run-http

# Or directly
go run cmd/http-server/main.go -config config.json

# With Docker
docker run -p 8082:8082 remember-me-mcp:latest http-server

Features

• User Registration & Authentication: JWT-based authentication
• API Key Management: Generate and manage API keys for programmatic access
• RESTful Endpoints: Full CRUD operations for memories
• Swagger Documentation: Interactive API docs at /swagger

For detailed HTTP API documentation, see docs/HTTP_API.md.

Development

Prerequisites

• Go 1.21+
• Docker (for PostgreSQL)
• OpenAI API key (optional, will use mock embeddings if not provided)

Quick Development Setup

# Clone repository
git clone https://github.com/ksred/remember-me-mcp.git
cd remember-me-mcp

# One-command development setup
make dev-setup

Manual Development Setup

# Install dependencies
make deps

# Start PostgreSQL in Docker
make docker-db

# Test database connection
make db-test

# Run tests
make test

# Start development server
make run

Database-Only Docker Commands

# Start PostgreSQL container
make docker-db

# Stop PostgreSQL container
make docker-db-down

# View PostgreSQL logs
make docker-db-logs

# Connect to PostgreSQL
make docker-db-connect

# Clean up database container
make docker-db-clean

# Test database connection
make db-test

Testing

# Run all tests
make test

# Run tests with coverage
make test-coverage

# Run tests with HTML coverage report
make test-coverage-html

# Run linter
make lint

Docker Development

# Start with Docker
make docker-up

# View logs
make docker-logs

# Stop services
make docker-down

# Clean up
make docker-clean

Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Claude        │    │   MCP Server    │    │   PostgreSQL    │
│   Desktop       │◄──►│   (Go)          │◄──►│   + pgvector    │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                │
                                ▼
                       ┌─────────────────┐
                       │   OpenAI API    │
                       │   (Embeddings)  │
                       └─────────────────┘

Components

• MCP Server: Go-based server implementing MCP protocol
• Memory Service: Core business logic for memory operations
• Database Layer: PostgreSQL with pgvector for vector storage
• OpenAI Integration: Text embeddings for semantic search
• Configuration: Flexible configuration management

Deployment

Production Setup

1. Server Requirements:

   • 2+ CPU cores
   • 4GB+ RAM
   • 20GB+ storage
   • PostgreSQL 15+ with pgvector

2. Environment Setup:

   # Create production environment
   cp .env.example .env
   # Edit .env with production values
   
   # Deploy with Docker
   make docker-setup
   

3. Database Optimization:

   -- Optimize for production
   ALTER SYSTEM SET shared_buffers = '256MB';
   ALTER SYSTEM SET effective_cache_size = '1GB';
   ALTER SYSTEM SET maintenance_work_mem = '64MB';
   

Monitoring

• Logs: View logs with make docker-logs
• Health Check: Built-in health checks in Docker
• Metrics: Application metrics available via logs

Security

• Database: Use strong passwords and SSL connections
• API Keys: Store OpenAI API keys securely
• Access Control: Restrict database access to application only
• Input Validation: All inputs are validated and sanitized

Troubleshooting

Common Issues

1. Database Connection Failed:

   # Check PostgreSQL is running
   pg_isready -h localhost -p 5432
   
   # Check database exists
   psql -l | grep remember_me
   

2. pgvector Extension Missing:

   # Install pgvector
   # macOS: brew install pgvector
   # Ubuntu: apt-get install postgresql-15-pgvector
   
   # Enable extension
   psql -d remember_me -c "CREATE EXTENSION IF NOT EXISTS vector;"
   

3. OpenAI API Issues:

   # Check API key
   echo $OPENAI_API_KEY
   
   # Test API access
   curl -H "Authorization: Bearer $OPENAI_API_KEY" \
        https://api.openai.com/v1/models
   

4. Claude Desktop Not Connecting:

   # Check configuration
   cat ~/.config/claude-desktop/claude_desktop_config.json
   
   # Restart Claude Desktop
   # Check logs in Claude Desktop
   

Debug Mode

Enable debug logging:

export LOG_LEVEL=debug
export DEBUG=true
./remember-me-mcp

Performance Tuning

1. Database Indexes: Automatically created by GORM
2. Connection Pooling: Configured via environment variables
3. Memory Limits: Set MEMORY_MAX_MEMORIES to limit storage
4. Embedding Cache: Consider caching for frequently accessed memories

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Guidelines

• Follow Go best practices
• Write comprehensive tests
• Update documentation
• Use conventional commits
• Ensure all tests pass

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• Documentation: GitHub Wiki
• Issues: GitHub Issues
• Discussions: GitHub Discussions

Roadmap

• [ ] Web dashboard for memory management
• [ ] Multi-user support
• [ ] Additional embedding providers
• [ ] Memory expiration policies
• [ ] Export/import functionality
• [ ] Advanced search filters
• [ ] Memory clustering and summarization

Acknowledgments

• Model Context Protocol for the MCP specification
• pgvector for PostgreSQL vector support
• OpenAI for embedding models
• GORM for database ORM

---

Made with ❤️ for the Claude Desktop community