true-recall-gems/README.md

# TrueRecall Gems (v2)

**Purpose:** Memory curation (gems) + context injection

**Status:** ⚠️ Requires true-recall-base to be installed first

---

## Overview

TrueRecall Gems adds **curation** and **injection** on top of Base's capture foundation.

**Gems is an ADDON:**
- Requires true-recall-base
- Independent from openclaw-true-recall-blocks
- Choose Gems OR Blocks, not both

---

## Three-Tier Architecture

```
true-recall-base (REQUIRED)
├── Watcher daemon
└── memories_tr (raw capture)
    │
    └──▶ true-recall-gems (THIS ADDON)
        ├── Curator extracts gems
        ├── gems_tr (curated)
        └── Plugin injection

Note: Don't install with openclaw-true-recall-blocks.
Choose one addon: Gems OR Blocks.
```

---

## Prerequisites

**REQUIRED: Install TrueRecall Base first**

Base provides the capture infrastructure (`memories_tr` collection).

```bash
# Verify base is running
curl -s http://<QDRANT_IP>:6333/collections/memories_tr | jq '.result.points_count'
```

## Installation

### 1. Curator Setup

**Install cron job:**

```bash
# Edit path and add to crontab
echo "*/5 * * * * cd <INSTALL_PATH>/true-recall-gems/tr-continuous && /usr/bin/python3 curator_timer.py >> /var/log/true-recall-timer.log 2>&1" | sudo crontab -

sudo touch /var/log/true-recall-timer.log
sudo chmod 644 /var/log/true-recall-timer.log
```

**Configure curator_config.json:**
```json
{
  "timer_minutes": 5,
  "max_batch_size": 100,
  "user_id": "your-user-id",
  "source_collection": "memories_tr",
  "target_collection": "gems_tr"
}
```

**Edit curator_timer.py:**
- Replace `<QDRANT_IP>`, `<OLLAMA_IP>` with your endpoints
- Replace `<USER_ID>` with your identifier
- Replace `<CURATOR_MODEL>` with your LLM (e.g., `qwen3:30b`)

### 2. Injection Setup

Add to your OpenClaw `openclaw.json`:

```json
{
  "plugins": {
    "entries": {
      "memory-qdrant": {
        "config": {
          "autoCapture": true,
          "autoRecall": true,
          "captureCollection": "memories_tr",
          "collectionName": "gems_tr",
          "embeddingModel": "snowflake-arctic-embed2",
          "maxRecallResults": 2,
          "minRecallScore": 0.8,
          "ollamaUrl": "http://<OLLAMA_IP>:11434",
          "qdrantUrl": "http://<QDRANT_IP>:6333"
        },
        "enabled": true
      }
    },
    "slots": {
      "memory": "memory-qdrant"
    }
  }
}
```

---

## Files

| File | Purpose |
|------|---------|
| `tr-continuous/curator_timer.py` | Timer-based curator |
| `tr-continuous/curator_config.json` | Curator settings template |

---

## Verification

```bash
# Check v1 capture
curl -s http://<QDRANT_IP>:6333/collections/memories_tr | jq '.result.points_count'

# Check v2 curation
curl -s http://<QDRANT_IP>:6333/collections/gems_tr | jq '.result.points_count'

# Check curator logs
tail -20 /var/log/true-recall-timer.log
```

---

## Dependencies

| Component | Provided By | Required For |
|-----------|-------------|--------------|
| Capture | v1 | v2 (input) |
| Curation | v2 | Injection |
| Injection | v2 | Context recall |

---

**Version:** 2.0  
**Requires:** TrueRecall v1  
**Collections:** `memories_tr` (v1), `gems_tr` (v2)