MemoryOS MCP Server
OfficialClick on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@MemoryOS MCP Server add memory: user prefers visual learning"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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-mcpRelated MCP server: FusionPact MCP Server
Configure
export MEMORYOS_API_KEY=mem_live_xxx
export MEMORYOS_API_URL=https://api.memoryo.devFor local Docker:
export MEMORYOS_API_URL=http://localhost:8000For cross-agent universal memory tools, also set:
export MEMORYOS_AGENT_API_KEY=mem_agent_xxx
export MEMORYOS_UUI_TOKEN=uui_xxxRun
memoryo-mcpHTTP 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-mcpThe 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_onlyFor 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_memorymemoryos_get_contextmemoryos_list_memoriesmemoryos_get_memorymemoryos_update_memorymemoryos_delete_memorymemoryos_get_memory_historymemoryos_get_job_statusmemoryos_export_usermemoryos_get_user_statsmemoryos_block_user
Domain and workspace tools:
memoryos_get_domain_schemamemoryos_set_domain_schemamemoryos_get_edtech_profilememoryos_set_support_typememoryos_list_support_customersmemoryos_get_support_stats
Cross-agent tools:
memoryos_register_global_agentmemoryos_get_global_agentmemoryos_create_consent_urlmemoryos_universal_add_memorymemoryos_universal_get_contextmemoryos_universal_get_job_status
Other:
memoryos_list_billing_plansmemoryos_get_billing_subscriptionmemoryos_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 toolsmemoryos_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_create_consent_urlB
Create a MemoryOS consent URL for cross-agent memory sharing.
Inputs: agent_id (required), redirect_uri (required), state, consent_base_url. Returns: object
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
Scored across 26 tools
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.
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.
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.
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
Persistent memory, knowledge graph, task management and more for AI agents via MCP.
Cross-tool persistent memory and context for AI assistants over MCP.
Your memory, everywhere AI goes. Build knowledge once, access it via MCP anywhere.
Shared memory for your AI tools: tasks, notes and context every tool can read and write over MCP.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceGoverned 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 npm559Apache 2.0
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to access hybrid vector, reasoning-based tree retrieval, and agent memory through the Model Context Protocol (MCP), supporting Claude Desktop and other MCP-compatible clients.76 npmApache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables 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
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to access file systems, fetch web content, query databases, and execute shell commands through the standardized Model Context Protocol.MIT