内容
# mnemon
[](https://github.com/nousergon/mnemon/issues)
[](https://www.python.org/downloads/)
[](LICENSE)
[](https://modelcontextprotocol.io)
[](https://pypi.org/project/mnemon-memory/)
[](https://github.com/nousergon/mnemon/actions/workflows/ci.yml)
> 一个记忆保险库。每个MCP客户端。自我托管。
>
> **状态：** alpha — 接口可能会更改。欢迎提交问题和拉取请求。
Claude Code、Cursor、claude.ai 网页/移动端/桌面端、Claude Desktop、Gemini CLI — 一个保险库可跨所有客户端共享。
mnemon 是一个 [Model Context Protocol](https://modelcontextprotocol.io) 服务器，采用混合 BM25 + 向量搜索。您的数据保留在您的机器或您自己的 Fly 应用程序上。
**平台：** 在 macOS 14+ 上经过测试。Linux 应该可行。Windows 未测试。
## 两条产品线：本地和网页
| 功能 | **mnemon 本地** | **mnemon 网页** |
|---|---|---|
| Claude Code (CLI) | ✅ | ✅ |
| Claude Desktop (Mac/Win 应用) | ✅ | ✅ |
| Cursor | ✅ | ✅ |
| Gemini CLI | ✅ | ✅ |
| 任意本地 MCP 客户端 | ✅ | ✅ |
| **claude.ai (网页)** | ❌ | ✅ |
| **Claude 移动应用** | ❌ | ✅ |
| 跨笔记本电脑 + 桌面端共享内存 | ❌ | ✅ |
| 持久的机器外备份 | ❌ (手动文件复制) | ✅ (S3) |
| 需要外部账户 | 无 | Fly.io + AWS |
| 需要信用卡 | 否 | 是（两个免费层级都需要） |
| 首次安装设置时间 | ~2 分钟 | ~15 分钟 |
| 持续成本 | $0 | ~$0（免费层级） |
| 空闲状态下的冷启动延迟 | 无 | 2–5 秒 |
- **mnemon 本地** — 一台机器，一个或多个 MCP 客户端。无需外部账户。`pip install mnemon-memory && mnemon setup`。
- **mnemon 网页** — 跨设备共享内存 + claude.ai + 移动应用。需要 Fly.io + AWS。`mnemon upgrade web --app-name my-mnemon`。
从本地开始，随后升级 — 您的保险库会保留。`mnemon downgrade local` 恢复。舒适地支持多达 ~50k 个记忆。
## 安装
```bash
pip install mnemon-memory
```
可选：`pip install "mnemon-memory[ui]"` 以安装 Streamlit 仪表板，或 `[llm]` 以安装设备上的 1.7B 模型。
**从源代码安装** （例如，尝试在 `main` 分支上发布未发布的修复程序）：
```bash
git clone https://github.com/nousergon/mnemon.git
cd mnemon
pip install -e .
```
**对于贡献者** （添加 `pytest`、`ruff` 和其他测试/检查工具）：
```bash
pip install -e ".[dev]"
```
## 快速入门
mnemon 的主要目的是 **一个记忆保险库可跨所有客户端共享** — Claude Code、claude.ai 网页、Claude Desktop、移动应用、Cursor。这是一个 **默认设置**。它是一个您自己的 Fly.io 应用部署（使用您的密钥，您的资料），而 `upgrade web` 使其变得简单 — 包括头条客户端和浏览器客户端的身份验证。
### 跨设备（默认）
前提条件：[`flyctl`](https://fly.io/docs/flyctl/install/) 已身份验证，`aws` CLI 已配置，S3 存储桶。
```bash
pip install "mnemon-memory[server]"
export MNEMON_S3_BUCKET=my-mnemon-vault
mnemon upgrade web --app-name my-mnemon
```
这部署了 **您自己的** mnemon 到 Fly，初始化保险库，并为两种客户端提供身份验证：
- **无头客户端** （Claude Code，Cursor）— 自动重新配置带有 bearer token。
- **浏览器客户端** （claude.ai 网页，Claude Desktop，移动应用）— 为您启用自托管 OAuth 授权服务器（密钥对保留在 Fly 卷上）。在应用的设置 → 连接器中，添加一个自定义连接器，名称 + URL 为 `https://my-mnemon.fly.dev/mcp` — **保持客户端 ID / 客户端密钥为空** （授权服务器通过动态客户端注册自行注册）。当您点击连接时，它会重定向到登录页面；输入在部署结束时打印的 **通行短语** （也保存在 `~/.mnemon/as_passphrase`）。通行短语是 OAuth 登录，**不是**连接器字段。
无第三方身份验证供应商，无手动密钥管理。`mnemon doctor` 在部署结束时运行以验证部署。
### 仅本地（快速演示）
仅在单台机器上试用，无需 Fly/AWS 账户？您可以选择仅本地路径 — 但请注意这是 **单机，无跨设备共享** （这是您将跳过的主要功能）：
```bash
pip install mnemon-memory
mnemon setup
```
自动检测 Claude Code、Claude Desktop、Cursor、Gemini CLI — 配置每个客户端，然后运行 `mnemon doctor`。首次 `memory_search` 需要 ~10–20 秒（一次性 FastEmbed 模型下载）。随时升级到完整跨设备设置，使用 `mnemon upgrade web`。
### 升级到较新版本（已在网页上）
在 `pip install -U mnemon-memory` 后重新运行相同的命令 — `upgrade web` 是幂等的。如果 Fly 应用已经存在，它会跳过首次步骤（S3 推送，卷创建，客户端重新配置），并直接使用新版本重新部署。客户端保留其 URL 和令牌；新镜像将在下一个请求中被拾取。
```bash
pip install -U 'mnemon-memory[server]'
mnemon upgrade web --app-name my-mnemon
```
> **从 0.7.0rc10 之前的部署升级？重新认证您的浏览器连接器一次。** 在 OAuth 授权服务器自动配置之前部署的应用程序仅具有无头 bearer 令牌。`upgrade web` 的第一个操作 **配置一个新的 OAuth 通行短语** （并启用授权服务器） — 因此，您的现有 claude.ai / Desktop / 移动连接器登录停止工作，直到您重新认证。获取新的通行短语从部署摘要或 `~/.mnemon/as_passphrase`，并在连接器的登录页面上重新输入。通行短语是 **一次性** 转换：一旦通行短语存在，每个后续部署都会保留它（它永远不会被轮换）。无头客户端（Claude Code，Cursor）不受影响 — 它们保留其 bearer 令牌。
#### 可选：从 CI 部署
上述命令是 **支持的，充分功能** 的部署方式 — 用于自托管和在信任自动化之前测试更改。存储库还附带一个可选的 **`Deploy to Fly`** GitHub Actions 工作流（`.github/workflows/deploy-fly.yml`），您可以将合并的更改滚动到 Fly 上，而无需在本地运行 `flyctl`。它只是包装相同的 `flyctl deploy` — 它无法执行您手动无法执行的操作。
它针对 **您的** 部署，因此在新 fork 中它是惰性的，直到您连接两个内容：
1. **`FLY_API_TOKEN`** 存储库密钥 — `fly tokens create deploy -a <your-app>` （设置 → 密钥和变量 → 操作 → **密钥**）。
2. **`FLY_APP`** 存储库变量 — 您的 Fly 应用名称（同一页面 → **变量**）。或在手动运行时将它作为 `app` 输入传递。
一旦连接，它会以两种方式运行：
- **自动在每次推送到 `main` 时运行** （例如，合并的 PR）— 零点击。此自动部署 **仅在规范的非 fork 存储库上触发** ，因此 fork 项目永远不会出现红色 CI。
- **手动** — 从 **操作** 选项卡，或 `gh workflow run "Deploy to Fly"` （此路径在 fork 上也适用）。
无论哪种方式，它都会为您的应用渲染 `fly.toml`，运行 `flyctl deploy --remote-only` （在 Fly 的构建器上构建），并在完成后检查 `/health` 是否报告 `status=ok`。重新部署保留您的保险库卷和密钥（包括 OAuth 通行短语，从不轮换）— 与 `upgrade web` 的重新部署路径相同。不要想要自动部署？删除工作流中的 `push:` 触发器，它将恢复为仅手动。
### 降级回本地
```bash
mnemon downgrade local --destroy-fly-app
```
通过 S3 拉回 Fly 保险库，重新配置客户端为 stdio，可选地销毁 Fly 应用。不会丢失任何记忆。
### 可视化您的保险库
```bash
pip install "mnemon-memory[ui]"
mnemon dashboard
```
在 `http://localhost:8503` 处显示 Streamlit 仪表板 — 保险库健康状况、搜索、时间线、交互式图形视图和您的个人资料。对本地和远程保险库均有效。
图形视图将您的嵌入空间投影到 2-D — 本地保险库使用 UMAP，远程保险库使用服务器端计算的 PCA，以便扩展到数千个记忆，而无需通过线缆发送每个向量。
### 使用它
配置后，mnemon 会自动工作 — 记忆会保存并在您的会话期间显示。您也可以直接交互：
```bash
mnemon search "部署架构"
mnemon save "DB 迁移计划" "从 PostgreSQL 迁移到 DynamoDB 在 Q3"
mnemon forget 42
mnemon status
```
### 验证它是否正常工作
```bash
mnemon doctor # 健康状况 + 身份验证 + 真实保存→搜索→遗忘往返
mnemon verify-sharing # 证明多个客户端共享一个保险库（网页模式）
```
`doctor` 自动检测本地或网页模式，并运行正确的检查（在网页模式下，它还会警告如果过时的本地保险库遮蔽了远程保险库）。`verify-sharing` 在远程写入一个哨兵，并打印一个搜索词在另一个客户端运行（例如 Claude Desktop）— 如果它出现在那里，则该客户端已连接到同一个保险库。使用 `mnemon verify-sharing --cleanup` 进行清理。
## MCP 工具
### 检索
| 工具 | 描述 |
|------|-------------|
| `memory_search` | 混合 BM25 + 向量搜索，具有复合评分（相关性 + 时效性 + 置信度） |
| `memory_get` | 通过 ID 获取特定记忆及其完整内容 |
| `memory_timeline` | 按逆时间顺序排列的最近记忆 |
| `memory_related` | 通过关系图查找与给定记忆相关的记忆 |
### 变更
| 工具 | 描述 |
|------|-------------|
| `memory_save` | 存储具有内容类型分类和自动嵌入的新记忆 |
| `memory_pin` | 固定记忆以提高置信度并防止存档 |
| `memory_forget` | 软删除记忆（标记为失效，但不物理删除） |
### 层次（显著性）
| 工具 | 描述 |
|------|-------------|
| `memory_promote` | 将记忆提升到层次 — 始终开启的上下文，无论查询如何注入 |
| `memory_demote` | 将层次记忆降级回情况（相关性排名）召回 |
| `memory_list_standing` | 列出当前的层次记忆 |
### 生命周期
| 工具 | 描述 |
|------|-------------|
| `memory_status` | 保险库健康状况统计 — 按类型、向量、固定/失效计数 |
| `memory_sweep` | 存档过期记忆（默认情况下为试运行） |
| `memory_rebuild` | 重新嵌入所有文档（在升级嵌入模型后使用） |
| `memory_export_vectors` | 导出存储的嵌入（例如，用于分析或可视化） |
| `memory_export_coords` | 导出保险库嵌入的 2-D PCA 投影 — 仪表板图形页面的可扩展路径，用于大型远程保险库 |
| `memory_export_relations` | 导出所有活动文档之间的关系边，一次调用，用于图形页面的边叠加层 |
### 智能
| 工具 | 描述 |
|------|-------------|
| `memory_check_contradictions` | 使用向量相似性 + NLI 分类检查记忆冲突（`cross-encoder/nli-deberta-v3-xsmall`） |
| `profile_get` | 从存储的偏好和决策中合成用户配置文件 |
| `profile_update` | 手动向用户配置文件添加事实 |
## 记忆类型
每个记忆都有一个内容类型，它决定了其默认置信度和衰减半衰期：
| 类型 | 默认置信度 | 半衰期 | 用途 |
|------|-------------------|-----------|---------|
| `decision` | 0.85 | 永远 | 架构选择、设计决策 |
| `preference` | 0.80 | 永远 | 用户工作流习惯、样式偏好 |
| `antipattern` | 0.80 | 永远 | 失败的事、避免的方法 |
| `observation` | 0.70 | 90 天 | 学习到的事实、发现的行为 |
| `research` | 0.70 | 90 天 | 调查结果、发现 |
| `project` | 0.65 | 120 天 | 项目状态、目标、上下文 |
| `handoff` | 0.60 | 30 天 | 连续性会话摘要 |
| `note` | 0.50 | 60 天 | 一般笔记、默认类型 |
访问活动中的记忆衰减较慢 — 每次访问将有效半衰期延长 10%，最多 3 倍基数值。
## Claude Code 钩子
配置 `mnemon setup` 后，以下钩子将在 Claude Code 上安装：
| 钩子 | 事件 | 超时 | 模式 | 描述 |
|------|-------|---------|------|-------------|
| 健康保持器 | `UserPromptSubmit` | 40 秒 | 仅远程 | `curl /health` 以唤醒/保持 Fly 机器温暖。运行在 MCP 调用之前，因此以下操作具有温暖的机器。 |
| 上下文显示 | `UserPromptSubmit` | 8 秒 | 两个 | 搜索保险库并注入相关记忆作为上下文 |
| 会话预热 | `SessionStart` | 90 秒 | 仅远程 | 在后台轮询 `/health` 多达 60 秒，以便第一个提示会话落在温暖的机器上 |
| 会话提取器 | `Stop` | 30 秒 | 两个 | 从转录中提取决策、偏好和观察结果 |
| 转移生成器 | `Stop` | 30 秒 | 两个 | 创建会话摘要以实现连续性 |
提取器和转移生成器在安装 `mnemon[llm]` 时使用基于 LLM 的提取，否则使用正则表达式/启发式回退。
### 为什么 Fly 自动停止？
具有自动停止启用（`fly.toml.example` 默认设置为 `auto_stop_machines = "suspend"` — RAM 快照/恢复 ~1s，因此 OAuth 令牌唤醒时保持在连接器超时范围内）的自托管 mnemon Fly 应用将空闲后几分钟后空闲。保持器重置 Fly 的空闲计时器以确保在活跃的 Claude Code 会话期间机器保持温暖，并且仅在您空闲了一段时间后自动停止。成本保持不变 — Fly 仅计费运行时间 — 但您获得可靠的会话中间访问权限而无需支付始终在线的机器。 `|| true` 确保慢 Fly 冷启动永远不会阻止您的提示。
### 如果冷停止发生怎么办？
服务器在 `<vault_dir>/mcp_sessions.sqlite` 持久化每个发出的 MCP 会话 ID（7 天 TTL）。当请求带有已知但不在内存中的会话 ID 到新进程时 — 通常在冷停止或重新部署后 — 会话透明地恢复：一个新的传输与相同的 ID 产生，并且底层 `ServerSession` 已初始化以确保工具调用成功。MCP 客户端看到连续性中断。
### 什么是真正的修复？
Anthropic 需要在 Claude Desktop 上添加预提示生命周期钩子 — Claude Desktop 侧等效于 Claude Code 的 `UserPromptSubmit`。一旦该接口存在，mnemon 现有的 `context_surfacing` 钩子可以直接连接到它。直到该接口存在，Claude Code` 的唯一客户端具有保证的预 LLM 注入；其他地方的检索由模型决定。
### 适用于非 Code 客户端的近似实用解决方法
为非 Code 客户端提供相同的代码片段 — 将其粘贴到客户端提供的自定义说明/规则/记忆界面中：
> 在响应我的任何提示之前，请使用 mnemon MCP 服务器的相关术语调用 `memory_search` 工具。使用返回的记忆来为您的响应提供信息。如果 `memory_search` 返回的结果没有用，请继续处理它。
| 客户端 | 需要自定义说明吗？ | 在哪里粘贴 |
|---|---|---|
| **Claude Code** | 否 — `UserPromptSubmit` 钩子无条件处理。 | — |
| **Claude Desktop** | 是 | 设置 → 个人资料 → “应考虑的个人偏好” |
| **claude.ai（网页）** | 是 | 与 Desktop 相同 — 它在您的 Anthropic 帐户中共享。项目说明也起作用，并在该项目中覆盖个人资料。 |
| **Claude 移动应用** | 是 | 继承自相同的个人资料字段 — 在 Desktop 或 claude.ai 上设置一次，移动应用会继承。 |
| **Cursor** | 是 | 设置 → 规则 → **用户规则**（全局）或 `.cursor/rules/*.mdc` 文件（作用于项目） |
| **Gemini CLI** | 是 | `~/.gemini/GEMINI.md` （全局）或项目根目录下的 `GEMINI.md` |
在所有非 Code 客户端中，调用仍然由模型决定 — 它将跳过短提示、后续跟进或当模型分心时。不能替代真正的生命周期钩子。
### 何时真正的修复到来
Anthropic 需要为 Claude Desktop 添加一个预提示生命周期钩子 — 与 Claude Code 的 `UserPromptSubmit` 类似的 Desktop 端等价钩子。一旦该接口存在，mnemon 现有的 `context_surfacing` 钩子可以直接连接到它。直到那时，Claude Code 是唯一具有保证的预 LLM 注入的客户端；其他地方的检索由模型决定。
## 卸载
删除此机器上的 mnemon 状态。云中用户拥有的内容不会被触及。
```bash
mnemon uninstall [--yes] [--keep-vault]
```
### mnemon 卸载会删除的内容
- `~/.mnemon/` — 保险库（SQLite + 向量）、存档/、remote_url、local_token、模型缓存。使用 `--keep-vault` 时，该目录将被保留。
- Claude Code MCP 注册（`claude mcp remove --scope user mnemon`）。
- `~/.claude/settings.json` 中的 mnemon 钩子和 mcpServers 条目。
- `~/.cursor/mcp.json` 中的 mnemon 条目。
- Claude Desktop 配置文件中的 mnemon 条目。
### mnemon 卸载不会触及的内容
- **`mnemon-memory` Python 包。** 请单独使用 `pip uninstall mnemon-memory` 命令。
- **您的 Fly.io 应用。** 如果您想删除应用，请先使用 `mnemon downgrade local --destroy-fly-app` 命令销毁它 — 这会将远程保险库拉回到本地，因此不会丢失任何记忆。
- **您的 S3 存储桶内容。** mnemon 没有 `sync delete` 命令。
- **claude.ai + Claude 移动版 MCP 条目。** 这些条目存在于您的 Anthropic 账户中。`claude mcp list` 命令会显示它们，并带有 `claude.ai` 前缀。您可以通过 claude.ai 网页 UI 中的设置 → 连接器进行删除。如果 `mnemon uninstall` 检测到其中一个条目，它会显示一个 `⚠ REQUIRED` 项目，引导您到那里。
### 记忆保留矩阵
| 命令 | 本地 `~/.mnemon/default.sqlite` | Fly 卷 | S3 存储桶内容 |
|---|---|---|---|
| `mnemon uninstall` | 已删除（除非使用 `--keep-vault`） | **未触及** | **未触及** |
| `mnemon uninstall --keep-vault` | **未触及** | **未触及** | **未触及** |
| `mnemon downgrade local` | 用 Fly 状态替换（通过 S3 拉取） | 未触及（保持运行） | 未触及 |
| `mnemon downgrade local --destroy-fly-app` | 用 Fly 状态替换 | 已销毁（在数据拉取到本地后） | 未触及 |
| `mnemon upgrade web` | 存档到 `archive/pre-web-<date>.sqlite` | 新创建，从 S3 种子 | 已写入（推送） |
| `mnemon sync push` / `mnemon sync pull` | 读取/写入本地 | — | 读取/写入 |
只要以下任意一个存在（S3 备份、Fly 卷、本地保险库、本地存档），记忆始终可恢复。
### 常见流程
**从头开始在一台机器上测试：**
```bash
mnemon uninstall --yes
pip install -e . # 或：pip install mnemon-memory
mnemon setup
```
**完全停止使用 mnemon：**
```bash
mnemon downgrade local --destroy-fly-app # 拆除 Fly，保留通过 S3 拉取的保险库
mnemon uninstall --yes # 删除本地状态
pip uninstall mnemon-memory # 删除软件包
# 然后手动删除 claude.ai 和 Claude 移动应用中的 mnemon 条目。
# 如果您希望没有残留的记忆数据，请删除您的 S3 存储桶内容。
```
**转移到新机器（保留所有记忆）：**
```bash
# 旧机器：
mnemon sync push
mnemon uninstall --yes
# 新机器：
pip install mnemon-memory
mnemon setup claude-code --remote-url https://<您的应用>.fly.dev/mcp
```
## 安装故障排除
### Intel Mac + Python 3.12：`pip install "mnemon-memory[ui]"` 构建 `llvmlite` / `numba` 失败
`[ui]` 额外依赖项引入了 `umap-learn`，它需要 `numba` + `llvmlite`。从 `numba 0.63` 开始，这些软件包仅为 Apple Silicon（arm64）提供 macOS 轮。在 Intel Mac（x86_64）上，pip 退回到源代码构建，并因 `llvmlite needs CMake tools to build` 而失败。
固定到提供 x86_64 macOS 轮的最后一个版本：
```bash
pip install 'numba==0.62.1' 'llvmlite==0.45.1' 'mnemon-memory[ui]'
```
如果 pip 然后抱怨 NumPy，请在同一命令中添加 `'numpy<2.3'`。
Apple Silicon、Linux 和 Windows 不受影响 — 这些平台上存在预编译轮。
## 开发
```bash
pip install -e ".[dev]"
pytest
```
## 许可证
MIT
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器