使用说明

MCP纪念品

MCP客户端的智能内存管理，具有信心跟踪、关系映射和知识质量维护功能。

Memento是一个MCP服务器，可在多个平台上提供持久内存功能：

月中日：Zed、光标、风帆、VSCode、克劳德桌面
CLI代理：Gemini CLI、Claude CLI、自定义代理
程序化使用：MCP客户端（Python）、Docker部署、CLI导出/导入
应用程序：任何与MCP兼容的应用程序

建立一个个人或团队知识库，随着时间的推移变得更加智能，可以从您的所有开发工具中访问。

🌱 温和的介绍

什么是Memento？ 想象一下，你正在解决一个复杂的bug，找出一个棘手的配置，或者建立一个新的编码模式。通常，你会在几周内忘记细节。Memento是您的AI助手的“长期记忆驱动器”。它允许你的人工智能保存这些解决方案、决策和事实，这样它就可以在不同的项目中立即回忆起它们，甚至在几个月后。

💡 代理思维：传统开发者指南 如果你习惯于确定性软件（因为脚本这么说，事情会自动发生），与人工智能代理交互需要轻微的心理转变。

纪念品是 不是自主代理 它看着你的屏幕，神奇地决定要记住什么。相反，Memento是一个 工具腰带 提供给您的AI助手（如Claude、Cursor或Gemini）。

AI就是工人： 需要告知何时使用工具带。如果没有明确的指令或预定义的规则，则不会保存任何内容。
你是经理： 您可以控制存储的内容。你可以在聊天时告诉人工智能(“保存此数据库连接字符串”)，或者您可以给出AI标准操作程序（通过系统提示或 .cursorrules/CLAUDE.md 文件），因此它知道自动保存某些内容，如错误修复或架构决策。

如何养成习惯：

会话开始： 问你的AI， “我们对身份验证系统了解多少？” 提取上下文。
工作期间： 当你解决一个棘手的问题时，比如说， “我们修复了Redis超时问题。请存储此解决方案。”
会议结束： 告诉你的AI， “存储我们今天完成的工作摘要。”

或者，您可以向您的AI添加自定义指令（请参阅我们的代理配置指南)使其自动执行这些步骤，而无需每次都询问。

✨ 主要特点

🧠 智能信任系统

自动衰减：未使用的知识会随着时间的推移而失去信心（每月5%）
关键保护：安全性/auth/API密钥内存从不衰退
加强验证当知识被成功运用时，信心会增强
智能排序：搜索结果按以下方式排列 confidence × importance

🔗 关系映射

35种关系类型：跨7个语义类别的解决、原因、改进、USED_IN等（参见关系类型参考)
图形导航：查找概念之间的联系
模式检测：识别重复出现的解决方案模式

📊 三剖面系统

配置文件	工具	最适合
核心	13个工具	所有用户-基本操作
扩展的	17个工具	高级用户-统计、上下文搜索、衰变控制
高级	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代理 （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的工具。这是不一个你可以使用的Python库 import.用于编程Python访问看 Python集成指南.

💬 自然语言：您还可以通过自然对话与Memento互动。只需告诉你的人工智能助手“记住……”或“存储这个……”，或“记忆碎片……”——不需要代码。

📖 核心概念

要深入了解Memento的概念（信任系统、标记、关系），请阅读综合规则.md 和关系S.md 文档。

🔗 集成

Memento适用于所有主要的开发工具：

平台	配置指南	注意事项
Zed编辑	IDE集成	原生MCP支持
光标	IDE集成	AI驱动的编辑器
帆板运动	IDE集成	现代代码编辑器
VSCode	IDE集成	通过MCP扩展
克劳德桌面	IDE集成	桌面应用程序
双子星命令行工具	代理集成	Google的CLI代理
Claude 命令行界面	代理集成	Anthropic的CLI代理
Python/MCP客户端	Python集成	嵌入服务器或通过MCP客户端调用
Docker/CLI	API与编程	MCP客户端、Docker、导出/导入

另请参阅: 集成概述以获取选择正确集成的指导。

🛠️ 基本使用示例

以下示例展示了 MCP工具调用 AI助手（Zed、Cursor、Google）， Claude、Gemini CLI等）在您要求它记住或执行时代表您执行取回某物。它们是用类似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"

当配置了中的指南时，AI还可以自动存储重要信息 AGENT_CONFIGURATION.md.

⚙️ 配置

Memento支持多个配置源（按优先级顺序）：

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

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

环境变量

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

YAML配置文件
- 项目配置： ./memento.yaml 在当前目录中（覆盖全局）
- 全局配置： ~/.mcp-memento/config.yaml

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

默认值 （最低优先级）

支持的YAML密钥

以下按键为 读取并应用 通过配置加载器。YAML文件中存在的任何其他键都会被自动忽略。

关键字	类型	默认值	描述
`db_path`	字符串	`~/.mcp-memento/context.db`	SQLite数据库文件路径
`profile`	字符串	`core`	刀具轮廓(`core`, `extended`, `advanced`)
`logging.level`	字符串	`INFO`	日志级别(`DEBUG`, `INFO`, `WARNING`, `ERROR`)
`features.allow_relationship_cycles` bool的。 `false`	允许图中的循环关系

备注：The 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种关系类型及其示例
使用规则 -最佳做法和惯例
代理配置 -AI代理模板

集成指南

集成概述 -选择正确的集成
IDE集成 -Zed、光标、风帆、VSCode、克劳德桌面
Python集成 -MCP客户端使用、服务器嵌入、CLI导出/导入
代理集成 -CLI代理和自定义应用程序
API与程序集成 -MCP客户端（Python）、Docker部署、CLI导出/导入

发展与高级主题

数据库模式 -技术数据库结构
贡献指南 -开发设置和工作流程

🏗️ 架构概述

数据库模式

Memento使用统一的SQLite模式，可从所有集成中访问：

核心表: nodes （存储器存储）， relationships （有向图）
全文搜索: nodes_fts --用于快速搜索的FTS5虚拟表（如果FTS5不可用，则回退到基于LIKE的搜索）
信心追踪：自动衰减，保护关键记忆

一致性行为

该系统在所有平台上的工作方式相同：

同一数据库：所有工具访问相同的SQLite文件
相同的置信度跟踪：一个工具的更新随处可见
相同的搜索排名：结果按顺序排列 confidence × importance
相同的关系类型：35种语义关系类型随处可用

📜 背景

Memento是一个简化的、轻量级的fork 内存图 Gregory Dickson，针对IDE和CLI代理之间的MCP集成进行了优化。

分叉侧重于可移植性和令牌效率：它消除了严重的依赖性（NetworkX、多后端存储、双时态跟踪、多租户架构），转而支持仅使用SQLite的后端，该后端具有基于置信度的衰减和指南驱动的存储。

团队协作和远程部署

多个用户可以使用标记约定共享SQLite数据库（例如，在网络存储上）(team:[name], author:[name]).Memento也可以作为远程MCP服务器运行，尽管所有客户端共享同一个数据库，没有租户隔离。看团队协作指南了解详情。

对于真正的多租户，请使用原始的MemoryGraph项目。

什么时候选择MemoryGraph和Memento？

使用记忆：用于IDE和CLI工具中的轻量级跨平台内存管理
使用内存图：适用于需要多租户、双时态跟踪或自定义后端的企业用例

🙏 致谢

Memento建立在Gregory Dickson的坚实基础之上内存图项目。我们感谢他在内存管理系统方面的开创性工作。

此分支保持了与MemoryGraph核心概念的兼容性，同时使其适应MCP集成和现代开发工具的特定需求。对于需要MemoryGraph高级功能全部功能的用户，我们建议您探索原始项目。

🧪 Beta状态

mcp webgate加入 测试版核心功能稳定，服务器用于生产，但是配置API在1.0之前仍然可能改变。

非常欢迎反馈。 如果某件事没有按预期工作，表现得很奇怪，或者你有一个未涵盖的用例：

→ 在GitHub上打开一个问题

错误报告、配置问题和功能请求都有助于制定路线图。

🤝 贡献

欢迎投稿！请看贡献.md 有关以下内容的详细指南：

开发设置和工作流程
代码风格和惯例
测试要求
文件标准
拉取请求流程

📄 许可证

MIT许可证-请参阅许可证了解详情。

🔗 链接

GitHub存储库 -源代码和问题
MCP协议 -模型上下文协议规范
PyPI包 -Python包索引
MCP注册表 -模型上下文协议注册表

需要帮助？ 检查文档或打开问题在GitHub上。