# memory-compactor

Temporal conversational memory compactor for your custom mem0-python-server.

## What it does
- pulls conversational memories for one `user_id`
- clusters by time windows
- extracts a compact summary + structured facts per segment (Groq)
- writes summaries **verbatim** to `POST /memories/raw`
- preserves extracted facts in metadata alongside the summary
- injects `metadata.created_at` so summaries sort correctly without date prefixes
- optionally deletes older intermediate entries (safe budget + dry-run first)

## Safety defaults
- **dry-run by default** (no writes/deletes)
- keeps recent memories (`--min-age-days`)
- delete cap per run (`--max-deletes`)

## Run
```bash
cd /home/lucky/.openclaw/workspace/memory-compactor
python3 compactor.py --user-id main
```

Apply changes:
```bash
python3 compactor.py --user-id main --apply
```

## Environment
The compactor auto-loads `.env` from this directory (useful for cron). At minimum set:
```env
GROQ_API_KEY=your_key_here
```

## Useful options
- `--base-url http://192.168.0.200:8420`
- `--gap-minutes 45`
- `--min-age-days 2`
- `--max-deletes 50`
- `--segment-max-items 15`
- `--max-summaries 1` (limit created summaries for testing)
- `--skip-ephemeral` (skip obvious weather-like chatter)

## Next improvements
- semantic clustering (embeddings) beyond time windows
- better resolution detection (state machine)
- reversible snapshots before apply
- cron wrapper + run history logging
- **future milestone:** capture a pre-change snapshot + restore option before deleting memories