mongodb-memory-bank-mcp-v2/README.md

MongoDB-powered Memory Bank MCP server with hybrid search capabilities for AI assistants

# Memory Bank MCP Server

[![npm version](https://badge.fury.io/js/mongodb-memory-bank-mcp.svg)](https://www.npmjs.com/package/mongodb-memory-bank-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A MongoDB-powered Memory Bank MCP (Model Context Protocol) server that creates an intelligent, project-aware memory system for AI assistants. Built with MongoDB Atlas Vector Search's hybrid search capabilities.

## What It Does

This MCP server provides AI assistants with persistent memory across sessions by:
- Storing structured project documentation in MongoDB
- Using vector embeddings for semantic search
- Combining vector and text search for powerful hybrid queries
- Maintaining strict project isolation
- Providing tools for reading, updating, and searching memories

## Features

- 🧠 **Intelligent Memory System** - Structured documentation that evolves with your project
- 🔍 **Hybrid Search** - Combines MongoDB's vector and text search capabilities
- 🏗️ **Project Isolation** - Each project maintains its own memory space
- 🚀 **High-Performance** - Leverages MongoDB indexes and Voyage AI embeddings
- 🔧 **MCP Integration** - Works seamlessly with Claude and other MCP-compatible AI assistants

## Installation

### Prerequisites

- Node.js 18+ 
- MongoDB Atlas cluster with Vector Search enabled
- Voyage AI API key

### Quick Start (Recommended)

Run directly with npx (no installation needed):

```bash
# Set environment variables
export MONGODB_URI="your-mongodb-uri"
export VOYAGE_API_KEY="your-voyage-key"

# Run the server
npx mongodb-memory-bank-mcp
```

Or configure in Claude's MCP settings:
```json
{
  "mcpServers": {
    "memory-bank": {
      "command": "npx",
      "args": ["mongodb-memory-bank-mcp"],
      "env": {
        "MONGODB_URI": "your-mongodb-uri",
        "VOYAGE_API_KEY": "your-voyage-key"
      }
    }
  }
}
```

### Local Development

1. Clone the repository:
```bash
git clone https://github.com/romiluz13/mongodb-memory-bank-mcp.git
cd mongodb-memory-bank-mcp
```

2. Install dependencies:
```bash
pnpm install
```

3. Configure environment:
```bash
cp .env.example .env.local
# Edit .env.local with your MongoDB URI and Voyage AI key
```

4. Build the project:
```bash
pnpm build
```

5. Create MongoDB indexes:
```bash
pnpm db:indexes
```

## Running Locally

### Development Mode
```bash
pnpm dev
```

### Testing with MCP Inspector
```bash
pnpm mcp:inspect
```

### Running Tests
```bash
pnpm test
```

## Usage with Claude

Add to your Claude MCP settings:

```json
{
  "mcpServers": {
    "mongodb-memory-bank-mcp": {
      "command": "npx",
      "args": ["mongodb-memory-bank-mcp-v2"],
      "env": {
        "MONGODB_URI": "your-mongodb-uri",
        "VOYAGE_API_KEY": "your-voyage-key"
      }
    }
  }
}
```

## Version 1.3.0 - Context Engineering REVOLUTION! 🚀

### Feature Blueprints - Your New SUPERPOWER!
- **🎯 Validation Gates**: Ensure production-ready code EVERY time
- **📊 Confidence Scoring**: Know exactly when to ship (0-10 scale)
- **🔍 Pattern Discovery**: Find similar features with MongoDB hybrid search
- **✅ Multi-Level Validation**: TypeScript → Tests → Integration → Production
- **🧠 Context Engineering**: 100x better than prompt engineering!

### Quick Start with Feature Blueprints
```bash
# Create a new feature blueprint
memory_bank/feature --action create --name "user-authentication"

# Validate your implementation
memory_bank/feature --action validate --name "user-authentication"

# Find similar patterns
memory_bank/feature --action search --name "auth"
```

## Version 1.2.0 - AI-Optimized Memory Bank!

### v1.2.0 Features - The Final 5%!
- **🎯 Smart Search Previews**: Shows actual matching context, not just first 200 chars
- **🧠 AI-Focused Templates**: Rich prompts helping AI understand project context better
- **🔗 Auto-Reference Detection**: Automatically finds relationships between memory files
- **📊 Content Stats**: Shows file size and version in search results
- **⏰ Access Tracking**: Tracks last accessed time for freshness
- **💡 Better Memory Structure**: Each file now has AI-specific guidance sections

### v1.1.1 Fixes
- **Fixed Hybrid Search Scoring**: Proper handling of $rankFusion RRF scores
- **Score Safety**: All score values now safely handle undefined cases
- **100% Search Coverage**: Vector, text, and hybrid all working perfectly

### v1.1.0 Features
- **MongoDB $rankFusion**: Official MongoDB 8.1 operator for hybrid search
- **Reciprocal Rank Fusion**: Intelligent result ranking algorithm
- **Weighted Scoring**: Configurable weights (default: 70% vector, 30% text)
- **Atlas Search Integration**: Full-text search with Atlas Search indexes

### v1.0.1 Fixes
- Fixed vector search index naming mismatch
- Fixed hybrid search filter configuration
- Improved search reliability

## Memory Structure

The memory bank uses six core files:
- `projectbrief.md` - Foundation document
- `productContext.md` - Why the project exists
- `activeContext.md` - Current work focus
- `systemPatterns.md` - Architecture decisions
- `techContext.md` - Technology stack
- `progress.md` - What works and what's next

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines.

## Documentation

- [CLAUDE.md](CLAUDE.md) - Detailed project context and rules
- [WORKFLOWS/](WORKFLOWS/) - Reusable automation recipes
- [ONBOARDING.md](ONBOARDING.md) - Getting started guide

## License

MIT