refactor: consolidate nvim crates, extract server library, and update workspace dependencies

server/src/instructions.md

@@ -1,24 +1,184 @@
-# Antigravity Memory MCP Instructions
+# Memory MCP Strategic Guidelines
 
-You are Antigravity, connected to the mcp-memory persistence layer. This server provides a persistent knowledge graph, task management, and environment state tracking.
+This document outlines the STRATEGY, SEMANTICS, and CASING STANDARDS for using the MCP Memory Server.
+You do not need to memorize JSON schemas for these tools; they are strictly defined and typed in the `tools/list` endpoint. Focus purely on WHEN and WHY to use them.
 
-## Core Directives
-1. **Always Log Code Changes**: Before completing any coding task or pull request, you MUST invoke the `MemoryLibrarian` subagent to execute `log_code_change`. The server uses `git2` to automatically detect your branch and hash.
-2. **Always Log Error Fixes**: If you spend more than one turn fixing an error or bug, call log_error_fix with the stack trace and the exact solution you discovered.
-3. **Omni Search (Hybrid Vector)**: When starting a session or looking for context, use omni_search. It uses Vector Embeddings for semantic matching, so you can query conceptually (e.g., "how does auth work") without needing exact keyword matches. It searches the knowledge graph, tasks, snippets, ADRs, and tech debt.
-4. **Architectural Entities**: When refactoring or creating new files, delegate to the `MemoryLibrarian` to define structural components via `create_entities` and `create_relations`.
-5. **Tech Debt**: Do NOT ignore tech debt. If you are forced to make a workaround or take a shortcut, log it with log_tech_debt. When you fix it later, use resolve_tech_debt.
-6. **Decisions**: Use log_decision when you make an architectural choice (e.g. choosing a specific library or pattern).
-7. **Workspaces & Context**: When pausing work or shifting focus, use `save_context_workspace` to snapshot your active tasks and pinned files. When resuming, use `list_context_workspaces` and `load_context_workspace`. Keep your working files pinned (`pin_file`)!
-8. **Snippets**: If you write a highly reusable piece of code, utility, or config, store it using `store_snippet`. Before writing boilerplate, try `search_snippets`. If outdated, use `delete_snippet`.
-9. **PR Checklists**: Aggressively use `add_pr_checklist_item` to build up a list of manual verification steps. Once the PR is merged, use `clear_pr_checklist`.
-10. **Tasks & Milestones**: Always track the user's larger goals! Invoke the `ScrumMaster` subagent to manage the board (`add_task`, `update_task_status`, `set_acceptance_criteria`). Use `list_active_tasks` to check what's next.
-11. **Handoff Memos**: If you need to stop your session or hand off work to a subagent, use `leave_handoff_memo`. When starting, use `read_handoff_memos` and `clear_handoff_memos` once read.
-12. **Preferences**: If the user tells you how they like things done (e.g., "always use fastify", "never use sed"), use `learn_preference`.
-13. **Sticky Notes**: Use `add_sticky_note` for ephemeral, temporary scratchpad info (like IP addresses, temporary URLs, or pending command outputs).
+---
 
-Be aggressive about logging state changes in the background! You MUST delegate this heavy lifting to the `MemoryLibrarian`, `ScrumMaster`, and `DevOpsSRE` subagents in the background.
+## 1. Casing & Naming Standards (CRITICAL)
 
-## Tool Schema Discovery
-Do **NOT** grep or search the Rust source code to find tool schemas or arguments. All lazy-loaded MCP tool schemas are automatically cached as JSON files on your disk. To understand a tool`s arguments, directly read `~/.gemini/antigravity-cli/mcp/mcp-memory/<tool_name>.json`. Do not waste tokens inspecting the Rust server code for schemas.
+To prevent graph fragmentation and ensure seamless LLM context retrieval:
+* **Entity Types (`entity_type`)**: MUST ALWAYS be **`PascalCase`** (e.g. `DatabaseTable`, `McpTool`, `ArchitectureComponent`, `File`, `DataStructure`).
+* **Relation Types (`relation_type`)**: MUST ALWAYS be **`snake_case`** (e.g. `depends_on`, `calls`, `implements`, `uses`, `contains`).
+* **Field Keys & Properties**: MUST ALWAYS be **`snake_case`** (e.g. `file_path`, `git_commit`, `created_at`).
 
+> [!NOTE] 
+> The server automatically enforces and migrates incoming entity and relation types to these canonical casing rules on every read and write operation.
+
+---
+
+## 2. LLM Token Budgeting & RRF Search Optimization
+
+* **Token Budgeting (`summary_level` & `max_tokens`)**:
+  When calling `list_active_tasks` or `list_tech_debt`, pass `summary_level: "compact"` or `"detailed"` and `max_tokens: 500` to constrain output size when token context budget is tight.
+* **Reciprocal Rank Fusion (RRF) Omni-Search**:
+  `omni_search` uses Hybrid RRF (BM25 keyword search + Dense Vector Embeddings) to rank results semantically. You do not need exact keyword matches; query conceptually (e.g. "database lock issues").
+* **Delta Session Context (`memory://session/delta`)**:
+  Passively read `memory://session/delta` to get a succinct delta of code changes, tasks, and tech debt recorded during the current working session.
+* **Context Warmup (`context_warmup`)**:
+  Trigger the `context_warmup` prompt at session start to automatically synthesize delta changes, active tasks, tech debt, and pinned files in a single pass.
+
+---
+
+## 3. Subgraph Expansion & Multi-Hop Navigation
+- **Tool:** `get_subgraph`
+- **When to use:** When you need to understand the complete architectural neighborhood surrounding a specific component, module, or database table.
+- **Behavior:** Performs a multi-hop Breadth-First Search (BFS) around a `root_node` (or `root_entity`) up to a requested `depth` (e.g. 1 to 3 hops) and returns all connected entities and relations. Pass `format: "markdown_tree"` to generate a compact, token-budgeted Markdown topology tree capped within a requested `max_tokens` budget.
+
+---
+
+## 4. Automated Error Fix Auto-Matcher
+- **Tools:** `log_error_fix`, `search_error_fixes` (and alias `suggest_error_fix`)
+- **When to use:** When encountering a build error, test failure, or stack trace. Call `search_error_fixes` with either a text `query` or `stack_trace` before attempting a fix from scratch.
+- **Behavior:** Computes cosine similarity between error trace embeddings and past resolution logs when `stack_trace` is provided, or keyword filtering when `query` is provided, returning top matched solutions, modified files, and git commits.
+
+---
+
+## 5. Memory State Checkpointing & Rollbacks
+- **Tool:** `manage_checkpoint` (unifying `checkpoint_state`, `restore_state`, `create_snapshot`, `restore_snapshot`)
+- **When to use:** Before initiating a large refactor, running experimental subagent tasks, or executing destructive batch operations.
+- **Behavior:** Consolidates state snapshots and point-in-time checkpointers. Use `action: "create"`, `"restore"`, `"list"`, or `"delete"`.
+
+---
+
+## 6. Symbol Reference Backlinks
+- **Tools:** `log_code_change`, `log_error_fix`, `log_tech_debt`
+- **When to use:** When logging changes or debt tied to specific code symbols or line boundaries.
+- **Behavior:** Accept `symbol_references` (e.g., `["MemoryState::new", "CreateEntitiesTool"]`) and `line_range` (e.g., `"L45-L90"`), automatically indexing code references for quick symbol backlink searches.
+
+---
+
+## 7. Ephemeral Sticky Notes with TTL
+- **Tool:** `manage_sticky_notes` (or granular `add_sticky_note`, `read_sticky_notes`, `delete_sticky_note`, `clear_sticky_notes`)
+- **When to use:** For temporary scratchpad items, temporary ports, task IDs, or transient notes.
+- **Behavior:** Supports `action: "add" | "read" | "delete" | "clear"`. Supports `ttl_seconds` for auto-expiration and `session_only: true` for automatic purging when the session ends.
+
+---
+
+## 8. Snippet Vault & Domain Tagging
+- **Tools:** `store_snippet`, `search_snippets`, `delete_snippet`, `tag_snippet`
+- **When to use:** Store exact multi-line code snippets, Nushell pipelines, or frequently used CLI commands.
+- **Behavior:** `search_snippets` supports `mode: "hybrid" | "keyword" | "semantic"` combining BM25 term frequency keyword matching with semantic tag scoring. Guarantees precise syntactic preservation. Use `tag_snippet` to attach domain tags (e.g., `["rust", "axum", "mcp"]`) for category-filtered searches.
+
+---
+
+## 9. Context & Subagent Namespaces
+- **Tools:** `manage_subagent_namespace` (unifying `create_subagent_namespace`, `condense_subagent_namespace`, `purge_subagent_namespace`)
+- **When to use:** Isolate graph queries, tasks, and tech debt to specific project or subagent scopes.
+- **Behavior:** `manage_subagent_namespace` manages subagent memory lifecycles (`action: "create" | "condense" | "purge"`). Condensing auto-promotes subagent entities/relations to the global Knowledge Graph.
+
+---
+
+## 10. Architectural Decision Records (ADRs)
+- **Tools:** `log_decision`, `query_decisions`, `delete_decision`
+- **When to use:** Whenever making a non-trivial architectural, environmental, or design decision.
+- **Behavior:** Permanently stores context, decision, and consequences to prevent future agents from second-guessing choices.
+
+---
+
+## 11. Graph Refactoring & Algorithms
+- **Tools:** `merge_entities`, `find_orphans`, `query_graph_path`, `condense_entity`
+- **When to use:** Run `find_orphans` periodically to clean unused nodes. Use `merge_entities` to combine duplicate concepts. Use `query_graph_path` to find shortest relational connections between components. Use `condense_entity` when entity observation counts grow large.
+
+---
+
+## 12. Dynamic Learned Preferences
+- **Tools:** `learn_preference`, `read_preferences`
+- **When to use:** When the user specifies personal or repository-specific preferences.
+- **Behavior:** Stores key-value behavioral preferences that persist across agent invocations.
+
+---
+
+## 13. Pinned Workspaces & Hot Files
+- **Tools:** `pin_file`, `unpin_file`, `list_pinned_files`
+- **When to use:** Pin 3–5 active working set files to maintain focus in large codebases.
+
+---
+
+## 14. Agent Handoffs & Memos
+- **Tools:** `leave_handoff_memo`, `read_handoff_memos`, `clear_handoff_memos`
+- **When to use:** Leave messages for future agent sessions or inspect pending handoff notes upon waking.
+
+---
+
+## 15. Real-time WebSocket Memory Sync
+- **Endpoint:** `ws://127.0.0.1:3000/ws`
+- **Behavior:** Broadcasts live state updates and activity notifications to the Brain Monitor UI in real time.
+
+---
+
+## 16. Self-Healing Graph Health Sweeper
+- **Tool:** `sweep_graph_health`
+- **When to use:** Periodically or before committing major graph changes to audit entity consistency.
+- **Behavior:** Detects orphaned nodes (0 relations), computes name similarity to identify near-duplicates (e.g., `APIGateway` vs `ApiGateway`), and provides structured `merge_entities` recommendations or auto-prunes orphans.
+
+---
+
+## 17. Causal Lineage & Provenance Tracker
+- **Tool:** `query_lineage`
+- **When to use:** When asking *"Why was this component modified?"* or *"What task or ADR led to this code change?"*
+- **Behavior:** Searches across tasks, ADRs, audit ledger entries, and error fixes to assemble a unified chronological timeline explaining the provenance behind any file, symbol, or commit.
+
+---
+
+## 18. Topological Unblocked Task Resolver
+- **Tool:** `get_next_actionable_tasks`
+- **When to use:** When orchestrating subagent execution or selecting the next task to work on.
+- **Behavior:** Evaluates task dependency DAGs and filters out any blocked tasks, returning only unblocked, actionable tasks ready for immediate execution.
+
+---
+
+## 19. Chain-of-Thought & Diagnostic Hypothesis Memory
+- **Tools:** `log_hypothesis`, `query_hypotheses`
+- **When to use:** During complex debugging or root cause analysis.
+- **Behavior:** Records hypotheses alongside tested evidence and status (`unverified`, `verified`, `rejected`). Allows subagents to query past diagnostic paths and avoid re-testing disproven hypotheses.
+
+---
+
+## 20. Workspace Context Diffing
+- **Tool:** `diff_context_workspaces`
+- **When to use:** When switching branches or comparing two saved context workspaces.
+- **Behavior:** Returns a structured delta highlighting added, removed, and shared pinned files and active task IDs between two context workspaces.
+
+---
+
+## 21. Universal Token Guardrails
+- **Behavior:** Automatically caps large MCP resource reads (e.g. `memory://graph/entities`) and list responses, adding summary headers (`"_meta": "Showing 100 of N items"`) to guarantee output stays within context window limits.
+
+---
+
+## 22. LLM Pre-Flight Context Bundle
+- **Tool:** `get_preflight_context`
+- **When to use:** At the start of a turn or subagent task to gain total situational awareness in 1 call.
+- **Behavior:** Aggregates current active branch, in-progress tasks with acceptance criteria, pinned files, top open tech debts, and active unverified hypotheses into a consolidated executive context bundle.
+
+---
+
+## 23. Self-Healing Symbol & Line Range Resolver
+- **Tool:** `resolve_stale_symbols`
+- **When to use:** When files have been deleted, moved, or heavily refactored.
+- **Behavior:** Verifies graph entities and tech debt symbol references against disk and AST, flagging and auto-healing stale pointers or broken file paths.
+
+---
+
+## 24. Inter-Agent Signal Bus
+- **Tools:** `broadcast_agent_signal`, `query_agent_signals`
+- **When to use:** For real-time coordination and event-driven communication between concurrent subagents (e.g., `PrePushAuditor` signaling `AUDIT_PASSED` to parent agent).
+- **Behavior:** Ephemeral TTL-backed signal bus storing structured agent events, payloads, and artifact URIs.
+
+---
+
+## 25. Automated Session Checkpoint on Shutdown
+- **Tool:** `auto_session_checkpoint`
+- **When to use:** Executed automatically on `/shutdown` or manually when pausing a session.
+- **Behavior:** Captures active tasks, unverified hypotheses, recent commit ledgers, and workspace state into a permanent `HandoffMemo` for seamless turn-taking and recovery.