132 lines
9.4 KiB
Markdown
132 lines
9.4 KiB
Markdown
# 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.
|
|
- When calling **log_code_change**, **log_error_fix**, or **log_tech_debt**, you should execute git rev-parse HEAD and git branch --show-current in the project directory first (if it's a git repo).
|
|
- Pass the resulting hash and branch name into the git_commit and git_branch arguments of those tools to permanently link the memory item to the VCS state.
|
|
|
|
## 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.
|