mcp-memento

MCP Memento

为 MCP 客户端提供智能记忆管理，具备置信度跟踪、关系映射和知识质量维护功能。

Memento 是一个 MCP 服务，可在多个平台上提供持久记忆能力：

• IDE：Zed、Cursor、Windsurf、VSCode、Claude Desktop
• CLI Agent：Gemini CLI、Claude CLI、自定义 Agent
• 程序化使用：MCP 客户端（Python）、Docker 部署、CLI 导出/导入
• 应用程序：任何兼容 MCP 的应用程序

构建个人或团队知识库，让它随着时间推移变得越来越智能，并可通过所有开发工具访问。

目录

• 🌱 简明入门
• ✨ 主要功能
• 🚀 快速开始
• ⚙️ 配置
• 📖 核心概念
• 🔗 集成
• 🛠️ 基本用法示例
• 📚 文档结构
• 🏗️ 架构概览
• 📜 背景
• 🙏 致谢
• 🤝 贡献
• 📄 许可证
• 🔗 链接

🌱 简明入门

什么是 Memento？ 想象一下，你正在解决一个复杂的 Bug、摸索棘手的配置，或建立新的编码模式。通常，几周后你就会忘记细节。Memento 是 AI 助手的“长期记忆盘”。它能让 AI 保存这些解决方案、决策和事实，以便即使几个月后，也能在不同项目中即时回想起来。

💡 Agent 思维方式：传统开发者指南 如果你习惯了确定性软件（事情会按照脚本的指示自动发生），那么与 AI Agent 交互需要稍微转换一下思维方式。

Memento 不是一个自主 Agent，不会监视你的屏幕并神奇地决定要记住什么。相反，Memento 是提供给 AI 助手（如 Claude、Cursor 或 Gemini）的工具带。

• **AI 是执行者：**需要告诉它何时使用工具带。没有明确指示或预先定义的规则，就不会保存任何内容。
• **你是管理者：**由你决定保存哪些内容。你可以在聊天时告诉 AI（“保存这个数据库连接字符串”），也可以通过系统提示词或 .cursorrules/CLAUDE.md 文件为 AI 提供标准操作流程，让它知道自动保存某些内容，例如 Bug 修复或架构决策。

如何养成习惯：

1. **会话开始时：**询问 AI：“关于身份验证系统，我们知道些什么？”，以获取上下文。
2. **工作期间：**解决棘手问题后，说：“我们解决了 Redis 超时问题。请保存这个解决方案。”
3. **会话结束时：**告诉 AI：“保存一份今天工作成果的摘要。”

此外，你也可以为 AI 添加自定义指令（请参阅Agent 配置指南），让它自动执行这些步骤，而无需你每次都提出要求。

✨ 主要功能

🧠 智能置信度系统

• 自动衰减：未使用的知识会随时间降低置信度（每月 5%）
• 关键内容保护：安全、身份验证和 API 密钥相关记忆永不衰减
• 验证后提升：知识成功使用后，置信度会提高
• 智能排序：搜索结果按 confidence × importance 排序

🔗 关系映射

• 35 种关系类型：SOLVES、CAUSES、IMPROVES、USED_IN 等，涵盖 7 个语义类别（参见关系类型参考）
• 图谱导航：查找概念之间的联系
• 模式检测：识别反复出现的解决方案模式

📊 三种配置方案

配置方案	工具	适用对象
Core	13 个工具	所有用户 - 基本操作
Extended	17 个工具	高级用户 - 统计、上下文搜索、衰减控制
Advanced	25 个工具	管理员 - 图谱分析

🗃️ 跨平台存储

• SQLite 后端：零依赖，本地存储
• 全文搜索：在所有记忆中快速进行模糊匹配
• 自动维护：置信度衰减、关系完整性
• 共享数据库：同一数据库可用于所有集成

🚀 快速开始

1. 安装

# Install with pipx (recommended for MCP servers)
pipx install mcp-memento

# Or with pip
pip install mcp-memento

2. 基本配置

Memento 支持多种配置方式。为清晰起见，我们建议始终使用同一种方式：

方式 1：CLI 参数（推荐 - 最明确）

{
  "mcpServers": {
    "memento": {
      "command": "memento",
      "args": ["--profile", "extended", "--db", "~/.mcp-memento/context.db"]
    }
  }
}

方式 2：环境变量

{
  "mcpServers": {
    "memento": {
      "command": "memento",
      "args": [],
      "env": {
        "MEMENTO_PROFILE": "extended",
        "MEMENTO_DB_PATH": "~/.mcp-memento/context.db"
      }
    }
  }
}

方式 3：YAML 配置文件 创建 ~/.mcp-memento/config.yaml：

profile: extended
db_path: ~/.mcp-memento/context.db

然后使用精简的 JSON 配置：

{
  "mcpServers": {
    "memento": {
      "command": "memento",
      "args": []
    }
  }
}

CLI Agent（Gemini CLI）：

gemini --mcp-servers memento

注意：具体的标志语法取决于你的 Gemini CLI 版本。请参阅 AGENT_CONFIGURATION.md，了解针对特定版本的设置说明。

3. 第一步

配置完成后，你的 AI 助手现在可以：

# Store solutions and knowledge
store_memento(
    type="solution",
    title="Fixed Redis timeout with connection pooling",
    content="Increased connection timeout to 30s and added connection pooling...",
    tags=["redis", "timeout", "production_fix"],
    importance=0.8
)

# Find knowledge later
recall_mementos(query="Redis timeout solutions")

📌 注意：上面的代码表示 MCP 工具调用——你向 AI 助手（Claude、Cursor、Gemini 等）提供的指令，用于调用 Memento 的工具。 这不是可供 import 的 Python 库。有关以编程方式使用 Python 的方法，请参阅 Python 集成指南。

💬 自然语言：你也可以通过自然对话与 Memento 交互。只需告诉 AI 助手“记住……”或“存储……”或“Memento……”即可——无需编写代码。

📖 核心概念

如需深入了解 Memento 的概念（置信度系统、标签、关系），请阅读详尽的 RULES.md 和 RELATIONSHIPS.md 文档。

🔗 集成

Memento 可与所有主流开发工具配合使用：

平台	配置指南	备注
Zed Editor	IDE 集成	原生支持 MCP
Cursor	IDE 集成	AI 驱动的编辑器
Windsurf	IDE 集成	现代代码编辑器
VSCode	IDE 集成	通过 MCP 扩展
Claude Desktop	IDE 集成	桌面应用
Gemini CLI	Agent 集成	Google 的 CLI Agent
Claude CLI	Agent 集成	Anthropic 的 CLI Agent
Python / MCP Client	Python 集成	嵌入服务或通过 MCP 客户端调用
Docker / CLI	API 与编程接口	MCP 客户端、Docker、导出/导入

另请参阅：集成概览，了解如何选择合适的集成方式。

🛠️ 基本使用示例

以下示例展示了 AI 助手（Zed、Cursor、Claude、Gemini CLI 等）在你要求其记住或检索信息时，代你执行的 MCP 工具调用。它们采用类似 Python 的伪代码编写，与 MCP 工具接口相对应——它们不是可直接导入的 Python 库。

如需通过 Python 以编程方式调用这些工具，请使用 mcp 客户端库。 请参阅 Python 集成，了解可运行的示例。

存储和检索知识

# Store a solution — the AI calls this tool when you say "remember this fix"
solution_id = store_memento(
    type="solution",
    title="Fixed memory leak in WebSocket handler",
    content="Added proper cleanup in on_close()...",
    tags=["websocket", "memory", "python"],
    importance=0.9
)

# Natural language search — called when you ask "what do you know about X"
results = recall_mementos(query="WebSocket memory leak", limit=5)

# Tag-based search — for precise filtering
redis_solutions = search_mementos(tags=["redis"], memory_types=["solution"])

管理置信度

# Find potentially obsolete knowledge
low_confidence = get_low_confidence_mementos(threshold=0.3)

# Boost confidence after verification
boost_memento_confidence(
    memory_id=verified_solution_id,
    boost_amount=0.15,
    reason="Verified in production deployment"
)

创建关系

# Link solution to problem
create_memento_relationship(
    from_memory_id=solution_id,
    to_memory_id=problem_id,
    relationship_type="SOLVES",  # See all 35 types in docs/RELATIONSHIPS.md
    strength=0.9,
    context="Connection pooling resolved the timeout issue"
)

# Explore connected knowledge
related = get_related_mementos(
    memory_id=solution_id,
    relationship_types=["RELATED_TO", "USED_IN"],
    max_depth=2
)

自然语言交互（基于聊天）

Memento 通过自然语言对话运行。AI 助手会解读意图，并自动调用适当的工具。

存储信息：

User: Remember that we solved Redis timeout with connection pooling
AI: ✅ Memento stored - "Redis timeout solution: connection pooling"

检索知识：

User: What do you remember about Redis timeout?
AI: Found 2 solutions: 1) Connection pooling... 2) Query optimization...

使用 “Memento” 关键词：

User: Memento the deployment script is in /scripts/deploy.sh
AI: ✅ Memento stored - "Deployment script location: /scripts/deploy.sh"

根据 AGENT_CONFIGURATION.md 中的指南完成配置后，AI 也可以自动存储重要信息。

⚙️ 配置

Memento 支持多种配置来源（按优先级从高到低排列）：

1. 命令行参数（最高优先级）

   memento --profile advanced --db ~/custom/path/memento.db --log-level DEBUG
   

2. 环境变量

   export MEMENTO_PROFILE="advanced"
   export MEMENTO_DB_PATH="~/custom/path/memento.db"
   export MEMENTO_LOG_LEVEL="DEBUG"
   export MEMENTO_ALLOW_CYCLES="false"   # Allow cycles in relationship graph
   

3. YAML 配置文件

   • 项目配置：当前目录中的 ./memento.yaml（优先于全局配置）
   • 全局配置：~/.mcp-memento/config.yaml

优先级顺序：CLI 参数 > 环境变量 > 项目 YAML > 全局 YAML > 默认值

4. 默认值（最低优先级）

支持的 YAML 键

配置加载器会读取并应用以下键。YAML 文件中的其他键均会被静默忽略。

键	类型	默认值	说明
db_path	string	~/.mcp-memento/context.db	SQLite 数据库文件路径
profile	string	core	工具配置（core、extended、advanced）
logging.level	string	INFO	日志级别（DEBUG、INFO、WARNING、ERROR）
features.allow_relationship_cycles	bool	false	允许图中存在循环关系

注意：项目附带的 memento.yaml 模板包含其他注释部分（confidence、search、performance、memory、fts、project）。 这些功能尚未实现——它们是为未来版本预留的设想占位项，不会影响当前服务的行为。

配置文件示例

项目配置（./memento.yaml）：

db_path: ~/.mcp-memento/context.db
profile: extended
logging:
  level: INFO
features:
  allow_relationship_cycles: false

全局配置（~/.mcp-memento/config.yaml）：

db_path: ~/.mcp-memento/global.db
profile: extended
logging:
  level: INFO

📚 文档结构

必备指南

• 工具参考 - 所有 MCP 工具的完整指南
• 置信度系统 - 置信度跟踪的工作方式
• 关系类型 - 全部 35 种关系类型及示例
• 使用规则 - 最佳实践和约定
• Agent 配置 - AI Agent 模板

集成指南

• 集成概览 - 选择合适的集成方式
• IDE 集成 - Zed、Cursor、Windsurf、VSCode、Claude Desktop
• Python 集成 - MCP 客户端用法、嵌入服务、CLI 导出/导入
• Agent 集成 - CLI Agent 和自定义应用程序
• API 与编程式集成 - MCP 客户端（Python）、Docker 部署、CLI 导出/导入

开发与高级主题

• 数据库架构 - 数据库技术结构
• 贡献指南 - 开发环境设置和工作流

🏗️ 架构概览

数据库架构

Memento 使用统一的 SQLite 架构，所有集成都可以访问：

• 核心表：nodes（记忆存储）、relationships（有向图）
• 全文搜索：nodes_fts — 用于快速搜索的 FTS5 虚拟表（如果 FTS5 不可用，则回退到基于 LIKE 的搜索）
• 置信度跟踪：自动衰减，并为关键记忆提供保护

行为一致性

该系统在所有平台上的行为完全一致：

1. 同一数据库：所有工具都访问同一个 SQLite 文件
2. 相同的置信度跟踪：一个工具所做的更新会反映在所有地方
3. 相同的搜索排序：结果按 confidence × importance 排序
4. 相同的关系类型：所有平台都提供 35 种语义关系类型

📜 背景

Memento 是 MemoryGraph 的简化轻量分支，由 Gregory Dickson 开发，针对 MCP 集成进行了优化，可用于 IDE 和命令行 Agent。

该分支专注于可移植性和令牌效率：它移除了繁重的依赖项（NetworkX、多后端存储、双时态跟踪、多租户架构），转而采用仅使用 SQLite 的后端，并结合基于置信度的衰减和由指南驱动的存储方式。

团队协作与远程部署

多个用户可以通过标记约定（team:[name]、author:[name]）共享一个 SQLite 数据库（例如，存储在网络存储上）。Memento 也可以作为远程 MCP 服务运行，但所有客户端共享同一个数据库，且没有租户隔离。详情请参阅团队协作指南。

如需真正的多租户支持，请使用原始的 MemoryGraph 项目。

何时选择 MemoryGraph，何时选择 Memento？

• 使用 Memento：在 IDE 和命令行工具中进行轻量、跨平台的记忆管理
• 使用 MemoryGraph：适用于需要多租户、双时态跟踪或自定义后端的企业用例

🙏 致谢

Memento 基于 Gregory Dickson 的 MemoryGraph 项目这一坚实基础构建。我们感谢他在记忆管理系统方面的开创性工作。

该分支保持与 MemoryGraph 核心概念的兼容，同时针对 MCP 集成和现代开发工具的特定需求进行了调整。对于需要充分利用 MemoryGraph 高级功能的用户，我们建议了解原始项目。

🧪 Beta 状态

mcp-webgate 目前处于 beta 阶段。核心功能稳定，且该服务已用于生产环境， 但配置 API 在 1.0 版本发布前仍可能发生变化。

非常欢迎反馈。 如果某些功能未按预期工作、表现异常， 或你有尚未涵盖的使用场景：

→ 在 GitHub 上提交问题

错误报告、配置问题和功能请求都有助于规划后续路线图。

🤝 贡献

欢迎贡献！请参阅 CONTRIBUTING.md，了解以下方面的详细指南：

• 开发环境设置和工作流
• 代码风格和约定
• 测试要求
• 文档规范
• 拉取请求流程

📄 许可证

MIT 许可证 — 详情请参阅 LICENSE。

🔗 链接

• GitHub 仓库 - 源代码和问题
• MCP 协议 - Model Context Protocol 规范
• PyPI 软件包 - Python Package Index
• MCP 注册表 - Model Context Protocol 注册表

---

需要帮助？ 请查看文档或在 GitHub 上提交问题。