This release is a pre-release and may not be stable for production use.
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.5PyO3 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
- Client setup guide (v1)
- Memory types guide
- v1 migration guide
- Environment variables
- Hermes setup guide
- Feature comparison
Changelog
The latest changes live in CHANGELOG-public.md — kept current there rather than duplicated in this README.
License
MIT
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file totalreclaw-2.5.0rc2.tar.gz.
File metadata
- Download URL: totalreclaw-2.5.0rc2.tar.gz
- Upload date:
- Size: 845.0 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
50952bb0cfb1fd5ac870cbcd567d44d47fd3c66254d113c059a2ab4779e8a9a5
|
|
| MD5 |
4900bacb71cdf9e6c13cba48d04d841e
|
|
| BLAKE2b-256 |
d1944b3902237ada852f90ba9dd8f4e8135755a273206fbc9e9d94feaf4df988
|
File details
Details for the file totalreclaw-2.5.0rc2-py3-none-any.whl.
File metadata
- Download URL: totalreclaw-2.5.0rc2-py3-none-any.whl
- Upload date:
- Size: 464.2 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
f11c94a801a35abd1a8a91cc339edc03d31e92f6155164d70f1db13a56203de8
|
|
| MD5 |
49d4624ce84ef90e1737dfe72f7984e8
|
|
| BLAKE2b-256 |
f9486e14216b19601f0434132756e2aadd4e9fbed30bf6b94ff74c3d04b99d83
|
