Skip to main content
Glama
deeneskoruzh
nikitacometa

mnemon-mcp

by nikitacometa
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

mnemon-mcp

CI npm version Node.js License: MIT

面向 AI 代理的持久化分层记忆。 本地优先。零云端。单个 SQLite 文件。

Landing Page · npm · GitHub

您的 AI 代理在每次会话后都会忘记一切。Mnemon 解决了这个问题。

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

为什么需要分层记忆？

扁平化的键值存储将"昨天发生了什么"与"没有测试绝不提交"混为一谈。这是错误的——不同类型的知识有不同的生命周期和访问模式。

Mnemon 将记忆组织为四个层：

层

存储内容

访问方式

生命周期

情景

事件、会话、日志条目

按日期或时间段

衰减（30 天半衰期）

语义

事实、偏好、关系

按主题或实体

稳定

程序性

规则、工作流、约定

启动时加载

很少更改

资源

参考资料、读书笔记

按需

缓慢衰减（90 天）

上周二的日志条目和一条永不变更的编码规则位于不同的层中——因为本就该如此。

Related MCP server: persistent-kb-mcp

检索质量

检索质量基于真实的 797 条记忆双语（RU/EN）语料库中的 50 个案例黄金集进行衡量，通过实际的 MCP 服务器进行——而非重新实现。当前数据（方法论与历史）：

指标

仅 FTS

仅向量

混合（RRF）

综合得分

88.9

89.2

91.7

Recall@5

0.907

0.898

0.919

MRR

0.817

0.832

0.878

nDCG@5

0.816

0.828

0.869

负例精确率

1.000

1.000

1.000

混合模式在两个单独指标上都更优，这正是融合它们的全部意义所在：词法搜索具有更好的原始召回率，向量搜索具有更好的排序，而 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 索引和可选的向量索引。写入通过保持取代链不变式的事务进行；读取运行搜索中描述的分阶段检索流水线。

完整图景——模块边界、写入/读取路径、不变式和已知限制——见 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"

或添加到 ~/.openclaw/mcp_config.json：

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

添加到 ~/.claude/mcp.json：

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

添加到您客户端的 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）在首次运行时自动创建。

就这样。您的代理现在拥有了持久化记忆。

它能做什么

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

创建结构化日志条目

搜索

四种模式，均支持层 / 实体 / 范围 / 日期 / 置信度过滤：

FTS 模式（未配置嵌入时的默认模式）— 使用 BM25 排序的标记化全文搜索。多词查询使用 AND；如果结果太少，OR 会以分数惩罚作为补充。渐进式 AND 放宽在回退到完整 OR 之前，会先尝试前 3 个最具体的词项。

混合模式（配置嵌入后的默认模式）— 通过倒数排名融合结合 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)

搜索仅返回最新版本。memory_inspect 配合 include_history: true 显示完整链。memory_delete 会重新激活前一个版本——不会丢失任何内容。

向量搜索（可选，自带密钥）

通过提供您自己的嵌入 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" — 通过倒数排名融合结合的 FTS5 + 向量

需要 sqlite-vec（作为可选依赖安装）。新记忆在添加时嵌入；现有记忆可以回填。

变量

默认值

描述

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 端点

导入知识库

有一堆 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"
    }
  ]
}

配置字段

字段

类型

描述

owner_name

string

您的姓名——用于 entity_name 中的 $owner 替换

extra_stop_words

string[]

从 FTS 查询中过滤的词（例如您的姓名形式）

glob

string

要匹配的文件模式

layer

string

目标记忆层

entity_type

string

user / person / project / concept / file / rule / tool

entity_name

string

字面名称、"$owner" 或 "from-heading"（从 H2/H3 提取）

split

string

"whole"（每个文件一条记忆）、"h2" 或 "h3"（按标题拆分）

importance

number

0.0–1.0，影响搜索排名

confidence

number

0.0–1.0，可在搜索中过滤

scope

string

可选命名空间

HTTP 传输

用于远程或多客户端设置：

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

端点

描述

POST /mcp

MCP JSON-RPC（如设置令牌则使用 Bearer 认证）

GET /health

{"status":"ok","version":"..."}

默认绑定到 127.0.0.1。绑定到任何其他主机都需要 MNEMON_AUTH_TOKEN — 服务器拒绝在未认证的情况下将记忆存储暴露到网络（在受信任网络上可使用 MNEMON_ALLOW_INSECURE_HTTP=1 覆盖）。速率限制（默认 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

—

HTTP 传输的 Bearer 令牌

MNEMON_HOST

127.0.0.1

HTTP 传输绑定地址

MNEMON_PORT

3000

HTTP 传输端口

MNEMON_CORS_ORIGIN

—

CORS Access-Control-Allow-Origin（未设置时不发送 CORS 头）

MNEMON_RATE_LIMIT

100

每 IP 每分钟最大请求数（0 = 关闭）

工具参考

参数

类型

必填

描述

content

string

是

记忆文本（最多 100K 字符）

layer

string

是

episodic / semantic / procedural / resource

title

string

否

短标题（最多 500 字符）

entity_type

string

否

user / project / person / concept / file / rule / tool

entity_name

string

否

用于筛选的实体名称

confidence

number

否

0.0–1.0（默认 0.8）

importance

number

否

0.0–1.0（默认 0.5）

scope

string

否

命名空间（默认 global）

source_file

string

否

源文件路径 — 触发匹配条目的自动取代

ttl_days

number

否

N 天后自动过期

valid_from / valid_until

string

否

时间事实窗口（ISO 8601）

参数

类型

必填

描述

query

string

是

搜索文本

mode

string

否

fts（默认）、exact、vector、hybrid

layers

string[]

否

按层筛选

entity_name

string

否

按实体筛选（支持别名）

scope

string

否

按作用域筛选

date_from / date_to

string

否

日期范围（ISO 8601）

as_of

string

否

时间事实筛选 — 在此日期有效的事实

min_confidence

number

否

最低置信度

min_importance

number

否

最低重要性

limit

number

否

最大结果数（默认 10，最大 100）

offset

number

否

分页偏移量

参数

类型

必填

描述

id

string

是

记忆 ID

content

string

否

新内容

title

string

否

新标题

confidence

number

否

新置信度

importance

number

否

新重要性

supersede

boolean

否

true = 版本化替换；false（默认）= 原地更新

new_content

string

否

用于取代条目的内容

参数

类型

必填

描述

id

string

是

记忆 ID。如果属于取代链的一部分，则重新激活前驱条目

参数

类型

必填

描述

id

string

否

记忆 ID（省略则显示聚合统计）

layer

string

否

按层筛选统计

entity_name

string

否

按实体筛选统计

include_history

boolean

否

显示取代链

参数

类型

必填

描述

format

string

是

json / markdown / claude-md

layers

string[]

否

按层筛选

scope

string

否

按作用域筛选

date_from / date_to

string

否

日期范围

limit

number

否

最大条目数（默认全部，最大 10K）

参数

类型

必填

描述

cleanup

boolean

否

true = 垃圾回收过期条目（默认：仅报告）

返回：状态（healthy / warning / degraded）、按层统计、过期条目、孤立链、陈旧/低置信度计数，以及 cleanup=true 时的清理计数。

参数

类型

必填

描述

client

string

是

客户端标识符（例如 claude-code、cursor、api）

project

string

否

此会话的项目作用域

meta

object

否

附加会话元数据

返回：id（会话 UUID）、started_at（ISO 8601）。

参数

类型

必填

描述

id

string

是

要结束的会话 ID

summary

string

否

完成内容的摘要（最多 10K 字符）

返回：id、ended_at、duration_minutes、memories_count。

参数

类型

必填

描述

limit

number

否

最大会话数（默认 20，最大 100）

client

string

否

按客户端筛选

project

string

否

按项目筛选

active_only

boolean

否

仅返回尚未结束的会话（默认 false）

返回：会话数组，包含 id、client、project、started_at、ended_at、summary、memories_count。

对比

mnemon-mcp

mem0

basic-memory

Engram

Anthropic KG

架构

SQLite FTS5 + vector

Cloud API + Qdrant

Markdown + vector

SQLite FTS5

JSON file

记忆结构

4 个类型化层

扁平

扁平

扁平 + 会话

图

搜索

FTS5 + hybrid RRF

语义

混合

FTS5

精确

事实版本控制

取代链

部分

无

无

无

词干提取

EN + RU (Snowball)

仅 EN

仅 EN

无

无

嵌入

BYOK (OpenAI / Ollama)

内置

FastEmbed

无

无

依赖

0 个必需

Qdrant, Neo4j

Python 3.12

Go binary

无

需要云服务

否

是

否

否

否

成本

免费

$19–249/mo

免费

免费

免费

安装

npm install -g

Docker + API 密钥

pip + 依赖

Go install

内置

许可证

MIT

Apache 2.0

AGPL

MIT

MIT

包含来源的扩展竞争分析：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 上运行构建、lint 和测试，然后通过真实 JSON-RPC 对编译后的 服务器进行冒烟测试（tools/list 必须与精确的工具集匹配）。

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

代码指南请参阅 CONTRIBUTING.md。

设计原则

  • 默认气隙隔离 — 零遥测，永不例外。开箱即用，不会有任何数据离开本机；唯一与网络通信的组件是可选的嵌入器（embedder），且仅与你配置的提供商通信（包括本地 Ollama）。

  • 单文件 — 单个 SQLite 数据库，零运维，通过文件复制即可即时备份。

  • 确定性搜索 — 默认使用 FTS5 而非嵌入（embeddings）。可解释、可复现，无需 GPU。

  • 结构化优于扁平化 — 层级编码访问模式；取代链编码时间。

  • 极简 — 仅 4 个生产依赖。可在 Node 运行的任何地方工作。

  • 以度量而非断言评估 — 检索变更以黄金集（golden set）为基准进行评判，包含回归测试。

许可证

MIT

This server cannot be deployed

Context All Your Agents Can ShareAgents share what they learn, hand off work, and hold it when you switch models. Start with 5 GB free.fulcradynamics.comAd

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers