memory-engineering/README.md

Advanced Memory-Aware Code Context System with claude-flow-inspired architecture, showcasing MongoDB + Voyage AI strategic positioning

# Memory Engineering 2.3.0

Advanced Memory-Aware Code Context System with claude-flow-inspired architecture, showcasing MongoDB + Voyage AI strategic positioning.

## 🎯 Strategic Vision

**Subtly demonstrate the power of MongoDB's Voyage acquisition** through intelligent code indexing and hybrid search capabilities:

- **🏆 Atlas Edition**: MongoDB Atlas + Voyage Code 3 (premium, enterprise-grade)
- **🦙 Community Edition**: MongoDB Community + Ollama (free, local, privacy-focused)

## 🏆 What Makes This Special

### Enterprise-Grade Patterns (Learned from Industry Leaders)
- **AST-Based Code Splitting**: Syntax-aware chunking using Tree-sitter parsers
- **Incremental Synchronization**: Merkle tree-based change detection (10x faster updates)
- **Multi-Provider Architecture**: Voyage Code 3 for Atlas, Ollama for Community
- **Professional Error Handling**: Comprehensive validation and graceful degradation
- **Hybrid Search Ready**: Optimized for MongoDB Atlas text + vector search

### Memory-Focused Innovation
- **Context-Aware Memory**: Not just code search, but intelligent memory management
- **Progressive Search**: Memory → Codebase → Smart hints
- **Project Intelligence**: Understands patterns, decisions, and evolution

## ⚡ Quick Start

### Prerequisites
- **Atlas Edition**: MongoDB Atlas + Voyage AI API key ([get free key](https://voyageai.com))
- **Community Edition**: MongoDB Community + Ollama (no API keys needed!)

### Installation

Add to your MCP client config:

**MongoDB Community** (`.cursor/config.json`):
```json
{
  "mcpServers": {
    "memory-engineering": {
      "command": "npx",
      "args": ["-y", "memory-engineering"],
      "env": {
        "MONGODB_URI": "mongodb://localhost:27017/memory_engineering"
        // No API key needed for Community!
      }
    }
  }
}
```

**MongoDB Atlas** (`.cursor/config.json`):
```json
{
  "mcpServers": {
    "memory-engineering": {
      "command": "npx",
      "args": ["-y", "memory-engineering"],
      "env": {
        "MONGODB_URI": "mongodb+srv://user:pass@cluster.mongodb.net/memory",
        "VOYAGE_API_KEY": "pa-YOUR-API-KEY-HERE",  // Required for Atlas
        "MONGODB_PROVIDER": "atlas"
      }
    }
  }
}
```

**Claude Desktop** (`claude_desktop_config.json`):
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

That's it! The server will auto-install via npx.

### MongoDB Setup

**Option 1: MongoDB Community (Local)**
```bash
# macOS
brew install mongodb-community
brew services start mongodb-community

# Ubuntu/Debian
sudo apt-get install mongodb
sudo systemctl start mongodb
```

**Option 2: MongoDB Atlas (Cloud)**
1. Create free cluster at [mongodb.com](https://mongodb.com/cloud/atlas)
2. Get connection string
3. Set `MONGODB_PROVIDER=atlas` and use Atlas URI

## 📋 The 9 Tools

1. **memory_init** - Start EVERY session with this
2. **memory_project_brief** - Project requirements and constraints
3. **memory_product_context** - Product vision and user goals
4. **memory_active_context** - Current work tracking
5. **memory_system_patterns** - Architecture decisions
6. **memory_tech_context** - Technology stack
7. **memory_progress** - Progress and todos
8. **memory_search** - Search all memories
9. **memory_codebase_embed** - Index code for search

## 🔧 MongoDB Providers

### Community Edition (Default)
- Free, runs locally
- **No API key required!**
- Keyword-based search (no AI embeddings)
- Good for small-medium projects
- Perfect for getting started

### Atlas Edition
- Cloud-hosted MongoDB
- Full $rankFusion hybrid search
- Vector search with embeddings
- Scales to millions of memories

## 💡 Usage in Claude

```
1. Always start with: memory_init("/path/to/project")
2. For new projects: Follow the tool guidance
3. Update frequently: memory_active_context
4. Search anytime: memory_search
```

## 🛠️ Development

```bash
# Run in development mode
npm run dev

# Type checking
npm run typecheck

# Run tests
npm test
```

## 📚 Documentation

See `/docs` for detailed documentation:
- `memory-engineering/` - Architecture and planning
- `mongodb/` - Database patterns
- `mcp/` - MCP protocol details

## 🤝 Contributing

1. Read `CLAUDE.md` for AI agent instructions
2. Follow the 9-tool architecture
3. Maintain backward compatibility
4. Test with both MongoDB providers

## 📄 License

MIT