Local-first memory for agents Single Rust Binary

Every fact it holds, and every fact it decided not to hand over.

MemVault stores what you give it and explains what it hands back. One binary, no service to operate, no cloud egress, no network unless you ask for one.

The Macro Problem Pathos

Stateless models, opaque cloud caches, and silent amnesia.

Language model calls are pure functions of their context window. Everything learned in a previous session vanishes unless written down outside. The common workarounds fail silently: truncation discards critical context, rolling summarisation burns expensive tokens while blurring specifics, and giant context windows drive latency and degrade middle-attention.

When teams adopt cloud memory microservices, they trade amnesia for three harder problems:

How It Works Divisio

Two indexes, fused by rank, packed to a budget.

A vector index (usearch) and a keyword index (tantivy) answer every query independently. Their ranks are fused via Reciprocal Rank Fusion (RRF), weighted by decay, and packed to fit the token budget you set.

The write path only ever appends. The read path queries both indexes, fuses their ranks, and writes its own decision back into the ledger, which is why an old retrieval can be replayed instead of re-run.

Cryptographic Erase Confirmatio

Erase a fact and the chain still verifies.

An append-only ledger appears to forbid deletion, while privacy compliance mandates it. MemVault resolves this through cryptographic erase: every record is encrypted with its own key.

When you call forget, the engine destroys the key. The ciphertext becomes mathematically unrecoverable, the content hash and sequence position remain intact, and verify confirms the ledger was never tampered with.

Bitemporal Mechanics Two Clocks

What was true, and what the engine believed.

Two clocks, both queryable. Ask what held in the real world at a moment (Valid Time), or ask what MemVault believed held at that moment (Belief Time). They are not the same question, and a memory engine that conflates them cannot explain past decisions.

Run It Four Surfaces

Four ways in, one engine behind them.

An MCP server over stdio, the standalone CLI, Python in-process, and an optional gRPC surface. Every one of them returns the exact same provenance.

{
  "mcpServers": {
    "memvault": {
      "command": "/absolute/path/to/memvault/target/release/memvault-server",
      "args": ["/absolute/path/to/my-memory"]
    }
  }
}

memvault --data-dir ./my-memory write --namespace project \
  --content "the deploy script lives in ops/deploy.sh"

memvault --data-dir ./my-memory search --namespace project \
  --query "deploy script" --max-tokens 20

memvault --data-dir ./my-memory explain <retrieval_id>
memvault --data-dir ./my-memory verify
memvault --data-dir ./my-memory forget <fact_id> --reason "customer deletion request"

# a wheel for each platform is attached to every release
pip install https://github.com/swap-mitra/memvault/releases/download/v0.2.0/memvault-0.2.0-cp39-abi3-manylinux_2_28_x86_64.whl

import memvault

mv = memvault.MemVault("./my-memory")
fact_id = mv.write("project", "the deploy script lives in ops/deploy.sh")

result = mv.search("project", "deploy script")
for f in result.injected:    # what goes in context, best first
    print(f.fact_id, f.content)
for e in result.candidates:  # why: every candidate considered
    print(e.fact_id, e.outcome, e.final_score, e.token_cost)

mv.verify()  # raises if the chain is broken

cargo build -p memvault-server --features grpc

MEMVAULT_GRPC_ADDR=127.0.0.1:50051 \
  ./target/debug/memvault-server ./my-memory

Known Limits Refutatio

Stated plainly, because each one otherwise looks like a bug.

Install MemVault as an MCP server for this project.

Prerequisites, check both before you start and stop if either is missing:
Rust 1.85 or newer (the workspace is edition 2024), and a C++ toolchain,
because the vector index builds from source. (If either is missing, the
release page at https://github.com/swap-mitra/memvault/releases has a
prebuilt archive per platform; unpack it and skip step 1.)

1. git clone https://github.com/swap-mitra/memvault
   cd memvault
   cargo build --release

2. If the build fails, stop and report the error to me verbatim. Do not
   improvise a fix, and do not substitute another memory tool.

3. Write .mcp.json in my project root. Use absolute paths for both the
   binary and the data directory, because the server inherits whatever
   working directory the client launched it from:

   {
     "mcpServers": {
       "memvault": {
         "command": "<abs path>/target/release/memvault-server",
         "args": ["<abs path>/my-memory"]
       }
     }
   }

4. Tell me to restart the client, then prove the round trip: call
   memory_write with namespace "project" and some fact about this repo,
   call memory_search for it, and report the retrieval_id and each
   candidate's outcome you got back.

chain verified from seq 0 MIT OR Apache-2.0 · github.com/swap-mitra/memvault