Rag Memory Pg

npm version License: MIT

A Model Context Protocol (MCP) server for RAG-enabled memory with PostgreSQL/Supabase backend. Provides knowledge graph, document management, and semantic search capabilities.

---

🚀 Quick Install

One-click installation for your IDE:

Note: Using @latest ensures automatic updates. npx checks for new versions every 24 hours.

---

🔑 Get Your Credentials First

Before installation, get your credentials:

• Supabase: https://app.supabase.com/project/_/settings/api
• OpenAI (optional, 10-100x faster embeddings): https://platform.openai.com/api-keys

---

Manual Installation

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "rag-memory-pg": {
      "command": "npx",
      "args": ["-y", "rag-memory-pg-mcp@latest"],
      "env": {
        "SUPABASE_URL": "https://your-project.supabase.co",
        "SUPABASE_SERVICE_KEY": "your-service-key",
        "MODE": "local",
        "OPENAI_API_KEY": "sk-your-api-key",
        "TOOLS_MODE": "full"
      }
    }
  }
}

Options:

• MODE: "local" (free, slower) or "openai" (10-100x faster)
• TOOLS_MODE: "client" (11 tools), "maintenance" (10 tools), or "full" (21 tools, default)

Then restart Cursor.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "rag-memory-pg": {
      "command": "npx",
      "args": ["-y", "rag-memory-pg-mcp@latest"],
      "env": {
        "SUPABASE_URL": "https://your-project.supabase.co",
        "SUPABASE_SERVICE_KEY": "your-service-key",
        "MODE": "local",
        "OPENAI_API_KEY": "sk-your-api-key",
        "TOOLS_MODE": "full"
      }
    }
  }
}

Options:

• MODE: "local" (free, slower) or "openai" (10-100x faster)
• TOOLS_MODE: "client" (11 tools), "maintenance" (10 tools), or "full" (21 tools, default)

Then restart Claude Desktop.

VS Code

Add to .vscode/mcp.json in your workspace:

{
  "servers": {
    "rag-memory-pg": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "rag-memory-pg-mcp@latest"],
      "env": {
        "SUPABASE_URL": "https://your-project.supabase.co",
        "SUPABASE_SERVICE_KEY": "your-service-key",
        "MODE": "local",
        "OPENAI_API_KEY": "sk-your-api-key"
      }
    }
  }
}

To use OpenAI (10-100x faster): Change MODE to "openai" and add your real OpenAI key.
MODE=local (default): Free, private, slower - ignores OPENAI_API_KEY.

Then reload VS Code window.

Windsurf

Add to ~/.windsurf/mcp.json:

{
  "mcpServers": {
    "rag-memory-pg": {
      "command": "npx",
      "args": ["-y", "rag-memory-pg-mcp@latest"],
      "env": {
        "SUPABASE_URL": "https://your-project.supabase.co",
        "SUPABASE_SERVICE_KEY": "your-service-key",
        "MODE": "local",
        "OPENAI_API_KEY": "sk-your-api-key",
        "TOOLS_MODE": "full"
      }
    }
  }
}

Options:

• MODE: "local" (free, slower) or "openai" (10-100x faster)
• TOOLS_MODE: "client" (11 tools), "maintenance" (10 tools), or "full" (21 tools, default)

Then restart Windsurf.

---

Features

• Knowledge Graph: Entities, relationships, and observations
• Document Processing: Store → Chunk → Embed pipeline
• Semantic Search: Vector embeddings with local HuggingFace model (no API keys needed)
• Hybrid Search: Combines text and semantic search
• Multi-Machine Sync: PostgreSQL backend enables real-time sync across devices

⚠️ Important: All content (entities, documents, queries) should be stored and searched in English for optimal embedding and search performance. The embedding models are trained on English text and work best with English input.

📦 Installation Options

Option 1: Direct via npx (Recommended)

Already configured in Quick Start above!

Option 2: Global Installation

npm install -g rag-memory-pg-mcp@latest

Option 3: From GitHub

npm install -g github:kshidenko/rag-memory-pg-mcp

Note: Using @latest ensures you always get the newest version. npx automatically checks for updates every 24 hours.

Environment Variables

Variable	Required	Description
SUPABASE_URL	Yes	Your Supabase project URL
SUPABASE_SERVICE_KEY	Yes	Supabase service role key
MODE	No	Embedding mode: local (default) or openai
OPENAI_API_KEY	No	Only used when MODE=openai
TOOLS_MODE	No	Tool set: client, maintenance, or full (default)

Tools Mode

• full (default) - All 21 tools for complete functionality
• client - 10 essential tools for daily memory operations (recommended for most users)
• maintenance - 11 admin/cleanup tools for database management

Tools by Mode

CLIENT mode (10 tools) - Recommended for daily use:

• Knowledge Graph: createEntities, createRelations, addObservations, searchNodes, openNodes
• Documents: processDocument (⭐ main tool)
• Search: hybridSearch, getDetailedContext
• Info: getGraph, getKnowledgeGraphStats

MAINTENANCE mode (11 tools) - For cleanup and admin:

• Cleanup: deleteEntities, deleteRelations, deleteObservations, deleteDocuments
• Advanced: storeDocument, chunkDocument, embedChunks, embedAllEntities
• Utilities: listDocuments, extractTerms, linkEntitiesToDocument

FULL mode (21 tools) - Everything:

• All CLIENT tools + all MAINTENANCE tools

Available Tools (21 total)

Language Note: All tools expect English input for entity names, observations, document content, and search queries. This ensures optimal embedding quality and search accuracy.

Document Processing

processDocument ⭐ Recommended

Full pipeline: store → chunk → embed. Use this for adding documents.

{
  "id": "my-document",
  "content": "Document content here...",
  "maxChunkSize": 500,
  "overlap": 50,
  "metadata": { "category": "tech" }
}

storeDocument

Store document only (without chunking/embedding).

chunkDocument

Split document into chunks.

embedChunks

Generate embeddings for document chunks.

Knowledge Graph

createEntities

{
  "entities": [{
    "name": "React",
    "entityType": "TECHNOLOGY",
    "observations": ["JavaScript library", "Used for UI"]
  }]
}

createRelations

{
  "relations": [{
    "from": "React",
    "to": "JavaScript",
    "relationType": "BUILT_WITH"
  }]
}

addObservations

Add observations to existing entities.

searchNodes

Search entities by name or type.

openNodes

Get specific entities by name.

deleteEntities

Delete entities and their relationships.

deleteRelations

Delete specific relationships.

deleteObservations

Delete observations from entities.

Search & Retrieval

hybridSearch

Semantic + text search across documents.

getDetailedContext

Combined semantic and graph search.

readGraph

Read entire knowledge graph.

Utilities

listDocuments

List all stored documents.

getKnowledgeGraphStats

Get database statistics.

extractTerms

Extract key terms from document.

linkEntitiesToDocument

Link entities to documents.

embedAllEntities

Generate embeddings for all entities.

Database Schema

Required PostgreSQL tables (with pgvector extension):

-- Enable pgvector
CREATE EXTENSION IF NOT EXISTS vector;

-- Entities
CREATE TABLE rag_entities (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  name TEXT UNIQUE NOT NULL,
  entity_type TEXT NOT NULL,
  observations TEXT[] DEFAULT '{}',
  created_at TIMESTAMPTZ DEFAULT NOW()
);

-- Relationships
CREATE TABLE rag_relationships (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  from_entity UUID REFERENCES rag_entities(id),
  to_entity UUID REFERENCES rag_entities(id),
  relation_type TEXT NOT NULL,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

-- Documents
CREATE TABLE rag_documents (
  id TEXT PRIMARY KEY,
  content TEXT NOT NULL,
  metadata JSONB DEFAULT '{}',
  created_at TIMESTAMPTZ DEFAULT NOW()
);

-- Chunks with embeddings
CREATE TABLE rag_chunks (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  document_id TEXT REFERENCES rag_documents(id),
  chunk_index INTEGER,
  content TEXT NOT NULL,
  embedding VECTOR(384),
  start_pos INTEGER,
  end_pos INTEGER,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

-- Entity embeddings
CREATE TABLE rag_entity_embeddings (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  entity_id UUID REFERENCES rag_entities(id),
  embedding VECTOR(384),
  embedding_text TEXT,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

Embedding Modes

The server supports two embedding modes controlled by the MODE environment variable:

Mode	Speed	Cost	Privacy	Setup
local (default)	Slower	Free	100%	Zero config
openai	10-100x faster	~$0.02/1M tokens	Cloud	API key required

Local Mode (Default)

• Uses Xenova/all-MiniLM-L12-v2 via HuggingFace Transformers
• Runs locally (data never leaves your machine)
• ~50MB model download on first run
• 384-dimensional vectors

OpenAI Mode

• Uses text-embedding-3-small
• Much faster, no local resources needed
• 384-dimensional vectors (configured for backward compatibility)

Switching modes: Just change MODE from "local" to "openai" in your config. Both modes produce compatible 384-dim vectors, so existing embeddings remain valid.

⚡ Full-Text Search (Optional)

For better search performance on large document sets, enable PostgreSQL Full-Text Search:

# Run in Supabase SQL Editor
# File: supabase-fts-setup.sql (included in repo)

Feature	Without FTS	With FTS
Speed (1000+ docs)	Slow (seq scan)	Fast (GIN index)
Stemming	❌	✅ "running" → "run"
Stop words	❌	✅ ignores "the", "a"
Phrase search	❌	✅ "exact phrase"

The server auto-detects FTS availability and uses the optimal search method.

Development

# Clone
git clone https://github.com/kshidenko/rag-memory-pg-mcp.git
cd rag-memory-pg-mcp

# Install
npm install

# Run
node src/index.js

# Test with MCP Inspector
npx @modelcontextprotocol/inspector node src/index.js

📚 Documentation

• CHANGELOG.md - Version history and migration notes
• CONTRIBUTING.md - How to contribute to this project
• SECURITY.md - Security policy and best practices
• MIGRATION.md - Migration guide for version upgrades
• UPDATE_GUIDE.md - How to update to latest version

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for:

• How to submit pull requests
• Code style guidelines
• Development workflow
• Testing requirements

🔒 Security

Found a security issue? Please see SECURITY.md for:

• How to report vulnerabilities
• Security best practices
• Credential management

📋 Version History

See CHANGELOG.md for detailed version history and breaking changes.

License

MIT