MCP Server

The official Model Context Protocol server for MemoryRelay. Connects Claude Desktop, OpenClaw, and other MCP-compatible clients directly to your MemoryRelay instance.

Package: @memoryrelay/mcp-server

Installation

# Global install
npm install -g @memoryrelay/mcp-server

# Or run directly with npx (no install needed)
npx @memoryrelay/mcp-server

Claude Desktop Configuration

Add the following to your Claude Desktop MCP configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "memoryrelay": {
      "command": "npx",
      "args": ["-y", "@memoryrelay/mcp-server"],
      "env": {
        "MEMORYRELAY_API_KEY": "mem_your_api_key"
      }
    }
  }
}

tip

If you installed the package globally, you can use "command": "memoryrelay-mcp" instead of npx.

Self-Hosted Instances

Point the server at your own deployment by adding MEMORYRELAY_API_URL:

{
  "mcpServers": {
    "memoryrelay": {
      "command": "npx",
      "args": ["-y", "@memoryrelay/mcp-server"],
      "env": {
        "MEMORYRELAY_API_KEY": "mem_your_api_key",
        "MEMORYRELAY_API_URL": "https://memory.your-domain.com"
      }
    }
  }
}

Tool Groups

The MCP server organizes its 73 tools into groups. By default, all groups are enabled. Configure which groups are active using the MEMORYRELAY_TOOLS environment variable.

{
  "env": {
    "MEMORYRELAY_API_KEY": "mem_your_api_key",
    "MEMORYRELAY_TOOLS": "core,sessions,decisions"
  }
}

info

Enable only the tool groups your workflow needs. Fewer tools means less context for the LLM to parse, which improves tool selection accuracy and reduces token usage. Set MEMORYRELAY_TOOLS=all (or omit it) to enable everything.

core (31 tools)

Core memory, entity, and agent operations.

Tool	Description
memory_store	Store a new memory with content and optional metadata
memory_search	Semantic search across stored memories
memory_list	List memories with pagination
memory_get	Retrieve a specific memory by ID
memory_update	Update memory content or metadata
memory_delete	Soft-delete a memory
memory_batch_store	Store multiple memories in a single call
memory_context	Build a formatted context string from relevant memories
memory_health	Check the health of the MemoryRelay service
memory_status	Get the processing status of a memory
memory_extraction_status	Get entity extraction status for a memory
memory_extract_entities	Trigger entity re-extraction for a memory
memory_feedback	Submit relevance feedback on a memory
memory_bulk_delete	Bulk delete memories by IDs
memory_consolidate	Find and merge near-duplicate memories
memory_restore_merge	Restore a previously merged memory
entity_create	Create a new entity (person, org, technology, concept)
entity_link	Link an entity to a memory with a relationship label
entity_list	List entities with optional type filtering
entity_update	Update entity name or metadata
entity_delete	Delete an entity
entity_graph	Explore the knowledge graph around an entity
entity_merge	Merge two entities
entity_create_relationship	Create a relationship between entities
entity_delete_relationship	Delete a relationship between entities
entity_list_relationships	List all entity relationships
agent_list	List all agents
agent_create	Create a new agent
agent_get	Get agent details
agent_update	Update agent name or description
agent_delete	Delete an agent and its data

sessions (7 tools)

Session tracking for bounded interaction periods.

Tool	Description
session_start	Start a new session
session_end	End an active session
session_recall	Recall memories from a specific session
session_list	List sessions
session_get_or_create	Get or create a session by external ID
session_summarize	Auto-summarize a session's memories
session_delete	Delete a session

decisions (7 tools)

Architectural and design decision tracking.

Tool	Description
decision_record	Record a new decision
decision_list	List decisions with optional status filter
decision_supersede	Supersede an existing decision with a new one
decision_check	Check for existing decisions about a topic
decision_get	Get decision details
decision_update	Update a decision
decision_delete	Delete a decision

patterns (9 tools)

Reusable pattern discovery and sharing.

Tool	Description
pattern_create	Create a new reusable pattern
pattern_search	Search patterns by meaning
pattern_adopt	Adopt a pattern for a project
pattern_suggest	Get pattern suggestions based on project context
pattern_get	Get pattern details
pattern_list	List patterns
pattern_update	Update a pattern
pattern_delete	Delete a pattern
pattern_unadopt	Remove pattern adoption from a project

projects (5 tools)

Project registration and management.

Tool	Description
project_register	Register a new project
project_list	List all projects
project_info	Get detailed project information
project_update	Update project details
project_delete	Delete a project

relationships (6 tools)

Project dependency and relationship management.

Tool	Description
project_add_relationship	Register a relationship between two projects
project_dependencies	What does this project depend on?
project_dependents	What depends on this project?
project_related	All related projects with relationship types
project_impact	Analyze impact of changes across linked projects
project_shared_patterns	Patterns adopted by both projects

context (3 tools)

Context building and memory promotion.

Tool	Description
project_context	Get full project context (memories, decisions, patterns)
memory_promote	Update a memory's importance and tier
context_build_v2	Build context using v2 API with advanced ranking

Configuration Reference

Variable	Required	Default	Description
MEMORYRELAY_API_KEY	Yes	--	Your MemoryRelay API key
MEMORYRELAY_API_URL	No	https://api.memoryrelay.net	API base URL
MEMORYRELAY_TOOLS	No	all	Comma-separated list of tool groups to enable (core, sessions, decisions, patterns, projects, relationships, context)
MEMORYRELAY_AGENT_ID	No	auto-detected	Agent identifier
MEMORYRELAY_TIMEOUT	No	30000	Request timeout in milliseconds
MEMORYRELAY_LOG_LEVEL	No	info	Log level (debug, info, warn, error)

Security

The MCP server includes several security measures:

• API key masking -- Keys starting with mem_ are masked in all log output. Only the first 8 characters are shown.
• Input validation -- All tool inputs are validated against Zod schemas before being sent to the API. Malformed requests are rejected client-side.
• Sanitized errors -- Error messages returned to the LLM are sanitized to prevent leaking internal details like stack traces or database errors.
• Stdio safety -- All logging is directed to stderr. Only valid MCP protocol messages are written to stdout, preventing log contamination of the protocol stream.

warning

The API key is passed via environment variables in the MCP configuration. Ensure your configuration file has appropriate file permissions (readable only by your user account).

Troubleshooting

Tools not appearing in Claude Desktop

1. Verify the MCP configuration JSON is valid (no trailing commas).
2. Restart Claude Desktop after editing the configuration.
3. Check stderr output for initialization errors.

Authentication errors

1. Confirm your API key starts with mem_ and has not expired.
2. Verify the key has the required scopes (read, write) for the tools you are using.

Connection timeouts with self-hosted instances

1. Ensure MEMORYRELAY_API_URL does not include a trailing slash.
2. Verify the API is reachable: curl $MEMORYRELAY_API_URL/v1/health.