MCP Server

The Memory OS MCP Server enables AI assistants like Claude Desktop, Claude Code, and other MCP-compatible clients to store, search, and retrieve memories. Give your AI assistant the ability to remember context across conversations.

What is MCP?

Model Context Protocol (MCP) is an open standard that enables AI assistants to connect with external data sources and tools. By running the Memory OS MCP server, you give AI assistants direct access to your memory store without requiring manual API calls.

Benefits of using MCP:

• Seamless integration - AI assistants can automatically store and retrieve relevant memories
• No code required - Works out of the box with compatible clients
• Persistent memory - Memories persist across conversations and sessions
• Semantic search - AI can find relevant context using natural language

Installation

Claude Desktop

Add the following to your Claude Desktop configuration file:

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

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "memory-os": {
      "command": "npx",
      "args": ["-y", "@memoryos/mcp-server"],
      "env": {
        "MEMORY_OS_API_KEY": "mos_live_xxx"
      }
    }
  }
}

Restart Claude Desktop after updating the configuration.

Claude Code

Add the MCP server to your Claude Code configuration:

claude mcp add memory-os npx @memoryos/mcp-server --env MEMORY_OS_API_KEY=mos_live_xxx

Or add it to your project's .mcp.json file:

{
  "mcpServers": {
    "memory-os": {
      "command": "npx",
      "args": ["-y", "@memoryos/mcp-server"],
      "env": {
        "MEMORY_OS_API_KEY": "mos_live_xxx"
      }
    }
  }
}

Other MCP-Compatible Clients

For any MCP-compatible client, use the following configuration:

Replace mos_live_xxx with your actual API key from the Memory OS dashboard.

Available MCP Tools

The Memory OS MCP server exposes the following tools to AI assistants:

memory_create

Create a new memory.

Parameters:

Example Usage:

When you tell Claude something like "Remember that I prefer TypeScript over JavaScript", Claude will use:

Tool: memory_create
Parameters:
  content: "User prefers TypeScript over JavaScript for development"
  tier: "long"
  content_type: "fact"
  memory_nature: "semantic"
  importance_score: 0.8

Example Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "content": "User prefers TypeScript over JavaScript for development",
  "tier": "long",
  "content_type": "fact",
  "memory_nature": "semantic",
  "importance_score": 0.8,
  "relevance_score": 1.0,
  "created_at": "2025-01-04T10:30:00Z"
}

memory_search

Perform semantic search across memories.

Parameters:

Example Usage:

When Claude needs to find relevant information, it will search:

Tool: memory_search
Parameters:
  query: "What programming languages does the user prefer?"
  threshold: 0.6
  limit: 10

Example Response:

{
  "results": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "content": "User prefers TypeScript over JavaScript for development",
      "tier": "long",
      "similarity": 0.89,
      "combined_score": 0.92,
      "created_at": "2025-01-04T10:30:00Z"
    },
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "content": "User is learning Rust for systems programming",
      "tier": "medium",
      "similarity": 0.78,
      "combined_score": 0.81,
      "created_at": "2025-01-03T14:20:00Z"
    }
  ],
  "search_type": "semantic",
  "threshold": 0.6
}

memory_get_context

Retrieve formatted context optimized for LLM consumption.

Parameters:

Example Usage:

When starting a new conversation, Claude can load relevant context:

Tool: memory_get_context
Parameters:
  query: "User asking about web development best practices"
  max_tokens: 2000

Example Response:

{
  "context": "## User Background\n- Prefers TypeScript over JavaScript\n- Senior developer with 8 years experience\n- Works at TechCorp on e-commerce projects\n\n## Preferences\n- Uses VS Code as primary editor\n- Prefers functional programming patterns\n- Values clean, documented code",
  "memories": [
    {"id": "...", "content": "...", "tier": "long", "score": 0.92},
    {"id": "...", "content": "...", "tier": "long", "score": 0.87}
  ],
  "token_count": 156,
  "retrieval_time_ms": 45
}

memory_list

List recent memories with optional filtering.

Parameters:

Example Usage:

Tool: memory_list
Parameters:
  tier: "long"
  limit: 10

Example Response:

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "content": "User prefers TypeScript over JavaScript",
      "tier": "long",
      "content_type": "fact",
      "created_at": "2025-01-04T10:30:00Z"
    }
  ],
  "meta": {
    "total": 42,
    "limit": 10,
    "offset": 0,
    "has_more": true
  }
}

memory_update

Update an existing memory.

Parameters:

Example Usage:

Tool: memory_update
Parameters:
  id: "550e8400-e29b-41d4-a716-446655440000"
  tier: "long"
  importance_score: 0.95

Example Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "content": "User prefers TypeScript over JavaScript",
  "tier": "long",
  "importance_score": 0.95,
  "updated_at": "2025-01-04T11:00:00Z"
}

memory_delete

Delete a memory permanently.

Parameters:

Example Usage:

Tool: memory_delete
Parameters:
  id: "550e8400-e29b-41d4-a716-446655440000"

Example Response:

{
  "deleted": true
}

Usage Examples

Example Conversation: Storing Preferences

User: Remember that I prefer dark mode in all my applications and I'm allergic to shellfish.

Claude's internal process:

1. Claude recognizes this as information to remember
2. Creates two memories using memory_create:

Tool: memory_create
Parameters:
  content: "User prefers dark mode in all applications"
  tier: "long"
  content_type: "fact"
  memory_nature: "semantic"
  importance_score: 0.7

Tool: memory_create
Parameters:
  content: "User is allergic to shellfish - important health information"
  tier: "long"
  content_type: "fact"
  memory_nature: "semantic"
  importance_score: 1.0
  metadata: {"category": "health", "critical": true}

Claude's response: I've noted both preferences. I'll remember that you prefer dark mode for applications, and I've stored your shellfish allergy as critical health information.

Example Conversation: Retrieving Context

User: Can you help me set up a new React project?

Claude's internal process:

1. Claude searches for relevant context:

Tool: memory_get_context
Parameters:
  query: "User setting up React project, development preferences"
  max_tokens: 1500

2. Gets context including the user's TypeScript preference

Claude's response: Based on your preference for TypeScript, I'll help you set up a React project with TypeScript. Let me walk you through creating a new project with Vite...

Example Conversation: Updating Information

User: Actually, I've switched to preferring Tailwind CSS over styled-components now.

Claude's internal process:

1. Searches for existing styling preference:

Tool: memory_search
Parameters:
  query: "CSS styling preference styled-components"
  limit: 5

2. If found, updates the memory:

Tool: memory_update
Parameters:
  id: "existing-memory-id"
  content: "User prefers Tailwind CSS for styling (previously preferred styled-components)"

Or creates a new memory if none exists:

Tool: memory_create
Parameters:
  content: "User prefers Tailwind CSS for styling"
  tier: "long"
  content_type: "fact"

Troubleshooting

Common Issues

MCP server not appearing in Claude

Symptoms: Claude doesn't have access to memory tools

Solutions:

1. Verify your configuration file is valid JSON
2. Ensure the API key is correctly set
3. Restart Claude Desktop completely
4. Check that Node.js is installed (node --version)

Authentication errors

Symptoms: "AUTHENTICATION_ERROR" when using memory tools

Solutions:

1. Verify your API key is correct and starts with mos_
2. Check the key hasn't expired in your dashboard
3. Ensure the environment variable is properly set

Connection timeouts

Symptoms: Tools take too long or fail to respond

Solutions:

1. Check your internet connection
2. Verify the Memory OS API is accessible
3. Try increasing the timeout in your configuration

Debug Logging

Enable verbose logging to troubleshoot issues:

{
  "mcpServers": {
    "memory-os": {
      "command": "npx",
      "args": ["-y", "@memoryos/mcp-server"],
      "env": {
        "MEMORY_OS_API_KEY": "mos_live_xxx",
        "DEBUG": "memoryos:*"
      }
    }
  }
}

Verifying Connection

To verify the MCP server is working:

1. Ask Claude: "What memory tools do you have available?"
2. Claude should list the memory tools (memory_create, memory_search, etc.)
3. Try: "Remember that this is a test memory"
4. Then: "Search for test memories"

If Claude can create and find the test memory, the connection is working.

Getting Help

If you continue to experience issues:

• Check the Memory OS status page
• Review logs in your terminal if running the server manually
• Contact support at support@mymemoryos.com

Related