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 ```bash # 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) ```bash npx memory-engineering ``` ### Option 2: Global Installation ```bash npm install -g memory-engineering memory-engineering ``` ### Option 3: Local Development ```bash 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: ```env 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: ```json { "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`: ```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: ```javascript { 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: ```javascript { query: "authentication implementation", type: "task", // optional filter limit: 5 } ``` ### `memory_list` List all project memories: ```javascript { type: "pattern" // optional filter } ``` ### `codebase_search` Semantic search through codebase: ```javascript { query: "database connection", filePattern: "*.ts", // optional limit: 10 } ``` ### `codebase_index` Index or re-index the codebase: ```javascript { 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 ```javascript 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](https://claude.ai/code) and [Cursor](https://cursor.sh) - Powered by [Voyage AI](https://voyageai.com) embeddings - Uses [MongoDB](https://mongodb.com) for persistence - Implements [Model Context Protocol](https://modelcontextprotocol.io) ## ⚠️ 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 ```typescript // 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' }); ```