TotalReclaw Skill for OpenClaw

End-to-end encrypted memory + knowledge graph for AI agents -- portable, yours forever.

Your AI remembers everything. Your server sees nothing.

TotalReclaw gives any OpenClaw agent persistent, encrypted long-term memory. Preferences, decisions, commitments, rules, and context carry across every conversation -- fully end-to-end encrypted so the server never sees plaintext.

v3.0.0 ships Memory Taxonomy v1: every memory is typed (claim / preference / directive / commitment / episode / summary) and tagged with source, scope, and volatility. Recall uses source-weighted reranking so user-authored claims consistently rank above assistant-regurgitated noise. See docs/guides/memory-types-guide.md.

Installation

ClawHub (recommended)

Tell your OpenClaw agent:

"Install the TotalReclaw skill from ClawHub"

Or via terminal:

openclaw skills install totalreclaw

Then set one environment variable:

export TOTALRECLAW_RECOVERY_PHRASE="your twelve word recovery phrase here"

That's it. TotalReclaw hooks into your agent automatically. The server URL defaults to https://api.totalreclaw.xyz (managed service) -- only set TOTALRECLAW_SERVER_URL if you are self-hosting. See the env vars reference for the full (short) list.

Alternative: npm

openclaw plugins install @totalreclaw/totalreclaw

Why TotalReclaw?

Most AI memory solutions force a tradeoff: good recall OR privacy. TotalReclaw eliminates that tradeoff.

98.1% recall with 100% privacy -- tested against 8,727 real-world memories. The server never sees your data, yet search quality is within 1.1% of plaintext alternatives.

Key Differentiators

• True end-to-end encryption: XChaCha20-Poly1305 encryption, Argon2id key derivation, HKDF-SHA256 auth. The server is cryptographically unable to read your memories.
• Near-plaintext recall: LSH blind indices with client-side BM25 + cosine + RRF reranking achieve 98.1% recall@8.
• No vendor lock-in: One-click plaintext export in JSON or Markdown. Your data is always yours.
• Works everywhere: Any MCP-compatible AI agent, not just OpenClaw.

Features

• End-to-End Encryption: XChaCha20-Poly1305 ensures the server never sees plaintext memories
• Memory Taxonomy v1: 6 speech-act types + source / scope / volatility axes on every memory. Learn more
• Intelligent Extraction: G-pipeline — single merged-topic LLM call, provenance filter, comparative rescoring, volatility heuristic. v1 is the only write path.
• Semantic Search: LSH blind indices with client-side BM25 + cosine + RRF fusion reranking
• Retrieval v2 Tier 1: Source-weighted reranking — user=1.0, user-inferred=0.9, derived/external=0.7, assistant=0.55
• Lifecycle Hooks: Seamlessly integrates with OpenClaw's agent lifecycle (before_agent_start, agent_end, pre_compaction, before_reset)
• Natural-language overrides: "pin that", "that was actually a rule, not a preference", "file that under work" — agent calls the right tool automatically
• Portable Export: One-click plaintext export -- no vendor lock-in
• Decay Management: Automatic memory decay with configurable thresholds

Quick Start

1. Install

Tell your OpenClaw agent:

"Install the TotalReclaw skill from ClawHub"

Or via terminal:

openclaw skills install totalreclaw

Alternative (npm):

openclaw plugins install @totalreclaw/totalreclaw

2. Configure

Set one environment variable:

export TOTALRECLAW_RECOVERY_PHRASE="your twelve word recovery phrase here"

That's it. v1 is the default extraction and write path. Extraction cadence, importance floor, candidate pool size, and dedup thresholds are all server-tuned via the relay's billing response -- no client env vars to set. See env vars reference.

For self-hosted deployments:

export TOTALRECLAW_SERVER_URL="http://your-totalreclaw-server:8080"
export TOTALRECLAW_SELF_HOSTED=true

3. Use

Once installed, TotalReclaw hooks into your agent lifecycle automatically. No code changes needed.

Your agent will:

• Load relevant memories before processing each message (before_agent_start)
• Extract and store facts after each turn (agent_end)
• Flush all memories before context compaction (pre_compaction)

You can also use the tools directly in conversation:

"Remember that I prefer dark mode in all editors"
"What do you know about my programming preferences?"
"Forget the memory about my old email address"
"Export all my memories as JSON"

Tools

The plugin exposes these tools to your OpenClaw agent. Most invocations happen via natural language -- the agent picks the right tool from context.

totalreclaw_remember

Explicitly store a memory. Accepts v1 taxonomy fields.

const result = await skill.remember({
  text: 'User prefers dark mode',
  type: 'preference',  // v1 types: claim, preference, directive, commitment, episode, summary
  source: 'user',      // v1 sources: user, user-inferred, assistant, external, derived
  scope: 'personal',   // v1 scopes: work, personal, health, family, creative, finance, misc, unspecified
  importance: 7,       // 1-10 (see importance rubric)
});

console.log(result); // "Memory stored successfully with ID: fact-123"

totalreclaw_recall

Search for relevant memories.

const memories = await skill.recall({
  query: 'programming language preferences',
  k: 5,  // optional: number of results (default: 8, max: 20)
});

// Each memory has:
// - fact: The fact object with text, metadata, etc.
// - score: Combined relevance score
// - vectorScore: Vector similarity score
// - textScore: BM25 text score
// - decayAdjustedScore: Score adjusted for decay

totalreclaw_forget

Delete a specific memory.

await skill.forget({
  factId: 'fact-123',
});

totalreclaw_export

Export all memories for portability.

const jsonExport = await skill.export({
  format: 'json',  // or 'markdown'
});

console.log(jsonExport);

Lifecycle Hooks

TotalReclaw integrates with OpenClaw through three lifecycle hooks:

before_agent_start

Runs before the agent processes a user message. Retrieves relevant memories and formats them for context injection.

const result = await skill.onBeforeAgentStart(context);

// result.memories - Array of retrieved memories
// result.contextString - Formatted string for injection
// result.latencyMs - Search latency in milliseconds

agent_end

Runs after the agent completes its turn. Extracts facts from the conversation and stores them.

const result = await skill.onAgentEnd(context);

// result.factsExtracted - Number of facts extracted
// result.factsStored - Number of facts stored
// result.processingTimeMs - Processing time

pre_compaction

Runs before conversation history is compacted. Performs comprehensive extraction of the full history.

const result = await skill.onPreCompaction(context);

// result.factsExtracted - Number of facts extracted
// result.factsStored - Number of facts stored
// result.duplicatesSkipped - Duplicates skipped
// result.processingTimeMs - Processing time

Configuration

Environment Variables

See docs/guides/env-vars-reference.md for the complete, authoritative list. The v1-launch cleanup reduced the user-facing surface to 5 vars plus LLM provider keys. The short version:

Tuning knobs (extraction interval, importance threshold, cosine thresholds) now come from the relay billing response. Self-hosted operators can still set the env-var equivalents as fallbacks — see the env vars reference.

Configuration Sources (Priority Order)

Configuration is loaded from multiple sources. Higher priority overrides lower:

1. Default values -- Built-in defaults
2. OpenClaw config -- agents.defaults.totalreclaw.*
3. Environment variables -- TOTALRECLAW_*
4. Explicit overrides -- Passed to constructor

OpenClaw Configuration

Add to your OpenClaw configuration file:

{
  "agents": {
    "defaults": {
      "totalreclaw": {
        "serverUrl": "http://your-server:8080",
        "autoExtractEveryTurns": 3,
        "minImportanceForAutoStore": 6,
        "maxMemoriesInContext": 8,
        "forgetThreshold": 0.3
      }
    }
  }
}

Memory Types

TotalReclaw categorizes memories into five types:

Importance Scoring

Memories are scored on a 1-10 scale:

Encryption Details

All cryptographic operations are powered by @totalreclaw/core -- a unified Rust/WASM module that ensures byte-for-byte consistency across all TotalReclaw clients.

TotalReclaw uses end-to-end encryption:

1. Key Derivation: Recovery phrase is processed through Argon2id to derive encryption keys. The phrase is never sent to the server.
2. Encryption: All memories are encrypted client-side using XChaCha20-Poly1305 before transmission.
3. Search: LSH blind indices (SHA-256 hashed) enable server-side search without exposing plaintext.
4. Decryption: Memories are decrypted client-side after retrieval.
5. Authentication: HKDF-SHA256 for authentication tokens.

The server is cryptographically unable to read your memories, embeddings, or search queries.

Performance Targets

Architecture

+-------------------+     +-------------------+     +-------------------+
|   OpenClaw Agent  |     |  TotalReclaw Skill |     | TotalReclaw Server |
+-------------------+     +-------------------+     +-------------------+
        |                         |                         |
        | onBeforeAgentStart()    |                         |
        |------------------------>| recall()                |
        |                         |------------------------>|
        |                         |<------------------------|
        |<------------------------|                         |
        |                         |                         |
        | [Agent processes]       |                         |
        |                         |                         |
        | onAgentEnd()            |                         |
        |------------------------>| extract + store()       |
        |                         |------------------------>|
        |<------------------------|                         |

Troubleshooting

"Skill not initialized"

Call await skill.init() before using any methods.

"Failed to load reranker model"

The reranker model is optional. If not found, vector scores are used as fallback.

"Memory not found"

The fact ID may be incorrect, or the memory may have been evicted due to decay.

Slow searches

• Ensure the TotalReclaw server is properly indexed
• Check network latency to the server
• Consider increasing maxMemoriesInContext for better recall

Development

Setup

git clone https://github.com/p-diogo/totalreclaw
cd totalreclaw/skill
npm install

Build

npm run build

Test

npm test

# With coverage
npm test -- --coverage

# Watch mode
npm run test:watch

Lint

npm run lint

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Commit changes: git commit -am 'Add my feature'
4. Push to the branch: git push origin feature/my-feature
5. Submit a pull request

License

MIT License - see LICENSE for details.

Links

• TotalReclaw Documentation
• Claw Hub Listing
• OpenClaw
• Issue Tracker