mcp-vl-msa-rs

A searchable long-term memory for AI agents, exposed as an MCP stdio server. Index documents, notes and past conversations into collections; retrieve the top-k relevant chunks for a query and inject the original text back to the model; add or drop agent memories with msa_remember / msa_forget. Pure Rust, BM25 over tantivy, zero ML deps in the default build; optional in-process dense rerank.

Any MCP client (Claude Code, Codex, or anything speaking MCP stdio) gets the same memory: a queryable corpus that survives across sessions and model swaps, with no cloud account and no embedding service required. Use it to give an agent durable recall over a knowledge base, a docs tree, or its own chat history — retrieval that returns the original text, not just embeddings.

It is one half of a two-part memory: this server is the library (corpus recall), its companion mcp-memory-rs is the notebook (curated state). An agent that swaps models loses neither.

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")]

The name: msa is the retrieval pattern it borrows from the Memory Sparse Attention paper (arXiv:2603.23516) — an extrinsic approximation, not the neural model; distinct from MiniMax's MSA-architecture LLMs, which are intrinsic (in-model) generators. vl is for Vivling (codex-vl), its first adopter — but the server is fully AI-agnostic and depends on nothing from it.

Status: v0.4 — hybrid sparse+dense optional.

Why

The original Memory Sparse Attention paper (EverMind-AI) describes an end-to-end trainable sparse attention layer over chunk-pooled KV caches. That is a neural artifact and is not portable to a pure-Rust MCP server. What is portable, and what this repo aims to deliver, is the MSA macro pattern:

1. Chunked storage of long-form text with a small fixed pool size (P=64 words by default, mirroring the paper).
2. Top-k sparse routing over chunks (BM25 surrogate; learned routing is out of scope).
3. Original text injection (paper §4.3, ablation -37.1% without): msa_search returns chunks, msa_fetch_doc returns the full document.
4. Memory Interleave as a protocol (planned v0.4): the AI client orchestrates multi-hop retrieval through repeated tool calls with a server-side cursor.

Design and rationale are documented in the project notes (negative results, gate methodology); see docs/NEGATIVE_RESULTS.md.

Benchmarks

Retrieval changes are decided on pre-registered, paired deltas with bootstrap confidence intervals — not on absolute scores. Workloads: HotpotQA (extractive QA), MLDR-it (long-doc retrieval, Italian), LongMemEval-S (500 conversational-memory questions). Full methodology, acceptance gates and refuted hypotheses live in docs/NEGATIVE_RESULTS.md.

Headline measurements:

• BM25 is the engine, not a placeholder. Three pre-registered attempts; no hybrid (BM25 + dense rerank) configuration beat the gate on these workloads. Dense rerank stays available (dense_alpha, off by default) for re-testing as encoders improve.
• Rich capsules at ingestion (deterministic enrich, no LLM): +7 to +20 recall@5 across every category.
• Original-text injection (msa_fetch_doc after msa_search): +14.6 F1 exactly on the stratum where snippets miss the content.
• Recency priors lose — handle time at serving, not in the retrieval score.

Reproduce:

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

Tool surface

Install

Prebuilt binary (recommended) — download the archive for your platform from the latest release, extract, and point your MCP client at the binary:

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/

Prebuilt targets (Linux + Android): x86_64-unknown-linux-gnu, x86_64-unknown-linux-musl, aarch64-unknown-linux-gnu, aarch64-unknown-linux-musl (edge / ARM / Termux), aarch64-linux-android.

macOS: no prebuilt binary is shipped (it would need Apple code-signing). Install from source instead — cargo install below compiles it on your Mac in one command, no signing needed.

From source (Rust toolchain) — --locked is required (the workspace Cargo.lock pins a working time / tantivy-common resolution; a fresh resolve breaks the build), and mcp-msa-server is the package name (the binary it installs is mcp-vl-msa-rs):

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

Build & test

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

Hybrid mode config

Add [embeddings] to MCP_MSA_CONFIG to activate dense rerank. Without this section the server stays in BM25-only mode even when the binary was built with --features embeddings.

The production backend is candle-modernbert: the encoder runs in-process (Candle), offline-deterministic, from a local model bundle — no daemon, no network at runtime, no automatic downloads. Prepare the bundle once with scripts/prepare-granite-r2-97m.sh.

[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"

A transitional backend = "ollama" (HTTP to an Ollama-compatible service) still exists but is deprecated and scheduled for removal in v0.6 — do not build new setups on it.

The AI client opts into hybrid scoring per-call by passing dense_alpha to msa_search (or any future tool that supports it). dense_alpha = 1.0 (default) is BM25-only; 0.0 is dense-only; intermediate values are a linear blend α·bm25 + (1-α)·((cos+1)/2). Cosine is shifted to [0,1] so it composes linearly with the already max-normalized BM25 score.

Run as 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

Example ~/.codex/config.toml entry:

[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"

Equivalent ~/.claude.json entry for Claude Code:

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

AI client compatibility