Code-Memory MCP (Rust Version)

Semantic code search for your local repositories, powered by SQLite Vector Search, AST-based chunking, and Parallel AI Cascading.

Find functions, classes, and logic across your codebase using natural language — 100% local, accurate, and resilient.

---

✨ Key Features

• 🔍 Hybrid Search (Vector + FTS5) — Fast local semantic retrieval using sqlite-vec combined with Full-Text Search (FTS5) and Reciprocal Rank Fusion (RRF) for maximum accuracy.
• 📦 AST-based Smart Chunking — Language-aware splitting (Python, JS, TS, Rust, Go, Java, Markdown) that preserves functional context using Tree-sitter.
• ⚡ Parallel AI Collaboration (Async Planning) — Support for non-blocking, asynchronous planning tasks that allow Worker and Mahaguru (planner) models to work in parallel.
• 🔄 Background Indexing — High-performance, non-blocking indexing of large folders with job monitoring and status tracking.
• 🧠 Session-based Chat Context — Automatically preserves and restores chat summaries per project to maintain context across sessions.
• 📏 Agent Rules Sync — Synchronizes specialized Antigravity/Cursor rules based on the detected project stack.
• 🛡️ Path Sandboxing — Secure file access with environment-based path validation.
• 🔌 MCP Protocol — Native integration as an MCP server for Claude Desktop, Cursor, Antigravity, and more.

---

🔌 MCP Tools Overview

The server exposes 13 powerful tools for AI agents to interact with your codebase:

Tool	Description
semantic_code_search	Hybrid search (Vector + FTS5 + RRF) with heuristic re-ranking.
index_folder	Initiates background indexing for a local project folder.
get_index_stats	Monitors active indexing and planning (Mahaguru) jobs.
list_indexed_projects	Lists all projects currently available in the index.
delete_project	Removes a project and its chat context from the index.
request_mahaguru_refinement	Synchronous escalation to a high-level planner (Mahaguru) model.
request_async_mahaguru_refinement	Non-blocking escalation; returns a Job ID for parallel workflows.
get_planning_job_result	Polls the result of an asynchronous planning/refinement job.
save_project_chat_context	Persists a summary of the current session context.
get_project_chat_context	Retrieves the last saved session context for a project.
sync_agent_rules	Updates .agents/rules based on the project's detected stack.
maintenance_prune	Removes stale entries for files that no longer exist on disk.
rebuild_index_database	Factory Reset: Clears the entire database (use with caution).

---

🚀 Quick Start

1. Requirements

• Rust 1.80+ (Stable toolchain via rustup).
• sqlite-vec (Binary vec0.dylib for macOS or equivalent for your OS must be in the binary directory).

2. Build

git clone <your-repo-url> mcp-code-search
cd mcp-code-search
cargo build --release

3. Run

Mode A: MCP Server (Stdin/Stdout) Best for Claude Desktop, Cursor, and other IDE integrations.

cargo run --release -- --mcp

Mode B: HTTP Management API Runs a REST API (default on port 8000) for managing the server.

cargo run --release -- --port 8000

Mode C: CLI Indexer One-off indexing without running a server.

cargo run --release -- --index /path/to/project

---

🔌 IDE & Client Integration

Claude Desktop / Cursor / Antigravity

Add the following configuration to your MCP settings. Using the provided run_mcp.sh is highly recommended as it ensures the binary is built and run from the correct root with all environment variables.

macOS / Linux

{
  "mcpServers": {
    "code-memory-rs": {
      "command": "/absolute/path/to/mcp-code-search-rs/run_mcp.sh"
    }
  }
}

[!TIP] Petunjuk Integrasi (Bahasa Indonesia): Gunakan file run_mcp.sh untuk memastikan server berjalan stabil di Claude/Cursor. Skrip ini akan otomatis menjalankan cargo build jika ada perubahan kode, memastikan binary terbaru selalu digunakan. Pastikan path yang Anda masukkan adalah path absolut.

---

🏗️ Architecture

• Engine: Pure Rust with tokio for async orchestration.
• Storage: SQLite (WAL mode) for reliable persistence.
• Search: sqlite-vec for vector embeddings + FTS5 for keyword matching, merged via Reciprocal Rank Fusion (RRF).
• Chunking: AST-aware logic using tree-sitter to preserve logical boundaries (functions, classes).
• Hardening: State-machine based balanced-brace JSON extraction for reliable processing of unpredictable AI outputs.
• Safety: Environment-variable driven path sandboxing (ALLOWED_PATHS).
• Observability: Integrated tracing spans and instrumented futures for deep visibility into async/sync execution boundaries.
• Resilience: Robust API retry logic with exponential backoff and circuit breaking for all LLM interactions.

---

📁 Project Structure

mcp-code-search/
├── src/                 # Rust source (Core, API, Indexer)
├── data/                # Database and persistent state
├── docs/                # Extended documentation suite
├── bin/                 # Helper scripts and utilities
└── Cargo.toml           # Package metadata

---

📄 License

MIT