memory-engineering

Memory Engineering - AI Memory MCP Server

A Model Context Protocol (MCP) server that provides persistent memory and codebase understanding for AI coding assistants like Claude Code and Cursor.

🚀 Quick Start with npx

# Run directly without installation
npx memory-engineering

# Or install globally
npm install -g memory-engineering
memory-engineering

🎯 Key Features

• Fixed Memory Slots: 20 memories per project (5 per type) to prevent infinite growth
• Smart Updates: Memories update based on similarity (>85% threshold) instead of creating duplicates
• Project Isolation: Each project has its own memory namespace using path hashing
• Hybrid Search: Combines vector embeddings with keyword search for better retrieval
• Codebase Understanding: Indexes and embeds your entire codebase for semantic search
• Automatic Relevance Decay: Memories become less relevant over time if not updated

📋 Prerequisites

• Node.js v18 or higher
• MongoDB (local or Atlas)
• Voyage AI API key (optional, fallback available)

📦 Installation Options

Option 1: Use with npx (Recommended)

npx memory-engineering

Option 2: Global Installation

npm install -g memory-engineering
memory-engineering

Option 3: Local Development

git clone https://github.com/romiluz13/memory-engineering.git
cd memory-engineering
npm install
npm run build
npm start

⚙️ Configuration

Create .env file in your project root:

MONGODB_URI=mongodb://localhost:27017/ai_memory
VOYAGE_API_KEY=your_voyage_api_key_here  # Optional
MAX_MEMORIES_PER_TYPE=5
SIMILARITY_THRESHOLD=0.85
CHUNK_SIZE=500
CHUNK_OVERLAP=50

For Claude Desktop

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["memory-engineering"],
      "env": {
        "MONGODB_URI": "mongodb://localhost:27017/ai_memory",
        "VOYAGE_API_KEY": "your_api_key"
      }
    }
  }
}

For Cursor

Add to your .cursor/mcp.json:

{
  "servers": {
    "memory": {
      "command": "npx",
      "args": ["memory-engineering"],
      "cwd": "${workspaceFolder}"
    }
  }
}

📚 Memory Types

1. Context Memory (5 slots)

• Project structure and architecture
• Tech stack and dependencies
• Coding conventions
• Business logic
• Design decisions

2. Task Memory (5 slots)

• Recent implementations
• Problem-solving patterns
• Bug fixes
• Feature development
• Refactoring decisions

3. Pattern Memory (5 slots)

• Common code patterns
• API patterns
• Database queries
• Error handling
• Testing patterns

4. Issue Memory (5 slots)

• Known issues and fixes
• Performance optimizations
• Security considerations
• Debugging insights
• Edge cases

🛠️ Available Tools

memory_save

Save or update a memory slot:

{
  type: "context", // or "task", "pattern", "issue"
  content: "Project uses React 18 with TypeScript...",
  keywords: ["react", "typescript"],
  files: ["src/App.tsx"]
}

memory_search

Search memories using semantic + keyword search:

{
  query: "authentication implementation",
  type: "task", // optional filter
  limit: 5
}

memory_list

List all project memories:

{
  type: "pattern" // optional filter
}

codebase_search

Semantic search through codebase:

{
  query: "database connection",
  filePattern: "*.ts", // optional
  limit: 10
}

codebase_index

Index or re-index the codebase:

{
  rescan: true // force full rescan
}

project_summary

Get a summary of all project memories.

🔄 How It Works

Memory Update Strategy

1. New Memory Arrives → Embed it
2. Find Similar Memories → Compare embeddings
3. Decision Logic:
   • Similarity > 85%: Merge with existing
   • Similarity 50-85%: Ask which slot to replace
   • Similarity < 50%: Replace least relevant slot

Codebase Indexing

1. File Discovery: Scans for code files (ignores node_modules, dist, etc.)
2. Chunking: Splits files into 500-line chunks with 50-line overlap
3. Embedding: Uses Voyage AI's code model for embeddings
4. Caching: Only re-indexes changed files (MD5 hash comparison)

Project Isolation

projectId = SHA256(absolute_project_path).substring(0, 16)

Each project gets a unique ID based on its absolute path, ensuring complete isolation.

🏗️ Architecture

memory-mcp-server/
├── src/
│   ├── index.ts           # MCP server implementation
│   ├── db/
│   │   └── connection.ts  # MongoDB connection with retry
│   ├── services/
│   │   ├── memory.ts      # Memory CRUD operations
│   │   ├── embedding.ts   # Voyage AI integration
│   │   └── codebase.ts    # Code indexing service
│   └── types/
│       └── memory.ts      # TypeScript types
├── .env                   # Configuration
├── package.json
└── tsconfig.json

🐛 Troubleshooting

MongoDB Connection Issues

• Ensure MongoDB is running: mongod
• Check connection string in .env
• Verify network access for Atlas

Embedding Failures

• The server works without Voyage API key (uses fallback)
• Check API key validity
• Monitor rate limits

Memory Not Updating

• Check similarity threshold (default 0.85)
• Verify project path consistency
• Look for MongoDB write errors

Performance Issues

• Reduce CHUNK_SIZE for large codebases
• Increase CHUNK_OVERLAP for better context
• Clear old indexes: db.codebase_chunks.drop()

📊 Monitoring

Logs are written to stderr and include:

• [MongoDB] - Database operations
• [Embedding] - Embedding service status
• [Memory] - Memory operations
• [Codebase] - Indexing progress
• [Memory MCP] - Server status

🔐 Security

• Project isolation via hashing
• No cross-project data leakage
• Credentials in environment variables
• MongoDB connection retry with backoff
• Graceful degradation on API failures

📈 Performance Optimizations

• Lazy Loading: Memories loaded on demand
• Batch Embeddings: Process multiple texts together
• Embedding Cache: In-memory cache for repeated queries
• Incremental Indexing: Only changed files re-indexed
• Connection Pooling: Reuses MongoDB connections

🤝 Contributing

1. Fork the repository
2. Create your feature branch
3. Test thoroughly with real projects
4. Submit a pull request

📄 License

MIT

🙏 Acknowledgments

• Built for Claude Code and Cursor
• Powered by Voyage AI embeddings
• Uses MongoDB for persistence
• Implements Model Context Protocol

⚠️ Important Notes

1. First Run: Will initialize 20 empty memory slots
2. Codebase Indexing: Run codebase_index on first use
3. Memory Lifecycle: Memories decay in relevance over time
4. Project Switching: Each project maintains separate memories
5. Backup: Regular MongoDB backups recommended

🚦 Quick Start Example

// 1. Save project context
await mcp.call('memory_save', {
  type: 'context',
  content: 'This is a Next.js 14 app with App Router...',
  keywords: ['nextjs', 'react', 'typescript']
});

// 2. Index the codebase
await mcp.call('codebase_index', { rescan: true });

// 3. Search for patterns
await mcp.call('memory_search', {
  query: 'authentication flow'
});

// 4. Search codebase
await mcp.call('codebase_search', {
  query: 'API endpoints',
  filePattern: '*.ts'
});