Tracking: hands-off memory hygiene for Perseus + Perseus Vault

[tcconnally]

Umbrella for the 2026-07-07 design review: the store stays signal-rich and small without the user ever running a command — hygiene is automatic, conservative, and reversible by default, built on the existing decay model (Ebbinghaus 7-day half-life, verified floor 0.2, shared 0.05 archive threshold) rather than replacing it.

Design decision

Foundation-first: (C) a one-shot Vault CLI verb composing the shipped autocohere + maintenance handlers, then (B) ride the existing perseus cron scheduler to run it nightly, with (A) an in-server loop as the Windows fallback. Everything unattended is a reversible archived=1 flip — purge (hard delete) is excluded from any unattended path; history retention stays env-gated no-op unless explicitly enabled.

Work items (dependency order)

Perseus Vault

• Add one-shot CLI verb perseus-vault maintain [--dry-run] — shell entry point for the full hygiene pass perseus-vault#490 — one-shot perseus-vault maintain [--dry-run] [--vacuum] CLI verb (enabling primitive; ship + validate first)
• Maintenance dry-run silently skips vacuum and reindex — report would-do estimates instead perseus-vault#491 — dry-run should report would-do estimates for vacuum/reindex (report-only rollout fidelity)
• Optional in-server maintenance loop (serve --maintain-every) — the Windows hygiene story perseus-vault#492 — optional serve --maintain-every in-server loop (Windows fallback)

Perseus

• Add perseus vault maintain passthrough + hygiene: config block (default off) #691 — perseus vault maintain passthrough + hygiene: config block (default off)
• Generalize scheduler beyond hardcoded render — add --job maintain for scheduled memory hygiene #693 — generalize scheduler beyond hardcoded render; --job maintain (cron/launchd/systemd)
• Windows scheduling backend (schtasks) — close the win32 gap for scheduled jobs #694 — Windows Task Scheduler (schtasks) backend
• docs: memory-cleanup skill should point at scheduled perseus vault maintain for live-store hygiene #697 — docs: memory-cleanup skill points at the automatic path

Rollout

1. Land vault#490, validate --dry-run on a real store (cold model cache + concurrent with a live server).
2. Land Add perseus vault maintain passthrough + hygiene: config block (default off) #691 + Generalize scheduler beyond hardcoded render — add --job maintain for scheduled memory hygiene #693; onboarding installs the job report-only for the first week, then flips live.
3. Windows: Windows scheduling backend (schtasks) — close the win32 gap for scheduled jobs #694 (complete fix) and/or vault#492 (interim).

End state for the everyday user: perseus cron create --job maintain --every 1440 --install — or a single config flag — and never think about memory hygiene again.

[tcconnally]

Status 2026-07-07 (session 2):

All code children merged + released.

• perseus: Add perseus vault maintain passthrough + hygiene: config block (default off) #691→feat: perseus vault maintain passthrough + hygiene config block #700, Generalize scheduler beyond hardcoded render — add --job maintain for scheduled memory hygiene #693→feat: generalize scheduler beyond hardcoded render — --job maintain #701, docs: memory-cleanup skill should point at scheduled perseus vault maintain for live-store hygiene #697→docs: memory-cleanup skill points at the automatic live-store hygiene path #702, Windows scheduling backend (schtasks) — close the win32 gap for scheduled jobs #694→feat: Windows Task Scheduler (schtasks) backend — close the win32 scheduling gap #703 — merged; shipped in v1.0.21 (release publication pending owner action; the release PR release: v1.0.21 — bridge fixes, perseus knows, /knows endpoint #710 is merged so main is at 1.0.21).
• perseus-vault: [patent] Claim element: recursive / dependency-ordered directive resolution #490→feat(mimir): MimirConnector.as_of() — surface bi-temporal time-travel #495, [patent] Reduction-to-practice: expand docs/ip exhibit suite + CI gate #491→test(ip): prove directive resolution happens outside the model loop (#487) #496, [patent] Defensive publication: tighten the 6 disclosures to bracket the claims and pre-empt §103 #492→test(ip): prove the unified typed-directive grammar (claim element a) (#488) #497 — merged; shipped in v2.19.0 (tagged + released, all binary assets verified attached incl. x86_64-unknown-linux-gnu, windows, mcpb).

Remaining before this tracker closes (blocked on prod-access approval, surfaced to owner):

1. Deploy perseus-vault v2.19.0 to greg (/opt/data/webui/minions/.minions-data/mimir/perseus-vault).
2. Redeploy perseus v1.0.21 in the hermes-webui container (after PyPI publish).
3. Actually enable the nightly maintain job on greg (serve --maintain-every 24 on the mimir MCP launch, or perseus scheduler --job maintain).
4. Validate the bridge live (perseus_memory returns vault-backed results — the bug: default perseus_vault: block shadows legacy mneme:/mimir: config → bridge silently falls back to local-only #704 fix makes the interim config workaround unnecessary once 1.0.21 is deployed).

[tcconnally]

Done — every box checked, live-verified on the production deploy (2026-07-07):

Code (all merged): perseus #691→#700, #693→#701, #697→#702, #694→#703; perseus-vault #490→#495, #491→#496, #492→#497.

Released: perseus v1.0.21 (PyPI perseus-ctx published via OIDC), perseus-vault v2.19.0 then v2.19.1 — the 2.19.1 hotfix matters here: the first production maintain --dry-run exposed vault#503 (the #487 usefulness columns never migrated on stores already at schema v15, so decay_tick/maintain/autocohere failed with "no such column: usefulness_count" on every upgraded store). Fixed via SCHEMA_VERSION 16 + regression test, released, redeployed.

Deployed + enabled on greg:

• perseus-vault 2.19.1 + perseus 1.0.21 live in hermes-webui (versions verified in-container).
• Nightly maintain ENABLED: /boot/config/plugins/dynamix/perseus-vault-maintain.cron → /etc/cron.d/root — nightly pass Mon–Sat 03:17, weekly --vacuum Sundays; logs to the hermes appdata share.
• A real (non-dry-run) pass executed via the exact cron command: 80 decay updates, 80 rows reindexed, errors: [].
• Bonus from the same deploy: the bug: default perseus_vault: block shadows legacy mneme:/mimir: config → bridge silently falls back to local-only #704 bridge fix verified live (perseus doctor: ✓ Perseus Vault connected + healthy; perseus knows returns vault-backed results with active-only counts) and the config block renamed to canonical perseus_vault:.

Hands-off memory hygiene is now actually hands-off.