MCP Server

MemoryRouter runs a remote Model Context Protocol server that gives any MCP-capable client durable, portable memory. One vault, many AI apps.

https://mcp.memoryrouter.ai/mcp

This is the address you paste into ChatGPT, Claude, Claude Cowork, Codex, or any other MCP client. Authentication is OAuth 2.1 with PKCE, you never paste an API key into a connector.

Prerequisites and first connection

Create a MemoryRouter account and choose a vault you are allowed to use. Your client must support remote Streamable HTTP MCP and OAuth. A local-only stdio client needs a compatible bridge; adding this HTTPS URL as an executable will not work.

Add https://mcp.memoryrouter.ai/mcp as a remote server, complete browser authorization, and select the intended vault. Follow the exact host UI in ChatGPT, Claude, or Cowork. OAuth setup does not require a model-provider API key.

Cross-session proof

1. In a connected conversation ask: "Store this synthetic test fact in MemoryRouter: the demo project's release phrase is ORCHID-7419."
2. Approve the write and inspect the successful store_memory result.
3. Open a new conversation with MemoryRouter enabled, without copying the old chat.
4. Ask: "Search MemoryRouter for the demo project's release phrase." Check that the result contains ORCHID-7419.

This is a test you run, not a guarantee that a model will call tools unprompted. Recall is relevance-ranked, not the full vault on every request. Read-only connections cannot perform step 1. Use a writable connection to seed the same vault first.

Protocol support

The server implements the 2026-07-28 revision, which is stateless: every request describes itself, and there is no session handshake to lose. Concretely:

• server/discover reports supported versions, capabilities, and cache hints.
• Each modern request carries _meta protocol version and client capabilities, mirrored by MCP-Protocol-Version, Mcp-Method, and Mcp-Name headers.
• Every successful result carries a resultType discriminator and per-response server info.
• Tool and resource catalogs are deterministic and cacheable.

Older handshake-era clients still work: they send initialize, and the server negotiates a legacy version without ever claiming a modern one. No client is dropped.

Why stateless matters for memory

Session-based MCP couples your memory to a live connection. If the connection drops or the client restarts, the session is gone. MemoryRouter's durability lives in the vault, not in a session, so a stateless protocol is the right fit. Any request, from any client, at any time, reaches the same memories.

Tools

The server exposes exactly ten tools. If a client shows you something else, it is not coming from MemoryRouter.

Two MCP resources are also available when the host exposes resources: memory://vault/stats and memory://vault/recent.

Tool reference: inputs, outputs, and permission classes

Each tool does one thing. No tool combines a read with a write, and no tool sends, shares, publishes, or charges anything. The class column uses the Read, Write, and Sensitive write model that agent hosts such as Muse apply to connector tools.

Every tool acts only on the vault the user selected during OAuth sign-in.

Smaller scope. Scopes are independent. A connection granted only memories:read can use the five Read tools and nothing else. A connection granted memories:read and memories:write adds store_memory; the delete tools refuse without memories:delete, and the reflection tools refuse without memories:reflect. A host that wants to offer only Read and Write tools should request memories:read memories:write.

Status and errors.

• No token: HTTP 401 with a WWW-Authenticate challenge that points to the protected resource metadata. The host starts sign-in.
• Missing scope: the tool result has isError: true, plain text naming the scope, and an insufficient_scope challenge in _meta. Reconnect with that scope. Retrying does not help.
• Missing or wrong confirmation phrase on a delete tool: isError: true with "Deletion was not performed". Nothing reaches storage.
• Invalid arguments, such as an empty query: JSON-RPC error -32602. Malformed JSON: -32700. A request that is not JSON-RPC 2.0: -32600.
• store_memory returns status from the queue. A queued write becomes searchable shortly after; check with a search instead of retrying, which would store a duplicate.

Rate limits. Authenticated tool calls have no fixed per-vault request cap today. Usage is metered against the plan's monthly memory-token allowance. Unauthenticated traffic is limited per IP address, and OAuth client registration is limited to 10 per IP per hour. If the API ever returns 429, the tool result has isError: true with that message; wait before retrying.

Deletion: what is and is not possible

Two deletion tools exist, and they are deliberately different:

• delete_memories removes specific memories by their ids (up to 100 per call). Ids come from search_memories or inspect_memory results. It requires the memories:delete scope and an explicit confirmation argument, and the host should show the user what will be deleted before calling it. Deleting a raw memory does not delete reflections built from it.
• forget_all_memories is whole-vault only. It requires the memories:delete scope, the exact confirmation phrase DELETE ALL MEMORIES, and returns a result confirming both primary and mirrored storage were cleared. Anything short of that returns "nothing was deleted" and never reaches storage.

A store_memory receipt is not a deletion handle. The dashboard at app.memoryrouter.ai also supports per-memory deletion.

Reflections on this server

The Reflection Hierarchy is live end to end: three memory tiers, consolidation, lineage, and per-memory deletion, all usable from inside a chat.

The consolidation round trip works like this:

1. The model calls consolidate_memories. The server checks out the oldest unconsolidated memories under a 15 minute lease and returns their texts, dates, and the server-authored reflection_contract instructions.
2. The model reads the texts and writes 5 to 10 standalone reflection entries, rating each entry's importance from 1 to 10, following the contract verbatim.
3. The model calls commit_reflections with the batch id and its entries. The server embeds and stores them at the tier above, links lineage to every source, and marks the sources consolidated.

So in ChatGPT or Claude you can literally say "consolidate my memories" and the model you are already talking to does the reflecting. If the lease expires before commit, nothing is lost: the memories return to the pool and the next checkout picks them up.

memory_status reports reflection debt (how much unconsolidated material the vault carries), and search_memories results include consolidation_available when the vault crosses the consolidation threshold, so the model knows when reflection is worth suggesting.

inspect_memory is the receipts tool: give it any memory id from a search result and it returns the lower-tier memories that reflection was built from, chainable all the way down to raw. Ask "why do you believe that?" and the model can show you.

Search filters

search_memories accepts two optional filters on top of the query:

• tiers: a non-empty subset of [1, 2, 3] to restrict results to raw memories, reflections, or high-level reflections. Omit to search all tiers blended.
• importance: an integer 1 to 10 minimum threshold. Only reflections carry importance ratings, so this filters to tier 2 and 3 content.

Tier guide: tier 3 holds the highest-level consolidated reflections (identity, principles, what matters most); tier 2 holds reflections of specific meaningful events; tier 1 holds raw verbatim memories. Match filters to the question rather than applying one rigid recipe:

• Broad "most important things we've done" questions: tiers [3], importance 8 or higher, a large limit such as 250. Time-bounded variants ("most important things last month") use date search with the same filters.
• Big-picture overviews ("what do you know about this area or period"): tiers [3] alone, with no importance filter. Importance filtering is optional and can exclude useful context.
• Specific-topic lookups ("find the decision about X"): omit tiers entirely so raw, tier 2, and tier 3 are searched together, and leave importance unset. A high importance filter hides the specific detail being sought.
• Specific meaningful events where raw noise is unwanted: tiers [2] (optionally [2, 3]).
• Exact verbatim or forensic detail: if the detail is not already in context, drill down by lineage: search tiers [3] to find the relevant thread, then use inspect_memory on the result to see the tier 2 reflections it consolidated, then inspect those to reach the raw memories underneath. Direct tiers [1] search works when you know exact wording to match.

Mixtures of tiers are legitimate; adjust the importance threshold to the question instead of always setting it high. Only reflections (tiers 2 and 3) carry importance ratings.

The served tool descriptions teach this playbook to every connected model automatically.

Every result row is tagged with its tier, and reflection rows include their importance.

Date search

date_search_memories retrieves memories from a specific time window: from (required ISO 8601 date or datetime), optional to, query, tiers, importance, and max_tokens (1000 to 200000). Omit query for a chronological review; include it to rank by relevance within the window. Truncated pages return next_to/next_from continuation cursors. Relative phrases like "lately" must be resolved to concrete ISO dates before calling.

Authentication and scopes

MemoryRouter runs a full OAuth 2.1 authorization server with PKCE (S256), dynamic client registration, Client ID Metadata Documents, refresh-token rotation, and revocation.

Four scopes exist, and they are independent:

There is deliberately no hierarchy and no admin scope. memories:write does not grant recall, reflect authority does not grant deletion, and delete authority is never inherited from write. A connector configured to save notes therefore cannot erase your vault.

Authorization defaults to read-only. Clients request more only when they need it, and the server answers an under-scoped call with a reauthorization challenge instead of performing the action.

Read-only enforcement is layered

A read-only OAuth token is also downgraded at the downstream API-key layer, so even an internal routing mistake cannot turn a read connection into a write. Existing read-only key conventions (mk_ro_, mk-ro-, and :read/:off modes) keep working and are never widened.

Vaults: personal, project, and organization

One OAuth connection is bound to one vault, chosen during sign-in.

That is the entire isolation model, and it is worth being precise about:

• Personal, project, and organization vaults are separate vaults. You pick which one a connection uses when you authorize it.
• To switch vaults, disconnect and reconnect the connector and choose a different vault.
• Project and organization "handles" that appear inside a conversation are behavioral labels for compatibility, not server-verified arguments. The MCP tools do not currently accept a project or vault parameter, so a model cannot select or escape a scope by asking.

If you need strict isolation, use a separate vault and a separate connection. Do not rely on conversational scope labels as a security boundary.

Setting it up per platform

The canonical chooser separates connection, capture, and historical import:

"Model-directed" means the AI decides whether and when to search or save. It is not guaranteed on every turn. A connection makes future tool calls possible; it never implies that historical chats were imported. Generic MCP compatibility must be proven per client: Streamable HTTP support alone does not prove OAuth discovery/callback, scope, tool, or resource behavior.

Claude Code, Codex, and OpenClaw use local hooks outside the generic remote MCP transport. Claude Code 2.1.0 durably captures one typed prompt plus one final user-visible response for a completed turn and excludes tool/intermediate transcript data. Codex hooks require a MemoryRouter API key in addition to OAuth. OpenClaw uses relay hooks; inference and provider keys remain in OpenClaw.

See the platform comparison for plans, distribution/listing state, exact capture units, limitations, and current manual acceptance boundaries.

Troubleshooting

The client says authentication is required. Expected on first use. The server answers unauthenticated protected calls with a 401 and a WWW-Authenticate challenge so your client opens the connect flow. Sign in and retry.

A save or delete is refused as insufficient scope. The connection lacks memories:write or memories:delete. This is not retriable, disconnect, reconnect, and approve the scope. ChatGPT surfaces this as a reauthorization prompt.

Recall returns nothing. Confirm with memory_status that you are connected to the vault you expect. A common cause is being connected to a different vault than the one holding the memories.

Claude or ChatGPT never uses memory. On those surfaces, tool use is model-directed. Ask explicitly ("check my memory for…"), or use Claude Code / Codex where hooks make it deterministic.

A tool you read about does not exist. Only the ten tools above exist. Server-side project arguments are not implemented.

Consolidation is refused as insufficient scope. consolidate_memories and commit_reflections need the memories:reflect scope. Disconnect, reconnect, and approve reflect access when your client requests it.

For clients with a doctor command, run npx memoryrouter-claude doctor or npx memoryrouter-codex doctor for a local diagnosis.

Discovery endpoints

The advertised resource value is the full /mcp URL, matching what you type into the client, and access tokens are bound to that same RFC 8707 resource.

Privacy and deletion

• Memories are stored in the vault you selected during OAuth; they are not shared between vaults.
• memory_status returns an opaque vault reference. Your memory key is never exposed to the model, in tool output, or in a client-readable token claim.
• Whole-vault deletion is permanent and confirmed against both primary and mirrored storage.
• Per-memory deletion is available via the delete_memories tool or the dashboard.

Next steps

View the integration · Create an account · All integrations