memory-forge

cpretzinger/memory-forge

3.3

If you are the rightful owner of memory-forge and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

Memory Forge is a comprehensive infrastructure solution designed to provide AI assistants with persistent memory and context awareness, utilizing the Model Context Protocol (MCP) server.

๐Ÿง  Memory Forge - Universal AI Context & Memory System

smithery badge MIT License

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

  1. Clone and Install
git clone https://github.com/cpretzinger/memory-forge.git
cd memory-forge
npm install
  1. Configure Environment
cp examples/.env.example .env
# Edit .env with your settings (see Configuration section)
  1. Run Setup Script
npm run setup
# This will:
# - Check prerequisites
# - Generate secure passwords
# - Set up databases
# - Configure services
# - Start everything
  1. 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

  1. Find the server:
smithery search memory-forge
  1. Install directly into Claude:
smithery install cpretzinger/memory-forge
  1. 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

  1. Create Smithery account:
smithery auth
  1. Configure smithery.yml:
name: memory-forge
version: 1.0.0
description: Universal AI memory system
author: yourname
runtime: typescript
  1. Publish:
smithery publish

๐Ÿ“Š Architecture

Services Overview

ServicePurposePortTechnology
MCP ServerContext API3005TypeScript/Express
PostgreSQLPersistent storage5432PostgreSQL 16
RedisCache & sessions6379Redis 7
QdrantVector search6333Qdrant
n8nAutomation5678n8n (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

{
  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

{
  sessionId?: string,  // Optional, gets latest if not provided
  userId?: string      // Optional user filter
}
search_context

Search through all contexts

{
  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

{
  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

  1. Use environment-specific .env files
  2. Enable HTTPS/TLS in production
  3. Set up firewall rules
  4. Use secrets management (AWS Secrets Manager, etc.)
  5. 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 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 file

๐Ÿ†˜ Support

Common Issues

Q: Services won't start?

# Reset everything
npm run reset
npm run setup

Q: Can't connect to MCP server?

# Check if running
npm run health

# Check logs
docker logs memory-forge-mcp

Q: How to upgrade?

git pull
npm install
npm run migrate

Get Help

๐Ÿš€ 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