# Mnemonic Protocol — README

(Saved from mnemonik.xyz landing page metadata, llms.txt, agent.json, and monorepo README.)

# Mnemonic Protocol

> Verifiable, persistent memory for AI agents — signed COSE_Sign1 envelopes, anchored on Solana (SPL Memo) and optionally Arweave, exposed over the Model Context Protocol (MCP). Open-source under Apache-2.0.

## What it does

Mnemonic gives AI agents a persistent memory that any third party can verify:

- **Sign** — every memory is canonically CBOR-encoded, blake3-hashed, and signed with the agent's Ed25519 identity in a COSE_Sign1 envelope.
- **Anchor** — the hash is committed on-chain via Solana SPL Memo (sub-cent, sub-second) and the bytes are stored permanently on Arweave.
- **Recall** — TurboQuant-compressed embeddings allow cosine search by semantic meaning, not just keyword.
- **Verify** — anyone with the `solana_tx` and `arweave_tx` can independently re-fetch, re-hash, re-verify the signature — without contacting Mnemonic.

## MCP tools

The server exposes 5 tools over JSON-RPC at `POST /mcp` (and stdio):

| Tool | Purpose |
|---|---|
| `mnemonic_whoami` | Server identity (Ed25519 pubkey, DIDs, storage mode, attestation count) |
| `mnemonic_sign_memory` | Embed + compress + canonicalize (CBOR) + hash (blake3) + sign (COSE_Sign1) + persist |
| `mnemonic_verify` | Verify a memory by `solana_tx` and/or `arweave_tx` (version-aware) |
| `mnemonic_prove_identity` | Sign an arbitrary challenge with the server key |
| `mnemonic_recall` | Semantic search over stored embeddings (SQLite) |

Current artifact format: **canonical CBOR + COSE_Sign1, blake3 hashing**. Older SHA-256/JSON artifacts are still verifiable via a legacy fallback path.

## Storage modes (`STORAGE_MODE`)

- `local` (default) — SQLite only. No Solana / Arweave writes, no payment gate. Synthetic tx ids (`local:...`). Ideal for dev, demos, and UX testing.
- `full` — signed COSE bytes written to Arweave, anchor memo written to Solana, searchable embeddings kept in SQLite. Payment gate applies on HTTP when enabled.

## Programmatic access

- `@mnemonik-xyz/cli` (npm) — `mnemonic` binary for terminal use. `npx @mnemonik-xyz/cli init --ticket <uuid>` after clicking "Send to CLI" at `mnemonik.xyz/install`.
- `@mnemonik-xyz/sdk` (npm) — runtime-agnostic TypeScript SDK. Pure ESM; runs on Node 20+, Bun, Deno, and modern browsers.

## Endpoints

- Hosted MCP: `https://mcp.mnemonik.xyz/mcp` (HTTP, OAuth 2.1 + PKCE)
- Agent card: `https://mnemonik.xyz/.well-known/agent.json`
- OAuth metadata: `https://mcp.mnemonik.xyz/.well-known/oauth-authorization-server`

## Repository layout

Cargo workspace with two crates:

- `core/` — `mnemonic-core`: library — codec, identity, embed, compress, storage, solana, arweave, lineage.
- `mcp/` — `mnemonic-mcp`: binary — MCP server (HTTP + stdio), payment gate, pricing engine.

## License

Apache-2.0. Sources, foundational paper, and docs at https://github.com/mnemonik-xyz/monorepo.