/total-recall

name: total-recall
description: "The only memory skill that watches on its own. No database. No vectors. No manual saves. Just an LLM observer that compresses your conversations into prioritised notes, consolidates when they grow, and recovers anything missed. Five layers of redundancy, zero maintenance. ~$0.00/month (using free-tier models). While other memory skills ask you to remember to remember, this one just pays attention."
metadata:
  openclaw:
    emoji: "🧠"
    requires:
      bins: ["jq", "curl"]
    env:
      - key: OPENROUTER_API_KEY
        label: "OpenRouter API key (for LLM calls)"
        required: true
    config:
      memorySearch:
        description: "Enable memory search on observations.md for cross-session recall"

Total Recall — Autonomous Agent Memory

**The only memory skill that watches on its own.**

No database. No vectors. No manual saves. Just an LLM observer that compresses your conversations into prioritised notes, consolidates when they grow, and recovers anything missed. Five layers of redundancy, zero maintenance. ~$0.00/month (using free-tier models).

While other memory skills ask you to remember to remember, this one just pays attention.

Architecture

Layer 1: Observer (cron, every 15-30 min)
    ↓ compresses recent messages → observations.md
Layer 2: Reflector (auto-triggered when observations > 8000 words)
    ↓ consolidates, removes superseded info → 40-60% reduction
Layer 3: Session Recovery (runs on every /new or /reset)
    ↓ catches any session the Observer missed
Layer 4: Reactive Watcher (inotify daemon, Linux only)
    ↓ triggers Observer after 40+ new JSONL writes, 5-min cooldown
Layer 5: Pre-compaction hook (memoryFlush)
    ↓ emergency capture before OpenClaw compacts context

What It Does

• **Observer** reads recent session transcripts (JSONL), sends them to an LLM, and appends compressed observations to `observations.md` with priority levels (high, medium, low)
• **Reflector** kicks in when observations grow too large, consolidating related items and dropping stale low-priority entries
• **Session Recovery** runs at session start, checks if the previous session was captured, and does an emergency observation if not
• **Reactive Watcher** watches the session directory with inotify so high-activity periods get captured faster than the cron interval
• **Pre-compaction hook** fires when OpenClaw is about to compact context, ensuring nothing is lost

Quick Start

1. Install the skill

clawdhub install total-recall

2. Set your API key

Add to your `.env` or OpenClaw config:

OPENROUTER_API_KEY=sk-or-v1-xxxxx

3. Run the setup script

bash skills/total-recall/scripts/setup.sh

This will:

• Create the memory directory structure (`memory/`, `logs/`, backups)
• On Linux with inotify + systemd: install the reactive watcher service
• Print cron job and agent configuration instructions for you to add manually

4. Configure your agent to load observations

Add to your agent's workspace context (e.g., `MEMORY.md` or system prompt):

At session startup, read `memory/observations.md` for cross-session context.

Or use OpenClaw's `memoryFlush.systemPrompt` to inject a startup instruction.

Platform Support

| Platform | Observer + Reflector + Recovery | Reactive Watcher | |----------|-------------------------------|-----------------| | Linux (Debian/Ubuntu/etc.) | Full support | With inotify-tools | | macOS | Full support | Not available (cron-only) |

All core scripts use portable bash. `stat`, `date`, and `md5` commands are handled cross-platform via `_compat.sh`.

Configuration

All scripts read from environment variables with sensible defaults:

| Variable | Default | Description | |----------|---------|-------------| | `OPENROUTER_API_KEY` | (required) | OpenRouter API key for LLM calls | | `MEMORY_DIR` | `$OPENCLAW_WORKSPACE/memory` | Where observations.md lives | | `SESSIONS_DIR` | `~/.openclaw/agents/main/sessions` | OpenClaw session transcripts | | `OBSERVER_MODEL` | `stepfun/step-3.5-flash:free` | Primary model for compression (free) | | `OBSERVER_FALLBACK_MODEL` | `nvidia/nemotron-3-nano-30b-a3b:free` | Fallback if primary fails (free) | | `OBSERVER_LOOKBACK_MIN` | `15` | Minutes to look back (daytime) | | `OBSERVER_MORNING_LOOKBACK_MIN` | `480` | Minutes to look back (before 8am) | | `OBSERVER_LINE_THRESHOLD` | `40` | Lines before reactive trigger (Linux) | | `OBSERVER_COOLDOWN_SECS` | `300` | Cooldown between reactive triggers (Linux) | | `REFLECTOR_WORD_THRESHOLD` | `8000` | Words before reflector runs | | `REFLECTOR_MODEL` | `nvidia/nemotron-3-super-120b-a12b:free` | Model for consolidating observations (free) | | `REFLECTOR_FALLBACK_MODEL` | `openrouter/hunter-alpha` | Fallback if reflector model fails (free) | | `OPENCLAW_WORKSPACE` | `~/your-workspace` | Workspace root |

LLM Provider Configuration

Total Recall uses any OpenAI-compatible chat completion API. Switch providers by setting environment variables:

| Variable | Default | Description | |----------|---------|-------------| | `LLM_BASE_URL` | `https://openrouter.ai/api/v1` | API endpoint | | `LLM_API_KEY` | falls back to `OPENROUTER_API_KEY` | API key | | `LLM_MODEL` | `deepseek/deepseek-v3.2` | Model to use |

Provider examples

# OpenRouter (default)
export OPENROUTER_API_KEY="your-key"

# Ollama (local)
export LLM_BASE_URL="http://localhost:11434/v1"
export LLM_API_KEY="ollama"
export LLM_MODEL="llama3.1:8b"

# Groq
export LLM_BASE_URL="https://api.groq.com/openai/v1"
export LLM_API_KEY="your-groq-key"
export LLM_MODEL="llama-3.3-70b-versatile"

Files Created

memory/
  observations.md          # The main observation log (loaded at startup)
  observation-backups/     # Reflector backups (last 10 kept)
  .observer-last-run       # Timestamp of last observer run
  .observer-last-hash      # Dedup hash of last processed messages
logs/
  observer.log
  reflec