total-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.10/month.

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
```bash
clawdhub install total-recall
```

### 2. Set your API key
Add to your `.env` or OpenClaw config:
```bash
OPENROUTER_API_KEY=sk-or-v1-xxxxx
```

### 3. Run the setup script
```bash
bash skills/total-recall/scripts/setup.sh
```

This will:
- Create the memory direc...

# 🧠 Total Recall — Autonomous Agent Memory

**The only memory system 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.10/month.

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

## How It Works

```
Layer 1: Observer (cron, every 15 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
```

Inspired by how human memory works during sleep — the hippocampus captures experiences, and during consolidation, important memories are strengthened while noise is discarded.

## Install via ClawdHub

```bash
clawdhub install total-recall
bash skills/total-recall/scripts/setup.sh
```

## Install from GitHub

```bash
git clone https://github.com/gavdalf/total-recall.git
cd total-recall
bash scripts/setup.sh
```

See [SKILL.md](SKILL.md) for full documentation, configuration, and platform support.

## What's Inside

| Component | Description |
|-----------|-------------|
| `scripts/observer-agent.sh` | Compresses recent conversations via LLM |
| `scripts/reflector-agent.sh` | Consolidates when observations grow large |
| `scripts/session-recovery.sh` | Catches missed sessions on /new |
| `scripts/observer-watcher.sh` | Reactive inotify trigger (Linux) |
| `scripts/dream-cycle.sh` | Nightly memory consolidation (Dream Cycle) |
| `scripts/staging-review.sh` | Review, approve, or reject Pa...