🧠 Memory Engineering MCP

📦 NPM Package | 📖 Documentation

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

🚀 Powered by voyage-code-3: The Code Understanding Model

voyage-code-3 is Voyage AI's specialized model that understands code like a senior developer:

• Syntax-Aware: Distinguishes between UserService.create() and User.create() - knows one is a service method, the other is a model method
• Cross-Language: Recognizes that Python's async def, JavaScript's async function, and Go's go func() all represent asynchronous patterns
• Semantic Relationships: Understands that hash_password() relates to verify_password(), salt, bcrypt, and security patterns
• Architecture Understanding: Knows that controllers → services → repositories → models represents a layered architecture

Real-World Impact

// Ask: "How do we handle authentication?"
// voyage-code-3 finds ALL of these (even without the word "auth"):
validateToken()      // JWT validation
checkSession()       // Session management  
requirePermission()  // Authorization
refreshTokens()      // Token refresh logic
loginUser()         // Login flow
// Traditional search would miss most of these!

✨ See It In Action

🔥 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:

1. activeContext - What you're doing RIGHT NOW (update every 3-5 min!)
2. projectbrief - Core requirements and features
3. systemPatterns - Architecture decisions and patterns
4. techContext - Stack, dependencies, constraints
5. progress - What's done, in-progress, and next
6. productContext - Why this exists, user needs
7. 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 Integration - Powered by voyage-code-3

Why voyage-code-3 Changes Everything

• Purpose-Built for Code: Unlike general models, voyage-code-3 understands syntax, patterns, and programming concepts
• 1024 Dimensions: Optimal balance between accuracy and performance
• Code-Aware Embeddings: Knows the difference between class Auth and authenticate() semantically
• Language Agnostic: Works across JavaScript, TypeScript, Python, Go, Rust, and more

Technical Capabilities

// voyage-code-3 understands these are related:
authenticate() → JWT.verify() → checkPermissions() → isAuthorized()

// Even without shared keywords, it knows:
"user login" → findByEmail() → bcrypt.compare() → generateToken()

// Understands code patterns:
try/catch → error handling → .catch() → Promise.reject()

Advanced Features

• Reranking with rerank-2.5-lite: Re-orders results by true relevance (8% accuracy boost)
• 32K Context Window: 8x larger than before for understanding long files
• Semantic Expansion: auth automatically searches for authentication, JWT, tokens, sessions
• Pattern Recognition: Identifies 27 architectural patterns automatically
• Smart Batching: Processes 100 chunks simultaneously for speed

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

🔬 voyage-code-3 vs Other Embedding Models

Technical Comparison

| Aspect | voyage-code-3 | General Models (text-embedding-3) | |--------|--------------|-----------------------------------| | Code Syntax | Understands AST-like structures | Treats code as text | | Variable Names | Knows userId ≈ user_id ≈ userID | Sees as different tokens | | Design Patterns | Recognizes Singleton, Factory, Repository | No pattern awareness | | Error Handling | Links try/catch ↔ .catch() ↔ error boundaries | Misses connections | | Import Relationships | Tracks dependency graphs | Ignores imports | | Context Window | 32K tokens (full files) | 8K tokens typical |

Benchmark Results

// Query: "user authentication"
// voyage-code-3 finds (relevance score):
verifyPassword()     // 0.94 - Understands auth concept
generateJWT()        // 0.92 - Knows JWT = auth token
checkPermissions()   // 0.89 - Links to authorization
validateSession()    // 0.87 - Session = auth state

// Generic model finds:
authenticateUser()   // 0.95 - Only exact match
userAuth()          // 0.88 - Keyword matching
// Misses everything else!

🎯 Real Power Examples

Finding Code You Forgot Exists

search --query "payment processing"
# voyage-code-3 finds: processPayment(), handleStripeWebhook(), validateCard()
# Even without 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 & Technical Metrics

Speed & Scale

• Code sync: 100 files/batch with voyage-code-3 embeddings
• Search latency: <500ms for 100k chunks with reranking
• Memory operations: <100ms read/write
• Reranking: +50ms for 23% better accuracy

voyage-code-3 Specifications

• Embedding dimensions: 1024 (optimal for code)
• Context window: 32K tokens (8x improvement)
• Languages supported: 50+ programming languages
• Pattern detection: 27 architectural patterns
• Accuracy boost: 15% over general models

Code Understanding Capabilities

// voyage-code-3 understands these are the SAME pattern:
// JavaScript
promise.then(result => {}).catch(err => {})
// Python
try: result = await async_func()
except Exception as err: handle_error(err)
// Go
if err := doSomething(); err != nil { return err }
// All recognized as: error-handling pattern

🎯 How voyage-code-3 Helps Different Tasks

Code Review & Refactoring

search --query "duplicate logic" --codeSearch "similar"
# Finds semantically similar code blocks that could be refactored

Debugging

search --query "null pointer exception possible" --codeSearch "pattern"
# Finds: optional chaining missing, unchecked nulls, unsafe access

Learning a New Codebase

search --query "entry point main initialization" --codeSearch "implements"
# Finds: main(), app.listen(), server.start(), bootstrap()

Security Audit

search --query "SQL injection vulnerable" --codeSearch "pattern"
# Finds: string concatenation in queries, unparameterized SQL

🔧 Advanced Features

Smart Pattern Aliasing (Enhanced by voyage-code-3)

The system understands natural language variations:

• "auth" → searches: authentication, authorization, login, JWT, token, session, OAuth
• "db" → searches: database, MongoDB, schema, model, collection, repository, ORM
• "error handling" → searches: try-catch, exception, error-handler, .catch(), Promise.reject

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

1. Complete Code Understanding: Unlike other systems that break functions arbitrarily, we preserve semantic units
2. Rich Embeddings: Each chunk has context, patterns, and relationships
3. Behavioral Prompting: Dramatic prompts ensure AI assistants take memory seriously
4. MongoDB Scale: Handles millions of chunks with millisecond queries
5. 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