# Memory MCP Strategic Guidelines This document outlines the STRATEGY, SEMANTICS, and CASING STANDARDS 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 `tools/list` endpoint. Focus purely on WHEN and WHY to use them. --- ## 1. Casing & Naming Standards (CRITICAL) To prevent graph fragmentation and ensure seamless LLM context retrieval: * **Entity Types (`entity_type`)**: MUST ALWAYS be **`PascalCase`** (e.g. `DatabaseTable`, `McpTool`, `ArchitectureComponent`, `File`, `DataStructure`). * **Relation Types (`relation_type`)**: MUST ALWAYS be **`snake_case`** (e.g. `depends_on`, `calls`, `implements`, `uses`, `contains`). * **Field Keys & Properties**: MUST ALWAYS be **`snake_case`** (e.g. `file_path`, `git_commit`, `created_at`). > [!NOTE] > The server automatically enforces and migrates incoming entity and relation types to these canonical casing rules on every read and write operation. --- ## 2. LLM Token Budgeting & RRF Search Optimization * **Token Budgeting (`summary_level` & `max_tokens`)**: When calling `list_active_tasks` or `list_tech_debt`, pass `summary_level: "compact"` or `"detailed"` and `max_tokens: 500` to constrain output size when token context budget is tight. * **Reciprocal Rank Fusion (RRF) Omni-Search**: `omni_search` uses Hybrid RRF (BM25 keyword search + Dense Vector Embeddings) to rank results semantically. You do not need exact keyword matches; query conceptually (e.g. "database lock issues"). * **Delta Session Context (`memory://session/delta`)**: Passively read `memory://session/delta` to get a succinct delta of code changes, tasks, and tech debt recorded during the current working session. * **Context Warmup (`context_warmup`)**: Trigger the `context_warmup` prompt at session start to automatically synthesize delta changes, active tasks, tech debt, and pinned files in a single pass. --- ## 3. Subgraph Expansion & Multi-Hop Navigation - **Tool:** `get_subgraph` - **When to use:** When you need to understand the complete architectural neighborhood surrounding a specific component, module, or database table. - **Behavior:** Performs a multi-hop Breadth-First Search (BFS) around a `root_node` up to a requested `depth` (e.g. 1 to 3 hops) and returns all connected entities and relations in a single call. --- ## 4. Automated Error Fix Auto-Matcher - **Tools:** `log_error_fix`, `suggest_error_fix`, `search_error_fixes` - **When to use:** When encountering a build error, test failure, or stack trace. Call `suggest_error_fix` with the error trace before attempting a fix from scratch. - **Behavior:** Computes cosine similarity between error trace embeddings and past resolution logs to return top matched solutions, modified files, and git commits. --- ## 5. Memory State Checkpointing & Rollbacks - **Tools:** `checkpoint_state`, `restore_state` - **When to use:** Before initiating a large refactor, running experimental subagent tasks, or executing destructive batch operations. - **Behavior:** Saves or restores a point-in-time snapshot of graph entities, active tasks, and tech debt backlogs. --- ## 6. Symbol Reference Backlinks - **Tools:** `log_code_change`, `log_error_fix`, `log_tech_debt` - **When to use:** When logging changes or debt tied to specific code symbols or line boundaries. - **Behavior:** Accept `symbol_references` (e.g., `["MemoryState::new", "CreateEntitiesTool"]`) and `line_range` (e.g., `"L45-L90"`), automatically indexing code references for quick symbol backlink searches. --- ## 7. Ephemeral Sticky Notes with TTL - **Tools:** `add_sticky_note`, `read_sticky_notes`, `delete_sticky_note`, `clear_sticky_notes` - **When to use:** For temporary scratchpad items, temporary ports, task IDs, or transient notes. - **Behavior:** Supports `ttl_seconds` for auto-expiration and `session_only: true` for automatic purging when the session ends. --- ## 8. Snippet Vault & Domain Tagging - **Tools:** `store_snippet`, `search_snippets`, `delete_snippet`, `tag_snippet` - **When to use:** Store exact multi-line code snippets, Nushell pipelines, or frequently used CLI commands. - **Behavior:** Guarantees precise syntactic preservation. Use `tag_snippet` to attach domain tags (e.g., `["rust", "axum", "mcp"]`) for category-filtered searches. --- ## 9. Context Namespaces (Project Scopes) - **Feature:** `namespace` optional parameter - **When to use:** Isolate graph queries, tasks, and tech debt to specific project scopes (e.g. "mcp-memory"). - **Behavior:** Pass `namespace` to `read_graph`, `search_nodes`, `create_entities`, or `create_relations` to isolate items from global scope. --- ## 10. Architectural Decision Records (ADRs) - **Tools:** `log_decision`, `query_decisions`, `delete_decision` - **When to use:** Whenever making a non-trivial architectural, environmental, or design decision. - **Behavior:** Permanently stores context, decision, and consequences to prevent future agents from second-guessing choices. --- ## 11. Graph Refactoring & Algorithms - **Tools:** `merge_entities`, `find_orphans`, `query_graph_path`, `condense_entity` - **When to use:** Run `find_orphans` periodically to clean unused nodes. Use `merge_entities` to combine duplicate concepts. Use `query_graph_path` to find shortest relational connections between components. Use `condense_entity` when entity observation counts grow large. --- ## 12. Dynamic Learned Preferences - **Tools:** `learn_preference`, `read_preferences` - **When to use:** When the user specifies personal or repository-specific preferences. - **Behavior:** Stores key-value behavioral preferences that persist across agent invocations. --- ## 13. Pinned Workspaces & Hot Files - **Tools:** `pin_file`, `unpin_file`, `list_pinned_files` - **When to use:** Pin 3–5 active working set files to maintain focus in large codebases. --- ## 14. Agent Handoffs & Memos - **Tools:** `leave_handoff_memo`, `read_handoff_memos`, `clear_handoff_memos` - **When to use:** Leave messages for future agent sessions or inspect pending handoff notes upon waking. --- ## 15. Real-time WebSocket Memory Sync - **Endpoint:** `ws://127.0.0.1:3000/ws` - **Behavior:** Broadcasts live state updates and activity notifications to the Brain Monitor UI in real time. --- ## 16. Self-Healing Graph Health Sweeper - **Tool:** `sweep_graph_health` - **When to use:** Periodically or before committing major graph changes to audit entity consistency. - **Behavior:** Detects orphaned nodes (0 relations), computes name similarity to identify near-duplicates (e.g., `APIGateway` vs `ApiGateway`), and provides structured `merge_entities` recommendations or auto-prunes orphans. --- ## 17. Causal Lineage & Provenance Tracker - **Tool:** `query_lineage` - **When to use:** When asking *"Why was this component modified?"* or *"What task or ADR led to this code change?"* - **Behavior:** Searches across tasks, ADRs, audit ledger entries, and error fixes to assemble a unified chronological timeline explaining the provenance behind any file, symbol, or commit. --- ## 18. Topological Unblocked Task Resolver - **Tool:** `get_next_actionable_tasks` - **When to use:** When orchestrating subagent execution or selecting the next task to work on. - **Behavior:** Evaluates task dependency DAGs and filters out any blocked tasks, returning only unblocked, actionable tasks ready for immediate execution. --- ## 19. Chain-of-Thought & Diagnostic Hypothesis Memory - **Tools:** `log_hypothesis`, `query_hypotheses` - **When to use:** During complex debugging or root cause analysis. - **Behavior:** Records hypotheses alongside tested evidence and status (`unverified`, `verified`, `rejected`). Allows subagents to query past diagnostic paths and avoid re-testing disproven hypotheses. --- ## 20. Workspace Context Diffing - **Tool:** `diff_context_workspaces` - **When to use:** When switching branches or comparing two saved context workspaces. - **Behavior:** Returns a structured delta highlighting added, removed, and shared pinned files and active task IDs between two context workspaces. --- ## 21. Universal Token Guardrails - **Behavior:** Automatically caps large MCP resource reads (e.g. `memory://graph/entities`) and list responses, adding summary headers (`"_meta": "Showing 100 of N items"`) to guarantee output stays within context window limits. --- ## 22. LLM Pre-Flight Context Bundle - **Tool:** `get_preflight_context` - **When to use:** At the start of a turn or subagent task to gain total situational awareness in 1 call. - **Behavior:** Aggregates current active branch, in-progress tasks with acceptance criteria, pinned files, top open tech debts, and active unverified hypotheses into a consolidated executive context bundle. --- ## 23. Self-Healing Symbol & Line Range Resolver - **Tool:** `resolve_stale_symbols` - **When to use:** When files have been deleted, moved, or heavily refactored. - **Behavior:** Verifies graph entities and tech debt symbol references against disk and AST, flagging and auto-healing stale pointers or broken file paths. --- ## 24. Subgraph Topology Summarizer - **Tool:** `summarize_subgraph` - **When to use:** When needing a high-density, token-budgeted architectural summary of a module or component neighborhood. - **Behavior:** Generates a compact Markdown topology tree centered on a `root_entity` up to `depth` hops, capped strictly within a requested `max_tokens` budget. --- ## 25. Inter-Agent Signal Bus - **Tools:** `broadcast_agent_signal`, `query_agent_signals` - **When to use:** For real-time coordination and event-driven communication between concurrent subagents (e.g., `PrePushAuditor` signaling `AUDIT_PASSED` to parent agent). - **Behavior:** Ephemeral TTL-backed signal bus storing structured agent events, payloads, and artifact URIs. --- ## 26. Automated Session Checkpoint on Shutdown - **Tool:** `auto_session_checkpoint` - **When to use:** Executed automatically on `/shutdown` or manually when pausing a session. - **Behavior:** Captures active tasks, unverified hypotheses, recent commit ledgers, and workspace state into a permanent `HandoffMemo` for seamless turn-taking and recovery. --- ## 27. Hybrid Vector & BM25 Code Search - **Tool:** `search_snippets_hybrid` - **When to use:** When searching the snippet vault for reusable code patterns or Nushell pipelines. - **Behavior:** Combines BM25 term frequency keyword matching with semantic tag scoring to rank code snippets by relevance.