188 lines
16 KiB
Markdown
188 lines
16 KiB
Markdown
# 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.
|
|
|
|
|