Skip to main content
Glama
bobmatnyc

MCP Memory Service - TypeScript

by bobmatnyc
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Hybrid

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

  1. Get Clerk credentials from dashboard.clerk.com

  2. 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

  3. Start server:

    npm run mcp-server-remote

  4. 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

Guides

Features

API Reference

Security

Deployment

Schema & Database

Testing & Quality

Additional Documentation

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.

This server cannot be installed

-
security - not tested
F
license - not found
-
quality - not tested

How are these scores calculated?

Resources

New MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/bobmatnyc/mcp-memory-ts'

If you have feedback or need assistance with the MCP directory API, please join our Discord server