🧠 Memory Forge - Universal AI Context & Memory System

![smithery badge](https://smithery.ai/server/@cpretzinger/ai-assistant-simple) ![MIT License](https://opensource.org/licenses/MIT)

A production-ready MCP (Model Context Protocol) server for persistent AI memory across Claude, ChatGPT, and any LLM.

🎯 What is Memory Forge?

Memory Forge is a complete infrastructure solution that gives AI assistants persistent memory and context awareness. It includes:

MCP Server: TypeScript-based context server following the Model Context Protocol
Multi-Storage: PostgreSQL for persistence + Redis for speed + Qdrant for vector search
Auto-Save: Automatic conversation backup every 30 seconds
Multi-User: Support for unlimited users with isolated contexts
Deploy Anywhere: Local Docker, Railway, Vercel, or Smithery

🚀 Quick Start (Under 5 Minutes!)

Option 1: One-Command Setup (Recommended)

curl -sSL https://raw.githubusercontent.com/cpretzinger/memory-forge/main/scripts/setup.sh | bash

Option 2: Manual Setup

git clone https://github.com/cpretzinger/memory-forge.git
cd memory-forge
npm install
npm run setup

📦 What's Included

memory-forge/
├── src/                    # TypeScript source code
│   ├── server.ts          # Main MCP server
│   ├── handlers/          # Request handlers
│   ├── storage/           # Storage adapters
│   └── types/             # TypeScript definitions
├── docs/                   # Documentation
│   ├── SERVICES.md        # Service architecture
│   ├── DOCKER.md          # Docker setup guide
│   ├── RAILWAY.md         # Railway deployment
│   └── SMITHERY.md        # Smithery deployment
├── scripts/               # Setup & deployment scripts
│   ├── setup.sh          # Universal setup script
│   ├── deploy.ts         # Deployment helper
│   └── test.ts           # System test script
├── config/               # Configuration files
│   ├── docker-compose.yml
│   ├── railway.toml
│   └── smithery.yml
└── examples/             # Example implementations
    ├── .env.example      # Environment template
    └── claude-config.json

🛠️ Installation

Prerequisites

Node.js 20+
Docker (for local deployment)
2GB RAM minimum
10GB disk space

Step-by-Step Setup

Clone and Install

git clone https://github.com/cpretzinger/memory-forge.git
cd memory-forge
npm install

Configure Environment

cp examples/.env.example .env
# Edit .env with your settings (see Configuration section)

Run Setup Script

npm run setup
# This will:
# - Check prerequisites
# - Generate secure passwords
# - Set up databases
# - Configure services
# - Start everything

Test Installation

npm test
# Should show all services as ✅ Running

⚙️ Configuration

Environment Variables

Create a .env file from the example:

# Project Configuration
PROJECT_NAME=my-ai-assistant
NODE_ENV=production

# Database Credentials (generated by setup script)
POSTGRES_PASSWORD=<auto-generated>
REDIS_PASSWORD=<auto-generated>
QDRANT_API_KEY=<auto-generated>

# MCP Configuration
MCP_AUTH_TOKEN=<auto-generated>
MCP_PORT=3005

# API Keys (optional - add your own)
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...

# Service URLs (for production)
DATABASE_URL=postgresql://user:pass@host:5432/dbname
REDIS_URL=redis://:password@host:6379
QDRANT_URL=http://host:6333

Claude Code Configuration

Add to your Claude desktop config (~/.config/claude/claude_desktop_config.json):

{
  "mcpServers": {
    "memory-forge": {
      "command": "node",
      "args": ["/path/to/memory-forge/dist/bridge.js"],
      "env": {
        "MCP_SERVER_URL": "http://localhost:3005/mcp",
        "MCP_AUTH_TOKEN": "your-token-here",
        "AUTO_SAVE": "true"
      }
    }
  }
}

🚢 Deployment Options

Local Docker (Development)

npm run docker:up
# Access at http://localhost:3005

Railway (Production)

npm run deploy:railway
# Follow prompts to configure

Smithery (Managed MCP)

npm run deploy:smithery
# Or use Smithery CLI:
smithery publish cpretzinger/memory-forge

Vercel (Serverless)

npm run deploy:vercel
# Configure environment variables in Vercel dashboard

🔌 Using with Smithery

Installing from Smithery Registry

Find the server:

smithery search memory-forge

Install directly into Claude:

smithery install cpretzinger/memory-forge

Or add to your config manually:

{
  "mcpServers": {
    "memory-forge": {
      "command": "npx",
      "args": ["-y", "@smithery/memory-forge"],
      "env": {
        "API_KEY": "your-api-key"
      }
    }
  }
}

Publishing Your Own Fork

Create Smithery account:

smithery auth

Configure smithery.yml:

name: memory-forge
version: 1.0.0
description: Universal AI memory system
author: yourname
runtime: typescript

Publish:

smithery publish

📊 Architecture

Services Overview

| Service | Purpose | Port | Technology | |---------|---------|------|------------| | MCP Server | Context API | 3005 | TypeScript/Express | | PostgreSQL | Persistent storage | 5432 | PostgreSQL 16 | | Redis | Cache & sessions | 6379 | Redis 7 | | Qdrant | Vector search | 6333 | Qdrant | | n8n | Automation | 5678 | n8n (optional) |

Data Flow

graph LR
    A[Claude/LLM] -->|MCP Protocol| B[MCP Server]
    B --> C[Redis Cache]
    B --> D[PostgreSQL]
    B --> E[Qdrant Vectors]
    C -->|Fast Read| B
    D -->|Persistent| B
    E -->|Semantic Search| B

🔧 API Reference

Available Tools

`store_context`

Store conversation context with auto-save ``typescript { sessionId?: string, // Optional, auto-generated if not provided userId?: string, // Optional user identifier context: object, // Required context data metadata?: object // Optional metadata } ``

`retrieve_context`

Retrieve conversation context ``typescript { sessionId?: string, // Optional, gets latest if not provided userId?: string // Optional user filter } ``

`search_context`

Search through all contexts ``typescript { query: string, // Required search query limit?: number, // Optional result limit (default: 10) semantic?: boolean // Use vector search (default: false) } ``

`list_sessions`

List all available sessions ``typescript { userId?: string, // Optional user filter limit?: number // Optional limit (default: 10) } ``

🧪 Testing

Run All Tests

npm test

Test Specific Service

npm run test:mcp      # Test MCP server
npm run test:storage  # Test storage layer
npm run test:e2e      # End-to-end tests

Manual Testing

# Test MCP endpoint
curl -X POST http://localhost:3005/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

🔒 Security

Default Security Features

Auto-generated secure passwords (32+ characters)
Bearer token authentication on all endpoints
Isolated user contexts
Encrypted storage for sensitive data
No passwords in logs or error messages

Production Hardening

Use environment-specific .env files
Enable HTTPS/TLS in production
Set up firewall rules
Use secrets management (AWS Secrets Manager, etc.)
Enable audit logging

📈 Monitoring

Health Checks

# Check all services
npm run health

# Individual checks
curl http://localhost:3005/health

Metrics

Request latency
Storage usage
Active sessions
Cache hit rate

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Development Setup

# Install dev dependencies
npm install --save-dev

# Run in development mode
npm run dev

# Run with hot reload
npm run dev:watch

📝 License

MIT License - see LICENSE file

🆘 Support

Common Issues

Q: Services won't start? ```bash

Reset everything

npm run reset npm run setup ```

Q: Can't connect to MCP server? ```bash

Check if running

npm run health

Check logs

docker logs memory-forge-mcp ```

Q: How to upgrade? ``bash git pull npm install npm run migrate ``

Get Help

📧 Email: support@memory-forge.ai
💬 Discord: Join our server
🐛 Issues: GitHub Issues

🚀 Roadmap

[ ] OpenAI function calling support
[ ] LangChain integration
[ ] Web UI dashboard
[ ] Backup/restore tools
[ ] Multi-region support
[ ] GraphQL API

---

Built with ❤️ by the Memory Forge team

memory-forge