End-to-end encrypted memory vault as an MCP server. Your memories are encrypted on your device before leaving -- no one can read them, not even us.

v3.0.0 ships Memory Taxonomy v1 — 6 speech-act types + source / scope / volatility axes on every memory. Four new tools (totalreclaw_pin, totalreclaw_unpin, totalreclaw_retype, totalreclaw_set_scope) let agents override categorization via natural language. Source-weighted reranking ranks user-authored claims above assistant-regurgitated noise. See memory types guide.

Requirements: Node.js 18+

Quick Start

1. Run the setup wizard

npx @totalreclaw/mcp-server setup

The wizard generates your 12-word recovery phrase, registers you, and prints a config snippet for your MCP client.

Save your recovery phrase somewhere safe. It's the only way to recover your encrypted memories.

Note: The first run downloads a ~600MB embedding model for local inference. This is cached locally and only happens once.

2. Add to your MCP client

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "totalreclaw": {
      "command": "npx",
      "args": ["-y", "@totalreclaw/mcp-server"],
      "env": {
        "TOTALRECLAW_RECOVERY_PHRASE": "your twelve word recovery phrase goes here"
      }
    }
  }
}

Note: The server URL defaults to https://api.totalreclaw.xyz (the managed service). You only need to set TOTALRECLAW_SERVER_URL if you are running a self-hosted server.

Cursor / Windsurf

Add to your MCP settings (Settings > MCP Servers):

{
  "totalreclaw": {
    "command": "npx",
    "args": ["-y", "@totalreclaw/mcp-server"],
    "env": {
      "TOTALRECLAW_RECOVERY_PHRASE": "your twelve word recovery phrase goes here"
    }
  }
}

IronClaw (NEAR AI)

Add to your IronClaw MCP configuration (typically ~/.ironclaw/mcp.json or via the IronClaw dashboard):

{
  "mcpServers": {
    "totalreclaw": {
      "command": "npx",
      "args": ["@totalreclaw/mcp-server"],
      "env": {
        "TOTALRECLAW_RECOVERY_PHRASE": "your twelve word recovery phrase goes here"
      }
    }
  }
}

If IronClaw supports a credential vault, store TOTALRECLAW_RECOVERY_PHRASE there instead of in the config file. See the IronClaw setup guide for the full walkthrough including background routines.

3. Verify

Ask your agent: "Do you have access to TotalReclaw memory tools?"

How It Works

All cryptographic operations (XChaCha20-Poly1305, HKDF key derivation, LSH hashing, blind indices, content fingerprinting) are powered by @totalreclaw/core -- a unified Rust/WASM module shared across all TotalReclaw clients.

All encryption happens client-side inside the MCP server process on your machine:

1. Facts are encrypted with XChaCha20-Poly1305 before leaving your device
2. Search uses blind indices (SHA-256 hashes) -- the server never sees your queries
3. Your recovery phrase derives all keys via Argon2id + HKDF
4. Encrypted facts are stored on-chain (Gnosis Chain) and indexed by The Graph

The server only ever sees ciphertext and hashed tokens.

Available Tools

All 18 tools are invoked by the host agent from natural language context. Tool schemas include v1 taxonomy fields (type, source, scope, reasoning).

| Tool | Description | |------|-------------| | totalreclaw_remember | Store a fact in encrypted memory. Supports v1 taxonomy (type, scope, reasoning) + legacy types for migration | | totalreclaw_recall | Search memories by natural language query. Source-weighted ranking (Retrieval v2 Tier 1) | | totalreclaw_forget | Delete a specific memory by ID | | totalreclaw_pin | Pin a memory so auto-resolution never supersedes it. Accepts fact_id or memory_id | | totalreclaw_unpin | Remove the pin, returning the memory to active status | | totalreclaw_retype (new in v3.0.0) | Change the v1 type of a memory (e.g. preference → directive) via supersession | | totalreclaw_set_scope (new in v3.0.0) | Change the v1 scope of a memory (e.g. set to work / personal) | | totalreclaw_export | Export all memories decrypted as Markdown or JSON | | totalreclaw_status | Check billing status and quota usage | | totalreclaw_import | Re-import previously exported memories | | totalreclaw_import_from | Import from Mem0, MCP Memory Server, ChatGPT, Claude, or generic JSON/CSV | | totalreclaw_import_batch | Batch import with background polling | | totalreclaw_consolidate | Merge duplicate and related memories | | totalreclaw_debrief | End-of-conversation summary to capture broader context | | totalreclaw_upgrade | Get a link to upgrade to Pro | | totalreclaw_account | View account details (wallet, tier, quota, phrase hint) | | totalreclaw_pair | Set up the account via a browser pair flow — the browser generates/imports a recovery phrase out-of-band (never through chat) | | totalreclaw_support | Troubleshooting help + contact links |

Onboarding (recovery phrase): the totalreclaw_setup tool was removed in 3.2.1 for phrase-safety. The preferred path is the server's own totalreclaw_pair browser flow (URL + PIN; the phrase is generated or imported in the browser and never enters chat). Alternatively, follow the URL-driven flow at docs/guides/claude-code-setup.md: source the phrase out-of-band (OpenClaw / Hermes browser pair flow, offline BIP-39 generator, or a prior ~/.totalreclaw/credentials.json cache) and paste it into TOTALRECLAW_RECOVERY_PHRASE in the MCP host config. Either way, the agent never sees the phrase.

Users invoke the new v1 tools naturally: "pin that", "that was actually a rule, not a preference", "file that under work". Tool descriptions teach the host LLM to match utterances to tools.

Memory Taxonomy v1 (@totalreclaw/core 2.0)

MCP server v3.0.0 writes v1 inner blobs (outer protobuf wrapper version = 4). The six v1 types correspond to Searle's speech-act classes:

• claim — assertive ("lives in Lisbon", "chose PostgreSQL"). Absorbs legacy fact/context/decision.
• preference — expressive ("likes dark mode").
• directive — imperative ("always check d.get(errors)"). Replaces legacy rule.
• commitment — commissive ("will ship v2 Friday"). Replaces legacy goal.
• episode — narrative ("deployed v1.0 on March 15"). Replaces legacy episodic.
• summary — derived synthesis (debrief pipelines only).

v0 types (fact, context, decision, rule, goal, episodic) are still accepted by the remember tool and auto-mapped to v1 equivalents. Recall output includes source and scope when available.

See docs/specs/totalreclaw/memory-taxonomy-v1.md.

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | TOTALRECLAW_RECOVERY_PHRASE | 12-word BIP-39 recovery phrase. Deprecated in favour of a derived-bundle-v1 bundle in credentials.json — see "Credential Material" below | Required unless a version: 2 bundle is present | | TOTALRECLAW_SERVER_URL | TotalReclaw server URL (only needed for self-hosted) | https://api.totalreclaw.xyz | | TOTALRECLAW_SELF_HOSTED | Use a self-hosted server instead of the managed service | false | | TOTALRECLAW_CREDENTIALS_PATH | Override credentials file location | ~/.totalreclaw/credentials.json | | TOTALRECLAW_CACHE_PATH | Override encrypted cache file location | ~/.totalreclaw/cache.enc |

v1 env cleanup: TOTALRECLAW_CHAIN_ID, TOTALRECLAW_EMBEDDING_MODEL, TOTALRECLAW_STORE_DEDUP, TOTALRECLAW_LLM_MODEL, TOTALRECLAW_SESSION_ID, TOTALRECLAW_TAXONOMY_VERSION, TOTALRECLAW_CLAIM_FORMAT, and TOTALRECLAW_DIGEST_MODE were removed. All tiers use Gnosis mainnet; chain selection is no longer user-configurable. The MCP server silently ignores these vars for a transition period. See the env vars reference.

Credential Material

The managed-service (subgraph) path configures from either a BIP-39 recovery phrase (the legacy path, above) or a derived-bundle-v1 credential bundle (Option E Phase 2 — #581): the four HKDF-derived vault keys plus a signing key, but never the phrase or the 64-byte BIP-39 seed. See docs/specs/totalreclaw/client-consistency.md for the full cross-client contract.

Precedence (first match wins):

1. TOTALRECLAW_RECOVERY_PHRASE env var — a phrase. Deprecated but retained.
2. ~/.totalreclaw/credentials.json with "version": 2 — a derived-bundle-v1 bundle.
3. ~/.totalreclaw/credentials.json legacy shape — {"mnemonic": "…", ...}.

A credentials.json with a version field present and not 2 is a loud, fatal startup error — never a silent downgrade to legacy handling. Same for a version: 2 file that fails schema validation (malformed hex, an owner-eoa bundle carrying a grant, a signing.address that doesn't match the address of signing.private_key, …).

MCP-specific gaps vs. the Hermes (Python) implementation — tracked explicitly, not silently unsupported:

• No OS-keychain unwrap. MCP only reads the plaintext ("headless / no keychain") bundle storage form. A version: 2 file with "keychain_wrapped": true (the desktop-keychain storage form Hermes writes) is a loud, actionable error, not a silent skip.
• No TOTALRECLAW_CREDENTIALS_PROVIDER / external-secret-manager transport. MCP always reads credentials.json from disk (or TOTALRECLAW_CREDENTIALS_PATH) — it has no file / external provider abstraction yet.
• No local-migration tool. MCP does not write a version: 2 bundle from an existing plaintext mnemonic on its own initiative — that credential is produced by Hermes's auto_migrate.py or the vault SPA's pair-time provisioning, and simply read by the MCP server if present.
• Bundle-mode pairing (totalreclaw_pair) is wired but currently inert. The relay does not yet forward a payload_type field on the pair envelope, so totalreclaw_pair always completes via the legacy-phrase path today. The derived-bundle-v1 completion branch is implemented and fixture-tested (tests/pair-bundle.test.ts) so it activates automatically once the relay-side plumbing (tracked separately) lands.

Self-hosted mode is unaffected and unrelated. It is a completely separate credential system (MASTER_PASSWORD + a random, server-issued salt — no BIP-39 root at all) and never consults bundle detection.

Dependency note: bundle support requires an @totalreclaw/core release exposing parseBundleV1 / validateBundleV1 / deriveBundleFromMnemonic. That gate is cleared — @totalreclaw/core 2.6.0 (published 2026-08-16) carries all three in both the nodejs and ./web builds, and package.json requires ^2.6.0. (The earlier 2.6.0-rc.1 predated #587 and did not carry them; it is superseded by 2.6.0.) The runtime feature-detection in src/subgraph/bundle.ts is retained deliberately — it keeps a stale-install downgrade loud rather than a crash.

Free Tier & Pricing

• Free tier — 250 memories/month on Gnosis mainnet. Permanent storage. Cosine dedup (paraphrase detection). E2E encrypted. No credit card required.
• Pro tier — 1,500 memories/month on Gnosis mainnet. Permanent. LLM-guided dedup (catches contradictions). Custom extraction interval. Pay via the totalreclaw_upgrade tool or visit https://totalreclaw.xyz/pricing.

Pay with card via Stripe. Use totalreclaw_status to check current pricing. Counter resets monthly.

Development

npm run build    # Build
npm test         # Run tests
npm run lint     # Lint

Learn More

• Client setup guide (v1) — one install command per client
• Memory types guide — what gets stored and natural-language overrides
• v1 migration guide — upgrading from v0
• Environment variables — the 5 env vars that matter
• Feature comparison — what works on each client
• IronClaw setup guide — full walkthrough for IronClaw (NEAR AI) agents
• totalreclaw.xyz
• Main repository

License

MIT