Reazul Ashraf
67b6a0407e
- Created linux-nvim and win-nvim MCP servers for deep Neovim Msgpack-RPC integration. - Implemented tools: nvim_goto_line, nvim_get_active_buffer, nvim_get_cursor, nvim_get_visual_selection, nvim_set_diagnostics. - Added gemini-integration.lua for active UI socket discovery. - Updated build.cmd to cross-compile for both Windows (gnu) and Linux (musl). - Updated README, design.md, and instructions.md with architecture and tool capabilities.
100 lines
5.2 KiB
Markdown
100 lines
5.2 KiB
Markdown
# 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.
|
|
`
|
|
## Quick Start & Usage
|
|
`
|
|
### 1. Windows Installation (The Server & Stub)
|
|
Compile the main daemon and lightweight stub natively for Windows:
|
|
```powershell
|
|
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:
|
|
```powershell
|
|
# 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 the background daemon (e.g., to replace the executable after a recompile), use the built-in `--exit` flag instead of forcefully killing the process.
|
|
```powershell
|
|
mcp-memory-server.exe --exit
|
|
```
|
|
`
|
|
**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 HTML dashboard called the **Brain Monitor**. It visually tracks the metrics of your Antigravity knowledge graph, such as the total count of Entities, Relations, Tasks, Snippets, and Architectural Decisions (ADRs).
|
|
|
|
To view the dashboard, simply navigate to the root endpoint in your browser while the server is running:
|
|
`http://127.0.0.1:3000/`
|
|
|
|
You can also programmatically query these live metrics via the API endpoint:
|
|
`curl http://127.0.0.1:3000/api/stats`
|
|
|
|
## Further Reading
|
|
For a deep dive into the architecture, Write-Ahead Logging (WAL), locking mechanisms, 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, you must add the provided `gemini-integration.lua` file to your Neovim `lua/` configuration directory and require it in your `init.lua`:
|
|
```lua
|
|
require('gemini-integration')
|
|
```
|
|
This script allows Neovim to broadcast its active socket to `~/.gemini/active_nvim.txt` when it gains focus, allowing the MCP servers to bridge the connection.
|
|
|
|
These MCP servers provide the following two-way integration tools:
|
|
* **`nvim_goto_line`**: Open files and jump cursors directly from the LLM.
|
|
* **`nvim_set_diagnostics`**: Push inline code review warnings as virtual text.
|
|
* **`nvim_get_active_buffer`**: Read live, unsaved buffer contents.
|
|
* **`nvim_get_cursor`**: Fetch precise line/column coordinates.
|
|
* **`nvim_get_visual_selection`**: Read highlighted code blocks.
|