MCP Memory Server

An intelligent memory management server based on Model Context Protocol (MCP), providing persistent memory storage and powerful vector search capabilities for AI models.

🌟 Features

$3

- CRUD Operations: Create, read, update, and delete memory entries
- Multiple Memory Types: Support for global, conversation, and temporary memories
- Folder Management: Create, delete, and rename folders to organize and categorize memories
- Flexible Storage: User-customizable storage paths
- JSON Format: JSON-based storage for easy reading and backup

$3

- Semantic Search: Intelligent search based on meaning rather than keywords
- Hybrid Search: Combines semantic and keyword search
- Multi-Provider Support: Support for Ollama, Gemini, OpenAI embedding models
- Auto-Vectorization: Automatic embedding generation when creating memories
- Similarity Calculation: Calculate semantic similarity between any two texts
- High Performance: In-memory caching + file persistence

$3

- Memory Caching: Improved read performance
- Indexing System: Fast search and filtering
- Performance Monitoring: Real-time performance metrics
- File Management: Automatic backup and recovery
- Comprehensive Error Handling: Stable and reliable operation

📦 Installation

$3

``bash
npm install @qianjue/mcp-memory-server
`

$3

`bash


Clone the repository

git clone https://github.com/QianJue-CN/mcp-memory-server.git
cd mcp-memory-server

Install dependencies

npm install

Build the project

npm run build
`

🚀 Quick Start

$3

Add this server to your MCP client configuration file:

#### For Claude Desktop (config.json)

`json
{
"mcpServers": {
"memory-server": {
"command": "node",
"args": ["path/to/mcp-memory-server/dist/index.js"],
"env": {
"MCP_MEMORY_STORAGE_PATH": "/path/to/your/memory/storage"
}
}
}
}
`

#### Using NPM Package

`json
{
"mcpServers": {
"memory-server": {
"command": "npx",
"args": ["@qianjue/mcp-memory-server"],
"env": {
"MCP_MEMORY_STORAGE_PATH": "/path/to/your/memory/storage"
}
}
}
}
`

#### Configuration Options

- MCP_MEMORY_STORAGE_PATH: Custom storage directory path
- MCP_EMBEDDING_PROVIDER: Default embedding provider (ollama/gemini/openai)
- MCP_EMBEDDING_API_KEY: Default API key for embedding provider
- LOG_LEVEL: Logging level (debug/info/warn/error)

$3

`bash


Start the server directly

npm start

Or run from dist

node dist/index.js
`

$3

#### 1. Configure Embedding Provider

`json
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "configure_embedding",
"arguments": {
"provider": "gemini",
"apiKey": "your-gemini-api-key",
"baseUrl": "https://generativelanguage.googleapis.com",
"model": "text-embedding-004"
}
}
}
`

#### 2. Create Memory (Auto-generates vectors)

`json
{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "create_memory",
"arguments": {
"content": "I am learning JavaScript programming",
"type": "global",
"tags": ["programming", "learning"]
}
}
}
`

#### 3. Semantic Search

`json
{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "semantic_search",
"arguments": {
"query": "programming learning",
"limit": 5,
"threshold": 0.7
}
}
}
`

📚 MCP Tools

$3

#### 1. create_memory
Create a new memory entry

`json
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "create_memory",
"arguments": {
"content": "Memory content",
"type": "global",
"tags": ["tag1", "tag2"],
"metadata": {"key": "value"}
}
}
}
`

#### 2. read_memories
Read memory entries

`json
{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "read_memories",
"arguments": {
"type": "global",
"limit": 10,
"searchText": "search keywords"
}
}
}
`

#### 3. update_memory
Update a memory entry

`json
{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "update_memory",
"arguments": {
"id": "memory-id",
"content": "Updated content"
}
}
}
`

#### 4. delete_memory
Delete a memory entry

`json
{
"jsonrpc": "2.0",
"id": 4,
"method": "tools/call",
"params": {
"name": "delete_memory",
"arguments": {
"id": "memory-id"
}
}
}
`

#### 5. get_memory_stats
Get memory statistics

`json
{
"jsonrpc": "2.0",
"id": 5,
"method": "tools/call",
"params": {
"name": "get_memory_stats",
"arguments": {}
}
}
`

$3

#### 1. configure_embedding
Configure embedding model provider

`json
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "configure_embedding",
"arguments": {
"provider": "gemini",
"apiKey": "your-gemini-api-key",
"baseUrl": "https://generativelanguage.googleapis.com",
"model": "text-embedding-004"
}
}
}
`

#### 2. semantic_search
Semantic similarity search

`json
{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "semantic_search",
"arguments": {
"query": "programming learning",
"limit": 5,
"threshold": 0.7,
"hybridSearch": false
}
}
}
`

#### 3. generate_embeddings
Generate embeddings for existing memories

`json
{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "generate_embeddings",
"arguments": {}
}
}
`

#### 4. calculate_similarity
Calculate similarity between two texts

`json
{
"jsonrpc": "2.0",
"id": 4,
"method": "tools/call",
"params": {
"name": "calculate_similarity",
"arguments": {
"text1": "learning programming",
"text2": "writing code"
}
}
}
`

#### 5. get_vector_stats
Get vector storage statistics

`json
{
"jsonrpc": "2.0",
"id": 5,
"method": "tools/call",
"params": {
"name": "get_vector_stats",
"arguments": {}
}
}
`

$3

#### 1. create_folder
Create a new memory folder

`json
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "create_folder",
"arguments": {
"folderPath": "Work/ProjectA",
"description": "Memories related to Project A"
}
}
}
`

Parameters:
- folderPath: Folder path, supports multi-level paths (e.g., "Work/ProjectA/Documents")
- description: Optional folder description

Use Cases:
- Organize memories for different projects
- Categorize memories by topic
- Create hierarchical memory structures

#### 2. delete_folder
Delete a folder

`json
{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "delete_folder",
"arguments": {
"folderPath": "Work/ProjectA",
"deleteMemories": false
}
}
}
`

Parameters:
- folderPath: Path of the folder to delete
- deleteMemories: Whether to delete all memories in the folder (default: false)
- true: Delete folder and all its memories
- false: Only delete folder, memories are retained but folder tags are removed

Important Notes:
- Confirm whether you need to keep memories before deleting a folder
- Setting deleteMemories: true will permanently delete all memories in the folder

#### 3. rename_folder
Rename a folder

`json
{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "rename_folder",
"arguments": {
"oldPath": "Work/ProjectA",
"newPath": "Work/ProjectAlpha"
}
}
}
`

Parameters:
- oldPath: Current folder path
- newPath: New folder path

Features:
- Automatically updates metadata for all memories in the folder
- Ensures atomicity of rename operations
- Prevents data inconsistency

Important:
When renaming a folder, the system automatically synchronizes and updates the metadata.folderPath field for all memories in the folder, ensuring the correct association between memories and folders.

#### 4. list_folders
List all folders

`json
{
"jsonrpc": "2.0",
"id": 4,
"method": "tools/call",
"params": {
"name": "list_folders",
"arguments": {}
}
}
`

Returns:
- Folder path
- Folder name
- Creation time
- Number of memories contained
- Parent folder path

$3

When creating a memory, you can specify a folder using the metadata.folderPath field:

`json
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "create_memory",
"arguments": {
"content": "Project A requirements document completed",
"type": "conversation",
"tags": ["project", "documentation"],
"metadata": {
"folderPath": "Work/ProjectA",
"priority": "high"
}
}
}
}
`

Notes:
- Global memories (type: "global") do not need folder tags
- Folder paths are automatically stored in the memory's metadata.folderPath field
- When renaming a folder, all related memories' folder paths are automatically updated

🔧 Configuration

$3

#### Ollama (Local Models)
`json
{
"provider": "ollama",
"baseUrl": "http://localhost:11434",
"model": "nomic-embed-text",
"dimensions": 768
}
`

#### Gemini API
`json
{
"provider": "gemini",
"apiKey": "your-gemini-api-key",
"baseUrl": "https://generativelanguage.googleapis.com",
"model": "text-embedding-004",
"dimensions": 768
}
`

#### OpenAI API
`json
{
"provider": "openai",
"apiKey": "your-openai-api-key",
"model": "text-embedding-3-small",
"dimensions": 1536
}
`

$3


`bash

Optional: Set default storage path

MCP_MEMORY_STORAGE_PATH=/path/to/storage

Optional: Set embedding configuration

MCP_EMBEDDING_PROVIDER=gemini
MCP_EMBEDDING_API_KEY=your-gemini-api-key
`

$3

Here's a complete example of how to configure the MCP Memory Server in Claude Desktop:

`json
{
"mcpServers": {
"memory-server": {
"command": "npx",
"args": ["@qianjue/mcp-memory-server"],
"env": {
"MCP_MEMORY_STORAGE_PATH": "~/Documents/AI-Memory",
"MCP_EMBEDDING_PROVIDER": "gemini",
"MCP_EMBEDDING_API_KEY": "your-gemini-api-key",
"LOG_LEVEL": "info"
}
}
}
}
`

After adding this configuration:
1. Restart Claude Desktop
2. The memory server will be available with all 11 tools
3. Vector search will be automatically enabled if API key is provided
4. Memories will be stored in the specified directory

📊 Data Structures

$3


`typescript
interface MemoryEntry {
id: string; // UUID
content: string; // Memory content
type: MemoryType; // Memory type
conversationId?: string; // Conversation ID (optional)
createdAt: string; // Creation time (ISO 8601)
updatedAt: string; // Update time (ISO 8601)
tags?: string[]; // Tags array
metadata?: object; // Metadata object
embedding?: number[]; // Embedding vector (optional)
}
`

$3

`typescript
enum MemoryType {
GLOBAL = 'global', // Global memory
CONVERSATION = 'conversation', // Conversation memory
TEMPORARY = 'temporary' // Temporary memory
}
`

🏗️ Project Structure

`
src/
├── types/ # Type definitions
│ ├── memory.ts # Memory-related types
│ └── vector.ts # Vector-related types
├── memory/ # Memory management core
├── embedding/ # Embedding model providers
│ ├── EmbeddingProvider.ts
│ ├── EmbeddingManager.ts
│ └── providers/ # Provider implementations
├── vector/ # Vector storage and computation
│ ├── VectorStore.ts
│ └── VectorUtils.ts
├── utils/ # Utility classes
├── tools/ # MCP tool interfaces
└── index.ts # Server entry point
`

🤝 Contributing

Contributions, issues, and feature requests are welcome!

1. Fork the project
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature`)
5. Open a Pull Request

📄 License

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

🔗 Links

- GitHub Repository
- NPM Package
- Issue Tracker
- 中文文档