TotalReclaw

---

Your AI remembers everything — without remembering it for Big Tech. And starting with v1, every memory is structured: 6 speech-act types, provenance, scope, and volatility on every entry.

• Private — XChaCha20-Poly1305 encryption happens on-device. The server never sees plaintext, even if fully compromised.
• Structured — every memory typed by speech act with source, scope, and volatility. Learn more →
• Portable — one 12-word recovery phrase works across every supported agent. Switch platforms without losing a single memory. Compare integrations →
• Yours forever — memories are anchored to Gnosis Chain and indexed by The Graph. No vendor lock-in, no data hostage.

Most AI memory products store your data unencrypted server-side, or leave encryption up to your deployment. TotalReclaw can't read your data by design — that's the difference between a privacy promise and a structural guarantee.

	TotalReclaw	Typical hosted memory
Server sees your memories in plaintext?	Never — E2E encrypted on-device	Yes
One-click plain-text export?	Yes	Varies
Works across agents?	Yes — OpenClaw, Claude Desktop, Hermes, ZeroClaw, any MCP host	Usually SDK-locked
Storage you control?	Yes — public chain or your own PostgreSQL	Vendor database

New in v1 (April 2026): memory taxonomy (6 types), source-weighted reranking, 4 new MCP tools (totalreclaw_pin / totalreclaw_unpin / totalreclaw_retype / totalreclaw_set_scope), protobuf v4 wire format. v1 is the default on every client. Existing vaults decrypt transparently. See the v1 migration guide.

Quick Start

One command per client. v1 is the default — no env toggles, no feature flags.

Prefer the chat-driven install? Paste one host-agnostic line into any agent (OpenClaw, Hermes, Claude Desktop / Cursor / Windsurf): Install TotalReclaw. See https://totalreclaw.xyz/install — a short alias for the universal dispatcher (install.md).

Client	Install
OpenClaw	openclaw plugins install @totalreclaw/totalreclaw
Claude Desktop / Cursor / Windsurf	npx @totalreclaw/mcp-server setup — run it yourself in a terminal, never via your AI agent (the wizard prints your recovery phrase, which must not enter the agent's context)
NanoClaw	@totalreclaw/skill-nanoclaw (bundled via NanoClaw) + set TOTALRECLAW_RECOVERY_PHRASE in deployment env — see the NanoClaw guide
Python / Hermes	pip install totalreclaw
Rust / ZeroClaw	cargo add totalreclaw-memory
IronClaw	via the generic MCP server (first-class integration paused) — see IronClaw setup

Then set one env var on your host:

export TOTALRECLAW_RECOVERY_PHRASE="your twelve word recovery phrase here"

If you don't have a phrase yet, the setup wizard generates one. See the client setup guide for per-platform details.

How It Works

1. Your agent extracts facts from conversations — typed by speech act (claim, preference, directive, commitment, episode, summary) and tagged with source, scope, volatility.
2. Everything is encrypted on-device — keys derived from your recovery phrase, never sent anywhere.
3. Encrypted data is stored on-chain — the server only sees ciphertext and hashed search tokens.
4. Search works over encrypted data — blind indices and LSH let the server find relevant memories without reading them.
5. Results are decrypted and ranked locally — BM25 + cosine + RRF with source-weighted reranking (v1 Tier 1).

Full technical deep dives: Architecture, Memory Taxonomy v1, Tiered Retrieval.

What's new in v1

v1 shipped across every client in April 2026. Highlights:

• 6-type speech-act taxonomy — claim / preference / directive / commitment / episode / summary. Replaces the ambiguous 8-type v0 list.
• 3 orthogonal axes — source (user / user-inferred / assistant / external / derived), scope (work / personal / health / family / creative / finance / misc / unspecified), volatility (stable / updatable / ephemeral).
• Source-weighted reranking — user-authored claims consistently rank above assistant-regurgitated noise. Structurally fixes the 97.8% junk problem documented in other memory systems.
• 4 new MCP tools — totalreclaw_pin, totalreclaw_unpin, totalreclaw_retype, totalreclaw_set_scope. Invoked by natural language ("pin that", "file that under work").
• Protobuf v4 wire format — outer wrapper bump; subgraph schema unchanged.
• Env var cleanup — several experimental env vars removed; a small set of user-facing env vars remain. See the env vars reference.

Full details: v1 migration guide and memory types guide.

Import from Other AI Tools

Already using another AI assistant with memory? Tell your agent:

• "Import my ChatGPT memories into TotalReclaw"
• "Import my Claude memories into TotalReclaw"
• "Import my Gemini history into TotalReclaw"

Supported sources: ChatGPT (memories or conversations.json), Claude (memory export), Gemini (Google Takeout), Mem0 (API or file), MCP Memory Server (JSONL). All imports are encrypted client-side before storage. See the import guide.

On the managed service, the free tier includes one lifetime import; re-importing from additional sources is a Pro feature. See pricing.

Your vault in the browser

View and curate your memories at app.totalreclaw.xyz — no install required. Your recovery phrase is entered locally and never leaves your device; decryption happens entirely in the browser, so the server only ever serves ciphertext.

Packages

Package	Description	Install
@totalreclaw/totalreclaw	OpenClaw plugin — automatic encrypted memory	openclaw plugins install @totalreclaw/totalreclaw
@totalreclaw/mcp-server	MCP server for Claude Desktop and other MCP clients	npx @totalreclaw/mcp-server setup
@totalreclaw/client	Client library (encryption, indexing, search, re-ranking)	npm install @totalreclaw/client
totalreclaw	Python client + Hermes Agent plugin	pip install totalreclaw

Pricing

Free: 250 memories/month, permanently stored on Gnosis mainnet, end-to-end encrypted — no credit card required. Pro: 1,500 memories/month, plus LLM-guided dedup and custom extraction intervals. See pricing →

Self-Hosting

Run the open-source server with PostgreSQL — no dependency on totalreclaw.xyz:

cd server && cp .env.example .env && docker-compose up -d

Set TOTALRECLAW_SELF_HOSTED=true and TOTALRECLAW_SERVER_URL=http://localhost:8080 on the client. Both modes encrypt identically — the difference is where the encrypted blobs are stored.

Repository Structure

totalreclaw/
├── client/          TypeScript client library (encryption, indexing, search, re-ranking)
├── rust/            Rust core (XChaCha20-Poly1305, LSH, reranker) — compiles to WASM + PyO3
├── python/          Python client library + Hermes Agent plugin
├── skill/           OpenClaw plugin (automatic memory via lifecycle hooks)
├── skill-nanoclaw/  NanoClaw skill package + MCP bridge
├── mcp/             MCP server for Claude Desktop and other MCP clients
├── app/             Vault SPA (Vite + React) — managed-mode read UI
├── server/          Self-hosted server (FastAPI + PostgreSQL)
├── contracts/       Smart contracts (Gnosis Chain)
├── subgraph/        The Graph subgraph (AssemblyScript indexer)
├── docs/            Architecture, specs, and guides
└── tests/           Integration, parity, and E2E tests

Documentation

Start here

• Universal install prompt — one host-agnostic paste line; routes any agent to its runtime's setup guide.
• Client setup — v1 — one install command per client.
• Memory types guide — what gets stored and how to override it via natural language.
• v1 migration guide — if you're upgrading from v0.
• Environment variables — the user-facing env vars that matter.
• Feature comparison — which features work on which client.

Per-client setup

• OpenClaw
• Claude Desktop / Cursor / Windsurf
• NanoClaw
• Hermes (Python)
• IronClaw (NEAR AI) (first-class integration paused — works via the generic MCP server)
• ZeroClaw (Rust)

Specs + architecture

• Architecture — encryption, LSH, search, deduplication, network layer.
• Memory Taxonomy v1 — normative cross-client spec.
• Retrieval v2 — source-weighted reranking + future tiers.
• Tiered Retrieval — implementation-focused retrieval deep dive.
• Client Consistency — cross-client contracts.

Other

• Importing memories — ChatGPT, Claude, Gemini, Mem0.
• totalreclaw.xyz — project homepage.

License

• Self-hosted server (server/) — AGPL-3.0
• All other code — MIT