memento-mcp

Memento MCP：为 LLM 打造永久记忆的知识图谱系统

一、痛点切入：AI 为何总是"失忆"？

你一定有过这样的经历：让 AI 助手分析一个复杂项目，聊到一半时它突然"失忆"了——之前提到的关键人物、技术栈、项目背景，全都不记得了。每次对话都是一次"零基础起步"。这对于需要跨会话积累知识的 AI 应用来说，简直是致命的短板。

Memento MCP 正是为解决这一痛点而生。它为任何支持 Model Context Protocol（MCP）的 AI 客户端（如 Claude Desktop、Cursor、GitHub Copilot）提供了一套持久化、可追溯的知识图谱记忆系统。让 AI 不仅能在单次对话中保持上下文，还能跨会话、跨任务地记住关键实体、关系和观察结果。

图1：Memento MCP 项目 Logo

二、项目背景与作者

Memento MCP 由独立开发者 Gannon Hall（GitHub @gannonh）于 2025 年 3 月创建，采用 MIT 许可证开源。项目定位为"MCP 协议的知识图谱记忆后端"，解决了 LLM 长期记忆这一行业级难题。

在 MCP 生态中，Memento 的出现填补了一个关键空白：此前 MCP 协议定义了一套工具调用标准，但没有官方的记忆存储方案。开发者要么自行实现简单的键值存储，要么干脆放弃持久化。Memento MCP 以 Neo4j 图数据库 + OpenAI 向量嵌入的组合，提供了一套生产级的知识图谱记忆解决方案，并在 GitHub 上迅速积累到 422 颗星，获得了 Smithery AI 平台的官方推荐。

三、核心原理：知识图谱如何让 AI "记住一切"

Memento MCP 的底层设计围绕两大核心概念：实体（Entity） 和 关系（Relation）。

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

• 唯一标识符（name）：如 John_Smith
• 实体类型（entityType）：如 person、organization、event
• 观察记录（observations）：AI 观察到的该实体相关信息列表
• 向量嵌入（embedding）：用于语义搜索的高维向量表示
• 完整版本历史：每次修改都有时间戳记录

关系是有向连接边，定义两个实体之间的关联：

• 关系类型（如 works_at、created_by）
• 强度系数（strength，0.0-1.0）：衡量这条关系的可靠程度
• 置信度（confidence，0.0-1.0）：关系本身的可信程度
• 元数据：来源、时间戳、标签等附加信息
• 时间感知：支持基于时间的置信度衰减

这种设计比简单的键值存储强大得多。当你说"帮我记住 John 在 Anthropic 工作"，Memento 会创建一个 John_Smith 实体（类型 person）和一个 Anthropic 实体（类型 organization），再用一条 works_at 关系将它们连接起来——未来 AI 可以顺着关系图谱进行复杂推理，而不仅仅是关键词匹配。

四、技术架构：TypeScript + Neo4j + OpenAI

从代码结构来看，Memento MCP 是一个典型的 TypeScript 工程：

src/
├── KnowledgeGraphManager.ts   # 核心管理器，所有知识图谱操作入口
├── index.ts                  # CLI 入口，初始化存储和嵌入服务
├── server/
│   ├── setup.ts              # MCP Server 初始化
│   └── handlers/             # 工具调用处理器（create_entities, search_nodes等）
├── embeddings/               # 向量嵌入层
│   ├── EmbeddingService.ts   # 嵌入服务接口
│   ├── OpenAIEmbeddingService.ts  # OpenAI text-embedding-3-small 实现
│   ├── EmbeddingJobManager.ts     # 嵌入任务队列（带速率限制）
│   └── EmbeddingServiceFactory.ts # 工厂模式创建嵌入服务
├── storage/
│   ├── neo4j/               # Neo4j 存储驱动
│   └── VectorStoreFactory.ts # 向量存储工厂
├── types/                   # 类型定义（Entity, Relation, VectorStore等）
└── utils/                   # 工具函数（FS操作、日志）

核心技术栈：

• 运行时：Node.js >= 18，TypeScript 5.8.2（strict 模式编译）
• MCP SDK：@modelcontextprotocol/sdk 1.11.0，标准化的 MCP Server 实现
• 图数据库：Neo4j 5.13+（使用 Cypher 查询语言，原生支持图遍历）
• 向量嵌入：OpenAI text-embedding-3-small（1536 维，cosine 相似度）
• 连接池：neo4j-driver 5.28.1，Bolt 协议连接
• 依赖管理：npm，pnpm workspace 友好

Memento MCP 暴露的核心工具（LLM 可调用的 MCP 工具）：

工具名称	功能描述
create_entities	创建新实体及其向量嵌入
read_graph	读取图谱片段
create_relations	创建实体间关系
add_observations	为实体添加观察记录
delete_entities	删除实体
delete_observations	删除观察记录
delete_relations	删除关系
search_nodes	语义搜索实体
open_nodes	读取指定实体的完整信息
get_entity_history	获取实体版本历史
get_relation_history	获取关系版本历史
get_relation	查询特定关系详情

这套工具集覆盖了知识图谱的全生命周期操作——CRUD + 历史追踪 + 语义搜索，功能相当完整。

五、部署体验：Docker 一键启动

Memento MCP 的部署体验在开源 MCP 项目中属于中上水平：

优点：

• 提供完整的 docker-compose.yml，Neo4j 数据库一键启动，数据持久化到本地卷
• Dockerfile 生成的镜像可直接用于 MCP 客户端（如 Claude Desktop）
• Smithery AI 平台支持：一行命令安装，无需手动配置
• .env.example 清晰标注了必需的环境变量

局限：

• 无 Web UI：Neo4j 有自己的 Browser UI（:7474），但 Memento 本身没有独立的图形界面
• 需要自行准备 OpenAI API Key（费用按 token 计费）
• Neo4j 企业版需要许可证，但社区版足够个人使用
• 数据迁移（升级版本）需要手动执行 npm run neo4j:init

部署流程（简化版）：

git clone https://github.com/gannonh/memento-mcp.git
cd memento-mcp
cp example.env .env  # 填入 OPENAI_API_KEY
docker-compose up -d neo4j  # 启动 Neo4j
npm install && npm run build
npm run neo4j:init  # 初始化 Neo4j schema

接入 Claude Desktop 只需在 claude_desktop_config.json 中添加 server 配置即可。

六、适用场景与局限

最适用的场景：

• 多轮对话 Agent：需要在多次会话中保持用户信息、项目上下文
• 知识管理助手：帮助 AI 记住研究对象、人物关系、事件脉络
• 复杂推理场景：需要 AI 进行关系推理而非简单检索
• Cursor/Copilot 增强：为 IDE 中的 AI 助手提供长期记忆能力

局限性：

• 依赖 OpenAI API（成本 + 隐私），不支持本地 embedding 模型
• Neo4j 学习曲线较陡，非图数据库用户需要学习 Cypher 查询语言
• 仅支持 MCP 协议客户端，OpenAI API ChatGPT 插件暂不支持
• 无中文文档，对国内用户有一定门槛

七、行业意义与趋势

Memento MCP 的出现反映了 AI 应用架构的一个重要趋势：记忆层（Memory Layer）的独立化。此前，AI 的上下文全靠 prompt 拼接，记忆能力受限于 context window 大小。Memento 代表的知识图谱记忆方案，通过将"记忆"外部化到专业数据库，让 AI 可以突破 context 限制，拥有近乎无限的长期记忆。

从 GitHub 422 星的增长势头来看，社区对这类工具的需求非常旺盛。随着 MCP 协议的普及（Anthropic 主推），预计会出现更多类似的知识记忆中间件，而 Memento MCP 凭借其干净的架构设计和 Neo4j 的成熟生态，已经在这个细分领域占据了先发优势。

---

分析时间：2026-06-25 | 数据来源：GitHub API + 源码分析 | 部署难度：中等（需要 Docker + Neo4j + OpenAI Key）