Rms Memory MCP

🧠 RMS Memory MCP

Version: 1.3.0 (2026-10-13) · companion GUI 1.3.0 (unified numbering)

Persistent, local-first memory for your AI coding agents.

Stop re-explaining your architecture to Cursor, Zed, and Claude Code and other IDEs every single session.

[]()

Features • Download • Install • Quick Start • CLI • MCP Tools • Architecture

---

---

The Problem

You're developing a single project but switching between different agents — Cursor, Zed, Claude Code, OpenCode, etc. Every one of them loses context of architectural decisions, system requirements, and user preferences the moment you close the tab. You end up re-explaining the same things over and over, or copy-pasting a stale CLAUDE.md between tools.

RMS Memory MCP bridges this gap: a single, isolated, centralized Markdown vault — perfectly structured for LLM consumption — that any MCP-compatible IDE can read from and write to.

🖥️ Prefer a GUI over raw Markdown?

RMS Memory GUI turns your vault into a visual workspace — full graph editor, per-project Git & GitHub sync, one-click Doctor repair, and an AI-assisted Wiki generator (bring your own key). One-time desktop app, works on top of everything below. The MCP server stays 100% free and standalone either way.

✨ Key Features

📦 Installation

Option 1: Homebrew (macOS Apple Silicon & Linux)

brew tap max-ramas/tap
brew install rms-memory-mcp

Installs a prebuilt binary — no Rust toolchain required. The formula updates automatically with every release.

Not covered by Homebrew: macOS Intel (dropped as of v1.0.1) and Windows (Homebrew doesn't run there — use Option 2 or the .zip below).

Option 2: GitHub release binary

Prebuilt binaries for aarch64-apple-darwin (Apple Silicon), x86_64-unknown-linux-gnu, aarch64-unknown-linux-gnu, and x86_64-pc-windows-msvc are published on every release, along with .deb/.rpm packages for Linux. One-line installers auto-detect your architecture:

curl -fsSL https://raw.githubusercontent.com/max-ramas/rms-memory-mcp/master/scripts/install.sh | bash

irm https://raw.githubusercontent.com/max-ramas/rms-memory-mcp/master/scripts/install.ps1 | iex

Option 3: Build from Source

# 1. Clone the repository
git clone https://github.com/max-ramas/rms-memory-mcp.git
cd rms-memory-mcp

# 2. Build the optimized release binary
cargo build --release

# 3. Add the binary to your global PATH
cp target/release/rms-memory ~/.cargo/bin/

crates.io (cargo install)

As of 1.1.0+, tag push publishes only the umbrella crate rms-memory-mcp to crates.io. Internal workspace members (rms-memory-core / index / vault / cli) stay publish = false (path deps for local builds and the companion GUI). Release packaging flattens those crates into a staging tree via scripts/flatten-for-crates-io.py before cargo publish (as of 1.1.1 the staging tree also inlines rms-memory-cli) — see docs/crate-split.md.

cargo install rms-memory-mcp
# Prefer Homebrew or a GitHub release binary if you want a pinned installer.

Optional RMS Memory GUI installers

The companion RMS Memory GUI is a paid, optional Tauri desktop control plane: a visual Markdown/graph editor, per-project and Vault-wide Git/GitHub sync, a Doctor dashboard with one-click repair, an AI-assisted organizer and Wiki generator (bring your own key, proposal-only), and cross-tool spend tracking. The MCP server remains fully standalone: it does not require the GUI, an AI provider, or a GUI license to index, search, sync or serve MCP clients.

See GUI-README.md for the full feature breakdown, supported platforms, installer verification and release-distribution policy.

GUI source is private, but desktop installers are published as binary assets on this repository's GitHub Releases under the matching v<version> tag. Until Apple/Windows signing certificates exist, macOS builds may be unsigned — see GUI-README.md for Gatekeeper notes. The private GUI workflow transfers only the completed .dmg, .msi/.exe, .AppImage, .deb, and .rpm installer files (plus SHA256SUMS.txt when present). With updater signing enabled, the GUI pipeline mirrors signed latest.json, companion .sig files, and macOS *.app.tar.gz onto this public release (URLs rewritten to rms-memory-mcp; in-app Install reads …/releases/latest/download/latest.json). It never mirrors GUI source, build logs, credentials, or private GUI release archives. The same publication flow runs for a v* GUI tag and for a manually dispatched, version-validated GUI release.

🚀 Quick Start

The fastest way to get every IDE on your machine connected:

rms-memory install

This scans ~/.config/ and ~/Library/Application Support/ and hooks rms-memory directly into Cursor, Zed, Claude Code, OpenCode, and others — no manual JSON editing.

Generated Wiki namespace

The optional desktop GUI writes human-readable Wiki pages to <vault>/wiki/. RMS Memory MCP remains AI-free and treats this directory as generated output rather than canonical memory. A shared case-insensitive path policy (src/path_policy.rs, also reused by the GUI) excludes the entire namespace from Markdown/code indexing, vector and full-text retrieval, watchers, the durable graph and Wiki context packs. Write isolation matches that policy: rms_write requires .md and rejects wiki/**; canonical DocumentService list/read/write APIs exclude or reject wiki; Wiki page mutations use wiki-safe methods that skip memory audit-frontmatter injection. Linked-document link: resolution always re-checks that the canonical target stays inside the vault. Full or incremental sync removes legacy Wiki-derived records by path without deleting the files, and doctor reports the isolation state explicitly.

For virtual projects without a filesystem path (threads, leads, etc.), use --scope:

rms-memory --scope "thread:abc-123" serve

Use multiple isolated scopes

A scope is an isolation boundary for a vault and its index. Without --scope, RMS Memory uses the canonical current working directory; an explicit filesystem path addresses that same kind of project vault. Any other non-empty identifier creates an isolated virtual vault:

rms-memory serve                                      # current project scope
rms-memory --scope "/home/user/my-project" serve     # explicit project scope
rms-memory --scope "thread:abc-123" serve             # virtual thread scope
rms-memory --scope "product:acme" serve                # virtual product scope

For project knowledge plus per-thread history, query each scope explicitly and merge the results in the caller. RMS Memory intentionally does not mix scopes implicitly. Scope IDs may not be empty or exceed 512 characters; absolute and .//../ values are resolved as paths, while all other values are opaque identifiers.

When using min_confidence, start with an unfiltered search. Use 0.3–0.5 for broad refinement and reserve 0.7+ for verified canonical facts; records without a confidence value remain visible.

Configure your vault

The simplest way to configure the server is to run the interactive setup wizard. You don't need to memorize any CLI flags — just run:

rms-memory config

(Alternatively, set the vault root directly with rms-memory config --vault-path ~/MyVaults/, then run rms-memory init in each repository you want to register.)

Register a repository explicitly from its root before connecting IDE agents:

cd /path/to/project
rms-memory init

This creates the project mapping in ~/.rms-memory/registry.toml and provisions its isolated, structured vault. Routine MCP discovery is read-only and fail-closed: it never creates a project from /, never falls back to a shared global vault, and never guesses between multiple registered projects.

~/MyVaults/
  └── <ProjectKey>/
      ├── rules/
      ├── decisions/
      ├── architecture/
      ├── artifacts/
      ├── docs/
      └── api/

Optional semantic code memory

Markdown memory remains the default corpus. Semantic source indexing is separate, supports all bundled language adapters, and never changes source files:

rms-memory reindex --code  # build/update only derived code memory
rms-memory reindex --all   # refresh Markdown vault + code memory

Registered projects support code_index_mode = "off" | "manual" | "watch"; the default is off. Set it from the project root with rms-memory config --code-index-mode watch (or add --scope <project-path>). watch is explicitly opt-in, coalesces supported source saves for three seconds, and reindexes only the dirty paths (try_index_code_paths) with a full-walk fallback when the index is cold, the dirty set is empty/oversized (>200), or the watcher channel overflows. Concurrent IDE processes share a completion marker so an unchanged workspace stays idle. Code search results include their source language.

Perf smoke for large fixtures: ./scripts/bench_large_vault.sh [notes] [code_files].

Language selection is project-scoped and defaults to every bundled adapter:

rms-memory config --code-languages auto
rms-memory config --code-languages go,typescript,tsx,vue

Supported names are rust, go, javascript, jsx, typescript, tsx, python, c, cpp, java, ruby, swift, vue, csharp, php, kotlin, sql, html, and css. Generated paths (node_modules, .next, .nuxt, target, vendor, and coverage) are always excluded. Ambiguous .h files are indexed as C exactly once; use .hpp, .hh, or .hxx for C++ headers. Vue indexes only inline JavaScript/TypeScript <script> contents and maps results back to the .vue host file; templates, styles, script setup macros, and external src scripts remain outside v1.0.5 semantic extraction. HTML files contribute inline JavaScript <script> blocks (mapped back to the .html file) and elements with an id; CSS files contribute rule sets by selector and @keyframes. SQL files contribute CREATE TABLE / VIEW / TYPE / FUNCTION / PROCEDURE / TRIGGER statements.

Use an existing Obsidian vault

rms-memory projects attach-obsidian ~/Obsidian/Notes --key notes   # in place, read-only
rms-memory import --obsidian ~/Obsidian/Notes --dry-run             # or copy into this project's vault

An attached vault is indexed and searchable (pass project: "notes"), but RMS Memory never creates, edits, moves or deletes files in it: rms_write, checkpoints, prune and hooks refuse, and projects remove only drops the registration. The index lives under ~/.rms-memory/dbs/ like any other. Obsidian links ([[Note]], [[Note|label]], [[Note#Heading]], ![[image.png]], frontmatter aliases) resolve in the graph, the index and doctor.

Embedding model and retrieval eval

The default model is multilingual-e5-small (384 dimensions, downloaded once). To compare it with others on your own notes and switch:

rms-memory embedding list
rms-memory embedding eval --models multilingual-e5-small,bge-m3 --show-misses
rms-memory embedding use bge-m3              # or: ollama:nomic-embed-text (local Ollama)

eval turns each note's first heading into a query (or reads --queries file.jsonl with {"query": "...", "expect": ["path.md"]} lines) and reports hit@1, hit@k and MRR for embeddings alone and for hybrid search. Each model keeps its own index under the project's dbs/ folder, so switching back reuses the old one. After use, restart running MCP servers (IDE, GUI); the next sync builds the new index. Ollama URLs must be loopback (http://127.0.0.1:11434 by default).

🛠 CLI Commands

🔌 MCP Tools Exposed

Tool descriptions are written to be action-oriented, so agents use the vault proactively without being asked.

ToolPurposeInput

rms-memory_rms_search Searches Markdown memory by default. Set corpus to code or all; all uses Reciprocal Rank Fusion. Pass projects: [key, …] for read-only cross-project federation (when both project and projects are set, projects wins); vault/all with len>1 requires cross_project_vault=true on every listed key (hard fail — no silent degrade). Returns an inject/abstain decision envelope (decision, reason, injected_ids, optional retrieval_mode). Optional include_file_history / include_graph_neighbors enrich hits (not with federated projects). Agents are instructed to call this first. { query, project?, projects?, corpus: vault|code|all, limit, include_content, min_confidence, max_chars?, min_score?, include_file_history?, include_graph_neighbors? }

rms-memory_rms_code_search Convenience endpoint for the derived semantic code index. Results include file, symbol, kind, line range, and segment index. Same optional projects: […] federation as rms_search (code-only; does not change the active bind). Optional include_graph_neighbors. { query, project?, projects?, limit, include_content, include_file_history?, include_graph_neighbors? }

rms-memory_rms_read Reads the full contents of a document found via rms_search. { path, project? }

rms-memory_rms_write Persists new decisions, constraints, or rules. Agents are prompted to call this proactively after solving a tricky bug or learning a preference. Auto-injects audit metadata. Optional soft supersede of a prior note. Optional dry_run previews create/update/noop without disk or index side effects. Content or source containing a known token format or private key is refused (kind + line, never the value). { path, project?, content, mode: replace|append|create, confidence, source, status?, supersedes?, dry_run? }

rms-memory_rms_file_history Derived code_path git file→commit history (no shell). Lazy catch-up; action=reindex requires explicit project (after force-push). Prefer over git log. Search may set include_file_history for the last 3 commits on code hits (not with projects federation). { path?, project?, limit?, include_message?, action?: query|catch_up|reindex }

rms-memory_rms_graph Durable knowledge graph for agents: status/ensure/neighbors/path/snapshot/semantic/export_dot; create_edge and suppress/restore overrides (mutations require explicit project). Refreshed on sync and immediately after rms_write (write response includes graph_refresh). Visual GraphView remains GUI-only. Also available as CLI rms-memory graph. { action?, project?, node?, path?, from?, to?, source?, target?, relation?, edge_key?, override_action?, force?, limit?, max_depth?, … }

rms-memory_rms_doctor Eight-point vault health report (structure, IDs, links, LanceDB, wiki isolation, registry, freshness, stored credentials) plus notices for a newer release or a replaced server binary. repair_frontmatter requires explicit project. { project?, repair_frontmatter? }

rms-memory_rms_reindex Full vault/code/all index rebuild. Requires explicit project. { project, corpus?: vault\|code\|all }

rms-memory_rms_sync Incremental vault index sync (prefer over reindex for routine catch-up). { project? }

rms-memory_rms_projects Lists registered project keys even when the MCP client did not supply workspace roots. {}

rms-memory_rms_overview Structured orientation for exactly one project: counts by folder/status, recent notes, active checkpoints, coverage metadata, index lag (modified/new/removed files) and the code repository's git state (branch, HEAD, ahead/behind, changed file names — never diff contents). Fail-closed scoping; never aggregates across projects. Returns structuredContent + JSON text. { project?, recent_limit? }

rms-memory_rms_checkpoint_save / done / load / query Session continuity on plain Markdown (artifacts/checkpoints/): save goal/pending/links before context compaction, list or load active checkpoints on resume, close with a summary — closing writes a durable session note under artifacts/sessions/ and drops the checkpoint out of default recall. goal/pending/summary get the same credential refusal as rms_write. { name, project?, goal?, pending?, links?, summary?, status? }

rms-memory_rms_system_instructions Returns the canonical memory-usage protocol (search-first, persist, continuity) so agents can self-bootstrap without injected rule files. { project? }

rms-memory_rms_wiki_pack Builds a deterministic Wiki context pack from vault/code sources (manifest-driven). Writes under wiki/.generation/; does not call cloud LLMs. { project?, manifest? }

rms-memory_rms_prune Archives aged status: superseded notes under artifacts/pruned/YYYY-MM-DD/ with a JSONL manifest. Safe by default: apply is false (dry-run). Never deletes. Skips pinned, wiki, trash, and prior prune batches. Distinct from gc and from supersession marking. { project?, older_than_days?, apply? }

rms-memory_rms_hygiene Read-only consolidation report: near-duplicate notes (embedding similarity confirmed by shared word 3-grams), identical notes, checkpoints untouched for 14+ days, session notes older than 90 days. The agent merges with rms_write + supersedes and closes checkpoints with rms_checkpoint_done. { project?, min_similarity? }

MCP resources (1.3.0): rms://<project>/overview, rms://<project>/instructions, rms://<project>/checkpoint/<name> and rms://<project>/note/<path> are read-only views for clients that attach context by URI. MCP prompts: session_start, save_progress (name) and record_decision (topic).

The server resolves an explicit scope or legacy rootUri, then negotiates MCP roots/list. If a client exposes neither (or opens several registered roots), pass the short registry key in project; injected agent rules contain the correct key for that repository. rms_projects lists valid keys without requiring a bound workspace. An explicit project on any tool call always wins and rebinds the active vault — one long-lived MCP process can serve every registered project. Without project, ambiguity stays fail-closed (no silent pick-first).

To remove an accidental registration without deleting its Markdown vault:

rms-memory projects remove <key>

If the repository folder was moved or renamed, do not recreate .git or re-run init from scratch. Plan and apply a migrate instead:

rms-memory projects migrate --project <key> --to /new/path/to/repo --dry-run
rms-memory projects migrate --project <key> --to /new/path/to/repo
rms-memory projects resolve-key --path /new/path/to/repo

The CLI command projects remove is intentionally non-destructive. The companion GUI exposes a separate Delete project and data action for permanent cleanup of the registration, Markdown vault, and derived index. It requires typing the exact project key and accepts only a dedicated child of the configured master vault; the repository source path is explicitly excluded from deletion.

🏗 Architecture Highlights

Cargo workspace (v1.0.9+ / 1.1.1)

Implementation lives in path-only crates under crates/ (rms-memory-core, rms-memory-index, rms-memory-vault, rms-memory-cli for cycle-free gc/prune). The published product remains the root umbrella rms-memory-mcp (binary + MCP server + tools + rules injector + serve), which re-exports every former rms_memory_mcp::<module> path so the companion GUI keeps stable imports. Heavy deps (lancedb, ort, fastembed, tree-sitter) concentrate in rms-memory-index. Details: docs/crate-split.md.

Unified Configuration & Knowledge Isolation

A central ~/.rms-memory/registry.toml routes every project to an isolated vault, computed from a hash of the project path. No .mcp files, no per-repo config — global MCP entries (e.g. Zed's settings.json) can target any workspace automatically.

Safe Project Lifecycle

The transport-neutral ProjectService is the single implementation used by the CLI and companion GUI. Registry mutation remains revisioned through ConfigManager; deletion validates canonical paths before unregistering and returns structured warnings if filesystem cleanup cannot be completed.

Linked Documents (zero-copy import)

Instead of duplicating existing docs into the vault, rms-memory import can create lightweight Link Files — Markdown stubs with a link: <path> frontmatter property. Reads/writes are transparently redirected to the source file, while the vector index still respects the vault's directory structure.

Hybrid Search (LanceDB + Tantivy)

Embedded LanceDB (~/.rms-memory/dbs/) combines vector similarity with full-text search, so a query never comes back empty just because the exact keywords didn't match.

Separate Markdown and Code Corpora

Human-authored Markdown and derived Rust code live in separate tables. Code chunks carry stable symbol identities, line ranges, and preambles; unchanged chunks reuse their vectors. corpus=all fuses independently ranked result sets with Reciprocal Rank Fusion, avoiding any assumption that distances from the two corpora are comparable.

Graph-ready Knowledge Core

Graph nodes and edges are deliberately independent of retrieval chunk boundaries. Markdown links, Rust imports, trait implementations, and lexical call hints can be reconciled as derived relationships; user-created edges and suppress/restore overrides persist across reindexing. Current Rust call edges are syntax-level hints, not a compiler-accurate call graph.

AST-Aware Chunking

pulldown-cmark parses the Markdown AST directly. Chunks are built by walking up to the parent heading, with a strict 1500-character boundary and ~200-character overlapping window for oversized code blocks — no mid-sentence truncation.

Ten-Point Production Resiliency

1. Path traversal + filter injection prevention
2. Zombie process prevention (watcher shutdown on EOF + std::process::exit(0))
3. Graceful shutdown (SIGINT/Ctrl+C handler)
4. macOS sandbox bypass for fastembed model downloads
5. rms-memory gc — orphaned vector store pruning
6. PID-aware per-project writer lock and read-only background synchronization across IDE processes
7. Markdown watcher plus an explicitly opt-in, 3s-debounced code watcher with path-scoped reindex and shared-generation suppression
8. Write-guard snapshotting with rolling .bak backups (default: 5)
9. Isolated telemetry logging (~/.rms-memory/rms.log)
10. llms.txt export for flat, decoupled LLM ingestion

Validated v1.0.5 Multi-IDE Behavior

Live MCP requests have been verified for rms_search(corpus=vault|code|all) and rms_code_search. On this repository, reindex --code indexed 43 Rust files into 298 semantic items and 438 segments with all vectors reused on an unchanged run. An isolated five-server watcher run coalesced rapid saves into one shared completion-marker update; a later real-project stress gate completed concurrent GeoMail, License Server, RMS Monitoring, and GeoTax Site indexing, then seven MCP servers (after four IDE restarts) stayed at 0.0% CPU with no background reindex.

🧩 Supported IDEs

📄 License

MIT License — see LICENSE for details.

---

Built by Maksim Ramzaev · RMS Digital Services