Skip to main content
The Ryumem MCP (Model Context Protocol) server enables AI coding assistants to have persistent, intelligent memory across sessions.
MCP is an open protocol that standardizes how AI applications connect to external tools and data sources. Learn more about MCP.

​
Supported Clients

Claude Code

Anthropic’s CLI coding assistant

Cursor

AI-powered code editor

Claude Desktop

Claude desktop application

​
Quick Start

​
Option 1: Self-Hosted (Open Source)

If you’re running your own Ryumem server:
1

Start Your Ryumem Server

Make sure your Ryumem server is running (see Setup Guide):
docker-compose up -d
# Server at http://localhost:8000
2

Install MCP Server

npx @predictable/ryumem-mcp-server install \
  --api-key ryu_your_api_key_here \
  --api-url http://localhost:8000
3

Restart Your Client

Restart Claude Code, Cursor, or Claude Desktop to load the new configuration.

​
Option 2: Ryumem Cloud

For hosted Ryumem service with GitHub authentication: 
# Claude Code (default)
npx @predictable/ryumem-mcp-server install --oauth

# Cursor
npx @predictable/ryumem-mcp-server install --oauth --client cursor

# Claude Desktop
npx @predictable/ryumem-mcp-server install --oauth --client claude-desktop
This authenticates via GitHub OAuth and automatically configures your client.

​
Manual Configuration

If you prefer manual setup, add to your configuration file: Configuration file locations:
  • Claude Code: ~/.claude.json
  • Cursor: ~/.cursor/mcp.json
  • Claude Desktop (macOS): ~/Library/Application Support/Claude/claude_desktop_config.json
  • Claude Desktop (Windows): %APPDATA%\Claude\claude_desktop_config.json
  • Claude Desktop (Linux): ~/.config/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "ryumem": {
      "command": "npx",
      "args": ["@predictable/ryumem-mcp-server"],
      "env": {
        "RYUMEM_API_URL": "http://localhost:8000",
        "RYUMEM_API_KEY": "ryu_your_api_key_here"
      }
    }
  }
}

​
CLI Options

npx @predictable/ryumem-mcp-server install [options]
OptionDescription
--oauthAuthenticate via GitHub OAuth (for hosted service)
--api-key <key>Use a specific API key
--api-url <url>Custom API URL (default: https://api.ryumem.io)
--client <name>Target client: claude-code (default), cursor, or claude-desktop

​
Uninstall

npx @predictable/ryumem-mcp-server uninstall

​
Available Tools

The MCP server provides the following tools to AI agents:
ToolDescription
search_memoryMulti-strategy semantic search across the knowledge graph
add_episodeSave new episodic memory
get_entity_contextRetrieve entity details and relationships
list_episodesPaginated episode listing with filters
get_episodeRetrieve specific episode by UUID
update_episode_metadataUpdate metadata on existing episode
prune_memoriesClean up old or redundant memories

​
Cursor Configuration

Cursor’s MCP implementation doesn’t automatically load server instructions. To enable Ryumem’s memory-first behavior, add the following to your project’s .cursorrules file: 
Always search and follow Ryumem's memory-first instructions.
Alternative: You can also add these instructions to Cursor’s global “Rules for AI” in Settings > General > Rules for AI.

​
How It Works

Once configured, your AI coding assistant will:
  1. Search memory before starting tasks to retrieve relevant context
  2. Store important information like code patterns, decisions, and preferences
  3. Build a knowledge graph of entities and relationships in your codebase
  4. Learn from past sessions to provide more contextual assistance
The MCP server includes instructions that guide the AI to use memory proactively. You don’t need to explicitly ask it to remember things.

​
Example Workflow

After setting up the MCP server, your AI assistant will automatically:
  1. At conversation start: Search for project context, preferences, and recent decisions
  2. When reading files: Check if summaries exist before reading full content
  3. When making decisions: Store architectural decisions and trade-offs
  4. When learning preferences: Remember your coding style and tool preferences

​
Troubleshooting

  1. Verify the configuration file path is correct for your client
  2. Check that npx @predictable/ryumem-mcp-server runs without errors
  3. Restart your AI client after configuration changes
  1. Verify your API key is correct (should start with ryu_)
  2. For self-hosted, ensure the API URL is accessible
  3. Check server logs for authentication errors
  1. Verify your Ryumem server is running and accessible
  2. Check the user_id being used (usually derived from project name)
  3. Use the dashboard to verify episodes are being stored

​
Next Steps

Setup Guide

Deploy your own Ryumem server

Dashboard Guide

View and manage your memories

Core Concepts

Understand how memory works

Google ADK Integration

Add memory to custom agents