madappgang/mnemex-orchestration

Claudemem Multi-Agent Orchestration

Version: 1.1.0 Purpose: Coordinate multiple agents using shared mnemex output

Overview

When multiple agents need to investigate the same codebase:

1. Run mnemex ONCE to get structural overview
2. Write output to shared file in session directory
3. Launch agents in parallel - all read the same file
4. Consolidate results with consensus analysis

This pattern avoids redundant mnemex calls and enables consensus-based prioritization.

For parallel execution patterns, see: multimodel:multi-model-validation skill

Claudemem-Specific Patterns

This skill focuses on mnemex-specific orchestration. For general parallel execution:

• 4-Message Pattern - See multimodel:multi-model-validation Pattern 1
• Session Setup - See multimodel:multi-model-validation Pattern 0
• Statistics Collection - See multimodel:multi-model-validation Pattern 7

Pattern 1: Shared Claudemem Output

Purpose: Run expensive mnemex commands ONCE, share results across agents.

# Create unique session directory (per multimodel:multi-model-validation Pattern 0)
SESSION_ID="analysis-$(date +%Y%m%d-%H%M%S)-$(head -c 4 /dev/urandom | xxd -p)"
SESSION_DIR="ai-docs/sessions/${SESSION_ID}"
mkdir -p "$SESSION_DIR"

# Run mnemex ONCE, write to shared files
mnemex --agent map "feature area" > "$SESSION_DIR/structure-map.md"
mnemex --agent test-gaps > "$SESSION_DIR/test-gaps.md" 2>&1 || echo "No gaps found" > "$SESSION_DIR/test-gaps.md"
mnemex --agent dead-code > "$SESSION_DIR/dead-code.md" 2>&1 || echo "No dead code" > "$SESSION_DIR/dead-code.md"

# Export session info
echo "$SESSION_ID" > "$SESSION_DIR/session-id.txt"

Why shared output matters:

• Claudemem indexing is expensive (full AST parse)
• Same index serves all queries in session
• Parallel agents reading same file = no redundant computation

Pattern 2: Mode-Based Analysis Distribution

After running mnemex, distribute to mode-specific agents:

# Parallel Execution (ONLY Task calls - per 4-Message Pattern)
Task: code-analysis:investigate (architecture mode)
  Prompt: "Analyze architecture from $SESSION_DIR/structure-map.md.
           Focus on layer boundaries and design patterns.
           Write findings to $SESSION_DIR/architect-analysis.md"
---
Task: code-analysis:investigate (testing mode)
  Prompt: "Analyze test gaps from $SESSION_DIR/test-gaps.md.
           Prioritize coverage recommendations.
           Write findings to $SESSION_DIR/tester-analysis.md"
---
Task: code-analysis:investigate (implementation mode)
  Prompt: "Analyze dead code from $SESSION_DIR/dead-code.md.
           Identify cleanup opportunities.
           Write findings to $SESSION_DIR/developer-analysis.md"

All 3 execute simultaneously (3x speedup!)

Pattern 3: Consolidation with Deep Analysis

Task: code-analysis:deep-analysis
  Prompt: "Consolidate analyses from:
           - $SESSION_DIR/architect-analysis.md
           - $SESSION_DIR/tester-analysis.md
           - $SESSION_DIR/developer-analysis.md

           Create unified report with prioritized action items.
           Write to $SESSION_DIR/consolidated-analysis.md"

Pattern 4: Consolidated Feedback Reporting (v0.8.0+)

When multiple agents perform searches, consolidate feedback for efficiency.

Why Consolidate?

• Avoid duplicate feedback submissions
• Single point of failure handling
• Cleaner session cleanup

Shared Feedback Collection:

Each agent writes feedback to a shared file in the session directory:

# Agent writes feedback entry (atomic with flock)
report_agent_feedback() {
  local query="$1"
  local helpful="$2"
  local unhelpful="$3"

  # Use file locking to prevent race conditions
  (
    flock -x 200
    printf '%s|%s|%s\n' "$query" "$helpful" "$unhelpful" >> "$SESSION_DIR/feedback.log"
  ) 200>"$SESSION_DIR/feedback.lock"
}

# Usage in agent
report_agent_feedback "$SEARCH_QUERY" "$HELPFUL_IDS" "$UNHELPFUL_IDS"

Orchestrator Consolidation:

After all agents complete, the orchestrator submits all feedback:

consolidate_feedback() {
  local session_dir="$1"
  local feedback_log="$session_dir/feedback.log"

  # Skip if no feedback collected
  [ -f "$feedback_log" ] || return 0

  # Check if feedback command available (v0.8.0+)
  if ! mnemex feedback --help 2>&1 | grep -qi "feedback"; then
    echo "Note: Search feedback requires mnemex v0.8.0+"
    return 0
  fi

  local success=0
  local failed=0

  while IFS='|' read -r query helpful unhelpful; do
    # Skip empty lines
    [ -n "$query" ] || continue

    if timeout 5 mnemex feedback \
      --query "$query" \
      --helpful "$helpful" \
      --unhelpful "$unhelpful" 2>/dev/null; then
      ((success++))
    else
      ((failed++))
    fi
  done < "$feedback_log"

  echo "Feedback: $success submitted, $failed failed"

  # Cleanup
  rm -f "$feedback_log" "$session_dir/feedback.lock"
}

# Call after consolidation
consolidate_feedback "$SESSION_DIR"

Multi-Agent Workflow Integration:

Phase 1: Session Setup
  └── Create SESSION_DIR with feedback.log

Phase 2: Parallel Agent Execution
  └── Agent 1: Search → Track → Write feedback entry
  └── Agent 2: Search → Track → Write feedback entry
  └── Agent 3: Search → Track → Write feedback entry

Phase 3: Results Consolidation
  └── Consolidate agent outputs

Phase 4: Feedback Consolidation (NEW)
  └── Read all feedback entries from log
  └── Submit each to mnemex
  └── Report success/failure counts

Phase 5: Cleanup
  └── Remove SESSION_DIR (includes feedback files)

Best Practices Update:

Do:

• Use file locking for concurrent writes (flock -x)
• Consolidate feedback AFTER agent completion
• Report success/failure counts
• Clean up feedback files after submission

Don't:

• Submit feedback from each agent individually
• Skip the version check
• Block on feedback submission failures
• Track feedback for non-search commands (map, symbol, callers, etc.)

Role-Based Command Mapping

| Agent Role | Primary Commands | Secondary Commands | New Tools | Focus | |------------|------------------|--------------------|-----------|-------| | Architect | map, dead-code | context, dependency-graph | memory_write (persist arch findings) | Structure, cleanup, knowledge persistence | | Developer | callers, callees, impact | symbol | edit_symbol, rename_symbol, think | Modification scope, safe edits | | Tester | test-gaps | callers | references (find all usages including tests) | Coverage priorities | | Debugger | context, impact | symbol, callers | define, references (LSP-backed call sites) | Error tracing, type verification | | Ultrathink | ALL | ALL | ALL | Comprehensive |

Sequential Investigation Flow

For complex bugs or features requiring ordered investigation:

Phase 1: Architecture Understanding
  mnemex --agent map "problem area"  Identify high-PageRank symbols (> 0.05)

Phase 2: Symbol Deep Dive
  For each high-PageRank symbol:
    mnemex --agent context <symbol>    Document dependencies and callers

Phase 3: Impact Assessment (v0.4.0+)
  mnemex --agent impact <primary-symbol>  Document full blast radius

Phase 4: Gap Analysis (v0.4.0+)
  mnemex --agent test-gaps --min-pagerank 0.01  Identify coverage holes in affected code

Phase 5: Action Planning
  Prioritize by: PageRank * impact_depth * test_coverage

MCP Tool Integration: For single-agent workflows, mnemex MCP tools can be called directly instead of via CLI. The mnemex-search skill covers both modes.

Agent System Prompt Integration

When an agent needs deep code analysis, it should reference the mnemex skill:

---
skills: code-analysis:mnemex-search, code-analysis:mnemex-orchestration
---

The agent then follows this pattern:

1. Check mnemex status: mnemex status
2. Index if needed: mnemex index
3. Run appropriate command based on role
4. Write results to session file for sharing
5. Return brief summary to orchestrator

Best Practices

Do:

• Run mnemex ONCE per investigation type
• Write all output to session directory
• Use parallel execution for independent analyses (see multimodel:multi-model-validation)
• Consolidate with deep-analysis for cross-perspective insights
• Handle empty results gracefully

Don't:

• Run same mnemex command multiple times
• Let each agent run its own mnemex (wasteful)
• Skip the consolidation step
• Forget to clean up session directory after investigation completes

Session Lifecycle Management

Session TTL Cleanup: Clean up expired session directories manually or use a cleanup pattern:

Note: Use ai-docs/sessions/{session-id}/ for session artifacts instead of /tmp/ to comply with project conventions.

Manual Cleanup:

# Clean up specific session
rm -rf "$SESSION_DIR"

# Clean all old sessions (24+ hours)
find ai-docs/sessions -maxdepth 1 -name "analysis-*" -o -name "review-*" -mtime +1 -exec rm -rf {} \;

Error Handling Templates

For robust orchestration, handle common mnemex errors. See mnemex-search skill for complete error handling templates:

Empty Results

RESULT=$(mnemex --agent map "query" 2>/dev/null)
if [ -z "$RESULT" ] || echo "$RESULT" | grep -q "No results found"; then
  echo "No results - try broader keywords or check index status"
fi

Version Compatibility

# Check if command is available (v0.4.0+ commands)
if mnemex --agent dead-code 2>&1 | grep -q "unknown command"; then
  echo "dead-code requires mnemex v0.4.0+"
  echo "Fallback: Use map command instead"
fi

Index Status

# Verify index before running commands
if ! mnemex status 2>&1 | grep -qE "[0-9]+ (chunks|symbols)"; then
  echo "Index not found - run: mnemex index"
  exit 1
fi

Reference: For complete error handling patterns, see templates in code-analysis:mnemex-search skill (Templates 1-5)

---

Maintained by: MadAppGang Plugin: code-analysis v4.0.0 Last Updated: March 2026 (v4.0.0 - MCP-based integration, removed hook refs)