mnemon-memory-mcp

# mnemon-mcp [](https://github.com/nikitacometa/mnemon-mcp/actions/workflows/ci.yml) [](https://www.npmjs.com/package/mnemon-mcp) [](https://nodejs.org/) [](LICENSE) **适用于AI代理的持久化分层记忆。** 本地优先，无云服务，单个SQLite文件。 [主页](https://aisatisfy.me/mnemon/) · [npm](https://www.npmjs.com/package/mnemon-mcp) · [GitHub](https://github.com/nikitacometa/mnemon-mcp) 您的AI代理每次会话后都会忘记所有内容。Mnemon解决了这个问题。 它为任何兼容[MCP](https://modelcontextprotocol.io)的客户端（如OpenClaw、Claude Code、Cursor、Windsurf或您自己的客户端）提供了一个结构化的长期记忆，支持单个SQLite数据库，无需API密钥、无云服务、无遥测。只需`npm install`，您的代理就有记忆了。 <p align="center"> <img src="demo/mnemon-demo.gif" alt="mnemon-mcp demo — memory_add, memory_search, memory_inspect, memory_update" width="800"> </p> --- ## 为什么需要分层记忆？ 扁平的键值存储会将“昨天发生的事情”和“从未提交测试”视为相同 - 这是错误的 - 不同的知识具有不同的生命周期和访问模式。 Mnemon将记忆组织成**四个层级**: | 层级 | 存储内容 | 访问方式 | 生命周期 | |-------|---------------|-------------------|----------| | **情景记忆** | 事件、会话、日志条目 | 按日期或时间段 | 衰减（30天半衰期） | | **语义记忆** | 事实、偏好、关系 | 按主题或实体 | 稳定 | | **过程记忆** | 规则、工作流程、约定 | 启动时加载 | 很少更改 | | **资源记忆** | 参考资料、笔记 | 按需加载 | 缓慢衰减（90天） | 日记条目和编码规则生活在不同的层级中，因为它们应该如此。 ## 快速入门 ### 安装 ```bash npm install -g mnemon-mcp ``` 或从源代码安装： ```bash git clone https://github.com/nikitacometa/mnemon-mcp.git cd mnemon-mcp && npm install && npm run build ``` ### 配置您的MCP客户端 <details open> <summary><strong>OpenClaw</strong></summary> ```bash openclaw mcp register mnemon-mcp --command="mnemon-mcp" ``` 或添加到 `~/.openclaw/mcp_config.json`： ```json { "mnemon-mcp": { "command": "mnemon-mcp" } } ``` </details> <details> <summary><strong>Claude Code</strong></summary> 添加到 `~/.claude/mcp.json`： ```json { "mcpServers": { "mnemon-mcp": { "command": "mnemon-mcp" } } } ``` </details> <details> <summary><strong>Cursor / Windsurf / 其他MCP客户端</strong></summary> 将以下内容添加到您的客户端的MCP配置中： ```json { "mcpServers": { "mnemon-mcp": { "command": "mnemon-mcp" } } } ``` </details> <details> <summary><strong>从源代码运行？</strong></summary> 使用编译入口点的完整路径： ```json { "mnemon-mcp": { "command": "node", "args": ["/absolute/path/to/mnemon-mcp/dist/index.js"] } } ``` </details> ### 验证 ```bash echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | mnemon-mcp ``` 您应该在响应中看到10个工具。数据库（`~/.mnemon-mcp/memory.db`）将在首次运行时自动创建。 就这样。您的代理现在具有持久的记忆。 ## 它能做什么 ### 10个MCP工具 | 工具 | 功能 | |------|-------------| | **`memory_add`** | 存储具有层级、实体、置信度、重要性和可选TTL的记忆 | | **`memory_search`** | 全文或精确搜索，支持按层级、实体、日期、范围和置信度过滤 | | **`memory_update`** | 原地更新或创建版本替换（继承链） | | **`memory_delete`** | 删除记忆；如果有前任，则重新激活 | | **`memory_inspect`** | 获取层级统计信息或跟踪单个记忆的版本历史 | | **`memory_export`** | 导出为JSON、Markdown或Claude-md格式，支持过滤 | | **`memory_health`** | 运行诊断：过期条目、孤立链、陈旧记忆；可选GC | | **`memory_session_start`** | 开始代理会话 - 返回会话ID用于分组记忆 | | **`memory_session_end`** | 结束会话，可选摘要；返回持续时间和记忆数量 | | **`memory_session_list`** | 列出会话，支持按客户端、项目或活动状态过滤 | ### MCP资源和提示 **资源** - 代理可以读取的实时数据： | URI | 返回 | |-----|---------| | `memory://stats` | 按层级聚合统计信息 | | `memory://recent` | 最近24小时内创建/更新的记忆 | | `memory://layer/{layer}` | 层级中的所有活跃记忆 | | `memory://entity/{name}` | 关于实体的所有活跃记忆 | **提示** - 预构建的工作流程： | 提示 | 目的 | |--------|---------| | `recall` | “告诉我关于X的一切” | | `context-load` | 在开始任务前加载相关上下文 | | `journal` | 创建结构化日记条目 | ## 搜索 四种模式，均支持层级/实体/范围/日期/置信度过滤： **全文搜索模式**（默认不带嵌入）- 使用BM25排名的词化全文搜索。多词查询使用AND；如果结果太少，OR补充并带有分数惩罚。渐进AND放松尝试前3个最具体的术语，然后回退到完整的OR。 **混合模式**（默认启用嵌入）- 结合FTS5和向量搜索，通过[互惠排名融合](https://www.singlestore.com/blog/hybrid-search-using-reciprocal-rank-fusion-in-sql/)。检测查询中的引号实体（例如`'Essentialism'`），并运行加权子查询进行交叉引用检索。 **向量模式** - 基于嵌入的纯余弦相似度搜索。 **精确模式** - `LIKE`子字符串匹配，用于精确短语查找。 分数：`bm25 × (0.3 + 0.7 × importance) × decay(layer) × recency` 最近度提升：`1 / (1 + daysSince / 365)` - 温和地奖励最近创建的记忆而不惩罚旧记忆。 ### 词干提取 在**索引时**和**查询时**为英语和俄语应用雪球词干提取器。这意味着`"running"`与`"runs"`匹配，而`"книги"`与`"книга"`匹配。从查询中过滤停止词以提高精度。 ## 事实版本控制 知识不断演变。Mnemon不会删除旧事实 - 它会链接它们： ``` v1: "团队使用React 17" → superseded_by: v2 v2: "团队使用React 19" → supersedes: v1（活跃） ``` 搜索仅返回最新版本。`memory_inspect`带有`include_history: true`显示完整链。`memory_delete`重新激活前任 - 没有任何损失。 ## 向量搜索（可选，自带密钥） 通过提供自己的嵌入式API启用语义相似性搜索： ```bash # OpenAI MNEMON_EMBEDDING_PROVIDER=openai MNEMON_EMBEDDING_API_KEY=sk-... mnemon-mcp # Ollama（本地，免费） MNEMON_EMBEDDING_PROVIDER=ollama mnemon-mcp ``` 这解锁了另外两种搜索模式： - **`mode: "vector"`** - 纯余弦相似度搜索 - **`mode: "hybrid"`** - FTS5 + 向量通过[互惠排名融合](https://www.singlestore.com/blog/hybrid-search-using-reciprocal-rank-fusion-in-sql/)组合 需要`sqlite-vec`（作为可选依赖安装）。新记忆在添加时嵌入；现有记忆可以回填。 <details> <summary>嵌入式配置</summary> | 变量 | 默认值 | 描述 | |----------|---------|-------------| | `MNEMON_EMBEDDING_PROVIDER` | - | `openai`或`ollama`（未设置=禁用） | | `MNEMON_EMBEDDING_API_KEY` | - | API密钥（OpenAI必填） | | `MNEMON_EMBEDDING_MODEL` | `text-embedding-3-small` / `nomic-embed-text` | 模型名称 | | `MNEMON_EMBEDDING_DIMENSIONS` | `1024` / `768` | 向量维度 | | `MNEMON_OLLAMA_URL` | `http://localhost:11434` | Ollama端点 | </details> ## 导入知识库 有Markdown文件目录？批量导入： ```bash cp config.example.json ~/.mnemon-mcp/config.json # 先编辑此文件 npm run import:kb -- --kb-path /path/to/your/kb # 增量（跳过未更改的文件） ``` 配置文件将glob模式映射到记忆层级： ```json { "owner_name": "your-name", "extra_stop_words": [], "mappings": [ { "glob": "journal/*.md", "layer": "episodic", "entity_type": "user", "entity_name": "$owner", "importance": 0.6, "split": "h2" }, { "glob": "people/*.md", "layer": "semantic", "entity_type": "person", "entity_name": "from-heading", "importance": 0.8, "split": "h3" } ] } ``` ### 配置字段 | 字段 | 类型 | 描述 | |-------|------|-------------| | `owner_name` | 字符串 | 您的名字 - 用于`$owner`在`entity_name`中的替换 | | `extra_stop_words` | 字符串[] | 从FTS查询中过滤的单词（例如，您的名字形式） | | `glob` | 字符串 | 要匹配的文件模式 | | `layer` | 字符串 | 目标记忆层级 | | `entity_type` | 字符串 | `user` / `project` / `person` / `concept` / `file` / `rule` / `tool` | | `entity_name` | 字符串 | 字面名称，`"$owner"`或`"from-heading"`（从H2/H3提取） | | `split` | 字符串 | `"whole"`（一个文件一个记忆），`"h2"`或`"h3"`（按标题分割） | | `importance` | 数字 | 0.0-1.0，影响搜索排名 | | `confidence` | 数字 | 0.0-1.0，可在搜索中过滤 | | `scope` | 字符串 | 可选命名空间 | ## HTTP传输 适用于远程或多客户端设置： ```bash MNEMON_AUTH_TOKEN=your-secret MNEMON_PORT=3000 npm run start:http ``` | 端点 | 描述 | |----------|-------------| | `POST /mcp` | MCP JSON-RPC（Bearer认证，如果设置了令牌） | | `GET /health` | `{"status":"ok","version":"..."}` | 速率限制（默认每分钟100个请求/ IP）- CORS头，1MB正文限制，时间安全认证，SIGTERM时正常关闭。 ## 配置参考 | 变量 | 默认值 | 描述 | |----------|---------|-------------| | `MNEMON_DB_PATH` | `~/.mnemon-mcp/memory.db` | 数据库路径 | | `MNEMON_KB_PATH` | `.` | 知识库导入的根目录 | | `MNEMON_CONFIG_PATH` | `~/.mnemon-mcp/config.json` | 导入配置路径 | | `MNEMON_AUTH_TOKEN` | - | Bearer令牌，用于HTTP传输 | | `MNEMON_PORT` | `3000` | HTTP传输端口 | | `MNEMON_CORS_ORIGIN` | `*` | CORS `Access-Control-Allow-Origin` | | `MNEMON_RATE_LIMIT` | `100` | 每分钟最大请求数/ IP（0 = 关闭） | ## 工具参考 <details> <summary><code>memory_add</code> - 完整参数列表</summary> | 参数 | 类型 | 必需 | 描述 | |-----------|------|----------|-------------| | `content` | 字符串 | 是 | 记忆文本（最大100K字符） | | `layer` | 字符串 | 是 | `episodic` / `semantic` / `procedural` / `resource` | | `title` | 字符串 | 否 | 短标题（最大500个字符） | | `entity_type` | 字符串 | 否 | `user` / `project` / `person` / `concept` / `file` / `rule` / `tool` | | `entity_name` | 字符串 | 否 | 实体名称，用于过滤 | | `confidence` | 数字 | 否 | 0.0-1.0（默认0.8） | | `importance` | 数字 | 否 | 0.0-1.0（默认0.5） | | `scope` | 字符串 | 否 | 命名空间（默认`global`） | | `source_file` | 字符串 | 否 | 源文件路径 - 触发匹配条目的自动替换 | | `ttl_days` | 数字 | 否 | 自动过期后N天 | | `valid_from` / `valid_until` | 字符串 | 否 | 时间事实窗口（ISO 8601） | </details> <details> <summary><code>memory_search</code> - 完整参数列表</summary> | 参数 | 类型 | 必需 | 描述 | |-----------|------|----------|-------------| | `query` | 字符串 | 是 | 搜索文本 | | `mode` | 字符串 | 否 | `fts`（默认），`exact`，`vector`，`hybrid` | | `layers` | 字符串[] | 否 | 按层级过滤 | | `entity_name` | 字符串 | 否 | 按实体过滤（支持别名） | | `scope` | 字符串 | 否 | 按范围过滤 | | `date_from` / `date_to` | 字符串 | 否 | 日期范围（ISO 8601） | | `as_of` | 字符串 | 否 | 时间事实过滤器 - 此时生效的事实 | | `min_confidence` | 数字 | 否 | 最小置信度 | | `min_importance` | 数字 | 否 | 最小重要性 | | `limit` | 数字 | 否 | 最大结果数（默认10，最大100） | | `offset` | 数字 | 否 | 分页偏移量 | </details> <details> <summary><code>memory_update</code> - 完整参数列表</summary> | 参数 | 是否 | 内存ID | | `content` | 字符串 | 否 | 新内容 | | `title` | 字符串 | 否 | 新标题 | | `confidence` | 数字 | 否 | 新置信度 | | `importance` | 数字 | 否 | 新重要性 | | `supersede` | 布尔值 | 否 | `true` = 版本替换；`false`（默认）= 原地修改 | | `new_content` | 字符串 | 否 | 替换条目的内容 | </details> <details> <summary><code>memory_delete</code></summary> | 参数 | 类型 | 必需 | 描述 | |-----------|------|----------|-------------| | `id` | 字符串 | 是 | 记忆ID。如果是继承链的一部分，则重新激活前任。 | </details> <details> <summary><code>memory_inspect</code></summary> | 参数 | 类型 | 必需 | 描述 | |-----------|------|----------|-------------| | `id` | 字符串 | 否 | 记忆ID（省略聚合统计信息） | | `layer` | 字符串 | 否 | 按层级过滤统计信息 | | `entity_name` | 字符串 | 否 | 按实体过滤统计信息 | | `include_history` | 布尔值 | 否 | 显示继承链 | </details> <details> <summary><code>memory_export</code></summary> | 参数 | 类型 | 必需 | 描述 | |-----------|------|----------|-------------| | `format` | 字符串 | 是 | `json` / `markdown` / `claude-md` | | `layers` | 字符串[] | 否 | 按层级过滤 | | `scope` | 字符串 | 否 | 按范围过滤 | | `date_from` / `date_to` | 字符串 | 否 | 日期范围 | | `limit` | 数字 | 否 | 最大条目数（默认全部，最大10K） | </details> <details> <summary><code>memory_health</code></summary> | 参数 | 类型 | 必需 | 描述 | |-----------|------|----------|-------------| | `cleanup` | 布尔值 | 否 | `true` = 回收过期条目（默认：仅报告） | 返回：状态（`healthy` / `warning` / `degraded`），按层级统计，过期条目，孤立链，过期/低置信度计数，清理计数（`cleanup=true`）。 </details> <details> <summary><code>memory_session_start</code></summary> | 参数 | 类型 | 必需 | 描述 | |-----------|------|----------|-------------| | `client` | 字符串 | 是 | 客户端标识符（例如`claude-code`，`cursor`，`api`） | | `project` | 字符串 | 否 | 会话作用域 | | `meta` | 对象 | 否 | 附加会话元数据 | 返回：`id`（会话UUID），`started_at`（ISO 8601）。 </details> <details> <summary><code>memory_session_end</code></summary> | 参数 | 类型 | 必需 | 描述 | |-----------|------|----------|-------------| | `id` | 字符串 | 是 | 要结束的会话ID | | `summary` | 字符串 | 否 | 总结（最大10K字符） | 返回：`id`，`ended_at`，`duration_minutes`，`memories_count`。 </details> <details> <summary><code>memory_session_list</code></summary> | 参数 | 类型 | 必需 | 描述 | |-----------|------|----------|-------------| | `limit` | 数字 | 否 | 最大会话数（默认20，最大100） | | `client` | 字符串 | 否 | 按客户端过滤 | | `project` | 字符串 | 否 | 按项目过滤 | | `active_only` | 布尔值 | 否 | 仅返回未结束的会话（默认否） | 返回：会话数组，包含`id`，`client`，`project`，`started_at`，`ended_at`，`summary`，`memories_count`。 </details> ## 比较 | | **mnemon-mcp** | mem0 | basic-memory | Engram | Anthropic KG | |---|---|---|---|---|---| | **架构** | SQLite FTS5 + 向量 | 云API + Qdrant | Markdown + 向量 | SQLite FTS5 | JSON文件 | | **记忆结构** | 4种类型层级 | 平面 | 平面 | 平面 + 会话 | 图 | | **搜索** | FTS5 + 混合RRF | 语义 | 混合 | FTS5 | 精确 | | **事实版本控制** | 继承链 | 部分 | 否 | 否 | 否 | | **词干提取** | 英语 + 俄语（Snowball） | 仅英语 | 仅英语 | 无 | 无 | | **嵌入式** | 自带密钥（OpenAI / Ollama） | 内置 | FastEmbed | 无 | 无 | | **依赖项** | 0 个必需 | Qdrant，Neo4j | Python 3.12 | Go二进制文件 | 无 | | **云服务需求** | 否 | 是 | 否 | 否 | 否 | | **成本** | 免费 | $19-249/月 | 免费 | 免费 | 免费 | | **设置** | `npm install -g` | Docker + API密钥 | pip + 依赖项 | Go安装 | 内置 | | **许可证** | MIT | Apache 2.0 | AGPL | MIT | MIT | ## 开发 ```bash npm run dev # 使用tsx运行（无需构建步骤） npm run build # TypeScript → dist/ npm test # vitest（229个测试） npm run bench # 性能基准测试 npm run db:backup # 备份数据库 ``` **技术栈：**TypeScript 5.9（严格模式），better-sqlite3，@modelcontextprotocol/sdk，Snowball词干提取器，Zod，vitest。 查看 [CONTRIBUTING.md](CONTRIBUTING.md) 获取代码指南。 ## 设计原则 - **独立运行** - 零网络调用，零遥测。您的记忆保留在您的机器上。 - **单个文件** - 一个SQLite数据库，零操作，文件复制即可备份。 - **确定性搜索** - FTS5，而非嵌入式，是默认的。可解释，可重现，无需GPU。 - **结构化优于平面** - 层级编码访问模式；继承链编码时间。 - **最小化** - 4个生产依赖项。在Node运行的任何地方都适用。 ## 许可证 [MIT](LICENSE)