mcp-memory/instructions.md

# Memory MCP Strategic Guidelines

This document outlines the STRATEGY and SEMANTICS 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 	ools/list endpoint. Focus purely on WHEN and WHY to use them.

## 7. Snippet & Command Vault
- **Tools:** `store_snippet`, `search_snippets`, `delete_snippet`
- **When to use:** Use the Vault to store exactly multi-line code snippets, Nushell pipelines, or complex commands that the user relies on frequently.
- **Behavior:** The vault guarantees precise syntactic preservation of the script (unlike Graph observations). Search snippets when trying to recall an exact query or pipeline.

## 8. Context Namespaces (Project Scopes)
- **Feature:** `namespace` optional parameter
- **When to use:** When using `read_graph`, `search_nodes`, or `visualize_graph`, you can now pass `namespace` to isolate graph queries to a specific project scope (e.g. "scascanner").
- **Behavior:** When calling `create_entities` or `create_relations`, you can inject `namespace: "your_project"` into the entity schema to isolate it from the global scope.

## 9. Architectural Decision Records (ADRs)
- **Tools:** log_decision, query_decisions
- **When to use:** Use this whenever you make a non-trivial architectural, environmental, or tooling decision (e.g. choosing a specific framework, a specific deployment flag, bypassing a rule with a workaround).
- **Behavior:** This permanently stores the context, decision, and consequence of *why* something is done the way it is, preventing future agents from second-guessing or reverting it.

## 10. Graph Refactoring & Algorithms
- **Tools:** merge_entities, find_orphans, query_graph_path
- **When to use:** Run `find_orphans` periodically or when you notice graph clutter to safely delete unused nodes. Use `merge_entities` when you notice duplicated semantic concepts (e.g. API_Gateway vs APIGateway). Use `query_graph_path` when you need to understand how two completely different architectural components are related (e.g. "How does the Frontend connect to the Database?").
- **Behavior:** `merge_entities` will safely combine their observations and automatically remap all relations pointing to or from the deleted duplicate. `query_graph_path` executes a breadth-first search to find the shortest relational path between nodes.

## 11. Dynamic Learned Preferences
- **Tools:** learn_preference, 
ead_preferences
- **When to use:** When the user corrects you on a specific local nuance (e.g. "Actually, use Python 3.10 instead of 3.12 for this repo").
- **Behavior:** Use this Key-Value store to record dynamic behavioral preferences to ensure you adapt instantly without modifying global Markdown files.

## Error Vault / Troubleshooting
When you spend time resolving a tricky environment issue, build error, or logic bug, immediately record the fix to save future time.
- **log_error_fix:** Provide the signature (the exact error string or stack trace snippet) and the solution.
- **search_error_fixes:** When encountering a weird bug, query this vault first before debugging from scratch.

## Pinned Workspaces (Hot Files)
To maintain focus on the active "working set" of files in large repositories, use pins.
- **pin_file / unpin_file:** Pin the 3-5 files you are actively modifying to the current 
amespace (project).
- **list_pinned_files:** When starting a new session or returning to a project, always list pinned files first to instantly regain context on what was being worked on.

## Rolling Session Summaries (Project Timeline)
To maintain a chronological narrative of the project's evolution beyond just code diffs.
- **add_session_summary:** At the end of every major coding session, write a 2-sentence summary of what was accomplished and add it to the 
amespace.
- **get_project_timeline:** When rejoining a project after a long time, read the timeline to instantly understand the recent architectural history.

## Agent Handoffs (The Inbox)
When working in a multi-session or multi-agent environment, agents need to communicate context across time.
- **leave_handoff_memo:** Leave a quick message describing current progress, roadblocks, or the literal next step to take.
- **read_handoff_memos:** ALWAYS check for memos when waking up in a new project namespace.
- **clear_handoff_memos:** Clear the memo after you have successfully read it and absorbed its context.

## Environment & Blueprint Tracker
Stop wasting tokens rediscovering how to run or configure the project.
- **update_env_fingerprint:** Run this when you set up a new project to snapshot the OS, shell, and key language versions (e.g. python, 
ustc).
- **read_env_fingerprint:** Query this to instantly know how the project is run.
- **log_env_requirement:** Log required .env variables (e.g. DATABASE_URL) without logging the secret itself.

## Milestones (Epics)
Organize granular tasks into high-level phases.
- **add_milestone:** Group a large subset of work into a cohesive phase (e.g., "V1 MVP", "CI/CD Setup").
- **update_milestone:** Mark a milestone as active, blocked, or completed.
- **list_milestones:** Use this to ensure task priorities align with the current active milestone.

## Standup Reports
When asked for a progress update or standup report, do not guess or read raw git logs.
- **generate_standup_report:** Generates a structured JSON containing all 	asks updated, code_changes logged, and session_summaries added within the last N hours. Format this cleanly as a markdown report for the user.

## Infrastructure & Environment Registry
Avoid asking the user for URLs or connection details repeatedly.
- **register_environment:** Save connection details for Dev, QA, Staging, or Prod environments.
- **get_environment_details:** Query this to know how to connect to databases, APIs, or VPNs.

## Pre-Push / PR Quality Checklists
Ensure high code quality and prevent incomplete pull requests.
- **add_pr_checklist_item:** Add recurring repository chores (e.g., "Run cargo fmt", "Update CHANGELOG").
- **get_pr_checklist:** Query and explicitly verify EVERY item on this list before triggering git push or merging PRs.
- **clear_pr_checklist:** Clear if the project lifecycle changes dramatically.

## Tech Debt & Refactor Backlog
Keep the main task board clean by isolating "hacky" workarounds.
- **log_tech_debt:** Record why a shortcut was taken and what the ideal solution should be.
- **resolve_tech_debt:** Mark a debt as paid off once refactored.
- **list_tech_debt:** Query this before starting a refactoring session.

## Context Workspaces
When shifting context rapidly (e.g. from building a feature to fixing a prod bug), save your state.
- **save_context_workspace:** Save your active pinned files and task IDs under a named workspace (e.g., "Feature X").
- **load_context_workspace:** Retrieve a saved workspace to instantly restore your context when returning to that task.
- **list_context_workspaces:** List all saved workspaces in a project.

## Omni-Search (Hybrid Vector Search)
When you remember a vague concept, keyword, or architectural pattern but don't know which specific vault it's stored in.
- **omni_search:** Searches across the Knowledge Graph, Tasks, Snippets, ADRs, Tech Debt, Memos, and Error Fixes simultaneously.
- **Semantic Superpower:** This tool utilizes **Hybrid Vector Search** (BM25 + Vector Embeddings). You do not need exact keyword matches. You can query conceptually (e.g., "database lock issues" or "how is auth handled") and the engine will return semantically relevant context.

## Terminal History & Telemetry
To maintain an audit trail of shell commands and execution contexts.
- **Context:** The server actively tracks Terminal History. Commands executed in the user's shell are logged to the memory server and visible in the dashboard UI. While you don't call an MCP tool for this directly, be aware that complex shell actions and their outcomes are persisted for historical auditing and UI visibility.

## Project Health Dashboard
When starting a new session, get a numerical aggregate of the project's current state.
- **get_project_health:** Returns a quick digest of active tasks, unread memos, unresolved tech debt, and pending PR checklist items.

## Git Context Binding (VCS Sync)
To maintain absolute traceability, we link memory items directly to the exact git commits they occurred on.
- **Fully Automated (git2):** You no longer need to manually execute `git rev-parse HEAD` or pass `git_branch` / `git_commit` arguments. 
- When you call tools like **log_code_change**, **log_error_fix**, or **log_tech_debt**, the Rust server uses the native `git2` crate to automatically discover the repository context of the active working directory, extract the current HEAD commit hash, message, and branch, and permanently bind them to the memory item in the background.


## 15. Neovim Integration & God Mode
The project contains two MCP binaries (win-nvim and linux-nvim) that bridge JSON-RPC over stdio directly to the active Neovim instance.
- **Interactive UI (UDP):** The active editor connects to the backend via UDP (port 3002). The UI script (`gemini-ui.lua`) supports non-destructive **Ghost Text Diff Reviews** and native `vim.ui` prompts without spawning subprocesses. You can trigger these interactively using the backend server.
- **Tools:** These binaries expose basic tools (`nvim_get_cursor`, `nvim_get_active_buffer`, `nvim_list_buffers`, etc.).
- **God Mode**: They also expose `nvim_execute_lua`. This is the ultimate fallback tool. If you need to access *any* Neovim API that does not have a dedicated Rust tool (e.g., getting LSP diagnostics, evaluating a visual selection block based on modes, setting registers), you MUST write a short Lua script and pass it to `nvim_execute_lua`. Do not attempt to recompile the Rust server to add new basic tools; use the Lua escape hatch dynamically.

## 16. 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/<server_name>/<tool_name>.json`. Do NOT guess arguments. ALWAYS read the schema if you are unfamiliar with a tool to prevent invalid argument errors.