⚙

知识图谱记忆系统

Memento MCP是一个高性能的知识图谱记忆系统，为支持模型上下文协议的LLM客户端提供语义检索、上下文回忆和时间感知功能，适用于需要长期记忆和复杂知识管理的场景。

作者 By gannonh

本地部署知识图谱语义检索

GitHub

Memento MCP:LLM的知识图存储系统

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

核心概念

实体

实体是知识图中的主要节点。每个实体都有：

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

例子：

JSON``` 1 2 3 4 5{ “name”: “John_Smith”, “entityType”: “person”, “observations”: [“Speaks fluent Spanish”] }


### 关系


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


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


例子：


JSON```
1
2
3
4
5
6
7
8
9
10
11{
  "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桌面:

从下载并安装Neo4j Desktop https://neo4j.com/download/
创建新项目
添加新数据库
将密码设置为 memento_password （或您的首选密码）
启动数据库

Neo4j数据库将在以下网址提供：

螺栓URI: bolt://127.0.0.1:7687 （用于驾驶员连接）
超文本传输协议: http://127.0.0.1:7474 （适用于Neo4j浏览器用户界面）
默认凭据：用户名： neo4j，密码： memento_password （或您配置的任何内容）

使用Docker安装Neo4j（替代方案）

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

BASH``` 1 2 3 4 5 6# 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数据库将在以下位置可用：


- **螺栓URI**: `bolt://127.0.0.1:7687` （用于驾驶员连接）
- **超文本传输协议**: `http://127.0.0.1:7474` （适用于Neo4j浏览器用户界面）
- **默认凭据**：用户名： `neo4j`，密码： `memento_password`


#### 数据持久性和管理


由于容器中的Docker卷配置，Neo4j数据在容器重启甚至版本升级时都会持续存在 `docker-compose.yml` 文件：


YAML```
1
2
3
4volumes:
  - ./neo4j-data:/data
  - ./neo4j-logs:/logs
  - ./neo4j-import:/import

这些映射确保：

/data 目录（包含所有数据库文件）保留在您的主机上 ./neo4j-data
/logs 目录保留在您的主机上 ./neo4j-logs
/import 目录（用于导入数据文件）保留在 ./neo4j-import

您可以在您的 docker-compose.yml 如果需要，可以将数据存储在不同的位置。

升级Neo4j版本

您可以在不丢失数据的情况下更改Neo4j的版本和版本：

在中更新Neo4j映像版本 docker-compose.yml
使用以下命令重新启动容器 docker-compose down && docker-compose up -d neo4j
使用重新初始化架构 npm run neo4j:init

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

完成数据库重置

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

BASH``` 1 2 3 4 5 6 7 8 9 10# 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数据，只需复制data目录即可：


BASH```
1
2# Make a backup of the Neo4j data
cp -r ./neo4j-data ./neo4j-data-backup-$(date +%Y%m%d)

Neo4j CLI实用程序

Memento MCP包括用于管理Neo4j操作的命令行实用程序：

测试连接

测试与Neo4j数据库的连接：

BASH``` 1 2 3 4# 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模式初始化会自动发生。您不需要为常规使用运行任何手动命令。


以下命令仅在开发、测试或高级自定义场景中是必需的：


BASH```
1
2
3
4
5
6
7
8# 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客户端主机可以通过模型上下文协议使用以下工具：

实体管理

create_entities
在知识图中创建多个新实体
输入： entities （对象数组）
每个对象包含：
name （string）：实体标识符
entityType （string）：类型分类
observations （string[]）：相关观测值
添加观察结果
向现有实体添加新的观察结果
输入： observations （对象数组）
每个对象包含：
entityName （string）：目标实体
contents （string[]）：要添加的新观测值
删除内容
删除实体及其关系
输入： entityNames （字符串[]）
删除观察
从实体中删除特定观察结果
输入： deletions （对象数组）
每个对象包含：
entityName （string）：目标实体
observations （string[]）：要删除的观察值

关系管理

创建关系
在具有增强属性的实体之间创建多个新关系
输入： relations （对象数组）
每个对象包含：
from （string）：源实体名称
to （string）：目标实体名称
relationType （string）：关系类型
strength （数字，可选）：关系强度（0.0-1.0）
confidence （数字，可选）：置信水平（0.0-1.0）
metadata （对象，可选）：自定义元数据字段
获取相关信息
获取与其增强属性的特定关系
输入：
from （string）：源实体名称
to （string）：目标实体名称
relationType （string）：关系类型
update_relation
使用增强的属性更新现有关系
输入： relation （对象）：
包含：
from （string）：源实体名称
to （string）：目标实体名称
relationType （string）：关系类型
strength （数字，可选）：关系强度（0.0-1.0）
confidence （数字，可选）：置信水平（0.0-1.0）
metadata （对象，可选）：自定义元数据字段
删除关系
从图中删除特定关系
输入： relations （对象数组）
每个对象包含：
from （string）：源实体名称
to （string）：目标实体名称
relationType （string）：关系类型

图的运算

read_graph
阅读整个知识图谱
无需输入
搜索节点
基于查询搜索节点
输入： query （字符串）
open_nodes
按名称检索特定节点
输入： names （字符串[]）

语义搜索

语义研究
使用向量嵌入和相似性在语义上搜索实体
输入：
query （string）：用于语义搜索的文本查询
limit （数字，可选）：返回的最大结果数（默认值：10）
min_similarity （数字，可选）：最小相似性阈值（0.0-1.0，默认值：0.6）
entity_types （string[]，可选）：按实体类型筛选结果
hybrid_search （布尔值，可选）：结合关键字和语义搜索（默认值：true）
semantic_weight （数字，可选）：混合搜索中语义结果的权重（0.0-1.0，默认值：0.6）
特征：
根据查询上下文智能选择最佳搜索方法（向量、关键字或混合）
通过回退机制优雅地处理没有语义匹配的查询
通过自动优化决策保持高性能
get_entity_embedded
获取特定实体的向量嵌入
输入：
entity_name （string）：要获取嵌入的实体的名称

时间特征

get_entity_history
获取实体的完整版本历史记录
输入： entityName （字符串）
get_relation_history
获取关系的完整版本历史记录
输入：
from （string）：源实体名称
to （string）：目标实体名称
relationType （string）：关系类型
get_graph_at_time
获取特定时间戳处的图形状态
输入： timestamp （number）：Unix时间戳（自纪元以来的毫秒数）
get_decayed_graph
获取具有时间衰减置信度值的图
输入： options （对象，可选）：
reference_time （number）：衰变计算的参考时间戳（自纪元以来的毫秒数）
decay_factor （数字）：可选衰减因子覆盖

配置

环境变量

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

BASH``` 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15# 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工具支持以下选项：

1 2 3 4 5 6 7 8 9—uri Neo4j server URI (default: bolt://127.0.0.1:7687) —username Neo4j username (default: neo4j) —password Neo4j password (default: memento_password) —database Neo4j database name (default: neo4j) —vector-index Vector index name (default: entity_embeddings) —dimensions Vector dimensions (default: 1536) —similarity 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. 从获取API密钥 [OpenAI](https://platform.openai.com/api-keys)
2. 使用以下配置您的环境：


BASH```
1
2
3
4# 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:

JSON``` 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21{ “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” } } } }


或者，对于本地开发，您可以使用：


JSON```
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21{
  "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可以通过自然语言访问语义搜索功能：

要创建具有语义嵌入的实体，请执行以下操作：

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

要进行语义搜索，请执行以下操作：

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

要检索特定信息，请执行以下操作：

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

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

实际应用

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

查询多功能性：用户不必担心如何表达问题——系统会自动适应不同的查询类型
故障恢复能力：即使语义匹配不可用，系统也可以在没有用户干预的情况下回退到其他方法
性能效率：通过智能选择最佳搜索方法，系统可以平衡每个查询的性能和相关性
改进的上下文检索：LLM对话受益于更好的上下文检索，因为系统可以在复杂的知识图中找到相关信息

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

故障排除

矢量搜索诊断

Memento MCP包括内置的诊断功能，可帮助解决矢量搜索问题：

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

调试工具（当Debug=true时）

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

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

开发者重置

要在开发过程中完全重置Neo4j数据库：

BASH``` 1 2 3 4 5 6 7 8 9 10 11 12 13 14# 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


## 建设与发展


BASH```
1
2
3
4
5
6
7
8
9
10
11# 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安装

通过以下方式自动安装Claude Desktop的memento mcp 史密瑟里:

BASH``` 1npx -y @smithery/cli install @gannonh/memento-mcp —client claude


### 使用npx进行全局安装


您可以直接使用npx运行Memento MCP，而无需全局安装：


BASH```
1npx -y @gannonh/memento-mcp

建议将此方法用于Claude Desktop和其他MCP兼容客户端。

本地安装

为了开发或为项目做出贡献：

BASH``` 1 2 3 4 5 6# 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


## 许可证


麻省理工学院

Memento MCP:LLM的知识图存储系统

核心概念

实体

存储后端

为什么选择Neo4j？

先决条件

Neo4j桌面设置（推荐）

使用Docker安装Neo4j（替代方案）

Stop Neo4j container

Remove Neo4j container (preserves data)

升级Neo4j版本

完成数据库重置

Remove the container

Delete the data directory contents

Restart the container

Reinitialize the schema

Neo4j CLI实用程序

测试连接

Test with custom settings

高级功能

语义搜索

时间意识

信心衰退

高级元数据

MCP API工具

实体管理

关系管理

图的运算

语义搜索

时间特征

配置

环境变量

Vector Search Configuration

Embedding Service Configuration

Debug Settings

与Claude Desktop集成

配置

推荐系统提示

测试语义搜索

实际应用

故障排除

矢量搜索诊断

调试工具（当Debug=true时）

开发者重置

Remove the container (if using Docker)

Delete the data directory (if using Docker)

For Neo4j Desktop, right-click your database and select “Drop database”

Restart the database

For Docker:

For Neo4j Desktop:

Click the “Start” button for your database

Reinitialize the schema

安装

通过Smithery安装

本地安装

Or clone the repository