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 & Maintenance

• Tools: merge_entities, ind_orphans
• When to use: Run ind_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).
• Behavior: merge_entities will safely combine their observations and automatically remap all relations pointing to or from the deleted duplicate.

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 (Global Vault Search)

When you remember a vague keyword 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.

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.

13. Server Lifecycle & Updates (Graceful Shutdown)

When instructed to restart, update, or stop the mcp-memory-server binary, never use brute-force OS kill commands (e.g. Stop-Process, pkill, kill).

• Why: The server uses asynchronous checkpointing. Force-killing it bypasses the shutdown flush, risking data loss in the master JSON graph, and can lead to lingering file locks.
• How: Always use the built-in graceful shutdown mechanisms:
  1. CLI Flag: mcp-memory-server --exit (or --restart)
  2. HTTP Endpoint: POST http://127.0.0.1:3000/shutdown

14. Dual Transport Architecture (SSE & WebSockets)

• Constraint: The MCP Memory Server natively supports a dual transport layer. You MUST maintain both if modifying network code.
  • SSE (/sse & /messages): Used strictly by the Antigravity LLM client because standard AI runtimes prefer synchronous HTTP JSON-RPC wrappers.
  • WebSockets (/ws): Used strictly by external UI clients (e.g., dashboard.html) or the mcp-memory-stub proxy.
• Behavior: Both transport layers route into the exact same central handle_request pipeline. Do not build feature logic that only works on one transport protocol.

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 ctive_nvim.txt for Last Focused Wins telemetry).

• These binaries expose basic tools ( vim_get_cursor, vim_get_active_buffer, vim_list_buffers, etc.).
• God Mode: They also expose vim_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 vim_execute_lua. Do not attempt to recompile the Rust server to add new basic tools; use the Lua escape hatch dynamically.