🧠 Memory Engineering MCP

AI Memory System powered by MongoDB Atlas & Voyage AI - Autonomous memory management with zero manual work

🚀 Quick Start (3 min) •
What's Included •
Architecture •
Local Setup Guide •
Troubleshooting

---

🎯 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

$3

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

$3

- 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

$3

- 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)

$3

- 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)

$3

#### 🚀 Option A: Local MongoDB (Recommended for Development)

One-command setup with full vector search:

1. Clone & Setup:
``bash
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:
`bash
# Edit .env and add:
VOYAGE_API_KEY=your-voyage-api-key
`

3. Initialize & Go:
`bash
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:
`bash
git clone https://github.com/your-username/memory-engineering-mcp.git
cd memory-engineering-mcp
`

2. Environment Configuration:
`bash
cp .env.example .env
# Edit .env and add your credentials:
# MONGODB_URI=mongodb+srv://user:pass@cluster.mongodb.net/memory-engineering
# VOYAGE_API_KEY=your-voyage-api-key
`

3. Install Dependencies:
`bash
pnpm install
`

4. Build the Server:
`bash
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):
`json
{
"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

$3

| 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) |

$3

| 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 |

$3

| 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

$3

`
┌─────────────────────────────────────────────────────────────┐
│ 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) │
└─────────────┘ └─────────────┘ └─────────────┘
`

$3

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

$3

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

`bash


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