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, repo_name, priority: "low" | "medium" | "high" | "urgent", assigned_agent, verification_command, 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, optional proof).
milestones: Milestone tracking.
- action: "add": Create milestone (requires title, optional namespace, target_date, description, deliverables: Vec<String>, repo_name).
- action: "update": Update milestone status (requires id, status: "active" | "completed" | "cancelled").
- action: "list": List milestones (optional namespace).
handoff_memos: Session handoff notes for future agents.
- action: "leave": Leave a memo (requires content, optional vcs_revision, repo_name, git_branch, blockers: Vec<String>, action_items: Vec<String>, expires_at).
- action: "read": Read active handoff memos.
- action: "clear": Clear memos.
snippets: Reusable code snippet vault.
- action: "store": Store snippet (requires query as name, optional language, code, description, tags, origin_file, line_range, repo_name).
- 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: "accepted" | "proposed" | "deprecated" | "superseded", context, decision, consequence, author, affected_components: Vec<String>, alternatives_considered: Vec<String>, supersedes, repo_name).
- 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, file_path, line_range, workaround, effort_estimate, severity: "low" | "medium" | "high" | "critical", git_commit, git_branch, symbol_references, repo_name).
- 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 (requires tool_versions: Map<String, String>, optional repo_name).
- action: "read_fingerprint": Read tool versions fingerprint.
- action: "log_requirement": Log environment variable requirement (requires key, description, is_secret, optional default_value, validation_regex, repo_name).
- action: "register": Register target environment (requires name, url, optional description, requires_vpn, env_type: "dev" | "staging" | "qa" | "prod", healthcheck_endpoint, ssh_host, repo_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.
hypotheses: Diagnostic hypothesis memory.
- action: "log": Record diagnostic hypothesis (requires hypothesis, optional status: "open" | "verified" | "disproven", evidence: Vec<String>, test_command, git_branch, repo_name).
- action: "query": Query hypotheses (optional status, git_branch, repo_name).
agent_signals: Inter-agent signal bus.
- action: "broadcast": Broadcast signal to other agents (requires signal_type, payload, optional target_agent, ttl_seconds).
- action: "query": Query active signals (optional signal_type, include_expired: bool).
process_logs: Process and daemon log management.
- action: "watch": Register or update log file watcher (requires label, file_path, optional description).
- action: "get": Retrieve recent log lines from watched process log (requires label, optional tail_lines: usize).
- action: "clear": Clear or truncate watched process log file (requires label).

3. VCS & SVN Agnosticism & Multi-Repo Provenance

To support diverse enterprise repositories (Git, Subversion / SVN, Mercurial / Hg, Monorepos):

vcs_type: Designates the VCS engine ("git", "svn", "hg", "perforce", or "none").
vcs_revision: Agnostic commit hash or SVN revision identifier (e.g., "r12458", "3e4f7a9").
upstream_url: Canonical remote repository URL (e.g. https://svn.corp/repo/trunk, git@bitbucket.org:org/repo.git).
repo_name: Logical project or repository identifier allowing multiple repositories to share or partition memory namespaces cleanly without collision.
Audit Ledger (log_code_change): Enriched with vcs_type, vcs_revision, upstream_url, author, diff_summary, and extensible metadata: HashMap<String, String>.

4. Terminal & Process Telemetry

The server ingests and tracks active terminal commands and sessions:

Active Terminals: Tracks PIDs, shell interpreters (pwsh, bash, nu, zsh), current working directories (cwd), command exit codes, and timestamps.
Terminal History Endpoint: /terminal/history exposes recent shell commands and output streams to dashboard and LLMs to prevent lost shell context.
Quality Gate Enforcement: GateRecord captures pre-flight and pre-push validation passes with gate_type, enforcer, status, validation_log, and repo_name.

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

Explicit Fail-Fast Persistence Safety: Replaced silent fallback to temporary databases (/tmp/mcp_store_fallback_*) with an explicit open retry and fail-fast panic unless MCP_ALLOW_TMP_FALLBACK=1 is explicitly set, preventing silent data loss.
Async Mutex Deadlock Elimination: Converted shared state and Neovim connection locks (shutdown_tx, NVIM_CONN, ACTIVE_SOCKET, HEADLESS_PROC) to tokio::sync::Mutex to prevent worker thread pool starvation across .await points.
Telemetry Session Deduplication & Channel Pruning: Added LAST_SESSION in-memory state deduplication for UDP telemetry writes (eliminating disk I/O thrashing) and distinguished WebSocket TrySendError::Full backpressure vs TrySendError::Closed client pruning.
Graph Adjacency Indexing: Leverages KnowledgeGraph::build_adjacency_map to build O(1) lookup adjacency lists for fast BFS shortest path graph queries.
Atomic Store Write Lock Minimization: Store::modify and Store::modify_async release write guards immediately after in-memory state mutations, serializing JSON payloads under read locks to allow non-blocking concurrent readers.
Async Commit Index Reader Auto-Reload: MemoryIndex::commit() automatically triggers reader.reload() upon completing background commits, guaranteeing immediate visibility of newly indexed document terms.
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.
Dynamic Character Micro-Batched Fastembed Inference: generate_embeddings_async dynamically batches text arrays using a 16,000 character budget ceiling inside spawn_blocking, preventing heap spikes during vector indexing while keeping ONNX SIMD execution saturated.
Bounded Telemetry Detail Records: Activity and terminal telemetry buffers enforce a 4,000 character truncation ceiling on log details (ActivityRecord, TerminalHistory) to prevent unbounded RAM growth under high RPC throughput.
Zero-Allocation Stream Formatting: Graph condensation loops (condense_graph_worker) format node/relation subgraphs into stream buffers via std::fmt::Write, eliminating intermediate String allocation overhead.
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.
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 (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 (process_logs, action: "get") 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.
Embedding Input Safeguard: generate_embedding_async returns explicit errors for empty/0-length text inputs instead of returning empty vectors, preventing downstream vector dimension mismatches during cosine similarity calculations.
Path Traversal Security Guards: validate_safe_path enforces path canonicalization and rejects relative parent traversal components (..) across file and process log handlers (process_logs / ProcessLogsTool).
Watcher Map Memory Eviction: Proactive daemon file watcher in watcher.rs caps last_processed map size at 1,000 entries and purges entries older than 10 minutes to prevent monotonic memory leakage.
Comprehensive Serde Casing Aliases: All 11 consolidated tool action enums (TaskAction, MilestoneAction, SnippetAction, DecisionAction, TechDebtAction, EnvAction, ClipboardAction, HandoffMemoAction, HypothesisAction, AgentSignalAction, ProcessLogAction) include serde alias attributes supporting snake_case, camelCase, PascalCase, and uppercase variants for maximum LLM casing resilience.
Two-Phase Graph Condensation: condense_graph_worker uses a 2-phase commit (non-destructive read_with -> graph insert -> prune by timestamp/content) to prevent data loss if summarization or graph insertion fails.
Store Write Lock Minimization: Store::modify and Store::modify_async unblock concurrent readers during JSON serialization by releasing the write lock immediately after mutating memory state.
Redb Database Lock Retry Backoff: init_db retries transient Redb lock contention with exponential backoff (3 attempts, 150ms delay) before falling back.
Offloaded Background Index Rebuilds: MemoryState::rebuild_index offloads graph snapshot cloning and Tantivy document re-indexing into tokio::task::spawn_blocking to avoid stalling async event loops.
Broadcast Watch-Based Shutdown Channels: Background workers utilize tokio::sync::watch for broadcast shutdown notifications without consuming cancellation signals.
Consolidated Neovim Tool Suite (v2): The Neovim server exposes 7 consolidated domain tools (nvim_buffer, nvim_window, nvim_view, nvim_diagnostics, nvim_visual, nvim_execute_lua, nvim_system) with comprehensive action dispatching.
Fallback Vector Search Parity: In-memory vector search fallback indexes Knowledge Graph entities, observations, and error fixes when external vector databases are unavailable.

22 KiB Raw Blame History