memento-mcp 是一个持久记忆 MCP 服务器，为 AI 编程智能体提供本地优先的项目记忆能力。它适用于 Claude Code、Codex、Cursor 以及任何 stdio-MCP 客户端。
用途 AI 编程智能体虽然强大，但会遗忘：忘记某个决策为何做出、哪次迁移导致生产故障、项目遵循什么约定、上周哪个临时方案省了三小时。memento-mcp 解决这一问题，同时也避免智能体在每次会话中重新读取相同上下文、消耗大量 token。它把结构化记忆存储在本地 SQLite 中，在智能体需要时检索并注入正确上下文，并可通过 git 同步选定的团队记忆。不需要托管向量数据库，不需要强制云账户。
主要能力
- 记忆知识模型：支持多种类型的项目知识，如 fact（事实）、decision（决策）、preference（偏好）、pattern（模式）、architecture（架构）、pitfall（踩坑），不同类型具有不同的排序权重和检索行为。提供 decisions_log、pitfalls_log 等专用工具便于记录高价值记忆。
- 节省 token：可一次性导入 CLAUDE.md、AGENTS.md、.cursor/rules/、Copilot 指令等 LLM 指令文件，并通过渐进式披露只返回当前提示所需的片段，优先使用低成本的索引/摘要层而非完整正文。
- 团队记忆同步：团队范围的记忆以 JSON 文件序列化到仓库中，团队成员可提交、推送、拉取共享的操作知识，像普通项目文件一样审查、提交、比对和同步。
- 本地优先：默认使用 SQLite FTS5 搜索和本地 Web 检查器，无需云账户和托管数据库；可选嵌入检索为选择性开启。
- 隐私控制：<private>...</private> 区域会从搜索索引、注入、嵌入、LLM 调用和同步路径中排除；写入时会清理常见凭据（环境变量值、JWT、GitHub token、URL 凭据、授权头等）。支持标题与正文净化。
- 本地 Web 检查器：可浏览记忆、会话、项目、同步状态、分析数据和记忆健康状况。
- 写入时去重：启用嵌入后，可在写入时检测近似重复的记忆。
- 会话摘要：支持确定性摘要（默认）和可选的 LLM 辅助摘要（使用 Anthropic 或 OpenAI）。
- 令牌感知搜索：默认使用令牌感知的结果排序和自适应效用反馈，无需向量数据库。
- 可选语义搜索：启用嵌入后，FTS5 与向量结果通过自适应排序器合并，嵌入为选择性开启并使用用户自己的提供商密钥。
- Obsidian 保险库集成：可索引精选的 Obsidian 保险库，并经由 me.md、vault.md、地图、技能、剧本、长篇项目笔记等路径路由上下文；保险库层会被索引和搜索，但除非明确提升，智能体不会自动写入。
- 按项目策略：通过 .memento/policy.toml 控制项目特定行为，包括禁用内容模式、保留规则、保险库提升规则和记忆约束；策略存放在仓库中。
- 模式配置：可通过配置或环境变量切换停用词与琐碎提示分类器的 profile。
使用方式 前置条件：Node.js 20 或更新版本（20.x、22.x、24.x；Node 18 已 EOL 不再支持）；一个兼容 MCP 的客户端，如 Claude Code、Codex、Cursor 或其他 stdio-MCP 客户端。可选：Obsidian 保险库（用于精选 Markdown 知识）、OpenAI 密钥（用于语义嵌入）、Anthropic 或 OpenAI 密钥（用于 LLM 辅助会话摘要）、git 仓库（用于团队记忆同步）。 该工具以 memento-mcp 名称发布在 npm 上。全局安装后，将其接入 MCP 客户端配置，即可支持 Claude Code、Codex、Cursor 等本地 stdio-MCP 客户端；随后可验证安装并打开本地 Web UI。 自动上下文注入与捕获：记忆工具（memory_store、memory_search、decisions_log 等）可在任意 stdio-MCP 客户端中使用。自动注入与捕获依赖各客户端提供的扩展机制——多数主流客户端现已暴露生命周期钩子。各客户端的钩子事件名称与配置格式不同（例如 Claude Code 使用 UserPromptSubmit，Cursor 使用 beforeSubmitPrompt，Cline 以文件名区分事件）。四个 memento-hook-* 二进制文件针对 Claude Code 的 stdin 载荷结构构建，可直接用于 Codex（载荷非常相似），在 Cursor、Gemini CLI 和 Cline 上可能需要轻量适配器。对于没有钩子的客户端，可退回使用规则文件（AGENTS.md、.cursor/rules/*.mdc、系统提示）指示智能体自行调用记忆工具。 启动本地浏览器 UI 后可查看 memories、sessions、projects、sync drift、analytics、memory health。
适用场景
- 记住项目决策：例如记录“复杂 SQL 访问使用仓库类而非在控制器中写查询”，并注明原因与范围、标签。
- 记住踩坑：例如记录“分页查询在加载全部行后代价高昂”，附上修复方式、范围与标签。
- 记住团队约定：例如记录“本项目在发布说明中分别跟踪缺陷修复和改进”，范围为团队。
- 将决策、踩坑、模式和架构说明记录为结构化记忆，而不是埋在旧聊天或随机 Markdown 文件里。
- 通过 git 与团队共享操作知识。
限制与说明
- 默认检索为本地 SQLite FTS5，语义检索需选择性开启嵌入。
- 嵌入与 LLM 会话摘要为可选项，需使用用户自己的提供商密钥。
- Obsidian 保险库层会被索引和搜索，但除非明确提升，智能体不会自动写入。
- 自动注入与捕获依赖客户端钩子机制，部分客户端需适配器或退回规则文件方式。
- 项目测试覆盖：共有 1,352 项测试、跨 121 个测试文件，覆盖 91% 行和 85% 分支，CI 在 Node 20、22、24 上运行每次推送和拉取请求。进程入口点（src/index.ts、src/cli/main.ts、钩子 bin 脚本）不计入覆盖率分母，因其通过 spawnSync 由集成测试执行，v8 无法跟踪子进程覆盖率；其调用的处理器与辅助函数已完全覆盖。
- 关于具体收费、价格与平台支持范围，资料未提供。
