saihm-mcp-server-pro

# @saihm/mcp-server-pro

[![npm version](https://img.shields.io/npm/v/@saihm/mcp-server-pro.svg)](https://www.npmjs.com/package/@saihm/mcp-server-pro)
[![license](https://img.shields.io/npm/l/@saihm/mcp-server-pro.svg)](./LICENSE)

Production thin-client for **SAIHM non-custodial memory**.

`SaihmProClient` seals every cell **on the client** with [`@saihm/client-pro`](https://www.npmjs.com/package/@saihm/client-pro), then POSTs the resulting ciphertext to the blind SAIHM `/mcp` endpoint. The endpoint stores, anchors, shares, and meters over ciphertext — it never holds your keys and cannot read your memory. Your master secret, key-encryption key, and plaintext never leave this process.

- **Seal before send** — `remember` encrypts client-side; `recall` decrypts client-side.
- **Post-quantum** — ML-DSA-65 identity/signing, ML-KEM-768 authenticated sharing (via `@saihm/client-pro`).
- **Same transport as the standards client** — `POST {method, params}` + `Authorization: Bearer <JWT>`; the endpoint binds your tenant from the JWT. HTTPS-only (loopback `http` permitted for local dev).
- **Crypto-shred erasure** — `forget` destroys the endpoint-side wrapped DEK, rendering the cell undecryptable (GDPR Art. 17).

> **Key loss is unrecoverable by design.** If you lose your master secret you lose your KEK, and no one — including SAIHM — can open your cells. Back it up securely.

## See it run

- **Live cross-model demos** — offline, ~1 min each, no account: <https://citw2.github.io/saihm-demos/>. Ground a memory you own in Claude, GPT, DeepSeek, Qwen, Kimi, or GLM, then prove you can erase it. `demo-claude-code` runs a stdio MCP server exactly like this one for Claude Code and Cursor.
- **Token benchmark** — recalling a bounded set of memory cells instead of re-sending the transcript cut input tokens by **62.8%–85.9%** (up to ~86%) across a realistic multi-session task; open, offline, reproducible: <https://github.com/citw2/saihm-token-benchmark>.

## Tool reference

| Tool | Title | Behavior |
|---|---|---|
| `saihm_remember` | Remember | seals + writes a memory cell (client-side) |
| `saihm_recall` | Recall | read-only; opens your cells — or a cell shared to you — client-side |
| `saihm_forget` | Forget (GDPR erasure) | **destructive** — irreversible erasure |
| `saihm_status` | Status | read-only |
| `saihm_share` | Share | end-to-end-authenticated grant |
| `saihm_revoke_share` | Revoke share | withdraws a grant |
| `saihm_governance_propose` | Propose (governance) | opens a proposal |
| `saihm_governance_vote` | Vote (governance) | casts a vote |

Each tool carries MCP annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`) and a human-readable `title`, so MCP hosts can gate confirmations and agents can select the right tool at reasoning time.

## Install

```sh
npm install @saihm/mcp-server-pro
```

## Run as an MCP server

The package ships a stdio MCP server. Point your MCP host (Claude Desktop,
Claude Code, …) at it — paste this **once**:

```jsonc
{
  "mcpServers": {
    "saihm": {
      "command": "npx",
      "args": ["-y", "@saihm/mcp-server-pro"],
      "env": {
        "SAIHM_ENDPOINT_URL": "https://saihm.coti.global/mcp",
        "SAIHM_MASTER_SECRET_HEX": "<your 64+ hex master secret>",
        "SAIHM_TIER": "PRO",
        "SAIHM_PAYMENT_METHOD": "stripe",
      },
    },
  },
}
```

With no `SAIHM_AUTH_HEADER`, the server **self-onboards**: it mints and
auto-refreshes its own short-lived access token from your master secret, so
there is no token to paste or re-paste. Eight tools are exposed
(`saihm_remember`, `saihm_recall`, `saihm_forget`, `saihm_status`,
`saihm_share`, `saihm_revoke_share`, `saihm_governance_propose`,
`saihm_governance_vote`).

### Zero-config free start — prompt your agent to "Join SAIHM"

The easiest start needs **no master secret and no card**. Self-join is on by
default, so this is the whole configuration:

```jsonc
{
  "mcpServers": {
    "saihm": {
      "command": "npx",
      "args": ["-y", "@saihm/mcp-server-pro"],
      "env": {
        "SAIHM_ENDPOINT_URL": "https://saihm.coti.global/mcp",
      },
    },
  },
}
```

Then, in your agent session, just say:

> Join SAIHM.

The agent calls the `saihm_join` tool, which **generates your identity on this
device** (a 32-byte master secret written mode-600 to `~/.saihm/free-identity.key`)
and hands back a one-time device sign-in — open the link, enter the short code,
approve. That step confirms you're a unique person; SAIHM never sees or stores the
token. When it returns, your **free**, non-custodial memory is live and the other
tools work. The key persists on this device, so your next session resumes with
your memory intact.

`saihm_join` is a one-time onboarding affordance, not a ninth protocol tool. It
is registered by default; set `SAIHM_SELF_JOIN=0` to suppress it and expose only
the canonical eight. Because your master secret is generated
locally and never leaves the process, **back up `~/.saihm/free-identity.key` — if
you lose it, no one (including SAIHM) can open your cells.**

### Start free

**The simplest way: just ask your agent to "Join SAIHM."** Self-join is on by
default, so the `saihm_join` tool is already there — it generates your key on
this machine, starts the sign-in, and activates the free trial for you. No
master secret to invent, no env vars, no website visit.

To do it yourself from a shell instead, generate a master secret first — it
never leaves your machine, and it is the only key to your memory:

```sh
openssl rand -hex 32 > saihm-master.key && chmod 600 saihm-master.key
```

Then activate. Prove you're a unique person once via a GitHub device sign-in;
your memory is then bound to your own key for life:

```sh
SAIHM_ENDPOINT_URL=https://saihm.coti.global/mcp \
SAIHM_MASTER_SECRET_FILE=./saihm-master.key \
SAIHM_TIER=FREE \
  npx -y @saihm/mcp-server-pro free-join
```

Open the printed link, enter the short code, approve. SAIHM never sees or stores
the GitHub token — the sign-in stays in your browser and the token is
server-ephemeral. When it returns, start the server normally (drop `free-join`)
and it self-onboards free.

The free trial is for testing on real infrastructure: a fixed, one-time
allowance of writes, reads, and shares that never resets or refills. **No card,
and nothing to cancel** — it is not an auto-renewing subscription. The client
shows your remaining balance and warns you as you approach it, so nothing fails
by surprise.

**Upgrade any time — same key, same memories:**

```sh
SAIHM_ENDPOINT_URL=https://saihm.coti.global/mcp \
SAIHM_MASTER_SECRET_HEX=<your 64+ hex master secret> \
SAIHM_TIER=FREE \
  npx -y @saihm/mcp-server-pro upgrade PRO
```

This prints a monthly checkout link bound to your identity; billing attaches to
the same key, so every memory you already have persists. Pay, switch your config
to the paid tier, and start the server normally.

### Self-serve join

To subscribe an identity from the command line instead of the website, run the
one-off `join` command with the same env:

```sh
SAIHM_ENDPOINT_URL=https://saihm.coti.global/mcp \
SAIHM_MASTER_SECRET_HEX=<your 64+ hex master secret> \
SAIHM_TIER=PRO SAIHM_PAYMENT_METHOD=stripe \
  npx -y @saihm/mcp-server-pro join
```

It prints a Stripe checkout link bound to your identity. Pay in a browser, then
start the server normally (drop `join`) — it connects automatically. Keep
`SAIHM_MASTER_SECRET_HEX` safe: it is the only key to your memory and cannot be
recovered.

## Use as a library

```ts
import { SaihmProClient } from '@saihm/mcp-server-pro';

// Boot from env: SAIHM_ENDPOINT_URL, SAIHM_MASTER_SECRET_HEX
//   self-onboard (recommended): + SAIHM_PAYMENT_METHOD + SAIHM_TIER (omit SAIHM_AUTH_HEADER)
//   static token (advanced):    + SAIHM_AUTH_HEADER="Bearer <JWT>"
//   (optional: SAIHM_SEQ_STATE_PATH)
const saihm = SaihmProClient.bootFromEnv();

// Store — encrypted before it leaves the process.
const { cellId } = await saihm.remember('remember this');

// Recall — decrypted after it returns.
const cell = await saihm.recallOne(cellId);
console.log(cell?.plaintext); // 'remember this'

// Recall everything (client-side keyword filter; the endpoint has no plaintext to filter on).
const matches = await saihm.recall('this');

// Update an existing cell (a fresh monotonic sequence is issued automatically).
await saihm.remember('new contents', { cellId });

// Forget — crypto-shred.
await saihm.forget(cellId);

// Share a cell with another agent, end-to-end authenticated. Pin the grantee's agentIdHash
// out-of-band; the library rejects directory key-substitution.
await saihm.share({
  cellId,
  recipientRecord, // the grantee's published identity record (hex)
  recipientPinnedAgentIdHashHex, // pinned out-of-band
});
await saihm.revokeShare(cellId, recipientPinnedAgentIdHashHex);

// Read a cell another agent shared TO you (the recipient side of `share`). Pin the
// sharer's agentIdHash out-of-band; the library verifies the sharer's signature and
// returns null when there is no live grant (e.g. revoked, or the sharer crypto-shredded it).
const shared = await saihm.recallShared({
  sharerPinnedAgentIdHashHex, // the sharer's agentIdHash, pinned out-of-band
  sharerRecord, // the sharer's published identity record (hex)
  cellId,
});
console.log(shared?.plaintext);

// Operator-observable metadata only (no plaintext).
const status = await saihm.status();
```

The derived `saihm.agentIdHash` is the `sub` the endpoint binds your tenant to — when self-onboarding the client proves it via ML-DSA; with a static `SAIHM_AUTH_HEADER` it must equal the JWT `sub`. Publish `saihm.identityRecord` so other agents can share to you.

## Configuration

| Env                        | Required          | Meaning                                                                                                                                                                                                           |
| ----