AI导哈

内存管理服务器

基于模型上下文协议（MCP）的智能内存管理服务器，为AI模型提供持久化内存存储和强大的向量搜索功能。

  • by QianJue-CN
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 QianJue-CN/mcp-memory-server

使用说明

MCP内存服务器

基于模型上下文协议（MCP）的智能内存管理服务器，为AI模型提供持久的内存存储和强大的向量搜索功能。

🌟 特性

核心功能

  • CRUD操作：创建、读取、更新和删除内存条目
  • 多种内存类型：支持全局、对话和临时记忆
  • 文件夹管理：创建、删除和重命名文件夹以组织和分类记忆
  • 灵活存储：用户可自定义存储路径
  • JSON格式：基于JSON的存储，便于读取和备份

🎯 矢量搜索功能（新增！）

  • 语义搜索：基于含义而非关键字的智能搜索
  • 混合搜索：结合语义搜索和关键字搜索
  • 多提供商支持：支持Ollama、Gemini、OpenAI嵌入模型
  • 自动向量化：创建记忆时自动生成嵌入
  • 相似计算：计算任意两个文本之间的语义相似度
  • 高性能：内存缓存+文件持久化

高级功能

  • 内存缓存：提高了读取性能
  • 索引系统：快速搜索和过滤
  • 性能监控：实时性能指标
  • 文件管理：自动备份和恢复
  • 全面的错误处理：运行稳定可靠

📦 安装

从NPM安装（推荐）

npm install @qianjue/mcp-memory-server

从源代码安装

# 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

🚀 快速开始

MCP服务器配置

将此服务器添加到MCP客户端配置文件中：

适用于Claude Desktop（config.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"
      }
    }
  }
}

使用NPM包

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

配置选项

  • MCP_MEMORY_STORAGE_PATH：自定义存储目录路径
  • MCP_EMBEDDING_PROVIDER：默认嵌入提供程序（ollama/gegemini/openai）
  • MCP_EMBEDDING_API_KEY：嵌入提供程序的默认API密钥
  • LOG_LEVEL：日志记录级别（调试/信息/警告/错误）

基本用法

# Start the server directly
npm start

# Or run from dist
node dist/index.js

矢量搜索快速入门

1.配置嵌入提供程序

{
  "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.创建内存（自动生成向量）

{
  "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.语义搜索

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

📚 MCP工具

基本内存管理

1.create_memory

创建新的内存条目

{
  "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

读取内存条目

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

3.update_memory

更新内存条目

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

4.删除记忆

删除内存条目

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

5.获取信息统计

获取内存统计信息

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

矢量搜索工具

1.配置嵌入

配置嵌入模型提供程序

{
  "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.语义研究

语义相似度搜索

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

3.生成嵌入

为现有内存生成嵌入

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

4.计算相似性

计算两个文本之间的相似度

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

5.获取向量状态

获取矢量存储统计信息

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

文件夹管理工具

1.创建文件夹

创建新的内存文件夹

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

参数：

  • folderPath：文件夹路径，支持多级路径（例如“工作/项目A/文档”）
  • description：可选文件夹描述

使用案例：

  • 为不同的项目整理记忆
  • 按主题对记忆进行分类
  • 创建分层内存结构

2.删除文件夹

删除文件夹

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

参数：

  • folderPath：要删除的文件夹的路径
  • deleteMemories：是否删除文件夹中的所有内存（默认值：false）
    • true：删除文件夹及其所有内存
    • false：仅删除文件夹，保留记忆，但删除文件夹标签

重要提示：

  • 删除文件夹前确认是否需要保留记忆
  • 设置 deleteMemories: true 将永久删除文件夹中的所有记忆

3.重命名文件夹

重命名文件夹

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

参数：

  • oldPath：当前文件夹路径
  • newPath：新文件夹路径

特征：

  • 自动更新文件夹中所有内存的元数据
  • 确保重命名操作的原子性
  • 防止数据不一致

重要提示： 重命名文件夹时，系统会自动同步和更新 metadata.folderPath 文件夹中所有内存的字段，确保内存和文件夹之间的正确关联。

4.列表文件夹

列出所有文件夹

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

退货：

  • 文件夹路径
  • 文件夹名称
  • 创建时间
  • 包含的内存数量
  • 父文件夹路径

使用带有记忆的文件夹

创建内存时，可以使用指定文件夹 metadata.folderPath 字段：

{
  "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"
      }
    }
  }
}

笔记：

  • 全局存储器（类型：“全局”）不需要文件夹标签
  • 文件夹路径会自动存储在内存中 metadata.folderPath 领域
  • 重命名文件夹时，所有相关内存的文件夹路径都会自动更新

🔧 配置

嵌入提供程序配置

Ollama（本地模型）

{
  "provider": "ollama",
  "baseUrl": "http://localhost:11434",
  "model": "nomic-embed-text",
  "dimensions": 768
}

API双子星

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

OpenAI API

{
  "provider": "openai",
  "apiKey": "your-openai-api-key",
  "model": "text-embedding-3-small",
  "dimensions": 1536
}

环境变量

# 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

完整配置示例

以下是如何在Claude Desktop中配置MCP内存服务器的完整示例：

{
  "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"
      }
    }
  }
}

添加此配置后：

  1. 重新启动克劳德桌面
  2. 内存服务器将提供所有11个工具
  3. 如果提供了API键，将自动启用矢量搜索
  4. 内存将存储在指定目录中

📊 数据结构

记忆

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)
}

内存类型

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

🏗️ 项目结构

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

🤝 贡献

欢迎投稿、问题和功能请求！

  1. 分叉项目
  2. 创建要素分支(git checkout -b feature/amazing-feature)
  3. 提交您的更改(git commit -m 'Add amazing feature')
  4. 推到分支(git push origin feature/amazing-feature)
  5. 打开拉取请求

📄 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

🔗 链接

相关 MCP