mcpField
M
Memento

Memento

本地服务
github.com/gannonh记忆与知识42477 周前更新
代码仓库

关于 Memento

Memento 是基于知识图谱的持久记忆 MCP 服务，面向需要长期保存和检索信息的 LLM 客户端。它结合 Neo4j 图存储与向量搜索，并支持语义检索、时间版本和关系置信度衰减。

主要功能

  1. 01管理实体、观察和实体关系
  2. 02结合语义与关键词检索
  3. 03保留图数据的完整版本历史
  4. 04支持按历史时点查询图数据
  5. 05按时间调整关系置信度

适用场景

  1. 01为 LLM 客户端保存长期上下文
  2. 02按含义检索相关实体与信息
  3. 03查询知识图谱在过去某时点的状态
  4. 04追踪关系及其置信度随时间的变化

MCP 相关

通过 MCP 向兼容客户端提供实体和关系管理、图查询及语义搜索工具。数据存储和向量搜索由 Neo4j 支持。

#knowledge-graph#memory-system#semantic-search

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置
{
  "mcpServers": {
    "memento": {
      "command": "npx",
      "args": [
        "-y",
        "@gannonh/memento-mcp"
      ],
      "env": {
        "MEMORY_STORAGE_TYPE": "<MEMORY_STORAGE_TYPE>",
        "NEO4J_URI": "<NEO4J_URI>",
        "NEO4J_USERNAME": "<NEO4J_USERNAME>",
        "NEO4J_PASSWORD": "<NEO4J_PASSWORD>",
        "NEO4J_DATABASE": "<NEO4J_DATABASE>",
        "NEO4J_VECTOR_INDEX": "<NEO4J_VECTOR_INDEX>",
        "NEO4J_VECTOR_DIMENSIONS": "<NEO4J_VECTOR_DIMENSIONS>",
        "NEO4J_SIMILARITY_FUNCTION": "<NEO4J_SIMILARITY_FUNCTION>",
        "OPENAI_API_KEY": "<OPENAI_API_KEY>",
        "OPENAI_EMBEDDING_MODEL": "<OPENAI_EMBEDDING_MODEL>"
      }
    }
  }
}
启动命令npx -y @gannonh/memento-mcp
需要配置的环境变量
MEMORY_STORAGE_TYPE
NEO4J_URI
NEO4J_USERNAME
NEO4J_PASSWORD密钥
NEO4J_DATABASE
NEO4J_VECTOR_INDEX
NEO4J_VECTOR_DIMENSIONS
NEO4J_SIMILARITY_FUNCTION
OPENAI_API_KEY密钥
OPENAI_EMBEDDING_MODEL

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包
npm@gannonh/memento-mcp

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

Memento MCP：面向大模型的知识图谱记忆系统

Memento MCP 徽标

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

Memento MCP 测试 smithery 徽章

核心概念

实体

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

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

示例：

{
  "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：

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

# 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 客户端宿主可通过 Model Context Protocol 使用以下工具：

实体管理

  • 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（string）：要进行语义搜索的文本查询
      • limit（number，可选）：返回结果的最大数量（默认值：10）
      • min_similarity（number，可选）：最低相似度阈值（0.0-1.0，默认值：0.6）
      • entity_types（string[]，可选）：按实体类型筛选结果
      • hybrid_search（boolean，可选）：结合关键词搜索和语义搜索（默认值：true）
      • semantic_weight（number，可选）：混合搜索中语义结果的权重（0.0-1.0，默认值：0.6）
    • 特性：
      • 根据查询上下文智能选择最佳搜索方法（向量、关键词或混合搜索）
      • 通过回退机制妥善处理没有语义匹配项的查询
      • 通过自动优化决策保持高性能

  • get_entity_embedding

    • 获取特定实体的向量嵌入
    • 输入：
      • entity_name（string）：要获取嵌入的实体名称
时序特性

  • get_entity_history

    • 获取实体的完整版本历史记录
    • 输入：entityName（string）

  • get_relation_history

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

  • get_graph_at_time

    • 获取指定时间戳时的图状态
    • 输入：timestamp（number）：Unix 时间戳（自纪元起的毫秒数）

  • get_decayed_graph

    • 获取置信度值随时间衰减的图
    • 输入：options（object，可选）：
      • reference_time（number）：用于计算衰减的参考时间戳（自纪元起的毫秒数）
      • decay_factor（number）：可选的衰减因子覆盖值

配置

环境变量

使用以下环境变量配置 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. 创建带有语义嵌入的实体：

    User: "Remember that Python is a high-level programming language known for its readability and JavaScript is primarily used for web development."

  2. 进行语义搜索：

    User: "What programming languages do you know about that are good for web development?"

  3. 检索特定信息：

    User: "Tell me everything you know about Python."

这种方法的优势在于，用户可以自然地进行交互，同时由大模型负责选择并使用合适的记忆工具。

实际应用

Memento 的自适应搜索功能具有以下实际优势：

  1. 查询灵活性：用户无需担心如何措辞提问——系统会自动适应不同类型的查询

  2. 故障韧性：即使没有可用的语义匹配，系统也能在无需用户干预的情况下切换到其他方法

  3. 性能效率：系统会智能选择最佳搜索方法，针对每个查询平衡性能与相关性

  4. 改进上下文检索：系统能够在复杂知识图谱中查找相关信息，从而帮助大模型对话更好地检索上下文

例如，当用户询问“你了解机器学习的哪些信息？”时，即使某些实体没有明确提及“机器学习”，系统也能检索到概念上相关的实体，例如关于神经网络、数据科学或特定算法的实体。但如果语义搜索返回的结果不足，系统会自动调整搜索方式，确保仍能返回有用信息。

故障排查

向量搜索诊断

Memento MCP 内置了诊断功能，可帮助排查向量搜索问题：

  • 嵌入验证：系统会检查实体是否具有有效的嵌入，并在缺少嵌入时自动生成
  • 向量索引状态：验证向量索引是否存在，以及状态是否为 ONLINE
  • 备用搜索：如果向量搜索失败，系统会切换到基于文本的搜索
  • 详细日志记录：全面记录向量搜索操作，便于排查问题
调试工具（当 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 自动为 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

许可证

MIT

评论

支持 Markdown

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。