{
  "markdown": "# context-keeper-remote\n\n[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/jarmstrong158/context-keeper-remote)\n\n_Part of the [xylem](https://github.com/jarmstrong158/xylem) stack._\n\nA remote [MCP](https://modelcontextprotocol.io) server on Cloudflare Workers that\nexposes context-keeper's rationale store (decisions, pipelines, constraints) over\nStreamable HTTP. It works as a **claude.ai custom connector**, including on mobile,\nso your project's decisions and constraints are available from any Claude session —\nno PC left running, no tunnel.\n\nIt also serves **[a phone app](#the-phone-view)** for reading that\nstore yourself: install it to your home screen once and it opens with no login and\nno token in the URL. Tabs for recent activity, per-project counts, cambium\nknowledge, and store health — and tapping any entry gives you the full rationale,\nnot just its title. Optional, opt-in, and on its own read-only credential.\n\n**Self-host your own copy in a few clicks with the button above** — Cloudflare\ncopies this repo into your GitHub account, creates a fresh D1 database for you, and\ndeploys the Worker. Then you add one secret and paste a URL into Claude. Full\nwalkthrough below; every step is a click, no command line anywhere.\n\n> The maintainer's own instance runs at\n> `https://context-keeper-remote.jarmstrong158.workers.dev`. Yours will be at your\n> own subdomain after you deploy.\n\n### Why it's built this way\n\n- **Worker, not tunnel** — no \"PC must be on\" dependency.\n- **D1, not KV** — row-level writes and `WHERE` queries; two writers (desktop +\n  mobile) don't clobber each other the way whole-file JSON read-modify-write does.\n- **Stateless handler, no Durable Objects** — the tools are stateless RPCs against\n  D1, so the Worker runs on the Cloudflare **free plan**.\n- **Secret-path auth** — claude.ai custom connectors don't reliably send custom\n  bearer headers, so the token is the last path segment of the URL. The URL is the\n  credential.\n- **Self-migrating** — the Worker creates its own D1 schema at runtime, so a\n  brand-new empty database needs **no manual SQL** (verified by a cold-start test).\n\n---\n\n## Self-host it (one-click, no command line)\n\n### Step 1 — Click \"Deploy to Cloudflare\"\n\nClick the **Deploy to Cloudflare** button at the top of this page. Cloudflare will:\n\n1. Ask you to authorize GitHub and pick an account — it **copies this repo into\n   your GitHub account** (you get your own repo).\n2. **Automatically create a new D1 database** in your Cloudflare account and bind it\n   to the Worker. (This works because the Worker's config declares the database\n   binding without a hard-coded id, so Cloudflare provisions a fresh one for you.)\n3. Set up **Workers Builds** so every push to your new repo redeploys automatically.\n4. Build and deploy the Worker.\n\nWhen it finishes, your Worker is live at\n`https://context-keeper-remote.<your-subdomain>.workers.dev`. Note that URL — you'll\nneed it in Step 3. (You can always find it under **Workers & Pages** in the\ndashboard.)\n\n> Nothing to configure in the repo, and **no SQL to run** — the database starts\n> empty and the Worker creates its tables on the first request.\n\n### Step 2 — Add the `AUTH_TOKEN` secret (Cloudflare dashboard)\n\nThe Worker refuses every request until it has an auth token, so set one:\n\n1. Cloudflare dashboard → **Workers & Pages** → your **context-keeper-remote**\n   Worker.\n2. **Settings** → **Variables and Secrets** → **Add**.\n3. Type: **Secret**. Name: `AUTH_TOKEN`. Value: a long random string (32+ characters\n   — treat it like a password). Save/Deploy.\n\nThat value is your connector's password. Keep it somewhere safe; you'll paste it in\nthe next step.\n\n<details>\n<summary>Also deploying the companion <code>agentsync-remote</code> worker?</summary>\n\n`agentsync-remote` uses the same `AUTH_TOKEN` scheme, and **additionally** needs, in\n*its* Worker's **Variables and Secrets**:\n\n- a **Secret** named `GH_PAT` — a GitHub personal access token, and\n- a **Variable** named `REPO` — set to the `owner/repo` it should sync.\n\nThose two do **not** apply to context-keeper-remote (this repo) — it only needs\n`AUTH_TOKEN`. See the `agentsync-remote` README for its specifics.\n</details>\n\n### Step 3 — Add the custom connector in claude.ai\n\n1. claude.ai → **Settings** → **Connectors** → **Add custom connector**.\n2. Paste your Worker URL with the token as the final path segment:\n\n   ```\n   https://context-keeper-remote.<your-subdomain>.workers.dev/mcp/<AUTH_TOKEN>\n   ```\n\n   Replace `<your-subdomain>` with your Worker's subdomain (Step 1) and\n   `<AUTH_TOKEN>` with the exact value you set (Step 2).\n3. Save. The tools (`record_entry`, `get_context`, `query_entries`, …) are now\n   available in your Claude sessions.\n\n**Check it works:** ask Claude to call `get_project_summary`. If it answers, the\nwhole chain (deploy → auto-provisioned D1 → auto-migration → auth) is working.\n\n### Step 4 — Migrate existing local data (optional)\n\nIf you already run local context-keeper, ask Claude (with the connector enabled) to\ncall **`import_entries`**, pasting each file's contents:\n\n- `decisions.json` → `import_entries(project, kind=\"decision\", entries=[...])`\n- `pipelines.json` → `import_entries(project, kind=\"pipeline\", entries=[...])`\n- `constraints.json` → `import_entries(project, kind=\"constraint\", entries=[...])`\n\nIncoming ids are preserved; existing ids are reported, never overwritten.\n\n### Step 5 — Install the phone view (optional)\n\nEverything above is the MCP connector, which is for Claude to read. Step 5 is for\n**you** to read it, from your phone. It needs a clone of this repo and Node 22+,\nwhich is the only part of the setup that touches a command line — the connector\nitself never does.\n\nSee [the phone view](#the-phone-view) below.\n\n---\n\n## The phone view\n\n`/view` is a read-only, server-rendered page of every project's decisions and\nconstraints. Install it to your home screen and it opens like an app: no login,\nno token in the URL, nothing to remember.\n\n| | |\n|---|---|\n| ![Recent](docs/screenshots/1-recent.png) | ![Entry detail](docs/screenshots/2-entry.png) |\n| **Recent** — what changed, across every project | **Any entry** — the reasoning, not just the title |\n| ![Projects](docs/screenshots/3-projects.png) | ![Health](docs/screenshots/4-health.png) |\n| **Projects** — counts per project, including how much of each rulebook is enforceable | **Health** — mojibake, thin rationale, untagged, stale |\n\n<sub>Synthetic data. Every project and entry above is invented — see\n[docs/screenshots](docs/screenshots/) for the dataset and how to regenerate these.</sub>\n\nIt has four tabs, matching the desktop dashboard:\n\n| tab | what it answers |\n|---|---|\n| **Recent** | what changed lately, across every project |\n| **Projects** | per-project counts: entries, active, constraints, **scoped**, supersession links, stale, mojibake |\n| **Knowledge** | cambium's team/org counts, if wired (see below) |\n| **Health** | mojibake, thin rationale, untagged, stale — as proportions and a per-project ranking |\n\nTap any row for the **full entry**: problem, why it was chosen, what was tried\nfirst, tradeoffs, alternatives with the reason each was rejected, and — for\nconstraints — scope, hardness, and what enforces it. Search covers every field,\nincluding the reasoning, which is usually where the answer is. Superseded entries\nstay reachable, and each entry links to what it replaced and what replaced it.\n\n### Install\n\n**1. Create the credential.** Double-click `scripts/set-view-token.cmd`\n(macOS/Linux: `scripts/set-view-token.sh`). From a terminal use the absolute path\n— **not** `npm run`, which needs the repo as your current directory:\n\n```bash\npowershell -NoProfile -ExecutionPolicy Bypass -File \"/full/path/to/context-keeper-remote/scripts/set-view-token.ps1\"\n```\n\nOne run generates the token, installs it, waits for the route to answer `200`,\ncopies the URL, opens it in your browser, and prints a **QR code**.\n\n**2. Scan the QR with your phone**, then install it:\n\n- **Android / Chrome** — a banner offers **Install**, or use ⋮ → **Install app**.\n  If the menu only says *Add to Home screen*, the manifest is failing Chrome's\n  install criteria; the usual cause is a missing **192x192** icon, which makes\n  Chrome degrade silently to a plain shortcut that opens in a browser tab.\n- **iPhone** — must be **Safari** (Chrome on iOS cannot install web apps).\n  Share → **Add to Home Screen**.\n\nThen tap through Recent, Projects, Knowledge and Health once while you have\nsignal — the offline cache only fills for pages you have actually opened.\n\nAdd `-DryRun` to run everything except the install, which is the fastest way to\ncheck your setup before touching anything.\n\n### It works offline, and a tap is instant\n\nA service worker caches every page you open, cache-first with a background\nrevalidate. Measured on the live instance:\n\n| | |\n|---|---|\n| served from cache | **1 ms** |\n| forced to the network | 278–383 ms |\n\nSo it opens with no signal, and switching tabs is instant rather than a\nround-trip. A decision log is not a live feed — showing yesterday's answer\nimmediately and correcting it a moment later beats showing nothing for 300ms,\nand the header carries an \"8h ago\" stamp so stale data is never presented as\ncurrent.\n\n**Only 200s are cached.** A `404` is what this Worker returns for an\nunauthenticated or rotated credential, and caching one would mean a device that\nrotated its token keeps being told it is signed out — from its own disk, with no\nnetwork involved and no obvious way to clear it. Verified in both directions.\n\n**The token still never reaches JavaScript.** The cookie is `HttpOnly`, so the\nservice worker cannot read it; it only issues same-origin requests the browser\nattaches it to. What was given up is \"no client-side JS at all\", not the\ncredential isolation. The CSP gains `script-src 'self'` and deliberately **not**\n`'unsafe-inline'` — the registration lives in its own file so an inline\nallowance, which would apply to the whole document including anything a recorded\nentry smuggled past the escaper, is never needed.\n\n### How it stays logged in\n\nThe token URL is an **enrolment** step, not a daily one. Visiting it sets a\nlong-lived `HttpOnly` cookie, and from then on the bare `/view` path works from\nthat device — which is what the home-screen icon opens.\n\n- **Nothing is widened.** The cookie carries the same secret the path did and is\n  compared the same way, so rotating `VIEW_TOKEN` still revokes every device at\n  once. There is one revocation path, no session table, and no expiry to track.\n- **Its own credential.** The view never accepts `AUTH_TOKEN`, and `/mcp` never\n  accepts `VIEW_TOKEN`. A leaked view URL discloses decision summaries; it cannot\n  write, deprecate, or delete.\n- **Unset means gone.** With no `VIEW_TOKEN`, `/view/<anything>` returns a bare\n  `404`, indistinguishable from a route that was never deployed.\n\n`npm run view` reopens it later (the URL is saved to `.view-url`, gitignored).\n`npm run view -- --qr` enrols another device **without** rotating the token —\nre-running setup would mint a new one and silently drop every device already\nadded.\n\n### Connect the Knowledge tab to cambium-remote (optional)\n\nOnly relevant if you also run [cambium-remote](https://github.com/jarmstrong158/cambium-remote).\n\n```bash\nscripts/connect-cambium.cmd\n```\n\nIt generates a **status-only** credential, installs it on cambium-remote as\n`STATUS_TOKEN`, verifies the route answers with real counts, and only then sets\n`CAMBIUM_STATUS_URL` here. Nothing to look up or paste.\n\n**Why a second credential rather than cambium's connector URL:** that URL is\ncambium-remote's `AUTH_TOKEN`, which grants `recall` over every promoted item —\non the Worker whose team scope reaches every repo under `TEAM_OWNER`, including\nprivate ones. Copying it here to render three integers would mean a leak of this\nWorker discloses cambium's entire reach. `STATUS_TOKEN` reads the counts and\nnothing else. It is also *generatable*, which is what makes the setup automatic;\n`AUTH_TOKEN` can only ever be re-typed by hand, since Cloudflare stores secrets\nwrite-only.\n\n**Self-hosters must add a service binding.** A Worker **cannot** reach another\nWorker by fetching its `workers.dev` hostname — Cloudflare's edge answers `404`\nand the target never runs, which looks exactly like a rejected token. Add to your\n`wrangler.toml`:\n\n```toml\n[[services]]\nbinding = \"CAMBIUM\"\nservice = \"cambium-remote\"\n```\n\nThis repo declares it only under `[env.production]`, deliberately: a service\nbinding names its target, so declaring it at the top level would break the\none-click deploy for anyone whose account has no `cambium-remote`.\n\nThe panel fails soft. If cambium is slow (10s budget), down, or unwired, the page\nstill renders and says so. Only the Knowledge tab makes that call, so the other\ntabs never pay for it.\n\n### Deploy on push, with no API token\n\n`git push` can deploy the Worker directly, using the wrangler login you already\nhave — no Cloudflare API token, no GitHub secret, no dashboard:\n\n```bash\nscripts/install-deploy-hook.cmd\n```\n\nIt installs a git **pre-push** hook. Deploy first, push second: if the deploy\nfails the push is aborted, so `origin` never receives a commit that could not be\ndeployed. That is the inverse of the failure it replaces — cambium-remote's CI\nwas accepting every merge and deploying none of them, with `main` drifting ahead\nof the running Worker and nothing to show it.\n\nMain only, skips branch deletes, `git push --no-verify` skips it once, `-Remove`\nuninstalls.\n\n**It refuses to install without `-Env` in a repo that has named environments**,\nand that refusal is load-bearing rather than fussy. A bare `wrangler deploy` uses\nthe *top-level* profile — which in this repo is the self-host profile, and that\none deliberately omits `database_id` so Cloudflare provisions a **fresh empty\ndatabase**. A hook installed without `-Env` here would bind the live Worker to an\nempty D1 on the next push. So:\n\n```bash\n# cambium-remote -- no named environments, bare deploy is correct\nscripts/install-deploy-hook.cmd\n\n# a repo whose real deploy lives under [env.production]\nscripts/install-deploy-hook.cmd -Env production\n```\n\nThis repo does not need the hook at all — its GitHub Actions deploy works, and a\nhook would deploy twice per push.\n\n**Why not just fix the CI?** Because that step genuinely cannot be automated.\nGitHub Actions needs `CLOUDFLARE_API_TOKEN`, and minting a Cloudflare API token\nthrough the API requires an existing token carrying *User API Tokens: Edit*.\nWrangler's OAuth login does not have it — its 29 scopes are workers/d1/pages/\nqueues operations plus `account:read`, with nothing token-management related. **No\ncredential on your machine can create that credential.** The paste is Cloudflare's\npermission model, not a gap in the tooling. Deploying locally sidesteps the\nquestion entirely.\n\n### If you want GitHub Actions CI anyway\n\n`connect-cambium` deploys cambium-remote itself when it finds the status route\nmissing, using the wrangler login you already have — so you do **not** need its\nGitHub Actions deploy working for the Knowledge tab to work.\n\nYou only need it if you want cambium-remote to auto-deploy on every push. Its\nworkflow needs two Cloudflare secrets, and an empty one fails **silently**: every\nmerge looks green and deploys nothing.\n\n```bash\nscripts/fix-cambium-ci.cmd\n```\n\n`CLOUDFLARE_ACCOUNT_ID` is read from `wrangler whoami` and set automatically — it\nis an identifier, not a credential; it is in every dashboard URL.\n\n`CLOUDFLARE_API_TOKEN` you paste once, and that step is genuinely irreducible:\ncreating a Cloudflare API token requires an existing token with\n*User API Tokens: Edit*, and wrangler's OAuth login is not one. **No credential on\nyour machine can mint that credential.** Everything around it is automated — the\nbrowser opens on the right page, the token is read without echoing, it is\n**verified against Cloudflare's API before being stored**, both secrets go over\nstdin rather than argv, and the previously failed run is re-triggered so you watch\nit go green instead of taking the script's word for it.\n\n### Set your Worker URL (self-hosters)\n\nNo wrangler command reports the `workers.dev` host — not `whoami`,\n`deployments list`, `versions list`, or `deployments status` — so it lives in\n`package.json`:\n\n```bash\nnode -e \"const p=require('./package.json');p.contextKeeper.workerUrl='https://<worker>.<account>.workers.dev';require('fs').writeFileSync('package.json',JSON.stringify(p,null,2)+'\n')\"\n```\n\nThe setup script reads it **before** installing anything and refuses to run\nwithout it. That ordering is deliberate: a token installed with no URL to put it\nin is unrecoverable, since Cloudflare cannot read a secret back.\n\n### Platform support, honestly\n\n| script | Windows | macOS / Linux |\n|---|---|---|\n| `set-view-token` | `.cmd` / `.ps1` | **`.sh`** |\n| `connect-cambium` | `.cmd` / `.ps1` | not ported — see below |\n| `install-deploy-hook` | `.cmd` / `.ps1` | not ported — see below |\n| `fix-cambium-ci` | `.cmd` / `.ps1` | not ported — see below |\n\nThe three that aren't ported are thin wrappers around a handful of commands, so\nthe manual equivalents are short. **Connect cambium:**\n\n```bash\nTOKEN=$(head -c 32 /dev/urandom | base64 | tr '+/' '-_' | tr -d '=\n')\nprintf '%s' \"$TOKEN\" | (cd ../cambium-remote && npx wrangler secret put STATUS_TOKEN)\n# wait ~60s for the new version to roll out, then check it answers with counts:\ncurl -s \"https://cambium-remote.<account>.workers.dev/status/$TOKEN\" | head -c 200\nprintf '%s' \"https://cambium-remote.<account>.workers.dev/status/$TOKEN\"   | npx wrangler secret put CAMBIUM_STATUS_URL --env production\n```\n\n**Deploy on push** — write `.git/hooks/pre-push` in the target repo, LF endings,\n`chmod +x`, running `npx wrangler deploy` (add `--env <name>` if that repo has\nnamed environments — a bare deploy there targets the self-host profile and will\nbind your live Worker to a fresh empty database).\n\n**Fix the CI** — `gh secret set CLOUDFLARE_ACCOUNT_ID` and\n`gh secret set CLOUDFLARE_API_TOKEN` against the repo, reading each from stdin.\n\n### Editing the setup scripts\n\nThey target **Windows PowerShell 5.1** — the version that ships with Windows and\nthe one `.cmd` launches. Five things there are load-bearing and look like they\ncould be modernised:\n\n- `RNGCryptoServiceProvider`, not `RandomNumberGenerator::Fill` — the latter is\n  .NET Core only and throws.\n- Manual `WebException` status extraction, not `-SkipHttpErrorCheck` — PowerShell 7 only.\n- No `??`, `?.`, or ternaries — all PowerShell 7 only, and a **parse error** here.\n- Every wrangler call goes through `Invoke-Wrangler`. On 5.1, `2>&1` on a *native*\n  command wraps each stderr line in an ErrorRecord, and under\n  `$ErrorActionPreference = 'Stop'` the first is **terminating** — so an ordinary\n  wrangler notice kills the run.\n- Confirmations gate on `[Console]::IsInputRedirected`, never\n  `[Environment]::UserInteractive` (which is always true), and cast `Read-Host` to\n  `[string]` before matching — `$null -notmatch '...'` evaluates to *empty*, not\n  `$true`, so the obvious guard fails **open**.\n\nEvery run writes a scrubbed log (`.view-setup.log`, `.cambium-setup.log`) with the\ntoken masked, so a failure can be read after the window closes.\n\n## ⚠️ Security: the connector URL is a credential\n\nThe URL you paste into Claude **embeds `AUTH_TOKEN`** as its last path segment.\nAnyone who has the full `…/mcp/<AUTH_TOKEN>` URL can read and write your entire\nstore. Treat it exactly like a password:\n\n- Don't share it, screenshot it, or paste it anywhere it could be logged.\n- Requests to any other path, or with the wrong token, get a bare `404` with no\n  detail (a valid token used with a non-POST method gets `405`).\n- **To rotate:** change `AUTH_TOKEN` in the Cloudflare dashboard (Step 2). This\n  **immediately invalidates every old URL** — any connector using the previous\n  token starts getting `404`s until you update it in claude.ai (Step 3) with the new\n  value.\n\nEverything in this section applies to the **view URL** too, with one difference in\nyour favour: `VIEW_TOKEN` can only read. A leaked view URL exposes every decision\nsummary in every project on the instance, which may well be the more sensitive half\n— but it cannot write, deprecate, or delete anything. That is the entire reason the\ntwo are separate credentials rather than one.\n\n### Why the token is in the URL path, and what that costs you\n\nThis is a **deliberate design choice, not an oversight**. claude.ai custom\nconnectors do not reliably send custom headers, so an `Authorization:` header —\nthe obvious alternative — cannot be depended on. Putting the credential in the\npath is what makes the connector work at all.\n\nBe clear about the price, because it is not the same as a header:\n\n- **URLs get recorded in places request bodies never do.** Browser history,\n  shell history, proxy and CDN access logs, crash reports, bug reports,\n  screenshots, \"copy link\" buttons, and **agent session transcripts**. During\n  the audit that produced this section, the connector URLs for these Workers\n  were found in **~54 occurrences across 13 local session transcripts** on a\n  single machine — none of them pasted deliberately; they were simply part of\n  the tool configuration an agent echoed back.\n- **The Worker itself does not log it.** Every log line records the route as\n  `/mcp/***`. The leak surface is everything *around* the Worker, which is\n  exactly what you cannot audit.\n- **A leaked token is full access, with no second factor and no per-caller\n  identity.** There is nothing to revoke except the token itself, and no log\n  that will tell you who used it.\n\n**Practical guidance:**\n\n1. **Rotate on a schedule**, not just on suspicion — assume the URL has been\n   recorded somewhere you don't control. Rotation is cheap: change `AUTH_TOKEN`,\n   update the connector.\n2. **Rotate immediately** if you've shared a terminal recording, a transcript,\n   a screen capture, or a bug report from a machine where the connector is\n   configured.\n3. Use a **long random token** (32+ bytes, e.g. `openssl rand -hex 32`). The\n   comparison is constant-time in both content *and* length, so length is not\n   observable — but entropy is still your only defence against guessing.\n4. If you ever get the chance to use a header or OAuth instead, **take it**.\n   This tradeoff is forced by the client, not preferred.\n\n---\n\n## Tools\n\nEvery tool takes an optional `project`; if omitted it falls back to the configured\n`default_project` (set it once with `config` — `op='set'`, key `default_project`).\n\nThe unified tools (`config`, `record_entry`) are the current surface; the older\nper-operation tools remain as **deprecated aliases** so existing callers keep\nworking. New work should prefer the unified tools.\n\n| Tool | Purpose |\n| --- | --- |\n| `config` | Read or write config: `op='get'` reads a key, `op='set'` writes it (`value` required). Use key `default_project` (global scope, no `project`) to pick the project used when a call omits `project`. |\n| `set_config` / `get_config` | **Deprecated** aliases for `config(op='set')` / `config(op='get')`. |\n| `record_entry` | Unified write: record a `decision`, `constraint`, or `pipeline`. Required field depends on kind — decision needs `summary`, constraint needs `rule`, pipeline needs `name`. |\n| `record_decision` | **Deprecated** alias for `record_entry(kind='decision')`: `summary`, `problem`, `why_chosen`, `what_we_tried`, `tradeoffs`, `tags`. |\n| `record_constraint` | **Deprecated** alias for `record_entry(kind='constraint')`: a rule that must hold — `rule`, `reason`, `tags`. |\n| `record_pipeline` | **Deprecated** alias for `record_entry(kind='pipeline')`: a reusable process — `name`, `purpose`, `steps` (extra fields kept verbatim). |\n| `get_context` | Relevance-ranked retrieval for a query (keyword scoring; excludes deprecated unless `include_deprecated`). An entry that superseded something carries a one-line `predecessor` -- what the prior entry said and why it changed -- byte-identical to the local server's, so history reads the same over either transport. |\n| `query_entries` | Structured filters: `id`, `kind`, `tags` (all must match), `status` (`active`/`deprecated`/`all`), free `text`, and `limit`. |\n| `get_project_summary` | One-call orientation: entry counts by kind and status, the ids present, the active constraints (compact), and the most recent decisions. |\n| `list_projects` | The org registry: every project with entries, plus per-project active counts (decisions/constraints/pipelines), active/deprecated totals, and last-updated time. Enumerates the whole org in one call — discover exact, case-sensitive project names instead of guessing. |\n| `update_entry` | Merge `patch` fields into an entry's payload; optionally change `status`. |\n| `deprecate_entry` | Mark deprecated, optionally linking `superseded_by` and recording a `reason` (the reason is what the predecessor line quotes). |\n| `reload_constraints` | Compact list of the active constraints. |\n| `prune_stale` | Delete old deprecated entries (**dry run by default**; pass `dry_run=false`). |\n| `verify_quality` | Flag entries missing rationale-bearing fields. |\n| `export_markdown` | Render entries as a DECISIONS.md-style document. |\n| `import_entries` | Bulk import from the local JSON store format (preserves ids and lifecycle status including `superseded`, reports collisions, never overwrites). |\n| `upsert_entries` | Bulk upsert in the local store format — the mirror-sync path. New ids are inserted; an existing id is replaced only when the incoming `updated_at` is strictly newer (last-writer-wins by timestamp), else skipped. Carries edits and deprecations between mirrored stores; never deletes. |\n\n### Entry conventions\n\n- **Decisions** use `summary`, `problem`, `why_chosen`, `what_we_tried`,\n  `tradeoffs`, `tags`. The deprecated `rationale` field is accepted on input and\n  mapped to `why_chosen` when `why_chosen` is absent.\n- **Constraints** use `rule`, `reason`, `tags`.\n- **Pipelines** use `name`, `purpose`, `steps`, plus any extra fields you pass.\n- **ids** are per project+kind: `dec-001`, `pipe-003`, `con-012`. Because the same\n  id recurs across projects, the D1 primary key is composite `(project, id)`.\n\n---\n\n## For maintainers / contributors\n\nEverything above is for self-hosters. This section is for working on the code\nitself.\n\n### Config layout: how one repo serves both the button and CI\n\n`wrangler.toml` has two profiles:\n\n- **Default (top level)** — the D1 binding is declared **without** a `database_id`.\n  This is what the Deploy button, `wrangler dev`, and the local test suite use. With\n  no id, Cloudflare auto-provisions a fresh database for each self-hoster.\n- **`[env.production]`** — pins the maintainer's real `database_id` and the Worker\n  `name`. The maintainer's CI deploys with `wrangler deploy --env production` so it\n  keeps hitting the same database and the same URL. Self-hosters never touch this\n  env.\n\nThe **cambium service binding lives only in `[env.production]`**, and that split is\nload-bearing rather than tidy. A service binding names its target Worker, so a\ntop-level `[[services]] service = \"cambium-remote\"` would make the one-click deploy\nfail in any account that has no such Worker — which is every account but the\nmaintainer's. Anything that names another Worker, another database by id, or\nanother account belongs in the named env for the same reason.\n\nNamed environments **inherit nothing**. Every binding the production deploy needs\nhas to be repeated under `[env.production.*]`, including `[observability]`. A\nbinding that exists only at the top level is silently absent from the env CI\nactually deploys.\n\n### Deploy pipeline (maintainer only)\n\n`.github/workflows/deploy.yml` runs on push to `main`, and is gated with\n`if: github.repository == 'jarmstrong158/context-keeper-remote'` so forks (which\ndeploy via Workers Builds instead) don't run failing Actions. Steps: checkout →\nNode 22 (Wrangler needs ≥ 22) → `npm ci` → `npm test` → `wrangler deploy --env\nproduction`. Tests gate the deploy. It reads two GitHub repo secrets,\n`CLOUDFLARE_API_TOKEN` (needs **Workers Scripts: Edit**) and `CLOUDFLARE_ACCOUNT_ID`\n— **distinct** from the Worker's own `AUTH_TOKEN`.\n\n### Local development\n\nNo network and no Cloudflare credentials required — tests run against a local\nworkerd D1 via `@cloudflare/vitest-pool-workers`. Requires **Node ≥ 22**.\n\n```bash\nnpm install\nnpm test          # vitest: migrations, cold-start, CRUD, id sequencing, auth, import, ...\nnpm run typecheck # tsc --noEmit\n```\n\n### Live smoke test\n\nAfter a deploy, from any machine with network access:\n\n```bash\nWORKER_URL=\"https://context-keeper-remote.<subdomain>.workers.dev/mcp/<AUTH_TOKEN>\" \\\n  node scripts/smoke-test.mjs\n```\n\nRuns `initialize → tools/list → record_decision → query_entries` against the live\nworker.\n\n### Layout\n\n```\nsrc/index.ts             fetch handler: token check -> MCP dispatch (schema ensured lazily on first tools/call, not on the handshake)\nsrc/mcp.ts               stateless Streamable HTTP MCP server (createMcpHandler)\nsrc/db.ts                D1 access + runtime migration runner + id generation\nsrc/entries.ts           payload normalization, insert-with-retry, keyword scoring\nsrc/tools/*.ts           one module per tool group\nsrc/view.ts              the phone view: shell, tabs, knowledge panel, dispatch on ?e/?p/?q/?t\nsrc/detail.ts            entry detail, project drill-down, search, supersession trail\nsrc/health.ts            quality flags + the Projects and Health tables\nsrc/install.ts           enrolment cookie, web app manifest, home-screen icon\nsrc/icon-data.ts         GENERATED by scripts/make-icon.mjs -- do not hand-edit\nschema.sql               reference copy of the DDL the migration runner embeds\nwrangler.toml            default (auto-provision) + [env.production] (pinned) config\n.github/workflows/deploy.yml   test-then-deploy on push to main (maintainer repo)\nscripts/smoke-test.mjs   live JSON-RPC round-trip check\nscripts/set-view-token.*  create VIEW_TOKEN, verify, QR, save the URL  (.cmd = double-click)\nscripts/connect-cambium.* generate STATUS_TOKEN on cambium-remote and wire it here\nscripts/make-icon.mjs     regenerate the home-screen PNG (npm run make-icon)\ntest/                    vitest suite (local workerd D1, no network)\n```\n\n### Troubleshooting the maintainer deploy\n\n| Symptom in the Actions log | Cause | Fix |\n| --- | --- | --- |\n| `Wrangler requires at least Node.js v22.0.0` | Node < 22 | Already set to Node 22 in `deploy.yml`. |\n| `it's necessary to set a CLOUDFLARE_API_TOKEN environment variable` | Deploy secrets missing | Add both GitHub repo secrets. |\n| `No route for that URI [code: 7000]` / `object identifier is invalid [code: 7003]` | API token lacks Workers permission, or wrong `CLOUDFLARE_ACCOUNT_ID` | Use an \"Edit Cloudflare Workers\" token; confirm the account id. |\n| Deploys succeed but every call returns `404` | Worker `AUTH_TOKEN` not set, or the URL's token doesn't match it | Set/verify `AUTH_TOKEN` in the Cloudflare dashboard. |\n\n---\n\n## Related\n\n- [context-keeper](https://github.com/jarmstrong158/context-keeper) — the local stdio original this Worker hosts as a remote transport.\n- [xylem](https://github.com/jarmstrong158/xylem) — the stack this is part of.\n",
  "bytes": 31487,
  "sha": "aef6a103f0a4c93df0eaea982f13b967b57ad78c43f94590429645193ee5a264",
  "repo_slug": "jarmstrong158/context-keeper-remote",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_jarmstrong158_context_keeper_r_dcc44d0f/readme"
}