From 83aa26634d8cda0738107d2db72a82da1a419161 Mon Sep 17 00:00:00 2001 From: Riz Ashraf Date: Fri, 2 Oct 2026 07:27:26 +0100 Subject: [PATCH] docs: update workflow constraints, rules, and project documentation --- README.md | 12 ++++++++++++ agent-rules/workflow-constraints.md | 6 ++++++ instructions.md | 17 +++++++++++++++++ 3 files changed, 35 insertions(+) diff --git a/README.md b/README.md index 3467467..4bf3602 100644 --- a/README.md +++ b/README.md @@ -86,6 +86,18 @@ Update your WSL ~/.gemini/config/mcp_config.json: } ` *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.* + +## Native Local Ollama LLM Handshake +`mcp-memory-server` directly interfaces with local Ollama instances (e.g. `http://192.168.1.30:11434`) via a native compiled Rust client (`server/src/ollama.rs`): +* **Connection Handshake:** On startup and before executing LLM-enhanced tools, `mcp-memory-server` issues a **1.5-second health probe** (`GET /api/tags`). +* **Environment Configuration (`mcp_config.json`):** + * `OLLAMA_URL`: Target Ollama host URL (default: `http://192.168.1.30:11434`). + * `OLLAMA_CODER_MODEL`: Local coding model (e.g., `qwen2.5-coder:1.5b`). + * `OLLAMA_REASONING_MODEL`: Chain-of-thought reasoning model (e.g., `deepseek-r1:1.5b`). + * `OLLAMA_VISION_MODEL`: Multimodal vision model (e.g., `qwen3-vl:2b`). + * `OLLAMA_EMBED_MODEL`: Dense embedding model (e.g., `nomic-embed-text:latest`). +* **Graceful Degradation Guarantee:** If the local Ollama host is offline or unreachable, **no tool ever fails.** Every tool automatically falls back to pure Rust execution and local `redb`/`Tantivy` storage. + ` ## Push Safety Gates The daemon also operates as a global safety gate for Git. Before pushing code, run: diff --git a/agent-rules/workflow-constraints.md b/agent-rules/workflow-constraints.md index 368b879..4ea5a03 100644 --- a/agent-rules/workflow-constraints.md +++ b/agent-rules/workflow-constraints.md @@ -32,3 +32,9 @@ trigger: always_on # 8. GCP Infrastructure Provisioning (gcloud & Cloud Armor) - **Rule (Cloud Armor IP Limits):** GCP Cloud Armor security policies strictly enforce a limit of **10 IP ranges per rule** (`--src-ip-ranges`). When allowlisting large services (like Atlassian Bitbucket which has 11+ IP CIDR blocks), you MUST split the ranges across multiple rules (e.g., priority 1000 and 1001) to prevent the `Only a maximum of 10 IP ranges allowed per rule` API error. - **Rule (gcloud Idempotency):** When writing bash scripts to provision GCP infrastructure, NEVER use bare `gcloud ... create` commands. You MUST wrap all creation commands in existence checks (e.g., `if ! gcloud ... describe ... >/dev/null 2>&1; then ... fi`) to ensure the script is fully idempotent and can be safely retried upon failure. + +# 9. Rust Build System & Toolchain Resilience +- **Rule (SChannel VPN Revocation Bypass):** To prevent `CRYPT_E_NO_REVOCATION_CHECK` errors when fetching crates over corporate VPNs, ensure `.cargo/config.toml` specifies `[http] check-revoke = false`. +- **Rule (sccache Caching Efficiency):** When using `sccache` as `rustc-wrapper`, set `incremental = false` under `[profile.dev]` in `.cargo/config.toml`. `sccache` cannot cache incremental compilation units. +- **Rule (sccache Daemon Recovery):** If `sccache` fails with socket error 10054 (`connection forcibly closed`), restart the daemon using `sccache --stop-server; Start-Sleep -Seconds 1; sccache --start-server` before retrying compilation. +- **Rule (cargo-llvm-cov Toolchain Matching):** Always set `LLVM_COV` and `LLVM_PROFDATA` environment variables to the matching `rustup` toolchain LLVM binaries (`.../lib/rustlib//bin/llvm-cov.exe`) to prevent LLVM profile format version mismatches. diff --git a/instructions.md b/instructions.md index 5c52cf7..91914b4 100644 --- a/instructions.md +++ b/instructions.md @@ -127,3 +127,20 @@ To reduce token costs and eliminate exact-match string failures: ## 17. Tool Schema Discovery (Lazy Loading) Antigravity automatically caches all MCP tool schemas to your disk to save tokens. Do **NOT** grep or search the Rust source code to find tool schemas or arguments. To understand a tool's arguments, directly read `~/.gemini/antigravity-cli/mcp//.json`. Do NOT guess arguments. ALWAYS read the schema if you are unfamiliar with a tool to prevent invalid argument errors. +## 18. Local Ollama LLM Handshake & Graceful Fallback +`mcp-memory-server` includes a native, compiled Rust client (`server/src/ollama.rs`) that interfaces directly with local Ollama hardware (e.g. `http://192.168.1.30:11434`). +- **Connection Handshake:** On startup and before executing LLM-enhanced tools, the server performs a **1.5-second health probe** (`GET /api/tags`). +- **Environment Variables:** `OLLAMA_URL`, `OLLAMA_CODER_MODEL` (`qwen2.5-coder:1.5b`), `OLLAMA_REASONING_MODEL` (`deepseek-r1:1.5b`), `OLLAMA_VISION_MODEL` (`qwen3-vl:2b`), and `OLLAMA_EMBED_MODEL` (`nomic-embed-text:latest`). +- **Synergistic Tool Enhancements:** + - **`log_code_change`**: Automatically uses `qwen2.5-coder:1.5b` to summarize architectural impact. + - **`log_error_fix`**: Automatically uses `deepseek-r1:1.5b` for root cause & solution extraction. + - **`read_clipboard`**: Automatically passes clipboard image bytes to `qwen3-vl:2b` for OCR/layout parsing. + - **`omni_search`**: Uses `nomic-embed-text` for dense vector search indexing. +- **Graceful Fallback Guarantee:** If Ollama is offline, unreachable, or times out (>1.5s), **no tool ever fails or throws an error.** Every tool automatically degrades gracefully to pure Rust execution and local `redb`/`Tantivy` storage. + +## 19. Tool Discovery & WebSocket Handshake (`tools/list_changed`) +The server implements the full Model Context Protocol (MCP) JSON-RPC specification for tool discovery and live updates: +- **`tools/list` Endpoint:** Primary clients query this endpoint during initialization to discover all registered tools, schemas, and argument types. +- **Dynamic Handshake Notification (`notifications/tools/list_changed`):** When the backend server restarts or modifies its tool definitions, it broadcasts a WebSocket `notifications/tools/list_changed` JSON-RPC notification. Light stubs (`mcp-memory-stub`) automatically receive this event and refresh the host CLI's tool catalog in real time without disconnecting or restarting the CLI context. + +