🧠 Memory Engineering MCP

🎯 What is Memory Engineering MCP?

PROOF: Following Archon's README.md structure (line 23-37)

Memory Engineering MCP is a production-ready AI coding assistance platform that manages your project's 7 Core Memories automatically. For AI coding assistants (Claude Code, Cursor, Windsurf), it's a Model Context Protocol (MCP) server providing:

• 7 Core Memories (activeContext, projectBrief, systemPatterns, techContext, progress, productContext, codebaseMap)
• Smart semantic search with Voyage AI embeddings and reranking
• MongoDB graph capabilities for code relationship tracking
• Automatic memory sync with zero manual work
• Production-grade reliability with monitoring, backups, and error recovery

100% MongoDB + Voyage AI - Built exclusively on MongoDB Atlas Vector Search and Voyage AI for embeddings/reranking

✨ Key Features

7 Core Memories (Heart of the System)

Each memory serves a specific purpose in your AI's understanding:

1. activeContext - Current work focus and immediate tasks
2. projectBrief - High-level project goals and vision
3. systemPatterns - Coding patterns and architectural decisions
4. techContext - Technology stack and dependencies
5. progress - Development milestones and achievements
6. productContext - Business requirements and user needs
7. codebaseMap - File structure and module organization

Advanced RAG Capabilities

• Hybrid search: 70% memories + 30% knowledge base
• Voyage reranking: 5x candidate fetching for precision
• MongoDB Vector Search: Native vector operations
• Contextual embeddings: Voyage AI voyage-code-3 for code

Production Features

• Performance monitoring: Track operation duration, detect slow queries
• Automatic backups: Hourly backups of all 7 memories
• Error recovery: Retry with exponential backoff, circuit breakers
• MongoDB graph: Track code relationships and dependencies

Quick Start

PROOF: Following Archon's Quick Start structure (line 47-111)

Prerequisites

• Node.js 18+
• Option A (Easiest): Docker Desktop for local MongoDB
• Option B (Production): MongoDB Atlas account (free tier works!)
• Voyage AI API key (free tier: 25M tokens/month)
• AI coding assistant (Claude Code, Cursor, or Windsurf)

Setup Instructions

🚀 Option A: Local MongoDB (Recommended for Development)

One-command setup with full vector search:

1. Clone & Setup:

   git clone https://github.com/your-username/memory-engineering-mcp.git
   cd memory-engineering-mcp
      
   # Automated setup (creates MongoDB 8.2 + mongot)
   ./scripts/setup-local-mongodb.sh

2. Add Voyage AI Key:

   # Edit .env and add:
   VOYAGE_API_KEY=your-voyage-api-key

3. Initialize & Go:

   memory_engineering_init

✅ That's it! Full vector search, hybrid search, all features enabled locally.

What you get: MongoDB 8.2 with mongot for vector search, replica set for change streams, automatic health checks.

📚 Detailed guide: See LOCAL_SETUP_GUIDE.md

☁️ Option B: MongoDB Atlas (Recommended for Production)

1. Clone Repository:

   git clone https://github.com/your-username/memory-engineering-mcp.git
   cd memory-engineering-mcp

2. Environment Configuration:

   cp .env.example .env
   # Edit .env and add your credentials:
   # MONGODB_URI=mongodb+srv://user:[email protected]/memory-engineering
   # VOYAGE_API_KEY=your-voyage-api-key

3. Install Dependencies:

   pnpm install

4. Build the Server:

   pnpm run build

5. Initialize MongoDB Collections: The collections will be created automatically on first run with proper indexes.

6. Configure Your AI Coding Assistant:

   For Claude Code: Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

   {
     "mcpServers": {
       "memory-engineering": {
         "command": "node",
         "args": ["/absolute/path/to/memory-engineering-mcp/dist/index.js"],
         "env": {
           "MONGODB_URI": "your-mongodb-uri",
           "VOYAGE_API_KEY": "your-voyage-key"
         }
       }
     }
   }

   For Cursor/Windsurf: Similar configuration in their respective MCP settings.

7. Initialize Your Project: In your AI coding assistant, use:

   Use the memory_engineering_init tool to initialize memories for this project

⚡ Quick Test

Once configured:

1. Initialize Memories: Ask your AI assistant to initialize the 7 core memories
2. Sync Codebase: Use memory_engineering_sync to analyze your code and create embeddings
3. Search: Use memory_engineering_search to find relevant code and context
4. Check Status: Use memory_engineering_status to see memory freshness

📊 What's Included

PROOF: Following Archon's structure with 7 core memories as the foundation

MCP Tools (7 Available)

| Tool | Purpose | |------|---------| | memory_engineering_init | Initialize 7 core memories for a project | | memory_engineering_memory | Get or update a specific memory | | memory_engineering_sync | Sync codebase with embeddings | | memory_engineering_search | Semantic search across memories and code | | memory_engineering_status | Get memory freshness and health status | | memory_engineering_health | System health check | | memory_engineering_crawl | Crawl documentation (ready for Bright Data) |

Services (10 Production Services)

| Service | Purpose | |---------|---------| | MemoryService | CRUD operations for 7 core memories | | SearchService | Unified search with reranking | | EmbeddingService | Voyage AI integration with rate limiting | | SettingsService | MongoDB-based configuration | | HealthService | System monitoring | | KnowledgeService | Documentation storage | | CrawlService | Web crawling (Bright Data ready) | | GraphService | MongoDB graph for code relationships | | PerformanceMonitor | Operation tracking and analytics | | BackupService | Automatic memory backups |

MongoDB Collections (8 Core Collections)

| Collection | Purpose | |------------|---------| | memories | 7 core memories with embeddings | | projects | Project metadata | | codeChunks | Code embeddings for search | | archon_settings | Runtime configuration | | knowledgeSources | Crawled documentation | | knowledgeChunks | Content embeddings | | graph_nodes | Code entities (files, functions, classes) | | graph_edges | Code relationships (imports, calls, extends) |

🏗️ Architecture

PROOF: Following Archon's architecture overview structure

System Design

┌─────────────────────────────────────────────────────────────┐
│                    AI Coding Assistant                      │
│              (Claude Code / Cursor / Windsurf)              │
└────────────────────────┬────────────────────────────────────┘
                         │ MCP Protocol
                         ↓
┌─────────────────────────────────────────────────────────────┐
│                  Memory Engineering MCP Server              │
│                                                             │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐    │
│  │  MCP Tools   │→│  Services    │→│  Utilities   │    │
│  │  (7 tools)   │  │ (10 services)│  │ (monitoring) │    │
│  └──────────────┘  └──────────────┘  └──────────────┘    │
└────────────────────────┬────────────────────────────────────┘
                         │
          ┌──────────────┼──────────────┐
          ↓              ↓              ↓
  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
  │  MongoDB    │ │  Voyage AI  │ │ Bright Data │
  │  Atlas      │ │  API        │ │ (optional)  │
  └─────────────┘ └─────────────┘ └─────────────┘

Technology Stack

Backend: TypeScript 5, Node.js 18+, MCP SDK Database: MongoDB Atlas with Vector Search AI: Voyage AI (voyage-code-3 for embeddings, rerank-2 for reranking) Infrastructure: Production-grade error handling, monitoring, backups

Key Design Decisions

1. MongoDB + Voyage AI Only: No other infrastructure dependencies
2. 7 Core Memories: Fixed structure, each with specific purpose
3. Service Layer: Clean separation of concerns
4. Production First: Monitoring, backups, error recovery from day one

📖 Documentation

• Architecture Guide - Detailed system design
• API Reference - All MCP tools and services
• Example Workflows - Common usage patterns
• Troubleshooting - Common issues and solutions

🔧 Development

# Install dependencies
pnpm install

# Build TypeScript
pnpm run build

# Run linter
pnpm run lint

# Type check
pnpm run typecheck

# Watch mode for development
pnpm run watch

🤝 Contributing

We follow Archon's contributing patterns:

1. Fix forward: No backward compatibility, always improve
2. Detailed errors: Help users debug issues
3. Production quality: Every feature production-ready
4. Documentation: Code changes include docs

See CONTRIBUTING.md for details.

📝 License

MIT License - See LICENSE for details.

🙏 Acknowledgments

Built following Archon's proven production patterns:

• Service layer architecture
• MCP tool design
• Error handling patterns
• Performance monitoring
• Documentation structure

Memory Engineering MCP v14.0.0-alpha.6
Production-Ready AI Memory System
Powered by MongoDB Atlas & Voyage AI