ragmax 1.0.0
RAGMax - Advanced RAG memory system for AI platforms via MCP
License: MIT
Requires Python: >=3.8
Keywords: ai, memory, mcp, claude, chatgpt, rag, vector-search

# 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](https://www.voyageai.com/) or [Cohere](https://cohere.com/)

### Installation

```bash
# 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`:
```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`:

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

```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 Claude Desktop.

### ChatGPT Desktop (with MCP support)

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

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

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

```json
{
  "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:

```json
{
  "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:

```javascript
// 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

```bash
# 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](ROADMAP.md) for planned features:
- Web search integration
- Multi-modal support (images, code)
- Knowledge graph
- Team collaboration
- And more...

## 📚 Documentation

- [ARCHITECTURE.md](ARCHITECTURE.md) - Technical architecture details
- [PROJECT_SUMMARY.md](PROJECT_SUMMARY.md) - Project overview
- [ROADMAP.md](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
```bash
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 ✅