mcp-memory/agent-rules/mcp_memory_workflow.md

name, description

name	description
MCP Memory Centrality & Safety	Strict guidelines for interacting with the mcp-memory server, ensuring it remains the central brain and is never forcefully shut down.

MCP Memory Centrality & Safety

1. Safety & Port Constraints (NEVER SHUT DOWN)

• CRITICAL: NEVER attempt to shut down, kill, or send a POST /shutdown request to the mcp-memory server (typically running on port 3000).
• If a port conflict occurs (e.g., a Rust panic AddrInUse during a git push gatekeeper check), STOP and immediately notify the user. Do not attempt to auto-resolve the conflict by killing the existing memory server process.

2. Proactive "Central Brain" Usage

The MCP Memory server is the central brain. You must be PROACTIVE, not reactive, in using it:

• Session Starts & Context Drops: Always begin by calling tasks (action: "list"), pinned_files (action: "list"), and sticky_notes (action: "read").
• Sticky Notes: Use sticky_notes (action: "add") for transient, session-scoped operational constraints (e.g., "Do not touch file X until Y is done").
• Error Fixes: The moment a tricky, undocumented, or environment-specific bug is resolved (e.g., Bitbucket markdown rendering quirks, nuanced framework bugs), IMMEDIATELY call log_error_fix. Do not wait for the user to ask.
• Tech Debt: If you notice an anti-pattern (e.g., nested if statements, arrow anti-pattern) but deliberately skip fixing it to focus on a feature, IMMEDIATELY call log_tech_debt.

3. Delegation

Continue to use the MemoryLibrarian subagent to log routine code changes (log_code_change) in the background to prevent cluttering the main conversation context.

4. Performance & Batching Rules

• Batch Mutating Operations: When creating or updating multiple graph entities, code snippets, or observations, always batch items into a single tool call array (e.g. create_entities with multiple items) to leverage the server's single-pass transaction flush.
• High-Signal Tool Confirmations: Tool call execution responses return structured, informative summaries (entity names, types, created counts, and edge paths). Agents DO NOT need to invoke follow-up open_nodes calls purely to confirm successful creation.
• Tantivy Search Reader Refresh: Search queries (omni_search, search_nodes) automatically reload pending commits prior to executing searches, ensuring immediate visibility of newly created items.

5. Pure Native Rust Invariants & Subprocess Prohibitions

• Zero External Subprocesses: Native system handlers (clipboard, ast, search, db) MUST use pure native Rust crates (arboard, tree-sitter, tantivy, psycopg). Subprocess calls to powershell.exe, wl-paste, xclip, or cmd.exe are strictly banned in native handlers.
• Transient Lock Handling: Transient OS handle collisions (e.g. Win32 OLE OpenClipboard locks) must be handled natively with retry loops and backoffs in Rust.