完整文档 -- 指南、工具参考、架构和维护，请访问 cachorro.space

mcp-memory

这是 Anthropic MCP Memory 服务器 的直接替代品，具备 SQLite 持久化、向量嵌入、语义搜索以及用于动态排名的边缘系统评分 (Limbic Scoring)。

为什么选择它？ 原始服务器在每次操作时都会将整个知识图谱写入 JSONL 文件，且没有锁定或原子写入机制。在并发访问（多个 MCP 客户端）下，这会导致数据损坏。本服务器将其替换为标准的 SQLite 数据库。

特性

• 直接兼容 Anthropic 的 8 个 MCP 工具（相同的 API，相同的行为）

• SQLite + WAL -- 安全的并发访问，不再有损坏的 JSONL

• 语义搜索 -- 通过 sqlite-vec + ONNX 嵌入（支持 94+ 种语言）

• 混合搜索 (FTS5 + KNN) -- 通过倒数排名融合 (Reciprocal Rank Fusion) 结合全文 BM25 和语义向量搜索。可以通过精确术语或语义相似度查找实体，也可以两者同时使用。

• 边缘系统评分 (Limbic Scoring) -- 结合显著性、时间衰减、共现信号和混合搜索分数的动态重排序。对 API 透明。

• 语义去重 -- 当余弦相似度 >= 0.85 时，自动对新观察结果标记 similarity_flag（包含针对非对称文本长度的包含评分）

• 整合报告 -- 用于拆分候选对象、标记观察结果、陈旧实体和大型实体的只读健康检查

• 改进的近因衰减 -- entity_access_log 跟踪，带有 ALPHA_CONS=0.2 的多日整合信号

• 包含修复 -- 在去重评分中正确处理非对称文本长度（比率 >= 2.0）

• 观察类型 -- 观察结果的语义分类（hallazgo, decision, estado, spec, metrica, metadata, generic）

• 观察覆盖 -- 显式替换链：新观察结果可以覆盖旧观察结果，旧结果会被标记为已覆盖 (superseded)

• 实体状态 -- 生命周期跟踪：activo, pausado, completado, archivado（支持状态感知搜索降权）

• 关系上下文 + 有效期 -- 关系携带可选的上下文、active/ended_at 字段，用于时间有效性

• 自动反向关系 -- 自动创建 contains/parte_de 对

• 反思 (Reflections) -- 独立的叙事层：附加到实体/会话/关系/全局的自由格式散文，带有作者和情绪元数据，可通过语义 + FTS5 混合搜索进行搜索

• 轻量级 -- 总计约 500 MB，而类似解决方案约为 1.4 GB

• 迁移 -- 一键导入 Anthropic 的 JSONL 格式

• 零配置 -- 开箱即用，可选模型下载以支持语义搜索

快速入门

1. 添加到您的 MCP 配置

{
  "mcpServers": {
    "memory": {
      "command": ["uvx", "--from", "git+https://github.com/Yarlan1503/mcp-memory", "mcp-memory"]
    }
  }
}

或者克隆并在本地运行：

{
  "mcpServers": {
    "memory": {
      "command": ["uv", "run", "--directory", "/path/to/mcp-memory", "mcp-memory"]
    }
  }
}

2. 启用语义搜索（可选）

cd /path/to/mcp-memory
uv run python scripts/download_model.py

这将下载一个多语言句子模型（约 465 MB）到 ~/.cache/mcp-memory-v2/models/。如果没有它，所有工具仍可正常工作，仅 search_semantic 不可用。

3. 迁移现有数据（可选）

如果您有 Anthropic MCP Memory JSONL 文件，请使用 migrate 工具或直接调用它：

uv run python -c "
from mcp_memory.storage import MemoryStore
from mcp_memory.migrate import migrate_jsonl
store = MemoryStore()
store.init_db()
result = migrate_jsonl(store, '~/.config/opencode/mcp-memory.jsonl')
print(result)
"

MCP 工具

核心（兼容 Anthropic）

搜索与分析

实体管理

反思 (Reflections)

实体类型

8 种规范类型：

观察类型

观察结果的语义分类：

关系类型

4 个类别：

contiene/parte_de 对会自动创建反向关系。

架构

server.py (FastMCP)  <--  storage.py (SQLite + sqlite-vec + FTS5)
                               |
                         embeddings.py (ONNX Runtime)
                               |
                         sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2
                         (384d, multilingual, cosine similarity)
                               |
                         scoring.py (Limbic Scoring + RRF)
                         salience . temporal decay . co-occurrence

• 存储：带有 WAL 日志的 SQLite，5 秒忙碌超时，CASCADE 删除

• 嵌入：启动时加载一次的单例 ONNX 模型，L2 归一化余弦搜索

• 边缘系统评分：使用重要性信号、时间衰减、共现模式和 RRF 分数对混合 (KNN + FTS5) 候选对象进行重排序 -- 对 API 透明

• 并发：SQLite 内部处理锁定 -- 无 fcntl，无文件系统冲突

• 反思：用于叙事层的并行 FTS5 (reflection_fts) 和向量 (reflection_embeddings) 索引，通过相同的 RRF 混合管道进行搜索

工作原理

每个实体都有一个使用 Head+Tail+Diversity 选择策略（预算：480 个 token）从其文本生成的嵌入向量：

"{name} ({entity_type}) | {obs1} | {obs2} | ... | Rel: type -> target; ..."

当您调用 search_semantic 时，管道并行运行：

1. 语义 (KNN) -- 查询被编码并与 sqlite-vec 中的实体向量进行比较

2. 全文 (FTS5) -- 查询针对覆盖名称、类型和观察内容的 BM25 索引进行搜索

3. 合并 (RRF) -- 使用倒数排名融合 (score(d) = Sum 1/(k + rank)) 合并来自两个分支的结果

合并后的候选对象随后由 边缘系统评分 引擎进行重排序，该引擎考虑：

• 显著性 -- 频繁访问且连接良好的实体排名更高

• 时间衰减 -- 最近使用的实体保持新鲜；未触及的实体逐渐淡出

• 共现 -- 经常一起出现的实体会相互强化

输出包括 limbic_score、scoring（重要性/时间/共现细分），以及当 FTS5 提供结果时的可选 rrf_score。

有关完整技术细节，请参阅 DOCUMENTATION.md -- 包含评分公式、RRF 常量、模式 DDL 和架构图。

测试

uv run pytest tests/ -v

在 15 个测试文件中进行了 285 次以上的测试，涵盖所有工具、嵌入、评分和边缘情况。零回归。

要求

• Python >= 3.12

• uv (包管理器)

依赖

许可证

MIT