true-recall/checklist.md

# TrueRecall v2 - Installation Checklist

Pre-install and post-install validation steps.

---

## Pre-Installation Checks

### 1. System Requirements

| Check | Command | Expected Result |
|-------|---------|---------------|
| Python 3.8+ | `python3 --version` | 3.8 or higher |
| pip available | `pip3 --version` | Working |
| curl available | `curl --version` | Working |
| git available | `git --version` | Working |

### 2. Qdrant Verification

| Check | Command | Expected Result |
|-------|---------|---------------|
| Qdrant running | `curl http://localhost:6333` | Returns version |
| Collections accessible | `curl http://localhost:6333/collections` | Returns list |
| Network reachable | `curl http://127.0.0.1:6333` | Same result |

### 3. Ollama Verification

| Check | Command | Expected Result |
|-------|---------|---------------|
| Ollama running | `curl http://localhost:11434/api/tags` | Returns models |
| Embedding model | Check in list | snowflake or mxbai |
| Curator model | Check in list | qwen3:4b or 30b |
| Network reachable | `curl http://127.0.0.1:11434/api/tags` | Same result |

### 4. OpenClaw Status

| Check | Command | Expected Result |
|-------|---------|---------------|
| Gateway running | `openclaw gateway status` | Active |
| Config valid | `openclaw doctor` | No errors |
| Plugin available | `openclaw plugins list` | memory-qdrant present |

---

## Installation Steps

### Step 1: Choose Mode

| Mode | Description | Use Case |
|------|-------------|----------|
| **full** | Watcher + Curator + Gems | Complete TrueRecall v2 |
| **simple** | Watcher only | Just capture memories |

### Step 2: Full Mode Prompts

| # | Prompt | Default | Validate |
|---|--------|---------|----------|
| 1 | Installation mode | `full` | Must be "full" or "simple" |
| 2 | Embedding model | `mxbai-embed-large` | Model must exist in Ollama |
| 3 | Timer interval | `5` minutes | 5, 30, 60, or custom |
| 4 | Batch size | `100` | 50, 100, 500, or custom |
| 5 | Qdrant URL | `http://localhost:6333` | Must be reachable |
| 6 | Ollama URL | `http://localhost:11434` | Must be reachable |
| 7 | Curator LLM | `qwen3:30b-a3b-instruct` | Model must exist in Ollama |
| 8 | User ID | `rob` | Non-empty string |

### Step 3: Simple Mode Prompts

| # | Prompt | Default | Validate |
|---|--------|---------|----------|
| 1 | Installation mode | `full` | Must be "simple" |
| 2 | Embedding model | `snowflake-arctic-embed2` | Model must exist in Ollama |
| 3 | Qdrant URL | `http://localhost:6333` | Must be reachable |
| 4 | User ID | `rob` | Non-empty string |

---

## Post-Installation Validation

### 1. Config Files Created

| File | Location | Check |
|------|----------|-------|
| `curator_config.json` | `tr-continuous/` | Contains all settings |
| `curator_timer.py` | `tr-continuous/` | Executable, no syntax errors |
| `mem-qdrant-watcher.service` | systemd path | Loaded and enabled |

### 2. Watcher Service

| Check | Command | Expected Result |
|-------|---------|---------------|
| Service installed | `systemctl status mem-qdrant-watcher` | Loaded |
| Service running | `systemctl is-active mem-qdrant-watcher` | `active` |
| Logs available | `sudo journalctl -u mem-qdrant-watcher -n 5` | Recent entries |

### 3. Cron Job (Full Mode Only)

| Check | Command | Expected Result |
|-------|---------|---------------|
| Cron entry exists | `crontab -l \| grep true-recall` | Entry present |
| Syntax valid | Visual check | No errors |
| Timer matches | Compare to config | Same interval |

### 4. Collections Created

| Check | Command | Expected Result |
|-------|---------|---------------|
| memories_tr exists | `curl http://localhost:6333/collections/memories_tr` | 200 OK |
| gems_tr exists (full) | `curl http://localhost:6333/collections/gems_tr` | 200 OK |
| Can write | Test point insertion | Success |
| Can read | Test point query | Success |

### 5. First Run (Full Mode)

| Check | Command | Expected Result |
|-------|---------|---------------|
| Curator runs | Wait for first cron | Log entry created |
| Log file exists | `ls /var/log/true-recall-timer.log` | File present |
| Gems extracted | Check `gems_tr` count | Increased from 0 |
| Memories tagged | Query with `curated: false` | All have field |

### 6. Injection Test

| Check | Method | Expected Result |
|-------|--------|-----------------|
| Plugin loads | `openclaw plugins list` | memory-qdrant active |
| Recall works | Send test message | Gems injected in context |
| Capture works | Check `memories_tr` | New point added |

---

## Troubleshooting

### Common Issues

| Symptom | Likely Cause | Fix |
|---------|--------------|-----|
| Qdrant unreachable | Not running | `sudo systemctl start qdrant` |
| Ollama unreachable | Not running | `ollama serve` |
| Model not found | Not pulled | `ollama pull mxbai-embed-large` |
| Permission denied | Wrong user | Run with `sudo` or check ownership |
| Cron not running | Service stopped | `sudo systemctl start cron` |
| Watcher not capturing | Session path wrong | Check `session.jsonl` location |

---

## Validation Commands Quick Reference

```bash
# Check all services
openclaw status && curl -s http://localhost:6333 && curl -s http://localhost:11434/api/tags

# Check collections
curl -s http://localhost:6333/collections/memories_tr | jq .result.points_count
curl -s http://localhost:6333/collections/gems_tr | jq .result.points_count

# Check watcher
sudo systemctl status mem-qdrant-watcher

# Check cron
crontab -l | grep true-recall

# Check logs
tail -f /var/log/true-recall-timer.log
sudo journalctl -u mem-qdrant-watcher -f
```

---

## Security & Privacy Review (Pre-Commit)

### Before Committing to Git

| Check | Command | What to Look For |
|-------|---------|------------------|
| **Internal IPs** | `grep -rE "(10\.[0-9]+\.[0-9]+\.[0-9]+\|192\.168\.[0-9]+\.[0-9]+\|172\.(1[6-9]\|2[0-9]\|3[01])\.[0-9]+\.[0-9]+)"` | Private network addresses |
| **Passwords/Tokens** | `grep -riE "(password|token|secret|api.?key)"` | Hardcoded credentials |
| **SSH Keys** | `grep -rE "(BEGIN.*PRIVATE KEY|ssh-rsa|ssh-ed25519)"` | Private keys |
| **Absolute Paths** | `grep -rE "(/root/|/home/[a-z]+/|\.ssh/)"` | System-specific paths |
| **Timestamps** | `grep -rE "[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}"` | Non-project dates/times |
| **Usernames** | `grep -riE "(user: [a-z]+\|username: [a-z]+)"` | System usernames |

### Replace With Placeholders

| Found | Replace With |
|-------|--------------|
| `10.0.0.x` | `<QDRANT_IP>` or `<OLLAMA_IP>` |
| `192.168.x.x` | `<LOCAL_NETWORK_IP>` |
| `/root/.openclaw/` | `~/.openclaw/` or `<OPENCLAW_PATH>` |
| `/home/username/` | `~/` or `<USER_HOME>` |
| Real tokens | `<TOKEN>` or `<API_KEY>` |
| Specific dates | `<DATE>` or `<TIMESTAMP>` |

### Files to Review

- [ ] All `.py` files
- [ ] All `.md` files
- [ ] All `.json` files
- [ ] All `.sh` files
- [ ] Any log files (should be in `.gitignore`)
- [ ] Any config files with paths

---

## Sign-off

| Check | Status | Date |
|-------|--------|------|
| Pre-install checks passed | ⏳ | |
| Installation completed | ⏳ | |
| Post-install validation passed | ⏳ | |
| First curator run successful | ⏳ | |
| Injection test passed | ⏳ | |

**Installer:** _______________  
**Date:** _______________