mcp-memory/instructions.md

MCP Memory Server Guidelines

This server provides an OS-agnostic, persistent Knowledge Graph and working memory. The following guidelines dictate when and how to best utilize these tools.

1. Ephemeral Working Memory (Sticky Notes)

• Tools: dd_sticky_note, ead_sticky_notes
• When to use:
  • When you need to remember a specific context, broken build state, or pending task across conversation boundaries (e.g., "We are in the middle of refactoring main.rs, next step is testing").
  • When saving short-term scratchpad thoughts that don't belong in the permanent knowledge graph.
• Behavior: Notes have a 24-hour TTL and are pruned automatically. Always consider reading sticky notes at the start of a session if picking up an ongoing task.

2. The Knowledge Graph (Entities & Relations)

• Tools: search_nodes, open_nodes, ead_graph
• When to use search_nodes: Use this for fuzzy searching when you aren't 100% sure of the exact entity name, or you want to find everything related to a topic (e.g., "Docker", "Jenkins"). It uses Jaro-Winkler distance and token matching.
• When to use open_nodes: Use this for 1-hop traversal. If you know a specific entity name (e.g., "auth-service") and want to see how it connects to other services, open_nodes will pull the entity AND all directly connected neighbors.

3. Graph Maintenance & Condensation

• Tool: condense_entity
• When to use: Proactively use this tool if you notice an entity's observations array is getting excessively long (e.g., >10 items) or repetitive. Condense the list into a shorter, more concise summary of the core facts to preserve token limits.

4. The Audit Ledger (Code Changes)

• Tools: log_code_change, query_recent_changes
• When to use log_code_change: MANDATORY. Immediately after successfully making significant file modifications (e.g., refactoring a script, fixing a bug). Log the file path and a short description.
• When to use query_recent_changes: When the user asks "What did we do yesterday?", "What changed recently?", or when trying to debug a newly introduced issue. (The ledger retains 7 days of history, max 1000 items).

5. Architectural Visualization

• Tool: isualize_graph
• When to use: When you need to explain complex system relationships, dependencies, or architectures to the user. This tool outputs a raw Mermaid.js string. Put the output inside a ``mermaid` markdown block in an Artifact so the user can see a visual diagram.

6. Structured Task Queue (Agentic Kanban)

• Tools: add_task, update_task_status, list_active_tasks
• When to use: Use this for structured checklist tracking of complex, multi-day features or goals (e.g., when the user initiates a /goal).
• Behavior: Log tasks with a title and description. When resuming sessions, always run list_active_tasks to see what is still pending, in_progress, or blocked, and pick up where you left off. Use update_task_status to transition tasks to done.

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.