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) & Lifecycle Closure:
  • When selecting design patterns, crate choices, or system structure, call decisions (action: "log") with author, affected_components, alternatives_considered, decision, and consequence.
  • MANDATORY Definition of Done: When code implementing an ADR is committed, you MUST IMMEDIATELY call decisions (action: "update", id: "ADR-XXXX", status: "implemented", git_commit: <commit_hash>, git_branch: ). NEVER leave an ADR in accepted once the implementing code is committed. The user should NEVER have to manually flag or remind that an implemented ADR is still marked as 'accepted'.
• 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 (..).