mcp-melquiades

DSH 会话的草稿纸 + 压缩档案回查 —— 一个由 MariaDB 支撑的 MCP 服务器。

名字取自加西亚·马尔克斯《百年孤独》里的墨尔基阿德斯（Melquíades）——那个把布恩迪亚家族 百年史写在羊皮卷上、并且「没有按人类惯常的时间顺序来排列这些事件」的人。本项目与同门的 mcp-pergaminos、memoria-del-hielo 共享这一母题：身份稳定，顺序易变。

这句话在这里不是修辞，是设计约束：DSH 的会话日志会改名、换代、重编号，而档案指针不能 跟着碎掉。本项目为此付出的大部分工程努力，都在这一条上（见 §4）。

⚠️ 丑话说在前头：这是个人满足自己需求的娱乐作品。它为「跨会话找回刚被压缩掉的东西」 而写，绑定了 DeepSeek Harness（下称 DSH）的私有会话日志格式。如果你不用 DSH， 它对你基本没用。 作者不承诺接口稳定，但承诺不静默降级——上游一变，它会吵，不会装死。

1. 它做什么

三个能力，一个 MCP 服务器：

它不做什么：不写入 DSH、不修改任何会话日志、不进 DSH 进程。收割是只读的。 （这是有意的：侵入上游进程的代价，远大于"压缩后产物"本身的价值。）

1.1 为什么需要它

DSH 会自动压缩长会话——把早期消息压成一段约 35:1 的摘要。摘要是有损的： 没被写进摘要的词，在摘要里永远搜不到。而真实的痛点是 「开新对话找不到之前的东西」、以及「刚被压掉的内容还想要」。

本项目把压缩产物连同被遮蔽事件的身份锚一起入库，使"刚被压掉的内容"可以被检索、 并且能回到原文——即使原文所在的日志文件已经改名、换代、甚至消失。

Related MCP server: LLM Second Brain

2. 工具清单（10 个）

3. 安装

核心（MCP 服务器本体：轻量，无需 CUDA / torch）

pip install -e .
# 或不装包，直接用：python -m melquiades.cli / python -m melquiades.server

核心依赖：mcp、mariadb、PyYAML、httpx、jieba、sqlglot、zstandard、rapidfuzz。 其中 jieba / sqlglot / zstandard 缺失时各自降级（CJK 全文 / AST 门禁 / 收割器）， 不影响其余功能——降级都会显式告警，不静默。

可选：自建嵌入代理（[embed] extra）——只有你要跑向量检索才需要，含 CUDA torch：

# 先装 CUDA 版 torch（版本必须三者对齐：torch / torchaudio / torchvision 同 minor）
pip install torch==2.10.0+cu126 torchvision==0.25.0+cu126 torchaudio==2.10.0+cu126 \
    --index-url https://download.pytorch.org/whl/cu126
pip install -e '.[embed]'

torch 全家桶必须显式锁版本：torchaudio 与 torch 差一个 minor， 就会在 undefined symbol 上炸——而这条错配能潜伏半年不发作， 直到 sentence-transformers → transformers → loss_rnnt → torchaudio 这条 死亡 import 路径被走通。详见 NOTES.md。

可选：预下载模型权重（[models] extra）：pip install -e '.[models]' && python download_models.py。

嵌入代理（server_bge.py）不在本仓库。 它是同门项目 memoria-del-hielo 里的一个双端口 BGE 嵌入 / 重排代理（9005 本地优先 / 9006 远端优先）， 本项目默认指向它。没有嵌入代理时，向量路与精排路不可用，全文 / LIKE 路照常工作。

4. 与 DSH 的关系 —— 上游适配（本项目的核心工程）

4.1 耦合点（每一处都有实测出处，不是推测）

架构纪律：所有 DSH 格式知识只许出现在 melquiades/harvest/ 与 config.resolve_dsh_home。 改上游适配就改这两处；别把格式知识漏进 retrieval.py 之类的地方。

4.2 上游漂移探测器

melquiades/harvest/drift.py 持有 DSH 事件类型的实测基线（对 40 个真实会话日志做直方图， 得 38 种顶层类型）。它报两类事实：

• unknown_event_types(events) —— 多出来的类型（升级会新增，改名才是事故）；

• missing_content_types(events) —— 少掉的、本该承载正文的类型（改名 = 静默少收的前兆）。

升级 DSH 之后的第一件事：跑 melquiades status（已内置这项检查，默认扫最近 1 个日志， --drift-logs N 可加宽）。看有没有未登记的类型——比"等线上发现内容变少"便宜得多。

4.3 兼容性

（作者会随 DSH 升级更新此表；release notes 里会写明适配的 DSH 版本。）

4.4 适配流程（固定闭环，每次都一样）

① 升级 DSH
② pytest                              → 哪条契约破了 / 有没有破
③ 喂新日志给 harvest/drift            → 有没有未登记 / 消失的事件类型
④ 只改隔离层（harvest/ 或 config.resolve_dsh_home）
⑤ 补一条黄金样本 fixture（把这次的上游形态钉住）
⑥ 更新本表 + 版本号 → 重新导出发布件（§8）

5. 配置

cp config.example.yaml config.yaml
$EDITOR config.yaml

config.yaml 含数据库口令，不要提交（.gitignore 已覆盖它）。 配置的每一项都有处可查：所有魔法数字（超时、阈值、权重、池大小）都在 config.yaml 的注释里写明了取值依据与实测数据——改它之前先读那段注释。

关键项：

mariadb:
  host: 127.0.0.1
  port: 3306
  database: melquiades_medicamento
  user: melquiades
  password: "……"                  # 必填

dsh:
  harness_dir: /path/to/deepseek-harness   # home 名由 <此>/DSH_VERSION 派生
  home: ""                                  # 留空 = 派生；填值则覆盖（逃生口）

search:
  bge_endpoints: ["http://localhost:9006", "http://localhost:9005"]
  bge_model: "remote:BAAI/bge-m3"           # `remote:` 前缀必留（见 config 注释）

数据库与低权限用户需要先建好（示例，口令自定）：

CREATE DATABASE IF NOT EXISTS melquiades_medicamento
  CHARACTER SET utf8mb4 COLLATE utf8mb4_uca1400_ai_ci;
CREATE USER IF NOT EXISTS 'melquiades'@'localhost' IDENTIFIED BY '<你的口令>';
GRANT ALL PRIVILEGES ON melquiades_medicamento.* TO 'melquiades'@'localhost';

6. 运行

初始化数据库表（幂等）：

python -m melquiades.cli ensure-tables

首扫历史日志（一次性；170MB 量级，不进 MCP 启动路径）：

python -m melquiades.cli harvest --backfill

查看状态（含上游漂移扫描：默认扫最近 1 个日志的事件类型，未登记即告警）：

python -m melquiades.cli status --logs 10
python -m melquiades.cli status --drift-logs 5     # 加宽到 5 个日志

作为 MCP 服务器（stdio）：

python -m melquiades.server

MCP 客户端（如 DSH）配置示例：

- name: melquiades
  command: bash
  args: ["-l", "/path/to/mcp-stdio.sh", "melquiades"]

7. 测试

pip install -e '.[test]'
pytest

测试分两层：

1. 纯单元：tokenizer（jieba / CJK 边界）、sqlguard（condition 的 AST 白名单）、 compaction_v2（代数解析 / 44 字符契约）、vocab（同义词环）、config（home 派生）。

2. 黄金样本：tests/fixtures/dsh_session_golden.jsonl 是一份合成的 DSH 事件样本 （真实日志是个人对话内容，进仓即泄露，故不进仓；测试时现场把它编成多帧 zstd、 摆成 DSH 的目录布局），跑通 发现日志 → 增量读 → 事件解析 → 抽取压缩记录 全链路。

这套测试是上游适配的回归网：DSH 一变，pytest 先响， 而不是等线上静默归零（本项目历史上吃过两次这种亏：home 硬编码、日志名写死）。

8. 发布件怎么生成

MELQUIADES_PUBLIC_DST=/path/to/public-dir ./tools/export_to_public.sh

白名单导出 + 泄露闸门（不是 cp -r）：白名单之外的东西永远不会被带出去， 且每次导出都是一次泄露检测——凭据 / 已知机密 / 机器绝对路径 / 真实邮箱 / 必备件 / 纯净度 / 语法，任一命中即拒绝（exit 1），不静默放行。

脱敏规则在 .publish-redactions、已知机密登记在 .publish-secrets——两者都不发布。 脱敏必须覆盖闸门：闸门扫的是脱敏后的导出件，规则漏一条就当场 FAIL。

9. 目录结构

melquiades/
├── melquiades/                # 包本体
│   ├── server.py              # MCP 入口（10 个工具）
│   ├── cli.py                 # ensure-tables / harvest / status / backfill
│   ├── config.py              # 配置（魔法数字唯一出口）+ DSH home 解析
│   ├── dbcore.py / db.py / schema.py          # 即弃连接 + 表结构演进
│   ├── retrieval.py / search.py / rerank.py   # 检索栈
│   ├── tokenizer.py / vocab.py / sqlguard.py  # 分词 / 词表 / SQL 门禁
│   └── harvest/               # ← 所有 DSH 格式知识都在这
│       ├── reader.py          #   多帧 zstd 增量读 + 字节偏移游标
│       ├── extract.py         #   compaction 事件 → 三层内容
│       ├── message_extract.py #   消息 / 附件抽取
│       ├── compaction_v2.py   #   seq→guid 译法（唯一真相源）
│       ├── drift.py           #   ★ 上游漂移探测器
│       └── runner.py / store.py / scheduler.py
├── tests/                     # 单元 + 黄金样本
├── tools/                     # export_to_public.sh / scan_paths.py / 回填 / 校验
├── config.example.yaml
└── pyproject.toml

10. 许可

代码：AGPL-3.0-only（见 LICENSE）。

本项目只读 DSH 的会话日志、不修改、不代持。它存储的是你自己的会话内容的 一份衍生副本（摘要 + 指针 + 你主动写入的笔记）——这些内容归你，怎么用由你决定。