Memento MCP：面向法学硕士 (LLM) 的知识图谱记忆系统
可扩展、高性能的知识图谱记忆系统，具有语义检索、上下文回忆和时间感知功能。为任何支持模型上下文协议的 LLM 客户端（例如 Claude Desktop、Cursor、Github Copilot）提供弹性、自适应且持久的长期本体记忆。
核心概念
实体
实体是知识图谱中的主要节点。每个实体具有：
- 唯一名称（标识符）
- 实体类型（例如“人”、“组织”、“事件”）
- 观察结果列表
- 向量嵌入（用于语义搜索）
- 完整版本历史记录
例子：
{
"name": "John_Smith",
"entityType": "person",
"observations": ["Speaks fluent Spanish"]
}
关系
关系定义具有增强属性的实体之间的有向连接：
- 强度指标（0.0-1.0）
- 置信水平（0.0-1.0）
- 丰富的元数据（来源、时间戳、标签）
- 通过版本历史实现时间感知
- 基于时间的置信度衰减
例子：
{
"from": "John_Smith",
"to": "Anthropic",
"relationType": "works_at",
"strength": 0.9,
"confidence": 0.95,
"metadata": {
"source": "linkedin_profile",
"last_verified": "2025-03-21"
}
}
存储后端
Memento MCP 使用 Neo4j 作为其存储后端，为图形存储和向量搜索功能提供了统一的解决方案。
为什么选择 Neo4j？
- 统一存储：将图形和矢量存储整合到单个数据库中
- 原生图形操作：专为图形遍历和查询而构建
- 集成向量搜索：Neo4j 内置的向量相似性搜索
- 可扩展性：大型知识图谱具有更好的性能
- 简化的架构：简洁的设计，所有操作均使用单一数据库
先决条件
Neo4j 桌面设置（推荐）
开始使用 Neo4j 最简单的方法是使用Neo4j Desktop ：
- 从https://neo4j.com/download/下载并安装 Neo4j Desktop
- 创建新项目
- 添加新数据库
- 将密码设置为
memento_password （或您喜欢的密码） - 启动数据库
Neo4j 数据库可在以下位置获取：
- Bolt URI ：
bolt://127.0.0.1:7687 （用于驱动程序连接） - HTTP ：
http://127.0.0.1:7474 7474（用于 Neo4j 浏览器 UI） - 默认凭证：用户名：
neo4j ，密码： memento_password （或您配置的任何密码）
使用 Docker 设置 Neo4j（替代方案）
或者，您可以使用 Docker Compose 来运行 Neo4j：
# Start Neo4j container
docker-compose up -d neo4j
# Stop Neo4j container
docker-compose stop neo4j
# Remove Neo4j container (preserves data)
docker-compose rm neo4j
使用 Docker 时，Neo4j 数据库将在以下位置可用：
- Bolt URI ：
bolt://127.0.0.1:7687 （用于驱动程序连接） - HTTP ：
http://127.0.0.1:7474 7474（用于 Neo4j 浏览器 UI） - 默认凭据：用户名：
neo4j ，密码： memento_password
数据持久化与管理
由于docker-compose.yml文件中的 Docker 卷配置，Neo4j 数据在容器重启甚至版本升级后依然有效：
volumes:
- ./neo4j-data:/data
- ./neo4j-logs:/logs
- ./neo4j-import:/import
这些映射确保：
/data目录（包含所有数据库文件）在您的主机上保留在./neo4j-data/logs目录在您的主机上保留在./neo4j-logs/import目录（用于导入数据文件）保留在./neo4j-import
如果需要，您可以在docker-compose.yml文件中修改这些路径以将数据存储在不同的位置。
升级 Neo4j 版本
您可以更改 Neo4j 版本而不会丢失数据：
- 在
docker-compose.yml中更新 Neo4j 镜像版本 - 使用
docker-compose down && docker-compose up -d neo4j重新启动容器 - 使用
npm run neo4j:init重新初始化架构
只要卷映射保持不变，数据就会在此过程中保留下来。
完全数据库重置
如果您需要完全重置 Neo4j 数据库：
# Stop the container
docker-compose stop neo4j
# Remove the container
docker-compose rm -f neo4j
# Delete the data directory contents
rm -rf ./neo4j-data/*
# Restart the container
docker-compose up -d neo4j
# Reinitialize the schema
npm run neo4j:init
备份数据
要备份 Neo4j 数据，您只需复制数据目录：
# Make a backup of the Neo4j data
cp -r ./neo4j-data ./neo4j-data-backup-$(date +%Y%m%d)
Neo4j CLI 实用程序
Memento MCP 包含用于管理 Neo4j 操作的命令行实用程序：
测试连接
测试与 Neo4j 数据库的连接：
# Test with default settings
npm run neo4j:test
# Test with custom settings
npm run neo4j:test -- --uri bolt://127.0.0.1:7687 --username myuser --password mypass --database neo4j
初始化架构
在正常运行情况下，当 Memento MCP 连接到数据库时，Neo4j 模式初始化会自动进行。您无需在常规使用中运行任何手动命令。
以下命令仅对于开发、测试或高级定制场景才是必需的：
# Initialize with default settings (only needed for development or troubleshooting)
npm run neo4j:init
# Initialize with custom vector dimensions
npm run neo4j:init -- --dimensions 768 --similarity euclidean
# Force recreation of all constraints and indexes
npm run neo4j:init -- --recreate
# Combine multiple options
npm run neo4j:init -- --vector-index custom_index --dimensions 384 --recreate
高级功能
语义搜索
根据含义而非仅仅根据关键词来查找语义相关的实体：
- 向量嵌入：使用 OpenAI 的嵌入模型将实体自动编码到高维向量空间中
- 余弦相似度：即使使用不同的术语，也能找到相关概念
- 可配置阈值：设置最小相似度分数以控制结果相关性
- 跨模式搜索：使用文本查询来查找相关实体，无论它们是如何描述的
- 多模型支持：兼容多种嵌入模型（OpenAI text-embedding-3-small/large）
- 上下文检索：根据语义而不是精确的关键字匹配来检索信息
- 优化默认值：调整参数以平衡精度和召回率（相似度阈值 0.6，启用混合搜索）
- 混合搜索：结合语义和关键字搜索以获得更全面的结果
- 自适应搜索：系统根据查询特征和可用数据，智能地选择仅矢量、仅关键字或混合搜索
- 性能优化：优先进行向量搜索以实现语义理解，同时保持回退机制以实现弹性
- 查询感知处理：根据查询复杂性和可用的实体嵌入调整搜索策略
时间意识
通过时间点图形检索跟踪实体和关系的完整历史记录：
- 完整版本历史记录：对实体或关系的每次更改都通过时间戳保存
- 时间点查询：检索过去任何时刻知识图谱的精确状态
- 变更跟踪：自动记录 createdAt、updatedAt、validFrom 和 validTo 时间戳
- 时间一致性：保持对知识如何演变的历史准确看法
- 非破坏性更新：更新会创建新版本，而不是覆盖现有数据
- 基于时间的过滤：根据时间标准过滤图形元素
- 历史探索：调查特定信息如何随时间变化
信心衰退
根据可配置的半衰期，关系的可信度会随着时间的推移而自动衰减：
- 基于时间的衰减：如果不加强，关系中的信心自然会随着时间的推移而下降
- 可配置的半衰期：定义信息变得不确定的速度（默认值：30 天）
- 最低置信水平：设置阈值以防止重要信息过度衰减
- 衰减元数据：每个关系都包含详细的衰减计算信息
- 非破坏性：原始置信值与衰减值一起保留
- 强化学习：当新的观察得到强化时，关系会重新获得信心
- 参考时间灵活性：根据任意参考时间计算衰减以进行历史分析
高级元数据
对实体和具有自定义字段的关系提供丰富的元数据支持：
- 源跟踪：记录信息来源（用户输入、分析、外部来源）
- 置信度：根据确定性为关系分配置信度分数（0.0-1.0）
- 关系强度：表示关系的重要性或强度（0.0-1.0）
- 时间元数据：跟踪信息的添加、修改或验证时间
- 自定义标签：添加任意标签进行分类和过滤
- 结构化数据：在元数据字段中存储复杂的结构化数据
- 查询支持：基于元数据属性的搜索和过滤
- 可扩展架构：根据需要添加自定义字段，而无需修改核心数据模型
MCP API 工具
LLM 客户端主机可以通过模型上下文协议使用以下工具：
实体管理
- 创建实体
- 在知识图谱中创建多个新实体
- 输入：
entities （对象数组）- 每个对象包含：
name （字符串）：实体标识符entityType （字符串）：类型分类observations （string[]）：相关观察
- 添加观察结果
- 向现有实体添加新观察
- 输入：
observations （对象数组）- 每个对象包含：
entityName （字符串）：目标实体contents （string[]）：要添加的新观察结果
- 删除实体
- 删除实体及其关系
- 输入：
entityNames （string[]）
- 删除观察结果
- 从实体中删除特定观察结果
- 输入：
deletions （对象数组）- 每个对象包含：
entityName （字符串）：目标实体observations （string[]）：要删除的观察结果
关系管理
- 创建关系
- 在具有增强属性的实体之间创建多个新关系
- 输入：
relations （对象数组）- 每个对象包含：
from （字符串）：源实体名称to （字符串）：目标实体名称relationType （字符串）：关系类型strength （数字，可选）：关系强度（0.0-1.0）confidence （数字，可选）：置信度（0.0-1.0）metadata （对象，可选）：自定义元数据字段
- 获取关系
- 获取具有增强属性的特定关系
- 输入：
from （字符串）：源实体名称to （字符串）：目标实体名称relationType （字符串）：关系类型
- 更新关系
- 使用增强属性更新现有关系
- 输入：
relation （对象）：- 包含：
from （字符串）：源实体名称to （字符串）：目标实体名称relationType （字符串）：关系类型strength （数字，可选）：关系强度（0.0-1.0）confidence （数字，可选）：置信度（0.0-1.0）metadata （对象，可选）：自定义元数据字段
- 删除关系
- 从图中删除特定关系
- 输入：
relations （对象数组）- 每个对象包含：
from （字符串）：源实体名称to （字符串）：目标实体名称relationType （字符串）：关系类型
图操作
- 读取图
- 搜索节点
- 打开节点
- 按名称检索特定节点
- 输入：
names （string[]）
语义搜索
- 语义搜索
- 使用向量嵌入和相似性在语义上搜索实体
- 输入：
query （字符串）：要进行语义搜索的文本查询limit （数字，可选）：返回的最大结果数（默认值：10）min_similarity （数字，可选）：最小相似度阈值（0.0-1.0，默认值：0.6）entity_types （string[]，可选）：按实体类型过滤结果hybrid_search （布尔值，可选）：结合关键字和语义搜索（默认值：true）semantic_weight （数字，可选）：混合搜索中语义结果的权重（0.0-1.0，默认值：0.6）
- 特征：
- 根据查询上下文智能选择最佳搜索方法（向量、关键字或混合）
- 通过回退机制优雅地处理没有语义匹配的查询
- 通过自动优化决策保持高性能
- 获取实体嵌入
- 获取特定实体的向量嵌入
- 输入：
entity_name （字符串）：要获取嵌入的实体的名称
时间特征
- 获取实体历史记录
- 获取实体的完整版本历史记录
- 输入：
entityName （字符串）
- 获取关系历史记录
- 获取关系的完整版本历史记录
- 输入：
from （字符串）：源实体名称to （字符串）：目标实体名称relationType （字符串）：关系类型
- 获取时间图
- 获取特定时间戳的图表状态
- 输入：
timestamp （数字）：Unix 时间戳（自纪元以来的毫秒数）
- 获取衰减图
- 获取具有随时间衰减的置信度值的图表
- 输入：
options （对象，可选）：reference_time （数字）：衰减计算的参考时间戳（自纪元以来的毫秒数）decay_factor （数字）：可选衰减因子覆盖
配置
环境变量
使用以下环境变量配置 Memento MCP：
# Neo4j Connection Settings
NEO4J_URI=bolt://127.0.0.1:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=memento_password
NEO4J_DATABASE=neo4j
# Vector Search Configuration
NEO4J_VECTOR_INDEX=entity_embeddings
NEO4J_VECTOR_DIMENSIONS=1536
NEO4J_SIMILARITY_FUNCTION=cosine
# Embedding Service Configuration
MEMORY_STORAGE_TYPE=neo4j
OPENAI_API_KEY=your-openai-api-key
OPENAI_EMBEDDING_MODEL=text-embedding-3-small
# Debug Settings
DEBUG=true
命令行选项
Neo4j CLI 工具支持以下选项：
--uri <uri> Neo4j server URI (default: bolt://127.0.0.1:7687)
--username <username> Neo4j username (default: neo4j)
--password <password> Neo4j password (default: memento_password)
--database <n> Neo4j database name (default: neo4j)
--vector-index <n> Vector index name (default: entity_embeddings)
--dimensions <number> Vector dimensions (default: 1536)
--similarity <function> Similarity function (cosine|euclidean) (default: cosine)
--recreate Force recreation of constraints and indexes
--no-debug Disable detailed output (debug is ON by default)
嵌入模型
可用的 OpenAI 嵌入模型：
text-embedding-3-small ：高效、经济（1536 维）text-embedding-3-large ：准确率更高，成本更高（3072 维）text-embedding-ada-002 ：旧模型（1536 维）
OpenAI API 配置
要使用语义搜索，您需要配置 OpenAI API 凭据：
- 从OpenAI获取 API 密钥
- 使用以下配置来配置您的环境：
# OpenAI API Key for embeddings
OPENAI_API_KEY=your-openai-api-key
# Default embedding model
OPENAI_EMBEDDING_MODEL=text-embedding-3-small
注意：在测试环境中，如果未提供 API 密钥，系统将模拟嵌入生成。但是，建议在集成测试中使用真实的嵌入。
与 Claude Desktop 集成
配置
将其添加到您的claude_desktop_config.json中：
{
"mcpServers": {
"memento": {
"command": "npx",
"args": ["-y", "@gannonh/memento-mcp"],
"env": {
"MEMORY_STORAGE_TYPE": "neo4j",
"NEO4J_URI": "bolt://127.0.0.1:7687",
"NEO4J_USERNAME": "neo4j",
"NEO4J_PASSWORD": "memento_password",
"NEO4J_DATABASE": "neo4j",
"NEO4J_VECTOR_INDEX": "entity_embeddings",
"NEO4J_VECTOR_DIMENSIONS": "1536",
"NEO4J_SIMILARITY_FUNCTION": "cosine",
"OPENAI_API_KEY": "your-openai-api-key",
"OPENAI_EMBEDDING_MODEL": "text-embedding-3-small",
"DEBUG": "true"
}
}
}
}
或者，对于本地开发，您可以使用：
{
"mcpServers": {
"memento": {
"command": "/path/to/node",
"args": ["/path/to/memento-mcp/dist/index.js"],
"env": {
"MEMORY_STORAGE_TYPE": "neo4j",
"NEO4J_URI": "bolt://127.0.0.1:7687",
"NEO4J_USERNAME": "neo4j",
"NEO4J_PASSWORD": "memento_password",
"NEO4J_DATABASE": "neo4j",
"NEO4J_VECTOR_INDEX": "entity_embeddings",
"NEO4J_VECTOR_DIMENSIONS": "1536",
"NEO4J_SIMILARITY_FUNCTION": "cosine",
"OPENAI_API_KEY": "your-openai-api-key",
"OPENAI_EMBEDDING_MODEL": "text-embedding-3-small",
"DEBUG": "true"
}
}
}
}
重要提示：始终在 Claude Desktop 配置中明确指定嵌入模型，以确保一致的行为。
推荐的系统提示
为了与 Claude 进行最佳集成，请将这些语句添加到系统提示符中：
You have access to the Memento MCP knowledge graph memory system, which provides you with persistent memory capabilities.
Your memory tools are provided by Memento MCP, a sophisticated knowledge graph implementation.
When asked about past conversations or user information, always check the Memento MCP knowledge graph first.
You should use semantic_search to find relevant information in your memory when answering questions.
测试语义搜索
配置完成后，Claude 可以通过自然语言访问语义搜索功能：
- 要创建具有语义嵌入的实体：
User: "Remember that Python is a high-level programming language known for its readability and JavaScript is primarily used for web development."
- 按语义搜索：
User: "What programming languages do you know about that are good for web development?"
- 要检索特定信息：
User: "Tell me everything you know about Python."
这种方法的优势在于用户可以自然地进行交互，而 LLM 则负责处理选择和使用适当记忆工具的复杂性。
实际应用
Memento 的自适应搜索功能提供了实际的好处：
- 查询多功能性：用户无需担心如何表述问题 - 系统会自动适应不同的查询类型
- 故障恢复：即使语义匹配不可用，系统也可以在无需用户干预的情况下恢复到替代方法
- 性能效率：通过智能选择最佳搜索方法，系统平衡每个查询的性能和相关性
- 改进的上下文检索：LLM 对话受益于更好的上下文检索，因为系统可以在复杂的知识图谱中找到相关信息
例如，当用户询问“你对机器学习了解多少？”时，即使用户没有明确提及“机器学习”，系统也能检索概念相关的实体——可能是关于神经网络、数据科学或特定算法的实体。但是，如果语义搜索的结果不足，系统会自动调整方法，以确保仍然返回有用的信息。
故障排除
矢量搜索诊断
Memento MCP 包含内置诊断功能，可帮助解决矢量搜索问题：
- 嵌入验证：系统检查实体是否具有有效的嵌入，如果缺失则自动生成
- 向量索引状态：验证向量索引是否存在且处于 ONLINE 状态
- 回退搜索：如果向量搜索失败，系统将返回基于文本的搜索
- 详细日志记录：全面记录矢量搜索操作，以便排除故障
调试工具（当 DEBUG=true 时）
启用调试模式后，可以使用其他诊断工具：
- 诊断_vector_search ：有关 Neo4j 向量索引、嵌入计数和搜索功能的信息
- force_generate_embedding ：强制为特定实体生成嵌入
- debug_embedding_config ：有关当前嵌入服务配置的信息
开发者重置
要在开发过程中完全重置 Neo4j 数据库：
# Stop the container (if using Docker)
docker-compose stop neo4j
# Remove the container (if using Docker)
docker-compose rm -f neo4j
# Delete the data directory (if using Docker)
rm -rf ./neo4j-data/*
# For Neo4j Desktop, right-click your database and select "Drop database"
# Restart the database
# For Docker:
docker-compose up -d neo4j
# For Neo4j Desktop:
# Click the "Start" button for your database
# Reinitialize the schema
npm run neo4j:init
建筑与开发
# Clone the repository
git clone https://github.com/gannonh/memento-mcp.git
cd memento-mcp
# Install dependencies
npm install
# Build the project
npm run build
# Run tests
npm test
# Check test coverage
npm run test:coverage
安装
通过 Smithery 安装
通过Smithery自动为 Claude Desktop 安装 memento-mcp：
npx -y @smithery/cli install @gannonh/memento-mcp --client claude
使用 npx 进行全局安装
您可以使用 npx 直接运行 Memento MCP，而无需全局安装：
npx -y @gannonh/memento-mcp
建议将此方法与 Claude Desktop 和其他 MCP 兼容客户端一起使用。
本地安装
对于开发或为项目做出贡献：
# Install locally
npm install @gannonh/memento-mcp
# Or clone the repository
git clone https://github.com/gannonh/memento-mcp.git
cd memento-mcp
npm install
执照
麻省理工学院