内存服务增强版

全部文件 --指南、工具参考、架构和维护 狗.空间

mcp存储器

A. 直接替换品 为了 Anthropic的MCP内存服务器 --使用SQLite持久性、向量嵌入、语义搜索和 边缘评分 用于动态排名。

为什么？ 原始服务器在每次操作时都会将整个知识图写入JSONL文件，而不会进行锁定或原子写入。在并发访问（多个MCP客户端）下，这会导致数据损坏。此服务器用适当的SQLite数据库替换了它。

特性

• 插入兼容 使用Anthropic的8个MCP工具（相同的API，相同的行为）
• SQLite+WAL --安全的并发访问，不再有损坏的JSONL
• 语义搜索 通过sqlite-vec+ONNX嵌入（94+种语言）
• 混合搜索 （FTS5+KNN）——通过互易秩融合将全文BM25和语义向量搜索相结合。通过精确的术语或语义相似性（或同时通过这两者）查找实体。
• 边缘评分 --利用显著性、时间衰减、共现信号和混合搜索分数进行动态重新排序。对API透明。
• 语义重复数据删除 --自动 similarity_flag 余弦相似度>=0.85时的新观察结果（非对称文本长度的包含评分）
• 合并报告 --对拆分候选对象、标记的观察结果、过时实体和大型实体进行只读健康检查
• 改善近距衰减 -- entity_access_log 跟踪与 ALPHA_CONS=0.2 多日盘整信号
• 安全壳修复 --重复数据删除评分中不对称文本长度（比率>=2.0）的正确处理
• 观察种类 --观测的语义分类（hallazgo、decision、estado、spec、metrica、元数据、泛型）
• 观察取代 --显式替换链：新的观测值可以替换旧的观测值，这些观测值会被标记为被替换的时间戳
• 实体状态 --生命周期跟踪：活动，暂停，完成，存档（具有状态感知搜索-增强）
• 关系语境+氛围 --关系携带可选的上下文、active/ended_at字段以实现时间有效性
• 自动逆关系 --包含自动创建的/parte_de对
• 反思 --独立叙事层：自由形式的散文附加到实体/会话/关系/全局，带有作者和情绪元数据，可通过语义+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.启用语义搜索（可选）

嵌入模型(sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2，~465 MB，ONNX CPU，384 dim） 自动下载 首次使用时调用任何语义工具。无需手动设置。

如果您更喜欢预下载：

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

这是一个精简的包装器，可以将相同的文件下载到 ~/.cache/mcp-memory-v2/models/没有模型，所有非语义工具都能正常工作——只有 search_semantic 将不可用。

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

如果您有Anthropic MCP内存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工具

19工具 总计，按功能分组：

核心（与人类相容）

搜索与检索

实体管理与分析

关系管理

反思

实体类型

8种规范类型：

观察种类

观察的语义分类：

关系类型

关系类型有 不按传统格式的 （无限制枚举）。唯一硬编码的反向对是：

知识图中使用的常见约定（未强制执行）：

• 结构性的: contiene / parte_de
• 生产: producido_por, contribuye_a
• 依赖: depende_de, usa
• 时间: continua （传统映射→ contribuye_a), sucedido_por

遗留类型在创建时通过以下方式进行规范化 _constants.py: continua → contribuye_a （上下文为“会议续会”）， documentado_en → producido_por （上下文“记录在”）。

建筑

server.py (97 lines)          — FastMCP init + tool registration
├── tools/
│   ├── core.py              — 6 CRUD tools (Anthropic-compatible)
│   ├── search.py            — 3 search tools + ranking helpers
│   ├── entity_mgmt.py       — 6 entity management tools
│   ├── reflections.py       — 2 reflection tools
│   └── relations.py         — 2 tools (migrate, end_relation)
├── storage/                  — 7 mixins + constants via multiple inheritance
│   ├── __init__.py           — MemoryStore facade (134 lines)
│   ├── schema.py            — SchemaMixin (migrations)
│   ├── core.py              — CoreMixin (entity/obs CRUD)
│   ├── relations.py         — RelationsMixin
│   ├── search.py            — SearchMixin (FTS + embeddings)
│   ├── access.py            — AccessMixin
│   ├── reflections.py       — ReflectionsMixin
│   ├── consolidation.py     — ConsolidationMixin
│   └── _constants.py        — Inverse relation & validation constants
├── embeddings.py             — EmbeddingEngine (ONNX, lazy load, auto-download)
├── scoring.py                — Limbic Scoring + RRF
├── entity_splitter.py        — Semantic clustering (Agglomerative + c-TF-IDF fallback)
├── retry.py                  — retry_on_locked (concurrency)
└── config.py                 — Input limits + A/B config

• 存储：带WAL日志的SQLite，5秒繁忙超时，CASCADE删除
• 嵌入：启动时加载一次Singleton ONNX模型，L2归一化余弦搜索
• 边缘评分：使用重要性信号、时间衰减、同现模式和RRF分数的重新链接混合（KNN+FTS5）候选——对API透明
• 并发: retry_on_locked 在19种写入方法上具有指数回退+抖动的装饰器。安全的多客户端访问（通过并发开放代码会话进行测试）
• 反思：平行FTS5(reflection_fts)和矢量(reflection_embeddings)叙事层索引，通过同一RRF混合管道搜索

运作原理

每个实体都使用 头部+尾部+多样性 选择策略（预算：480个代币）：

"{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 （重要性/时间/COC分解），以及可选 rrf_score 当FTS5贡献结果时。

了解完整的技术细节，请参阅 文件.md --包括评分公式、RRF常数、模式DDL和架构图。

测试

uv run pytest tests/ -v

涵盖所有工具、嵌入、评分和边缘情况的23个测试文件中的402个测试。零回归。

需求

• Python>=3.12
• 紫外线 （包管理器）

依赖项

许可证

麻省理工学院