Update docs with correct server/stub binary roles

README.md

@@ -1,29 +1,29 @@
 # 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
+```powershell
 cargo build --release
-Copy-Item target\release\mcp-memory-server.exe C:\Users\reazul.ashraf\.local\bin\mcp-memory.exe
+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
+```powershell
 # Add this to your PowerShell profile:
-if (-not (Get-Process mcp-memory -ErrorAction SilentlyContinue)) { Start-Process -FilePath "C:\Users\reazul.ashraf\.local\bin\mcp-memory.exe" -WindowStyle Hidden -ErrorAction SilentlyContinue }
+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 }
+```
 `
-
 **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
 {
@@ -35,14 +35,14 @@ if (-not (Get-Process mcp-memory -ErrorAction SilentlyContinue)) { Start-Process
   }
 }
 `
-
+`
 ### 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
 {
@@ -51,20 +51,20 @@ Update your WSL ~/.gemini/config/mcp_config.json:
       "command": "/home/riz/.local/bin/mcp-memory-stub",
       "args": [
         "--target", "http://127.0.0.1:3000",
-        "--wake-cmd", "/mnt/c/Windows/System32/cmd.exe /c start /B C:\\Users\\reazul.ashraf\\.local\\bin\\mcp-memory.exe"
+        "--wake-cmd", "/mnt/c/Windows/System32/cmd.exe /c start /B 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.
-
+`
 ## 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.

design.md

@@ -63,8 +63,8 @@ econcile_worker) on a 5-second polling loop responsible for:
 
 ## 8. The Gate System (Push Safety Verification)
 The binary includes dedicated CLI subcommands (gate set and gate verify) that interact with a persistent gates.json store to enforce safety policies (like ensuring tests pass before a git push).
-*   **mcp-memory gate set**: Records an authorization status (authorized, blocked, or pending) for a specific target and namespace, alongside optional failure reasons and parameters.
+*   **mcp-memory-stub gate set**: Records an authorization status (authorized, blocked, or pending) for a specific target and namespace, alongside optional failure reasons and parameters.
-*   **mcp-memory gate verify**: Evaluates a pending action against the gate store. It returns exit code  if authorized, 1 if explicitly blocked, and 2 if no gate record exists. It also supports a --consume flag to immediately revoke the authorization after a successful check.
+*   **mcp-memory-stub gate verify**: Evaluates a pending action against the gate store. It returns exit code  if authorized, 1 if explicitly blocked, and 2 if no gate record exists. It also supports a --consume flag to immediately revoke the authorization after a successful check.
 
 ## 9. Operational Configuration & Paths
 The physical storage location of the knowledge graph and all persistent stores is strictly controlled by the MCP_MEMORY_STORE_DIR environment variable.
@@ -86,21 +86,14 @@ With the introduction of the Dual Transport System, the daemon must safely handl
 *   **Locking Mechanism:** The unified Knowledge Graph and modular Store<T> components are protected by RwLock primitives. 
 *   **Safe Mutation:** Store modifications utilize closure-based modify(|store| { ... }) methods to ensure locks are safely acquired, mutations applied, and file writes executed sequentially without deadlocking the asynchronous Tokio runtimes.
 
-## 12. Lifecycle & Startup Management (Leader/Stub Architecture)
+## 12. Lifecycle & Startup Management (Server/Stub Architecture)
 The mcp-memory daemon employs a self-healing, morphing Server/Client paradigm to allow multiple concurrent agy sessions without port collisions or file lock contention.
 
-### The Windows Morphing Daemon (Leader vs. Stub)
+### The Windows Background Daemon
-Every time a Windows agy session starts, it blindly spawns mcp-memory.exe as a stdio subprocess. On startup, the binary evaluates its environment:
+Every time a Windows gy session starts, it blindly spawns mcp-memory-stub.exe as a proxy. The proxy expects the mcp-memory-server.exe daemon to be running natively on port 3000.
-*   **The Leader (Server):** The binary attempts to bind to .0.0.0:3000. If successful, it becomes the Leader. It initializes the file locks, starts the Axum HTTP server, and natively processes the stdio input from its parent agy session.
-*   **The Stub (Proxy Client):** If port 3000 is already in use, the binary instantly morphs into a Stub. Instead of crashing, it acts as a proxy: reading JSON-RPC requests from its parent agy's stdin, forwarding them via HTTP POST to the Leader at http://localhost:3000/messages, and writing the HTTP responses back to stdout. It also pipes the Leader's /sse stream directly to stdout. **Graceful Shutdown:** The stub detects EOF on its stdin pipe when the CLI exits, safely closing all HTTP streams and terminating cleanly.
-
-### Automatic Failover & Self-Healing
-If the terminal hosting the Leader is closed, the Leader process dies and releases port 3000. 
-*   **The Race:** The active Stubs immediately detect the dropped SSE HTTP connection. Instead of crashing, they race to bind to port 3000.
-*   **Resolution:** The first Stub to bind successfully promotes itself to the new Leader (taking over file locks, WAL management, and the Axum server). The losing Stubs recognize the new Leader, reconnect their HTTP streams, and resume proxying. This results in near-zero downtime for the user's agy clients.
 
 ### WSL (Linux) Client Lifecycle (Permanent Stub)
-To provide a seamless experience without complex configuration drift, the WSL environment utilizes a native Linux binary (`/home/riz/.local/bin/mcp-memory`) that acts as a **Permanent Stub**.
+To provide a seamless experience without complex configuration drift, the WSL environment utilizes a native Linux binary (`/home/riz/.local/bin/mcp-memory-stub`) that acts as a **Permanent Stub**.
 *   **Transparent Proxying:** The WSL `agy` CLI spawns this Linux binary via standard `stdio`. The binary immediately proxies all `stdio` JSON-RPC requests over HTTP to the Windows Leader at `http://127.0.0.1:3000/messages`, handling SSE streams transparently.
 *   **Startup via Interop:** Upon launch, the Linux Stub pings the Windows host. If port 3000 is dead, the Linux binary automatically executes WSL interop (`cmd.exe /c start /B C:\Users\reazul.ashraf\.local\bin\mcp-memory.exe`) to silently wake up the Windows Leader before commencing the proxy loop.
 *   **Zero I/O Penalty:** This ensures the Linux binary never directly touches the Windows NTFS files, reserving all heavy disk operations for the native Windows host.
@@ -111,11 +104,11 @@ To optimize for different environments, the codebase is structured as a Cargo Wo
 *   **Path:** server/
 *   **Size/Complexity:** Heavy (contains Axum, MCP SDK, JSON parsing, Tokio runtime).
 *   **Role:** This is the primary background daemon. It binds to .0.0.0:3000, holds file locks, and manages the graph.
-*   **Windows Behavior:** It employs the Morphing logic. The first instance becomes the Leader (Server). Subsequent instances spawned by agy detect the port is in use and seamlessly morph into Stubs, proxying stdio to HTTP.
+*   **Windows Behavior:** It is designed to run in the background as a standalone service.
 
 ### 2. mcp-memory-stub (The Ultra-Lightweight Proxy)
 *   **Path:** stub/
 *   **Size/Complexity:** Extremely light (only relies on 
 eqwest and 	okio).
-*   **Role:** A dedicated, OS-agnostic proxy binary used strictly for routing stdio JSON-RPC traffic over HTTP to a remote Leader. Windows clients can point directly to this binary to bypass loading the heavy Server daemon into memory.
+*   **Role:** A dedicated, OS-agnostic proxy binary used strictly for routing stdio JSON-RPC traffic over HTTP to a remote Leader. Windows gy clients point directly to this binary to bypass loading the heavy Server daemon into memory.
 *   **WSL Behavior:** Compiled as a Linux native binary (x86_64-unknown-linux-musl). When executed by WSL agy, it acts as a transparent proxy to http://127.0.0.1:3000. It can also execute wake_cmd (e.g., WSL interop) to silently wake the Windows host if the Leader is offline.