接入你的智能体
发布者自己的 URL。不是 PlugMCP 端点。
用我们的密钥与日志托管一份副本。
https://{worker_domain}/mcp上方的 Claude 按钮会打开 Claude，并填好名称和 URL。你仍需在那里确认。
claude mcp add --transport http io.github.nazar256-memheaven https://{worker_domain}/mcpRun in a terminal.
{ "mcpServers": { "io.github.nazar256-memheaven": { "command": "npx", "args": [ "-y", "mcp-remote", "https://{worker_domain}/mcp" ] } }}claude_desktop_config.json
远程 URL 还是本机命令？ 两种安装方式的区别
来自发布者
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.
Self-hosted remote MCP memory server for ChatGPT and AI agents.
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
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:
Choose MemHeaven when a hosted client or AI agent needs a searchable memory layer that persists outside the current chat:
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.
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.
MemHeaven is designed for personal use and small trusted-group usage on Cloudflare-managed services.
That means:
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.
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.
Full details: docs/CLIENT_COMPATIBILITY.md
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
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.
/mcp endpoint.WebStandardStreamableHTTPServerTransport with per-request stateless bootstrap.mempalace_* tool surface, including adapted local-only tools.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.
Implemented MemPalace-compatible tools are grouped by domain below. Each tool is listed individually so directory indexes can extract its name and description.
Palace read tools
mempalace_status — Diagnostics and backend capabilities for memory-relevant chats.mempalace_wake_context — Start a memory-relevant chat with bounded, privacy-scoped startup context.mempalace_list_wings — List tenant-scoped wings and active drawer counts.mempalace_list_rooms — List tenant-scoped rooms and active drawer counts for one wing or all wings.mempalace_get_taxonomy — Return the current tenant-scoped wing and room taxonomy.mempalace_get_aaak_spec — Return compact guidance for concise, readable memory notes.mempalace_search — Search tenant-scoped drawers with hybrid semantic and lexical retrieval.mempalace_check_duplicate — Check for exact or semantic duplicates before writing memory.mempalace_get_drawer — Fetch one tenant-scoped drawer with bounded content and provenance.mempalace_list_drawers — List active tenant-scoped drawers with optional wing and room filters.Palace write tools
mempalace_add_drawer — Add durable drawer content and index it semantically.mempalace_update_drawer — Update a drawer and reindex changed content or metadata.mempalace_delete_drawer — Soft-delete a tenant-scoped drawer and remove its semantic index entries.Diary tools
mempalace_diary_write — Write a concise diary entry and index it for scoped search.mempalace_diary_read — Read recent diary entries with optional wing and room filters.mempalace_diary_search — Search diary entries for one explicit agent with hard scope filters.mempalace_diary_reindex — Backfill or refresh diary semantic index rows for the tenant.Knowledge graph tools
mempalace_kg_query — Query tenant-scoped temporal knowledge-graph facts.mempalace_kg_check — Run deterministic reliability checks for active KG conflicts and stale facts.mempalace_kg_add — Add a tenant-scoped temporal knowledge-graph fact.mempalace_kg_invalidate — Invalidate an exact tenant-scoped knowledge-graph fact.mempalace_kg_timeline — Show the recent knowledge-graph timeline for an entity or all facts.mempalace_kg_stats — Return tenant-scoped knowledge-graph statistics.Navigation and graph tools
mempalace_traverse — Traverse the tenant shared-room graph and explicit tunnels.mempalace_find_tunnels — Find tenant-scoped cross-wing shared rooms that behave like passive tunnels.mempalace_graph_stats — Return tenant-scoped graph, shared-room, and explicit tunnel statistics.mempalace_create_tunnel — Create an explicit tenant-scoped tunnel between wing and room locations.mempalace_list_tunnels — List tenant-scoped explicit tunnels, optionally filtered by endpoint wing.mempalace_delete_tunnel — Delete a tenant-scoped explicit tunnel by ID.mempalace_follow_tunnels — Follow explicit tunnels connected to a wing and room location.Deployment adaptations
mempalace_hook_settings — Return the configured save policy for this deployment.mempalace_memories_filed_away — Return the latest tenant-scoped write filing status.mempalace_reconnect — Return configured binding and index health.mempalace_sync — Report that local filesystem and git sync is unsupported in hosted mode.This MVP intentionally omits generic search / fetch aliases to avoid duplicating the primary MemPalace surface unless connector UX proves they are needed later.
All exposed MCP tools also advertise structured outputSchema metadata so ChatGPT and other MCP clients can better understand successful tool results from tools/list.
wrangler authenticated against the target Cloudflare accountThis is the fastest happy path for self-hosting MemHeaven.
Install dependencies:
npm install
Choose the public base URL. This must be the origin only; do not include /mcp.
https://memheaven.<your-workers-subdomain>.workers.devhttps://memory.example.comPick the final public origin you actually plan to keep using. Changing the public origin later changes the OAuth issuer/client identity and will force hosted clients like ChatGPT to reconnect.
Create the local Wrangler config:
cp wrangler.toml.example wrangler.toml
Create Cloudflare resources, patch wrangler.toml, and apply remote migrations:
npm run init -- --base-url https://memheaven.<your-workers-subdomain>.workers.dev
Generate valid secret material:
npm run secrets:generate
Upload the generated secrets:
npx wrangler secret put JWT_SIGNING_SECRET
npx wrangler secret put TOKEN_ENCRYPTION_KEY
npx wrangler secret put AUTH_KEY_PEPPER
Generate your first access key and sync ACCESS_KEYS_JSON:
export AUTH_KEY_PEPPER='<same AUTH_KEY_PEPPER value>'
npm run keygen -- --tenant personal --label "Personal"
Validate locally, then deploy:
npm run lint
npm run typecheck
npm test
npm run build
npx wrangler deploy --dry-run --outdir .tmp/wrangler-bundle
npx wrangler deploy
cp wrangler.toml.example wrangler.toml
npm run init -- --base-url https://memheaven.<your-workers-subdomain>.workers.dev
npm run init now:
wrangler.tomltenant_id, wing, room, kind, agent_name, topic)[[d1_databases]] block in wrangler.toml with the real D1 database_idOAUTH_ISSUER, MCP_RESOURCE, and MCP_AUDIENCE when --base-url is providedwrangler.toml is intentionally gitignored because npm run init -- --base-url ... patches account-specific deployment values. Commit changes to wrangler.toml.example when defaults change.
Useful variants:
npm run init -- --dry-run
npm run init -- --skip-migrations
npm run init -- --base-url https://memory.example.com
After bootstrap, continue with secrets and access-key setup below. If you later bind a custom domain, rerun npm run init -- --base-url https://memory.example.com or manually update the three OAuth/MCP vars in wrangler.toml, then redeploy.
Generate valid secrets:
npm run secrets:generate
This prints JSON with valid values for:
JWT_SIGNING_SECRETTOKEN_ENCRYPTION_KEYAUTH_KEY_PEPPERStore them with Wrangler:
npx wrangler secret put JWT_SIGNING_SECRET
npx wrangler secret put TOKEN_ENCRYPTION_KEY
npx wrangler secret put AUTH_KEY_PEPPER
Generate an access key and automatically maintain the local git-ignored key store plus the Cloudflare ACCESS_KEYS_JSON secret:
export AUTH_KEY_PEPPER='<same AUTH_KEY_PEPPER value>'
npm run keygen -- --tenant personal --label "Personal"
By default this command:
.tmp/access-keys.jsonACCESS_KEYS_JSON using npx wrangler secret putIf you only want to update the local git-ignored file without touching Cloudflare yet:
export AUTH_KEY_PEPPER='<same AUTH_KEY_PEPPER value>'
npm run keygen -- --tenant personal --label "Personal" --no-sync
If you want a custom local file, it must stay under .tmp/:
export AUTH_KEY_PEPPER='<same AUTH_KEY_PEPPER value>'
npm run keygen -- --tenant personal --label "Personal" --file .tmp/my-access-keys.json --no-sync
The local file stores only hashed records, never raw keys. Save the printed raw key somewhere safe immediately because it is not written to disk.
npm run keygen -- --tenant <tenant> --label <label> to append a new active record..tmp/access-keys.json.npx wrangler secret put ACCESS_KEYS_JSON if you edited the file manually.Removing or deactivating a key invalidates existing access/refresh tokens for that key on the next /mcp or refresh-token check.
If you rotate AUTH_KEY_PEPPER, every existing raw access key becomes invalid because hashes are computed from raw_key + AUTH_KEY_PEPPER. After changing the pepper, regenerate all access keys and sync a fresh ACCESS_KEYS_JSON.
npm run init already applies remote migrations by default. If you skip them during bootstrap or need to rerun them later, Wrangler v4 defaults D1 commands to local mode, so use --remote explicitly for the deployed database.
npx wrangler d1 migrations apply memheaven_memory --remote
tenant_id.tenant_id is derived only from the verified bearer token; MCP tools never accept tenant selection from tool input.tenant_id, R2 keys are prefixed with tenants/{tenant_id}/..., Vectorize queries filter by tenant_id, and Vectorize hits are rechecked against D1 before content is returned.Add another tenant:
export AUTH_KEY_PEPPER='<same AUTH_KEY_PEPPER value>'
npm run keygen -- --tenant family-member --label "Family member"
npx wrangler deploy
The new command output prints a different raw_key. Give that key only to that tenant. Their drawers, diary entries, KG facts, and tunnels are isolated from the personal tenant.
Recommended operator checklist before sharing a second key:
id.tenant_id.memory.read, memory.write).npm run lint
npm run typecheck
npm test
npm run build
npx wrangler deploy --dry-run --outdir .tmp/wrangler-bundle
Notes:
npm run build emits Worker build artifacts to .tmp/dist.wrangler deploy --dry-run --outdir .tmp/wrangler-bundle validates the deploy bundle without changing production state.Before deploying, make sure:
wrangler.toml exists locally and npm run init -- --base-url <public-origin> has patched it with the right D1 id and OAuth/MCP URLs.JWT_SIGNING_SECRET, TOKEN_ENCRYPTION_KEY, AUTH_KEY_PEPPER, and ACCESS_KEYS_JSON are set with npx wrangler secret put ....<public-origin>/mcp.npx wrangler deploy --dry-run --outdir .tmp/wrangler-bundle
npx wrangler deploy
https://memory.example.com/mcp or your workers.dev /mcp URL./authorize, enter a valid raw_key printed by npm run keygen./mcp.ChatGPT has been manually verified end-to-end for MemHeaven's /mcp URL, OAuth authorization flow, and a mempalace_status tool call. That confirms the main hosted-client path without claiming that every ChatGPT plan or workspace supports custom MCP connectors.
Redirect URIs are intentionally restricted to documented ChatGPT and Claude callback contracts plus generic localhost loopback flows. Non-OAuth hosts can only work when they can call /mcp with Authorization: Bearer <token>.
OAuth discovery smoke:
npm run smoke:oauth -- --base https://your-domain.example
Authenticated MCP smoke:
export MEMHEAVEN_BEARER_TOKEN='<bearer-token>'
npm run smoke:mcp -- --base https://your-domain.example
Vector metadata reindex helper:
npm run reindex -- --base https://your-domain.example --dry-run
npm run reindex -- --base https://your-domain.example
npm run reindex -- --kind diary --base https://your-domain.example --dry-run
npm run reindex -- --kind all --base https://your-domain.example
Use the reindex helper if you created Vectorize metadata indexes after data had already been embedded and inserted. After upgrading an existing deployment to diary semantic search, run npm run init to ensure the agent_name and topic Vectorize metadata indexes exist, then run npm run reindex -- --kind diary --base https://your-domain.example to backfill existing diary entries from R2 into diary_chunks and Vectorize. Use --kind all when both drawer and diary vectors should be refreshed.
401 invalid_token on /mcp: token expired, key was removed, or the bearer token is missing.authorization failed / wrong key: make sure the raw key was generated with the same AUTH_KEY_PEPPER that is deployed as the Worker secret, and that npm run keygen synced the latest ACCESS_KEYS_JSON.406 Not Acceptable on /mcp: the client must send Accept: application/json, text/event-stream.503 from /health: a required secret or binding is missing or invalid.Quota exceeded: wait for UTC reset or raise the configured per-tenant limits.npm run init to ensure metadata indexes, then rerun npm run reindex ...; use --kind diary or --kind all when diary semantic search was added after diary entries already existed.http://127.0.0.1/localhost: the /authorize CSRF cookie is intentionally non-Secure in local HTTP mode so the browser can return it on consent POST.wrangler whoami looks unauthenticated under wrappers/custom HOME: check plain npx wrangler whoami in your normal shell before assuming the login is missing.After adding a second tenant, validate isolation manually:
mempalace_search.drawer_id with mempalace_get_drawer.The service does not trust client-supplied tenant information; isolation comes from the verified bearer token and storage-layer tenant filters.
mempalace_sync is intentionally unsupported in hosted mode.@cf/baai/bge-small-en-v1.5, so long drawer bodies are chunked before indexing.384 for the default MVP setup).docs/GETTING_STARTED_FROM_ZERO.mddocs/CLIENT_COMPATIBILITY.mddocs/AGENT_MEMORY_PROTOCOL.mddocs/SECURITY.mddocs/PRODUCT_REQUIREMENTS.mddocs/IMPLEMENTATION_PLAN.mddocs/PROJECT_STATE.mddocs/DECISIONS.mdMIT. See LICENSE.
Self-hosted remote MCP memory server for ChatGPT and AI agents.
{ "mcpServers": { "io.github.nazar256-memheaven": { "url": "https://{worker_domain}/mcp", "headers": {} } }}工具
暂无工具列表。远程服务器在首次健康检查后会获得工具列表。
常见问题
在本页复制适用于 Cursor、Claude Desktop、Claude Code 或 VS Code 的 http 配置。它使用发布者的安装方式，而不是 PlugMCP 代理。
此记录未列出必需的环境变量。
MemHeaven — Self Hosted Remote MCP Memory For ChatGPT 通过 HTTP 访问。
上次检查时间：2026-11-10。 Self-hosted remote MCP memory server for ChatGPT and AI agents.