@memoryrelay/mcp-server

MCP server for MemoryRelay - Give your AI agents persistent memory across sessions.

🚀 Features

• Persistent Memory: Store and retrieve memories across conversations
• Semantic Search: Find relevant memories using natural language queries
• Batch Operations: Create multiple memories in a single request for optimal performance
• Security Hardened: API key masking, input validation, sanitized errors
• MCP Compliant: Works with Claude Desktop, OpenClaw, and any MCP client
• Fully Tested: 169 test cases covering all functionality

Why MemoryRelay?

| Feature | MemoryRelay | Mem0 | Basic MCP Memory | |---------|------------|------|-----------------| | Semantic Search | Yes | Yes | No | | Work Sessions | Yes | No | No | | Architectural Decisions (ADRs) | Yes | No | No | | Reusable Patterns | Yes | No | No | | Project Orchestration | Yes | No | No | | Knowledge Graph (Entities) | Yes | Limited | No | | Multi-Agent Support | Yes | Yes | No | | V2 Async Storage (60-600x faster) | Yes | No | No | | Tools | 44 | ~10 | 3-5 |

MemoryRelay is purpose-built for engineering teams managing complex, long-running projects — not general-purpose Q&A memory.

Use Cases

• Tech Lead managing 3+ projects — track architectural decisions across repos, build pattern libraries, understand cross-project dependencies
• DevOps Engineer — record infrastructure decisions with rationale, store runbooks as reusable patterns, track deployment configurations
• Solo Developer — build a persistent knowledge base that grows across sessions, link related concepts through entities
• Coding Agent — auto-capture important context, adopt proven patterns, maintain session continuity across conversations

📦 Installation

Using npx (recommended)

No installation needed - run directly:

npx @memoryrelay/mcp-server

Global Installation

npm install -g @memoryrelay/mcp-server

Local Project Installation

npm install @memoryrelay/mcp-server

⚡ Quick Start

1. Get Your API Key

Sign up at memoryrelay.ai to get your API key (format: mem_prod_xxxxx).

2. Configure Your MCP Client

For OpenClaw

See docs/OPENCLAW_GUIDE.md for a comprehensive setup guide.

Edit ~/.openclaw/openclaw.json:

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

For Claude Desktop (macOS)

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

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

For Claude Desktop (Windows)

On Windows, npx with scoped packages can fail to resolve the bin entry. Install globally first, then use node directly.

Step 1: Install the package globally:

npm install -g @memoryrelay/mcp-server

Step 2: Edit %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "MemoryRelay": {
      "command": "node",
      "args": ["%APPDATA%\\npm\\node_modules\\@memoryrelay\\mcp-server\\dist\\index.js"],
      "env": {
        "MEMORYRELAY_API_KEY": "mem_prod_xxxxx"
      }
    }
  }
}

Note: Replace %APPDATA% with your actual path (e.g., C:\\Users\\YourName\\AppData\\Roaming). You can find it by running echo %APPDATA% in Command Prompt.

3. Restart Your Client

Restart OpenClaw or Claude Desktop to load the MCP server.

4. Test It Out

Try asking:

• "Remember that I prefer Python over JavaScript"
• "What programming languages do I like?"
• "Create an entity for the MemoryRelay project"

🔧 Configuration

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | MEMORYRELAY_API_KEY | ✅ Yes | - | Your API key (starts with mem_) | | MEMORYRELAY_API_URL | No | https://api.memoryrelay.net | API base URL (for custom deployments) | | MEMORYRELAY_AGENT_ID | No | Auto-detected | Agent identifier (auto-generated if not set) | | MEMORYRELAY_TIMEOUT | No | 30000 | Request timeout in milliseconds | | MEMORYRELAY_LOG_LEVEL | No | info | Logging level (debug, info, warn, error) | | MEMORYRELAY_TOOLS | No | all | Comma-separated tool groups to enable (see below) | | OPENCLAW_AGENT_NAME | No | - | Agent name when running under OpenClaw (used for agent ID detection) |

Tool Groups

Control which tools are exposed via the MEMORYRELAY_TOOLS environment variable:

| Group | Tools | Description | |-------|-------|-------------| | core | 18 tools | Memory CRUD, entities, agents, health, aliases (forget/recall) | | v2 | 3 tools | Async memory storage, status polling, context building | | sessions | 4 tools | Session lifecycle (start, end, recall, list) | | decisions | 4 tools | Decision recording and checking | | patterns | 4 tools | Pattern library (create, search, adopt, suggest) | | projects | 3 tools | Project registration and listing | | relationships | 6 tools | Project graph (add, deps, dependents, related, impact, shared patterns) | | context | 2 tools | Project context, memory promotion |

Examples:

• MEMORYRELAY_TOOLS=all (default) — all tools enabled
• MEMORYRELAY_TOOLS=core,sessions — only core + session tools
• MEMORYRELAY_TOOLS=core,relationships,context — core + graph tools

Agent ID Detection

The server automatically detects your agent ID from:

1. MEMORYRELAY_AGENT_ID environment variable
2. OPENCLAW_AGENT_NAME environment variable (OpenClaw)
3. Hostname-based generation (if neither is set)

🛠️ Available Tools

The MCP server provides 44 tools organized into groups:

Memory Management Tools

memory_store

Store a new memory with optional metadata.

Note: The agent_id parameter is automatically injected from MEMORYRELAY_AGENT_ID environment variable. You don't need to include it in your request.

Parameters:

• content (string, required) - The memory content to store (1-50,000 characters)
• metadata (object, optional) - Key-value metadata to attach (max 10KB when serialized)

Example:

{
  "content": "User prefers Python for data analysis projects",
  "metadata": {
    "category": "preference",
    "topic": "programming"
  }
}

Returns: Memory object with id, content, agent_id, metadata, created_at, updated_at

Rate Limit: 30 requests per minute

memory_search

Search memories using semantic similarity.

Parameters:

• query (string, required) - Natural language search query
• limit (number, optional, default: 10) - Maximum results (1-50)
• threshold (number, optional, default: 0.5) - Minimum similarity score (0-1)

Example:

{
  "query": "What are the user's programming preferences?",
  "limit": 5,
  "threshold": 0.7
}

Returns: Array of memory objects with similarity scores

memory_list

List recent memories chronologically.

Parameters:

• limit (number, optional, default: 20) - Number of memories to return (1-100)
• offset (number, optional, default: 0) - Pagination offset

Example:

{
  "limit": 10,
  "offset": 0
}

Returns: Object with memories array, total, limit, offset

memory_get

Retrieve a specific memory by ID.

Parameters:

• id (string, required) - Memory UUID

Example:

{
  "id": "550e8400-e29b-41d4-a716-446655440000"
}

Returns: Memory object

memory_update

Update an existing memory's content or metadata.

Note: Metadata updates are merged with existing metadata, not replaced. To remove a key, explicitly set it to null.

Parameters:

• id (string, required) - Memory UUID
• content (string, required) - New content (1-50,000 characters)
• metadata (object, optional) - Updated metadata (merged with existing, max 10KB)

Example:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "content": "Updated: User prefers Python and TypeScript for data analysis",
  "metadata": {
    "category": "preference",
    "updated": "2026-02-12"
  }
}

Returns: Updated memory object

memory_delete

Permanently delete a memory.

Parameters:

• id (string, required) - Memory UUID

Example:

{
  "id": "550e8400-e29b-41d4-a716-446655440000"
}

Returns: Success confirmation

Health Check Tool

memory_health

Check API connectivity and server health.

Parameters: None

Example:

{}

Returns: Health status object with status, version, latency

🔒 Security

This MCP server is designed with security best practices:

API Key Protection

• API keys starting with mem_ are automatically masked in all logs
• Keys are never exposed in error messages or debug output
• Environment variables are the only supported authentication method

Input Validation

• All inputs validated using Zod schemas before processing
• UUIDs validated for format correctness
• String lengths enforced (content max 50,000 characters, metadata max 10KB)
• Memory IDs must be valid UUIDs

Error Handling

• Errors sanitized to prevent information leakage
• No internal paths or stack traces exposed to clients
• All errors logged to stderr (stdout reserved for MCP protocol)

STDIO Safety

• All logging strictly to stderr
• STDIO transport properly isolated per MCP specification

For detailed security information, see SECURITY.md.

🧪 Development

Prerequisites

• Node.js 18+ (22+ recommended)
• npm or yarn

Setup

# Clone the repository
git clone https://github.com/memoryrelay/mcp-server.git
cd mcp-server

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Run all tests (including integration)
npm run test:all

# Generate coverage report
npm run test:coverage

# Type checking
npm run type-check

Available Scripts

• npm run build - Build for production
• npm run dev - Build in watch mode
• npm test - Run unit tests
• npm run test:watch - Run tests in watch mode
• npm run test:integration - Run integration tests (requires API key)
• npm run test:server - Run server-specific tests
• npm run test:security - Run security-focused tests
• npm run test:all - Run all tests
• npm run test:coverage - Generate coverage report
• npm run type-check - Run TypeScript type checking

Project Structure

mcp-server/
├── src/
│   ├── index.ts          # Entry point with CLI routing
│   ├── server.ts         # MCP server implementation (44 tools)
│   ├── client.ts         # MemoryRelay API client
│   ├── config.ts         # Configuration loader + tool groups
│   ├── logger.ts         # Security-hardened logging
│   ├── types.ts          # TypeScript types
│   └── cli/
│       ├── setup.ts      # Interactive setup wizard
│       └── test.ts       # Connection test command
├── tests/
│   ├── server.test.ts    # Server tests
│   ├── client.test.ts    # Client tests
│   ├── config.test.ts    # Config tests
│   ├── security.test.ts  # Security tests
│   ├── entity.test.ts    # Entity tests
│   ├── e2e-protocol.test.ts # MCP protocol e2e tests
│   └── integration.test.ts # Integration tests
├── docs/
│   ├── SECURITY.md       # Security documentation
│   └── OPENCLAW_GUIDE.md # OpenClaw setup guide
├── package.json
├── tsconfig.json
├── tsup.config.ts
├── vitest.config.ts
├── eslint.config.js
├── CHANGELOG.md
├── LICENSE
└── README.md

🐛 Troubleshooting

Server Won't Start

Problem: Failed to start MemoryRelay MCP server

Solutions:

1. Verify your API key is set correctly:

   echo $MEMORYRELAY_API_KEY

2. Check the API key format (should start with mem_)
3. Ensure Node.js version is 18+ (node --version)
4. Try running with debug logging:

   {
     "env": {
       "MEMORYRELAY_LOG_LEVEL": "debug"
     }
   }

Connection Errors

Problem: API request failed or timeout errors

Solutions:

1. Check internet connectivity
2. Verify API URL (if using custom deployment)
3. Increase timeout:

   {
     "env": {
       "MEMORYRELAY_TIMEOUT": "60000"
     }
   }

4. Check firewall/proxy settings

Windows: npx Fails with Scoped Package

Problem: 'memoryrelay-mcp' is not recognized when using npx on Windows

Solutions:

1. Install globally instead of using npx:

   npm install -g @memoryrelay/mcp-server

2. Use node directly in your Claude Desktop config (see Windows setup above)
3. Verify the global install path:

   npm root -g

Tools Not Showing Up

Problem: MCP tools not available in client

Solutions:

1. Restart your MCP client (Claude Desktop, OpenClaw)
2. Check configuration file syntax (valid JSON)
3. Verify the command path is correct
4. Check client logs for MCP server connection errors

Authentication Errors

Problem: 401 Unauthorized errors

Solutions:

1. Verify API key is correct and active
2. Check for extra spaces in environment variable
3. Ensure key hasn't expired
4. Contact support if key should be valid

Validation Errors

Problem: Validation error when calling tools

Solutions:

1. Check parameter types match schema (e.g., limit should be number, not string)
2. Verify required parameters are provided
3. Check UUID format for ID parameters
4. Ensure string lengths are within limits (e.g., entity names max 200 chars)

Debug Mode

Enable debug logging to see detailed information:

{
  "env": {
    "MEMORYRELAY_LOG_LEVEL": "debug"
  }
}

Debug logs go to stderr and include:

• API request/response details (with masked API keys)
• Tool invocation parameters
• Validation errors
• Connection status

Getting Help

• 📖 Full Documentation
• 🐛 Report Issues
• 💬 Discussions
• 🔒 Security Policy

📊 Testing

The project has comprehensive test coverage:

• 169 test cases covering all functionality
• Unit tests for each component
• Integration tests against live API
• Security-focused tests for API key masking and input validation
• Server protocol tests

Run tests:

# All unit tests
npm test

# With coverage
npm run test:coverage

# Integration tests (requires API key)
MEMORYRELAY_API_KEY=mem_prod_xxx npm run test:integration

# Specific test suites
npm run test:server    # Server tests only
npm run test:security  # Security tests only

📄 License

MIT License - see LICENSE for details

🔗 Links

• Documentation: GitHub Repository
• npm Package: @memoryrelay/mcp-server
• Website: memoryrelay.ai
• API: api.memoryrelay.net
• Model Context Protocol: modelcontextprotocol.io
• OpenClaw: openclaw.org

🙏 Contributing

Contributions welcome! Please open an issue or pull request on GitHub.

📝 Changelog

v0.2.0 (2026-03-04)

• 39 tools across 7 configurable tool groups (up from 9)
• Session tools: session_start, session_end, session_recall, session_list — track development sessions with automatic memory linking
• Decision tools: decision_record, decision_list, decision_supersede, decision_check — log architectural decisions with semantic search
• Pattern tools: pattern_create, pattern_search, pattern_adopt, pattern_suggest — share and reuse conventions across projects
• Project tools: project_register, project_list, project_info, project_context — manage project namespaces and load full context
• Relationship tools: project_add_relationship, project_dependencies, project_dependents, project_related, project_impact, project_shared_patterns — map project dependencies and analyze impact
• Context tools: memory_promote — manage memory importance tiers (hot/warm/cold)
• Tool group configuration: MEMORYRELAY_TOOLS env var to selectively enable tool groups
• Session-aware descriptions: Tool descriptions dynamically show active session context
• Server instructions: Recommended workflow guidance via MCP protocol instructions field
• 169 test cases with full coverage

v0.1.0 (2026-02-12)

• Initial release
• 9 MCP tools for memory and entity management
• Semantic search with configurable thresholds
• Entity linking for knowledge graphs
• Security hardened with API key masking and input validation
• 102 test cases with full coverage
• Support for OpenClaw and Claude Desktop

Made with ❤️ by the MemoryRelay Team