rag-memory-mcp

An advanced MCP server for RAG-enabled memory through a knowledge graph with vector search capabilities. This server extends the basic memory concepts with semantic search, document processing, and hybrid retrieval for more intelligent memory management.

Inspired by: Knowledge Graph Memory Server from the Model Context Protocol project.

Note: This server is designed to run locally alongside MCP clients (e.g., Claude Desktop, VS Code) and requires local file system access for database storage.

✨ Key Features

🧠 Knowledge Graph Memory: Persistent entities, relationships, and observations
🔍 Vector Search: Semantic similarity search using sentence transformers
📄 Document Processing: RAG-enabled document chunking and embedding
🔗 Hybrid Search: Combines vector similarity with graph traversal
⚡ SQLite Backend: Fast local storage with sqlite-vec for vector operations
🎯 Entity Extraction: Automatic term extraction from documents

Tools

This server provides comprehensive memory management through the Model Context Protocol (MCP):

📚 Document Management

storeDocument: Store documents with metadata for processing
chunkDocument: Create text chunks with configurable parameters
embedChunks: Generate vector embeddings for semantic search
extractTerms: Extract potential entity terms from documents
linkEntitiesToDocument: Create explicit entity-document associations
deleteDocuments: Remove documents and associated data
listDocuments: View all stored documents with metadata

🧠 Knowledge Graph

createEntities: Create new entities with observations and types
createRelations: Establish relationships between entities
addObservations: Add contextual information to existing entities
deleteEntities: Remove entities and their relationships
deleteRelations: Remove specific relationships
deleteObservations: Remove specific observations from entities

🔍 Search & Retrieval

hybridSearch: Advanced search combining vector similarity and graph traversal
searchNodes: Find entities by name, type, or observation content
openNodes: Retrieve specific entities and their relationships
readGraph: Get complete knowledge graph structure

📊 Analytics

getKnowledgeGraphStats: Comprehensive statistics about the knowledge base

Usage Scenarios

This server is ideal for scenarios requiring intelligent memory and document understanding:

Research and Documentation: Store, process, and intelligently retrieve research papers
Knowledge Base Construction: Build interconnected knowledge from documents
Conversational Memory: Remember context across chat sessions with semantic understanding
Content Analysis: Extract and relate concepts from large document collections
Intelligent Assistance: Provide contextually aware responses based on stored knowledge

Client Configuration

This section explains how to configure MCP clients to use the rag-memory-mcp server.

Usage with Claude Desktop / Cursor

Add the following configuration to your claude_desktop_config.json (Claude Desktop) or mcp.json (Cursor):

{
  "mcpServers": {
    "rag-memory": {
      "command": "npx",
      "args": ["-y", "rag-memory-mcp"]
    }
  }
}

With specific version:

{
  "mcpServers": {
    "rag-memory": {
      "command": "npx",
      "args": ["-y", "[email protected]"]
    }
  }
}

With custom database path:

{
  "mcpServers": {
    "rag-memory": {
      "command": "npx",
      "args": ["-y", "rag-memory-mcp"],
      "env": {
        "MEMORY_DB_PATH": "/path/to/custom/memory.db"
      }
    }
  }
}

Usage with VS Code

Add the following configuration to your User Settings (JSON) file or .vscode/mcp.json:

{
  "mcp": {
    "servers": {
      "rag-memory-mcp": {
        "command": "npx",
        "args": ["-y", "rag-memory-mcp"]
      }
    }
  }
}

Core Concepts

Entities

Entities are the primary nodes in the knowledge graph. Each entity has:

A unique name (identifier)
An entity type (e.g., "PERSON", "CONCEPT", "TECHNOLOGY")
A list of observations (contextual information)

Example:

{
  "name": "Machine Learning",
  "entityType": "CONCEPT",
  "observations": [
    "Subset of artificial intelligence",
    "Focuses on learning from data",
    "Used in recommendation systems"
  ]
}

Relations

Relations define directed connections between entities, describing how they interact:

Example:

{
  "from": "React",
  "to": "JavaScript",
  "relationType": "BUILT_WITH"
}

Observations

Observations are discrete pieces of information about entities:

Stored as strings
Attached to specific entities
Can be added or removed independently
Should be atomic (one fact per observation)

Documents & Vector Search

Documents are processed through:

Storage: Raw text with metadata
Chunking: Split into manageable pieces
Embedding: Convert to vector representations
Linking: Associate with relevant entities

This enables hybrid search that combines:

Vector similarity (semantic matching)
Graph traversal (conceptual relationships)

Environment Variables

MEMORY_DB_PATH: Path to the SQLite database file (default: memory.db in the server directory)

Development Setup

This section is for developers looking to modify or contribute to the server.

Prerequisites

Node.js: Check package.json for version compatibility
npm: Used for package management

Installation (Developers)

Clone the repository:

git clone https://github.com/ttommyth/rag-memory-mcp.git
cd rag-memory-mcp

Install dependencies:

npm install

Building

npm run build

Running (Development)

npm run watch  # For development with auto-rebuild

Development Commands

Build: npm run build
Watch: npm run watch
Prepare: npm run prepare

Usage Example

Here's a typical workflow for building and querying a knowledge base:

// 1. Store a document
await storeDocument({
  id: "ml_intro",
  content: "Machine learning is a subset of AI...",
  metadata: { type: "educational", topic: "ML" }
});

// 2. Process the document
await chunkDocument({ documentId: "ml_intro" });
await embedChunks({ documentId: "ml_intro" });

// 3. Extract and create entities
const terms = await extractTerms({ documentId: "ml_intro" });
await createEntities({
  entities: [
    {
      name: "Machine Learning",
      entityType: "CONCEPT",
      observations: ["Subset of artificial intelligence", "Learns from data"]
    }
  ]
});

// 4. Search with hybrid approach
const results = await hybridSearch({
  query: "artificial intelligence applications",
  limit: 10,
  useGraph: true
});

System Prompt Suggestions

For optimal memory utilization, consider using this system prompt:

You have access to a RAG-enabled memory system with knowledge graph capabilities. Follow these guidelines:

1. **Information Storage**:
   - Store important documents using the document management tools
   - Create entities for people, concepts, organizations, and technologies
   - Build relationships between related concepts

2. **Information Retrieval**:
   - Use hybrid search for comprehensive information retrieval
   - Leverage both semantic similarity and graph relationships
   - Search entities before creating duplicates

3. **Memory Maintenance**:
   - Add observations to enrich entity context
   - Link documents to relevant entities for better discoverability
   - Use statistics to monitor knowledge base growth

4. **Processing Workflow**:
   - Store → Chunk → Embed → Extract → Link
   - Always process documents completely for best search results

Contributing

Contributions are welcome! Please follow standard development practices and ensure all tests pass before submitting pull requests.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Built with: TypeScript, SQLite, sqlite-vec, Hugging Face Transformers, Model Context Protocol SDK

RAG Memory