@totalreclaw/totalreclaw 1.0.5 → 1.2.0

package/README.md

@@ -1,122 +1,102 @@
-# TotalReclaw
+<p align="center">
+  <img src="../../docs/assets/logo.png" alt="TotalReclaw" width="80" />
+</p>
 
-Zero-knowledge encrypted memory vault for AI agents. Your agent remembers -- only you can read it.
+<h1 align="center">@totalreclaw/totalreclaw</h1>
 
-## What it does
+<p align="center">
+  <strong>End-to-end encrypted memory for OpenClaw -- fully automatic, yours forever</strong>
+</p>
 
-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.
+<p align="center">
+  <a href="https://totalreclaw.xyz">Website</a> &middot;
+  <a href="https://www.npmjs.com/package/@totalreclaw/totalreclaw">npm</a> &middot;
+  <a href="../../docs/guides/beta-tester-guide.md">Getting Started</a>
+</p>
 
-- **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).
+<p align="center">
+  <a href="https://www.npmjs.com/package/@totalreclaw/totalreclaw"><img src="https://img.shields.io/npm/v/@totalreclaw/totalreclaw?color=7B5CFF" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/@totalreclaw/totalreclaw"><img src="https://img.shields.io/npm/dm/@totalreclaw/totalreclaw" alt="npm downloads"></a>
+  <a href="../../LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="License"></a>
+</p>
+
+---
+
+Your AI agent remembers everything -- preferences, decisions, facts -- encrypted so only you can read it. Built for [OpenClaw](https://openclaw.ai) with fully automatic memory extraction and recall.
 
 ## Install
 
-### OpenClaw (recommended)
+Ask your OpenClaw agent:
 
-```
+> "Install the @totalreclaw/totalreclaw plugin"
+
+Or from the terminal:
+
+```bash
 openclaw plugins install @totalreclaw/totalreclaw
 ```
 
-Or just ask your OpenClaw 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, asks you to save a 12-word recovery phrase, and registers you. After that, memory is fully automatic.
 
-### 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, everything happens in the background:
 
-## How it works
+- **Start of conversation** -- loads relevant memories from your encrypted vault
+- **During conversation** -- extracts facts, preferences, and decisions automatically
+- **Before context compaction** -- saves important context before the 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. The server never sees your plaintext data.
 
 ## 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
-
-| 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 |
-
-## Recovery phrase
-
-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.
-
-- **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.
-
-## Privacy and security
+| `totalreclaw_status` | Check billing status and quota |
+| `totalreclaw_consolidate` | Merge duplicate memories |
+| `totalreclaw_import_from` | Import from Mem0 or MCP Memory Server |
 
-- 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
+Most of the time you won't use these directly -- the automatic hooks handle memory for you.
 
-## Configuration
+## Features
 
-| 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 |
+- **End-to-end encrypted** -- AES-256-GCM encryption, blind index search, HKDF auth
+- **Automatic extraction** -- LLM extracts facts from conversations, no manual input needed
+- **Semantic search** -- Local embeddings + BM25 + cosine reranking with RRF fusion
+- **Smart 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
 
-## How TotalReclaw compares
+## Free Tier & Pricing
 
-Every AI memory tool stores your data on a server that can read it. TotalReclaw is the only one that encrypts on your device first -- a compromised server reveals nothing.
+| Tier | Memories | Reads | Storage | Price |
+|------|----------|-------|---------|-------|
+| **Free** | 500/month | Unlimited | Testnet (trial) | $0 |
+| **Pro** | Unlimited | Unlimited | Permanent on-chain (Gnosis) | $5/month |
 
-| | TotalReclaw | Mem0 | Zep | Letta | MCP Memory | memU |
-|---|---|---|---|---|---|---|
-| **Server sees plaintext** | Never | Yes | Yes | Yes | N/A (local) | Yes |
-| **Client-side E2EE** | AES-256-GCM | No | No | No | No | No |
-| **Cross-device sync** | Seed phrase | Account | Account | Account | No | Account |
-| **Data export** | One-click plaintext | JSON (7-day link) | No | Via API | Copy file | No |
-| **On-chain storage** | Gnosis Chain | No | No | No | No | No |
-| **Self-hostable** | Yes | Yes | No | Yes | Yes (local) | Yes |
-| **OpenClaw plugin** | Yes | Yes | No | No | No | Yes |
-| **MCP server** | Yes | Yes | No | No | Yes | No |
-| **Knowledge graph** | No | Yes ($249/mo) | Yes | Yes | Simple | No |
-| **Free tier** | 100 writes/mo | 10K memories | 1K credits | 3 agents | Unlimited | Varies |
+Pay with card via Stripe. Counter resets monthly.
 
-### Where TotalReclaw wins
+## Using with Other Agents
 
-- **Zero-knowledge encryption** -- No other memory tool encrypts client-side. Mem0 and Zep offer SOC 2 and HIPAA, but their servers still process your plaintext. TotalReclaw's server only ever sees encrypted blobs.
-- **Seed-phrase portability** -- One 12-word phrase, any device, any agent. No accounts, no passwords, no vendor. Works like a crypto wallet.
-- **On-chain anchoring** -- Memories are stored on Gnosis Chain and indexed by The Graph. No single server controls your data.
-- **True data ownership** -- One-click plaintext export. No 7-day expiry links, no API-only access. Your data, your format.
+TotalReclaw also works outside OpenClaw:
 
-### Where others win
+- **Claude Desktop / Cursor / Windsurf** -- Use [@totalreclaw/mcp-server](https://www.npmjs.com/package/@totalreclaw/mcp-server)
+- **NanoClaw** -- Built-in support via MCP bridge
 
-- **Knowledge graphs** -- Zep's temporal graph tracks how facts evolve over time. Mem0's graph memory ($249/mo) maps entity relationships. TotalReclaw can't build graphs because the server can't read the data -- that's the privacy trade-off.
-- **Ecosystem maturity** -- Mem0 has 49K GitHub stars, $24M in funding, and integrations with every major framework. TotalReclaw is a beta product.
-- **Offline simplicity** -- The official MCP Memory Server and Engram need zero network, zero accounts, zero setup. Good enough for single-device use.
-- **Enterprise compliance** -- Mem0 and Zep offer SOC 2, HIPAA, RBAC, SSO. TotalReclaw doesn't need most of these (zero-knowledge means there's nothing to comply about), but enterprises want the paperwork.
+Same encryption, same recovery phrase, same memories across all agents.
 
-## Links
+## Learn More
 
-- [Website](https://totalreclaw.xyz)
-- [Documentation](https://github.com/p-diogo/totalreclaw)
-- [Pricing](https://totalreclaw.xyz/pricing)
+- [Getting Started Guide](../../docs/guides/beta-tester-guide.md)
+- [totalreclaw.xyz](https://totalreclaw.xyz)
+- [Main Repository](https://github.com/p-diogo/totalreclaw)
 
 ## 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;
+      }
+    },
+  };
+}