# mnemonik

Mnemonic Protocol is a memory layer for AI agents where every memory is signed, deterministically hashed, and optionally anchored on a public blockchain. The pitch is *verifiable* memory: a third party with two transaction IDs can re-fetch the bytes, recompute the hash, and check the agent's signature without ever talking to the Mnemonic server. Exposed as an MCP server so Claude / Cursor / VS Code / custom agents plug it in like any other context provider.

## How it works

Each memory the agent writes goes through a fixed pipeline:

1. **Embed** — semantic vector for similarity recall (local ONNX via `fastembed` feature, or default to a placeholder).
2. **Compress** — TurboQuant-compressed embedding so the bytes are cheap to ship around.
3. **Canonicalize** — deterministic CBOR encoding (same memory always serialises identically).
4. **Hash** — blake3 fingerprint of the canonical bytes.
5. **Sign** — Ed25519 signature wrapped in a COSE_Sign1 envelope using the server's identity key.
6. **Anchor (optional)** — bytes go to Arweave, hash goes to Solana via SPL Memo (sub-cent, sub-second).

Two storage modes (`STORAGE_MODE` env):

- `local` (default) — SQLite only, no chain writes, synthetic `local:` tx ids. For dev and demos.
- `full` — Arweave for bytes, Solana for the anchor, SQLite for embedding search; HTTP payment gate.

The verification flow runs entirely client-side. Given `solana_tx` and `arweave_tx`, anyone can pull the COSE artefact off Arweave, recompute the blake3 hash, confirm the Solana memo points at that hash, and verify the Ed25519 signature with the server's published identity key. Mnemonic is not a trusted party at verify time — it just publishes anchors.

## MCP tools

Five JSON-RPC tools at `POST /mcp` (and stdio):

| Tool | Purpose |
|------|---------|
| `mnemonic_whoami` | Server identity, storage mode, attestation count |
| `mnemonic_sign_memory` | Embed → compress → canonicalise → hash → sign → persist (and optionally anchor) |
| `mnemonic_verify` | Verify a memory by `solana_tx` and/or `arweave_tx` |
| `mnemonic_prove_identity` | Sign an arbitrary challenge with the server's key |
| `mnemonic_recall` | Cosine search over stored embeddings |

## Usage

```bash
# pair via the webapp ticket
npx @mnemonik-xyz/cli init --ticket <uuid>
npx @mnemonik-xyz/cli login
npx @mnemonik-xyz/cli sign "first memory"
npx @mnemonik-xyz/cli recall "first"

# CLI-only
npx @mnemonik-xyz/cli init --standalone
```

Self-host the MCP server:

```bash
STORAGE_MODE=local PAYMENT_MODE=none \
  ./target/release/mnemonic-mcp --transport http --port 3000
```

Hosted endpoint: `https://mcp.mnemonik.xyz/mcp` (OAuth 2.1 + PKCE).

## Where it fits

Mnemonic is at the cryptography-first end of the AI memory spectrum, in contrast to retrieval-style memory ([[toolbox/hippo-memory|hippo-memory]] biological-decay model, [[toolbox/mempalace|mempalace]] palace metaphor, [[toolbox/stash|stash]] nine-stage consolidation pipeline). Those projects optimise for *recall quality*; Mnemonic adds *attribution and non-repudiation* — you can show that this agent saved this memory at this point in time. The trade-off is operational complexity: Solana account, Arweave bundling, an additional signing path. For agents whose outputs need to be later cited or audited (legal review, regulatory contexts, claims about prior state), the verification surface is the point.

The MCP surface keeps it interchangeable with the others — same drop-in slot in a Claude / Cursor config, different guarantees underneath. See [[agent-memory-decay]] for the recall-side concerns Mnemonic does not address.

## Limitations

- Solana / Arweave dependency in `full` mode adds two external chains to the failure domain.
- TurboQuant compression and the default ONNX embedder are commodity choices — semantic recall quality is no better than the embedding you wire in.
- Verification requires both `solana_tx` and `arweave_tx`; losing one means losing the audit trail.
- Single-author project; on the watchlist for early-stage indicators.

Repo: https://github.com/mnemonik-xyz/monorepo (Apache-2.0). Hosted: https://mnemonik.xyz. Listed in [[toolbox/watchlist]].