# @conxt/mcp

**Local-first MCP server for governed AI memory.** Your agents *propose* memories;
*you* approve them; only approved memories are ever recalled. Runs standalone with
no account — optionally syncs to [Conxt](https://conxt.dev) cloud for team memory.

Implements the open [Governed Memory Record](https://conxt.dev) format.

## Quickstart

Point your IDE at it — no install, no signup:

**Cursor** (`~/.cursor/mcp.json`)
```json
{ "mcpServers": { "conxt": { "command": "npx", "args": ["-y", "@conxt/mcp"] } } }
```

**Claude Code**
```bash
claude mcp add conxt -- npx -y @conxt/mcp
```

**Claude Desktop** → Settings → Developer → Edit Config: same block as Cursor.

That's it. Memory lives in `~/.conxt/memory.json` on your machine.

## The tools

| Tool | Who calls it | What it does |
|---|---|---|
| `remember` | agent | Propose a memory (**pending** — doesn't govern yet) |
| `recall` | agent | Recall **approved** memories for a query |
| `list_pending` | agent/you | See what's awaiting approval |
| `approve` | **you** | Approve a pending memory → it now governs |
| `reject` / `forget` | you | Decline or delete |

The rule that makes it *governed*: **an agent can propose, but only a human can
approve** — and `recall` never returns anything that isn't approved.

## Human approval from the terminal

```bash
npx @conxt/mcp pending          # what's waiting
npx @conxt/mcp approve <id>     # approve it
npx @conxt/mcp reject <id>
npx @conxt/mcp list
npx @conxt/mcp path             # where the store lives
```

Prefer zero friction for solo use? Set `CONXT_AUTO_APPROVE=1` and everything you
`remember` is approved on the spot.

## Cloud mode (optional)

Local is always the source of truth. Set both env vars to also push **approved**
records to your Conxt workspace for shared, governed team memory:

```
CONXT_API_KEY=...      CONXT_API_URL=https://...
```

A sync failure never affects your local memory.

## Config

| Env | Default | Purpose |
|---|---|---|
| `CONXT_STORE` | `~/.conxt/memory.json` | Local store path |
| `CONXT_AUTO_APPROVE` | off | Approve on `remember` (solo mode) |
| `CONXT_API_KEY` / `CONXT_API_URL` | unset | Optional cloud sync |

## Develop

```bash
npm install && npm run build && node dist/index.js
```

## License

MIT.

## Publishing

CI (`.github/workflows/ci.yml`) builds and runs the governance smoke test on every
push. To release to npm:

1. On npmjs.com, confirm you own the **`@conxt`** scope — or rename the package to
   unscoped `conxt-mcp` in `package.json`.
2. Add an **`NPM_TOKEN`** (Automation token) as a repository secret
   (Settings → Secrets and variables → Actions).
3. Cut a release:
   ```bash
   npm version patch      # or minor / major — creates a v* tag
   git push --follow-tags
   ```
   The `publish` workflow builds, smoke-tests, and runs `npm publish --access public`.

Or publish manually:
```bash
npm install && npm run build && npm login && npm publish --access public
```