@totalreclaw/totalreclaw 1.0.4 → 1.1.0

package/README.md

@@ -1,104 +1,85 @@
-# TotalReclaw
+# @totalreclaw/totalreclaw
 
-Zero-knowledge encrypted memory vault for AI agents. Your agent remembers -- only you can read it.
+Encrypted memory for your AI agent — zero-knowledge E2EE vault with automatic extraction, semantic search, and portable storage.
 
-## What it does
+Built for [OpenClaw](https://openclaw.ai). Your memories are encrypted on your device before leaving — no one can read them, not even us.
 
-TotalReclaw gives your AI agent persistent, encrypted memory that works across sessions and devices. Memories are encrypted on your device before they reach any server. Not even TotalReclaw can read your data.
-
-- **True zero-knowledge E2EE** -- Client-side AES-256-GCM encryption. The server only sees encrypted blobs.
-- **Portable** -- One-click plaintext export. No vendor lock-in.
-- **Automatic** -- Memory extraction and recall happen via lifecycle hooks. No manual commands needed.
-- **Cross-device** -- Same 12-word recovery phrase restores all your memories on any device.
-- **98.1% recall** -- Blind-index search with BM25 + cosine + RRF fusion reranking.
-- **Free tier** -- 100 writes/month, unlimited reads. Upgrade at [totalreclaw.xyz/pricing](https://totalreclaw.xyz/pricing).
+**[totalreclaw.xyz](https://totalreclaw.xyz)**
 
 ## Install
 
-### OpenClaw (recommended)
-
-```
+```bash
 openclaw plugins install @totalreclaw/totalreclaw
 ```
 
-Or just ask your OpenClaw agent:
+Or just ask your agent:
+
 > "Install the totalreclaw plugin"
 
-The plugin sets itself up on first run -- it will ask if you have an existing recovery phrase or need a new one.
+The agent handles setup: generates your encryption keys and registers you. You'll be asked to write down a 12-word recovery phrase — that's the only thing you need to keep safe.
 
-### Other MCP-compatible agents
+## How It Works
 
-TotalReclaw also ships a standalone MCP server for Claude Desktop, Cursor, and others. See [totalreclaw.xyz](https://totalreclaw.xyz) for setup instructions.
+After setup, memory is **fully automatic**:
 
-## How it works
+- **Start of conversation** — loads relevant memories from your vault
+- **End of conversation** — extracts and encrypts new facts before storing them
+- **Before context compaction** — saves everything important before the context window is trimmed
 
-1. **Install** -- Add the plugin and set a recovery phrase (12-word BIP-39 mnemonic).
-2. **Talk normally** -- TotalReclaw automatically extracts facts, preferences, and decisions from your conversations, encrypts them client-side, and stores them on-chain.
-3. **Recall** -- At the start of each new conversation, relevant memories are decrypted and injected into context. You can also search explicitly with the `totalreclaw_recall` tool.
-4. **Export anytime** -- `totalreclaw_export` dumps all your memories as plaintext JSON or Markdown. Your data, your format.
+All encryption happens client-side using AES-256-GCM. Search uses blind indices (SHA-256 hashes) — the server never sees your queries or data. Your 12-word recovery phrase derives all keys via Argon2id + HKDF.
 
 ## Tools
 
-| Tool | What it does |
+Your agent gets these tools automatically:
+
+| Tool | Description |
 |------|-------------|
-| `totalreclaw_remember` | Store a fact, preference, or decision |
-| `totalreclaw_recall` | Search and retrieve relevant memories |
-| `totalreclaw_forget` | Delete a specific memory (on-chain tombstone) |
+| `totalreclaw_remember` | Manually store a fact |
+| `totalreclaw_recall` | Search memories by natural language |
+| `totalreclaw_forget` | Delete a specific memory |
 | `totalreclaw_export` | Export all memories as plaintext |
-| `totalreclaw_status` | Check subscription tier and quota |
-| `totalreclaw_generate_recovery_phrase` | Generate a secure 12-word BIP-39 mnemonic (onboarding) |
-
-## Lifecycle hooks
+| `totalreclaw_status` | Check billing status and quota |
 
-| Hook | When | What |
-|------|------|------|
-| `before_agent_start` | Every conversation | Recalls relevant memories and injects them into context |
-| `agent_end` | After each turn | Extracts new facts from the conversation |
-| `pre_compaction` | Before context compaction | Full memory extraction to prevent data loss |
+Most of the time you won't use these directly — the automatic hooks handle memory for you.
 
-## Recovery phrase
+## Features
 
-Your recovery phrase is a 12-word BIP-39 mnemonic -- like a crypto wallet seed. It derives all encryption keys locally. The server never sees it.
+- **Zero-knowledge E2EE** — AES-256-GCM encryption, blind index search, HKDF auth
+- **Semantic search** — Local embeddings (bge-small-en-v1.5) + BM25 + cosine reranking with RRF
+- **Automatic extraction** — LLM extracts facts from conversations, no manual input needed
+- **Dedup** — Cosine similarity catches paraphrases; LLM-guided dedup catches contradictions (Pro)
+- **On-chain storage** — Encrypted data stored on Gnosis Chain, indexed by The Graph
+- **Portable** — One 12-word phrase. Any device, same memories, no lock-in
+- **Import** — Migrate from Mem0 or MCP Memory Server
 
-- **New user**: The plugin generates a random phrase and displays it once. Save it somewhere safe.
-- **Returning user**: Enter your existing phrase to restore all your memories on a new device.
-- **Lost phrase**: Memories cannot be recovered. This is the zero-knowledge guarantee.
+## Free Tier & Pricing
 
-## Privacy and security
+| Tier | Writes | Reads | Price |
+|------|--------|-------|-------|
+| **Free** | 250/month | Unlimited | $0 |
+| **Pro** | 10,000/month | Unlimited | $2-5/month |
 
-- All encryption happens client-side (AES-256-GCM + HKDF key derivation)
-- The server stores only encrypted blobs and blind indices
-- On-chain storage via Gnosis Chain (The Graph subgraph) -- fully auditable
-- Master password never leaves your device
-- One-click plaintext export -- no vendor lock-in
+Pay with card (Stripe) or crypto (Coinbase Commerce). Counter resets monthly.
 
 ## Configuration
 
-| Environment variable | Default | Description |
-|---------------------|---------|-------------|
-| `TOTALRECLAW_MASTER_PASSWORD` | *(required)* | 12-word BIP-39 recovery phrase |
-| `TOTALRECLAW_SERVER_URL` | `https://api.totalreclaw.xyz` | Relay server URL |
-| `TOTALRECLAW_SUBGRAPH_MODE` | `true` | Enable on-chain storage |
-| `TOTALRECLAW_EXTRACT_EVERY_TURNS` | `5` | Turns between automatic extractions |
+Set these environment variables before the agent starts:
 
-## Comparison
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `TOTALRECLAW_SERVER_URL` | Server URL | `https://api.totalreclaw.xyz` |
+| `TOTALRECLAW_CREDENTIALS_PATH` | Path to credentials file | `~/.totalreclaw/credentials.json` |
+| `TOTALRECLAW_SELF_HOSTED` | Set to `true` to use your own self-hosted server instead of the managed service | `false` (managed service) |
+| `TOTALRECLAW_EXTRACT_EVERY_TURNS` | Auto-extract interval (turns) | `5` (Free) / `2` (Pro min) |
 
-| Feature | TotalReclaw | Mem0 |
-|---------|-------------|------|
-| Encryption | Client-side (zero-knowledge) | Server-side (server can read) |
-| Data portability | One-click plaintext export | No export |
-| Key management | BIP-39 seed phrase (user-controlled) | Server-managed keys |
-| Search method | Blind-index + encrypted reranking | Plaintext vector search |
-| On-chain storage | Yes (Gnosis Chain subgraph) | No |
-| Cross-device | Same seed = same memories | Tied to account |
+## Using with Other Agents
 
-The fundamental difference: with TotalReclaw, even a compromised server reveals nothing.
+TotalReclaw also works outside OpenClaw:
 
-## Links
+- **Claude Desktop / Cursor / Windsurf** — Use [@totalreclaw/mcp-server](https://www.npmjs.com/package/@totalreclaw/mcp-server)
+- **NanoClaw** — Lightweight skill with MCP bridge
 
-- [Website](https://totalreclaw.xyz)
-- [Documentation](https://github.com/p-diogo/totalreclaw)
-- [Pricing](https://totalreclaw.xyz/pricing)
+Same encryption, same recovery phrase, same memories across all agents.
 
 ## License
 

package/api-client.ts

@@ -0,0 +1,328 @@
+/**
+ * TotalReclaw Plugin - HTTP API Client
+ *
+ * Communicates with the TotalReclaw server over JSON/HTTP. Uses Node.js
+ * built-in `fetch` (available since Node 18).
+ *
+ * All authenticated endpoints expect:
+ *   Authorization: Bearer <hex-encoded-auth-key>
+ *
+ * The server hashes the auth key with SHA-256 to look up the user.
+ */
+
+// ---------------------------------------------------------------------------
+// Request / Response Types
+// ---------------------------------------------------------------------------
+
+/**
+ * A single fact payload for the `/v1/store` endpoint.
+ *
+ * Field naming matches the server's `FactJSON` Pydantic model in
+ * `server/src/handlers/store.py`.
+ */
+export interface StoreFactPayload {
+  /** UUIDv7 fact identifier */
+  id: string;
+  /** ISO 8601 timestamp */
+  timestamp: string;
+  /** Hex-encoded AES-256-GCM ciphertext (iv || tag || ciphertext) */
+  encrypted_blob: string;
+  /** SHA-256 hashes of tokens for blind search */
+  blind_indices: string[];
+  /** Importance / decay score (0-10) */
+  decay_score: number;
+  /** Origin label */
+  source: string;
+  /** HMAC-SHA256 content fingerprint for dedup (hex) */
+  content_fp?: string;
+  /** Identifier of the creating agent */
+  agent_id?: string;
+  /** Hex-encoded AES-256-GCM encrypted embedding vector (PoC v2) */
+  encrypted_embedding?: string;
+}
+
+/**
+ * A search result candidate returned by `/v1/search`.
+ *
+ * Field naming matches the server's `SearchResultJSON` model.
+ */
+export interface SearchCandidate {
+  fact_id: string;
+  /** Hex-encoded AES-256-GCM ciphertext */
+  encrypted_blob: string;
+  decay_score: number;
+  /** Unix milliseconds */
+  timestamp: number;
+  version: number;
+  /** Hex-encoded AES-256-GCM encrypted embedding vector (PoC v2, optional) */
+  encrypted_embedding?: string;
+}
+
+/**
+ * A fact object returned by `/v1/export`.
+ */
+export interface ExportedFact {
+  id: string;
+  encrypted_blob: string;
+  blind_indices: string[];
+  decay_score: number;
+  version: number;
+  source: string;
+  created_at: string;
+  updated_at: string;
+}
+
+// ---------------------------------------------------------------------------
+// API Client Factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Create an API client bound to a specific TotalReclaw server URL.
+ *
+ * All methods are async and throw descriptive errors on non-2xx responses.
+ */
+export function createApiClient(serverUrl: string) {
+  // Normalise URL -- strip trailing slash.
+  const baseUrl = serverUrl.replace(/\/+$/, '');
+
+  // ------------------------------------------------------------------
+  // Shared helpers
+  // ------------------------------------------------------------------
+
+  /**
+   * Throw a descriptive error when the server returns a non-2xx status.
+   */
+  async function assertOk(res: Response, context: string): Promise<void> {
+    if (res.ok) return;
+    let body: string;
+    try {
+      body = await res.text();
+    } catch {
+      body = '(could not read response body)';
+    }
+    const hint = res.status === 401
+      ? ' Authentication failed. If using a recovery phrase, check that all 12 words are in the correct order and spelled correctly.'
+      : '';
+    throw new Error(`${context}: HTTP ${res.status} - ${body}${hint}`);
+  }
+
+  // ------------------------------------------------------------------
+  // Public methods
+  // ------------------------------------------------------------------
+
+  return {
+    // ---- Registration (unauthenticated) ----
+
+    /**
+     * Register a new user.
+     *
+     * @param authKeyHash  Hex-encoded SHA-256 of the auth key (64 chars).
+     * @param saltHex      Hex-encoded 32-byte salt (64 chars).
+     * @returns `{ user_id }` on success.
+     */
+    async register(
+      authKeyHash: string,
+      saltHex: string,
+    ): Promise<{ user_id: string }> {
+      const res = await fetch(`${baseUrl}/v1/register`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ auth_key_hash: authKeyHash, salt: saltHex }),
+      });
+      await assertOk(res, 'register');
+      const json = (await res.json()) as Record<string, unknown>;
+      if (!json.success && json.error_code !== 'USER_EXISTS') {
+        throw new Error(
+          `register: server returned success=false - ${json.error_code}: ${json.error_message}`,
+        );
+      }
+      if (!json.user_id) {
+        throw new Error(
+          `register: server did not return user_id (error_code=${json.error_code})`,
+        );
+      }
+      return { user_id: json.user_id as string };
+    },
+
+    // ---- Store (authenticated) ----
+
+    /**
+     * Store one or more encrypted facts.
+     *
+     * @param userId       The authenticated user's ID.
+     * @param facts        Array of `StoreFactPayload` objects.
+     * @param authKeyHex   Hex-encoded raw auth key (64 chars) for Bearer header.
+     */
+    async store(
+      userId: string,
+      facts: StoreFactPayload[],
+      authKeyHex: string,
+    ): Promise<{ ids: string[]; duplicate_ids?: string[] }> {
+      const res = await fetch(`${baseUrl}/v1/store`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          Authorization: `Bearer ${authKeyHex}`,
+        },
+        body: JSON.stringify({ user_id: userId, facts }),
+      });
+      await assertOk(res, 'store');
+      const json = (await res.json()) as Record<string, unknown>;
+      if (!json.success) {
+        throw new Error(
+          `store: server returned success=false - ${json.error_code}: ${json.error_message}`,
+        );
+      }
+      return {
+        ids: (json.ids as string[]) ?? [],
+        duplicate_ids: json.duplicate_ids as string[] | undefined,
+      };
+    },
+
+    // ---- Search (authenticated) ----
+
+    /**
+     * Search for facts using blind trapdoors.
+     *
+     * @param userId         The authenticated user's ID.
+     * @param trapdoors      SHA-256 hex hashes of query tokens.
+     * @param maxCandidates  Maximum candidates to retrieve.
+     * @param authKeyHex     Hex-encoded raw auth key for Bearer header.
+     * @returns Array of encrypted search candidates.
+     */
+    async search(
+      userId: string,
+      trapdoors: string[],
+      maxCandidates: number,
+      authKeyHex: string,
+    ): Promise<SearchCandidate[]> {
+      const res = await fetch(`${baseUrl}/v1/search`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          Authorization: `Bearer ${authKeyHex}`,
+        },
+        body: JSON.stringify({
+          user_id: userId,
+          trapdoors,
+          max_candidates: maxCandidates,
+        }),
+      });
+      await assertOk(res, 'search');
+      const json = (await res.json()) as Record<string, unknown>;
+      if (!json.success) {
+        throw new Error(
+          `search: server returned success=false - ${json.error_code}: ${json.error_message}`,
+        );
+      }
+      return (json.results as SearchCandidate[]) ?? [];
+    },
+
+    // ---- Delete (authenticated) ----
+
+    /**
+     * Soft-delete a fact by ID.
+     *
+     * @param factId      The fact UUID to delete.
+     * @param authKeyHex  Hex-encoded raw auth key for Bearer header.
+     */
+    async deleteFact(factId: string, authKeyHex: string): Promise<void> {
+      const res = await fetch(`${baseUrl}/v1/facts/${encodeURIComponent(factId)}`, {
+        method: 'DELETE',
+        headers: {
+          Authorization: `Bearer ${authKeyHex}`,
+        },
+      });
+      await assertOk(res, 'deleteFact');
+      const json = (await res.json()) as Record<string, unknown>;
+      if (!json.success) {
+        throw new Error(
+          `deleteFact: server returned success=false - ${json.error_code}: ${json.error_message}`,
+        );
+      }
+    },
+
+    // ---- Batch Delete (authenticated) ----
+
+    /**
+     * Batch soft-delete facts by ID list.
+     *
+     * @param factIds     Array of fact UUIDs to delete (max 500).
+     * @param authKeyHex  Hex-encoded raw auth key for Bearer header.
+     * @returns The number of facts that were actually deleted.
+     */
+    async batchDelete(factIds: string[], authKeyHex: string): Promise<number> {
+      const res = await fetch(`${baseUrl}/v1/facts/batch-delete`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          Authorization: `Bearer ${authKeyHex}`,
+        },
+        body: JSON.stringify({ fact_ids: factIds }),
+      });
+      await assertOk(res, 'batchDelete');
+      const json = (await res.json()) as Record<string, unknown>;
+      if (!json.success) {
+        throw new Error(
+          `batchDelete: server returned success=false - ${json.error_code}: ${json.error_message}`,
+        );
+      }
+      return (json.deleted_count as number) ?? 0;
+    },
+
+    // ---- Export (authenticated) ----
+
+    /**
+     * Export all active facts (paginated).
+     *
+     * @param authKeyHex  Hex-encoded raw auth key for Bearer header.
+     * @param limit       Page size (default 1000, max 5000).
+     * @param cursor      Cursor from previous page (omit for first page).
+     * @returns Page of facts with pagination metadata.
+     */
+    async exportFacts(
+      authKeyHex: string,
+      limit: number = 1000,
+      cursor?: string,
+    ): Promise<{ facts: ExportedFact[]; cursor?: string; has_more: boolean; total_count?: number }> {
+      const params = new URLSearchParams({ limit: String(limit) });
+      if (cursor) params.set('cursor', cursor);
+
+      const res = await fetch(`${baseUrl}/v1/export?${params.toString()}`, {
+        method: 'GET',
+        headers: {
+          Authorization: `Bearer ${authKeyHex}`,
+        },
+      });
+      await assertOk(res, 'exportFacts');
+      const json = (await res.json()) as Record<string, unknown>;
+      if (!json.success) {
+        throw new Error(
+          `exportFacts: server returned success=false - ${json.error_code}: ${json.error_message}`,
+        );
+      }
+      return {
+        facts: (json.facts as ExportedFact[]) ?? [],
+        cursor: json.cursor as string | undefined,
+        has_more: (json.has_more as boolean) ?? false,
+        total_count: json.total_count as number | undefined,
+      };
+    },
+
+    // ---- Health (unauthenticated) ----
+
+    /**
+     * Check server health.
+     *
+     * @returns `true` if the server responds with HTTP 200.
+     */
+    async health(): Promise<boolean> {
+      try {
+        const res = await fetch(`${baseUrl}/health`, { method: 'GET' });
+        return res.status === 200;
+      } catch {
+        return false;
+      }
+    },
+  };
+}