ragmax 1.0.0

RAGMax - Advanced RAG memory system for AI platforms via MCP

Universal AI Memory

A production-ready MCP (Model Context Protocol) server providing universal memory across all AI platforms (Claude, ChatGPT, Gemini, Perplexity, etc.)

🎯 Features

• Universal Memory: Share context across Claude Desktop, ChatGPT, Gemini, and any MCP-compatible platform
• Smart Chunking: Contextual embeddings using Anthropic's approach
• Hybrid Search: Vector similarity + keyword search with automatic reranking
• 3-Tier Storage: Hot (Redis), Warm (Qdrant), Cold (PostgreSQL)
• Automatic User ID: No need to specify userId - automatically consistent per machine
• Production Ready: Error handling, caching, batch operations

🚀 Quick Start

Prerequisites

• Node.js 18+
• Docker & Docker Compose
• API key from Voyage AI or Cohere

Installation

# 1. Clone and install
git clone <your-repo>
cd universal-ai-memory
npm install

# 2. Configure environment
cp .env.example .env
# Edit .env and add your API keys

# 3. Start databases
docker-compose up -d

# 4. Initialize database
cat src/storage/schema.sql | docker-compose exec -T postgres psql -U postgres -d ai_memory

# 5. Build
npm run build

Configuration

Edit .env:

# Required: Choose one
VOYAGE_API_KEY=your_voyage_key
# OR
COHERE_API_KEY=your_cohere_key

# Optional: Set your user ID (defaults to machine ID)
DEFAULT_USER_ID=your_name

📱 Platform Setup

Claude Desktop (Kiro)

Create or edit .kiro/settings/mcp.json:

{
  "mcpServers": {
    "universal-memory": {
      "command": "node",
      "args": ["/absolute/path/to/universal-ai-memory/dist/index.js"],
      "env": {
        "VOYAGE_API_KEY": "your_key_here",
        "DEFAULT_USER_ID": "your_name"
      },
      "disabled": false,
      "autoApprove": ["search_memory", "add_to_memory"]
    }
  }
}

Important: Use absolute path! Restart Claude Desktop after configuration.

Claude Desktop (Official)

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "universal-memory": {
      "command": "node",
      "args": ["/absolute/path/to/universal-ai-memory/dist/index.js"],
      "env": {
        "VOYAGE_API_KEY": "your_key_here",
        "DEFAULT_USER_ID": "your_name"
      }
    }
  }
}

Restart Claude Desktop.

ChatGPT Desktop (with MCP support)

Edit ~/Library/Application Support/ChatGPT/mcp_config.json:

{
  "mcpServers": {
    "universal-memory": {
      "command": "node",
      "args": ["/absolute/path/to/universal-ai-memory/dist/index.js"],
      "env": {
        "VOYAGE_API_KEY": "your_key_here",
        "DEFAULT_USER_ID": "your_name"
      }
    }
  }
}

Restart ChatGPT.

Continue.dev (VS Code Extension)

Edit ~/.continue/config.json:

{
  "mcpServers": [
    {
      "name": "universal-memory",
      "command": "node",
      "args": ["/absolute/path/to/universal-ai-memory/dist/index.js"],
      "env": {
        "VOYAGE_API_KEY": "your_key_here",
        "DEFAULT_USER_ID": "your_name"
      }
    }
  ]
}

Reload VS Code.

Cline (VS Code Extension)

Edit .vscode/settings.json in your workspace:

{
  "cline.mcpServers": {
    "universal-memory": {
      "command": "node",
      "args": ["/absolute/path/to/universal-ai-memory/dist/index.js"],
      "env": {
        "VOYAGE_API_KEY": "your_key_here",
        "DEFAULT_USER_ID": "your_name"
      }
    }
  }
}

Reload window.

Generic MCP Client

For any MCP-compatible client, use:

{
  "command": "node",
  "args": ["/absolute/path/to/universal-ai-memory/dist/index.js"],
  "env": {
    "POSTGRES_HOST": "localhost",
    "POSTGRES_PORT": "5432",
    "POSTGRES_DB": "ai_memory",
    "POSTGRES_USER": "postgres",
    "POSTGRES_PASSWORD": "postgres",
    "REDIS_HOST": "localhost",
    "REDIS_PORT": "6379",
    "QDRANT_URL": "http://localhost:6333",
    "VOYAGE_API_KEY": "your_key_here",
    "DEFAULT_USER_ID": "your_name"
  }
}

🧪 Testing

After setup, test in your AI platform:

// Add a memory (userId is automatic)
add_to_memory({
  platform: "claude",
  conversationId: "test_001",
  content: "I love TypeScript and building AI applications",
  role: "user"
})

// Search memory (userId is automatic)
search_memory({
  query: "What do I love?",
  limit: 5
})

Or just ask naturally:

• "Remember that I prefer functional programming"
• "What are my coding preferences?"
• "What did I say about TypeScript?"

🔧 Available Tools

search_memory

Search through all memories using hybrid semantic + keyword search.

Parameters:

• query (required): Search query
• userId (optional): User identifier (auto-detected)
• limit (optional): Max results (default: 10)
• platform (optional): Filter by platform
• minScore (optional): Minimum relevance (0-1)

add_to_memory

Add new content to memory with automatic chunking and embedding.

Parameters:

• platform (required): Platform name (claude, chatgpt, gemini, etc.)
• conversationId (required): Conversation identifier
• content (required): Content to remember
• role (required): "user" or "assistant"
• userId (optional): User identifier (auto-detected)
• metadata (optional): Additional metadata

📊 Architecture

User Input
    ↓
PostgreSQL (full content + metadata)
    ↓
Redis (hot cache - last 50 messages)
    ↓
Smart Chunking (contextual embeddings)
    ↓
Voyage AI / Cohere (embeddings)
    ↓
Qdrant (vector search) + PostgreSQL (backup)

Search Flow:

Query → Redis Cache → Generate Embedding → Hybrid Search → Rerank → Results

🛠️ Maintenance

# View logs
docker-compose logs -f

# Restart services
docker-compose restart

# Backup database
docker-compose exec postgres pg_dump -U postgres ai_memory > backup.sql

# Clear cache
docker-compose exec redis redis-cli FLUSHALL

# Check database
docker-compose exec postgres psql -U postgres -d ai_memory

📈 Performance

• Add Memory: 200-500ms (includes embedding)
• Search (hot): <10ms
• Search (cold): 50-200ms
• Storage: ~1KB per message

🔐 Security

• User isolation via userId
• No cross-user data leakage
• Local database (no external sharing)
• API keys in environment variables

🗺️ Roadmap

See ROADMAP.md for planned features:

• Web search integration
• Multi-modal support (images, code)
• Knowledge graph
• Team collaboration
• And more...

📚 Documentation

• ARCHITECTURE.md - Technical architecture details
• PROJECT_SUMMARY.md - Project overview
• ROADMAP.md - Future features

🐛 Troubleshooting

MCP Server Not Connecting

1. Check absolute path in config
2. Verify dist/index.js exists
3. Check databases are running: docker-compose ps
4. Restart the AI platform completely

No Search Results

1. Make sure you added memories first
2. Check userId is consistent
3. Verify databases are running
4. Check logs: docker-compose logs

Embedding Errors

1. Verify API key is correct
2. Check API credits/quota
3. Try alternative provider (Voyage ↔ Cohere)

Database Connection Errors

docker-compose restart
docker-compose logs postgres

💡 Tips

• Use consistent conversationId for threaded conversations
• Add metadata tags for better organization
• The system learns from all platforms - ask in Claude what you told ChatGPT!
• Hot cache makes repeated searches instant

📄 License

MIT

🤝 Contributing

Contributions welcome! Please open an issue or PR.

---

Built with: TypeScript, PostgreSQL, Redis, Qdrant, Voyage AI, Cohere MCP Version: 0.5.0 Status: Production Ready ✅