claude-mem-orchestrator

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:

# Start it (uses bun runtime)
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

# Check logs
cat ~/.claude-mem/logs/claude-mem-$(date +%Y-%m-%d).log | tail -20

# Check if port is in use
netstat -ano | grep 37777    # Windows
lsof -i :37777               # macOS/Linux

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.