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

[!NOTE] Two-Tier Memory Architecture

1. Tier 1 (Static Markdown): Repository rules, coding style, tech constraints, and architectural boundaries belong in static git-tracked markdown (rules/*.md, instructions.md) and system prompts for 0ms latency and deterministic turn-0 enforcement.
2. Tier 2 (Structured DB & Telemetry): The MCP Memory server specializes in high-volume, dynamic data: file modification ledgers (audit_ledger), terminal command history, error resolutions (log_error_fix), active tasks, and preflight context aggregation.

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"), get_preflight_context, and omni_search to regain context.
• Context Switching: When switching tasks or branches, use manage_checkpoint (action: "create") to freeze state, and use manage_checkpoint (action: "restore") to restore state for the task.
• 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. Supply repo_name, error_category, and stack_trace so future searches can perform embedding-based match.
• 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 tech_debt (action: "log") with description, file_path, line_range, workaround, effort_estimate, and severity.
• Architectural Decisions (ADR): When selecting design patterns, crate choices, or system structure, call decisions (action: "log") with author, affected_components, alternatives_considered, decision, and consequence.
• Task Management: When creating tasks, supply priority ('low'|'medium'|'high'|'urgent'), assigned_agent (e.g. subagent role), verification_command (automated test command), and acceptance_criteria.
• VCS & SVN Agnosticism: Supply vcs_type ('git'|'svn'|'hg'), vcs_revision (git hash or svn revision like 'r12345'), and upstream_url to log_code_change and workspace tools.
• Terminal & Shell Context: Terminal sessions and commands are automatically tracked in the server. Query /terminal/history or recent logs when analyzing shell execution context.
• Hypotheses & Root Cause Analysis: When diagnosing complex bugs or race conditions, call hypotheses (action: "log" / "query") to record test evidence and maintain reasoning trails across sessions.
• Inter-Agent Coordination: Autonomous subagents should call agent_signals (action: "broadcast" / "query") to publish events and discover peer agent status.
• Process & Daemon Logs: Query or tail daemon logs with process_logs (action: "get", "watch", "clear") instead of dumping log files into context.

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.
• Bounded Telemetry Buffers: High-volume telemetry logs (error_fixes max 300, ledger max 500, handoff_memos max 200, session_summaries max 200, agent_signals max 500) enforce deterministic length caps to guarantee low memory footprints over long sessions.

5. Pure Native Rust Invariants & Security

• 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.
• Atomic Serialization Scope: All store updates (Store::modify / modify_async) perform state mutation and JSON serialization inside an atomic write lock scope to guarantee thread-safe DbWriteQueue synchronization.
• Path Traversal Guards: AST and file handler operations enforce path canonicalization (validate_safe_path) to prevent directory traversal vulnerabilities (..).