rmcp_memex

Lightweight Model Context Protocol (MCP) server written in Rust. Provides a local RAG (Retrieval-Augmented Generation) toolset backed by embedded LanceDB vector storage and local embeddings via fastembed. Optional MLX HTTP bridge for Apple Silicon acceleration.

Features

• Vector Memory: Store, search, and retrieve text chunks with semantic similarity
• Document Indexing: Index UTF-8 text files and PDFs for RAG queries
• Namespace Isolation: Organize data into separate namespaces
• Health Monitoring: Built-in health tool for status checks
• Configuration Wizard: Interactive TUI for easy setup and host configuration
• MCP Compatible: Works with Claude Desktop, Codex, Cursor, and other MCP hosts

Quick Start

Installation

# Clone and build
git clone https://github.com/Loctree/rmcp-memex.git
cd rmcp_memex
cargo build --release

# Install to ~/.cargo/bin (optional)
cp target/release/rmcp_memex ~/.cargo/bin/

Or use the install script:

./scripts/install.sh
# For macOS app bundle:
./scripts/install.sh --bundle-macos

Run

# Default configuration (starts MCP server)
rmcp_memex

# Explicit serve subcommand
rmcp_memex serve

# With options
rmcp_memex --db-path ~/mydata/lancedb --log-level debug --cache-mb 2048

Configuration Wizard

Interactive TUI for setting up rmcp_memex and configuring MCP host integrations:

# Launch wizard
rmcp_memex wizard

# Dry-run mode (preview changes without writing)
rmcp_memex wizard --dry-run

The wizard will:

1. Auto-detect installed MCP hosts (Codex, Cursor, Claude Desktop, JetBrains, VS Code)
2. Guide you through memex configuration (database path, cache size, log level, mode)
3. Generate config snippets for selected hosts
4. Run health checks to verify setup
5. Optionally write configuration files (with backups)

Usage as Library

Add to your Cargo.toml:

[dependencies]
rmcp_memex = { git = "https://github.com/Loctree/rmcp-memex.git" }

Example: Direct RAG Pipeline Access

use rmcp_memex::{RAGPipeline, StorageManager, ServerConfig};
use std::sync::Arc;
use tokio::sync::Mutex;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Initialize storage
    let storage = Arc::new(StorageManager::new(4096, "~/.my_app/lancedb").await?);
    storage.ensure_collection().await?;

    // Create RAG pipeline (no MLX bridge)
    let mlx = Arc::new(Mutex::new(None));
    let rag = RAGPipeline::new(mlx, storage).await?;

    // Index text
    rag.memory_upsert(
        "my_namespace",
        "doc1".to_string(),
        "Important information to remember".to_string(),
        serde_json::json!({"source": "manual"}),
    ).await?;

    // Search
    let results = rag.memory_search("my_namespace", "important", 5).await?;
    for r in results {
        println!("{}: {} (score: {})", r.id, r.text, r.score);
    }

    Ok(())
}

Example: Run Full MCP Server Programmatically

use rmcp_memex::{run_stdio_server, ServerConfig};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let config = ServerConfig::default()
        .with_db_path("~/custom/lancedb");
    
    run_stdio_server(config).await
}

Exported Types

MCP Tools

Namespace Conventions

Namespaces provide data isolation and multi-tenancy. We recommend these naming patterns:

Best Practices

1. Use prefixes consistently — helps with retention policies and access control
2. Keep IDs URL-safe — avoid special characters; use alphanumeric + hyphen/underscore
3. Document your schema — maintain a mapping of namespace patterns in your project
4. Consider lifecycle — session:* for temporary, kb:* for persistent data

Examples

// Per-user memory
rag.memory_upsert("user:alice", "pref1", "Likes dark mode".into(), json!({})).await?;

// Shared knowledge base
rag.memory_upsert("kb:company-docs", "doc1", "Q4 report...".into(), json!({"type": "report"})).await?;

// Session-scoped (clean up after session ends)
rag.memory_upsert("session:abc123", "context", "Current task...".into(), json!({})).await?;
rag.purge_namespace("session:abc123").await?; // Cleanup

Configuration

CLI Options

Server Modes

# Memory-only mode (recommended for AI assistants)
rmcp_memex --mode memory

# Full RAG mode (default)
rmcp_memex --mode full

TOML Config File

mode = "memory"  # or "full"
db_path = "~/.rmcp_servers/rmcp_memex/lancedb"
cache_mb = 4096
log_level = "info"
max_request_bytes = 5242880
# features = "memory,search"  # Optional: overrides mode

CLI flags override config file values.

Environment Variables

MCP Host Configuration

Codex (~/.codex/config.toml)

[mcp_servers."rmcp_memex"]
command = "/path/to/rmcp_memex"
args = ["--db-path", "~/.rmcp_servers/rmcp_memex/lancedb", "--log-level", "info"]
startup_timeout_sec = 120

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "rmcp_memex": {
      "command": "/path/to/rmcp_memex",
      "args": ["--log-level", "info"]
    }
  }
}

Cursor / Other MCP Hosts

Use stdio transport with the binary path and desired arguments.

Library Usage

use rmcp_memex::{run_stdio_server, ServerConfig};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let config = ServerConfig::default()
        .with_db_path("/custom/path/lancedb");
    
    run_stdio_server(config).await
}

Architecture

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│   MCP Client    │────▶│   rmcp_memex     │────▶│    LanceDB      │
│ (Claude, Codex) │     │  (JSON-RPC/stdio)│     │  (embeddings)   │
└─────────────────┘     └──────────────────┘     └─────────────────┘
                               │
                               ▼
                        ┌──────────────────┐
                        │  fastembed/MLX   │
                        │   (embeddings)   │
                        └──────────────────┘

• Transport: Newline-delimited JSON-RPC over stdio
• Vector Store: Embedded LanceDB (no external DB required)
• Embeddings: fastembed (default) or MLX HTTP bridge
• Caching: moka (in-memory) + sled (persistent KV)

Development

# Format
cargo fmt

# Lint
cargo clippy --all-targets -- -D warnings

# Test
cargo test

# Build release
cargo build --release

Git Hooks

Install pre-commit and pre-push hooks:

./tools/install-githooks.sh

Pre-push runs: fmt check, clippy, tests, semgrep.

Requirements

• Rust: Stable toolchain
• OS: macOS, Linux (Windows untested)
• Protobuf: Build uses vendored protoc, but system protoc may be needed:
  • macOS: brew install protobuf
  • Linux: apt install protobuf-compiler

License

MIT — see LICENSE.

Links

• Repository: https://github.com/Loctree/rmcp_memex
• Changelog: CHANGELOG.md
• Loctree Integration: docs/LOCTREE_INTEGRATION_PROPOSAL.md