# MCP memory server: how persistent agent memory works

> The protocol, authorization, tools, and data model behind memory that works across MCP clients.

Published: 2026-07-11
Updated: 2026-07-11
Author: Ocean Labs

An MCP memory server is a service that exposes durable storage and retrieval as tools any compatible AI client can use. The agent connects through the Model Context Protocol, authorizes as a user, and calls tools to save or recall context. Because the memory sits outside the model, it can persist across sessions and clients.

## What MCP changes

Without a common protocol, every memory service needs a separate integration for every agent framework. MCP separates the client from the capability. The server describes its tools and resources; the client decides when to use them.

The official [Model Context Protocol documentation](https://modelcontextprotocol.io/) defines the transport and capability model. It does not prescribe one memory architecture. An MCP server can expose files, a vector store, a graph, SQL, or a layered system behind the same connection.

## The parts of an MCP memory service

### A stable endpoint

A remote server gives several clients one address. OceanDB uses:

```text
https://app.oceandb.ai/api/mcp
```

### Authorization

Memory is personal data. The server must establish who the caller is before it returns anything. OceanDB uses OAuth 2.1 discovery and browser authorization, then scopes database access to the user's workspaces.

### A small tool surface

Simple tools improve the common path:

- `remember` captures durable context;
- `recall` retrieves relevant memory;
- `onboarding_status` guides the first connection;
- `execute_sql` exposes the full data language underneath.

The simple tools make routine use easy. SQL prevents the abstraction from becoming a ceiling.

### Agent-readable resources

An MCP server can publish instructions and schema as resources. OceanDB exposes its operating conventions, Dreamer playbook, and live schema so the agent can orient itself without relying on an old prompt copied into every client.

## A memory turn

A typical turn is small:

1. The client connects and discovers the server.
2. The user authorizes access in the browser.
3. The agent checks memory before asking for repeated context.
4. The agent records a durable decision as it works.
5. A later agent recalls that decision through the same endpoint.

The model can be different on step five. The memory does not depend on model weights or a particular chat history.

## Remote versus local MCP memory

| Question            | Local server                    | Remote server                           |
| ------------------- | ------------------------------- | --------------------------------------- |
| Setup               | Install and run on each machine | Add one URL                             |
| Cross-device access | Requires synchronization        | Built in                                |
| Data custody        | Stays on the device             | Depends on the service and export model |
| Availability        | Depends on the local process    | Depends on the hosted service           |
| Team sharing        | Must be built separately        | Can be a first-class workspace boundary |

Neither is universally better. Local memory suits offline and device-bound work. Remote memory suits people who switch tools and machines or share a workspace. The important questions are who controls access, whether export is complete, and how maintenance works.

## Security is below the prompt

Prompt instructions are not an authorization layer. A memory server should enforce tenancy in storage and restrict the operations available to an agent.

OceanDB uses row-level security for workspace scope. Its agent database role can select, insert, and update but cannot delete, truncate, or change the schema. Human-only governance operations—such as inviting a member—remain outside the agent's grant.

This does not make every agent action correct. It limits what a mistaken or manipulated agent can do.

## Why maintenance remains separate

MCP solves connection and interoperability. It does not solve memory quality.

A server that accepts every write still needs a policy for duplicate facts, changing decisions, source attribution, and retrieval. OceanDB handles this with a scheduled client-side Dreamer. The user chooses the agent and model that perform the consolidation; the hosted server stores memory but does not run a hidden model over it.

## Connect an agent

For Claude Code:

```bash
claude mcp add --transport http oceandb https://app.oceandb.ai/api/mcp
```

Other MCP clients use the same URL. See the [connection guide](/docs/connect) for client-specific steps and [your first memory](/docs/getting-started) for the first write and recall.