Document the operational routine + ship automation templates
Until opencode session-stopping hooks land upstream, mempalace-session
is the entire mechanism that gets opencode conversations into the
palace — skip it and session history stays trapped in a local SQLite
DB, invisible to semantic search. Previous docs covered setup well
but were thin on when and how often to run it.
- ARCHITECTURE.md §5: replace the one-line 'When to re-mine' note with
a full Operational Routine section — triggers, cadence, relationship
to the session lifecycle, automation pointers, verification.
- SKILL.md: add an Operational Routine section aimed at agents —
when to suggest invoking the tool, cadence guidance, how to
distinguish this producer-side tool from the consumer-side
mempalace skill's in-session habits.
- README.md: add 'Keeping it fresh' subsection pointing at contrib/
and the full docs.
contrib/ ships three ready-to-use templates:
- systemd/mempalace-session.{service,timer} — user units with weekly
Mon 03:00 schedule, Persistent=true catch-up, RandomizedDelaySec for
fleet-wide jitter, ConditionPathExists guard for opencode-less boxes,
Nice+IOSchedulingClass=idle so it never fights interactive work.
- cron/mempalace-session.cron — sample crontab entry with log
redirection and clear USER-substitution instructions.
- README.md with install/verify/uninstall recipes for both, a chooser
table (systemd vs cron), container/devbox caveats, and tuning notes
(daily vs weekly vs monthly trade-offs).
The user's LATER-list item 'wrap mempalace-session in cron/systemd
timer for true auto-save coverage' is now actionable: a single
systemctl --user enable --now command stands it up.
This commit is contained in:
@@ -104,6 +104,57 @@ mempalace-session # stages + mines fresh
|
||||
|
||||
Staging is ephemeral by design; the palace is the source of truth.
|
||||
|
||||
## Operational Routine (when to invoke)
|
||||
|
||||
Until upstream opencode session hooks land, **`mempalace-session` is the entire mechanism** that gets opencode conversations into the palace. If the user's opencode history isn't showing up in `mempalace_search`, the most likely cause is "`mempalace-session` hasn't been run recently".
|
||||
|
||||
### Agent-level triggers
|
||||
|
||||
Suggest invoking the tool when any of these apply:
|
||||
|
||||
- User asks *"why can't you find our conversation from earlier?"* / *"you should remember this from last week"* → the palace may not have the opencode session yet. Check `mempalace_list_wings` for `wing_conversations`; if the last drawer there is older than the referenced conversation, run `mempalace-session`.
|
||||
- User mentions an upcoming **container recreate / system migration / OS reinstall** → suggest a full mine first as a backup checkpoint. The opencode DB normally survives via named volumes, but an explicit mine is cheap insurance.
|
||||
- User has just **set up a new machine** and asks about mempalace → part of the recipe is the initial backfill. Run `mempalace-session --dry-run` first to show scope, then the real mine.
|
||||
- User completed a **substantive session they want preserved past `/exit`** → offer a targeted `mempalace-session --session <id>` right then.
|
||||
- User asks *"how do I keep this up to date?"* → point at [`contrib/`](../../contrib/) (systemd timer or cron recipes).
|
||||
|
||||
### Cadence guidance
|
||||
|
||||
| Situation | Suggested cadence |
|
||||
|---|---|
|
||||
| Active devbox, daily opencode use | Weekly automated (systemd timer or cron) |
|
||||
| Occasional opencode user | Monthly manual or weekly automated |
|
||||
| Fresh machine / first setup | One-shot full backfill, then schedule |
|
||||
| "I'm about to rebuild the container" | Run now, as a checkpoint |
|
||||
| Automated daily mines | Pass `--no-repair` + schedule weekly repair separately |
|
||||
|
||||
Don't suggest running more often than daily — the post-mine HNSW repair (~5 min on 5k drawers) dominates cost, and session growth is slow enough that daily is already overkill.
|
||||
|
||||
### Relationship to the `mempalace` skill
|
||||
|
||||
The consumer-side `mempalace` skill covers in-session habits (wake-up search, wind-down diary). `mempalace-session` is **between-session maintenance** — it runs when no agent session is active, typically automated. Both are needed:
|
||||
|
||||
- Wake-up/wind-down → curated summaries (what mattered, what was decided)
|
||||
- `mempalace-session` → raw turns (the actual words exchanged)
|
||||
|
||||
A machine running only one of these has half a memory. Agents loading the `mempalace` skill on an opencode machine should be aware this tool exists and point users at it if they ask about persistence.
|
||||
|
||||
### Quick automation pitch
|
||||
|
||||
If the user has a devbox and hasn't set up automation, offer it:
|
||||
|
||||
```bash
|
||||
# One-time setup (modern Linux, systemd user timer)
|
||||
cd ~/mempalace-toolkit
|
||||
mkdir -p ~/.config/systemd/user
|
||||
cp contrib/systemd/*.{service,timer} ~/.config/systemd/user/
|
||||
systemctl --user daemon-reload
|
||||
systemctl --user enable --now mempalace-session.timer
|
||||
sudo loginctl enable-linger "$USER" # optional, for headless boxes
|
||||
```
|
||||
|
||||
Full install/verify/uninstall recipes for both systemd and cron are in [`contrib/README.md`](../../contrib/README.md). The quick-start above defaults to weekly runs on Monday 03:00 local time with a ≤30 min randomized delay.
|
||||
|
||||
## Failure Modes & Fixes
|
||||
|
||||
| Symptom | Cause | Fix |
|
||||
|
||||
Reference in New Issue
Block a user