mnem：给 AI Agent 装上"持久记忆"的 Git

场景切入： 你花了两天时间让 Claude Code 帮你在微服务架构上实现了一套熔断机制，告诉它所有服务间的超时策略、fallback 逻辑、具体负责人。第三天换到 Cursor 继续开发——你发现新来的 Agent 对那套熔断逻辑一无所知，它甚至不知道有这回事。更糟糕的是，你自己也记不清当时具体怎么约定的了。

这就是今天 AI Agent 开发者的日常困境：会话之间没有记忆，工具之间没有共识，知识在聊天窗口里产生，也在聊天窗口里消失。

mnem 想要解决的，就是这个问题。

---

1. 项目起源：Agent 记忆层的需求觉醒

mnem 的诞生源于一个非常具体的痛点——AI 编程助手（Claude Code、Cursor、Gemini CLI 等）在每次新会话开始时"失忆"。代码库有 Git 版本控制，而 Agent 的知识、决策、团队约定却没有任何持久化手段。

项目由 Uranid 团队开发，当前版本 v0.1.7，采用 Apache-2.0 开源许可。Stars 142，Forks 34。作为 Rust 语言实现的本地优先（local-first）工具，它的核心哲学是：不需要网络、不需要云端、不需要账户，一条命令就能在任何机器上跑起来。

项目的技术定位介于知识图谱工具（Graphiti、Letta）和轻量记忆 SDK（mem0）之间——比前者更简单（无需 Neo4j 等外部图数据库），比后者更强大（支持版本化历史和分支合并）。

---

2. 核心能力：从"文件摄入"到"知识图谱"全自动

mnem 的设计思路非常清晰：把知识当作代码来管理。

当你把一个目录丢进 mnem 时，它会自动完成以下工作：识别文件类型 → 按语义分块 → 提取实体和关系 → 构建知识图谱。所有这些都在摄入时完成，不调用任何 LLM API——也就是说，相同文件每次摄入的结果完全一致，重新摄入未修改文件是零操作。

文件格式支持极为广泛，README 文档提到支持 30 余种类型：Markdown 按标题层级分块，代码文件按函数/类粒度解析，PDF 用滑动窗口提取文本。摄取结果以节点（Node）和类型化边（Typed Edge）的形式存储在项目 .mnem/ 目录中。

知识图谱不是扁平的结构——每个节点都有 UUID、标签（label）、内容摘要（summary）和出边列表。这使得检索时可以沿着边的类型进行多跳遍历，比如找到"Alice"节点后，沿 reports_to 边继续找到她的上级，再沿同一条边找到上级的上级。

---

3. 混合检索：向量 + 关键词 + 图遍历，一次完成

mnem 的检索引擎是一个三层融合架构：

第一层：密集向量通道。 每个节点在摄入时通过嵌入模型生成向量，默认使用 MiniLM-L6-v2（ONNX 格式，无需额外安装）。如果想使用更强的嵌入模型（bge-large、OpenAI、Cohere），一行配置即可切换。

第二层：稀疏关键词通道（BM25 + SPLADE）。 通过 config.toml 启用后，与向量结果按一定比例融合，对专有名词和精确匹配的场景特别有效。

第三层：图遍历通道。 开启 --graph-expand 后，检索会沿着有类型的边向外扩展 N 跳（推荐 --graph-expand 20），从而聚合跨多个相关文档的知识片段。

三种通道的融合结果是确定性的——返回什么、跳过什么、消耗了多少 token，都通过 tokens_used / candidates_seen / dropped 字段精确报告。这是 mnem 区别于大多数竞品的核心差异：不会有任何内容被静默截断。

基准测试数据非常亮眼：项目在 LongMemEval、LoCoMo、ConvoMem、MemBench、FinanceBench 五个公开数据集上取得了领先或并列第一的成绩，复现脚本和原始数据均随仓库发布。

图1：mnem 与 mem0、MemPalace 在六个公开基准测试上的对比（五个领先）

---

4. Git 语义：分支、合并、回滚、版本化历史

这是 mnem 最独特的部分——它将 Git 的版本控制语义完整地移植到了知识图谱层面。

每次 mnem ingest 或 mnem commit 都会产生一个不可变提交（commit），包含节点变更和元数据（作者、agent_id、task_id）。提交通过内容寻址（Content Addressing）生成唯一 CID——相同字节总是获得相同 ID，跨机器、跨会话自动去重。

在此基础上，mnem 实现了完整的分支语义：mnem branch 创建分支、mnem merge 合并分支、mnem diff 对比差异、mnem revert 回滚提交。撤销某条知识（"遗忘"）不是简单删除，而是通过墓碑机制（tombstone）软删除——从检索结果中过滤，但完整审计轨迹仍然保留。

对于团队协作场景，mnem remote add + mnem push/pull 支持与远端同步全局图谱，格式是标准 CAR v1 归档——可在任意平台、任意机器上导入，不依赖特定数据库或云服务。

---

5. 多宿主接入：MCP 原生，Claude Code / Cursor / Hermes 即插即用

mnem 不只是一个 CLI 工具，它同时是 MCP 服务器、HTTP JSON API 和 Python 库，底层是同一套 Rust 检索引擎。

通过 mnem integrate claude-code（或 cursor / gemini / hermes），一条命令完成三项接入：添加 MCP 服务器（22 个原生工具）、注册自动检索触发器、写入系统提示。接入后，Claude Code 每次响应前会自动调用 mnem_retrieve 注入相关记忆，无需人工干预。

MCP 工具集覆盖完整生命周期：检索类（mnem_retrieve、mnem_global_retrieve、mnem_search）、写入类（mnem_commit、mnem_commit_relation、mnem_ingest）、删除类（mnem_tombstone_node 软删除 / mnem_delete_node 硬删除）、内省类（mnem_stats、mnem_schema、mnem_recent）。每个工具响应都附带 _meta 字段（bytes、latency_micros、tokens_estimate），便于 Agent 自测成本。

Python 开发者则可以通过 pip install mnem-py 直接调用：写入节点、生成嵌入、检索——完全无需启动子进程，相同的检索引擎无缝嵌入应用。

图2：检索速度对比（mnem 在准确率和速度上均表现优异）

---

6. 部署体验：单二进制、零配置、完全离线

mnem 的部署体验在同类工具中属于顶级：单个约 40 MB 的 Rust 编译二进制，内置 MiniLM-L6-v2 ONNX 嵌入模型，无需安装任何运行时依赖。

安装方式任选其一：cargo install --locked mnem-cli --features bundled-embedder（Rust 编译，推荐）、pip install mnem-cli（预构建 wheel）、npm install -g mnem-cli（预构建 Node.js 包）。Docker 部署一行命令：

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

Dockerfile 采用多阶段构建（BuildKit 语法），最终镜像约 40 MB（不含 ONNX 嵌入器）；通过 --build-arg FEATURES="bundled-embedder" 可启用内置嵌入器，镜像体积增加约 18 MB。docker-compose.yml 提供了 mnem-http + Ollama 的完整本地开发栈，可用于基准测试复现。

部署硬件需求极低：GPU 不必需，RAM 仅需 512 MB，磁盘 100 MB——普通开发笔记本即可运行。

---

7. 局限与思考：不适合的场景，以及 v0.1.0 的成熟度

mnem 明确标注了三个不适合的场景：

第一，不适合事务性 OLTP 系统。 mnem 是仅追加的版本化历史，目标是知识检索而非事务处理——支付账本、库存系统这类需要行级 UPDATE/DELETE 的场景不适用。

第二，不适合 10k+ QPS 的云规模场景。 项目明确表示本地优先，多区域分片检索在路线图上，v1 阶段尚未提供。并发多写者场景下，redb 后端是单写者锁（ACID 保证），第二个写操作会阻塞而非自动合并。

第三，Python API v0.1.0 功能受限。 当前 mnem-py 仅支持密集向量检索，BM25 关键词搜索和图遍历需要通过 CLI 或 HTTP API 调用。这是一个已知的产品路线问题。

总体而言，mnem 是一个工程完成度极高的本地优先 Agent 记忆基础设施。它在检索性能、版本化语义、多宿主接入三个维度上实现了竞品难以同时兼顾的平衡——比 mem0 更强大（有图有版本），比 Graphiti 更轻量（无外部数据库），比 Letta/MemPalace 更开放（单二进制、离线运行）。

---

技术速览

维度	详情
语言 / 架构	Rust 1.95，16 个 workspace crates 模块化设计
核心 crates	mnem-core（检索引擎）、mnem-ingest（解析分块）、mnem-ann（HNSW 近似最近邻）、mnem-backend-redb（嵌入式 ACID 存储）
嵌入模型	内置 MiniLM-L6-v2（ONNX），支持 Ollama / OpenAI / Cohere 热切换
存储格式	内容寻址 CAR v1，可跨平台迁移，无厂商绑定
MCP 工具数	22 个原生工具（稳定 21 + 功能门控 1）
License	Apache-2.0
平台支持	Linux / macOS / Windows / WASM（浏览器 + Lambda）
测试基准	6 个公开数据集，全部提供复现脚本和数据

mnem 代表了一种正在兴起的 AI Infra 趋势：在 Agent 运行时层面，将"记忆"作为一等公民，赋予它版本、分支、审计和跨工具共享的能力。如果你在构建任何需要 Agent 在会话间保持一致性的系统，mnem 是目前最值得评估的技术选型之一。