mcp-memory/instructions.md

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).
• Relation Tool Parameters: create_relations supports Serde field aliases (source -> from, target -> to, relationType/type -> relation_type) so LLM tool calls succeed seamlessly regardless of parameter naming.

Note

The server automatically enforces and migrates incoming entity and relation types to these canonical casing rules on every read and write operation. Store operations enforce atomic lock scope for serialization/deserialization and enter Quarantine Mode upon database corruption to prevent data overwrite hazards.

---

2. Consolidated Smart Tools Architecture

The server consolidates granular single-purpose tools into domain-named smart tools. Always prefer the consolidated tools over legacy aliases:

• tasks: Complete task lifecycle management.

  • action: "add": Create a new task (requires title, optional description, git_branch, parent_id, dependencies).
  • action: "update": Update task status (requires id, status: "pending" | "completed" | "cancelled").
  • action: "delete": Delete task and child tasks (requires id).
  • action: "list": List active tasks (optional git_branch, summary_level: "compact" | "detailed" | "full", max_tokens).
  • action: "set_criteria": Set acceptance criteria (requires id, criteria: Vec<String>).
  • action: "verify": Verify criteria met (requires id).

• milestones: Milestone tracking.

  • action: "add": Create milestone (requires title).
  • action: "update": Update milestone status (requires id, status).
  • action: "list": List milestones.

• sticky_notes: Ephemeral scratchpad notes with TTL.

  • action: "add": Add note (requires content, optional ttl_seconds, session_only).
  • action: "read": Read all active notes.
  • action: "delete": Delete note by index (requires 1-based index).
  • action: "clear": Clear all sticky notes.

• handoff_memos: Session handoff notes for future agents.

  • action: "leave": Leave a memo (requires content).
  • action: "read": Read active handoff memos.
  • action: "clear": Clear memos.

• pinned_files: Focus file working set.

  • action: "pin": Pin file to focus set (requires path).
  • action: "unpin": Unpin file from focus set (requires path).
  • action: "list": List pinned files.

• context_workspaces: Workspace context state snapshots.

  • action: "save": Save context workspace (requires name).
  • action: "load": Restore saved context workspace (requires name).
  • action: "list": List saved context workspaces.
  • action: "delete": Delete saved context workspace (requires name).
  • action: "diff": Compare two saved context workspaces (requires name, other_name).

• pr_checklist: Pre-commit and PR checklist.

  • action: "add": Add checklist item (requires description).
  • action: "get": Get PR checklist items.
  • action: "clear": Clear PR checklist.

• snippets: Reusable code snippet vault.

  • action: "store": Store snippet (requires query as name, optional language, code, description, tags).
  • action: "search": Search snippet vault (optional query, tags, hybrid: true).
  • action: "delete": Delete snippet (requires id).
  • action: "tag": Attach classification tags (requires id, tags: Vec<String>).

• decisions: Architectural Decision Records (ADRs).

  • action: "log": Log ADR (requires title, optional status, context, decision, consequences).
  • action: "query": Query ADRs (optional query).
  • action: "delete": Delete ADR (requires id).

• tech_debt: Engineering debt backlog.

  • action: "log": Log debt item (requires description, optional ideal_solution, git_commit, git_branch, symbol_references, line_range).
  • action: "resolve": Resolve debt item (requires id).
  • action: "list": List debt items (optional include_resolved).

• environment: Infrastructure and requirements tracking.

  • action: "update_fingerprint": Update tool versions.
  • action: "read_fingerprint": Read tool versions fingerprint.
  • action: "log_requirement": Log environment variable requirement (requires key).
  • action: "register": Register target environment (requires name).
  • action: "get_details": Read full environment details.

• clipboard: OS Clipboard management.

  • action: "read": Read OS clipboard.
  • action: "write": Write text/html/files/image to clipboard.
  • action: "toggle_watch": Toggle auto-clipboard watcher.

---

4. High-Signal Tool Responses & Performance Guidelines

To optimize context usage, response times, and LLM reasoning efficiency:

• High-Signal Feedback:

  • MCP tool calls (such as create_entities, create_relations, add_observations, pin_file) return explicit, structured summaries containing created names, types, edge counts, and relation paths.
  • LLMs do NOT need to execute follow-up open_nodes calls merely to confirm successful creation.

• Batch Operations:

  • When creating or updating multiple entities, snippets, or observations, always batch items into a single tool call array (e.g. create_entities with multiple array items) rather than making separate calls.
  • The server handles batch store mutations serially in a single transaction pass with single-permit event-driven flushes.

• Real-time Tantivy Search Indexing:

  • The Tantivy search engine automatically checks pending commits and reloads search readers prior to executing omni_search or search_nodes. Search queries always return up-to-date document results immediately following mutations.
  • Single-item deletions use targeted document removal rather than global index wipes.

• Real-Time AST & Workspace Source Code Symbol Scanning:

  • find_symbol_references, get_callers, and analyze_impact scan both stored code snippets and physical workspace source code files on disk (.rs, .ts, .py, .go, .java, .c, .cpp), providing accurate AST symbol references and call site tracking.

• Graph Entity Merge & Self-Loop Protection:

  • merge_entities re-points all relations from source_entity to target_entity and automatically prunes cyclic self-loops (target -> target).

• Safe UTF-8 Token Truncation:

  • Large responses (e.g. get_active_worktree_context, read_graph, summarize_subgraph) are safely truncated along UTF-8 character boundaries (floor_char_boundary), ensuring response bounds without runtime panics.

4. Automated Error Fix Auto-Matcher

• Tools: log_error_fix, search_error_fixes (and alias suggest_error_fix)
• When to use: When encountering a build error, test failure, or stack trace. Call search_error_fixes with either a text query or stack_trace before attempting a fix from scratch.
• Behavior: Computes cosine similarity between error trace embeddings and past resolution logs when stack_trace is provided, or keyword filtering when query is provided, returning top matched solutions, modified files, and git commits.

---

5. Memory State Checkpointing & Rollbacks

• Tool: checkpoint_state, restore_state (or create_snapshot, restore_snapshot)
• 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. 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 using pre-computed lowercase keys to identify near-duplicates (e.g., APIGateway vs ApiGateway), and provides structured merge_entities recommendations or auto-prunes orphans.

---

7. 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.

---

9. Native Rust Invariants & Subprocess Prohibition (CRITICAL)

To maintain maximum security, speed, and cross-platform reliability:

• Zero Subprocess Fallbacks: System and server tools (clipboard, ast, search, db) MUST strictly use pure native Rust crates (arboard, tree-sitter, tantivy, psycopg). Invocations of external shell commands (powershell.exe, wl-paste, xclip, cmd.exe) are strictly prohibited in native handlers.
• Transient Lock Recovery: Transient OS handle collisions (such as Win32 OLE OpenClipboard lock contention) must be handled using native retry loops with backoffs directly in Rust.
• Automated Static Regression Gates: Automated AST/source audit tests (e.g. test_no_subprocess_clipboard_regression) verify at test time that forbidden subprocess patterns are absent from handler implementations.

---

10. High-Performance Concurrency & Resilience Guarantees

• Zero-Allocation NDJSON Reader: mcp-stdio reclaims line buffers via std::mem::take and in-place trimming to eliminate heap allocations during high-frequency NDJSON message parsing.
• Micro-Batched Fastembed Inference: generate_embeddings_async chunks text arrays into 32-item micro-batches inside spawn_blocking, eliminating RAM/CPU spikes during batch indexing.
• Single-Handle OS Clipboard Retries & Image Downsampling: WriteClipboardHandler initializes OS clipboard handles once per operation and downsamples images exceeding 2048 \times 2048 resolution before writing raw RGBA bytes.
• Zero Transaction Drop Persistence Guarantee: Store::modify automatically spawns an async task to execute push_async with channel backpressure if push encounters queue saturation, ensuring zero data loss under spike write loads.
• Non-Blocking Read Lock Sticky Notes: StickyNotesHandler (action = "read") queries notes using shared read locks, executing write pruning only when expired items exist.
• Token-Budgeted Query Projections: Decision queries (query_decisions) support limit caps and compact include_body: false projections for token budget optimization.
• Serde Parameter & Enum Ergonomics: Action enums (StickyNoteAction, SnippetSearchMode, Relation) support case-insensitive variants and common synonyms (create/add, remove/delete, list/read, source/from, target/to, relationType/relation_type) ensuring seamless LLM tool execution.
• Atomic Search Index Swaps: MemoryState::rebuild_index constructs and populates a new MemoryIndex instance in isolation before performing an atomic pointer swap (*self.search_index.write().await = new_idx), eliminating transient empty search result windows.
• Non-Blocking Tantivy Search Queries: MemoryIndex::search queries current index searcher snapshots without executing synchronous disk commit locks, preventing query stalls during heavy background indexing.
• Zero-Allocation HashSet<&str> Snippet Deduplication: indexer.rs utilizes borrowed HashSet<&str> name lookups during snippet batch modifications, eliminating heap string re-allocations inside the store write lock.
• AST Recursion Depth Safeguard & Zero-Copy Borrowing: Tree-sitter AST traversal caps recursion depth at 100 to prevent thread stack overflows and borrows string slices (&str) during AST node walking.
• Strongly-Typed SearchResult & Pre-Allocated Search Vectors: search.rs uses a strongly-typed SearchResult struct with named fields and pre-allocates result vector capacity (Vec::with_capacity(top_docs.len())).
• BFS Graph Traversal Pre-allocation & Visited Node Upper Bound: GraphQueryBuilder::find_shortest_path pre-allocates adjacency map capacity (HashMap::with_capacity(relations.len() * 2)) and enforces a visited node upper bound (10,000 max) to guarantee deterministic BFS runtime.
• LLM Tool Schema Ergonomics & Context Guidance: ReadGraphHandler schema explicitly instructs LLMs on namespace filtering and search_nodes / get_subgraph tools for large graph discovery.
• Filesystem Event Debouncing & Proactive State Refresh: spawn_watcher implements a sliding 250ms debouncing window per file path, ignores .git, target, .gemini, and node_modules, and broadcasts activity events to MemoryState.
• Buffered Line-by-Line AST Workspace Symbol Scanning: scan_workspace_for_symbol reads workspace files via BufReader line streams instead of loading entire files into heap strings, preventing memory spikes when traversing source trees.
• AST Node Type Aliasing & Skeleton Preallocation: replace_ast_node documents friendly node aliases (function, fn, method, struct, class, enum, trait, type), and read_file_skeleton preallocates string buffer capacity (code.len() / 2).
• Batch Vector Indexing & Similarity Score Guidance: VectorDB provides index_documents_batch for single-request multi-point vector upserts and explicit score calibration notes (\ge 0.75 high confidence match).
• Compact JSON MCP Resources & UTF-8 Activity Truncation: MCP resources serialize using compact JSON (to_string), TerminalHistoryResource / MilestonesResource enforce output bounds, and format_tool_activity_description uses floor_char_boundary for guaranteed UTF-8 safety.
• SIMD-Friendly Single-Pass Cosine Similarity: cosine_similarity calculates dot product and Euclidean norm squares in a single linear pass over float vectors, enabling SIMD compiler auto-vectorization.
• Safe Stream Decoding on Log Tails: Log tail operations (get_recent_logs) read raw bytes and decode using lossy UTF-8 conversion (String::from_utf8_lossy) to ensure resilience when seeking across multi-byte UTF-8 boundaries.
• Task Summary UTF-8 Truncation Safety: tasks tool (action = "list") truncates serialized task text strictly along UTF-8 character boundaries using floor_char_boundary when enforcing max_tokens.
• Sequential Snapshot Lock Scope Flattening: GenerateStandupReportHandler reads tasks, ledger, and session_summaries sequentially rather than nesting read locks, preventing multi-lock deadlocks during concurrent store modifications.
• Directory Tree Depth Safeguard: ReadDirectoryArchitectureHandler caps directory recursion at depth 10 to prevent stack overflow on deep or cyclic directory structures.
• Deterministic Total-Order Score Ranking: OmniSearchHandler uses f64::total_cmp for Reciprocal Rank Fusion (RRF) score sorting, guaranteeing deterministic NaN-safe search result ordering.
• RPC Timeout Memory Hygiene: nvim-core maintains request hygiene by removing pending request entries from static RPC maps upon timeout or channel drop, eliminating orphan memory leaks.