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 (agent-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:

Passive Resource Retrieval (Zero-Turn Latency)

Before making expensive active tool calls, read available MCP resources:

• memory://tasks/active: Currently uncompleted tasks, priorities, and criteria.
• memory://decisions/active: Active architectural decisions in accepted status.
• memory://tech_debt/unresolved: Open engineering tech debt items.
• memory://session/delta: Recent changes, active tasks, code edits, and notes created in the last 2 hours.
• memory://terminal/recent: Recent terminal commands, interpreters (pwsh, bash, nu), working dirs, and exit codes.
• memory://activity/recent: Real-time IDE and developer activity event logs.
• memory://milestones: Project milestones and deliverable tracking.
• memory://graph/entities & memory://graph/relations: Knowledge graph snapshots.

Active Tool Invocations

• Session Starts & Context Drops: Begin by checking memory://tasks/active and memory://session/delta (or running context_warmup prompt), calling get_preflight_context and omni_search to regain operational 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, IMMEDIATELY call log_error_fix. Supply repo_name, error_category, and stack_trace so future searches can perform embedding-based match via search_error_fixes.
• Tech Debt: If you notice an 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 repository also executes scripts/git-reconcile.py on post-commit hooks (just install-git-hooks) to reconcile commit references automatically.
• 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 over zero-latency UDP. Query /terminal/history or memory://terminal/recent 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.
• Clipboard & Multimodal Screenshots:
  • User Image & Visual Queries: When the user says "look at image in clipboard", "see screenshot", "check the clipboard", or refers to an error screenshot, ALWAYS call clipboard(action: "image").
  • Decoupled Screenshot History: Even if the user got sidetracked and copied text/URLs afterwards, clipboard(action: "image") reliably retrieves the last captured screenshot from the event-driven cache with exact metadata (file_path, file_path_wsl, age, dimensions, ocr_text).
  • WSL Ubuntu Compatibility: For WSL sessions, use the returned file_path_wsl (e.g. /mnt/c/...) directly with view_file.
  • Text-Only Models & Fast Context: Use the returned deterministic ocr_text to immediately extract error traces, URLs, and code snippets without waiting for multimodal vision tokens.
  • Copying Formatted Tables / Data: clipboard(action: "read") automatically strips Win32 CF_HTML headers and converts HTML tables directly into clean GFM Markdown.
• End-of-Session Handoff: When finishing work or logging off, trigger the handoff_routine prompt or call generate_standup_report and handoff_memos (action: "leave").

3. Delegation

Continue to use the MemoryLibrarian, PrePushAuditor, BugDiagnostician, ScrumMaster, and DevOpsSRE subagents to offload graph curation, pre-push auditing, hypothesis testing, task tracking, and session handoffs.

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