A Model Context Protocol (MCP) server for intelligent memory management with vector search capabilities
npm install @qianjue/mcp-memory-serverAn intelligent memory management server based on Model Context Protocol (MCP), providing persistent memory storage and powerful vector search capabilities for AI models.
``bash`
npm install @qianjue/mcp-memory-server
`bashClone the repository
git clone https://github.com/QianJue-CN/mcp-memory-server.git
cd mcp-memory-server
π 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 startOr 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 descriptionUse 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 removedImportant 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 pathFeatures:
- 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/storageOptional: 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`)This project is licensed under the MIT License - see the LICENSE file for details.
- GitHub Repository
- NPM Package
- Issue Tracker
- δΈζζζ‘£