# contrib/ — automation recipes for `mempalace-session`

Manual invocation of `mempalace-session` is fine on a machine you actively drive. For long-running devboxes, a weekly automated mine keeps the palace fresh without thinking about it. This directory ships ready-to-use templates for two common scheduling mechanisms.

> **Before using either**: confirm the toolkit is installed and the wrapper works —
> `mempalace-session --dry-run` should list qualifying sessions. If that errors, fix the install before scheduling.

Pick **one**. Running both would double-mine (harmless — dedup skips everything on the second run — but wastes wall time on the HNSW repair).

---

## systemd user timer (recommended on modern Linux)

**Why:** runs without the user logged in (with `loginctl enable-linger`), survives reboots, logs to `journalctl`, Persistent=true catches missed runs after the machine was off. No root required — it's a *user* unit.

**Install:**

```bash
mkdir -p ~/.config/systemd/user
cp contrib/systemd/mempalace-session.service ~/.config/systemd/user/
cp contrib/systemd/mempalace-session.timer   ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now mempalace-session.timer

# Optional: keep the timer running when you log out (needed on headless servers)
sudo loginctl enable-linger "$USER"
```

**Verify:**

```bash
# Is the timer active and when will it next fire?
systemctl --user list-timers mempalace-session.timer

# Last run status + log tail
systemctl --user status mempalace-session.service

# Full run log (since today)
journalctl --user -u mempalace-session --since today

# Force a run right now (outside the schedule), for testing
systemctl --user start mempalace-session.service
```

**Uninstall:**

```bash
systemctl --user disable --now mempalace-session.timer
rm ~/.config/systemd/user/mempalace-session.{service,timer}
systemctl --user daemon-reload
```

### What the service does

- `Type=oneshot` — runs to completion, not a long-lived daemon.
- `ConditionPathExists=%h/.local/share/opencode/opencode.db` — skips silently on machines that haven't used opencode (no wasted boot-time runs).
- `ConditionPathExists=!%t/mempalace-session.lock` + `ExecStartPre/ExecStopPost` — soft mutual exclusion between overlapping runs.
- `Nice=10` + `IOSchedulingClass=idle` — background priority; won't interfere with interactive work.
- `TimeoutStartSec=7200` — 2 hour ceiling. The reference 60-session mine takes ~21 min; this is headroom for large corpora + slow disks.

### What the timer does

- `OnCalendar=Mon 03:00` — weekly, Monday 03:00 local time. Edit to taste (see `man systemd.time` for syntax).
- `Persistent=true` — if the machine was off at the scheduled time, run on next boot.
- `RandomizedDelaySec=30m` — jitters up to 30 minutes to avoid thundering-herd across a fleet.

---

## cron

**Why:** simpler, ubiquitous, works on any UNIX. No `loginctl enable-linger` dance, no user-units awareness required.

**Caveats:** no "persistent" semantics (a missed run while the machine was off stays missed); default cron output goes to mail or is silently dropped if no MTA.

**Install:**

```bash
# Edit the template first — replace USER with your actual username
sed "s|USER|$USER|g" contrib/cron/mempalace-session.cron > /tmp/mempalace-session.cron

# Append to your existing crontab (preserves any entries you already have)
(crontab -l 2>/dev/null; cat /tmp/mempalace-session.cron) | crontab -
rm /tmp/mempalace-session.cron

# Verify
crontab -l | grep mempalace
```

Ensure `~/.cache/mempalace-session/` exists so the log file can be written:

```bash
mkdir -p ~/.cache/mempalace-session
```

**Verify a run is happening:**

```bash
# Tail the log the cron entry writes to
tail -f ~/.cache/mempalace-session/cron.log

# Or force a run manually to prove the command is well-formed
mempalace-session
```

**Uninstall:**

```bash
crontab -e   # remove the mempalace-session line by hand
```

---

## Which should I pick?

| Situation | Pick |
|---|---|
| Desktop / laptop, modern systemd-based distro | systemd user timer |
| Long-running devbox or server, wants "Persistent=true" catch-up | systemd user timer |
| macOS, BSD, or distro without systemd | cron |
| You already have a cron-based job scheduler on the box | cron |
| You want logs in `journalctl` rather than a file | systemd user timer |

If you're not sure, pick systemd. `Persistent=true` alone is worth it on any box that ever sleeps or reboots.

---

## Running inside a container (devbox)

Inside a Docker-based devbox, neither systemd nor cron typically runs by default. Two options:

1. **Schedule on the host, not the container** — have the host run `docker exec -u <user> <container> mempalace-session` on a timer. The container must be long-running (not per-invocation) for this to work.
2. **Run a systemd-in-container setup** — viable but usually not worth the complexity for this alone.

For most devbox users, a simple weekly manual run via `mempalace-session` (or a host-side cron that shells into the container) is the pragmatic choice. The tool is cheap enough that skipping a week costs nothing — dedup will catch up on the next run.

---

## Tuning

**Frequency.** Weekly is the default because:
- New sessions you care about are typically a handful per week per user.
- Dedup is free on unchanged sessions, so there's no cost to running daily other than the ~5 min post-mine repair.
- Weekly keeps the palace fresh enough that searches almost always return current context.

**Daily or more:** edit `OnCalendar=` or the cron DOW field. On a daily schedule, add `--no-repair` to the wrapper invocation and let a separate weekly unit handle repair — otherwise you repair 7× more often than you need.

**Monthly:** probably too infrequent. You'll search for "that thing we discussed last Tuesday" and miss it.

---

## See also

- [`../../ARCHITECTURE.md`](../../ARCHITECTURE.md) §5 — operational routine (triggers, cadence) in full context.
- [`../../SKILL.md`](../../SKILL.md) — the agent-side Operational Routine section for when an AI agent should suggest running this.