Riz Ashraf
2a25f17a32
- Removed heavy Tantivy index rebuild loop that ran every 5 seconds and rewrote entire graph to disk - Converted polling worker to lightweight IndexWriter committer - Fixed 67+ instances of unnecessary clone and string parsing overhead in tool return results - Deduplicated state graph modification methods
mcp-memory
A high-performance, persistent Knowledge Graph and Context daemon for Antigravity, implementing the Model Context Protocol (MCP). `
Overview
mcp-memory acts as the persistent "brain" for the agy CLI agents. It tracks entities, relations, background tasks, engineering debt, and architectural decisions across sessions. ` To eliminate heavy Cross-OS I/O penalties when using WSL and Windows simultaneously, mcp-memory operates using a Dual-Transport Leader/Stub Architecture:
- The Server (mcp-memory-server): Runs natively on the Windows host. It binds to .0.0.0:3000, serving standard stdio to the primary Windows agy instance while simultaneously hosting an Axum HTTP server for secondary clients.
- The Stub (mcp-memory-stub): An ultra-lightweight proxy binary. WSL agy instances run this native Linux stub, which transparently pipes stdio JSON-RPC traffic over the network to the Windows HTTP server (http://127.0.0.1:3000), completely bypassing WSL NTFS mounts. It features full MPSC queue buffering and a WebSocket reconnect handshake (notifications/tools/list_changed) so that tools automatically refresh seamlessly without disconnecting the CLI if the background server restarts. `
Quick Start & Usage
`
1. Windows Installation (The Server & Stub)
Compile the main daemon and lightweight stub natively for Windows:
cargo build --release
Copy-Item target\release\mcp-memory-server.exe C:\Users\reazul.ashraf\.local\bin\mcp-memory-server.exe
Copy-Item target\release\mcp-memory-stub.exe C:\Users\reazul.ashraf\.local\bin\mcp-memory-stub.exe
` Step 1: To bypass Antigravity's lazy-loading and ensure the server is instantly available for WSL, configure your PowerShell profile to auto-start the background server when you open a terminal:
# Add this to your PowerShell profile:
if (-not (Get-Process mcp-memory-server -ErrorAction SilentlyContinue)) { Start-Process -FilePath "C:\Users\reazul.ashraf\.local\bin\mcp-memory-server.exe" -ArgumentList "--daemon" -WindowStyle Hidden -ErrorAction SilentlyContinue }
Shutting Down: If you need to stop or restart the background daemon (e.g., to replace the executable after a recompile), you MUST NEVER use brute-force OS kill commands (e.g., Stop-Process, pkill, or kill). Instead, you MUST ALWAYS use the server's built-in graceful shutdown mechanisms:
- The CLI flag:
--exit(or--restart)
mcp-memory-server.exe --exit
- The HTTP endpoint:
POST http://127.0.0.1:3000/shutdown**Step 2:** Update your Windows ~/.gemini/config/mcp_config.json to point the CLI to the ultra-lightweight stub (since the server is already running in the background):json { "mcpServers": { "memory": { "command": "C:\Users\reazul.ashraf\.local\bin\mcp-memory-stub.exe", "args": [] } } }
2. WSL / Linux Installation (The Stub)
Compile the ultra-lightweight stub as a static Linux binary (from the Windows host):
powershell cargo zigbuild --target x86_64-unknown-linux-musl --release -p mcp-memory-stub wsl.exe -d Ubuntu -e bash -c "cp /mnt/c/Users/reazul.ashraf/workspace/rust/mcp-memory/target/x86_64-unknown-linux-musl/release/mcp-memory-stub ~/.local/bin/mcp-memory-stub && chmod +x ~/.local/bin/mcp-memory-stub"
Update your WSL ~/.gemini/config/mcp_config.json:json
{
"mcpServers": {
"memory": {
"command": "/home/riz/.local/bin/mcp-memory-stub",
"args": [
"--target", "http://127.0.0.1:3000",
"--wake-cmd", "/mnt/c/Users/reazul.ashraf/.local/bin/mcp-memory-server.exe --daemon"
]
}
}
}
*Note: The --wake-cmd ensures that if you start WSL while Windows is completely asleep, the Linux stub will use WSL interop to silently spin up the Windows daemon in the background before connecting.*
Push Safety Gates
The daemon also operates as a global safety gate for Git. Before pushing code, run:
ash mcp-memory gate verify
This queries the daemon (via HTTP) to confirm if pre-push validation (like running tests via PrePushAuditor) has been cleared by the agent.
`
Brain Monitor Dashboard
The server hosts a live, real-time SPA dashboard called the Brain Monitor.
To view the dashboard, simply navigate to the root endpoint in your browser while the server is running:
http://127.0.0.1:3000/
Dashboard Features:
- Interactive Knowledge Graph: A full physics-simulated network graph with node-type coloring, a drag-to-pan canvas, and an interactive Inspector Panel. Click any node to instantly view its stored observations.
- Actionable Kanban Board: Visually track all active agent Tasks. You can click 'Complete' directly from the UI to trigger a
POST /api/tasks/{id}/completeREST call back to the daemon without needing the CLI. - Sticky Notes & Search: Browse your ephemeral notes and utilize the integrated fuzzy-search bar to locate graph entities instantly.
- Native Dark Mode: Fully styled for modern development environments.
You can also programmatically query the live backing APIs:
curl http://127.0.0.1:3000/api/stats
curl http://127.0.0.1:3000/api/graph
curl http://127.0.0.1:3000/api/tasks
Further Reading
For a deep dive into the architecture, the Redb LSM-tree embedded database, tantivy indexing, and the HTTP SSE event loop, consult the design.md file in this repository.
Neovim Integration
The linux-nvim and win-nvim MCP servers provide direct Msgpack-RPC communication with Neovim.
For this to work flawlessly across multiple Neovim instances (even split across Windows and WSL), you must load the provided gemini-integration.lua file in your Neovim init.lua:
lua dofile("C:/Users/reazul.ashraf/workspace/rust/mcp-memory/gemini-integration.lua")
The "Last Focused Wins" Architecture
When you use the gemini-integration.lua script, Neovim acts as an active telemetry broadcaster. Whenever you alt-tab into a Neovim window (FocusGained) or switch files (BufEnter):
- Fallback Sync: Neovim instantly writes its unique Session ID (Named Pipe / Unix Socket) to ~/.gemini/active_nvim.txt.
- WebSocket Telemetry: Neovim pushes a JSON payload containing the active filename, cursor row, and column to the Rust server's /nvim/telemetry webhook.
- UI Broadcast: The Rust server updates the global state and broadcasts this over WebSockets (/ws) so that the Brain Monitor Dashboard can animate your active file live in the UI!
Neovim MCP Tools
The LLM agent interacts with your active Neovim session using a dedicated set of MCP tools. (Note: /nvim/telemetry is strictly a one-way webhook for Neovim; the LLM uses the tools below to interact).
- vim_goto_line: Open files and jump cursors directly from the LLM.
- vim_set_diagnostics: Push inline code review warnings as virtual text.
- vim_get_active_buffer: Read live, unsaved buffer contents.
- vim_get_cursor: Fetch precise line/column coordinates.
- vim_get_visual_selection: Read highlighted code blocks.