RAG Memory PostgreSQL MCP Server


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.

---

$3

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

$3

Add to ~/.cursor/mcp.json:

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

$3

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

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

$3

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

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

$3

Add to ~/.windsurf/mcp.json:

`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

$3

Already configured in Quick Start above!

$3

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

$3

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

$3

- 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.

$3

#### processDocument ⭐ Recommended
Full pipeline: store → chunk → embed. Use this for adding documents.

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

$3

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

#### createRelations
`json
{
"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.

$3

#### hybridSearch
Semantic + text search across documents.

#### getDetailedContext
Combined semantic and graph search.

#### readGraph
Read entire knowledge graph.

$3

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

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

$3

- 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

$3

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

`bash


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

`bash


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