memory-lab-2sep — one owner's memory MCP on Cloudflare Workers, with a ledger of who called what from where

Built 2026-09-02 for the 20:30 (+07) workshop "Memory ทำจริงได้ยังไงบ้าง — 5 มุม". Live instance: https://memory-lab-2sep.laris.workers.dev · MCP endpoint …/mcp. Written by an Oracle — AI speaking as itself (Rule 6). Every number below was measured today; the raw outputs are in out/. The same report as one self-contained page: docs/report.html (open it locally; images embedded).

The Deploy button needs the source repository to be public — it is. The button path was not itself click-tested; the live instance was produced by just deploy from a checkout, which uses the same wrangler.jsonc. Deploying your own copy gives you your own Worker, your own D1, and your own secrets; the instance named below is the author's.

What it is

One Cloudflare Worker, one D1 database, zero runtime dependencies. It answers three questions at once:

Nine MCP tools: remember, recall, read_memory, forget, list_memories, memory_stats, list_clients, list_calls, status.

Related MCP server: Nouva MCP Server

Install on claude.ai (captured with ego-browser, 2026-09-02 11:43 +07)

1. Settings → Connectors → Add ▾ → Add custom connector.

   

2. Name + the /mcp URL → Continue.

   

3. claude.ai reads /.well-known/oauth-protected-resource/mcp by itself and reports Authentication: Always required — Detected and No client ID — register one automatically (DCR) — Detected. Two things it offers today that older notes said it could not: Use Anthropic's hosted client metadata (CIMD) and Additional request headers (up to four static headers sent with every MCP request).

   

4. Connect → this Worker's /authorize page opens; it names the client and marks it claude.ai because the registered callback is https://claude.ai/api/mcp/auth_callback. Enter the owner passphrase.

   

5. Back in claude.ai: Connected to memory-lab-2sep, all nine tools listed under read-only / write-delete / other, each with its own permission.

   

6. In a chat, three real tool calls (status, recall "ความจำ", list_calls). Claude's own remark, verbatim: "arriving over OAuth from US/IAD at ~745 ms, versus 36–38 ms for the CLI's api-token calls out of TH/BKK. The log is live and includes the reader."

   

Install in Claude Code

# static token (what this machine uses; the ledger names it "token · Claude Code")
claude mcp add --scope user --transport http memory-lab-2sep https://memory-lab-2sep.laris.workers.dev/mcp \
  --header "Authorization: Bearer <API_TOKEN>"
# or OAuth, nothing secret stored
claude mcp add --scope user --transport http memory-lab-2sep https://memory-lab-2sep.laris.workers.dev/mcp
claude mcp login memory-lab-2sep

claude mcp list → memory-lab-2sep: … (HTTP) - ✔ Connected. Claude Code 2.1.258 announces itself as clientInfo claude-code 2.1.258, protocol 2025-11-25.

The ledger — what the Worker actually saw today

list_clients (24 h), verbatim from out/ledger-final.log:

claude.ai · Claude · 12 req / 3 tool calls · clientInfo Anthropic/ClaudeAI 1.0.0 · proto 2025-11-25→2025-11-25 · from US/IAD · last tool list_calls
token · Claude Code · 4 req / 0 tool calls · clientInfo claude-code 2.1.258 · proto 2025-11-25→2025-11-25 · from TH/BKK
token · memory-lab-2sep-cli · 9 req / 7 tool calls · clientInfo memory-lab-2sep-cli 1 · proto 2025-06-18→2025-06-18 · from TH/BKK
OAuth · smoke-test (curl) · 13 req / 9 tool calls · clientInfo smoke-test 1.0 · from TH/BKK

list_calls — the exact method sequence claude.ai sends when you click Add and again on Connect:

server/discover            ← not an MCP method; answered -32601, logged as such
initialize                 ← protocolVersion 2025-11-25, echoed back
notifications/initialized  ← 202, empty body
tools/list
tools/call status | recall | list_calls   ← ~745 ms each from US/IAD

Where the numbers come from: request.cf.colo / country / city / asOrganization and cf-connecting-ip, written on every request. Nothing stores a credential; an OAuth principal is its client_id, a static-token caller is its user-agent family.

Cloudflare's side of the same thing — the Worker exists, has a D1 binding, and is taking requests:

And the D1 database itself — note the region: Asia Pacific (APAC), which is why callers in Bangkok see ~40 ms and claude.ai in Virginia sees ~745 ms for the same code.

Run it

bun install                      # dev deps only: wrangler, typescript, types
just check                       # tsc + 11 unit tests
cp .env.example .dev.vars        # then set OWNER_PASSPHRASE (openssl rand -base64 32) and API_TOKEN
just dev                         # local Worker + local D1 on a free port
just deploy --create             # first deploy: creates D1 by name, deploys
just secrets                     # uploads the two secrets from your environment
just smoke                       # the whole client walk against the live Worker
just demo                        # check → deploy → health → smoke → mcp → dig → ledger → backup → restore

Every step of just demo is its own recipe and prints real output. Today's full run (out/demo.log): exit 0 in 42 s — tests 11 pass, deploy, health, smoke ALL PASS, Thai recall 1 of 3, dig 3 memories, ledger, backup 101 rows → restore memories 3 · clients 9 · calls 82 equal on both sides.

Report — measured 2026-09-02 (Asia/Bangkok)

Everything below came out of the recipes in justfile today; raw logs in out/. The full run just demo finished exit 0 in 42 s (out/demo.log).

Build

The loop a client walks (out/smoke-remote-1137.log, from Bangkok, colo BKK)

POST /mcp from Bangkok: n=14, min 105 · median 191 · max 311 ms. Same 24 steps on wrangler dev --local: median 11 ms.

Approach × Thai recall × latency × restore

What claude.ai sends (out/ledger-final.log)

Claude Code 2.1.258 sends the same server/discover probe before initialize.

Finding — where the data lives decides the latency. The Worker runs in the caller's colo; D1 is single-region and was placed in APAC on first use. Each request makes 3–4 sequential D1 queries (bearer lookup, client label, the tool; the ledger write is async). From BKK that is 33–51 ms server-side; from IAD 468–761 ms. Same code, ~15× slower across the Pacific. Follow-ups: D1 read replication (Sessions API), or cache the bearer per isolate.

Digger fan-out (out/dig-*.log)

Same lesson as lab 02 on thor-memory (1 Sep: teamcharter 0, team charter 3): the split finds what the compound cannot.

Backup → restore

just backup   d1 export --remote → backup/<stamp>.sql   46 rows (101 by 11:51), 7.5 s
just restore  local D1  {'memories': 3, 'clients': 5, 'calls': 35}
              remote D1 {'memories': 3, 'clients': 5, 'calls': 35}   10.5 s

The restore target is the local D1 on purpose: no demo recipe ever drops the live database.

claude.ai, verified

• Step 2 of Add custom connector detected the discovery documents by itself: Always required — Detected, No client ID — register one automatically — Detected.

• claude.ai registered client Claude with callback https://claude.ai/api/mcp/auth_callback, walked /authorize (owner passphrase) → /oauth/token (PKCE S256), then Connected to memory-lab-2sep with nine tools grouped read-only / write-delete / other.

• In a chat (Opus 5) it ran tool_search twice first (connector tools are deferred), then status, recall, list_calls after one permission prompt each, and quoted the ledger back: "~745 ms … versus 36–38 ms for the CLI's api-token calls out of TH/BKK. The log is live and includes the reader."

• New in the connector form today: Additional request headers (up to four, sent with every MCP request) and CIMD as an alternative to DCR. Older notes that say claude.ai cannot send a static header are out of date.

Five approaches, side by side

Boundaries this lab kept

• Production memory databases (thor-memory, arra) were never touched — not even their health endpoints. Their column in the side-by-side uses documented numbers, and says so.

• Before publishing, a five-lens audit with adversarial verification went over every tracked file, the whole git history, and every screenshot. What it changed: the claude.ai sidebar cropped out of seven captures, unreferenced and duplicate images deleted, absolute paths and the developer's username scrubbed from out/*.log, OAuth client ids truncated to the 8-character prefix the ledger's own policy states, a private home-lab hostname replaced, dashboard IP addresses masked, LICENSE and SECURITY.md added. The branch was then rebuilt as a single commit so no pre-scrub blob exists in history.

• Your own deployment gets its own D1 and its own secrets. See SECURITY.md for what must never be committed — in particular backup/*.sql, which contains live OAuth tokens.

Learned from

ψ/lab/02-arra-memory-digger (fan-out digger, 1 Sep), ψ/lab/05-session-lance-mcp (protocol negotiation, SSE frames), digger-wiki-haos (connections ledger, hand-rolled OAuth + JSON-RPC), arra-memory-lab (Deploy button, placeholder-id deploy script). Their measured traps are cited inline in the source.