Episode 15: Troubleshooting + Best Practices + Summary

This episode's scenario: You've mastered all Claude-Mem features. This final episode consolidates the troubleshooting handbook, shares daily best practices, and wraps up with a blog project retrospective.

15.1 Troubleshooting Checklist

🔴 Worker Not Running

# Check process
ps aux | grep claude-mem

# Check port
lsof -i :37777

# Reinstall
npx claude-mem install

# Check logs
cat ~/.claude-mem/logs/worker.log

🔴 Observations Not Appearing

🔴 Search Results Inaccurate

# Check ChromaDB
ls -la ~/.claude-mem/chroma/

# Rebuild vector index if corrupted
npx claude-mem rebuild-index

🔴 MCP Not Working in Claude Desktop

15.2 Daily Best Practices

Practice 1: Control Session Length

Don't let a single session exceed 300 tool calls.

Long sessions degrade compression quality, produce vague summaries, and fill the context window. End sessions intentionally after completing a feature module.

Practice 2: File Read Gate

Let Claude search memory before reading files:

Without File Read Gate:
  Claude → read_file("comments.ts") → 8,000 tokens

With File Read Gate:
  Claude → search("comment bug") → 150 tokens
  Claude → get_observations([67]) → 1,000 tokens
  Claude → knows the issue + fix direction → read only needed lines

Practice 3: Build Corpora Regularly

Maintain topic-based knowledge vaults for important modules:

Monthly maintenance:
  build_corpus("auth_system", tags=["auth","JWT","login"])
  build_corpus("database", tags=["Prisma","schema","migration"])
  build_corpus("deployment", tags=["deploy","CI/CD","env"])

Practice 4: Use <private> Tags

Build the habit: wrap keys, passwords, and internal URLs in <private> tags.

Practice 5: Check the Web UI

Spend 2 minutes weekly browsing http://localhost:37777. This helps catch anomalies early.

15.3 Full Architecture Overview

graph TB
    subgraph "User Interface Layer"
        CC["Claude Code"]
        CD["Claude Desktop"]
        WebUI["Web Viewer
(localhost:37777)"]
    end

    subgraph "7 Skills"
        S1["Memory Search"]
        S2["Smart Explore"]
        S3["Knowledge Agent"]
        S4["Make Plan"]
        S5["Do"]
        S6["Timeline Report"]
        S7["Plugin Release"]
    end

    subgraph "Protocol Layer"
        MCP["MCP Protocol"]
        Hooks["5 Lifecycle Hooks
SessionStart / UserPromptSubmit
PostToolUse / Stop / SessionEnd"]
    end

    subgraph "Service Layer"
        Worker["Worker Service
(Bun + Express, port 37777)"]
        SDK["Claude Agent SDK
(AI compression engine)"]
        SSE["SSE Event Stream"]
    end

    subgraph "Storage Layer"
        SQLite["SQLite
+ FTS5 full-text search"]
        Chroma["ChromaDB
vector semantic search"]
    end

    CC --> Hooks
    CC --> S1 & S2 & S3 & S4 & S5 & S6 & S7
    CD -->|MCP| MCP
    MCP --> Worker
    Hooks --> Worker
    Worker --> SDK
    SDK --> SQLite & Chroma
    Worker --> SSE
    SSE --> WebUI

    style CC fill:#6366f1,color:#fff
    style CD fill:#6366f1,color:#fff
    style Worker fill:#f59e0b,color:#000
    style SQLite fill:#10b981,color:#fff
    style Chroma fill:#10b981,color:#fff

15.4 Without vs With Claude-Mem

15.5 Further Reading

Series Complete

From Episode 1's "Why AI needs memory" to now, you've mastered Claude-Mem's complete knowledge system:

• ✅ Dual-database architecture (SQLite + ChromaDB)
• ✅ All 5 lifecycle hooks — triggers and data flow
• ✅ 3-layer progressive retrieval for token optimization
• ✅ All 7 Skills with hands-on practice
• ✅ MCP integration for Claude Desktop memory sharing
• ✅ Language, privacy, and context configuration

Go build AI workflows with memory.