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.1

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.1
File	Size	Uploaded
totalreclaw-2.5.1.tar.gz	850.3 kB	Sep 16, 2026	Details

Built distribution (wheel)

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

Total release size: 1.3 MB

Release files / totalreclaw-2.5.1.tar.gz

Download URL	totalreclaw-2.5.1.tar.gz
Size	850.3 kB
Tags	Source
SHA-256 checksum How to use checksums	`da2f6ee5dd7cd31c7db438ddacc8e311c437ef3f5ca1ff7f7504e285e4f37d32`
BLAKE2b-256 checksum How to use checksums	`ffd26291ec6a34636c0a0f4ac2958c598e4b667426468d3a5918ac326ff819a7`
Upload date	Sep 16, 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.1-py3-none-any.whl

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