# 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`). - `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`). * **`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.