Memento MCP：适用于LLM的知识图谱记忆系统

一个可扩展、高性能的知识图谱记忆系统，具备语义检索、上下文回忆和时间感知功能。为支持模型上下文协议的任何LLM客户端（例如Claude Desktop、Cursor、Github Copilot）提供持久、适应性强且长期的本体记忆。

核心概念

实体

实体是知识图谱中的主要节点。每个实体包括：

• 唯一名称（标识符）
• 实体类型（例如，“人”，“组织”，“事件”）
• 观察列表
• 向量嵌入（用于语义搜索）
• 完整版本历史

示例：

{
  "name": "John_Smith",
  "entityType": "person",
  "observations": ["讲流利的西班牙语"]
}

关系

关系定义了实体之间的有向连接，并具有增强属性：

• 强度指标（0.0-1.0）
• 置信水平（0.0-1.0）
• 丰富的元数据（来源，时间戳，标签）
• 具备版本历史的时间感知
• 时间衰减置信度

示例：

{
  "from": "John_Smith",
  "to": "Anthropic",
  "relationType": "works_at",
  "strength": 0.9,
  "confidence": .95,
  "metadata": {
    "source": "linkedin_profile",
    "last_verified": "2025-03-21"
  }
}

存储后端

Memento MCP 使用 Neo4j 作为其存储后端，提供图形存储和向量搜索能力的统一解决方案。

为什么选择 Neo4j？

• 统一存储：将图形和向量存储整合到单一数据库中
• 原生图形操作：专门针对图形遍历和查询构建
• 集成向量搜索：向量相似性搜索直接内置在 Neo4j 中
• 可扩展性：在大型知识图谱中表现更好
• 简化架构：单个数据库用于所有操作的干净设计

预备条件

• Neo4j 5.13+（需要向量搜索功能）

Neo4j Desktop 设置（推荐）

开始使用 Neo4j 的最简单方法是使用 Neo4j Desktop：

1. 从 https://neo4j.com/download/ 下载并安装 Neo4j Desktop
2. 创建一个新的项目
3. 添加一个新的数据库
4. 将密码设置为 memento_password（或您喜欢的密码）
5. 启动数据库

Neo4j 数据库将在以下位置可用：

• Bolt URI：bolt://127.0.0.1:7687（用于驱动程序连接）
• HTTP：http://127.0.0.1:7474（用于 Neo4j 浏览器界面）
• 默认凭据：用户名：neo4j，密码：memento_password（或您配置的内容）

使用 Docker 设置 Neo4j（替代方案）

或者，您可以使用 Docker Compose 来运行 Neo4j：

# 启动 Neo4j 容器
docker-compose up -d neo4j

# 停止 Neo4j 容器
docker-compose stop neo4j

# 移除 Neo4j 容器（保留数据）
docker-compose rm neo4j

使用 Docker 时，Neo4j 数据库将在以下位置可用：

• Bolt URI：bolt://127.0.0.1:7687（用于驱动程序连接）
• HTTP：http://127.0.0.1:7474（用于 Neo4j 浏览器界面）
• 默认凭据：用户名：neo4j，密码：memento_password

数据持久化和管理

由于 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 版本而不丢失数据：

1. 在 docker-compose.yml 中更新 Neo4j 镜像版本
2. 使用 docker-compose down && docker-compose up -d neo4j 重新启动容器
3. 使用 npm run neo4j:init 重新初始化模式

只要卷映射保持不变，数据就会在过程中持续存在。

完全重置数据库

如果您需要完全重置 Neo4j 数据库：

# 停止容器
docker-compose stop neo4j

# 移除容器
docker-compose rm -f neo4j

# 删除数据目录内容
rm -rf ./neo4j-data/*

# 重新启动容器
docker-compose up -d neo4j

# 重新初始化模式
npm run neo4j:init

备份数据

要备份您的 Neo4j 数据，只需复制数据目录：

# 备份 Neo4j 数据
cp -r ./neo4j-data ./neo4j-data-backup-$(date +%Y%m%d)

Neo4j CLI 工具

Memento MCP 包括用于管理 Neo4j 操作的命令行工具：

测试连接

测试与您的 Neo4j 数据库的连接：

# 使用默认设置测试
npm run neo4j:test

# 使用自定义设置测试
npm run neo4j:test -- --uri bolt://127.0.0.1:7687 --username myuser --password mypass --database neo4j

初始化模式

正常操作时，当 Memento MCP 连接到数据库时，Neo4j 模式初始化会自动发生。您不需要为常规使用运行任何手动命令。

以下命令仅在开发、测试或高级定制场景中需要：

# 使用默认设置初始化（仅在开发或故障排除时需要）
npm run neo4j:init

# 使用自定义向量维度初始化
npm run neo4j:init -- --dimensions 768 --similarity euclidean

# 强制重建所有约束和索引
npm run neo4j:init -- --recreate

# 组合多个选项
npm run neo4j:init -- --vector-index custom_index --dimensions 384 --recreate

高级功能

语义搜索

基于意义而非仅仅是关键词查找语义相关的实体：

• 向量嵌入：实体自动编码成高维向量空间，使用 OpenAI 的嵌入模型
• 余弦相似性：即使使用不同术语也能找到相关概念
• 可配置阈值：设置最小相似分数以控制结果的相关性
• 跨模态搜索：通过文本查询找到相关实体，无论它们是如何描述的
• 多模型支持：兼容多种嵌入模型（OpenAI text-embedding-3-small/large）
• 上下文检索：根据语义意义而不是精确关键词匹配检索信息
• 优化默认设置：调整参数以平衡精度和召回率（0.6 相似性阈值，启用混合搜索）
• 混合搜索：结合语义和关键词搜索以获得更全面的结果
• 自适应搜索：系统智能地选择仅向量、仅关键词或混合搜索，基于查询特征和可用数据
• 性能优化：优先考虑向量搜索以理解语义，同时保持回退机制以确保韧性
• 查询感知处理：根据查询复杂性和实体嵌入的可用性调整搜索策略

时间感知

跟踪实体和关系的完整历史，通过时间点图检索：

• 完整版本历史：对实体或关系的每次更改都带有时间戳
• 时间点查询：检索过去任意时刻的知识图状态
• 变更跟踪：自动记录创建时间、更新时间、有效起始时间和有效结束时间
• 时间一致性：维护知识演变的历史准确视图
• 非破坏性更新：更新创建新版本而不是覆盖现有数据
• 基于时间的过滤：根据时间标准过滤图元素
• 历史探索：调查特定信息如何随时间变化

置信度衰减

关系基于可配置半衰期随着时间自然衰减：

• 基于时间的衰减：如果未得到加强，关系的置信度自然下降
• 可配置半衰期：定义信息变得不确定的速度（默认：30天）
• 最低置信度门槛：设置阈值以防止重要信息过度衰减
• 衰减元数据：每个关系包含详细的衰减计算信息
• 非破坏性：原始置信度值与衰减值一起保留
• 强化学习：当关系被新的观察加强时，恢复置信度
• 参考时间灵活性：基于任意参考时间进行历史分析的衰减计算

高级元数据

实体和关系的丰富元数据支持，带有自定义字段：

• 来源追踪：记录信息的来源（用户输入、分析、外部来源）
• 置信度水平：根据确定性为关系分配置信度分数（0.0-1.0）
• 关系强度：表示关系的重要性或强度（0.0-1.0）
• 时间元数据：跟踪信息添加、修改或验证的时间
• 自定义标签：添加任意标签进行分类和过滤
• 结构化数据：在元数据字段内存储复杂的结构化数据
• 查询支持：基于元数据属性进行搜索和过滤
• 可扩展模式：根据需要添加自定义字段，无需修改核心数据模型

MCP API 工具

以下工具可通过模型上下文协议提供给 LLM 客户端主机：

实体管理

• create_entities

  • 在知识图谱中创建多个新实体
  • 输入：entities（对象数组）
    • 每个对象包含：
      • name（字符串）：实体标识符
      • entityType（字符串）：类型分类
      • observations（字符串数组）：关联观察

• add_observations

  • 向现有实体添加新观察
  • 输入：observations（对象数组）
    • 每个对象包含：
      • entityName（字符串）：目标实体
      • contents（字符串数组）：要添加的新观察

• delete_entities

  • 删除实体及其关系
  • 输入：entityNames（字符串数组）

• delete_observations

  • 从实体中删除特定观察
  • 输入：deletions（对象数组）
    • 每个对象包含：
      • entityName（字符串）：目标实体
      • observations（字符串数组）：要移除的观察

关系管理

• create_relations

  • 创建多个具有增强属性的实体间新关系
  • 输入：relations（对象数组）
    • 每个对象包含：
      • from（字符串）：源实体名称
      • to（字符串）：目标实体名称
      • relationType（字符串）：关系类型
      • strength（数字，可选）：关系强度（0.0-1.0）
      • confidence（数字，可选）：置信度水平（0.0-1.0）
      • metadata（对象，可选）：自定义元数据字段

• get_relation

  • 获取具有增强属性的具体关系
  • 输入：
    • from（字符串）：源实体名称
    • to（字符串）：目标实体名称
    • relationType（字符串）：关系类型

• update_relation

  • 更新具有增强属性的现有关系
  • 输入：relation（对象）：
    • 包含：
      • from（字符串）：源实体名称
      • to（字符串）：目标实体名称
      • relationType（字符串）：关系类型
      • strength（数字，可选）：关系强度（0.0-1.0）
      • confidence（数字，可选）：置信度水平（0.0-1.0）
      • metadata（对象，可选）：自定义元数据字段

• delete_relations

  • 从图中删除特定关系
  • 输入：relations（对象数组）
    • 每个对象包含：
      • from（字符串）：源实体名称
      • to（字符串）：目标实体名称
      • relationType（字符串）：关系类型

图操作

• read_graph

  • 读取整个知识图谱
  • 不需要输入

• search_nodes

  • 根据查询搜索节点
  • 输入：query（字符串）

• open_nodes

  • 通过名称检索特定节点
  • 输入：names（字符串数组）

语义搜索

• semantic_search

  • 使用向量嵌入和相似性进行语义搜索实体
  • 输入：
    • query（字符串）：要语义搜索的文本查询
    • limit（数字，可选）：返回的最大结果数（默认：10）
    • min_similarity（数字，可选）：最小相似性阈值（0.0-1.0，默认：0.6）
    • entity_types（字符串数组，可选）：按实体类型筛选结果
    • hybrid_search（布尔值，可选）：组合关键词和语义搜索（默认：true）
    • semantic_weight（数字，可选）：混合搜索中语义结果的权重（0.0-1.0，默认：0.6）
  • 功能：
    • 根据查询上下文智能选择最优搜索方法（向量、关键词或混合）
    • 通过回退机制优雅地处理没有语义匹配的查询
    • 通过自动优化决策维持高性能

• get_entity_embedding

  • 获取特定实体的向量嵌入
  • 输入：
    • entity_name（字符串）：要获取嵌入的实体名称

时间特性

• get_entity_history

  • 获取实体的完整版本历史
  • 输入：entityName（字符串）

• get_relation_history

  • 获取关系的完整版本历史
  • 输入：
    • from（字符串）：源实体名称
    • to（字符串）：目标实体名称
    • relationType（字符串）：关系类型

• get_graph_at_time

  • 获取特定时间戳的图状态
  • 输入：timestamp（数字）：Unix 时间戳（自纪元以来的毫秒数）

• get_decayed_graph

  • 获取具有时间衰减置信度值的图
  • 输入：options（对象，可选）：
    • reference_time（数字）：衰减计算的参考时间戳（自纪元以来的毫秒数）
    • decay_factor（数字）：可选的衰减因子覆盖

配置

环境变量

使用以下环境变量配置 Memento MCP：

# 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

# 嵌入服务配置
MEMORY_STORAGE_TYPE=neo4j
OPENAI_API_KEY=your-openai-api-key
OPENAI_EMBEDDING_MODEL=text-embedding-3-small

# 调试设置
DEBUG=true

命令行选项

Neo4j CLI 工具支持以下选项：

--uri <uri>              Neo4j 服务器 URI（默认：bolt://127.0.0.1:7687）
--username <username>    Neo4j 用户名（默认：neo4j）
--password <password>    Neo4j 密码（默认：memento_password）
--database <n>           Neo4j 数据库名称（默认：neo4j）
--vector-index <n>       向量索引名称（默认：entity_embeddings）
--dimensions <number>    向量维度（默认：1536）
--similarity <function>  相似性函数（cosine|euclidean）（默认：cosine）
--recreate               强制重建约束和索引
--no-debug               禁用详细输出（调试默认开启）

嵌入模型

可用的 OpenAI 嵌入模型：

• text-embedding-3-small：高效、成本效益高（1536 维度）
• text-embedding-3-large：更高准确性、更昂贵（3072 维度）
• `text-embedding-ada