Memento MCP：面向LLM的知识图谱记忆系统

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

核心概念

实体

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

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

示例：

{
  "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 桌面版设置（推荐）

开始使用 Neo4j 的最简单方法是使用 Neo4j 桌面版：

1. 从 https://neo4j.com/download/ 下载并安装 Neo4j 桌面版
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：

# 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（用于 Neo4j 浏览器界面）
• 默认凭据：用户名：neo4j，密码：memento_password

数据持久化与管理

Neo4j 数据在容器重启甚至版本升级后仍然保持持久性，这是由于 docker-compose.yml 文件中的 Docker 卷配置：

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 数据库：

# 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 工具

通过 Model Context Protocol 向 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 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 凭证：

1. 从 OpenAI 获取 API 密钥
2. 配置您的环境：

# 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 可以通过自然语言访问语义搜索功能：

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

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

2. 进行语义搜索：

   用户: "你知道哪些适合 Web 开发的编程语言？"
   

3. 检索特定信息：

   用户: "告诉我你所知道的关于 Python 的一切。"
   

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

实际应用

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

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

2. 容错性：即使没有可用的语义匹配，系统也可以在无需用户干预的情况下回退到替代方法

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

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

例如，当用户询问“你知道关于机器学习的什么？”时，系统可以检索概念相关的实体，即使他们没有明确提到“机器学习”——也许是关于神经网络、数据科学或特定算法的实体。但如果语义搜索结果不足，系统会自动调整其方法，以确保返回有用的信息。

故障排除

向量搜索诊断

Memento MCP 包含内置的诊断功能，以帮助解决向量搜索问题：

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

调试工具（当 DEBUG=true 时）

启用调试模式后，将提供额外的诊断工具：

• diagnose_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 自动安装 memento-mcp 用于 Claude Desktop：

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

许可证

MIT