saihm-mcp

# SAIHM MCP Server

**The standards client for your own custodial SAIHM operator.** It carries no
cryptography of its own and expects an operator endpoint URL plus an operator
token. If you just want memory working, free, in about a minute, use
**`@saihm/mcp-server-pro`** and ask your agent to *"Join SAIHM"*.

[![npm version](https://img.shields.io/npm/v/@saihm/mcp-server)](https://www.npmjs.com/package/@saihm/mcp-server)
[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/12898/badge)](https://www.bestpractices.dev/projects/12898)
· Apache-2.0

This package is the **standards client**: eight memory tools any MCP agent —
Claude Code, Claude Desktop, Cursor, or your own — can call. It carries **no
cryptography of its own**. It speaks the publicly documented SAIHM memory
protocol over plain MCP and reaches whichever SAIHM operator you point it at.

**Which package do I want?**

- **You run, or subscribe to, your own SAIHM operator** — this one. Being
  crypto-free and dependency-light is the point: it drops into a **custodial**
  operator that performs the cryptography server-side.
  → [Install](#install) · [Configure](#configure)
- **You just want memory working, free, in about a minute** — use
  **[`@saihm/mcp-server-pro`](https://www.npmjs.com/package/@saihm/mcp-server-pro)**
  and ask your agent to *"Join SAIHM"*. It seals cells on your own machine, so it
  can use the hosted **non-custodial** service — which this crypto-free package
  cannot. No card. → [Free trial](#free-trial-sign-in-with-github)

**Want to watch it work first?** Runnable demos across every major model,
offline, no account — **[See it run](#see-it-run)**.

## What this is

A [Model Context Protocol](https://modelcontextprotocol.io/) server
that exposes eight tools any MCP-capable AI agent (Claude Code, Claude Desktop,
custom agents) can call to gain a persistent, encrypted memory layer the
**user** owns:

- `saihm_remember` — store an encrypted memory cell
- `saihm_recall` — retrieve and decrypt your memories
- `saihm_forget` — true cryptographic erasure (GDPR Art. 17)
- `saihm_status` — your protocol-runtime stats and storage tier dashboard
- `saihm_share` / `saihm_revoke_share` — selectively share a memory with another agent or user
- `saihm_governance_propose` / `saihm_governance_vote` — protocol governance; **not enabled by default**, so expect an error unless your operator has turned it on

Each tool forwards to a SAIHM operator endpoint that runs the full protocol
stack on COTI V2 mainnet. The server itself holds no crypto, no storage, and
no protocol runtime — those live behind the operator endpoint.

## Tool reference

| Tool | Title | Behavior |
|---|---|---|
| `saihm_remember` | Remember | writes a new memory cell |
| `saihm_recall` | Recall | read-only; safe to repeat |
| `saihm_forget` | Forget (GDPR erasure) | **destructive** — irreversible erasure |
| `saihm_status` | Status | read-only |
| `saihm_share` | Share | writes a sharing contract |
| `saihm_revoke_share` | Revoke share | withdraws a grant |
| `saihm_governance_propose` | Propose (governance) | forwards a proposal; **not enabled by default** |
| `saihm_governance_vote` | Vote (governance) | forwards a vote; **not enabled by default** |

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.

## Companion package

This package speaks MCP and holds no cryptography, so it always needs an
operator endpoint and token. Two companions cover the rest:

- **[`@saihm/mcp-server-pro`](https://www.npmjs.com/package/@saihm/mcp-server-pro)**
  — a drop-in MCP server that performs the client-side cryptography itself and
  can **self-onboard**, including the free tier. This is the package to use if
  you have no endpoint yet — see [Free trial](#free-trial-sign-in-with-github).
- **[`@saihm/client-pro`](https://www.npmjs.com/package/@saihm/client-pro)** —
  the same client-side cryptography as a library, for embedding in your own
  application: post-quantum sealing, authenticated sharing, and provable
  erasure performed on your own machine so the operator stays blind.

## See it run

Runnable, one-command demos ground a memory you own in every major model — Claude, GPT, DeepSeek, Qwen, Kimi, GLM — then prove you can erase it, alongside drop-in adapters for LangChain, LlamaIndex, CrewAI, AutoGen, and LangGraph. Each runs offline in about a minute; no account needed.

- **Live demos:** <https://citw2.github.io/saihm-demos/>
- **`demo-claude-code`** wires this server into Claude Code and Cursor as an MCP server.

**Measured — up to ~86% fewer context tokens.** Most agents re-send their entire transcript every turn, so context spend grows ~O(N²) over a session; recalling a bounded set of memory cells instead cut input tokens by **62.8%–85.9%** across a realistic multi-session coding task. The benchmark is open, offline, and deterministic — reproduce the number rather than trust it:

```bash
git clone https://github.com/citw2/saihm-token-benchmark
cd saihm-token-benchmark && npm install && node benchmark.mjs
```

## Install

```bash
npm install @saihm/mcp-server
# or run directly without install:
npx @saihm/mcp-server
```

## Configure

The server needs two env vars:

```
SAIHM_ENDPOINT_URL=https://operator.example.com/mcp
SAIHM_AUTH_HEADER=Bearer <token-issued-by-your-operator>
```

> **Don't have an endpoint and token yet?** They're issued by a SAIHM *operator*.
> This package is deliberately **crypto-free**, so it needs a **custodial**
> operator — one that performs cryptography server-side and returns plaintext.
>
> **The hosted SAIHM service at <https://saihm.coti.global> is not one.** It is
> non-custodial by design: it stores only ciphertext and never holds your keys,
> so cells sealed there can only be opened by a client that holds them. To use
> the hosted service — including the **free trial** (sign in with GitHub, no
> card) — use
> **[`@saihm/mcp-server-pro`](https://www.npmjs.com/package/@saihm/mcp-server-pro)**,
> which seals and opens on your own machine. See
> [Free trial](#free-trial-sign-in-with-github) and
> [Join SAIHM](#prefer-not-to-run-storage-yourself-join-saihm) below.
>
> Use *this* package against a custodial operator you run or subscribe to.
> Until one is configured, the tools have nowhere to reach and will return an
> error.

- **`SAIHM_ENDPOINT_URL`** — the endpoint of the **custodial** SAIHM operator you
  run or subscribe to. Not the hosted service at <https://saihm.coti.global>,
  which is non-custodial — see the note above.
- **`SAIHM_AUTH_HEADER`** — the `Authorization` header value the operator
  expects (typically a `Bearer <token>` issued to you after key-bound
  enrolment). The server is authentication-agnostic and **never transmits
  raw private keys**; the operator's enrolment flow keeps your
  signing key on your machine.

Both are read from the process environment. This package loads no `.env` file —
it has no `dotenv` dependency and never reads configuration from disk — so set
them in the `env` block of your MCP host's server configuration, or export them
in the shell that launches the server. If you keep them in a `.env` for your own
convenience, source it yourself before launching, and keep it out of version
control.

## Free trial (sign in with GitHub)

Want to test SAIHM on real infrastructure before you pay? Start a **free trial**
— for testing purposes, no card — by proving you're a unique person once through
a GitHub device sign-in. It runs through the non-custodial
[`@saihm/mcp-server-pro`](https://www.npmjs.com/package/@saihm/mcp-server-pro)
client, which seals cells on your own machine so the operator stays blind.

First generate your master secret — it never leaves your machine, and it is the
only key to your memory:

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

Then activate:

```bash
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
```

It prints a short code and a link: open <https://github.com/login/device> in
your browser and enter the code. The sign-in stays in your browser — this
client never sees or holds your GitHub token; it is exchanged server-side and
kept ephemeral. When `free-join` returns, start the server normally (drop
`free-join`) and it self-onboards on the free trial. **No card, and nothing to
cancel** — it's a fixed, one-time allowance, not an auto-renewing subscription.

Ready for production? Upgrade in place to a **monthly** plan — same signing key,
same memories, no re-onboarding.

## Wire into Claude Code

```json
{
  "mcpServers": {
    "saihm": {
      "command": "npx",
      "args": ["@saihm/mcp-server"],
      "env": {
        "SAIHM_ENDPOINT_URL": "https://operator.example.com/mcp",
        "SAIHM_AUTH_HEADER": "Bearer <token>"
      },
      "timeout": 60
    }
  }
}
```

Keep `timeout`, and keep the block as strict JSON with no trailing commas.
Hosts that don't recognise `timeout` ignore it, but Cline allows a server only
1.5 s to start — too short for `npx` to resolve and launch a package — and a
server that misses the deadline is skipped **silently**, with no error in the
chat.

## Tell your agent to use it

Wiring the server in makes the tools available; it does not make an agent reach
for them. Say this once, and keep it in whatever persistent instructions your
agent already reads:

> Liberally use SAIHM protocol to maximize token economy. Use my SAIHM memory
> from now on. At the start of each session, recall what you already know about
> me. When I tell you something worth keeping — my preferences, decisions, or
> ongoing projects — remember it. To confirm it works right now: remember that I
> wired up SAIHM today, then recall it back to me.

Hosts that support MCP pro