Lesson 17: Q&A (Part 2) Advanced Skills & MCP Troubleshooting

⏱ Est. reading time: 8 min Updated on 5/7/2026

Scenario: This issue is aimed at mid-to-senior developers who have already started deeply utilizing the Skills chain and frequently relying on Claude Desktop workflows. It resolves the most frustrating "disobedient tool" problems in automated programming.

Q8: AST Parsing Fallback (Smart Explore Fallbacks)

Q: How does Smart Explore gracefully degrade when it fails to parse the Abstract Syntax Tree (AST) of non-standard languages (e.g., Rust with complex macros, cutting-edge Astro templates)?

A: The core dependency of Smart Explore is tree-sitter. If it encounters unsupported syntax structures, the system has a strict three-tier fallback mechanism:

  1. Precise AST Layer: Prioritizes extracting function signatures, class definitions, and cross-file imports.
  2. Regex Probing Layer (Fallback 1): If AST construction fails (syntax error or unsupported language), the system degrades to use Regex parsers, extracting simple text features like class xxx, fn xxx.
  3. Chunk Pagination Layer (Fallback 2): If structural recognition completely fails, the system treats it as a plain text file, forcing a 100-line-per-chunk pagination mode. At this point, outline folding becomes invalid, degrading to traditional read_file mode.

Q9: Corpus Precision Tuning

Q: How can I highly customize the Knowledge Agent's Corpus so that it accurately reads only specified business documentation, ignoring massive test codes?

A: When calling the build_corpus tool, you can use include and exclude parameters for allowlist interception, but this isn't enough. To achieve "ultimate precision", you should use Tags Compasses.

  1. Add preceding comments manually to business documents: Insert <!-- mem-tags: core-biz, auth --> at the top of markdown files.
  2. Pass strong association Tags during build: build_corpus(name="auth-core", tags=["core-biz"]).
  3. Use .memignore: Create a .memignore file in the project root (syntax same as .gitignore) and write __tests__/ and *.spec.ts inside. Knowledge Agent will physically block reading these files.

Q10: Goal Deviation Pullback (Make Plan + Do Course Correction)

Q: Make Plan + Do often "forgets" the major goal and falls into local Bug handling dead loops when executing complex tasks (like major version migrations). How can I effectively pull it back using Checkpoints?

A: AI Attention Drift in long-range tasks is an industry pain point. You can utilize Claude-Mem's staged state machine to force pullbacks:

  1. Explicitly insert stopping points: In the Plan, mandate "After completing every 2 sections, you must pause and report the current Diff to the human."
  2. Use Checkpoint rollbacks: At the beginning of executing Do, tell the AI: "Before starting modifications, call git commit -m 'checkpoint_auto'." If the AI falls into a local loop, you can manually interrupt, force it to rollback to the last Checkpoint, and attach a prompt: "Your previous train of thought was wrong, your goal is X, don't worry about Y."

Q11: [Mermaid Fault Tree] MCP Connection Troubleshooting

Q: When Claude Desktop connects to Claude-Mem via MCP, it prompts "Connection Refused" or "Tool Execution Timeout." How do I troubleshoot this?

A: Please refer to the following diagnostic tree for step-by-step troubleshooting:

graph TD
    Start((Start Diagnostic)) --> A{Check config path}
    A -->|Incorrect| A1[Fix claude_desktop_config.json path]
    A -->|Correct| B{Is Worker Service online?}
    
    B -->|Offline| B1[Run npx claude-mem start in terminal]
    B -->|Online, but still Refused| C{Are Node Env variables active?}
    
    C -->|Inactive| C1[Configure absolute node path in config]
    C -->|Active| D{Timeout error?}
    
    D -->|Yes| D1[SQLite lock contention, kill residual processes]
    D -->|No| E[View ~/Library/Logs/Claude/mcp.log for underlying errors]

    style Start fill:#6366f1,color:#fff
    style E fill:#f43f5e,color:#fff

Key Tip: If MacOS users installed node via nvm, Claude Desktop's sandbox environment often cannot find the node command. Please make sure to fill in the absolute path of node in the command field of claude_desktop_config.json (e.g., /Users/xxx/.nvm/versions/node/v20.0.0/bin/node).

Q12: Multi-instance Setup (Multi-worker Setup)

Q: Is it possible to simultaneously run multiple differently configured Claude-Mem Workers on the same computer (e.g., one for confidential company projects, one for open-source)?

A: Yes, via port isolation and configuration overriding.

When starting a Worker, you can specify environment variables:

# Start an open-source exclusive Worker
CLAUDE_MEM_PORT=37778 CLAUDE_MEM_DB_PATH=~/.claude-mem/open-source npx claude-mem start

This way, you get two independent daemons. When using Claude Code, you also need to set environment variables telling it which port to connect to: export CLAUDE_MEM_URL=http://localhost:37778.

Q13: Timeline Ordering Anomaly

Q: Why are the project "Chronicle" event sequences generated by Timeline Report sometimes out of order?

A: This is caused by timestamp drift from asynchronous concurrent writes. When you quickly execute multiple operations using parallel scripts, each on_turn_end hook is triggered almost simultaneously. Due to the varying extraction times of LLMs, if the system uses "summary completion time" as the timeline event time, the order gets messed up.

Latest version fix: The system currently forces the use of the "Client Unix Timestamp when Hook was triggered" as the primary sorting key. If your historical data is still out of order, you can manually trigger a recalculation: npx claude-mem repair-timeline.

Q14: [Mermaid Architecture] Customizing MCP Extension Plugins

Q: How can I write custom MCP Tools and safely mount them onto Claude-Mem's Worker?

A: Claude-Mem is designed as a highly extensible architecture. You can mount your own scripts through its Plugin Registry:

graph LR
    subgraph "Claude-Mem Ecosystem"
        Worker[Core Worker]
        Registry[Plugin Registry]
    end

    subgraph "Your Custom Scripts (my_script.ts)"
        T1[Tool 1: Fetch JIRA]
        T2[Tool 2: Deploy AWS]
    end

    Registry --Dynamically Load--> my_script.ts
    my_script.ts --Register--> Worker
    Worker --Expose to--> Client(Claude Desktop)

Steps:

  1. Write a TypeScript file adhering to MCP protocol specifications.
  2. Place it in the ~/.claude-mem/plugins/ directory.
  3. Restart the Worker, and the system will automatically scan and pass it through to the AI as native tools.