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](docs/NEGATIVE_

... View full README on GitHub