# Project Memory MCP

A minimal remote MCP server that shares durable project knowledge between coding agents. It runs as a stateless Cloudflare Worker, stores data in Turso, and authenticates clients with scoped Bearer tokens.

## Setup

Requires Node.js 20+ and a Turso database.

```bash
npm install
cp .dev.vars.example .dev.vars
```

Set `TURSO_DATABASE_URL` and `TURSO_AUTH_TOKEN` in `.dev.vars`. For scripts, export the same variables in your shell; never commit them.

```bash
npm run migrate
npm run create-token -- --name "Codex MacBook" --projects '*'
npm run dev
```

Health check: `GET http://localhost:8787/health`. MCP endpoint: `http://localhost:8787/mcp` with `Authorization: Bearer mem_...`.

## Tools

- `project_create`
- `project_context`
- `memory_search`
- `memory_get`
- `decision_save`
- `bug_save`
- `memory_supersede`
- `memory_recent`
- `memory_update_metadata`

`decision_save` and `bug_save` reject exact duplicate titles and warn about likely conflicts. Review a warning and use `memory_supersede` when a technical fact changed; use `confirm_conflict: true` only when both active memories are intentionally valid.

`memory_supersede` atomically marks the old memory `superseded` and creates an active successor linked through `supersedes_id`. Search and project context return active memories only, while `memory_get` can still retrieve an archived or superseded memory by ID for history.

`memory_recent` returns compact changes from the last several days. `memory_update_metadata` can change only summary, importance, tags, and active/archive status; technical content remains immutable.

The server does not call an LLM or embedding API and does not automatically save conversations.

## Test and deploy

```bash
npm test
npm run typecheck
npx wrangler secret put TURSO_DATABASE_URL
npx wrangler secret put TURSO_AUTH_TOKEN
npm run deploy
```

Run `npx @modelcontextprotocol/inspector@latest`, select Streamable HTTP, enter the deployed `/mcp` URL, and add the Bearer token header.

## Client configuration

Claude Code (native remote HTTP):

```bash
claude mcp add --transport http --header "Authorization: Bearer mem_your_token" project-memory https://your-worker.workers.dev/mcp
```

Codex (`~/.codex/config.toml`):

```toml
[mcp_servers.project-memory]
url = "https://your-worker.workers.dev/mcp"
bearer_token_env_var = "PROJECT_MEMORY_TOKEN"
```

Set `PROJECT_MEMORY_TOKEN` in the Codex environment. Use a separate token per client/machine so one credential can be revoked independently.