totalreclaw 0.1.0__tar.gz

totalreclaw-0.1.0/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: totalreclaw
+Version: 0.1.0
+Summary: End-to-end encrypted memory for AI agents — Python client
+Author: TotalReclaw Team
+License-Expression: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: totalreclaw-core>=0.1.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: onnxruntime>=1.17
+Requires-Dist: numpy>=1.26
+Requires-Dist: PyStemmer>=2.2
+Requires-Dist: transformers>=4.40
+Requires-Dist: huggingface-hub>=0.23
+Requires-Dist: eth-account>=0.13
+Provides-Extra: hermes
+Requires-Dist: hermes-agent>=0.5.0; extra == "hermes"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
+Requires-Dist: pytest-xdist>=3.5; extra == "dev"
+Requires-Dist: mnemonic>=0.21; extra == "dev"
+
+# totalreclaw
+
+End-to-end encrypted memory for AI agents -- the "password manager for AI memory."
+
+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.
+
+## Features
+
+- **End-to-end encrypted** -- AES-256-GCM encryption, HKDF key derivation from BIP-39 mnemonic
+- **Portable** -- Same recovery phrase works across Hermes, OpenClaw, Claude Desktop, IronClaw
+- **Local embeddings** -- Qwen3-Embedding-0.6B 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/Base Sepolia via ERC-4337
+
+## Quick Start
+
+```bash
+pip install totalreclaw
+```
+
+```python
+import asyncio
+from totalreclaw import TotalReclaw
+
+async def main():
+    client = TotalReclaw(mnemonic="your twelve word recovery phrase here")
+
+    # Store a memory
+    fact_id = await client.remember("Pedro prefers dark mode for all editors")
+
+    # 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())
+```
+
+## With Embeddings (Recommended)
+
+For semantic search, install with embedding support:
+
+```bash
+pip install totalreclaw
+```
+
+```python
+from totalreclaw import TotalReclaw
+from totalreclaw.embedding import get_embedding
+
+client = TotalReclaw(mnemonic="...")
+
+# 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
+
+```bash
+pip install totalreclaw[hermes]
+```
+
+The plugin registers automatically with Hermes Agent v0.5.0+. See the [Hermes setup guide](https://github.com/p-diogo/totalreclaw/blob/main/docs/guides/hermes-setup.md).
+
+## Architecture
+
+```
+Plaintext → AES-256-GCM 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)
+- AES-256-GCM wire format (iv || 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.
+
+## License
+
+MIT

totalreclaw-0.1.0/README.md

@@ -0,0 +1,111 @@
+# totalreclaw
+
+End-to-end encrypted memory for AI agents -- the "password manager for AI memory."
+
+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.
+
+## Features
+
+- **End-to-end encrypted** -- AES-256-GCM encryption, HKDF key derivation from BIP-39 mnemonic
+- **Portable** -- Same recovery phrase works across Hermes, OpenClaw, Claude Desktop, IronClaw
+- **Local embeddings** -- Qwen3-Embedding-0.6B 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/Base Sepolia via ERC-4337
+
+## Quick Start
+
+```bash
+pip install totalreclaw
+```
+
+```python
+import asyncio
+from totalreclaw import TotalReclaw
+
+async def main():
+    client = TotalReclaw(mnemonic="your twelve word recovery phrase here")
+
+    # Store a memory
+    fact_id = await client.remember("Pedro prefers dark mode for all editors")
+
+    # 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())
+```
+
+## With Embeddings (Recommended)
+
+For semantic search, install with embedding support:
+
+```bash
+pip install totalreclaw
+```
+
+```python
+from totalreclaw import TotalReclaw
+from totalreclaw.embedding import get_embedding
+
+client = TotalReclaw(mnemonic="...")
+
+# 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
+
+```bash
+pip install totalreclaw[hermes]
+```
+
+The plugin registers automatically with Hermes Agent v0.5.0+. See the [Hermes setup guide](https://github.com/p-diogo/totalreclaw/blob/main/docs/guides/hermes-setup.md).
+
+## Architecture
+
+```
+Plaintext → AES-256-GCM 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)
+- AES-256-GCM wire format (iv || 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.
+
+## License
+
+MIT

totalreclaw-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "totalreclaw"
+version = "0.1.0"
+description = "End-to-end encrypted memory for AI agents — Python client"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [{ name = "TotalReclaw Team" }]
+dependencies = [
+    "totalreclaw-core>=0.1.0",
+    "httpx>=0.27",
+    "onnxruntime>=1.17",
+    "numpy>=1.26",
+    "PyStemmer>=2.2",
+    "transformers>=4.40",
+    "huggingface-hub>=0.23",
+    "eth-account>=0.13",
+]
+
+[project.optional-dependencies]
+hermes = ["hermes-agent>=0.5.0"]
+dev = ["pytest>=8.0", "pytest-asyncio>=0.24", "pytest-xdist>=3.5", "mnemonic>=0.21"]
+
+[project.entry-points."hermes_agent.plugins"]
+totalreclaw = "totalreclaw.hermes"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

totalreclaw-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

totalreclaw-0.1.0/src/totalreclaw/__init__.py

@@ -0,0 +1,5 @@
+"""TotalReclaw — End-to-end encrypted memory for AI agents."""
+
+from .client import TotalReclaw
+
+__all__ = ["TotalReclaw"]

totalreclaw-0.1.0/src/totalreclaw/client.py

@@ -0,0 +1,242 @@
+"""
+TotalReclaw Client -- High-level API.
+
+Usage:
+    from totalreclaw import TotalReclaw
+
+    client = TotalReclaw(mnemonic="abandon abandon ...")
+    await client.remember("Pedro prefers dark mode")
+    results = await client.recall("What does Pedro prefer?")
+    await client.forget(results[0].id)
+    facts = await client.export_all()
+    status = await client.status()
+    await client.close()
+"""
+from __future__ import annotations
+from typing import Optional
+
+from .crypto import (
+    derive_keys_from_mnemonic,
+    derive_lsh_seed,
+    compute_auth_key_hash,
+    DerivedKeys,
+)
+from .lsh import LSHHasher
+from .relay import RelayClient, BillingStatus, DEFAULT_RELAY_URL
+from .reranker import RerankerResult
+from .operations import store_fact, search_facts, forget_fact, export_facts
+
+# Smart Account address derivation constants
+# These match the CREATE2 deterministic address generation used by
+# SimpleSmartAccount in the permissionless library
+SIMPLE_ACCOUNT_FACTORY = "0x91E60e0613810449d098b0b5Ec8b51A0FE8c8985"
+ENTRYPOINT_V07 = "0x0000000071727De22E5E9d8BAf0edAc6f37da032"
+
+
+def _get_eoa_account(mnemonic: str):
+    """Derive the EOA (externally-owned account) from a BIP-39 mnemonic.
+
+    Returns the full ``LocalAccount`` so callers can access both address and
+    private key.
+    """
+    from eth_account import Account
+    Account.enable_unaudited_hdwallet_features()
+    return Account.from_mnemonic(mnemonic.strip(), account_path="m/44'/60'/0'/0/0")
+
+
+def _get_eoa_address(mnemonic: str) -> str:
+    """Derive the EOA address from a BIP-39 mnemonic."""
+    return _get_eoa_account(mnemonic).address
+
+
+async def _derive_smart_account_address(mnemonic: str, rpc_url: str = "https://sepolia.base.org") -> str:
+    """Derive the CREATE2 Smart Account address by querying the factory contract.
+
+    Calls SimpleAccountFactory.getAddress(owner, 0) via eth_call on a public RPC.
+    This matches the `toSimpleSmartAccount` logic in permissionless/viem.
+
+    Factory: 0x91E60e0613810449d098b0b5Ec8b51A0FE8c8985 (v0.7)
+    Method: getAddress(address owner, uint256 salt) view returns (address)
+    """
+    import httpx
+
+    eoa_address = _get_eoa_address(mnemonic)
+
+    # ABI-encode: getAddress(address,uint256)
+    # keccak256("getAddress(address,uint256)")[:4] = 0x8cb84e18
+    selector = "8cb84e18"
+
+    # Pad owner address to 32 bytes and salt (0) to 32 bytes
+    owner_padded = eoa_address.lower().replace("0x", "").zfill(64)
+    salt_padded = "0" * 64
+
+    calldata = f"0x{selector}{owner_padded}{salt_padded}"
+
+    async with httpx.AsyncClient(timeout=15.0) as client:
+        resp = await client.post(
+            rpc_url,
+            json={
+                "jsonrpc": "2.0",
+                "method": "eth_call",
+                "params": [
+                    {"to": SIMPLE_ACCOUNT_FACTORY, "data": calldata},
+                    "latest",
+                ],
+                "id": 1,
+            },
+        )
+        result = resp.json().get("result", "")
+        if not result or result == "0x" or len(result) < 66:
+            # Fallback to EOA if RPC fails
+            return eoa_address.lower()
+        # Result is ABI-encoded address (32 bytes, last 20 bytes are the address)
+        address = "0x" + result[-40:]
+        return address.lower()
+
+
+class TotalReclaw:
+    """High-level TotalReclaw client with remember/recall/forget/export/status.
+
+    The wallet_address is the CREATE2 Smart Account address. If not provided,
+    call `await client.resolve_address()` before using remember/recall/forget/export
+    to derive it via an RPC call to the SimpleAccountFactory contract.
+    """
+
+    def __init__(
+        self,
+        mnemonic: str,
+        relay_url: str = DEFAULT_RELAY_URL,
+        wallet_address: Optional[str] = None,
+        is_test: bool = False,
+    ):
+        self._mnemonic = mnemonic.strip()
+        self._keys = derive_keys_from_mnemonic(self._mnemonic)
+        self._lsh_seed = derive_lsh_seed(self._mnemonic, self._keys.salt)
+        self._lsh_hasher: Optional[LSHHasher] = None
+        self._auth_key_hex = self._keys.auth_key.hex()
+        self._relay_url = relay_url
+
+        # Derive EOA account (address + private key) for UserOp signing
+        eoa_acct = _get_eoa_account(self._mnemonic)
+        self._eoa_address: str = eoa_acct.address
+        self._eoa_private_key: bytes = bytes(eoa_acct.key)
+
+        # Use provided address, or fall back to EOA (resolve_address fixes it later)
+        self._wallet_address = (wallet_address or self._eoa_address).lower()
+        self._address_resolved = wallet_address is not None
+        self._relay = RelayClient(
+            relay_url=relay_url,
+            auth_key_hex=self._auth_key_hex,
+            wallet_address=self._wallet_address,
+            is_test=is_test,
+        )
+        self._registered = False
+
+    async def resolve_address(self) -> str:
+        """Resolve the CREATE2 Smart Account address via RPC.
+
+        Must be called before remember/recall/forget/export if wallet_address
+        was not provided at construction time.
+        """
+        if self._address_resolved:
+            return self._wallet_address
+
+        self._wallet_address = await _derive_smart_account_address(self._mnemonic)
+        self._address_resolved = True
+        # Update relay client with resolved address
+        self._relay._wallet_address = self._wallet_address
+        return self._wallet_address
+
+    async def _ensure_address(self) -> None:
+        """Lazily resolve the Smart Account address if not yet done."""
+        if not self._address_resolved:
+            await self.resolve_address()
+
+    def _get_lsh_hasher(self, dims: int = 1024) -> LSHHasher:
+        if self._lsh_hasher is None:
+            self._lsh_hasher = LSHHasher(self._lsh_seed, dims)
+        return self._lsh_hasher
+
+    @property
+    def wallet_address(self) -> str:
+        return self._wallet_address
+
+    @property
+    def keys(self) -> DerivedKeys:
+        return self._keys
+
+    async def register(self) -> str:
+        """Register with the relay. Returns user_id."""
+        auth_hash = compute_auth_key_hash(self._keys.auth_key)
+        user_id = await self._relay.register(auth_hash, self._keys.salt.hex())
+        self._registered = True
+        return user_id
+
+    async def remember(
+        self,
+        text: str,
+        embedding: Optional[list[float]] = None,
+        importance: float = 0.5,
+        source: str = "python-client",
+    ) -> str:
+        """Store a fact. Returns the fact ID."""
+        await self._ensure_address()
+        lsh = self._get_lsh_hasher() if embedding else None
+        return await store_fact(
+            text=text,
+            keys=self._keys,
+            owner=self._wallet_address,
+            relay=self._relay,
+            lsh_hasher=lsh,
+            embedding=embedding,
+            importance=importance,
+            source=source,
+            eoa_private_key=self._eoa_private_key,
+            eoa_address=self._eoa_address,
+            sender=self._wallet_address,
+        )
+
+    async def recall(
+        self,
+        query: str,
+        query_embedding: Optional[list[float]] = None,
+        max_candidates: int = 250,
+        top_k: int = 8,
+    ) -> list[RerankerResult]:
+        """Search for facts matching a query. Returns ranked results."""
+        await self._ensure_address()
+        return await search_facts(
+            query=query,
+            keys=self._keys,
+            owner=self._wallet_address,
+            relay=self._relay,
+            query_embedding=query_embedding,
+            max_candidates=max_candidates,
+            top_k=top_k,
+        )
+
+    async def forget(self, fact_id: str) -> bool:
+        """Soft-delete a fact by writing a tombstone."""
+        await self._ensure_address()
+        return await forget_fact(
+            fact_id,
+            self._wallet_address,
+            self._relay,
+            eoa_private_key=self._eoa_private_key,
+            eoa_address=self._eoa_address,
+            sender=self._wallet_address,
+        )
+
+    async def export_all(self) -> list[dict]:
+        """Export all active facts, decrypted."""
+        await self._ensure_address()
+        return await export_facts(self._keys, self._wallet_address, self._relay)
+
+    async def status(self) -> BillingStatus:
+        """Get billing status."""
+        await self._ensure_address()
+        return await self._relay.get_billing_status()
+
+    async def close(self):
+        """Close the HTTP client."""
+        await self._relay.close()

totalreclaw-0.1.0/src/totalreclaw/crypto.py

@@ -0,0 +1,122 @@
+"""
+TotalReclaw E2EE crypto primitives.
+
+Delegates to the totalreclaw_core Rust/PyO3 module for all crypto operations.
+Maintains the same Python API for backward compatibility.
+"""
+from __future__ import annotations
+
+import base64
+import struct
+from dataclasses import dataclass
+
+import totalreclaw_core
+
+# ---------------------------------------------------------------------------
+# Key Derivation
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class DerivedKeys:
+    salt: bytes
+    auth_key: bytes
+    encryption_key: bytes
+    dedup_key: bytes
+
+
+def derive_keys_from_mnemonic(mnemonic: str) -> DerivedKeys:
+    """Derive all crypto keys from a BIP-39 mnemonic.
+
+    Delegates to totalreclaw_core (Rust/PyO3).
+    """
+    result = totalreclaw_core.derive_keys_from_mnemonic(mnemonic)
+    return DerivedKeys(
+        salt=result["salt"],
+        auth_key=result["auth_key"],
+        encryption_key=result["encryption_key"],
+        dedup_key=result["dedup_key"],
+    )
+
+
+def compute_auth_key_hash(auth_key: bytes) -> str:
+    """SHA-256(authKey) as hex string."""
+    return totalreclaw_core.compute_auth_key_hash(auth_key)
+
+
+def derive_lsh_seed(mnemonic: str, salt: bytes) -> bytes:
+    """Derive the 32-byte LSH seed."""
+    return totalreclaw_core.derive_lsh_seed(mnemonic, salt)
+
+
+# ---------------------------------------------------------------------------
+# AES-256-GCM Encryption / Decryption
+# ---------------------------------------------------------------------------
+
+
+def encrypt(plaintext: str, encryption_key: bytes) -> str:
+    """Encrypt with AES-256-GCM.
+
+    Wire format: iv(12) || tag(16) || ciphertext -> base64.
+    """
+    return totalreclaw_core.encrypt(plaintext, encryption_key)
+
+
+def decrypt(encrypted_base64: str, encryption_key: bytes) -> str:
+    """Decrypt AES-256-GCM.
+
+    Expects wire format: iv(12) || tag(16) || ciphertext.
+    """
+    return totalreclaw_core.decrypt(encrypted_base64, encryption_key)
+
+
+# ---------------------------------------------------------------------------
+# Blind Indices + Stemming
+# ---------------------------------------------------------------------------
+
+
+def generate_blind_indices(text: str) -> list[str]:
+    """Generate blind indices (SHA-256 hashes of tokens).
+
+    Tokenization rules (matches canonical TypeScript/Rust implementation):
+      1. Lowercase
+      2. Remove punctuation (keep Unicode letters, numbers, whitespace)
+      3. Split on whitespace
+      4. Filter tokens shorter than 2 characters
+
+    Each surviving token is SHA-256 hashed and returned as a hex string.
+    Stemmed variants are prefixed with "stem:" before hashing.
+    The returned array is deduplicated.
+    """
+    return totalreclaw_core.generate_blind_indices(text)
+
+
+# ---------------------------------------------------------------------------
+# Content Fingerprint (Dedup)
+# ---------------------------------------------------------------------------
+
+
+def generate_content_fingerprint(plaintext: str, dedup_key: bytes) -> str:
+    """HMAC-SHA256 content fingerprint. Returns 64-char hex string."""
+    return totalreclaw_core.generate_content_fingerprint(plaintext, dedup_key)
+
+
+# ---------------------------------------------------------------------------
+# Embedding Encryption
+# ---------------------------------------------------------------------------
+
+
+def encrypt_embedding(embedding: list[float], encryption_key: bytes) -> str:
+    """Encrypt embedding: pack as LE float32 array -> base64 -> AES encrypt."""
+    buf = struct.pack(f"<{len(embedding)}f", *embedding)
+    return encrypt(base64.b64encode(buf).decode("ascii"), encryption_key)
+
+
+def decrypt_embedding(
+    encrypted_embedding: str, encryption_key: bytes
+) -> list[float]:
+    """Decrypt embedding back to float array."""
+    decrypted_base64 = decrypt(encrypted_embedding, encryption_key)
+    buf = base64.b64decode(decrypted_base64)
+    count = len(buf) // 4
+    return list(struct.unpack(f"<{count}f", buf))