From 68729571950b4eefc24d5aa163b009d513708225 Mon Sep 17 00:00:00 2001 From: Riz Ashraf Date: Sat, 12 Sep 2026 22:22:09 +0100 Subject: [PATCH] docs: Prune redundant JSON schemas from instructions in favor of strong static typing --- instructions.md | 59 ++++++++++++++----------------------------------- 1 file changed, 16 insertions(+), 43 deletions(-) diff --git a/instructions.md b/instructions.md index 2d11c33..8862246 100644 --- a/instructions.md +++ b/instructions.md @@ -1,36 +1,7 @@ -# MCP Memory Server Guidelines +# Memory MCP Strategic 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:** add_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`. +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` @@ -40,7 +11,7 @@ This server provides an OS-agnostic, persistent Knowledge Graph and working memo ## 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. +- **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 @@ -53,9 +24,10 @@ This server provides an OS-agnostic, persistent Knowledge Graph and working memo - **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 +- **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. +- **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. @@ -72,7 +44,7 @@ amespace (project). 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. +- **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. @@ -82,7 +54,8 @@ When working in a multi-session or multi-agent environment, agents need to commu ## 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). +- **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. @@ -90,7 +63,7 @@ Stop wasting tokens rediscovering how to run or configure the project. 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. +- **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. @@ -105,7 +78,7 @@ Avoid asking the user for URLs or connection details repeatedly. 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. +- **clear_pr_checklist:** Clear if the project lifecycle changes dramatically. ## Tech Debt & Refactor Backlog Keep the main task board clean by isolating "hacky" workarounds. @@ -117,7 +90,7 @@ Keep the main task board clean by isolating "hacky" workarounds. 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. +- **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. @@ -125,16 +98,16 @@ When you remember a vague keyword but don't know which specific vault it's store ## 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. +- **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. +- 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 + 2. HTTP Endpoint: POST http://127.0.0.1:3000/shutdown