Skip to main content
Glama
MemoryOS MCP Server

MemoryOS MCP Server

Official
by memengine

MemoryOS MCP Server

Run MemoryOS as a Model Context Protocol server for agent runtimes, IDEs, and local AI tools.

The MCP server is a sidecar around the MemoryOS API. It does not choose the memory schema itself. Your workspace setting still decides whether add and get use the General Engine, EdTech Schema, Customer Support Schema, or a future domain schema.

Install

From this repository:

cd memoryos-mcp
pip install -e .

When published:

pip install memoryo-mcp

Related MCP server: FusionPact MCP Server

Configure

export MEMORYOS_API_KEY=mem_live_xxx
export MEMORYOS_API_URL=https://api.memoryo.dev

For local Docker:

export MEMORYOS_API_URL=http://localhost:8000

For cross-agent universal memory tools, also set:

export MEMORYOS_AGENT_API_KEY=mem_agent_xxx
export MEMORYOS_UUI_TOKEN=uui_xxx

Run

memoryo-mcp

HTTP transport for private sidecars

The default remains stdio. For a private sidecar or internal service, enable streamable HTTP explicitly:

export MEMORYOS_MCP_TRANSPORT=streamable-http
export MEMORYOS_MCP_HOST=127.0.0.1
export MEMORYOS_MCP_PORT=8080
export MEMORYOS_MCP_HTTP_PATH=/mcp
memoryo-mcp

The MCP endpoint is http://127.0.0.1:8080/mcp; process health is available at http://127.0.0.1:8080/healthz.

HTTP mode carries the configured MemoryOS API key on behalf of the MCP caller. Keep it private: bind it to loopback as a sidecar, or place it on an authenticated internal network. Do not expose it through a public ingress.

Public MCP with Clerk OAuth

For a public MCP URL, set MEMORYOS_MCP_EXPOSURE=public. The server will refuse to start unless Clerk OAuth is configured; anonymous public mode is deliberately unsupported.

Create a dedicated Clerk OAuth application for MCP, register the FastMCP callback https://<your-mcp-domain>/auth/callback, and store its secrets outside source control. Configure:

export MEMORYOS_MCP_TRANSPORT=streamable-http
export MEMORYOS_MCP_EXPOSURE=public
export MEMORYOS_MCP_PUBLIC_BASE_URL=https://mcp.example.com
export MEMORYOS_MCP_AUTH_MODE=clerk
export MEMORYOS_MCP_CLERK_DOMAIN=clerk.memoryo.dev
export MEMORYOS_MCP_CLERK_CLIENT_ID=...
export MEMORYOS_MCP_CLERK_CLIENT_SECRET=...
export MEMORYOS_MCP_AUTH_SIGNING_KEY=...
export MEMORYOS_MCP_ALLOWED_CLIENT_REDIRECT_URIS=https://<approved-client-callback>

MEMORYOS_MCP_AUTH_SIGNING_KEY must be a new random secret, not a MemoryOS API key, Razorpay key, or Clerk secret. In public mode, do not set MEMORYOS_API_KEY, MEMORYOS_AGENT_API_KEY, or MEMORYOS_UUI_TOKEN; startup will reject them. The caller's verified Clerk access token is forwarded to the MemoryOS API, which independently validates it and resolves the tenant only from the active org_id claim. Configure the Clerk access-token template used by this OAuth application to include org_id, email, and boolean email_verified.

The public tenant surface is memory read/add/retrieve, memory detail/history/job reads, and billing-plan/subscription reads. Raw requests, configuration/admin, destructive actions, and global-agent registration remain private.

Optional public Universal Memory

Universal tools are disabled by default. To enable them, register exactly one dedicated Global Agent for the MCP service and store the returned agent key only in the MCP host secret store. Do not use a tenant API key or a caller-provided UUI token:

export MEMORYOS_MCP_UNIVERSAL_ENABLED=true
export MEMORYOS_MCP_UNIVERSAL_AGENT_API_KEY=mem_agent_server_only

For each Universal request, the server exchanges the verified Clerk caller for a five-minute capability. The API reloads that caller's Universal profile, the MCP Global Agent, and its live consent grant before every operation. Revoking consent therefore blocks further calls immediately, even before the capability expires. The token template must contain verified email, and the user must already have a Universal profile and active consent grant for this MCP Global Agent.

Example Claude Desktop config:

{
  "mcpServers": {
    "memoryos": {
      "command": "memoryo-mcp",
      "env": {
        "MEMORYOS_API_KEY": "mem_live_xxx",
        "MEMORYOS_API_URL": "https://api.memoryo.dev"
      }
    }
  }
}

Tools

Core tenant memory:

  • memoryos_add_memory

  • memoryos_get_context

  • memoryos_list_memories

  • memoryos_get_memory

  • memoryos_update_memory

  • memoryos_delete_memory

  • memoryos_get_memory_history

  • memoryos_get_job_status

  • memoryos_export_user

  • memoryos_get_user_stats

  • memoryos_block_user

Domain and workspace tools:

  • memoryos_get_domain_schema

  • memoryos_set_domain_schema

  • memoryos_get_edtech_profile

  • memoryos_set_support_type

  • memoryos_list_support_customers

  • memoryos_get_support_stats

Cross-agent tools:

  • memoryos_register_global_agent

  • memoryos_get_global_agent

  • memoryos_create_consent_url

  • memoryos_universal_add_memory

  • memoryos_universal_get_context

  • memoryos_universal_get_job_status

Other:

  • memoryos_list_billing_plans

  • memoryos_get_billing_subscription

  • memoryos_api_request

memoryos_api_request is an allowlisted escape hatch for new MemoryOS API endpoints that are not yet first-class MCP tools. It only allows /v1/memories, /v1/users, /v1/tenant, /v1/agents, /v1/billing/plans, and /v1/universal.

Billing checkout creation and payment-signature verification are intentionally not MCP tools. They are browser/payment flows and must remain in the tenant dashboard with server-side verification.

Production Notes

MCP is best when a company wants MemoryOS outside their main application process. They can run it as a sidecar and let their agent runtime call MemoryOS as tools.

For customer support and other live business workflows, MemoryOS MCP supplies memory context. The customer's own tools still provide live truth and actions such as get_order, create_refund, get_invoice, or update_ticket.

Available Tools

26 tools
memoryos_add_memoryA

Queue tenant-scoped conversation messages for MemoryOS extraction. Uses the workspace's configured general or domain schema.

Inputs: messages (required), external_user_id (required), agent_id, metadata, +1 more.

memoryos_api_requestC

Advanced allowlisted MemoryOS API request for endpoints not yet promoted to first-class MCP tools.

Inputs: path (required), method (required), json, params, +3 more.

memoryos_block_userB

Block a tenant-scoped user from future memory operations.

Inputs: external_user_id (required).

memoryos_delete_memoryB

Archive or hard-delete a memory.

Inputs: memory_id (required), hard_delete.

memoryos_export_userB

Export a tenant user's memories and version history for access requests.

Inputs: external_user_id (required).

memoryos_get_billing_subscriptionA

Fetch the authenticated tenant's read-only subscription and plan limits.

This tool never creates a checkout, verifies a payment, or changes billing.

Inputs: no named parameters.

memoryos_get_contextC

Retrieve prompt-ready memory context for a tenant-scoped user. Domain schema context is included by the MemoryOS backend when enabled.

Inputs: query (required), external_user_id (required), as_of, limit, +5 more.

memoryos_get_domain_schemaA

Read the workspace domain schema setting.

Inputs: no named parameters.

memoryos_get_edtech_profileA

Fetch the structured EdTech profile for a user when the EdTech schema is enabled.

Inputs: external_user_id (required).

memoryos_get_global_agentB

Fetch a public global agent profile.

Inputs: agent_id (required).

memoryos_get_job_statusC

Fetch extraction job status.

Inputs: job_id (required).

memoryos_get_memoryA

Fetch one memory by id.

Inputs: memory_id (required).

memoryos_get_memory_historyA

Fetch append-only version history for a memory.

Inputs: memory_id (required).

memoryos_get_support_statsB

Fetch Customer Support schema aggregate stats.

Inputs: no named parameters.

memoryos_get_user_statsA

Fetch tenant-scoped memory stats for one external user.

Inputs: external_user_id (required).

memoryos_list_billing_plansB

Fetch public MemoryOS billing plans.

Inputs: no named parameters.

memoryos_list_memoriesC

List tenant-scoped memories for a user.

Inputs: external_user_id (required), limit, cursor, agent_id, +1 more.

memoryos_list_support_customersC

List Customer Support schema customer summaries.

Inputs: limit, cursor.

memoryos_register_global_agentB

Register a global cross-agent MemoryOS agent and receive its agent API key once.

Inputs: name (required), redirect_uri (required), logo_url, description, +2 more.

memoryos_set_domain_schemaA

Set the workspace domain schema. Use null for General Engine, 'edtech' for EdTech, or 'support' for Customer Support.

Inputs: domain_schema (required).

memoryos_set_support_typeC

Configure Customer Support routing mode and allowed support types.

Inputs: support_type_mode (required), support_type, support_types_allowed.

memoryos_universal_add_memoryC

Queue cross-agent universal memory extraction.

Inputs: messages (required), metadata, uui_token, agent_api_key, +1 more.

memoryos_universal_get_contextC

Retrieve cross-agent universal memory context.

Inputs: query (required), limit, format, uui_token, +2 more.

memoryos_universal_get_job_statusC

Fetch universal memory extraction job status.

Inputs: job_id (required), uui_token, agent_api_key.

memoryos_update_memoryC

Update memory content, importance, or archived state.

Inputs: memory_id (required), content, is_archived, importance_score.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.9/5.0

    Scored across 26 tools

    Disambiguation4/5

    Most tools target distinct resource-action pairs, and the tenant-scoped vs universal variants are marked in names and descriptions. A few pairs like memoryos_get_job_status vs memoryos_universal_get_job_status and memoryos_get_context vs memoryos_universal_get_context require careful reading, but overall selection should be unambiguous.

    Naming Consistency4/5

    The memoryos_ prefix plus snake_case verb_noun naming is highly consistent across list/get/update/delete/set/register/create tools. The main deviations are memoryos_universal_* placing the scope modifier before the verb and memoryos_api_request being a noun-only exception.

    Tool Count2/5

    At 26 tools the surface is above the 25-tool threshold and feels too heavy for a memory-focused MCP server, especially with support, billing, global-agent, and universal features bundled in. The tools are individually justified, but the set would benefit from consolidation or splitting into focused servers.

    Completeness4/5

    The core memory lifecycle is well covered: add, list, get, update, delete, history, context, job status, plus user export/stats/block. Minor gaps exist in universal/global-agent operations, such as no update/delete/list for universal or global agents, but the catch-all api_request and read-only coverage make these workable.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Governed shared memory platform for AI agents and agent fleets. Provides persistent memory, cross-agent knowledge sharing, permissions, audit trails, and multi-tenant isolation through a Model Context Protocol (MCP) server.
      4 npm
      559
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables secure enterprise AI agents to access internal tools like GitHub, Gmail, Calendar, file systems, databases, and knowledge bases through the Model Context Protocol, with built-in security, audit, and observability.
      MIT