@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
• Entity Management: Create and link entities (people, projects, concepts) for knowledge graphs
• Security Hardened: API key masking, input validation, sanitized errors
• MCP Compliant: Works with Claude Desktop, OpenClaw, and any MCP client
• Fully Tested: 102+ test cases covering all functionality

📦 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.net to get your API key (format: mem_prod_xxxxx).

2. Configure Your MCP Client

For OpenClaw

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

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

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

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) |

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 9 tools for memory and entity management:

Memory Management Tools

memory_store

Store a new memory with optional metadata.

Parameters:

• content (string, required) - The memory content to store
• metadata (object, optional) - Key-value metadata to attach

Example:

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

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

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.

Parameters:

• id (string, required) - Memory UUID
• content (string, required) - New content
• metadata (object, optional) - Updated metadata (replaces existing)

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

Entity Management Tools

entity_create

Create a named entity for the knowledge graph.

Parameters:

• name (string, required) - Entity name (1-200 characters)
• type (enum, required) - One of: person, place, organization, project, concept, other
• metadata (object, optional) - Key-value metadata

Example:

{
  "name": "MemoryRelay Project",
  "type": "project",
  "metadata": {
    "status": "active",
    "started": "2026-01"
  }
}

Returns: Entity object with id, name, type, metadata, created_at

entity_link

Link an entity to a memory to establish relationships.

Parameters:

• entity_id (string, required) - Entity UUID
• memory_id (string, required) - Memory UUID
• relationship (string, optional, default: "mentioned_in") - Relationship type

Example:

{
  "entity_id": "650e8400-e29b-41d4-a716-446655440001",
  "memory_id": "550e8400-e29b-41d4-a716-446655440000",
  "relationship": "relates_to"
}

Returns: Success confirmation with link details

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
• Entity names sanitized to prevent XSS attacks
• String lengths enforced (e.g., entity names max 200 characters)

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/Alteriom/ai-memory-service.git
cd ai-memory-service/mcp

# 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/
├── src/
│   ├── index.ts          # Entry point
│   ├── server.ts         # MCP server implementation
│   ├── client.ts         # MemoryRelay API client
│   ├── config.ts         # Configuration loader
│   ├── logger.ts         # Logging utilities
│   └── types.ts          # TypeScript types
├── tests/
│   ├── server.test.ts    # Server tests
│   ├── client.test.ts    # Client tests
│   ├── config.test.ts    # Config tests
│   ├── security.test.ts  # Security tests
│   └── integration.test.ts # Integration tests
├── docs/
│   └── SECURITY.md       # Security documentation
├── package.json
├── tsconfig.json
├── vitest.config.ts
└── 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

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:

• 102+ 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
• MemoryRelay API: api.memoryrelay.net
• Model Context Protocol: modelcontextprotocol.io
• OpenClaw: openclaw.org

🙏 Contributing

Contributions welcome! Please see CONTRIBUTING.md for guidelines.

📝 Changelog

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 Alteriom