context-keeper-remote

# context-keeper-remote

[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/jarmstrong158/context-keeper-remote)

_Part of the [xylem](https://github.com/jarmstrong158/xylem) stack._

A remote [MCP](https://modelcontextprotocol.io) server on Cloudflare Workers that
exposes context-keeper's rationale store (decisions, pipelines, constraints) over
Streamable HTTP. It works as a **claude.ai custom connector**, including on mobile,
so your project's decisions and constraints are available from any Claude session —
no PC left running, no tunnel.

**Self-host your own copy in a few clicks with the button above** — Cloudflare
copies this repo into your GitHub account, creates a fresh D1 database for you, and
deploys the Worker. Then you add one secret and paste a URL into Claude. Full
walkthrough below; every step is a click, no command line anywhere.

> The maintainer's own instance runs at
> `https://context-keeper-remote.jarmstrong158.workers.dev`. Yours will be at your
> own subdomain after you deploy.

### Why it's built this way

- **Worker, not tunnel** — no "PC must be on" dependency.
- **D1, not KV** — row-level writes and `WHERE` queries; two writers (desktop +
  mobile) don't clobber each other the way whole-file JSON read-modify-write does.
- **Stateless handler, no Durable Objects** — the tools are stateless RPCs against
  D1, so the Worker runs on the Cloudflare **free plan**.
- **Secret-path auth** — claude.ai custom connectors don't reliably send custom
  bearer headers, so the token is the last path segment of the URL. The URL is the
  credential.
- **Self-migrating** — the Worker creates its own D1 schema at runtime, so a
  brand-new empty database needs **no manual SQL** (verified by a cold-start test).

---

## Self-host it (one-click, no command line)

### Step 1 — Click "Deploy to Cloudflare"

Click the **Deploy to Cloudflare** button at the top of this page. Cloudflare will:

1. Ask you to authorize GitHub and pick an account — it **copies this repo into
   your GitHub account** (you get your own repo).
2. **Automatically create a new D1 database** in your Cloudflare account and bind it
   to the Worker. (This works because the Worker's config declares the database
   binding without a hard-coded id, so Cloudflare provisions a fresh one for you.)
3. Set up **Workers Builds** so every push to your new repo redeploys automatically.
4. Build and deploy the Worker.

When it finishes, your Worker is live at
`https://context-keeper-remote.<your-subdomain>.workers.dev`. Note that URL — you'll
need it in Step 3. (You can always find it under **Workers & Pages** in the
dashboard.)

> Nothing to configure in the repo, and **no SQL to run** — the database starts
> empty and the Worker creates its tables on the first request.

### Step 2 — Add the `AUTH_TOKEN` secret (Cloudflare dashboard)

The Worker refuses every request until it has an auth token, so set one:

1. Cloudflare dashboard → **Workers & Pages** → your **context-keeper-remote**
   Worker.
2. **Settings** → **Variables and Secrets** → **Add**.
3. Type: **Secret**. Name: `AUTH_TOKEN`. Value: a long random string (32+ characters
   — treat it like a password). Save/Deploy.

That value is your connector's password. Keep it somewhere safe; you'll paste it in
the next step.

<details>
<summary>Also deploying the companion <code>agentsync-remote</code> worker?</summary>

`agentsync-remote` uses the same `AUTH_TOKEN` scheme, and **additionally** needs, in
*its* Worker's **Variables and Secrets**:

- a **Secret** named `GH_PAT` — a GitHub personal access token, and
- a **Variable** named `REPO` — set to the `owner/repo` it should sync.

Those two do **not** apply to context-keeper-remote (this repo) — it only needs
`AUTH_TOKEN`. See the `agentsync-remote` README for its specifics.
</details>

### Step 3 — Add the custom connector in claude.ai

1. claude.ai → **Settings** → **Connectors** → **Add custom connector**.
2. Paste your Worker URL with the token as the final path segment:

   ```
   https://context-keeper-remote.<your-subdomain>.workers.dev/mcp/<AUTH_TOKEN>
   ```

   Replace `<your-subdomain>` with your Worker's subdomain (Step 1) and
   `<AUTH_TOKEN>` with the exact value you set (Step 2).
3. Save. The tools (`record_entry`, `get_context`, `query_entries`, …) are now
   available in your Claude sessions.

**Check it works:** ask Claude to call `get_project_summary`. If it answers, the
whole chain (deploy → auto-provisioned D1 → auto-migration → auth) is working.

### Step 4 — Migrate existing local data (optional)

If you already run local context-keeper, ask Claude (with the connector enabled) to
call **`import_entries`**, pasting each file's contents:

- `decisions.json` → `import_entries(project, kind="decision", entries=[...])`
- `pipelines.json` → `import_entries(project, kind="pipeline", entries=[...])`
- `constraints.json` → `import_entries(project, kind="constraint", entries=[...])`

Incoming ids are preserved; existing ids are reported, never overwritten.

---

## ⚠️ Security: the connector URL is a credential

The URL you paste into Claude **embeds `AUTH_TOKEN`** as its last path segment.
Anyone who has the full `…/mcp/<AUTH_TOKEN>` URL can read and write your entire
store. Treat it exactly like a password:

- Don't share it, screenshot it, or paste it anywhere it could be logged.
- Requests to any other path, or with the wrong token, get a bare `404` with no
  detail (a valid token used with a non-POST method gets `405`).
- **To rotate:** change `AUTH_TOKEN` in the Cloudflare dashboard (Step 2). This
  **immediately invalidates every old URL** — any connector using the previous
  token starts getting `404`s until you update it in claude.ai (Step 3) with the new
  value.

---

## Tools

Every tool takes an optional `project`; if omitted it falls back to the configured
`default_project` (set it once with `config` — `op='set'`, key `default_project`).

The unified tools (`config`, `record_entry`) are the current surface; the older
per-operation tools remain as **deprecated aliases** so existing callers keep
working. New work should prefer the unified tools.

| Tool | Purpose |
| --- | --- |
| `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`. |
| `set_config` / `get_config` | **Deprecated** aliases for `config(op='set')` / `config(op='get')`. |
| `record_entry` | Unified write: record a `decision`, `constraint`, or `pipeline`. Required field depends on kind — decision needs `summary`, constraint needs `rule`, pipeline needs `name`. |
| `record_decision` | **Deprecated** alias for `record_entry(kind='decision')`: `summary`, `problem`, `why_chosen`, `what_we_tried`, `tradeoffs`, `tags`. |
| `record_constraint` | **Deprecated** alias for `record_entry(kind='constraint')`: a rule that must hold — `rule`, `reason`, `tags`. |
| `record_pipeline` | **Deprecated** alias for `record_entry(kind='pipeline')`: a reusable process — `name`, `purpose`, `steps` (extra fields kept verbatim). |
| `get_context` | Relevance-ranked retrieval for a query (keyword scoring; excludes deprecated unless `include_deprecated`). |
| `query_entries` | Structured filters: `id`, `kind`, `tags` (all must match), `status` (`active`/`deprecated`/`all`), free `text`, and `limit`. |
| `get_project_summary` | One-call orientation: entry counts by kind and status, the ids present, the active constraints (compact), and the most recent decisions. |
| `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. |
| `update_entry` | Merge `patch` fields into an entry's payload; optionally change `status`. |
| `deprecate_entry` | Mark deprecated, optionally linking `superseded_by`. |
| `reload_constraints` | Compact list of the active constraints. |
| `prune_stale` | Delete old deprecated entries (**dry run by default**; pass `dry_run=false`). |
| `verify_quality` | Flag entries missing rationale-bearing fields. |
| `export_markdown` | Render entries as a DECISIONS.md-style document. |
| `import_entries` | Bulk import from the local JSON store format (preserves ids, reports collisions, never overwrites). |
| `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. |

### Entry conventions

- **Decisions** use `summary`, `problem`, `why_chosen`, `what_we_tried`,
  `tradeoffs`, `tags`. The deprecated `rationale` field is accepted on input and
  mapped to `why_chosen` when `why_chosen` is absent.
- **Constraints** use `rule`, `reason`, `tags`.
- **Pipelines** use `name`, `purpose`, `steps`, plus any extra fields you pass.
- **ids** are per project+kind: `dec-001`, `pipe-003`, `con-012`. Because the same
  id recurs across projects, the D1 primary key is composite `(project, id)`.

---

## For maintainers / contributors

Everything above is for self-hosters. This section is for working on the code
itself.

### Config layout: how one repo serves both the button and CI

`wrangler.toml` has two profiles:

- **Default (top level)** — the D1 binding is declared **without** a `database_id`.
  This is what the Deploy button, `wrangler dev`, and the local test suite use. With
  no id, Cloudflare auto-provisions a fresh database for each self-hoster.
- **`[env.production]`** — pins the maintainer's real `database_id` and the Worker
  `name`. The maintainer's CI deploys with `wrangler deploy --env