Content
# 🧠 Memory Engineering MCP
[](https://www.npmjs.com/package/memory-engineering-mcp)
[](https://opensource.org/licenses/MIT)
<div align="center">
<a href="https://memory-engineering-mcp.vercel.app">
<img src="https://img.shields.io/badge/🚀_Visit_Landing_Page-FF6B6B?style=for-the-badge&logoColor=white" alt="Landing Page" height="40"/>
</a>
<br/>
[**📦 NPM Package**](https://www.npmjs.com/package/memory-engineering-mcp) |
[**📖 Documentation**](#-quick-start)
</div>
<br/>
**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
```javascript
// 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
<div align="center">
<a href="https://memory-engineering-mcp.app">
<img src="https://img.shields.io/badge/🌐_Interactive_Demo-4A90E2?style=for-the-badge" alt="Try Demo" />
</a>
<p><i>Experience the power of semantic code search and persistent AI memory</i></p>
</div>
## 🔥 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
```javascript
// 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
```bash
# 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
```javascript
// 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
```typescript
// 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
```bash
npm install -g memory-engineering-mcp
```
### Configure Cursor/.cursor/mcp.json
```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
```bash
# 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
```javascript
// 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
```bash
search --query "payment processing"
# voyage-code-3 finds: processPayment(), handleStripeWebhook(), validateCard()
# Even without the word "payment" in those functions!
```
### Understanding Patterns Across Codebase
```bash
search --query "error" --codeSearch "pattern"
# Returns ALL error handling patterns:
# - try/catch blocks
# - .catch() handlers
# - error middleware
# - validation errors
```
### Tracking Decisions
```bash
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
```javascript
// 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
```bash
search --query "duplicate logic" --codeSearch "similar"
# Finds semantically similar code blocks that could be refactored
```
### Debugging
```bash
search --query "null pointer exception possible" --codeSearch "pattern"
# Finds: optional chaining missing, unchecked nulls, unsafe access
```
### Learning a New Codebase
```bash
search --query "entry point main initialization" --codeSearch "implements"
# Finds: main(), app.listen(), server.start(), bootstrap()
```
### Security Audit
```bash
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:
```javascript
// Detects changes via:
- File modification time
- Content hash comparison
- Git diff integration
- Automatic after 24h gap
```
### Context Preservation
Every code chunk maintains context:
```typescript
// 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](LICENSE) file
## 🔗 Links
- [NPM Package](https://www.npmjs.com/package/memory-engineering-mcp)
- [GitHub Repository](https://github.com/romiluz13/memory-engineering-mcp)
- [MongoDB Atlas](https://www.mongodb.com/atlas)
- [Voyage AI](https://voyageai.com)
---
*Built with Model Context Protocol (MCP) by Anthropic*
