mcp-vl-msa-rs

mcp-vl-msa-rs

为 AI Agent 提供可搜索的长期记忆，并通过 MCP stdio 服务开放使用。 将文档、笔记和过往对话编入集合；针对查询检索最相关的 top-k 内容块，并将原文注入模型；通过 msa_remember / msa_forget 添加或删除 Agent 记忆。纯 Rust 实现，基于 tantivy 使用 BM25，默认构建不依赖任何 ML 库；也可选择在进程内进行稠密重排。

任何 MCP 客户端（Claude Code、Codex，或任何使用 MCP stdio 的工具）都能使用相同的记忆：可查询的语料库可跨会话和模型切换持续保留，无需云账户或嵌入服务。可用于为 Agent 提供对知识库、文档树或自身聊天记录的持久回忆能力——检索返回的是原文，而不只是嵌入向量。

它是两部分记忆系统中的一部分：此服务是图书馆（语料回忆），配套的 mcp-memory-rs 是笔记本（整理后的状态）。Agent 即使切换模型，也不会丢失记忆。

flowchart LR
    A["AI agent<br/>(any MCP client)"]
    A -->|"curated state<br/>read / write / sync"| M["mcp-memory-rs<br/><i>the notebook</i>"]
    A -->|"corpus recall<br/>index / search / fetch"| V["mcp-vl-msa-rs<br/><i>the library</i>"]
    M --- D1[("JSON categories<br/>SQLite FTS5")]
    V --- D2[("tantivy BM25<br/>collections")]

名称：msa 借鉴了 Memory Sparse Attention 论文（arXiv:2603.23516）中的检索模式——这是一种外部近似，而非神经模型；它不同于 MiniMax 的 MSA 架构大模型，后者是内在的（模型内）生成器。vl 代表 Vivling（codex-vl），这是它的首个采用者——但该服务完全不依赖特定 AI，也不依赖 Vivling 的任何组件。

状态：v0.4——可选的稀疏与稠密混合模式。

为什么

原始的 Memory Sparse Attention 论文（EverMind-AI）介绍了一种端到端可训练的稀疏注意力层，作用于按块池化的 KV 缓存。这属于神经模型产物，无法移植到纯 Rust 的 MCP 服务中。本仓库旨在实现的是可移植的 MSA 宏观模式：

1. 分块存储长文本，使用较小且固定的池大小（默认 P=64 个词，与论文设置一致）。
2. 对内容块进行 Top-k 稀疏路由（BM25 代理；不涉及学习式路由）。
3. 注入原文（论文 §4.3；消融实验表明，不注入会下降 37.1%）：msa_search 返回内容块，msa_fetch_doc 返回完整文档。
4. 将 Memory Interleave 作为一种协议（计划于 v0.4 推出）：AI 客户端通过重复调用工具进行多跳检索，服务端则使用游标。

设计和原理记录在项目说明文档中（负面结果、门槛方法）；详见 docs/NEGATIVE_RESULTS.md。

基准测试

检索改动依据预先注册的配对增量和自助法置信区间来决定——而非绝对分数。工作负载：HotpotQA（抽取式 QA）、MLDR-it（长文档检索，意大利语）、LongMemEval-S（500 个对话记忆问题）。完整方法、验收门槛和已被证伪的假设见 docs/NEGATIVE_RESULTS.md。

主要测量结果：

• BM25 是引擎，不是占位符。 进行了三次预先注册的尝试；在这些工作负载上，没有任何混合配置（BM25 + 稠密重排）通过门槛。稠密重排仍可用（dense_alpha，默认关闭），以便在编码器改进后重新测试。
• 摄取时生成丰富的胶囊（确定性增强，不使用 LLM）：所有类别的 recall@5 均提升 +7 到 +20。
• 注入原文（msa_search 后调用 msa_fetch_doc）：在片段未包含相关内容的分层上，F1 精确提升 +14.6。
• 新近度先验表现不佳——应在服务时处理时间，而不是将其纳入检索分数。

复现：

crates/msa-bench/scripts/download-bench-datasets.sh   # fetch datasets
scripts/run-baseline-bench.sh                         # BM25 vs BM25+dense sweep
# results land under crates/msa-bench/results/ as JSON

工具列表

工具	起始版本	说明
msa_index	v0.1	为文档建立索引；替换 doc_id 对应的现有分块。
msa_search	v0.1	返回 top-k 个分块，分数归一化至 0.0–1.0。
msa_fetch_doc	v0.1	获取文档的完整原文。
msa_delete	v0.1	移除文档及其所有分块。
msa_list_collections	v0.1	列出注册表中已打开的集合。
msa_stats	v0.1	集合统计信息（精确的 num_documents / total_tokens）。
SearchFilter	v0.2	元数据筛选器（where_eq/where_in/created_*），在检索后应用。
msa_search_iterative	v0.3	通过服务端游标实现 Memory Interleave；跨轮次去重。
msa_drop_session	v0.3	在 TTL 到期前强制清除 Memory Interleave 会话。
msa_search 上的 dense_alpha	v0.4	BM25 + 余弦重排的混合检索。需要 --features embeddings + [embeddings] 配置。
msa_remember / msa_forget	v0.4	Agent 记忆接口：增强 + 低信号门控 + 内容哈希去重；标准元数据（kind / source_id / created_at）。
msa_sync_path	v0.4	将目录镜像到集合中（文件系统来源；blake3 增量同步）。

安装

预编译二进制文件（推荐）——从最新版本下载适用于你平台的归档文件，解压后，将 MCP 客户端指向该二进制文件：

tar xzf mcp-vl-msa-rs-x86_64-unknown-linux-gnu.tar.gz
install -m755 mcp-vl-msa-rs-*/mcp-vl-msa-rs ~/.local/bin/

预编译目标平台（Linux + Android）：x86_64-unknown-linux-gnu、 x86_64-unknown-linux-musl、aarch64-unknown-linux-gnu、 aarch64-unknown-linux-musl（边缘设备 / ARM / Termux）、aarch64-linux-android。

macOS：不提供预编译二进制文件（因为需要 Apple 代码签名）。 请改为从源码安装——下方的 cargo install 命令会在你的 Mac 上通过一条命令完成编译，无需签名。

从源码安装（Rust 工具链）——必须使用 --locked（工作区的 Cargo.lock 固定了可用的 time / tantivy-common 依赖解析结果；重新解析会导致构建失败），且软件包名称为 mcp-msa-server（安装的二进制文件名为 mcp-vl-msa-rs）：

cargo install --git https://github.com/DioNanos/mcp-vl-msa-rs \
  --locked --features source-fs mcp-msa-server

构建与测试

cd mcp-vl-msa-rs

# Default: pure BM25, zero network deps
cargo build --release
cargo test

# Hybrid sparse + dense (in-process Candle rerank, no external service)
cargo build --release --features embeddings
cargo test  --features embeddings

混合模式配置

在 MCP_MSA_CONFIG 中添加 [embeddings] 以启用稠密重排。没有此部分时，即使二进制文件使用 --features embeddings 构建，服务仍会保持仅 BM25 模式。

[storage]
storage_dir = "~/.local/state/mcp-vl-msa-rs"

[chunking]
chunk_size = 64
overlap = 0

[embeddings]
backend   = "candle-modernbert"
model_dir = "~/.local/share/mcp-vl-msa-rs/models/granite-r2-97m"
dim       = 768
model_id  = "granite-r2-97m"

过渡性的 backend = "ollama"（通过 HTTP 连接兼容 Ollama 的服务）仍然存在，但已弃用，并计划在 v0.6 中移除——请勿基于它构建新的配置。

AI 客户端可通过在每次调用 msa_search（或任何未来支持此功能的工具）时传递 dense_alpha，选择启用混合评分。dense_alpha = 1.0（默认值）表示仅 BM25；0.0 表示仅稠密评分；中间值表示线性混合：α·bm25 + (1-α)·((cos+1)/2)。余弦值会平移到 [0,1]，使其能够与已进行最大值归一化的 BM25 分数线性组合。

作为 MCP stdio 运行

# Default storage: ~/.local/state/mcp-vl-msa-rs/
./target/release/mcp-vl-msa-rs

# With explicit config
MCP_VL_MSA_CONFIG=~/.config/mcp-vl-msa-rs/config.toml \
MCP_DEVICE=my-node \
./target/release/mcp-vl-msa-rs

~/.codex/config.toml 配置项示例：

[mcp_servers.vl_msa]
command = "/path/to/mcp-vl-msa-rs/target/release/mcp-vl-msa-rs"
env = { MCP_DEVICE = "my-node" }
# let the model call tools without a per-call approval prompt
default_tools_approval_mode = "approve"

Claude Code 对应的 ~/.claude.json 配置项：

{
  "mcpServers": {
    "vl_msa": {
      "command": "/path/to/mcp-vl-msa-rs/target/release/mcp-vl-msa-rs",
      "env": { "MCP_DEVICE": "my-node" }
    }
  }
}

AI 客户端兼容性

• 部分支持 MCP 的客户端可能不会显示服务的 instructions 文本。工具描述和请求字段描述内容完整，模型仅凭这些信息也能正常工作。
• 只读工具（msa_search、msa_fetch_doc、msa_stats、 msa_list_collections、msa_manifest、msa_search_iterative、 msa_interleave_round）带有 readOnlyHint 注解，客户端可据此自动批准这些工具。
• 如果模型在 codex 上报告“unsupported call”或“user cancelled”，这是审批关卡导致的，并非服务故障——请设置 default_tools_approval_mode（见上文），避免工具调用被提示词阻止。

存储布局

~/.local/state/mcp-vl-msa-rs/
├── <collection_a>/        ← tantivy index directory
├── <collection_b>/
└── ...

每个集合都是独立的 tantivy 索引。集合名称会经过验证（若包含路径分隔符、.. 等则会被拒绝），因此集合无法逃逸出根目录。

路线图

已发布：

• v0.2 — SearchFilter（where_eq / where_in / 创建时间范围），检索后过滤。
• v0.3 — msa_search_iterative Memory Interleave，带有服务端游标和设有 TTL 的 MsaSession 注册表。
• v0.4 — 通过功能标志 embeddings 启用混合 BM25 + 稠密重排、Ollama 后端、按调用指定 dense_alpha；Agent 记忆接口（msa_remember / msa_forget）；索引时记录文件系统来源元数据（created_at / source / ext / dir）；msa_stats 中提供精确的 num_documents / total_tokens；可复现的 msa-bench 基准测试 crate；预构建二进制文件打包。

接下来（尚未构建）：

• 查询时 tantivy 过滤（目前 SearchFilter 在检索后运行；对于普通语料库已足够，但当超大索引的筛选选择性很高时，预过滤会有所帮助）。
• 多租户集合的 ACL。
• 工具描述调优。

相关项目

• MSA 论文（arXiv:2603.23516）——架构灵感来源（神经式、内在式）；本仓库是对宏观模式的外在式纯 Rust 近似实现。
• Vivling（位于 codex-vl 中）——首个下游使用方：本服务是它的长期记忆。
• mcp-memory-rs——用于整理后的 Agent 状态的配套服务（命名 JSON 类别、按设备设置 ACL、集群同步）。本服务负责语料召回；二者结合，覆盖 Agent 记忆的两部分：整理好的笔记本和可查询的资料库。

许可证

Apache-2.0。参见 LICENSE。