devsh-memory-mcp

devsh-memory-mcp

MCP server for devsh/cmux agent memory - enables Claude Desktop, Cursor, and other MCP clients to access sandbox agent memory and orchestrate multi-agent workflows.

Installation

npm install -g devsh-memory-mcp
# or
npx devsh-memory-mcp

Usage

CLI

# Use default memory directory (/root/lifecycle/memory)
devsh-memory-mcp

# Specify custom directory
devsh-memory-mcp --dir /path/to/memory

# Set agent name for messaging
devsh-memory-mcp --agent my-agent

Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "devsh-memory": {
      "command": "npx",
      "args": ["devsh-memory-mcp"]
    }
  }
}

With custom options:

{
  "mcpServers": {
    "devsh-memory": {
      "command": "npx",
      "args": ["devsh-memory-mcp", "--dir", "/path/to/memory", "--agent", "claude-desktop"]
    }
  }
}

Available Tools

Read Tools

Tool	Description
read_memory	Read knowledge, tasks, or mailbox memory
list_daily_logs	List available daily log dates
read_daily_log	Read a specific daily log
search_memory	Search across all memory files

Messaging Tools

Tool	Description
send_message	Send a message to another agent (or "*" for broadcast)
get_my_messages	Get messages addressed to this agent
mark_read	Mark a message as read

Write Tools

Tool	Description
append_daily_log	Append content to today's daily log
update_knowledge	Add an entry to a priority section (P0/P1/P2)
add_task	Add a new task to TASKS.json
update_task	Update the status of a task

Orchestration Tools (Head Agent)

Tool	Description
spawn_agent	Spawn a sub-agent to work on a task
get_agent_status	Get status of a spawned agent
list_spawned_agents	List all agents in current orchestration
wait_for_agent	Wait for agent to complete (polling)
wait_for_events	Wait for events via SSE (event-driven, recommended)
cancel_agent	Cancel a running/pending agent
get_orchestration_summary	Get dashboard-style orchestration summary
pull_orchestration_updates	Sync local PLAN.json with server (read)
push_orchestration_updates	Push task status/completion to server (write)
read_orchestration	Read PLAN.json, AGENTS.json, or EVENTS.jsonl
append_event	Append an orchestration event to EVENTS.jsonl
update_plan_task	Update task status in PLAN.json

Provider Session Tools

Tool	Description
bind_provider_session	Bind a Claude session ID or Codex thread ID to task
get_provider_session	Get provider session binding for task resume

Orchestration Learning Tools

Tool	Description
log_learning	Log an orchestration learning, error, or feature request to the server
get_active_orchestration_rules	Fetch active orchestration rules for the team

log_learning types:

• learning - Discovered a better orchestration pattern
• error - Found an error pattern to avoid
• feature_request - Missing capability that would help

Logged items are reviewed by team leads and may be promoted to active orchestration rules.

Environment Variables (Orchestration)

Variable	Description
CMUX_TASK_RUN_JWT	JWT for authenticating orchestration API calls
CMUX_ORCHESTRATION_ID	Current orchestration session ID
CMUX_API_BASE_URL	API base URL (default: https://cmux-www.karldigi.dev)

Memory Directory Structure

/root/lifecycle/memory/
├── knowledge/
│   └── MEMORY.md              # Long-term insights (P0/P1/P2 sections)
├── daily/
│   └── {date}.md              # Daily session logs
├── orchestration/
│   ├── PLAN.json              # Orchestration task plan
│   ├── AGENTS.json            # Agent registry
│   └── EVENTS.jsonl           # Orchestration event log
├── behavior/
│   ├── HOT.md                 # Active workflow preferences
│   ├── corrections.jsonl      # User corrections log
│   ├── LEARNINGS.jsonl        # Orchestration learnings
│   ├── ERRORS.jsonl           # Error patterns
│   ├── FEATURE_REQUESTS.jsonl # Feature requests
│   └── skill-candidates.json  # Repeated patterns
├── TASKS.json                 # Task registry
└── MAILBOX.json               # Inter-agent messages

Priority Tiers (MEMORY.md)

• P0 - Core: Never expires. Project fundamentals, invariants.
• P1 - Active: 90-day TTL. Ongoing work, current strategies.
• P2 - Reference: 30-day TTL. Temporary findings, debug notes.

Format: - [YYYY-MM-DD] Your insight here

Development

Running Tests

cd packages/devsh-memory-mcp
bun test

Test Coverage

The package includes 81 unit tests covering:

• JWT Helper (5 tests): Token extraction, edge cases, UUID handling
• Orchestration Tools (24 tests): spawn_agent, get_agent_status, wait_for_agent schemas and URL construction
• Memory Tools (27 tests): Task/message structures, file paths, agent name validation
• Learning Tools (30 tests): log_learning, get_active_orchestration_rules, error handling

All tests run without external dependencies, suitable for CI environments