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 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 Browser UI）
• 默认凭据: 用户名：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 Browser 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 版本而不会丢失数据：

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 相似度阈值，启用混合搜索）
• 混合搜索：结合语义搜索和关键字搜索以获得更全面的结果
• 自适应搜索：系统根据查询特征和可用数据智能地选择仅向量、仅关键字或混合搜索
• 性能优化：优先考虑向量搜索以进行语义理解，同时保持后备机制以确保弹性
• 查询感知处理：根据查询复杂性和可用的实体嵌入调整搜索策略

时间感知

使用时间点图检索跟踪实体和关系的完整历史记录：

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

置信度衰减

关系中的置信度会随着时间的推移根据可配置的半衰期自动衰减：

• 基于时间的衰减：如果未加强，关系中的置信度会随着时间的推移自然降低
• 可配置的半衰期：定义信息变得不太确定的速度（默认值：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 时间戳（自 epoch 以来的毫秒数）

• get_decayed_graph

  • 获取具有时间衰减置信度值的图
  • 输入：options（对象，可选）：
    • reference_time（数字）：用于衰减计算的参考时间戳（自 epoch 以来的毫秒数）
    • 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-002：旧模型（1536 维）

OpenAI API 配置

要使用语义搜索，您需要配置 OpenAI API 凭据：

1. 从 OpenAI 获取 API 密钥
2. 使用以下内容配置您的环境：

# 用于嵌入的 OpenAI API 密钥
OPENAI_API_KEY=your-openai-api-key
# 默认嵌入模型
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 实现最佳集成，请将以下语句添加到您的系统提示中：

您可以使用 Memento MCP 知识图谱记忆系统，该系统为您提供持久的记忆功能。
您的记忆工具由 Memento MCP 提供，Memento MCP 是一种复杂的知识图谱实现。
当被问及过去的对话或用户信息时，请始终首先检查 Memento MCP 知识图谱。
在回答问题时，您应该使用 semantic_search 在您的记忆中查找相关信息。

测试语义搜索

配置完成后，Claude 可以通过自然语言访问语义搜索功能：

1. 要创建具有语义嵌入的实体：

   User: "记住 Python 是一种以其可读性而闻名的高级编程语言，而 JavaScript 主要用于 Web 开发。"
   

2. 要进行语义搜索：

   User: "您知道哪些适合 Web 开发的编程语言？"
   

3. 要检索特定信息：

   User: "告诉我您所知道的关于 Python 的一切。"
   

这种方法的强大之处在于，用户可以自然地进行交互，而 LLM 可以处理选择和使用适当的记忆工具的复杂性。

实际应用

Memento 的自适应搜索功能提供了实际的好处：

1. 查询多功能性：用户无需担心如何措辞问题 - 系统会自动适应不同的查询类型

2. 故障恢复能力：即使没有语义匹配，系统也可以在没有用户干预的情况下回退到替代方法

3. 性能效率：通过智能地选择最佳搜索方法，系统可以平衡每个查询的性能和相关性

4. 改进的上下文检索：LLM 对话受益于更好的上下文检索，因为系统可以在复杂的知识图谱中找到相关信息

例如，当用户问“您对机器学习了解多少？”时，即使它们没有明确提及“机器学习”，系统也可以检索概念相关的实体 - 可能是关于神经网络、数据科学或特定算法的实体。但是，如果语义搜索产生的结果不足，系统会自动调整其方法以确保仍然返回有用的信息。

故障排除

向量搜索诊断

Memento MCP 包含内置的诊断功能，可帮助您排除向量搜索问题：

• 嵌入验证：系统检查实体是否具有有效的嵌入，如果缺少嵌入，则会自动生成嵌入
• 向量索引状态：验证向量索引是否存在并且处于 ONLINE 状态
• 后备搜索：如果向量搜索失败，系统将回退到基于文本的搜索
• 详细日志记录：用于故障排除的向量搜索操作的全面日志记录

调试工具（当 DEBUG=true 时）

启用调试模式后，可以使用其他诊断工具：

• diagnose_vector_search：有关 Neo4j 向量索引、嵌入计数和搜索功能的信息
• force_generate_embedding：强制为特定实体生成嵌入
• debug_embedding_config：有关当前嵌入服务配置的信息

开发者重置

要在开发期间完全重置 Neo4j 数据库：

# 停止容器（如果使用 Docker）
docker-compose stop neo4j

# 删除容器（如果使用 Docker）
docker-compose rm -f neo4j

# 删除数据目录（如果使用 Docker）
rm -rf ./neo4j-data/*

# 对于 Neo4j Desktop，右键单击您的数据库并选择“删除数据库”

# 重启数据库
# 对于 Docker：
docker-compose up -d neo4j

# 对于 Neo4j Desktop：
# 单击数据库的“启动”按钮

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

构建和开发

# 克隆存储库
git clone https://github.com/gannonh/memento-mcp.git
cd memento-mcp

# 安装依赖项
npm install

# 构建项目
npm run build

# 运行测试
npm test

# 检查测试覆盖率
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 兼容的客户端一起使用。

本地安装

用于开发或为项目做出贡献：

# 本地安装
npm install @gannonh/memento-mcp

# 或克隆存储库
git clone https://github.com/gannonh/memento-mcp.git
cd memento-mcp
npm install

许可证

MIT