# 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'
});
```