memory-engineering-mcp

🧠 Memory Engineering MCP

📦 NPM Package | 💬 Discord | 📖 Documentation

Persistent memory and semantic code understanding for AI assistants. Built on MongoDB Atlas Vector Search and Voyage AI embeddings.

✨ See It In Action

Experience the power of semantic code search and persistent AI memory

🔥 The Game Changer: Code Embeddings

This is what makes Memory Engineering different from everything else:

Revolutionary Code Chunking

• Smart Semantic Boundaries: Tracks braces, parentheses, and indentation to capture COMPLETE functions (up to 200 lines) and classes (up to 300 lines)
• Context-Aware: Every chunk includes its imports, dependencies, and surrounding context
• Pattern Detection: Automatically identifies 27 code patterns (error-handling, async, authentication, etc.)

Why This Matters

// Traditional chunking BREAKS this function in half:
function processPayment(order) {  // <- Chunk 1 ends here
  validateOrder(order);           // <- Chunk 2 starts here, loses context!
  // ... 50 more lines
}

// Our chunking keeps it COMPLETE:
function processPayment(order) {  // <- Full function preserved
  validateOrder(order);           
  // ... entire function included
}                                 // <- Chunk ends at semantic boundary

Semantic Code Search That Actually Works

# Find similar implementations
search --query "JWT refresh" --codeSearch "similar"

# Find who implements an interface
search --query "AuthProvider" --codeSearch "implements"  

# Find usage patterns
search --query "error handling" --codeSearch "pattern"

# Natural language → Code
search --query "how do we validate users"
# Automatically searches: authenticate, verify, check, validate patterns

🧠 The 7 Core Memories

Inspired by Cline, but enhanced with MongoDB persistence:

• activeContext - What you're doing RIGHT NOW (update every 3-5 min!)
• projectbrief - Core requirements and features
• systemPatterns - Architecture decisions and patterns
• techContext - Stack, dependencies, constraints
• progress - What's done, in-progress, and next
• productContext - Why this exists, user needs
• codebaseMap - File structure with embedded statistics

💪 Technical Architecture

MongoDB Atlas Integration

• Vector Search: 1024-dimensional embeddings with cosine similarity
• Hybrid Search: Combines semantic + keyword search
• Auto-indexing: Manages compound, text, and vector indexes automatically
• Connection pooling: 5-100 connections with retry logic

Voyage AI Embeddings

• Model: voyage-3 (1024 dimensions)
• Contextualized: Each chunk knows about surrounding code
• Batch processing: 100 chunks at a time for efficiency
• Smart caching: Only re-embeds changed files

Code Intelligence

// What gets captured in each chunk:
interface CodeChunk {
  chunk: {
    type: 'function' | 'class' | 'method' | 'module';
    signature: string;      // Full signature with params
    content: string;        // Complete code
    context: string;        // Imports and dependencies
    startLine: number;
    endLine: number;
  };
  contentVector: number[];  // 1024-dim embedding
  metadata: {
    patterns: string[];     // Detected patterns
    dependencies: string[]; // What it imports
    exports: string[];      // What it exports
  };
}

⚡ Quick Start

Installation

npm install -g memory-engineering-mcp

Configure Cursor/.cursor/mcp.json

{
  "mcpServers": {
    "memory-engineering-mcp": {
      "command": "npx",
      "args": ["memory-engineering-mcp"],
      "env": {
        "MONGODB_URI": "your-mongodb-atlas-uri",
        "VOYAGE_API_KEY": "your-voyage-api-key"
      }
    }
  }
}

First Run

# Initialize (scans entire codebase, generates embeddings)
memory_engineering_init

# Now search your code semantically!
memory_engineering_search --query "authentication flow" --codeSearch "pattern"

# Update memories as you work
memory_engineering_memory --name activeContext --content "Fixed JWT expiry..."

🎯 Real Power Examples

Finding Code You Forgot Exists

search --query "payment processing"
# Finds: processPayment(), handleStripeWebhook(), validateCard()
# Even if you never used the word "payment" in those functions!

Understanding Patterns Across Codebase

search --query "error" --codeSearch "pattern"
# Returns ALL error handling patterns:
# - try/catch blocks
# - .catch() handlers  
# - error middleware
# - validation errors

Tracking Decisions

search --query "why Redis"
# Finds the exact activeContext entry where you decided to use Redis
# "Chose Redis for session storage because: 1) Fast lookups 2) TTL support..."

📊 Performance Metrics

• Code sync: Processes files with embeddings in batches of 100
• Search latency: <500ms for 100k chunks
• Memory operations: <100ms
• Embedding dimensions: 1024 (voyage-3 model)
• Chunk sizes: 80-300 lines (adaptive, default 80)
• Pattern detection: 27 patterns recognized

🔧 Advanced Features

Smart Pattern Aliasing

The system understands natural language variations:

• "auth" → searches: authentication, authorization, login, JWT, token
• "db" → searches: database, MongoDB, schema, model, collection
• "error handling" → searches: try-catch, exception, error-handler

Incremental Sync

Only changed files are re-embedded:

// Detects changes via:
- File modification time
- Content hash comparison  
- Git diff integration
- Automatic after 24h gap

Context Preservation

Every code chunk maintains context:

// Original file:
import { User } from './models';
import bcrypt from 'bcrypt';

class AuthService {
  async validateUser(email: string, password: string) {
    // ... implementation
  }
}

// Chunk includes:
- Imports (User, bcrypt)
- Class context (AuthService)
- Full method implementation
- Patterns detected: ["authentication", "async", "validation"]

🛠️ Tools Reference

Tool	Purpose	Key Features
memory_engineering_init	Initialize project	Scans code, creates memories, generates embeddings
memory_engineering_memory	Read/Update memories	Unified interface for all 7 memories
memory_engineering_search	Semantic search	Memory + code search with patterns
memory_engineering_sync	Sync code embeddings	Smart chunking, incremental updates
memory_engineering_system	Health & diagnostics	Status, environment, doctor mode

🚀 Why This Works

• Complete Code Understanding: Unlike other systems that break functions arbitrarily, we preserve semantic units
• Rich Embeddings: Each chunk has context, patterns, and relationships
• Behavioral Prompting: Dramatic prompts ensure AI assistants take memory seriously
• MongoDB Scale: Handles millions of chunks with millisecond queries
• Voyage AI Quality: State-of-the-art embeddings optimized for code

📦 Latest Updates

v13.4.0 (January 2025)

• Enhanced memory quality with structured templates
• Improved pattern detection in code embeddings (now 27 patterns)
• Better validation for consistent memory creation
• All improvements are backwards compatible

v13.3.2

• Consolidated tools for simpler interface
• Performance optimizations

📄 License

MIT - See LICENSE file

🔗 Links

• NPM Package
• GitHub Repository
• MongoDB Atlas
• Voyage AI

Built with Model Context Protocol (MCP) by Anthropic