Mnemon — Persistent Layered Memory for AI Agents

mnemon-mcp

为 AI Agent 提供持久化的分层记忆。 本地优先。零云端。单个 SQLite 文件。

落地页 · npm · GitHub

你的 AI Agent 每次会话结束后都会忘记一切。Mnemon 解决了这个问题。

它为任何兼容 MCP 的客户端——OpenClaw、Claude Code、Cursor、Windsurf 或你自己的客户端——提供由你机器上的单个 SQLite 数据库支持的结构化长期记忆。无需 API 密钥，无需云端，无遥测。只需 npm install，你的 Agent 就能记住信息。

为什么要使用分层记忆？

扁平的键值存储会把“昨天发生了什么”和“提交前绝不跳过测试”一视同仁。这是不合理的——不同类型的知识有不同的生命周期和访问模式。

Mnemon 将记忆组织成四个层级：

上周二的日志条目和永不更改的编码规则属于不同层级——因为它们理应如此。

检索质量

检索质量基于真实的 797 条记忆双语（RU/EN）语料库，通过实际的 MCP 服务（而非重新实现）在 50 个黄金测试用例上进行评估。当前数据（方法与历史）：

混合检索优于两种单独的检索方式，这正是融合它们的全部意义：词法搜索的原始召回率更高，向量搜索的排序更好，而 RRF 能兼顾两者，而不是将它们平均掉。

评估文档也记录了失败情况——语料库增长时的得分漂移、评估发现的 BM25 字段权重错误、融合效果仍不如纯词法搜索的两个案例，以及黄金测试集未涵盖的内容。无法审计的数据只是营销；了解这些数据是如何得出的。

架构

flowchart LR
    C["MCP client<br/>Claude Code · Cursor · …"] -- "stdio / HTTP" --> T["10 tools · 4 resources · 3 prompts"]
    T --> R["retrieval pipeline<br/>FTS5 · vector · RRF fusion"]
    T --> M["memories + supersede chains"]
    I["KB import pipeline<br/>markdown → memories"] --> M
    M -- triggers --> F["FTS5 index (stemmed EN+RU)"]
    R --> F
    R --> V["sqlite-vec (optional, BYOK)"]

单个 SQLite 文件存储记忆、FTS5 索引和可选的向量索引。写入通过事务进行，以维持 supersede-chain 不变量；读取则运行搜索部分所述的分阶段检索流程。

完整说明——包括模块边界、读写路径、不变量和已知限制——请参阅docs/ARCHITECTURE.md。设计决策记录在 ADR 中：SQLite+FTS5 核心、混合 RRF 检索、同步驱动、分层记忆模型。

快速开始

安装

npm install -g mnemon-mcp

或者从源代码安装：

git clone https://github.com/nikitacometa/mnemon-memory-mcp.git
cd mnemon-memory-mcp && npm install && npm run build

配置 MCP 客户端

openclaw mcp register mnemon-mcp --command="mnemon-mcp"

{
  "mnemon-mcp": {
    "command": "mnemon-mcp"
  }
}

{
  "mcpServers": {
    "mnemon-mcp": {
      "command": "mnemon-mcp"
    }
  }
}

{
  "mcpServers": {
    "mnemon-mcp": {
      "command": "mnemon-mcp"
    }
  }
}

{
  "mnemon-mcp": {
    "command": "node",
    "args": ["/absolute/path/to/mnemon-mcp/dist/index.js"]
  }
}

验证

echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | mnemon-mcp

你应该会在响应中看到 10 个工具。数据库（~/.mnemon-mcp/memory.db）会在首次运行时自动创建。

就是这样。现在，你的 Agent 拥有了持久记忆。

功能介绍

10 个 MCP 工具

MCP 资源与提示词

资源 — Agent 可读取的实时数据：

提示词 — 预构建工作流：

搜索

四种模式均支持按层 / 实体 / 范围 / 日期 / 置信度筛选：

FTS 模式（未配置嵌入时的默认模式）— 使用 BM25 排名的分词全文搜索。多词查询使用 AND；结果过少时，会以 OR 补充并施加分数惩罚。渐进式 AND 放宽会先尝试最具体的前 3 个词，再回退到完整 OR。

混合模式（配置嵌入后的默认模式）— 通过 Reciprocal Rank Fusion 结合 FTS5 和向量搜索。会检测查询中的带引号实体（例如 'Essentialism'），并运行加权子查询以检索交叉引用。

向量模式 — 对嵌入执行纯余弦相似度搜索。

精确模式 — 使用 LIKE 子串匹配精准查找短语。

分数：bm25 × (0.3 + 0.7 × importance) × decay(layer) × recency

近期度加成：1 / (1 + daysSince / 365) — 轻微提升近期创建的记忆，不会惩罚较旧的记忆。

词干提取

Snowball 词干提取器会在索引时和查询时应用于英语和俄语。这意味着 "running" 可匹配 "runs"，而 "книги" 可匹配 "книга"。查询中的停用词会被过滤，以提高精确度。

事实版本管理

知识会不断演变。Mnemon 不会删除旧事实，而是将它们串联起来：

v1: "Team uses React 17"  →  superseded_by: v2
v2: "Team uses React 19"  →  supersedes: v1 (active)

搜索只会返回最新版本。使用 include_history: true 调用 memory_inspect 可查看完整链条。memory_delete 会重新激活前序版本 — 不会丢失任何内容。

向量搜索（可选，BYOK）

提供自己的嵌入 API，即可启用语义相似度搜索：

# OpenAI
MNEMON_EMBEDDING_PROVIDER=openai MNEMON_EMBEDDING_API_KEY=sk-... mnemon-mcp

# Ollama (local, free)
MNEMON_EMBEDDING_PROVIDER=ollama mnemon-mcp

这会解锁两种额外的搜索模式：

• mode: "vector" — 纯余弦相似度搜索
• mode: "hybrid" — 通过 Reciprocal Rank Fusion 合并 FTS5 和向量搜索

需要 sqlite-vec（作为可选依赖安装）。添加新记忆时会生成嵌入；现有记忆可批量补全嵌入。

导入知识库

有一组 Markdown 文件？可以批量导入：

cp config.example.json ~/.mnemon-mcp/config.json   # edit this first
npm run import:kb -- --kb-path /path/to/your/kb     # incremental (skips unchanged files)

配置会将 glob 模式映射到记忆层：

{
  "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"
    }
  ]
}

配置字段

HTTP 传输

适用于远程或多客户端配置：

MNEMON_AUTH_TOKEN=your-secret MNEMON_HOST=0.0.0.0 MNEMON_PORT=3000 npm run start:http

默认绑定到 127.0.0.1。绑定到其他主机时必须设置 MNEMON_AUTH_TOKEN — 否则服务会拒绝在未经身份验证的情况下向网络公开记忆存储（在可信网络中可通过 MNEMON_ALLOW_INSECURE_HTTP=1 覆盖）。默认限流为每个 IP 每分钟 100 个请求；CORS 需选择启用；请求正文限制为 1MB；身份验证采用计时安全比较；收到 SIGTERM 时会优雅关闭。

配置参考

工具参考

对比

扩展版竞品分析及其来源见：docs/COMPETITORS.md。

开发

npm run dev        # run via tsx (no build step)
npm run build      # TypeScript → dist/
npm run lint       # eslint (flat config)
npm test           # vitest — unit + integration + MCP dispatch + HTTP transport + hybrid RRF
npm run bench      # performance benchmarks
npm run db:backup  # backup database

CI 会在 Node 20 和 22 上运行构建、代码检查和测试，然后通过真实 JSON-RPC 执行编译后服务的冒烟测试（tools/list 必须与确切的工具集一致）。

技术栈： TypeScript 5.9（严格模式）、better-sqlite3、@modelcontextprotocol/sdk、Snowball 词干提取器、Zod、vitest。

代码规范请参阅 CONTRIBUTING.md。

设计原则

• 默认支持物理隔离环境——始终零遥测。开箱即用时不会有任何数据离开设备；唯一会连接网络的组件是可选的嵌入器，且只连接到你配置的提供方（包括本地 Ollama）。
• 单文件——一个 SQLite 数据库，无需运维，通过复制文件即可即时备份。
• 确定性搜索——默认使用 FTS5，而非嵌入。结果可解释、可复现，无需 GPU。
• 结构化优于扁平化——分层结构编码访问模式；替代链编码时间。
• 精简——4 个生产依赖项。可在 Node 运行的任何环境中使用。
• 以测量为依据，而非空口断言——根据黄金集评估检索变更，其中也包括回归测试。

许可证

MIT