github.com/Uranid/mnem @v0.1.7

English  ·  中文  ·  Español

https://github.com/user-attachments/assets/bd744a7e-8e89-4531-bd96-fdee0030c390

1. 问题所在
2. 什么是 mnem
3. 性能基准
4. 与其他工具的比较
5. 安装
6. 快速入门
7. 接入与取消接入
8. 命令
9. MCP 工具
10. Python API
11. GraphRAG
12. 你能获得什么
13. 不适合使用 mnem 的场景
14. 文档
15. 贡献

问题所在

影响对象： 如果你使用 AI 编程助手（Claude Code、Cursor、Gemini CLI 等），或者正在构建需要 AI Agent 在会话间记住信息的软件，mnem 正是为解决这一问题而生。

每个会话都从零开始。

• 会话相互隔离。 在 Claude Code（一款 AI 编程助手）中规划一次迁移。明天打开 Cursor（另一款 AI 编程助手）。那个 Agent 对此一无所知。
• 无法检查的记忆不是真正的记忆。 Agent 的上下文发生了变化，你不知道是什么、何时、为什么。没有日志。
• 约定规则在扁平文件中腐烂。 六个工程师，六份各自悄然发散的 AGENTS.md 文件（许多 AI 工具会自动读取的 Agent 配置文件）。没有合并，没有历史，无法判断哪份是最新的。

你的代码库有 git，你 Agent 的知识却什么都没有。

什么是 mnem

不熟悉 git 或版本控制？ Git 是一种随时间保存文件编号快照的软件，让你可以追踪变更、撤销错误、协同协作。mnem 对 AI Agent 的知识做同样的事：每次写入都是一个可分支、可 diff、可合并或回滚的已保存快照。

AI Agent 知识的 git。 一个持久化、版本化的 AI Agent 知识层，在所有测试基准上达到最佳或并列最佳的召回率（召回率 = 返回正确结果的比例，越高越好）。

知识图谱是一种条目之间可以相互链接的可搜索事实存储，可以把它想象成你的 AI Agent 可以写入和读取的智能笔记本。例如：写入"部署窗口为每周二 UTC 10-11 时"，将其链接到发布检查清单，之后用普通中文询问"我们的部署计划是什么？"即可检索到它。（对于想了解技术术语的人：事实以节点形式存储，通过类型化关系边相连，如 part_of、relates_to、depends_on 等。）

技能、决策和上下文以可查询图谱的形式存储在项目文件夹中。提交 .mnem/ 目录，它就随代码一起移动。用可供整个团队版本化、diff 和合并的东西替换陈旧的 .cursorrules（Cursor 的项目规则文件）和 AGENTS.md 文件。

检索在一次遍历中融合向量搜索（按语义查找结果，而非仅精确词语，如"deploy schedule"能找到"deploy window"）、关键词搜索（精确词语）和图遍历（沿条目间的链接跟踪）。每次查询都精确报告消耗了多少 token 以及过滤掉了什么，不会有任何内容被静默丢弃。单个二进制文件（一个可执行文件），无需运行服务器。一条命令即可接入 Claude Code、Cursor、Gemini CLI 或任何 MCP（Model Context Protocol，为 AI 工具提供外部能力访问的标准）宿主；可从 CLI、HTTP 或 Python 使用。

对于团队： 将 .mnem/ 与代码一同提交，每位队友的 Agent 都从相同的知识基线出发。参见 mnem push / mnem pull 了解 CI 同步方式。

性能基准

在六个公开数据集上与 mem0 和 MemPalace 进行了正面对比测试。mnem 在五个数据集上领先‡†；在 LongMemEval 上与 MemPalace 并列。

方法论、脚注、查询速度与复现步骤

方法论： mem0 数据为我们在相同测试框架下的复现结果，mem0 未在这些数据集上发布 R@K（Recall at top K，即前 K 个结果中正确答案的比例）头条数字。MemPalace 头条数字已在我们的测试框架下交叉验证。这是公开披露，而非隐瞒：可复现的产物与二进制文件一同发布。

默认测试框架嵌入器：MiniLM-L6-v2（ONNX 格式的小型预训练文本模型，ONNX 是 AI 模型的开放文件格式，无需单独安装），各系统使用完全相同的字节。FinanceBench 在所有系统上使用 bge-large 以公平比较（见 † 脚注）。不使用 LLM 重排序。每次运行样本数：LongMemEval 500 问，LoCoMo 完整数据集（约 1986 问），ConvoMem 每类别 50 问，MemBench 每配置 100 问。所有基准测试仅使用密集检索（不含稀疏/BM25 通道）。复现方法：bash benchmarks/harness/run_bench.sh。

^{mem0 列：我们在相同测试框架下的复现结果（mem0 未在这些数据集上发布 R@K 头条数字）。MemPalace 列：公开头条数字，已在我们的测试框架下交叉验证。原始产物：benchmarks/results/v0.1.0/。† FinanceBench 在所有系统上均使用 Ollama bge-large（1024 维）；MemPalace 展示的是最佳配置下的结果（bge-large 直连 ChromaDB）；mem0 在存储前对记忆应用了 LLM 提取。流水线说明：mnem FinanceBench 运行使用了混合检索（--hybrid-boost --query-expand）；MemPalace bge-large 使用纯向量检索，流水线不同。完整方法论：benchmarks/results/analysis/financebench.md。‡ LoCoMo：mnem 使用 MAX-over-turn-hits 会话评分（宽松）；MemPalace 使用逐轮聚合（更严格），分数反映的是不同评估方法。参见 benchmarks/results/analysis/locomo.md。}

查询速度

复现方法

mnem bench fetch longmemeval     # 下载数据集（一次性，264 MB）
mnem bench                       # TUI 界面；交互式选择基准测试
mnem bench run --benches longmemeval --limit 50 --non-interactive
mnem bench results ./bench-out   # 从上次运行的结果重新渲染

# 传统 bash 工具（官方标题数字的标准路径）
bash benchmarks/harness/run_bench.sh

方法论、原始产物、各基准测试详细分类：benchmarks/ 和 docs/src/benchmarks/。

与其他工具的比较

^{✅ 完全支持  ·  ~ 部分或有限支持  ·  ✗ 不支持  ·  n/a 不适用  ·  + 见下方脚注}

| |

mnem |

mem0 |

MemPalace |

Hermes |

Supermemory |

Graphiti |

Letta |

Cognee | |--|:--------:|:--------:|:-------------:|:------------:|:---------------:|:------------:|:---------:|:----------:| | 本地优先 | ✅ | ~ | ✅ | ~ | ✗ | ✗ | ~ | ~ | | 版本化历史 | ✅ | ✗ | ✗ | ✗ | ✗ | ✗ | ~ | ✗ | | 分支与合并 | ✅ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | | 内容寻址存储 ⁺ | ✅ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | | WASM / 边缘 | ✅ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | | 无 API 摄入 | ✅ | ~ | ✅ | ~ | ✗ | ✗ | ✗ | ~ | | Token 预算透明度 | ✅ | ✗ | ✗ | ~ | ✗ | ✗ | ~ | ✗ | | 单一二进制 | ✅ | ✗ | ✗ | ✗ | n/a | ✗ | ✗ | ✗ | | 无外部数据库 | ✅ | ~ | ✗ | ✅ | n/a | ✗ | ✗ | ~ | | 知识图谱 | ✅ | ✗ | ~ | ✗ | ✗ | ✅ | ✗ | ✅ | | 混合检索 | ✅ | ~ | ~ | ✗ | ~ | ✅ | ~ | ~ | | MCP 原生 | ✅ | ~ | ✅ | ✗ | ✅ | ~ | ✅ | ✅ | | 许可证 | Apache-2.0 | Apache-2.0 | MIT | MIT | MIT | Apache-2.0 | Apache-2.0 | Apache-2.0 |

脚注与逐项深度对比

^{+ 内容寻址存储：相同字节始终获得相同 ID；相同事实自动去重  ·  混合检索 此处指向量 + 稀疏 + 图，单次完成  ·  Hermes 是 agent 运行时，并非记忆存储；mnem 作为 MemoryProvider 插件接入，行内仅反映 Hermes 原生记忆能力（受限的 MEMORY.md + FTS5 会话日志）  ·  mem0 v2（2026 年 4 月）从 OSS SDK 移除了图后端  ·  Graphiti 需要 LLM API 密钥 + 图后端（Neo4j / FalkorDB / Kuzu / Neptune）；内置 MCP 服务器  ·  Letta "MCP" = MCP 客户端（Letta agents 调用 MCP 服务器）  ·  MemPalace 默认使用 ChromaDB（后端可插拔）  ·  Supermemory 自托管需要 Cloudflare + Postgres + OpenAI  ·  Cognee 图提取需要 LLM API 密钥；自 v0.3.5 起内置 MCP 服务器  ·  验证：2026-05-19}

深度对比：

• mnem vs mem0 - agent 记忆层，OSS 领导者
• mnem vs MemPalace - 基准对标
• mnem vs Hermes - agent 运行时；mnem 作为记忆层接入
• mnem vs Supermemory - 云托管记忆服务
• mnem vs Graphiti - AI 编码助手知识图谱工具
• mnem vs Letta - agent 记忆框架（原 MemGPT）
• mnem vs Cognee - 面向 agent 的 KG 替代方案

完整矩阵：docs/src/comparisons/README.md。

安装

选择一种（如果你有 Python，推荐使用 pip）：

pip (Python) - 推荐 · 预构建二进制，内置嵌入器，即装即用

还没有 pip？

安装 Python（免费；pip 随 Python 3.4+ 一同提供）。可通过 python --version 验证。

pip install mnem-cli

想用 Python 从自己的应用调用 mnem？ pip install mnem-cli 给你提供的是 mnem 命令行工具。如果要在 Python 代码中导入 mnem（import pymnem），请改用 pip install mnem-py，参见 Python API。

npm (Node.js) · 预构建二进制，内置嵌入器，即装即用

还没有 npm？

安装 Node.js（免费；npm 已内置，需要 Node 18+）。可通过 node --version 验证。

npm install -g mnem-cli

Cargo (Rust) · 从源码编译，首次运行约需 5-15 分钟

还没有 Cargo？

通过 rustup 安装（免费；同时安装 rustc）。可通过 cargo --version 验证。

# Linux 专属：sudo apt-get install g++ (Debian/Ubuntu/WSL)  或  sudo dnf install gcc-c++ (Fedora/RHEL)
cargo install --locked mnem-cli --features bundled-embedder

从源码构建 · 未发布的 main 分支，适用于本地修改或预发布提交

何时使用此方式而非 cargo install

如果你需要尚未发布到 crates.io 的提交，或者正在进行本地修改，请使用此方式。否则推荐使用上面的已发布 crate 路径。需要 Rust 1.95+（如有需要：rustup install 1.95 && rustup default 1.95）。

# Linux 专属：sudo apt-get install g++ (Debian/Ubuntu/WSL)  或  sudo dnf install gcc-c++ (Fedora/RHEL)
git clone https://github.com/Uranid/mnem
cd mnem
cargo install --path crates/mnem-cli --features bundled-embedder

Docker · 运行 HTTP 服务器，无需本地安装

docker run --rm -p 9876:9876 -e MNEM_HTTP_ALLOW_NON_LOOPBACK=1 \
  ghcr.io/uranid/mnem:latest http --bind 0.0.0.0:9876

mnem --version    # 确认安装成功
mnem doctor       # 检测嵌入器、存储和配置，输出绿/黄/红状态清单

如果提示 mnem: command not found： 先尝试打开新终端（PATH 变更只对新会话生效）。在 Linux 上，pip 安装路径为 ~/.local/bin，如果该路径不在 PATH 中，运行 export PATH="$HOME/.local/bin:$PATH"，然后将该行添加到 ~/.bashrc（一次性修复，文件修改后永久生效）。在 Windows 上：1. 运行 pip show mnem-cli。2. 复制 Location 值（如 C:\Users\you\AppData\Roaming\Python\Python312\site-packages）。3. 将 site-packages 替换为 Scripts 得到 Scripts 文件夹路径。4. 打开系统属性 - 环境变量 - Path - 编辑 - 新建 - 粘贴 Scripts 路径 - 确定。5. 打开新的命令提示符（PATH 变更需要新窗口才能生效）。

[!NOTE] --locked 固定经过测试的精确依赖版本。--features bundled-embedder 将嵌入器（约 40 MB）打包进二进制文件，使 mnem retrieve 即刻可用，无需额外配置。此标志仅适用于 Cargo；pip 和 npm 已预置内置嵌入器。如不使用该标志（且未在 config.toml 中配置其他提供商），mnem retrieve 会报错"embedder not configured"。

完整安装矩阵：docs/src/install.md。

想将 mnem 嵌入 Python 应用？ 上面的 pip install mnem-cli 以 wheel 形式发布的是 CLI 二进制文件。原生 Python API（import pymnem）位于独立的包中。请跳转至 Python API (mnem-py) ↓，查看 pip install mnem-py 的安装方式和代码示例。

快速入门

第一步：立即体验（独立运行，无需 AI 助手）

mkdir my-graph
cd my-graph
mnem init          # 每个项目只需运行一次 - 创建存储知识图谱的 .mnem/ 文件夹
mnem ingest --text "mnem is a versioned knowledge graph for AI agents"
mnem retrieve "what does mnem do"

每个项目在使用 mnem ingest 或 mnem retrieve 之前，必须先运行一次 mnem init，它会创建存储图谱的 .mnem/ 文件夹。如果出现问题，运行 mnem doctor。

预期输出：

[1] score=0.94  mnem is a versioned knowledge graph for AI agents
    tokens_used=12  candidates_seen=1  dropped=0

第二步（可选）：接入你的 AI 助手

前提条件： 此示例使用 Claude Code。没有的话？在 claude.ai/code 免费下载。没有 Agent？跳过第二步，mnem retrieve 可独立使用。

工作目录： 接入后，请从 my-graph/（或其子目录）打开 Claude Code。从其他文件夹启动意味着它找不到这个图谱。

# 第一个会话：添加事实并接入 Agent
mnem init     # 如果第一步已运行可跳过
mnem ingest --text "The API retry policy uses exponential backoff with a 3-attempt limit"
mnem integrate claude-code    # Cursor：使用 `mnem integrate cursor`

# 第二个会话（第二天，新终端）：记忆持续存在
cd my-graph
mnem retrieve "what is our API retry policy"

mnem integrate 完成后，关闭并重新打开应用程序（不仅仅是终端）。验证方法：打开任意会话并发送消息，Claude 回复之前你应该能看到 mnem: N item(s) 作为系统消息出现在对话顶部。0 item(s) 表示图谱为空，但接入是正常工作的。

本地图谱与全局图谱： 项目目录中的 .mnem/ 存储项目专属记忆。~/.mnemglobal/.mnem/（全局图谱，其中 ~ 表示主目录，Windows 上为 C:\Users\you，Linux/macOS 上为 /home/you）存储跨所有项目的事实：个人偏好、团队共享约定、跨仓库实体等。使用 mnem global retrieve 和 mnem global add 来操作它。

下一步： - 摄入文件：mnem ingest README.md（或 mnem ingest your-docs/ --recursive 摄入整个目录） - 接入 AI 助手：mnem integrate（支持 Claude Code、Cursor 等） - 随意提问：mnem retrieve "你的问题"

五分钟从零上手。完整演练参见 docs/src/quickstart.md。

mnem integrate - 接入任何 Agent 宿主

不使用 Claude Code、Cursor 或其他 AI 编程助手？ 跳过此节，mnem integrate 只在你希望这些工具自动使用 mnem 时才需要。

Claude Code、Cursor 等工具必须已安装。 mnem integrate 会检测哪些工具已存在，先运行 mnem integrate --check 查看检测到的工具。

一条命令将 mnem 接入你的 Agent 宿主。对于支持 MCP 的宿主，它添加 MCP 服务器（mnem_retrieve 和 mnem_commit 等工具）、在支持钩子的宿主上添加自动检索触发器，以及在拥有规则文件的宿主上添加 mnem 系统提示。Hermes Agent 在设计上是纯钩子接入：mnem integrate hermes 写入 Hermes 的 pre_llm_call / post_llm_call 钩子，将检索到的记忆作为 +1 上下文层添加并持久化当前会话轮次，不修改 Hermes 的系统提示。重启宿主（将 Claude Code、Cursor、Hermes 等作为应用程序完全关闭并重新启动，而不仅仅是终端），Agent 即开始自动使用 mnem。验证方法：打开新会话并发送任意消息，你应该能看到检索到的 mnem 上下文在模型回答之前注入。0 item(s) 没问题，表示图谱为空，接入是正常工作的。

故障排除： 没有看到 mnem: N item(s)？ - 确保你已完全关闭并重新打开应用程序（不仅仅是终端），即完全关闭 Claude Code 或 Cursor 窗口并重新启动它 - 从包含 .mnem/ 文件夹的目录（或其子目录）内打开应用程序，从其他文件夹打开 Claude Code 则找不到那个项目的图谱 - 运行 mnem doctor 检查嵌入器和存储是否正常 - 运行 mnem integrate --check 确认宿主是否正确接入

mnem integrate                           # 交互式：检测已安装的宿主并提示选择
mnem integrate claude-code               # 接入指定宿主，跳过交互式检测
mnem integrate hermes                    # 仅接入 Hermes 的 pre/post LLM 钩子
mnem integrate --all                     # 无需提示，接入所有检测到的宿主

mnem integrate --check                   # 报告所有宿主的接入状态；不做任何修改
mnem integrate --dry-run                 # 预览将写入的内容，不实际修改任何文件
mnem integrate --show claude-code        # 打印 MCP JSON 块，供手动复制粘贴

mnem integrate --no-hooks                # 跳过 UserPromptSubmit 钩子接入
mnem integrate --no-system-prompt        # 跳过系统提示接入
mnem integrate --target-repo ~/notes     # 将 MCP 服务器指向指定图谱而非全局图谱

接入内容： - MCP 服务器（mcpServers.mnem）- 支持 MCP 的宿主通过 mnem mcp --repo <graph> 获得完整的 mnem 工具访问权限；默认指向全局图谱（~/.mnemglobal/.mnem） - 自动检索触发器 - Claude Code 获得 UserPromptSubmit 钩子；Hermes Agent 获得在 $HERMES_HOME/config.yaml 中配置的 pre_llm_call / `post_l