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 (using active_nvim.txt for Last Focused Wins telemetry). If no interactive instance is open, they will automatically spawn and connect to a persistent headless Neovim background instance. Note on Visual Engagement: While the headless instance is perfect for autonomous/background tasks, if the task involves collaborative "pair programming" or requires the user's visual review, you should pause and request the user to open a Neovim UI before proceeding.

• 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 tools 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.