MCP Memory Service - TypeScript

A modern TypeScript implementation of a cloud-based vector memory service for AI assistants via the Model Context Protocol (MCP). This service provides persistent storage with semantic search capabilities for Claude.ai and other AI assistants.

Current Version: 1.7.2 | Status: Production-ready | Test Coverage: 95.2%

Features

🧠 3-Tier Memory System: SYSTEM, LEARNED, and MEMORY layers for hierarchical knowledge organization
👥 Multi-Tenant Support: Secure user isolation with Clerk OAuth authentication
🔍 Vector Search: Semantic similarity search using OpenAI embeddings
🔄 Automatic Embeddings: Auto-generates and updates embeddings on data changes
🏢 Entity Management: Track people, organizations, projects, and relationships
📚 Interaction History: Store and retrieve conversation history with context
📱 Contacts Sync: True bidirectional sync with macOS Contacts using LLM-based deduplication
🔄 Google Sync: Google Contacts and Calendar integration with incremental sync (v1.7.0+)
📅 Calendar Tracking: Week-based Google Calendar event sync with attendee linking
🌐 Web Interface: Modern Next.js web UI for visual memory management (staging on port 3002)
🔌 MCP Protocol: JSON-RPC 2.0 over stdio (local) and HTTP (remote)
🌐 REST API: HTTP interface for web applications
🔐 OAuth Integration: Clerk authentication for remote access with 95.2% test coverage
☁️ Cloud-Ready: Built for modern cloud deployment with Turso database
🔐 Security Patches: Critical user isolation vulnerabilities fixed in v1.7.1
📝 Smart Logging: LOG_LEVEL-aware logging with state tracking (v1.7.1+)

Architecture

src/
├── types/          # TypeScript type definitions
├── models/         # Data models and schemas
├── database/       # Database connection and operations
├── core/           # Core memory logic and vector search
├── mcp/           # MCP server implementation
├── api/           # REST API server
├── cli/           # CLI tool
├── utils/         # Utility functions
└── index.ts       # Main entry point

web/
├── app/           # Next.js app directory
├── components/    # React components
├── lib/           # Utilities and integrations
└── public/        # Static assets

Quick Start

Prerequisites

Node.js 18+
Turso database (or LibSQL compatible)
OpenAI API key (for embeddings)

Installation

# Clone and install dependencies
npm install

# Copy environment configuration
cp .env.local .env

# Build the project
npm run build

# Start development server
npm run dev

Environment Variables

Required variables in .env:

# Database Configuration
TURSO_URL=libsql://your-database.turso.io
TURSO_AUTH_TOKEN=your-auth-token

# OpenAI Configuration (for vector embeddings)
OPENAI_API_KEY=your-openai-api-key

# Optional Configuration
LOG_LEVEL=info              # Options: debug, info (default), warn, error (v1.7.1+)
MCP_DEBUG=0                 # Set to 1 for detailed MCP protocol debugging
DEFAULT_USER_EMAIL=user@example.com

# Automatic Embedding Updates (v1.1.0+)
ENABLE_EMBEDDING_MONITOR=true  # Enable background monitoring
EMBEDDING_MONITOR_INTERVAL=60000  # Check every 60 seconds

# Web Interface (v1.3.0+)
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=your-clerk-publishable-key
CLERK_SECRET_KEY=your-clerk-secret-key

# Google Integration (v1.7.0+)
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
GOOGLE_REDIRECT_URI=http://localhost:3002/api/auth/google/callback  # Use port 3002 for staging

Usage

MCP Server (for Claude Desktop)

Recommended: Using CLI Tool

# Install globally
npm install -g mcp-memory-ts

# Initialize configuration
mcp-memory init

# Install to Claude Desktop
mcp-memory install

# Check status
mcp-memory status

This creates a config in ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-memory-ts": {
      "command": "mcp-memory",
      "args": ["server"],
      "env": {
        "TURSO_URL": "your-database-url",
        "TURSO_AUTH_TOKEN": "your-auth-token",
        "OPENAI_API_KEY": "your-openai-key",
        "DEFAULT_USER_EMAIL": "user@example.com"
      }
    }
  }
}

Manual Setup

For development or manual configuration:

# Start MCP server
npm run mcp-server

# Or with debug logging
MCP_DEBUG=1 npm run mcp-server

# Or using CLI command
mcp-memory server --debug

Remote MCP Server (HTTP with OAuth)

For web applications and remote access with Clerk authentication:

# Start remote MCP server
npm run mcp-server-remote

The remote MCP server will be available at http://localhost:3003 with:

Authentication: Clerk OAuth session tokens
Multi-Tenant: Complete user isolation by email
Protocol: JSON-RPC 2.0 over HTTP
Security: Rate limiting, CORS, session management
Endpoints: /mcp (main), /health
Test Coverage: 95.2% pass rate (20/21 tests)

OAuth Setup

Get Clerk credentials from dashboard.clerk.com

Configure environment:

# Development Keys
CLERK_SECRET_KEY=your-clerk-test-secret-key
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_bmF0aXZlLW1hcm1vc2V0LTc0LmNsZXJrLmFjY291bnRzLmRldiQ

# Production Keys (when ready)
CLERK_SECRET_KEY=your-clerk-live-secret-key
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_live_Y2xlcmsuYWktbWVtb3J5LmFwcCQ

Start server:
```
npm run mcp-server-remote
```

Test with authentication:

curl -X POST http://localhost:3003/mcp \
  -H "Authorization: Bearer YOUR_CLERK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'

See docs/REMOTE_MCP_SETUP.md for detailed setup instructions.

Web Interface (v1.3.0+)

Modern Next.js web interface for visual memory management:

# Setup web interface
./scripts/setup-web.sh

# Start development server (port 3002 for staging)
./START_WEB_SERVER.sh

# Or manually
cd web
npm run dev -- -p 3002

# Production deployment with PM2
cd web && npm run build && cd ..
pm2 start ecosystem.config.cjs

The web interface will be available at:

Staging: http://localhost:3002 (development/testing)
Production: http://localhost:3001 (via PM2)

Features:

Authentication: Clerk OAuth for multi-user support
Visual Search: Interactive memory browser with semantic search
Entity Management: Visual relationship mapping
Real-time Sync: Bidirectional sync with MCP server
Contacts Integration: Import/export with LLM deduplication
Google Integration: Contacts and Calendar sync with OAuth

See docs/features/WEB_INTERFACE.md for complete setup and deployment guide.

REST API Server

# Start REST API server
npm run api-server

The API will be available at http://localhost:3000 with endpoints for:

/api/memories - Memory management
/api/entities - Entity management
/api/search - Vector and text search
/api/users - User management

Development

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Lint code
npm run lint

# Format code
npm run format

# Type checking
npm run type-check

Testing

The project includes comprehensive test coverage:

Unit Tests: Core functionality and utilities
Integration Tests: OAuth authentication, user isolation, MCP protocol
E2E Tests: Complete workflows and Claude Desktop integration
Test Results: 95.2% pass rate (20/21 tests passing)

See docs/testing/QA_TEST_REPORT.md for detailed test results.

Documentation

Core Documentation

CLAUDE.md - Project instructions and architecture
README.md - This file (project overview)

Guides

Deployment Guide - Production deployment
CLI Guide - Command-line interface
Contacts Sync Guide - Bidirectional sync with macOS Contacts
Contacts Sync Quick Start - Quick start for contacts sync
Google Setup Guide - Google Cloud setup and OAuth configuration
Google Contacts Sync Guide - Google Contacts sync with LLM deduplication
Google Calendar Sync Guide - Google Calendar week-based sync
Google Migration Guide - Migrate from macOS to Google sync
Migration Guide - Schema migrations

Features

Web Interface - Web UI setup and usage
Google Sync - Google integration overview and features
Contacts Sync Performance - Sync optimization

API Reference

Google API Reference - REST API for Google sync

Security

Clerk Implementation - Clerk setup guide
Clerk Migration - Auth migration guide
Security Fixes - v1.2.1 security patches

Deployment

Deployment Comparison - Compare deployment options

Schema & Database

Schema Optimization - Database design
Schema Analysis - Database structure

Testing & Quality

Verification Checklist - Deployment checklist
Migration Tests - Migration test results
QA Test Report - Quality assurance results

Additional Documentation

docs/ - Complete documentation library
- features/ - Feature documentation
- guides/ - User guides and quick starts
- security/ - Authentication and security
- deployment/ - Deployment options
- schema/ - Database schema documentation
- testing/ - Test reports and QA
- _archive/ - Archived documentation versions

License

MIT License - See LICENSE file for details.

Testing

Comprehensive Integrity Tests

A comprehensive test suite is available to verify data integrity and system reliability:

# Run the full test suite
tsx comprehensive-integrity-test.ts

The test suite validates:

Data integrity (type preservation, importance values, metadata)
Boundary conditions (volume, special characters, concurrent operations)
Recovery & reliability (updates, deletions, clear operations)
Search algorithms (single-word, multi-word, case insensitivity)
Production scenarios (session tracking, priority queues, date handling)

Expected results: 17/17 tests passed, 5/5 production criteria met

See docs/testing/ for detailed test results and analysis.

MCP Memory Service - TypeScript

MCP Memory Service - TypeScript

Features

Architecture

Quick Start

Prerequisites

Installation

Environment Variables

Usage

MCP Server (for Claude Desktop)

Remote MCP Server (HTTP with OAuth)

OAuth Setup

Web Interface (v1.3.0+)

REST API Server

Development

Testing

Documentation

Core Documentation

Guides

Features

API Reference

Security

Deployment

Schema & Database

Testing & Quality

Additional Documentation

License

Testing

Comprehensive Integrity Tests

Reviews