| name | claude-mem-orchestrator |
| description | Orchestrates claude-mem persistent memory for maximum session context. Use at conversation start to load relevant past work, when the user says 'what did we do last time', 'load context', 'recall', 'remember', 'search memory', 'what do you know about this project', or when starting work on a project that has prior sessions. Also use when the user wants to save important decisions, search past sessions, or generate project history reports. |
Claude-Mem Orchestrator
claude-mem v12 — persistent cross-session memory via MCP tools on port 37777.
Plugin location: ~/.claude/plugins/cache/thedotmack/claude-mem/12.0.1/
Core Principle
Memory is automatic — hooks capture everything. The orchestrator's job is retrieval and routing: load the right context at the right time, and route memory queries to the right tool. Keep token usage lean by always filtering before fetching.
Step 0: Orient — Check Memory Health
Before anything, verify claude-mem is running:
- Check if
<claude-mem-context> blocks appeared in this session (auto-injected on session start)
- If not, check worker health:
curl -s http://localhost:37777/health
If the worker is down:
node "$HOME/.claude/plugins/cache/thedotmack/claude-mem/12.0.1/scripts/bun-runner.js" \
"$HOME/.claude/plugins/cache/thedotmack/claude-mem/12.0.1/scripts/worker-service.cjs" start
If port 37777 is stuck (stale socket from crashed process):
- Wait 1-2 minutes for OS to release, then retry
- Or restart the terminal / VS Code window
Once healthy, show:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
MEM | Worker: [healthy / down]
| Project: [detected project name]
| Context: [auto-injected / manual load needed]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Step 1: Assess Intent & Route
| User signal | Action |
|---|
| Starting a new session on a known project | Auto-context — search + fetch recent work (Route A) |
| "What did we do last time?" / "recall" | Memory search — targeted query (Route B) |
| "Save this decision" / "remember that..." | Save memory — store important context (Route C) |
| "What's the project history?" | Timeline report — use /timeline-report skill |
| "Search code structurally" | Smart explore — use /smart-explore skill |
| "Create a plan with memory context" | Route to /make-plan skill |
| "Execute a plan" | Route to /do skill |
Route A: Auto-Context Load (Session Start)
Use this when starting work on a project with prior sessions. Goal: get the user productive in under 30 seconds with full context.
Step 1: Search recent project work
search(query="recent work", limit=20, project="<project-name>", type="observations", orderBy="date_desc")
Also search for the specific area of work if known:
search(query="<topic from user's first message>", limit=10, project="<project-name>")
Step 2: Get timeline context around the most recent session
timeline(query="latest session", depth_before=5, depth_after=0, project="<project-name>")
Step 3: Fetch full details for the most relevant items
Review titles from search results. Pick the 3-5 most relevant IDs. Discard the rest.
get_observations(ids=[<selected IDs>], orderBy="date_desc")
Step 4: Summarize to the user
Present a brief status:
- What was last worked on and when
- Key decisions made
- Any open items or blockers from last session
- Suggested next steps
Route B: Memory Search (Targeted Query)
When the user asks about specific past work.
Always follow the 3-layer pattern — never fetch without filtering first:
-
Search — get compact index (~50-100 tokens/result)
search(query="<user's question>", limit=20, project="<project>")
-
Timeline — get chronological context around interesting results
timeline(anchor=<best_match_id>, depth_before=3, depth_after=3)
-
Fetch — get full details only for filtered IDs (~500-1000 tokens each)
get_observations(ids=[<selected>])
Present results as a narrative, not raw data. Connect the dots between observations to tell the user what happened and why.
Route C: Save Important Context
When the user explicitly wants to preserve a decision, insight, or context for future sessions.
save_memory(
text="<structured summary of what to remember>",
title="<concise title>",
project="<project-name>"
)
What's worth saving manually (hooks capture most things automatically):
- Architectural decisions and their rationale
- "We tried X and it failed because Y" — failure context
- User preferences discovered during conversation
- External knowledge not in the codebase (e.g., "the API changed in v3")
What NOT to save (hooks already capture these):
- Tool usage and file reads (PostToolUse hook)
- Session summaries (Stop hook)
- Code changes (captured via git + observation hooks)
Troubleshooting
Worker won't start
cat ~/.claude-mem/logs/claude-mem-$(date +%Y-%m-%d).log | tail -20
netstat -ano | grep 37777
lsof -i :37777
MCP tools not available
- In VS Code: run
Developer: Reload Window (Ctrl+Shift+P)
- Check plugin is enabled:
~/.claude/settings.json should have "claude-mem@thedotmack": true
- Verify MCP server config exists:
~/.claude/plugins/cache/thedotmack/claude-mem/12.0.1/.mcp.json
No context auto-injected
- Worker must be running BEFORE session starts
- Check
~/.claude-mem/claude-mem.db exists and has data
- Start worker manually, then open a new conversation
VS Code extension vs CLI
claude-mem works identically in both — same hooks, same MCP server, same worker on port 37777. If MCP tools appear in CLI but not in VS Code extension panel, this is a known VS Code extension issue — use Developer: Reload Window or run claude from the integrated terminal as fallback.
Anti-patterns to Flag
- Fetching all observations without filtering — always search first, then fetch by ID. 10x token savings.
- Ignoring auto-injected context — check for
<claude-mem-context> blocks before doing manual searches.
- Saving redundant memories — hooks capture tool usage and sessions automatically. Only manually save decisions and insights.
- Searching without project filter — always pass
project parameter to avoid cross-project noise.
Focus Recovery
If the conversation drifts from memory-related tasks:
"Memory context is loaded. Ready to work — what's the task?"
The orchestrator's job is to get context loaded fast, then get out of the way.
