@totalreclaw/totalreclaw 1.0.0

package/SKILL.md

@@ -0,0 +1,687 @@
+---
+name: totalreclaw
+description: "Zero-knowledge encrypted memory vault for AI agents — the password manager for AI memory. Full E2EE: server never sees plaintext."
+version: 0.1.0
+author: TotalReclaw Team
+license: MIT
+homepage: https://github.com/p-diogo/totalreclaw
+metadata:
+  openclaw:
+    requires:
+      env: []
+      bins: []
+    emoji: "🧠"
+    os: ["macos", "linux", "windows"]
+    keywords:
+      - memory
+      - e2ee
+      - zero-knowledge
+      - encryption
+      - privacy
+      - agent-memory
+      - persistent-context
+---
+
+# TotalReclaw Skill
+
+## Tools
+
+### totalreclaw_remember
+
+Store a new fact or preference in long-term memory.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| text | string | Yes | The fact or information to remember |
+| type | string | No | Type of memory: `fact`, `preference`, `decision`, `episodic`, or `goal`. Default: `fact` |
+| importance | integer | No | Importance score 1-10. Default: auto-detected by LLM |
+
+**Example:**
+```json
+{
+  "text": "User prefers TypeScript over JavaScript for new projects",
+  "type": "preference",
+  "importance": 7
+}
+```
+
+**Returns:**
+```json
+{
+  "factId": "01234567-89ab-cdef-0123-456789abcdef",
+  "status": "stored",
+  "importance": 7,
+  "encrypted": true
+}
+```
+
+---
+
+### totalreclaw_recall
+
+Search and retrieve relevant memories from long-term storage.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| query | string | Yes | Natural language query to search memories |
+| k | integer | No | Number of results to return. Default: 8, Max: 20 |
+
+**Example:**
+```json
+{
+  "query": "What programming languages does the user prefer?",
+  "k": 5
+}
+```
+
+**Returns:**
+```json
+{
+  "memories": [
+    {
+      "factId": "01234567-89ab-cdef-0123-456789abcdef",
+      "factText": "User prefers TypeScript over JavaScript for new projects",
+      "type": "preference",
+      "importance": 7,
+      "timestamp": "2026-02-22T10:30:00Z",
+      "relevanceScore": 0.95
+    }
+  ],
+  "totalCandidates": 47,
+  "searchLatencyMs": 42
+}
+```
+
+---
+
+### totalreclaw_forget
+
+Delete a specific fact from memory.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| factId | string | Yes | UUID of the fact to delete |
+
+**Example:**
+```json
+{
+  "factId": "01234567-89ab-cdef-0123-456789abcdef"
+}
+```
+
+**Returns:**
+```json
+{
+  "status": "deleted",
+  "factId": "01234567-89ab-cdef-0123-456789abcdef",
+  "tombstoneExpiry": "2026-03-24T00:00:00Z"
+}
+```
+
+---
+
+### totalreclaw_export
+
+Export all stored memories in plaintext format.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| format | string | No | Export format: `json` or `markdown`. Default: `json` |
+
+**Example:**
+```json
+{
+  "format": "json"
+}
+```
+
+**Returns (JSON format):**
+```json
+{
+  "exportVersion": "0.3",
+  "exportedAt": "2026-02-22T10:30:00Z",
+  "totalFacts": 127,
+  "facts": [
+    {
+      "id": "...",
+      "factText": "...",
+      "type": "preference",
+      "importance": 7,
+      "timestamp": "...",
+      "entities": [...],
+      "relations": [...]
+    }
+  ],
+  "graph": {
+    "entities": {...},
+    "relations": [...]
+  }
+}
+```
+
+**Returns (Markdown format):**
+```markdown
+# TotalReclaw Export
+Exported: 2026-02-22T10:30:00Z
+Total Facts: 127
+
+## Preferences
+- User prefers TypeScript over JavaScript for new projects (importance: 7)
+
+## Decisions
+- User decided to use PostgreSQL for the main database (importance: 8)
+
+...
+```
+
+---
+
+### totalreclaw_status
+
+Check subscription status and usage quota.
+
+**Parameters:** None
+
+**Example:**
+```json
+{}
+```
+
+**Returns:**
+```json
+{
+  "tier": "Free",
+  "writesUsed": 42,
+  "writesLimit": 100,
+  "resetsAt": "2026-04-01",
+  "pricingUrl": "https://totalreclaw.xyz/pricing"
+}
+```
+
+---
+
+## Post-Install Setup
+
+After installing TotalReclaw, the agent MUST complete setup automatically. **Do NOT ask the user to set environment variables manually.**
+
+### Step 1: Set the server URL
+
+The TotalReclaw server URL is always `https://api.totalreclaw.xyz`. Set it in the OpenClaw config:
+
+```json
+{ "env": { "TOTALRECLAW_SERVER_URL": "https://api.totalreclaw.xyz" } }
+```
+
+### Step 2: Master password (recovery phrase)
+
+The master password is a **12-word BIP-39 mnemonic** — like a crypto wallet seed phrase. It derives all encryption keys. The server never sees it.
+
+Ask the user:
+> "Do you have an existing TotalReclaw recovery phrase you'd like to restore, or should I generate a new one?"
+
+- **New user:** Generate a random 12-word BIP-39 mnemonic and set it as `TOTALRECLAW_MASTER_PASSWORD`. Then display it prominently with a warning:
+  > "⚠️ SAVE YOUR RECOVERY PHRASE — it's the only way to recover your memories if you switch devices: `[phrase]`"
+- **Returning user:** Ask them to provide their existing 12-word phrase, then set it as `TOTALRECLAW_MASTER_PASSWORD`.
+
+### Step 3: Enable subgraph mode
+
+Set `TOTALRECLAW_SUBGRAPH_MODE=true` in the config to enable on-chain storage (required for beta).
+
+### Step 4: Set memory slot
+
+Register TotalReclaw as the memory plugin:
+```json
+{ "plugins": { "slots": { "memory": "totalreclaw" } } }
+```
+
+### Step 5: Restart and verify
+
+Restart the gateway, then confirm the plugin loaded by checking that `totalreclaw_remember`, `totalreclaw_recall`, `totalreclaw_forget`, and `totalreclaw_export` tools are available.
+
+### Step 6: Explain the free tier
+
+After setup completes, inform the user about the free tier:
+> "You're on TotalReclaw's free tier — 100 memory writes per month, unlimited reads and searches.
+> I'll let you know if you're approaching the limit. For unlimited writes, visit
+> https://totalreclaw.xyz/pricing"
+
+The agent proactively warns when quota usage exceeds 80%. If the limit is reached, new writes are rejected but all existing memories remain searchable.
+
+---
+
+## Description
+
+TotalReclaw is a zero-knowledge encrypted memory vault for AI agents. Think of it as a "password manager for AI memory" that provides:
+
+1. **End-to-End Encryption** - All memories are encrypted client-side using AES-256-GCM. The server never sees plaintext data.
+
+2. **Portable Memory** - Export all data as plaintext with one command. No vendor lock-in.
+
+3. **Universal Compatibility** - Works across any MCP-compatible AI agent, not just OpenClaw.
+
+4. **Intelligent Extraction** - Automatically extracts atomic facts, preferences, decisions, and goals from conversations.
+
+5. **Smart Decay** - Important memories persist; trivial ones fade over time using a decay algorithm.
+
+6. **Graph-Based** - Maintains entity relationships for multi-hop reasoning.
+
+---
+
+## Instructions for the LLM
+
+### IMPORTANT: Do Not Write Cleartext Memory Files
+
+TotalReclaw handles all memory storage with end-to-end encryption. **Do NOT write facts, preferences, or decisions to MEMORY.md or memory/*.md files.** All memories are stored encrypted on-chain and recalled automatically — writing cleartext files defeats the zero-knowledge guarantee.
+
+If you need to store a memory, use the `totalreclaw_remember` tool. If you need to recall memories, use `totalreclaw_recall`.
+
+### Billing Awareness
+
+TotalReclaw has a free tier (100 writes/month, unlimited reads). The plugin monitors quota usage automatically:
+- If usage exceeds 80%, a warning is injected into your context at conversation start
+- If a write fails with quota exceeded (403), inform the user and suggest visiting https://totalreclaw.xyz/pricing
+- Use `totalreclaw_status` when the user asks about their subscription, quota, or billing
+
+### When to Use Each Tool
+
+#### totalreclaw_remember
+
+Use when:
+- The user explicitly asks you to remember something ("remember that...", "note that...", "don't forget...")
+- You detect a significant preference, decision, or fact that will be useful in future conversations
+- The user corrects or updates previous information about themselves
+- You observe important context about the user's work, projects, or preferences
+
+Do NOT use for:
+- Temporary information relevant only to the current conversation
+- Information the user explicitly says is temporary
+- Generic knowledge that isn't user-specific
+
+#### totalreclaw_recall
+
+Use when:
+- The user asks about their past preferences, decisions, or history
+- You need context about the user's projects, tools, or working style
+- The user asks "do you remember..." or "what did I tell you about..."
+- You're unsure about a user preference and want to check before making assumptions
+- Starting a new conversation to load relevant context
+
+Do NOT use for:
+- Every single message (use sparingly, max once per conversation start or when explicitly relevant)
+- General knowledge questions unrelated to the user
+
+#### totalreclaw_forget
+
+Use when:
+- The user explicitly asks you to forget something ("forget that...", "delete that memory...")
+- The user indicates information is outdated or incorrect and should be removed
+- The user requests a clean slate for a specific topic
+
+#### totalreclaw_export
+
+Use when:
+- The user asks to export, backup, or download their memory data
+- The user wants to see everything you know about them
+- The user is migrating to another system
+
+---
+
+### Best Practices
+
+1. **Atomic Facts Only**: Each memory should be a single, atomic piece of information.
+   - Good: "User prefers dark mode in all editors"
+   - Bad: "User likes dark mode, uses VS Code, and works at Google"
+
+2. **Importance Scoring**:
+   - 1-3: Trivial, unlikely to matter (small talk, pleasantries)
+   - 4-6: Useful context (tool preferences, working style)
+   - 7-8: Important (key decisions, major preferences)
+   - 9-10: Critical (core values, non-negotiables, safety info)
+
+3. **Search Before Storing**: Always recall similar memories before storing new ones to avoid duplicates.
+
+4. **Respect User Privacy**: Never store sensitive information (passwords, API keys, personal secrets) even if requested.
+
+5. **Prefer NOOP**: When in doubt about whether to store something, prefer not storing it. Memory pollution is worse than missing a minor fact.
+
+---
+
+## Extraction Prompts (Mem0-Style)
+
+TotalReclaw uses a Mem0-style extraction pattern with four possible actions:
+
+### Actions
+
+| Action | Description | When to Use |
+|--------|-------------|-------------|
+| ADD | Store as new memory | No similar memory exists |
+| UPDATE | Modify existing memory | New info refines/clarifies existing |
+| DELETE | Remove existing memory | New info contradicts existing |
+| NOOP | Do nothing | Already captured or not worth storing |
+
+---
+
+### Pre-Compaction Extraction
+
+Triggered before OpenClaw's context compaction (typically every few hours in long sessions).
+
+**System Prompt:**
+
+```
+You are a memory extraction engine for an AI assistant. Your job is to analyze conversations and extract structured, atomic facts that should be remembered long-term.
+
+## Extraction Guidelines
+
+1. **Atomicity**: Each fact should be a single, atomic piece of information
+   - GOOD: "User prefers TypeScript over JavaScript for new projects"
+   - BAD: "User likes TypeScript, uses VS Code, and works at Google"
+
+2. **Types**:
+   - **fact**: Objective information about the user/world
+   - **preference**: User's likes, dislikes, or preferences
+   - **decision**: Choices the user has made
+   - **episodic**: Event-based memories (what happened when)
+   - **goal**: User's objectives or targets
+
+3. **Importance Scoring (1-10)**:
+   - 1-3: Trivial, unlikely to matter (small talk, pleasantries)
+   - 4-6: Useful context (tool preferences, working style)
+   - 7-8: Important (key decisions, major preferences)
+   - 9-10: Critical (core values, non-negotiables, safety info)
+
+4. **Confidence (0-1)**:
+   - How certain are you that this is accurate and worth storing?
+
+5. **Entities**: Extract named entities (people, projects, tools, concepts)
+   - Use stable IDs: hash of name+type (e.g., "typescript-tool")
+   - Types: person, project, tool, preference, concept, location, etc.
+
+6. **Relations**: Extract relationships between entities
+   - Common predicates: prefers, uses, works_on, decided_to_use, dislikes, etc.
+
+7. **Actions (Mem0 pattern)**:
+   - **ADD**: New fact, no conflict with existing memories
+   - **UPDATE**: Modifies or refines an existing fact (provide existingFactId)
+   - **DELETE**: Contradicts and replaces an existing fact
+   - **NOOP**: Not worth storing or already captured
+```
+
+**User Prompt Template:**
+
+```
+## Task: Pre-Compaction Memory Extraction
+
+You are reviewing the last 20 turns of conversation before they are compacted. Extract ALL valuable long-term memories.
+
+## Conversation History (last 20 turns):
+{{CONVERSATION_HISTORY}}
+
+## Existing Memories (for deduplication):
+{{EXISTING_MEMORIES}}
+
+## Instructions:
+1. Review each turn carefully for extractable information
+2. Extract atomic facts, preferences, decisions, episodic memories, and goals
+3. For each fact, determine if it's NEW (ADD), modifies existing (UPDATE), contradicts existing (DELETE), or is redundant (NOOP)
+4. Score importance based on long-term relevance
+5. Extract entities and relations
+
+## Output Format:
+Return a JSON object with:
+{
+  "facts": [
+    {
+      "factText": "string (max 512 chars)",
+      "type": "fact|preference|decision|episodic|goal",
+      "importance": 1-10,
+      "confidence": 0-1,
+      "action": "ADD|UPDATE|DELETE|NOOP",
+      "existingFactId": "string (if UPDATE/DELETE)",
+      "entities": [{"id": "...", "name": "...", "type": "..."}],
+      "relations": [{"subjectId": "...", "predicate": "...", "objectId": "...", "confidence": 0-1}]
+    }
+  ]
+}
+
+Focus on quality over quantity. Better to have 5 highly accurate facts than 20 noisy ones.
+```
+
+---
+
+### Post-Turn Extraction
+
+Triggered every N turns (configurable, default: 5) for lightweight extraction.
+
+**User Prompt Template:**
+
+```
+## Task: Quick Turn Extraction
+
+You are doing a lightweight extraction after a few turns. Focus ONLY on high-importance items.
+
+## Recent Turns (last 3):
+{{CONVERSATION_HISTORY}}
+
+## Existing Memories (top matches):
+{{EXISTING_MEMORIES}}
+
+## Instructions:
+1. Extract ONLY items with importance >= 7 (critical preferences, key decisions)
+2. Skip trivial information - this is a quick pass
+3. Use ADD/UPDATE/DELETE/NOOP appropriately
+4. Be aggressive about NOOP for low-value content
+
+## Output Format:
+Return a JSON object matching the extraction schema.
+
+Remember: Less is more. Only extract what truly matters.
+```
+
+---
+
+### Explicit Command Detection
+
+Detect when the user explicitly requests memory storage.
+
+**Trigger Patterns (regex + LLM classification):**
+
+```
+# Explicit memory commands
+"remember that..."
+"don't forget..."
+"note that..."
+"I prefer..."
+"for future reference..."
+"make a note..."
+"store this..."
+"keep in mind..."
+
+# Explicit forget commands
+"forget about..."
+"delete that memory..."
+"remove that from memory..."
+"stop remembering..."
+```
+
+**User Prompt Template:**
+
+```
+## Task: Explicit Memory Storage
+
+The user has explicitly requested to remember something. This is a HIGH PRIORITY extraction.
+
+## User's Explicit Request:
+{{USER_REQUEST}}
+
+## Conversation Context:
+{{CONVERSATION_CONTEXT}}
+
+## Instructions:
+1. Parse what the user wants remembered
+2. Boost importance by +1 (explicit requests matter more)
+3. Extract as atomic fact(s) with appropriate type
+4. Check against existing memories for UPDATE/DELETE
+5. Set confidence HIGH (user explicitly wants this stored)
+
+## Output Format:
+Return a JSON object matching the extraction schema.
+
+This is user-initiated storage - ensure accuracy and capture their intent precisely.
+```
+
+---
+
+### Deduplication Judge
+
+Used to determine ADD vs UPDATE vs DELETE vs NOOP for each extracted fact.
+
+**System Prompt:**
+
+```
+You are a memory deduplication judge. Your job is to determine if a new fact should be added as new, update an existing fact, delete/replace an existing fact, or be ignored as redundant.
+
+## Decision Rules:
+
+1. **ADD**: The fact is genuinely new information not covered by existing memories
+2. **UPDATE**: The fact refines, clarifies, or partially modifies an existing fact
+3. **DELETE**: The fact directly contradicts an existing fact and should replace it
+4. **NOOP**: The fact is already fully captured by existing memories
+
+Be strict about NOOP - if the information is essentially the same, mark it as NOOP.
+```
+
+**User Prompt Template:**
+
+```
+## New Fact to Evaluate:
+{{NEW_FACT}}
+
+## Similar Existing Facts:
+{{EXISTING_FACTS}}
+
+## Instructions:
+1. Compare the new fact against each existing fact
+2. Determine the appropriate action (ADD/UPDATE/DELETE/NOOP)
+3. If UPDATE or DELETE, identify which existing fact to modify
+4. Provide your confidence (0-1) and reasoning
+
+## Output Format:
+{
+  "decision": "ADD|UPDATE|DELETE|NOOP",
+  "existingFactId": "string (if UPDATE/DELETE)",
+  "confidence": 0-1,
+  "reasoning": "string"
+}
+```
+
+---
+
+## Configuration
+
+Default configuration values:
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `serverUrl` | `https://api.totalreclaw.xyz` | TotalReclaw server URL |
+| `autoExtractEveryTurns` | `5` | Turns between automatic extractions |
+| `minImportanceForAutoStore` | `6` | Minimum importance to auto-store |
+| `maxMemoriesInContext` | `8` | Maximum memories to inject into context |
+| `forgetThreshold` | `0.3` | Decay score threshold for eviction |
+| `decayHalfLifeDays` | `30` | Memory decay half-life in days |
+
+---
+
+## Privacy & Security
+
+- **Zero-Knowledge**: All encryption happens client-side. The server never sees plaintext.
+- **Master Password**: Never sent to the server. Used only for key derivation (Argon2id).
+- **Export Portability**: Full plaintext export available anytime.
+- **Tombstone Recovery**: Deleted memories can be recovered within 30 days.
+
+---
+
+## Lifecycle Hooks
+
+TotalReclaw integrates with OpenClaw through three lifecycle hooks:
+
+| Hook | Priority | Description |
+|------|----------|-------------|
+| `before_agent_start` | 10 | Retrieve relevant memories before agent processes message |
+| `agent_end` | 90 | Extract and store facts after agent completes turn |
+| `pre_compaction` | 5 | Full memory flush before context compaction |
+
+---
+
+## Example Usage
+
+### Storing a preference
+
+```json
+// Tool call
+{
+  "tool": "totalreclaw_remember",
+  "params": {
+    "text": "User prefers functional programming over OOP",
+    "type": "preference",
+    "importance": 6
+  }
+}
+
+// Response
+{
+  "factId": "abc123",
+  "status": "stored"
+}
+```
+
+### Recalling memories
+
+```json
+// Tool call
+{
+  "tool": "totalreclaw_recall",
+  "params": {
+    "query": "programming preferences",
+    "k": 5
+  }
+}
+
+// Response
+{
+  "memories": [
+    {
+      "factId": "abc123",
+      "factText": "User prefers functional programming over OOP",
+      "type": "preference",
+      "importance": 6,
+      "relevanceScore": 0.92
+    }
+  ]
+}
+```
+
+### Forgetting a memory
+
+```json
+// Tool call
+{
+  "tool": "totalreclaw_forget",
+  "params": {
+    "factId": "abc123"
+  }
+}
+
+// Response
+{
+  "status": "deleted",
+  "factId": "abc123"
+}
+```