saihm-mcp

# SAIHM MCP Server

**Sovereign, encrypted, sharable, persistent memory protocol for AI agents.**

[![npm version](https://img.shields.io/npm/v/@saihm/mcp-server)](https://www.npmjs.com/package/@saihm/mcp-server) · Apache-2.0 · COTI V2 mainnet

[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/12898/badge)](https://www.bestpractices.dev/projects/12898)

> **Start free, no card** — on real infrastructure, via a GitHub sign-in:
> **[Free trial](#free-trial-sign-in-with-github)**.
> Or **evaluate it offline first:** runnable demos across every major model, no
> account needed — **[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 via gSAIHM

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) | 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.

## 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.

Place these in a `.env` file alongside the server (the `.gitignore` excludes
all `.env*` files from any future repo).

## 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

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

## What gets persisted, where

The server itself persists nothing. The operator endpoint runs the
full protocol stack: cells are encrypted under a per-cell DEK, sealed by a
per-agent KEK, persisted to the operator's configured durable storage, and
audited on COTI V2 mainnet. See the operator's documentation for tier details,
and **[Storage is the operator's responsibility (by design)](#storage-is-the-operators-responsibility-by-design)**
below.

## Storage is the operator's responsibility (by design)

> **For operators — read this first.** SAIHM does **not** hard-wire your
> durable storage to any single provider, and it does **not** silently
> provision storage for you. **Choosing and configuring where cells are
> persisted is your job, on purpose.** This is a deliberate design choice for
> operator convenience and data sovereignty — not a missing feature. If
> memory writes fail with a storage error, it almost always means the backend
> has not been configured yet.

Why it works this way:

- **Provider sovereignty.** You decide where your tenants' encrypted cells
  live. The protocol never locks you to one vendor or one network.
- **Local-first, then deep-archive.** A typical operator routes writes to a
  **local IPFS (Kubo) node first** — fast, authoritative, and under your own
  control — and then **asynchronously to a Filecoin deep-archive** provider
  such as Pinata, Synapse, or Lighthouse. The same content addressing spans
  both tiers.
- **Your memory and your tenants' take the same path.** Whatever backend you
  configure serves both the operator's own memory and every tenant's — there
  is no separate hidden sink hard-coded to one provider.

What you configure (your operator deployment guide lists the exact settings):

- a reachable IPFS / Kubo endpoint (a local node is recommended) for the
  authoritative low-latency tier, and
- credentials for at least one Filecoin / IPFS pinning provider for durable
  deep-archive.

If neither is configured, the endpoint has nowhere durable to put cells and
will **reject writes rather than lose data**. That refusal is intentional.

### Prefer not to run storage yourself? Join SAIHM.

You have two paths, and either is fine:

1. **Run your own operator endpoint** and configure the storage backend as
   described above — full sovereignty, your infrastructure.
2. **Join the hosted SAIHM operator** and let it provide durab