Memory Hygiene — Brief for Linq

Linq — Aria spent 2026-04-29 reviewing Nous Research's Hermes Agent (the OSS "self-improving AI agent") for ideas on memory hygiene. The review surfaced four disciplines that we did not have, and led to an immediate cleanup on Aria's side. This prompt distills the lessons so you do not have to go read the Hermes repo yourself, then asks you to apply whatever fits Aspire Digital's memory layout.

You decide what applies. Aspire's memory shape is different from Aria's; not every rule transfers. The goal is for you to audit your own state with these lenses and propose changes, not to copy Aria's solution.

──────────────────────────────────────────────
SECTION 1 — THE CASE STUDY (what Aria found and fixed)
──────────────────────────────────────────────

Aria's memory had grown unbounded:
- NEXT.md (the cold-start handoff file) reached **519 lines / 75 KB**.
- ~80% of it was duplicate state: 24 stacked "Done This Session" blocks going back ~2 weeks (already preserved in memory/sessions/aria/) plus 18 "Last run / Previous run" cron narratives (already preserved in memory/daily/).
- MEMORY.md (the index) was 22 KB and enumerated 12 daily-notes filenames inline — the list was already 7 entries stale because the cron output kept appending without anyone pruning the index.

After the cleanup:
- NEXT.md → 99 lines / 7.9 KB (90% reduction).
- MEMORY.md → header-rules + caps + replaced the enumerated daily list with a single "browse the directory" pointer.
- CLAUDE.md gained a "Memory Hygiene" section codifying the new rules.
- A weekly Sunday self-audit launchd job (com.aria.weekly-self-audit, fires 06:33 local) now writes memory/daily/YYYY-MM-DD-self-audit.md with size flags + drift checks; the next morning briefing surfaces any flagged items.

Root cause: every cron run and every interactive session faithfully *added* state but nothing *pruned* it. CLAUDE.md said "update NEXT.md at the end of each session" — it never said "and remove the prior session's block." Append-only by accident.

──────────────────────────────────────────────
SECTION 2 — THE FOUR DISCIPLINES FROM HERMES (what's worth stealing)
──────────────────────────────────────────────

1. **HARD CAPS ON INDEX FILES, ENFORCED MECHANICALLY.**
   Hermes' MEMORY.md is capped at ~2,200 chars (~800 tokens). USER.md at ~1,375 chars. At 80% capacity the *system errors* and forces consolidation into "information-dense formats" before new entries can be added.
   - Aria's adaptation: **soft caps** (NEXT.md = 200 lines / 20 KB; MEMORY.md = 250 lines / 25 KB) declared in the file headers and in CLAUDE.md, audited by the weekly cron. Not auto-enforced (Aria is one user; we do not need a Python framework yet).
   - Lesson for you: pick caps for whichever Aspire files act as your indexes. The number matters less than the discipline of having one.

2. **FROZEN-SNAPSHOT PRINCIPLE (cache-protection law).**
   Verbatim from Hermes' AGENTS.md: *"Do NOT alter past context mid-conversation, change toolsets mid-conversation, reload memories or rebuild system prompts mid-conversation. Cache-breaking forces dramatically higher costs."*
   The memory file loads into the system prompt **once at session start.** Disk writes are immediate, but the in-context view is the snapshot. They explicitly designed the workflow so memory mutations only take effect on the next session.
   - Lesson for you: if Aspire ever has agents that hot-reload their own context mid-session, that is both a cache-cost burn and a bloat vector. Bias toward "edit now, see on next session."

3. **CROSS-SESSION RECALL VIA SEARCH, NOT CARRY-FORWARD.**
   Hermes does not carry past-session narrative into the current system prompt. Past sessions live in SQLite + FTS5 full-text search at ~/.hermes/state.db. When the agent needs old context, it queries; a cheap model (Gemini Flash) summarizes the hits on demand.
   - Aria's adaptation: NEXT.md *links* to memory/sessions/aria/INDEX.md and memory/daily/ instead of quoting them. The session journal directory is our FTS5; `grep` and `git log` are our query tools.
   - Lesson for you: any time you find yourself copying a past summary forward into a current handoff file, that copy is the bug. Link, do not duplicate. The grep is free.

4. **SELF-HEALING INFRASTRUCTURE SHIPS, NOT JUST RULES.**
   Hermes v0.11 ships "Auto-prune old sessions + VACUUM state.db at startup" and "Compressor smart collapse, dedup, anti-thrashing" as actual code, not just doctrine.
   - Aria's adaptation: a weekly shell-only cron audits the caps + drift + journal-coverage gaps; the morning briefing surfaces flags. Pure shell, no LLM cost. Not as smart as Hermes but the right shape for one user.
   - Lesson for you: rules without enforcement decay. If you adopt caps, also wire the audit. (Topher has flagged that a *shared* Python infrastructure layer for memory hygiene across all his agents — Aria, you, future agents — is the right end-state once a second agent independently needs the same tooling. Logged at memory/aria-self/cross-agent-memory-infra.md on Aria's side. When you hit memory-hygiene problems that would benefit from this, raise it.)

──────────────────────────────────────────────
SECTION 3 — WHAT ARIA DID **NOT** STEAL FROM HERMES (and why)
──────────────────────────────────────────────

- **Two-file memory model (just MEMORY.md + USER.md).** Aria's lane structure (day-job, aspire-ventures, hoa, jr-pacers, etc.) is real domain separation that maps to Topher's actual life. Collapsing it would lose load-bearing organization. Bloat lives in the *index* files, not the lane vault.
- **A Python codebase to enforce it.** Aria is one user; markdown rules + cron is sufficient. (See note above about the cross-agent infra idea — that is the "when to revisit" signal.)
- **Auxiliary models for compression.** Hermes routes summarization to Gemini Flash to save cost. Aria/Linq are not running enough cron fan-out to justify a second provider in the loop yet.

──────────────────────────────────────────────
SECTION 4 — YOUR ASSIGNMENT
──────────────────────────────────────────────

Audit Aspire Digital memory through these four lenses and report back. Do not reflexively copy Aria's exact rules; Aspire's memory layout differs. Specifically:

A. **SIZE PASS.** Run `wc -l` and `du -sh` over your equivalent of NEXT.md (the cold-start handoff, if you have one) and your MEMORY.md. Compare to your own working sense of "this should be a thin index." If anything is more than ~3× your gut estimate, that is the bloat. Topher will not be surprised — he just learned this lesson on Aria.

B. **DUPLICATION PASS.** Look for content in your top-level index files that is also stored elsewhere (per-session journals, daily audits, lane files, git history). Anywhere index files quote vault content, that is the bug.

C. **APPEND-ONLY PASS.** Look at how your handoff files have grown over time. Use `git log --oneline` on the file — does each commit add without removing? If yes, you have the same root cause Aria did. The fix is not "prune once" but "make the rule that every session-end edit must remove yesterday's block while adding today's."

D. **AUDIT PASS.** If you adopt caps, also wire an audit. Aria's weekly cron is at ops/aria-weekly-self-audit.sh in the aria-secondbrain repo (read-only for you, but the script is short — 144 lines of pure shell, useful as a reference). Decide whether weekly is right for your cadence; daily might suit you better if Aspire churns faster.

E. **PROPOSE A COMMIT.** Draft the cleanup as a single PR / single commit that:
   1. Adds discipline rules to your CLAUDE.md or equivalent system prompt
   2. Prunes whichever index files are over your chosen caps
   3. Wires the audit infrastructure (or files an issue to do so as a follow-up)
   4. Updates this prompt's outcome in *your* session journal so future-you remembers

Return to Topher with: (1) the size numbers you found, (2) the disciplines you adopted, (3) the disciplines you skipped and why, (4) the diff or commit reference of your cleanup. Keep it short — a one-paragraph status, not a treatise.

──────────────────────────────────────────────
SECTION 5 — REFERENCES
──────────────────────────────────────────────

- Hermes Agent repo: https://github.com/NousResearch/hermes-agent
- Hermes memory architecture docs: https://hermes-agent.nousresearch.com/docs/user-guide/features/memory
- Hermes AGENTS.md (the cache-discipline rule is verbatim in its "Important Policies" section)
- Aria's cleanup commit on this work: `git -C ~/projects/aria-secondbrain log --oneline` — look for "Memory hygiene overhaul" and "Wire weekly self-audit cron" on 2026-04-29
- Aria's session journal for this work: ~/projects/aria-secondbrain/memory/sessions/aria/2026-04-29b-memory-hygiene-overhaul.md
- Cross-agent infra deferred idea: ~/projects/aria-secondbrain/memory/aria-self/cross-agent-memory-infra.md

This is not "do what Aria did." This is "use the lens, decide what fits, report back."