134 lines
7.5 KiB
Markdown
134 lines
7.5 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`).
|
|
|
|
> [!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.
|
|
|
|
---
|
|
|
|
## 3. Subgraph Expansion & Multi-Hop Navigation
|
|
- **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.
|