🧠 RMS Memory MCP

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.

✨ 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: Cargo

If you have Rust installed:

cargo install rms-memory-mcp

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/

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 (install.sh / install.ps1) auto-detect your architecture.

🚀 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.

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, you can pass flags directly: rms-memory config --vault-path ~/MyVaults/ --auto-add true)

The next time you open a project in a connected IDE, the server reads the rootUri from the MCP initialize handshake and provisions a clean, structured vault:

~/MyVaults/
  └── <ProjectHash>/
      ├── 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 coordinates concurrent IDE processes so an unchanged workspace stays idle. Code search results include their source language.

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, and vue. 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.

🛠 CLI Commands

🔌 MCP Tools Exposed

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

🏗 Architecture Highlights

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.

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.

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.

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 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.

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.

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 Rust code watcher with 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

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.