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

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 (or root_entity) up to a requested depth (e.g. 1 to 3 hops) and returns all connected entities and relations. Pass format: "markdown_tree" to generate a compact, token-budgeted Markdown topology tree capped within a requested max_tokens budget.

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

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

7.5 KiB Raw Blame History