MemPersist

MemPersist

Long-term memory for AI conversations, running entirely on Cloudflare. Original ChatGPT exports and normalized conversation graphs live in R2, a D1 catalog makes them queryable, lexical and semantic indexes stay disposable, and MCP exposes compact retrieval plus intentional writes.

What it does. Preserves every uploaded ChatGPT export byte-for-byte, normalizes branches and node metadata into revision-pinned canonical JSONL, indexes derived FTS and vector data, and answers search, context, and batch reads with deterministic IDs. Writes are intentional, revision-checked, and durable before indexing is queued.

What it refuses to do. It does not intercept ChatGPT traffic, extract replacement "facts", summarize with a model, or treat any index as canonical. No billing, organizations, or speculative multi-tenancy; no Durable Objects, Workflows, cron triggers, or containers. Deleting every chunk, FTS row, and vector does not delete memory. "Unlimited" means no application-level message quota — Cloudflare limits and billing still apply.

Architecture

flowchart TD

IMP["ChatGPT data export (conversations.json)"] --> V WRITE["MCP writes from any client"] --> V V["Validation and stable IDs"] --> R2[("R2 canonical archive raw import + immutable revisions")] R2 --> D1[("D1 catalog imports, revisions, graph, R2 pointers")] D1 --> Q["Cloudflare Queues import and index jobs"] Q --> FTS[("D1 FTS5 lexical chunks")] Q --> AI["Workers AI BGE-M3"] --> VEC[("Vectorize embeddings")] FTS --> SEARCH["Normalized hybrid search plus recent-canonical fallback"] VEC --> SEARCH SEARCH --> OUT["HTTP API and OAuth-protected MCP"] R2 --> EXPORT["Lossless export and recovery"]

Two ingestion paths, and they stay independent: the ChatGPT data export parser accepts the native conversations.json format only, while writes arrive through MCP from whichever client the caller uses. Both converge on the same canonical revision model, so a memory created by a tool call and one imported from an export are read, pinned, and restored identically.

R2 is the source of truth. A canonical write completes before its index job is queued, and an indexing failure never reports that durable memory was lost. Rebuilds read R2, so an export never needs to be uploaded twice. Full detail in ARCHITECTURE.md and docs/storage-and-indexing.md.

Quickstart

yarn install

cp .dev.vars.example .dev.vars # set a long random MEMORY_API_TOKEN yarn types:bindings yarn db:migrate:local yarn dev

Requires WSL2/Linux, Node.js 22+, Yarn 1.22, and Wrangler 4.x authenticated with yarn wrangler whoami. Use Yarn only. Local D1, R2, KV, and Queues are simulated; Workers AI and Vectorize point at real remote bindings in the main configuration, while unit and integration tests never call remote AI.

Connect any MCP client

MemPersist is a standard remote MCP server: stateless Streamable HTTP at https://mempersist.codifiedtech.id/mcp, OAuth 2.1 authorization code with PKCE S256, scope memory. Nothing in the endpoint is client-specific — the same handshake, tool contracts, and server instructions serve every caller. Point a client at the URL and it works:

Codex configuration:

[mcp_servers.mempersist]

type = "remote" url = "https://mempersist.codifiedtech.id/mcp"

auth = "oauth" is the default; run codex mcp login mempersist to authorize

The client discovers OAuth from the 401 challenge, opens the consent page, and stores the issued access and refresh tokens. The consent page takes an email and sends a single-use, 15-minute magic link through the EMAIL binding; the connection completes only after that link is opened, and an existing email reconnects to its archive. The single scope is memory, and the sender address is configuration (AUTH_EMAIL_FROM, LEGACY_AUTH_EMAIL_FROM), not part of the API contract. Never paste MEMORY_API_TOKEN into a connector.

Already-configured connections keep working across upgrades without re-authorization; the legacy hostname stays supported, and moving one client to the primary hostname costs exactly one new authorization.

Developer token

Scripts, the CLI, and non-interactive automation may send Authorization: Bearer instead of OAuth, which always maps to the owner archive. Every account may own multiple namespaces; the same namespace name in two accounts is separate data, and a supplied namespace is honored only when the caller owns it.

Local, without deploying

The MCP audience is deployment configuration, so point a development server at itself:

yarn dev --local --port 8787 --local-protocol https \

--var MCP_ORIGIN_OVERRIDE:https://127.0.0.1:8787

Discovery, consent, and token audiences then use https://127.0.0.1:8787, and both the .dev.vars developer token and the full OAuth flow work. Local send_email writes each magic link to .wrangler/tmp/email/ /email-text/. See docs/development.md.

Tools

24 tools, each carrying a human-readable title and read-only or destructive annotations. Retrieve first, then expand only what you selected.

Read

memory_get_messages accepts 1–100 ordered selectors. Each selector names a conversation_id, optionally pins a revision_id, and uses exactly one of source_node_id (up to 200 characters) or the forward-compatible message_key (1–128 lowercase ASCII letters, digits, ., _, /, or -, starting and ending with a letter or digit). Omitted revisions pin each conversation's current head before any canonical R2 body is loaded; canonical loads are deduplicated by unique pinned revision, while duplicate selectors retain duplicate ordered results. The read-only lookup does not use FTS or Vectorize. Missing, foreign, deleted, or unknown conversations, revisions, nodes, and keys share the same bounded NOT_FOUND result. Duplicate canonical message keys return a bounded canonical-storage error and are never resolved by choosing one. Whole messages are admitted within the 32 KiB default, 4 KiB minimum, and 48 KiB maximum serialized budgets; an oversized message is not truncated and returns only bounded identity/byte diagnostics. Continuations use an opaque, HMAC-signed, tenant-bound cursor that preserves selector order and revision pins.

The optional message_key selector reads keyed fields written by memory_upsert_messages (and any canonical data that carries them). memory_upsert_messages is the stable-key writer for logical records; its contract is documented in the Write section below.

Context assembly

Write

Each write returns a bounded durable receipt with separate indexing and verification status, and accepts verify: true to reload t