io.github.DioNanos/mcp-memory-rs

CI Tests License: Apache-2.0 Rust Local First

Local-first MCP memory server in pure Rust. Persistent, versioned, queryable memory for AI agents — owned by the user, not by a platform.

State lives on your disk as plain JSON categories backed by SQLite (FTS5). Every write is versioned and backed up. A fleet of devices syncs through an optional HTTP endpoint with merkle manifests and optimistic concurrency. No cloud account, no embedding service, no network dependency in the default mode.

Why

Agent memory tied to a vendor dies with the vendor session. This server keeps the agent's long-lived state — identity, projects, infrastructure notes, per-device workflows — in files you can read, grep, diff, and back up yourself. Any MCP client (Claude Code, Codex, or anything speaking MCP stdio) gets the same memory; swapping the model does not lose the state.

Design choices that follow from that:

• Local-first: the stdio server works fully offline against local storage. Sync is a separate, explicit step — never a hidden dependency.
• Plain storage: one JSON file per category plus a SQLite index. The database can be rebuilt from the files; the files are the truth.
• Versioning by default: every write keeps history; deletes create a backup first. memory_history and memory_compact manage the tail.
• Concurrency-safe writes: expected_hash turns clobbering races between concurrent agents into explicit conflicts.
• Zero ML in the core: full-text search is SQLite FTS5 with BM25; memory_search_semantic adds an optional TF-IDF hybrid. No model downloads.

The pair: for corpus recall (chunked documents, BM25 retrieval, original-text injection) see the companion server mcp-vl-msa-rs. This server holds the curated agent state; that one holds the queryable corpus.

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

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-memory-rs-x86_64-unknown-linux-gnu.tar.gz
install -m755 mcp-memory-rs-*/mcp-memory-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 compiles it on your Mac in one command, no signing needed:

cargo install --git https://github.com/DioNanos/mcp-memory-rs --locked

--locked uses the committed Cargo.lock (reproducible build).

Quick start

cargo build --release

# stdio MCP server, offline mode (default)
./target/release/mcp-memory-rs

Claude Code (~/.claude.json) or any MCP client:

{
  "mcpServers": {
    "memory": {
      "command": "/path/to/mcp-memory-rs",
      "env": {
        "MCP_MEMORY_CONFIG": "/home/me/.config/mcp-memory-rs/config.toml",
        "MCP_MEMORY_REQUIRE_CONFIG": "1",
        "MCP_MEMORY_MODE": "offline",
        "MCP_DEVICE": "my-laptop"
      }
    }
  }
}

Codex (~/.codex/config.toml):

[mcp_servers.memory]
command = "/path/to/mcp-memory-rs"
env = { MCP_MEMORY_CONFIG = "/home/me/.config/mcp-memory-rs/config.toml", MCP_MEMORY_REQUIRE_CONFIG = "1", MCP_MEMORY_MODE = "offline", MCP_DEVICE = "my-laptop" }
# auto-approve read-only tools (memory_read/list/search/…); writes still gated
default_tools_approval_mode = "approve"

Configuration is TOML — copy config/example.toml to ~/.config/mcp-memory-rs/config.toml and adjust it. The server auto-discovers that XDG-style path. Environment variables override file values (MCP_DEVICE, MCP_MEMORY_MODE, MCP_MEMORY_DIR, …); managed deployments should set MCP_MEMORY_REQUIRE_CONFIG=1 so a missing config fails closed.

Memory model

Memory is organized in categories: named JSON documents (base, projects, my-laptop, workflow_my-laptop, …). Reads return the document plus metadata (content hash, size, last writer, timestamp). Writes replace the category or, with merge=true, patch it per top-level key.

Access control

Multi-device fleets get a small, explicit ACL ([acl] in the config):

Rule	Effect
admin_devices	Listed devices write everything.
device_categories	Device name writes category name and workflow_name — its own namespace only.
agent scope	Device foo-agent writes foo_* categories.
everyone	All devices read everything.

Unknown categories are denied for non-admin writers — fail closed.

Fleet sync

Each node runs local-first; one node (or any number) exposes the HTTP API as a sync remote. sync_manifest builds a merkle-rooted fingerprint of all categories; sync_diff compares manifests; memory_sync pushes dirty categories or pulls remote changes. Conflicts between nodes are resolved by the configured conflict_strategy (last-write-wins by default); expected_hash preconditions protect direct writes (MCP and HTTP), not the sync envelope.

The HTTP API is an admin/sync plane: the bearer token grants full access to every category. Per-category ACL applies on the MCP stdio surface, where the device identity is known locally; HTTP callers are identified only by the shared token, so no per-device ACL is enforced there.

The HTTP server requires MCP_MEMORY_TOKEN and refuses to start without it. Bind it to loopback (the default) and tunnel between nodes; do not expose it to the public internet.

MCP_MEMORY_TOKEN=<secret> ./target/release/mcp-memory-rs --http

Tool surface

Tool	Description
memory_read	Read a category (optional field filtering).
memory_write	Replace or merge-patch a category; versioned; expected_hash precondition.
memory_append	Append a timestamped entry to a bounded append-only log category; auto-prunes by max_entries/max_age_days. For event streams / session journals, so they don't bloat memory categories.
memory_delete	Delete a category (backup created first).
memory_list	All categories with hash/size/last-update metadata.
memory_search	FTS5 full-text search, BM25 ranking, category/date/actor filters, snippets.
memory_search_semantic	Hybrid TF-IDF + FTS5 search.
memory_history	Version history of a category.
memory_delta	Changes since a known hash (cheap polling).
memory_context	Multi-category warmup read, token-budget oriented.
memory_compact	Prune old versions and backups.
memory_status	Local-first status: dirty queue, manifest hash, last sync.
memory_doctor	Diagnostics: paths, database, categories, sync config.
sync_manifest	Merkle-rooted manifest of all categories.
sync_diff	Compare local vs remote manifest: push/pull/conflict sets.
sync_push / sync_pull	Export/import sync envelopes.
memory_sync	One sync step against the configured remote (push_dirty / pull_remote).

The same surface is available over HTTP (/api/v1/*) for non-MCP consumers; /health is unauthenticated, everything else requires the bearer token.

AI client compatibility

The server is built to be self-explanatory to a weak client model:

• At initialize it returns an instructions string describing the memory model and the entry-point tools. Some lightweight clients ignore this field; if your client never surfaces it, read the tool descriptions instead — they carry the same guidance (e.g. memory_read takes category, not key).
• Read-only tools are annotated readOnlyHint, so a client such as Codex can auto-approve them. On Codex, an unsupported call / user cancelled result usually means the tool-approval gate fired, not a server fault — set default_tools_approval_mode = "approve" (see the Codex snippet above).
• The server speaks the standard MCP handshake. A client must complete initialize and send notifications/initialized like any MCP client.

Storage layout

With no config and strict mode disabled, standalone base_dir remains ~/.memory for compatibility. The auto-discovered example config uses ~/.local/state/mcp-memory-rs (XDG-style). Config resolution is: explicit MCP_MEMORY_CONFIG, $XDG_CONFIG_HOME, $HOME/.config, legacy cwd-local memory-config.toml, then standalone defaults. Either way the layout is:

<base_dir>/
├── categories/   # one .json file per category — the source of truth
├── backups/      # automatic pre-delete/pre-overwrite backups
└── memory.db     # SQLite: FTS5 index, versions, sync state (rebuildable)

Building and testing

cargo build --release   # single static-friendly binary
cargo test              # unit + integration tests
cargo clippy --all-targets -- -D warnings

No build-time network access, no C dependencies beyond bundled SQLite.

License

Apache-2.0. See LICENSE.