使用说明

内存MCP服务器

模型上下文协议（MCP）服务器，提供动态短期和长期内存管理，并支持中文。

概述

此MCP服务器实现了从GentianAphrodite项目中提取的复杂内存系统，提供：

短期记忆：基于关键字、时间衰减的动态记忆，带有相关性评分
长期记忆：基于触发器的永久存储器，可执行JS代码，实现灵活激活
中文语言支持：内置jieba分词，实现最佳中文文本处理
多个对话：每个会话ID都有独立的内存空间

特性

短期记忆

🔍 关键字提取：中文文本使用TF-IDF和jieba
⏰ 时间衰减：记忆相关性的指数时间衰减模型
📊 相关性评分：基于关键字匹配、时间和激活历史的动态评分
🎲 智能选择：三层选择（顶部相关、下一个相关、随机闪回）
🧹 自动清理：自动删除旧的或不相关的记忆（可配置）
🖼️ 图像存储器：用于视觉相似性搜索的可选图像嵌入

长期记忆

🎯 触发条件：执行JavaScript代码以灵活激活内存
🔒 沙盒执行：使用Node.js内置的vm模块进行安全的js代码评估
🎰 随机召回：偶然记忆激活，丰富上下文
📝 上下文跟踪：记录创建和更新上下文
🖼️ 多模式支持：图像、音频和自定义嵌入

数据优化

📉 空间节省：存储空间减少30-40%
🔄 自动重复数据删除：删除重复的关键字和图像
⏱️ 时间戳规范化：统一的时间戳格式（ISO 8601）
🗜️ 智能压缩：消除冗余 attachments 领域

性能与可靠性（新增！）

⚡ 查询缓存：使用智能结果缓存，搜索速度提高30-50%
⏱️ 超时保护：防止长时间运行的操作阻塞服务器
🚦 速率限制：防止API滥用（每次对话100次请求/分钟）
🛡️ 输入验证：对所有输入进行全面消毒和验证
📝 结构化日志记录：JSON格式的日志，便于解析和监控
📊 性能指标：实时指标收集（延迟、错误率、缓存命中率）
💚 健康监测：内置健康检查，用于主动检测问题
🔍 审计日志：对所有操作进行完整的合规审计跟踪
🔄 优雅地关闭：确保在关闭之前完成所有挂起的写入

新功能（新！）

💾 备份和恢复：导出和导入整个内存数据库
- backup_memories：使用元数据创建带时间戳的备份
- restore_memories：使用合并或覆盖模式从备份还原
- list_backups：浏览可用的备份文件
- delete_backup：清理旧备份
🔎 高级搜索：强大的搜索功能，灵活的过滤
- search_memories：使用关键字、日期范围、分数过滤器进行搜索
- analyze_memory_patterns：统计分析和见解
- 支持按相关性、分数或时间戳排序
- 搜索短期、长期或两种记忆类型
📈 系统监控：实时服务器监控工具
- health_check：获取服务器运行状况和诊断
- get_metrics：查看性能指标（P50/P95/P99延迟、错误率）
- get_cache_stats：监控查询缓存命中率

安装

# Clone or download this directory
cd memory-mcp-server

# Install dependencies
npm install

# Make the server executable (Unix/Linux/Mac)
chmod +x src/index.js

用法

使用克劳德桌面

添加到您的Claude Desktop配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "memory": {
      "command": "node",
      "args": ["/absolute/path/to/memory-mcp-server/src/index.js"]
    }
  }
}

使用Cursor或其他MCP客户端

根据客户端的MCP服务器设置说明进行配置，指向 src/index.js.

MCP功能

此服务器通过以下方式实现了完整的模型上下文协议规范：

工具：13个内存管理工具
资源：4个系统检查资源
鼓励：4个用于常见内存任务的提示模板

可用工具

短期记忆工具

`add_short_term_memory`

从对话信息中添加新的短期记忆。

参数：

messages （数组）：最近包含角色和内容的对话消息
conversation_id （string）：唯一对话标识符
roleWeights （对象，可选）：为不同角色自定义权重

例子：

{
  "messages": [
    {"role": "user", "content": "My birthday is July 17, 1990"},
    {"role": "assistant", "content": "I'll remember that!"}
  ],
  "conversation_id": "user_123",
  "roleWeights": {
    "user": 2.7,
    "assistant": 2.0,
    "system": 1.0
  }
}

`search_short_term_memories`

根据当前上下文搜索相关记忆。

参数：

recentMessages （array）：要搜索的最近邮件
conversation_id （string）：当前对话ID
roleWeights （对象，可选）：角色权重

退货： 最相关、次相关和随机闪回记忆

`delete_short_term_memories`

删除与模式匹配的记忆。

参数：

pattern （string）：关键字或正则表达式模式（例如，“/patter/i”）
conversation_id （字符串）：对话ID

`get_memory_stats`

获取有关短期记忆的统计数据。

`cleanup_memories`

手动触发内存清理（删除旧/低相关性内存）。

`get_frequent_conversation`

获取最常被提及的对话ID。

长期记忆工具

`add_long_term_memory`

添加具有触发条件的永久存储器。

参数：

name （string）：唯一内存名称
prompt （string）：内存内容
trigger （string）：激活条件的JavaScript代码
conversation_id （字符串，可选）：用于存储内存的对话ID（默认为“默认”）
createdContext （字符串，可选）：上下文描述
recentMessages （数组，可选）：根据消息自动生成上下文

触发器示例：

// Activate when "birthday" is mentioned
"match_keys(context.messages, ['birthday', '生日'], 'any')"

// Activate on specific date or when mentioned
"match_keys(context.messages, ['anniversary'], 'any') || (new Date().getMonth() === 6 && new Date().getDate() === 17)"

// Multiple keywords required
"match_keys_all(context.messages, ['project', 'deadline'], 'user')"

在触发器上下文中可用：

context.messages：最近的消息数组
context.conversation_id：当前对话ID
context.participants：参与者信息
match_keys(messages, keywords, scope, depth)：匹配任何关键字
match_keys_all(messages, keywords, scope, depth)：匹配所有关键字
Date, Math, RegExp, JSON：安全的内置对象

`update_long_term_memory`

更新现有的长期记忆。

参数：

name （string）：要更新的内存名称
trigger （字符串，可选）：新的触发条件
prompt （字符串，可选）：新内容
conversation_id （字符串，可选）：拥有内存的对话ID
updatedContext （字符串，可选）：更新上下文

`delete_long_term_memory`

按名称删除长期记忆。

参数：

name （string）：要删除的内存名称
conversation_id （字符串，可选）：拥有内存的对话ID

`list_long_term_memories`

列出所有长期记忆的基本信息。

参数：

conversation_id （字符串，可选）：要检查的对话ID（默认为“默认”）

`search_long_term_memories`

根据当前上下文搜索和激活记忆。

参数：

messages （数组）：最近的对话消息
conversation_id （string）：当前对话ID
participants （对象，可选）：参与者信息

退货： 激活记忆（触发）和随机记忆

`get_memory_context`

获取特定内存的创建和更新上下文。

参数：

name （string）：要检查的内存名称
conversation_id （字符串，可选）：拥有内存的对话ID

可用资源

MCP资源允许AI检查内存系统状态：

`memory://stats/overview`

全系统概览和健康状况。

退货：

对话总数
系统健康状态
可用特征

`memory://conversations/list`

列出所有具有内存统计信息的对话。

退货：

对话ID
短期记忆计数
长期记忆计数

`memory://stats/conversation/{id}`

特定对话的详细统计数据。

参数：

{id}：要检查的对话ID

退货：

短期记忆：总分、分数、年龄范围
长期内存：总数、更新计数、时间戳

`memory://guide/best-practices`

有效使用存储系统的综合指南。

退货：

短期和长期记忆的最佳实践
触发条件示例
多式联运支持指南
常见使用模式

可用提示

MCP提示为常见任务提供指导工作流程：

`remember-user-info`

将重要的用户信息存储在长期记忆中。

论据：

info_type （必填）：信息类型（偏好、生日、事实等）
information （必填）：要记住的信息
conversation_id （可选）：目标对话ID

指导AI：

创建适当的内存名称
生成相关触发条件
使用add_long_term_memory工具

`recall-context`

根据当前对话搜索相关记忆。

论据：

current_topic （必填）：当前主题或问题
conversation_id （可选）：要搜索的对话

指导AI：

在短期记忆中搜索最近的上下文
在长期记忆中寻找永恒的事实
考虑关键字相关性和时间衰减

`create-reminder`

创建基于上下文或日期激活的条件提醒。

论据：

reminder_content （必填）：提醒什么
trigger_condition （必填）：何时触发（关键字或日期）
conversation_id （可选）：目标对话

指导AI：

将自然语言条件转换为JavaScript
创建基于日期或基于关键字的触发器
使用带有适当触发器的add_long_term_memory

`analyze-conversation`

分析对话历史，并建议应该记住什么。

论据：

conversation_id （必填）：要分析的对话

指导AI：

获取当前内存统计信息
识别重要信息类型
根据短期与长期储存进行分类
创建适当的内存条目

建筑

memory-mcp-server/
├── src/
│   ├── index.js                 # MCP server entry point
│   ├── memory/
│   │   ├── short-term.js        # Short-term memory logic
│   │   ├── long-term.js         # Long-term memory logic
│   │   ├── storage.js           # JSON file storage with caching
│   │   └── modalities.js        # Multimodal attachment handling
│   ├── nlp/
│   │   ├── jieba.js             # Chinese segmentation
│   │   └── keywords.js          # Keyword matching
│   ├── triggers/
│   │   └── matcher.js           # JS code execution sandbox (Node.js vm)
│   ├── tools/
│   │   ├── short-term-tools.js  # Short-term MCP tools
│   │   └── long-term-tools.js   # Long-term MCP tools
│   ├── resources/
│   │   └── index.js             # MCP resources (stats, guides)
│   ├── prompts/
│   │   └── index.js             # MCP prompts (workflows)
│   └── utils/
│       ├── lru-cache.js         # LRU cache for managers
│       └── zod-to-json-schema.js
└── data/                        # Memory storage (auto-created)
    └── {conversation_id}/
        ├── short-term-memory.json
        └── long-term-memory.json

内存算法

短期记忆相关性

relevance = keyword_match_score - time_penalty + memory_score

where:
  keyword_match_score = Σ(current_kw.weight + memory_kw.weight)
  time_penalty = 15 * (1 - e^(-time_diff * 2e-9))
  memory_score = accumulated score from past activations

选择策略

最相关 （最多2）：相关性得分最高
下一个相关 （最多1）：次高分
随机闪回 （最多2个）：从剩余记忆中随机加权

过滤：

排除过去20分钟的相同对话记忆
排除任何选定内存10分钟内的内存
确保回忆的多样性

清理政策

每24小时触发一次
删除1年以上的记忆
删除低相关性记忆（得分<-5）
始终保留至少512个记忆

发展

# Run in development mode with auto-reload
npm run dev

# Run normally
npm start

安全

沙盒执行：长期内存触发器在Node.js内置中运行 vm 具有超时保护的模块沙盒
无文件系统访问权限：触发代码无法访问文件系统（沙盒）
无网络访问：触发代码无法发出网络请求
超时保护：1秒执行超时可防止无限循环
安全上下文：只有安全的内置对象才会暴露于触发代码

备注：内置 vm 模块为大多数用例提供了良好的隔离。为了在生产环境中获得最大的安全性，请考虑在具有额外限制的容器化环境中运行MCP服务器。

局限性

内存存储是基于文件的（JSON），适合适度使用
触发器执行有1秒超时
使用LRU缓存的管理器实例（最多100个对话，30分钟空闲超时）
中文文本处理优化（对于其他语言可能不太优化）

性能优化

写缓存：延迟写入1秒批处理以减少磁盘I/O
目录缓存：缓存目录存在检查以避免重复的文件系统调用
LRU管理器缓存：自动清理不活动的对话管理器可防止内存泄漏
重试逻辑：文件操作在出现暂时性错误时会自动重试，并采用指数回退
优雅地关闭：挂起的写入被刷新，资源在关机信号时被清理
重复数据消除：自动删除重复的图像和关键字（节省30-40%的空间）
时间戳规范化：统一的时间戳格式消除了冗余

图像存储功能

服务器包括可选的图像存储功能：

图像模式：使用嵌入、标签和描述存储带有记忆的图像
相似性搜索：使用嵌入上的余弦相似性查找视觉上相似的记忆
自动重复数据删除：自动检测并删除重复图像（URL或内容哈希）
灵活嵌入：支持CLIP、ResNet或自定义图像嵌入
Base64支持：处理URL和数据URI图像

例子：

import { createImageModality } from './src/utils/image-processor.js';

const imageMemory = createImageModality({
  uri: 'https://example.com/photo.jpg',
  embedding: [0.1, 0.2, 0.3, ...],  // 512-d vector from CLIP/etc
  tags: ['vacation', 'beach'],
  description: 'Sunset at the beach'
});

// Use in memory creation
await addShortTermMemory(messages, conversationId, {
  modalities: [imageMemory]
});

看 docs/IMAGE_MEMORY.md 详细指南。

数据优化

内置数据优化可将存储空间减少30-40%：

时间戳规范化: time_stamp/timeStamp/timestamp → timestamp （ISO 8601）
删除冗余: attachments 字段已删除（使用 modalities 仅）
关键字重复数据删除：不区分大小写的合并，最大重量保留
图像重复数据删除：根据URI或内容哈希删除重复图像

所有优化都会在存储过程中自动应用。看文档/数据优化.md 了解详情。

性能基准

最新增强功能带来的性能改进：

功能	改进	详细信息
查询缓存	速度提高30-50%	缓存50个最近的查询5分钟
向量相似性	速度提高40-60%	预先计算的幅度缓存
速率限制	保护	每次对话100个请求/分钟
超时保护	可靠性	所有操作在5-30s后超时
数据存储	减少30-40%	重复数据删除和标准化
健康检查	主动	内存、错误率、缓存监控
审核日志	完成	记录所有带有时间戳的操作

测试结果

运行综合测试套件：

node test-improvements.js

预期产量： 36项测试通过 涵盖：

查询缓存（4个测试）
超时处理（3次测试）
速率限制（5次测试）
输入验证（8次测试）
结构化日志记录（3次测试）
性能指标（6次测试）
健康检查（4次测试）
审计日志记录（3次测试）

建筑

src/
├── memory/           # Core memory management
│   ├── short-term.js    # Dynamic keyword-based memory
│   ├── long-term.js     # Trigger-based permanent memory
│   └── storage.js       # JSON file persistence
├── tools/            # MCP tool implementations
│   ├── short-term-tools.js
│   ├── long-term-tools.js
│   ├── backup-tools.js     # NEW: Backup/restore
│   └── search-tools.js     # NEW: Advanced search
├── utils/            # Utility modules
│   ├── query-cache.js      # NEW: Query result caching
│   ├── timeout.js          # NEW: Timeout handling
│   ├── logger.js           # NEW: Structured logging
│   └── lru-cache.js        # LRU cache implementation
├── security/         # NEW: Security features
│   ├── rate-limiter.js     # API rate limiting
│   ├── input-validator.js  # Input sanitization
│   └── audit-log.js        # Audit trail logging
├── monitoring/       # NEW: Monitoring features
│   └── metrics.js          # Performance metrics
├── health/           # NEW: Health checks
│   └── index.js            # Health monitoring
├── resources/        # MCP resources
│   └── index.js
└── prompts/          # MCP prompts
    └── index.js

许可证

BSD-3-条款许可

鸣谢

摘录并概括自阿芙罗狄蒂项目。

使用说明

内存MCP服务器

概述

特性

短期记忆

长期记忆

数据优化

性能与可靠性（新增！）

新功能（新！）

安装

用法

使用克劳德桌面

使用Cursor或其他MCP客户端

MCP功能

可用工具

短期记忆工具

add_short_term_memory

search_short_term_memories

delete_short_term_memories

get_memory_stats

cleanup_memories

get_frequent_conversation

长期记忆工具

add_long_term_memory

update_long_term_memory

delete_long_term_memory

list_long_term_memories

search_long_term_memories

get_memory_context

可用资源

memory://stats/overview

memory://conversations/list

memory://stats/conversation/{id}

memory://guide/best-practices

可用提示

remember-user-info

recall-context

create-reminder

analyze-conversation

建筑

内存算法

短期记忆相关性

选择策略

清理政策

发展

安全

局限性

性能优化

图像存储功能

数据优化

性能基准

测试结果

建筑

许可证

鸣谢

相关 MCP

内存服务器

远程内存银行服务器

内存管理服务器

内存管理服务器

AI代理内存管理服务

缓存增强生成服务器

`add_short_term_memory`

`search_short_term_memories`

`delete_short_term_memories`

`get_memory_stats`

`cleanup_memories`

`get_frequent_conversation`

`add_long_term_memory`

`update_long_term_memory`

`delete_long_term_memory`

`list_long_term_memories`

`search_long_term_memories`

`get_memory_context`

`memory://stats/overview`

`memory://conversations/list`

`memory://stats/conversation/{id}`

`memory://guide/best-practices`

`remember-user-info`

`recall-context`

`create-reminder`

`analyze-conversation`