From 938b8dbf45d57f39df6171368228e5e126c03c70 Mon Sep 17 00:00:00 2001 From: Riz Ashraf Date: Wed, 9 Sep 2026 04:32:50 +0100 Subject: [PATCH] docs: Document MPSC queue resilience and 127.0.0.1 binding --- design.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/design.md b/design.md index 0c41058..e431ccb 100644 --- a/design.md +++ b/design.md @@ -96,7 +96,8 @@ Every time a Windows gy session starts, it blindly spawns mcp-memory-stub.exe a ### 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-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. +* **MPSC Queue Resilience:** The stub utilizes an asynchronous multi-producer, single-consumer (MPSC) channel queue. If the Windows Leader daemon restarts or momentarily drops, the proxy buffers incoming JSON-RPC tool calls and infinitely retries them until the connection is restored. This guarantees **zero message loss** and **zero thread leaks** without crashing the active `agy` session. +* **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-server.exe --daemon`) 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. ## 13. Cargo Workspace & Binary Artifacts To optimize for different environments, the codebase is structured as a Cargo Workspace containing two distinct crates: