# rag-memory-mcp

[![npm version](https://img.shields.io/npm/v/rag-memory-mcp)](https://www.npmjs.com/package/rag-memory-mcp)
[![npm downloads](https://img.shields.io/npm/dm/rag-memory-mcp)](https://www.npmjs.com/package/rag-memory-mcp)
[![GitHub license](https://img.shields.io/github/license/ttommyth/rag-memory-mcp)](https://github.com/ttommyth/rag-memory-mcp/blob/main/LICENSE)
[![Platforms](https://img.shields.io/badge/Platform-Windows%20%7C%20macOS%20%7C%20Linux-blue)](https://github.com/ttommyth/rag-memory-mcp)
[![GitHub last commit](https://img.shields.io/github/last-commit/ttommyth/rag-memory-mcp)](https://github.com/ttommyth/rag-memory-mcp/commits/main)

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](https://github.com/modelcontextprotocol/servers/tree/main/src/memory) 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):

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

**With specific version:**
```json
{
  "mcpServers": {
    "rag-memory": {
      "command": "npx",
      "args": ["-y", "rag-memory-mcp@1.0.0"]
    }
  }
}
```

**With custom database path:**
```json
{
  "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`:

```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:
```json
{
  "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:
```json
{
  "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:
1. **Storage**: Raw text with metadata
2. **Chunking**: Split into manageable pieces
3. **Embedding**: Convert to vector representations
4. **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)

1. Clone the repository:
```bash
git clone https://github.com/ttommyth/rag-memory-mcp.git
cd rag-memory-mcp
```

2. Install dependencies:
```bash
npm install
```

### Building
```bash
npm run build
```

### Running (Development)
```bash
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:

```javascript
// 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](LICENSE) file for details.

---

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