totalreclaw

End-to-end encrypted memory + knowledge graph for AI agents.

Store, search, and recall memories across any AI agent with zero-knowledge encryption. Your data is encrypted on-device before it leaves -- the server never sees plaintext.

As of 2.4.6, the client uses Memory Taxonomy v1 (6 canonical types: claim | preference | directive | commitment | episode | summary) and Retrieval v2 Tier 1 source-weighted reranking (user-sourced facts rank higher than assistant-sourced facts on tied BM25 + cosine scores). See the memory types guide. Existing pre-v1 vault entries decrypt transparently.

Features

End-to-end encrypted -- XChaCha20-Poly1305 encryption, HKDF key derivation from a BIP-39 recovery phrase
Portable -- Same recovery phrase works across Hermes, OpenClaw, Claude Desktop, IronClaw, ZeroClaw
Memory Taxonomy v1 -- 6 speech-act types + required provenance (user | user-inferred | assistant | external | derived) and 8 life-domain scopes. v1 is the only write path (no env-var gating).
Retrieval v2 Tier 1 -- source-weighted reranking via totalreclaw-core@2.5.5 PyO3 bindings (user-sourced facts rank higher on tied scores)
G-pipeline extraction -- merged-topic prompt, provenance filter (lax), comparative rescoring, volatility heuristic
Local embeddings -- Harrier-OSS-v1-270M runs on-device (no API calls)
Hybrid search -- BM25 + cosine similarity + RRF reranking
LSH bucketing -- Locality-sensitive hashing for encrypted search
On-chain storage -- Managed service stores on Gnosis mainnet (single chain, all tiers) via ERC-4337; outer protobuf v4

Quick Start

pip install totalreclaw

import asyncio
from totalreclaw import TotalReclaw

async def main():
    client = TotalReclaw(
        recovery_phrase="your twelve word recovery phrase here",
        server_url="https://api.totalreclaw.xyz",  # default, can be omitted
    )

    # REQUIRED: resolve Smart Account address and register with relay
    await client.resolve_address()
    await client.register()

    # Store a memory — v1 taxonomy defaults: type="claim", source="user", scope="unspecified".
    # Importance is 1-10 (int) or 0-1 (float, auto-normalized).
    # v1 types: claim | preference | directive | commitment | episode | summary
    # scope, volatility, reasoning also accepted.
    fact_id = await client.remember(
        "Pedro prefers dark mode for all editors",
        fact_type="preference",
        scope="personal",
        importance=8,
    )

    # Search memories
    results = await client.recall("What does Pedro prefer?")
    for r in results:
        print(f"  [{r.rrf_score:.3f}] {r.text}")

    # Delete a memory
    await client.forget(fact_id)

    # Export all memories
    facts = await client.export_all()

    # Check billing
    status = await client.status()
    print(f"Tier: {status.tier}, Used: {status.free_writes_used}/{status.free_writes_limit}")

    await client.close()

asyncio.run(main())

Important: You must call resolve_address() and register() before any operations. resolve_address() derives the CREATE2 Smart Account address via an RPC call, and register() authenticates with the relay.

With Embeddings (Recommended)

For semantic search, install with embedding support:

pip install totalreclaw

from totalreclaw import TotalReclaw
from totalreclaw.embedding import get_embedding

client = TotalReclaw(recovery_phrase="...")

# Store with embedding for semantic search
text = "Pedro prefers dark mode"
embedding = get_embedding(text)
await client.remember(text, embedding=embedding)

# Search with embedding
query = "What are Pedro's UI preferences?"
query_emb = get_embedding(query)
results = await client.recall(query, query_embedding=query_emb)

The embedding model (~600 MB) downloads automatically on first use.

Hermes Agent Plugin

pip install totalreclaw[hermes]

The plugin registers automatically with Hermes Agent v0.5.0+. See the Hermes setup guide.

Architecture

Plaintext → XChaCha20-Poly1305 encrypt → Blind indices (SHA-256) → LSH buckets → On-chain via relay
                                                                              ↓
Query → Blind trapdoors → GraphQL search → Decrypt candidates → BM25+Cosine+RRF rerank → Top 8

All encryption happens client-side. The relay server and on-chain storage never see plaintext.

Cross-Language Parity

This Python client produces byte-for-byte identical outputs to the TypeScript implementation (@totalreclaw/mcp-server):

Key derivation (HKDF-SHA256)
XChaCha20-Poly1305 wire format (nonce || tag || ciphertext)
Blind indices (SHA-256 + Porter stemming)
Content fingerprints (HMAC-SHA256)
LSH bucket hashes (32-bit x 20 tables)

Memories stored by the Python client can be recalled by the MCP server, and vice versa.

Learn More

Changelog

The latest changes live in CHANGELOG-public.md — kept current there rather than duplicated in this README.

License

MIT

Release files for totalreclaw 2.5.1rc1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for totalreclaw 2.5.1rc1
File	Size	Uploaded
totalreclaw-2.5.1rc1.tar.gz	850.1 kB	Sep 15, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for totalreclaw 2.5.1rc1
File	Interpreter	ABI	Platform	Reset
totalreclaw-2.5.1rc1-py3-none-any.whl 467.1 kB Sep 15, 2026	Python 3	none	any	Details

Total release size: 1.3 MB

Release files / totalreclaw-2.5.1rc1.tar.gz

Download URL	totalreclaw-2.5.1rc1.tar.gz
Size	850.1 kB
Tags	Source
SHA-256 checksum How to use checksums	`83817fa35697bdc28577ca3b94b0ecb533d3eeaa39ef2f98e85b7b04a3c5dfa7`
BLAKE2b-256 checksum How to use checksums	`614b30ee7267c4479d93d7cc5e7155e37df414e63904f167e147eafe2505d242`
Upload date	Sep 15, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Release files / totalreclaw-2.5.1rc1-py3-none-any.whl

Download URL	totalreclaw-2.5.1rc1-py3-none-any.whl
Size	467.1 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`7f5defed8b858fd8e4f31cbb211a03e9b6d64be0585609d1e6aab4b90acea2a2`
BLAKE2b-256 checksum How to use checksums	`f630ac8bca56254b9fe58b1a6b08a14d014184bdaa40ea7f0ccc2035c2416f50`
Upload date	Sep 15, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`