MCP Server

The primary way to use memories.sh is the CLI — memories generate writes native config files that each tool reads natively. For browser-based agents (v0, bolt.new, Lovable) or any MCP client where the CLI can't run, the built-in MCP server provides real-time access.

When to Use the MCP Server

Use memories generate first. The MCP server is useful when:

• Browser-based agents — v0, bolt.new, Lovable, and other tools where the CLI can't run
• Agents need to add new memories during a conversation
• You want live search without regenerating files
• You want both — generated files for rules, MCP for real-time context

Cloud MCP (Recommended)

For signed-up users, the easiest way to connect is via our hosted MCP endpoint. This works with any tool that supports HTTP-based MCP.

1. Generate an API Key

Get your API key from the API Keys dashboard page or run:

memories login

2. Configure Your Tool

See the MCP Integration Guide for tool-specific setup instructions, including:

• Cursor — One-click install or manual config
• Claude Code — CLI command
• Claude Desktop — Config file
• Windsurf — Config file
• VS Code — Config file
• v0 / Web Tools — Paste endpoint URL

Local MCP (Self-Hosted)

For local-only use or self-hosted setups, run the MCP server locally via stdio:

memories serve

Configure your tool to spawn the local server:

{
  "mcpServers": {
    "memories": {
      "command": "npx",
      "args": ["-y", "@memories.sh/cli", "serve"]
    }
  }
}

The local server communicates over stdio and logs diagnostic information to stderr.

Available Tools and Resources

The MCP server exposes:

• 9 hosted core tools on https://memories.sh/api/mcp for reading, writing, searching, and managing memories
• 5 additional local lifecycle tools (start_session, checkpoint_session, end_session, snapshot_session, consolidate_memories) when running memories serve
• 6 local reminder tools (add_reminder, list_reminders, run_due_reminders, enable_reminder, disable_reminder, delete_reminder) when running memories serve
• 4 local streaming tools (start_memory_stream, append_memory_chunk, finalize_memory_stream, cancel_memory_stream) when running memories serve
• 3 resources — for accessing rules, recent memories, and project-specific data

See the Tools Reference, Resources Reference, and Tenant Routing for complete documentation.

Lifecycle-Aware MCP Pattern

For long sessions, treat MCP reads/writes as a lifecycle sequence instead of one-off calls:

1. start_session (local CLI MCP) to open a tracked session.
2. get_context with session_id + compaction hints (budget_tokens, turn_count, turn_budget, inactivity fields).
3. If compaction is signaled, call checkpoint_session before boundary operations.
4. On reset/handoff boundaries, persist a raw transcript slice via snapshot_session.
5. end_session when the task closes.

The hosted MCP endpoint focuses on tenant-routed core memory tools. Local lifecycle tools are exposed when running memories serve.