MemHeaven

MemHeaven is a self-hosted remote MCP memory server for ChatGPT and other cloud AI agents.

It gives hosted AI clients searchable long-term memory you own, deployed on Cloudflare. MemHeaven is inspired by MemPalace's long-term-memory model while using a remote deployment shape for hosted clients.

Deploy on a Cloudflare Free account. No VM, no Docker, no database admin.

Free-tier limits apply; heavy usage may require paid Cloudflare usage.

Quick links: Quickstart · Getting started from zero · ChatGPT setup · Client compatibility · Security model · Behavior evals

What problem it solves

AI assistants are useful in the moment, but they often forget project context across chats, sessions, and tools.

Built-in memory features can help, but they are usually provider-owned and are not the same thing as an inspectable, searchable memory layer you control. Local-first memory tools are powerful too, but hosted clients like ChatGPT and other remote agents need a remote MCP server.

MemHeaven is for people who want:

• searchable memory they own
• inspectable and deletable stored context
• continuity for coding agents and other AI workflows across sessions
• a remote MCP deployment shape instead of a laptop-only setup

When MemHeaven fits

Choose MemHeaven when a hosted client or AI agent needs a searchable memory layer that persists outside the current chat:

• ChatGPT needs to retrieve project decisions, preferences, notes, or other durable context across chats.
• A remote MCP client cannot depend on a memory service running only on your laptop.
• Separate users or workflows need tenant-scoped access to stored context.
• You want to inspect, search, and delete the records held by your own deployment.

External memory, not a replacement for ChatGPT memory

MemHeaven does not change ChatGPT's built-in memory. It is a separate OAuth-protected MCP service that your client can call for context stored in your own deployment. There is no shared public MemHeaven instance: you operate the Worker, storage bindings, OAuth configuration, and access keys in your Cloudflare account.

ChatGPT long-term memory over remote MCP

If you want ChatGPT to use a searchable memory layer across chats without putting that memory in a shared third-party service, deploy MemHeaven in your own Cloudflare account and connect ChatGPT to your instance's /mcp endpoint. This external memory complements ChatGPT's built-in memory: you can inspect, search, and delete the records stored by your own deployment. See the ChatGPT setup and security model before connecting a client.

Why MemHeaven exists

• AI assistants forget project context across chats and sessions.
• Built-in memory is useful, but it is usually provider-owned and not an exact, searchable memory layer.
• Local-first memory tools are powerful, but hosted clients need remote MCP.
• Users want inspectable, searchable, deletable, portable memory.
• Coding agents need continuity across sessions, editors, and tools.

Cloudflare Free account is enough for personal use

MemHeaven is designed for personal use and small trusted-group usage on Cloudflare-managed services.

• Worker runs the HTTP server.
• D1 stores relational metadata and indexes.
• R2 stores drawer and diary bodies.
• Vectorize powers semantic vector search.
• Workers AI generates embeddings.

That means:

• no VM
• no Docker
• no database admin
• no long-running server process

Free-tier limits apply. MemHeaven does not promise unlimited free usage, enterprise uptime, or zero cost under every workload. Also note that some underlying Cloudflare services, especially Vectorize, have their own plan and usage constraints, so review the current Cloudflare pricing before a broad rollout.

Fastest happy path

npm install
cp wrangler.toml.example wrangler.toml
npm run init -- --base-url https://memheaven.<your-workers-subdomain>.workers.dev
npm run secrets:generate

npx wrangler secret put JWT_SIGNING_SECRET
npx wrangler secret put TOKEN_ENCRYPTION_KEY
npx wrangler secret put AUTH_KEY_PEPPER

export AUTH_KEY_PEPPER='<same AUTH_KEY_PEPPER value>'
npm run keygen -- --tenant personal --label "Personal"

npx wrangler deploy

Then connect your hosted client to:

https://memheaven.<your-workers-subdomain>.workers.dev/mcp

When the authorization page opens, paste the printed raw_key.

If you want the hand-holding version, use docs/GETTING_STARTED_FROM_ZERO.md.

Supported / expected clients

Full details: docs/CLIENT_COMPATIBILITY.md

Agent memory instruction

Use MemHeaven conservatively for writes and proactively for reads when prior context matters. The MCP tools return their own detailed guidance, so the ChatGPT/custom-agent instruction can stay short.

Copy-paste instruction for agents:

Use MemHeaven for cross-session memory. When prior context may matter,
start with mempalace_wake_context if available; otherwise call
mempalace_status and follow its returned guidance. Do not mix work,
personal, or project scopes. Save only durable facts, decisions, and
preferences as concise plain text.

Full guide: docs/AGENT_MEMORY_PROTOCOL.md

Inspired by MemPalace

MemHeaven is inspired by MemPalace, the open-source local-first AI memory project that helped show how useful verbatim, searchable long-term memory can be for AI agents.

MemPalace made a strong case for keeping original context and organizing it in a navigable memory structure. MemHeaven explores a different deployment shape: remote MCP memory for hosted clients and trusted shared setups.

We see that as complementary to MemPalace’s on-device approach, not a replacement for it.

How it works at a high level

• A Cloudflare Worker exposes OAuth endpoints and the authenticated /mcp endpoint.
• Hosted AI clients connect over Streamable HTTP MCP.
• D1 stores metadata, indexes, KG facts, tunnels, quotas, and audit rows.
• R2 stores full verbatim drawer and diary bodies.
• Workers AI generates embeddings.
• Vectorize performs semantic search over chunked memory content.
• Access keys gate authorization and map users to tenant-scoped memory.

Documentation

• docs/GETTING_STARTED_FROM_ZERO.md
• docs/CLIENT_COMPATIBILITY.md
• docs/AGENT_MEMORY_PROTOCOL.md
• docs/SECURITY.md

What is included

• OAuth 2.1 + PKCE + dynamic client registration for ChatGPT-compatible remote MCP.
• Access-key-gated consent page backed by stateless JWT auth artifacts.
• Tenant-scoped drawer, diary, knowledge-graph, and tunnel storage.
• Streamable HTTP MCP server using WebStandardStreamableHTTPServerTransport with per-request stateless bootstrap.
• MemPalace-compatible mempalace_* tool surface, including adapted local-only tools.
• Worker-safe semantic search using Workers AI embeddings + Vectorize + R2/D1 hydration.
• Quota guardrails, redacted audit logging, smoke scripts, and local test coverage.
• Synthetic memory behavior evals for retrieval, scope isolation, tenant isolation, and KG lifecycle regressions.

Memory behavior evals

Use the local eval harness before/after retrieval, wake-context, or KG behavior changes:

npm run eval:local
npm run eval:baseline

The optional remote smoke/eval skips safely unless configured with environment variables:

npm run eval:remote

See docs/BENCHMARKS.md. These are MemHeaven self-evals with synthetic fixtures, not MemHeaven-vs-MemPalace benchmark claims.

How this differs from upstream MemPalace

• Preserves tool names, wings/rooms/drawers model, Memory Protocol, diary, KG, and tunnel concepts where practical.
• Does not preserve Python runtime, ChromaDB internals, filesystem sync, or local desktop hook behavior.
• Stores verbatim drawer and diary bodies in R2; D1 and Vectorize are indexes/metadata, not source of truth.
• Uses short-lived JWT authorization codes plus access and refresh tokens with durable replay protection instead of server-side OAuth sessions.

Public routes