mnemo

Mnemo MCP 服务

**更名（2026-09-13）：**仓库现名为 mnemo，以 CLI 优先（mnemo 命令）。PyPI 包仍为 mnemo-mcp；MCP 服务仍是次要入口。

mcp-name: io.github.n24q02m/mnemo

持久化 AI 记忆，支持混合搜索。开放、免费、无限制。

n24q02m 的姊妹项目（点击展开）

| 项目 | 标语 | 标签 | |---|---|---| | [agent-chat-plugin](https://github.com/n24q02m/agent-chat-plugin) | AI Agent 在共享文件夹中彼此聊天——无需人工传递消息、无需编排器，wor... | 工具 | | [better-code-review-graph](https://github.com/n24q02m/better-code-review-graph) | 面向高效令牌使用代码审查的知识图谱——语义搜索和调用-... | MCP | | [better-drive](https://github.com/n24q02m/better-drive) | 双向 Google Drive 同步，支持 .driveignore 过滤器——rclone 引擎，Windows 托盘 | 工具 | | [better-email-mcp](https://github.com/n24q02m/better-email-mcp) | 面向 AI Agent 的 IMAP/SMTP 邮件——读取、发送、整理文件夹并管理 att... | MCP | | [better-godot-mcp](https://github.com/n24q02m/better-godot-mcp) | 面向 Godot Engine 的复合 MCP 服务——提供 17 个复合工具，支持 AI 辅助 g... | MCP | | [better-notion-mcp](https://github.com/n24q02m/better-notion-mcp) | 面向 AI Agent、以 Markdown 为先的 Notion——页面、数据库、块和评论... | MCP | | [better-semantic-release](https://github.com/n24q02m/better-semantic-release) | 可直接替换的 python-semantic-release 分支，内置发布安全防护（orp... | 工具 | | [better-telegram-mcp](https://github.com/n24q02m/better-telegram-mcp) | 面向 AI Agent 的 Telegram——支持两种 bo...上的消息、聊天、媒体和联系人 | MCP | | [better-workspace-mcp](https://github.com/n24q02m/better-workspace-mcp) | Google Workspace MCP 服务（Docs/Drive/Calendar/Gmail/Sheets/Slides/Tasks/Ch... | MCP | | [claude-plugins](https://github.com/n24q02m/claude-plugins) | 面向 n24q02m MCP 服务的 Claude Code 插件市场——安装网页搜索... | 市场 | | [imagine-mcp](https://github.com/n24q02m/imagine-mcp) | 面向 AI Agent 的图像与视频理解及生成——支持 Gemini、Op... | MCP | | [jules-task-archiver](https://github.com/n24q02m/jules-task-archiver) | 通过 batchexecute API 批量操作 Jules 任务的 Chrome 扩展——a... | 工具 | | [mcp-core](https://github.com/n24q02m/mcp-core) | 构建 MCP 服务的共享基础组件——Streamable HTTP 传输、OAut... | MCP | | [mnemo](https://github.com/n24q02m/mnemo) | 支持混合搜索和嵌入式同步的持久化 AI 记忆。开放、免费、无限... | MCP | | [fastretrieval](https://github.com/n24q02m/fastretrieval) | 面向 ONNX/GGUF 嵌入和重排序的多模型检索运行时 | 库 | | [skret](https://github.com/n24q02m/skret) | 无需服务端的密钥管理。 | CLI | | [tacet](https://github.com/n24q02m/tacet) | 一种自蒸馏神经符号级联，可在 knowl...中分摊 LLM 成本 | 工具 | | [web-core](https://github.com/n24q02m/web-core) | 用于搜索、抓取、HTTP 安全和 st...的共享 Web 基础设施包 | 库 | | [wet-mcp](https://github.com/n24q02m/wet-mcp) | 面向 AI Agent 的开源 MCP 服务：网页搜索、内容提取和 lib... | MCP |

目录

• 功能
• 快速安装
• 状态
• 文档
• Smithery
• 工具
• 安全
• 从源代码构建
• CLI
• 自托管（本地 HTTP 实例）
• 远程（HTTP 模式）
• 信任模型
• 许可证

## 路线图（当前 = Phase 3 / v2.x）

下方阶段描述的是去托管前的设计历史（v1.x / v2 早期版本）： 多供应商大模型调度、GDrive/S3 Passport 同步和 Cloudflare 部署已在 2026-09 去托管时移除。当前架构： 一个本地 SQLite 存储（WAL）、按任务划分的 [models.*] 供应商单元格 （预接入的默认项为 OpenRouter），不内置同步（备份使用 rclone）。

Phase	Version	Status	Highlights
Phase 1	v1.x	已发布	类型化的 memory(action="capture")（6 种 context_types + 去重）——RRF（k=60）混合融合 + cross-encoder 重排序 + 时间衰减——重要性 × 新近度归档策略 + 恢复——Alembic 迁移——多供应商大模型调度（去托管前）——插件三件套（recall-context + memory-commit 技能、SessionStart + 可选的 PostToolUse 钩子）
Phase 2	v1.x+1	已发布，部分移除	由大模型驱动的旧记忆压缩（保留，现通过 [models.chat] 单元格实现）+ Passport 同步（加密导入/导出包；已于 2026-09 移除）
Phase 3	v2.0.0	已发布（重大变更）	时态知识图谱——双时态 valid_from / valid_to 列——通过嵌入 KNN 进行实体解析——entity_search / entity_graph / history 操作——在 capture 时选择启用 KG_AUTO_ENABLED 自动提取

功能

• 混合检索——FTS5 + 向量搜索（sqlite-vec），通过倒数排名融合（k=60）进行融合，然后由 [models.rerank] 供应商单元格（预接入的默认项为 OpenRouter）重新排序；若不可用，则回退到本地 Fastretrieval Qwen3 cross-encoder，并结合时间衰减和重要性加权
• 类型化捕获——memory(action="capture") 支持 6 种 context_types（conversation/fact/preference/skill/task/decision）、基于嵌入的去重，以及可选的 [models.chat] 单元格压缩 + 重要性评分
• 知识图谱——自动提取实体并跟踪关系；通过图谱邻近度提升排名靠前的结果
• 重要性评分 + 归档策略——由大模型评分，范围为 0.0-1.0；当 recency_factor * (1 - importance) > 1.0 时软归档；提供恢复操作
• 自动归档触发器——每 N 次捕获（默认 100 次）执行后台扫描——无需 cron
• STM 到 LTM 整合——对同一类别中的相关记忆进行大模型摘要
• 重复项检测——添加语义相似的记忆前发出警告
• 零配置——Fastretrieval 内置的本地注册表可解析 Qwen3 ONNX 嵌入和重排序，无需 API 密钥。可选的云端调用通过按任务划分的 [models.<task>] 供应商单元格进行（OpenAI 规范；预接入的默认项为 OpenRouter）
• 本地优先存储——在 ~/.mnemo/ 下存储一个 SQLite 文件（WAL）；备份和跨机器迁移由服务之外的 rclone 完成（不内置同步）
• 插件三件套——随附 /recall-context + /memory-commit 技能，以及 SessionStart + 可选的 PostToolUse 钩子（见 docs/ARCHITECTURE.md）
• 主动记忆——工具描述和技能会引导 AI 在恰当时机保存偏好、决策和事实
• 大模型压缩——每轮通过 [models.chat] 供应商单元格进行压缩，目标是在事实保留率 >=0.9 的前提下将令牌数减少约 3 倍；未配置该单元格时会正常跳过（见 docs/compression.md）
• 时态知识图谱——每条记忆都包含双时态列（valid_from / valid_to / superseded_by）+ 实体解析去重（嵌入 KNN，默认余弦阈值为 0.85）+ 审计跟踪（memory_audit 表记录变更前后的状态哈希）+ 新增操作（entity_search / entity_graph / history / as_of）+ 可选启用 KG_AUTO_ENABLED，在 capture 时自动提取。对于调用 memory.get 并预期获取包含历史记录的结果的客户端，属于重大变更：要进行时间回溯，请传入 as_of；默认行为现在会筛选为当前状态（valid_to IS NULL）。

快速安装

# Method 1: Claude Code plugin (skills + hooks; connects to a running
# mnemo HTTP instance -- start one per "Self-hosting" below)
/plugin marketplace add n24q02m/claude-plugins
/plugin install mnemo-mcp@n24q02m-plugins

# Method 2: run the HTTP server yourself and register the endpoint
uvx --from mnemo-mcp mnemo-mcp            # serves http://127.0.0.1:8000/mcp by default
claude mcp add --transport http mnemo http://127.0.0.1:8000/mcp

# Method 3 (remote): point a client at an existing HTTP deployment
claude mcp add --transport http mnemo https://<your-host>/mcp

安装矩阵（该服务仅支持 Streamable HTTP，不提供 stdio 传输；请参阅 设置页面，了解完整步骤）：

客户端	安装
Claude Code（插件）	/plugin marketplace add n24q02m/claude-plugins，然后运行 /plugin install mnemo-mcp@n24q02m-plugins（需要已运行的实例；请参阅自托管）
Claude Code（HTTP）	启动服务（uvx --from mnemo-mcp mnemo-mcp 或 docker compose），然后运行 claude mcp add --transport http mnemo http://127.0.0.1:8000/mcp
Codex / Gemini CLI / Cursor / Windsurf	启动服务，然后在客户端的 MCP 设置中注册 http://<host>:<port>/mcp HTTP 端点
任意 MCP 客户端	将其指向运行中实例的 /mcp 端点（Streamable HTTP）

在 mnemo-config/config.toml 中将 auth = "token" 或 "multi" 配置为认证方式后， 请将令牌作为 Bearer 凭证发送（使用 --header "Authorization: Bearer <token>" 或客户端的等效方式）。

与同类产品比较

功能	mnemo	Mem0	Letta	OpenMemory
混合检索（FTS + vec）	是（FTS5 + RRF + sqlite-vec）	是	部分支持	是
Cross-encoder 重排序	是（Fastretrieval Qwen3 本地运行 + [models.rerank] 配置项）	部分支持（仅 Cohere）	否	否
时间衰减评分	是（指数半衰期）	否	否	否
排名中的重要性加权	是（LLM 评分 0.0-1.0）	否	否	否
软归档 + 恢复策略	是（重要性 x 新近度）	否	否	否
可自托管（单个 SQLite 文件）	是（无需外部依赖）	部分支持（优先云端）	是（Postgres）	是（Postgres + Qdrant）
LLM 调度	是（[models.chat] 配置项，支持任意 OpenAI 规范的端点）	部分支持	是	部分支持
插件三件套（技能 + hooks）	是（recall-context + memory-commit）	不适用	不适用	不适用
跨机器迁移	是（在服务之外使用 rclone 备份 / 还原）	是（云端）	不适用	不适用
捕获时进行 LLM 压缩	是（[models.chat] 配置项，保留率 >=0.90 时约为 3x）	否	否	否
双时态 valid_from / valid_to 查询	是（as_of 时间回溯）	否	部分支持（仅事件）	否
通过嵌入 KNN 进行实体解析	是（余弦阈值可调）	否	否	否
含状态哈希的审计跟踪	是（memory_audit 表）	否	否	否

状态

2026-09 -- 去托管更新

Cloudflare D1/Vectorize/KV 部署模式、内嵌的 GDrive/S3 护照同步、多提供商密钥分发（每个提供商的 API 密钥环境变量 + 模型链），以及 stdio 传输均已移除。mnemo 现在在本地 SQLite（WAL）存储上运行一个 HTTP MCP 端点，所有云端调用都通过按任务配置的 [models.*] 提供商单元进行（默认预配置 OpenRouter）。 跨机器备份 = 在服务外部使用 rclone。

如果你在之前的版本中遇到问题，请更新到最新版本，并遵循当前的设置文档。

**MCP 注册表说明（2026-10）：**注册表版本 2.20.0 发布时包含 stdio PyPI 软件包声明（uvx mnemo-mcp），但该声明已不再反映产品现状：去托管后，mnemo 仅支持 Streamable HTTP——可自托管，无公共 URL。注册表版本不可变，因此无法直接修改过时的 stdio 声明；除非所有者将其从列表中移除，或重新发布为 2.20.1，否则注册表条目仍然有误。本仓库中的 server.json 现在声明了软件包的真实传输方式（streamable-http，默认本地端点），因此下次发布时将包含正确的元数据。

同一作者的相关插件：

• wet-mcp -- 网页搜索 + 内容提取
• imagine-mcp -- 图像/视频理解 + 生成
• better-notion-mcp -- Notion API
• better-email-mcp -- 邮件管理
• better-telegram-mcp -- Telegram
• better-godot-mcp -- Godot Engine
• better-code-review-graph -- 代码审查知识图谱

所有插件都采用相同的架构——安装一次，学会的模式即可迁移。

文档

完整文档请见 mcp.n24q02m.com/servers/mnemo-mcp/setup/：

• 设置 -- Claude Code、Codex、Gemini CLI、Cursor、Windsurf、mcp.json 的安装方法
• 模式概览 -- stdio / local-relay / remote-relay / remote-oauth
• 多用户设置 -- 基于 JWT sub 的凭据模型

使用 AI Agent 安装 -- 将以下内容粘贴给你的 AI 编码 Agent：

按照以下步骤安装 MCP 服务 mnemo-mcp： https://raw.githubusercontent.com/n24q02m/claude-plugins/main/plugins/mnemo-mcp/setup-with-agent.md

Smithery

mnemo-mcp 之前通过本地 stdio 启动命令打包供 Smithery 使用。去托管后，该服务仅支持 HTTP，因此已移除本地 smithery.yaml；请改为将运行实例的 https://<host>/mcp 端点作为远程服务发布到 Smithery。

工具

13 个 MCP 工具，18 种记忆操作。记忆功能通过 11 个 专用单一用途工具、已弃用的旧版 memory 调度器 （包含相同操作）以及 config 提供：

工具	操作	描述
add_memory、search_memory、list_memories、update_memory、delete_memory、export_memories、import_memories、memory_stats、restore_memory、archived_memories、consolidate_memories	（每个工具对应一种操作）	专用单一用途记忆工具——推荐使用
memory（旧版调度器，已弃用——请改用上方的细分工具；将在未来版本中移除）	add、capture、search、list、as_of、update、delete、export、import、stats、restore、archived、archive_now、consolidate、compress、entity_search、entity_graph、history	核心 CRUD + 类型化捕获（6 种 context_types）+ 混合搜索（RRF + 重排 + 时间衰减）+ 导入/导出 + 软归档 + 恢复 + 按需归档扫描 + LLM 整合 + LLM 压缩 + 时序知识图谱（实体搜索 / 图谱 / 历史 / as_of）
config	status、set、warmup、backfill_embeddings	服务状态、更新运行时设置、预下载嵌入模型、为缺失的嵌入向量回填数据

插件三件套（通过 Claude Code marketplace 安装）：

组件	触发条件	用途
mnemo:recall-context skill	会话开始、做出重要决策前、“关于 X 我知道什么？”	根据 context_type 筛选，提取与当前工作目录 / 主题相关的记忆
mnemo:memory-commit skill	“记住这个” / “保存这个” / “ghi nho” / “luu lai”	根据 context_type 决策树进行类型化手动捕获
mnemo:knowledge-audit skill	定期执行 / “审计记忆”	查找重复、矛盾和过时条目；进行整合
mnemo:session-handoff skill	会话结束	捕获决策 / 偏好 / 更正 / 约定 / 未解决的问题
mnemo:temporal-query skill	“截至” / “回到过去” / “历史” / “我当时是怎么想的”	通过 action="as_of" 获取特定时间点的快照，并通过 superseded_by 追踪版本链
SessionStart hook	每次会话初始化	以非阻塞方式提示调用 recall-context
PostToolUse hook（可选）	CAPTURE_AUTO_ENABLED=true	在写入 / 编辑 CLAUDE.md / AGENTS.md / ARCHITECTURE.md / docs/*.md 后提示使用 memory-commit

MCP 资源

URI	描述
mnemo://stats	数据库统计信息和服务状态

MCP 提示词

提示词	参数	描述
save_summary	summary	生成提示词，将对话摘要保存为记忆
recall_context	topic	生成提示词，回忆与某个主题相关的记忆

安全

• 优雅降级——云服务提供商单元会回退到本地 ONNX；未配置的单元绝不会静默选择付费服务提供商
• 仅主机凭据——服务提供商密钥存放在由主机管理的 config.toml 或 HULL_<TASK>_API_KEY 环境变量中；最终用户永远看不到这些密钥
• HTTP 认证门控——auth = "no-auth" 会拒绝非回环地址绑定；token / multi 需要进行凭据检查
• 错误信息清理——错误消息中不包含凭据

从源代码构建

git clone https://github.com/n24q02m/mnemo.git
cd mnemo
uv sync
uv run mnemo-mcp

CLI

该包提供两个不同的控制台脚本：

• mnemo —— 以 CLI 为先的记忆接口（主要供脚本／Agent 使用；不会启动服务）：capture、recall、reflect、fetch 和 standing-* 系列命令直接操作 SQLite 记忆数据库。 mnemo-pilot 是同一入口的旧版别名。
• mnemo-mcp —— MCP 服务及一次性运维子命令。直接运行时会启动 HTTP 服务；以子命令开头（config-init、warmup、token-hash、token-verify）则会执行相应操作并退出。

以 CLI 为先的记忆接口（mnemo；每个子命令都接受 --db <path>，输出 JSON 信封，并以映射到分类的代码退出）：

uvx --from mnemo-mcp mnemo recall --db ./mem.db "package naming" --k 3   # try without a persistent install

mnemo capture --db ./mem.db "keep PyPI name mnemo-mcp; repo is mnemo" --tags decision --category decision
mnemo recall --db ./mem.db "release ladder" --k 5        # search a subject's memories
mnemo reflect --db ./mem.db "why keep the alias?" --k 5  # bounded cited reflect over retrieval
mnemo fetch --db ./mem.db <memory_id>                    # fetch one memory by id
mnemo standing-refresh --db ./mem.db onboarding "how do releases cut?" --k 5   # materialize a standing page
mnemo standing-read --db ./mem.db onboarding             # cheap read with staleness info

服务运维 CLI（mnemo-mcp；直接运行时会启动 HTTP 服务）：

mnemo-mcp                       # start the Streamable HTTP MCP server
                                # (bind host/port from config.toml or MNEMO_HOST/MNEMO_PORT)

mnemo-mcp config-init [--force] # write ~/.mnemo/config.toml from the template
mnemo-mcp warmup                # pre-download local embedding model / probe cells
mnemo-mcp token-hash            # print a scrypt$ hash for [server] token_hash
                                # (reads MNEMO_AUTH_TOKEN or prompts)
mnemo-mcp token-verify <token> <scrypt$...>   # verify a token against a hash

子命令	用途
config-init [--force]	写入默认实例 config.toml（服务身份验证及 [models.*] 提供方配置项）
warmup	预下载由 Fastretrieval 管理的本地 ONNX 嵌入模型，以便首次使用时可离线运行
token-hash	为 [server] token_hash 生成 scrypt$ 哈希（共享令牌身份验证）
token-verify	根据已存储的 scrypt$ 哈希验证候选令牌

自托管（本地 HTTP 实例）

有两种方式可在你的计算机上为 MCP 客户端运行服务。

开发：使用 uv 启动（无身份验证，仅限环回地址）

uv run mnemo-mcp               # binds 127.0.0.1:8000, auth = "no-auth" by default

no-auth 会拒绝非环回地址绑定，因此从设计上讲只能通过本地主机访问——适合在本地试用该服务。MCP 端点为 http://127.0.0.1:8000/mcp。如需使用正式配置，请先初始化配置并进行编辑：

uv run mnemo-mcp config-init   # writes ~/.mnemo/config.toml from the template

持续运行：使用 docker compose（令牌身份验证，端口仅发布到环回地址）

docker-compose.http.yml 包含运行所需的全部配置（构建映像，并将状态持久化到 mnemo-data 卷），且仅在环回地址上发布端口：

cp mnemo-config/config.example.toml mnemo-config/config.toml   # then edit:
#   auth = "token"; set token_hash per the comments at the top of the example
docker compose -f docker-compose.http.yml up --build -d
# MCP endpoint: http://127.0.0.1:8771/mcp   (override the host port: MNEMO_PORT=9000 ...)

令牌设置（示例配置中也有说明）：

python -c "import secrets; print(secrets.token_urlsafe(32))"     # 1. mint token
MNEMO_AUTH_TOKEN=<token> uv run mnemo-mcp token-hash              # 2. print scrypt$ hash
# 3. paste the hash into token_hash in mnemo-config/config.toml; give clients the token

若要使用 auth = "multi"（按用户划分命名空间），还需挂载 users.toml——请参见 docker-compose.http.yml 中的注释行。

CLI 使用者（无需服务）

mnemo 接口直接访问记忆数据库，适用于脚本和 Agent：

mnemo capture --db ./mem.db "keep PyPI name mnemo-mcp; repo is mnemo" --tags decision --category decision
mnemo recall  --db ./mem.db "release ladder" --k 5
mnemo fetch   --db ./mem.db <memory_id>

每个子命令都会输出 JSON 信封，并接受 --db <path>。完整的命令列表（reflect、standing-* 等）请参见 CLI。

将 MCP 客户端指向该实例

注册 HTTP 端点（Streamable HTTP 传输）：

• Claude Code：claude mcp add --transport http mnemo http://127.0.0.1:8771/mcp
• 任意符合 OpenAI 规范的 MCP 客户端：服务 URL 为 http://127.0.0.1:8771/mcp；使用 auth = "token" 时，将共享令牌作为 Bearer 凭据发送。

配置：本地或云端，按任务设置

mnemo-config/config.toml 中的每个任务配置项（[models.embed]、rerank、chat、jev_score）彼此独立：通过 base_url + api_key + model 配置，使用符合 OpenAI 规范的 HTTP 接口。可自由混搭——例如，chat 使用云端 OpenRouter，而 embed／rerank 指向本地的 OpenAI 规范服务；也可以全部使用云端。密钥仅由主机持有（终端用户不会看到），也可通过 HULL_<TASK>_API_KEY 环境变量提供。

远程（HTTP 模式）

mnemo 通过单一 /mcp 端点使用 Streamable HTTP——远程访问需在可访问的主机上自托管实例，并使用你选择的 TLS 代理进行转发（服务本身绑定纯 HTTP）。在 mnemo-config/config.toml 的 [server] 下配置身份验证：auth = "token"（一个共享的 Bearer 令牌）或 auth = "multi"（通过 users.toml 设置每用户令牌和命名空间）。auth = "no-auth" 会拒绝非环回地址绑定。

公开发布 OCI 映像的工作已停止。现有历史注册表标签保持不变；新的容器部署需从源代码构建（docker build --target http）或使用 docker-compose.http.yml。

信任模型

mnemo 属于 TC-Local（绑定到本机）：所有存储文件都位于 由你的操作系统用户拥有的 ~/.mnemo/ 下，提供方密钥仅存于主机配置 （config.toml / HULL_<TASK>_API_KEY）中，MCP 客户端永远无法看到。

[server] auth	允许的绑定地址	存储	谁可以读取你的数据？
no-auth（默认）	仅限环回地址（拒绝非环回地址绑定）	~/.mnemo/memories.db + config.toml	只有你的操作系统用户
token	任意	相同，使用一个共享的 default 命名空间	任何持有共享令牌的人
multi	任意	按命名空间存储于 ~/.mnemo/subs/<ns>/memories.db（通过 users.toml）	每个令牌持有者只能看到自己的命名空间

许可证

Apache-2.0 -- 参见 LICENSE。