docs(memory): category-pinned selection — changelog + hygiene guidance

[indykish]

Companion to usezombie/usezombie M91_002 (category-pinned hydration + tiered cap eviction).

• New changelog <Update>: core memories now survive the hydration window and the entry cap.
• Memory page: new "What survives — selection and eviction" section with the four memory-hygiene habits.

Merge after the product Pull Request (PR) lands.

🤖 Generated with Claude Code

Greptile Summary

Companion docs for the category-pinned hydration and tiered cap eviction feature (M91_002). memory.mdx gains a new "What survives" section and updates both the categories table and the troubleshooting table; changelog.mdx gets a new "What's new" <Update> block for Jun 12, 2026.

• memory.mdx: core lifetime cell corrected from "permanent until forgotten" to "durable; evicted last at the entry cap"; new "What survives" section explains hydration order, eviction tiers, and four memory-hygiene habits; troubleshooting row updated to surface the all-core cap-eviction caveat.
• changelog.mdx: New <Update label="Jun 12, 2026" tags={["What's new"]}> block added at the top (after the <Tip>), covering category-pinned hydration, tiered cap eviction, and a link to the updated Memory page.

Confidence Score: 5/5

Documentation-only change; no code paths, schemas, or API contracts are affected.

Both files are documentation prose and MDX markup. The two factual corrections raised in the prior review (categories table lifetime, troubleshooting table eviction caveat) are now incorporated in this diff, and the new "What survives" section is internally consistent with those corrections and with the changelog entry.

No files require special attention.

Important Files Changed

Filename	Overview
changelog.mdx	New <Update> block for Jun 12, 2026 "What's new" — correctly placed at top after the <Tip>, follows fixed section-order and voice rules, no milestone IDs or marketing language.
memory.mdx	Categories table updated to replace "permanent until forgotten" with accurate eviction semantics; new "What survives" section documents hydration order and eviction tiers; troubleshooting row updated to mention cap-eviction of core; all three points raised in prior review are now addressed.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    subgraph Hydration["Hydration at run start"]
        H1["core entries newest-first"] --> H2{Fits byte budget?}
        H2 -->|yes| H3[Load into context]
        H2 -->|no| H4[Stays in Postgres - not evicted]
        H3 --> H5["Remaining budget fills with newest non-core entries"]
    end

    subgraph Eviction["Eviction at entry cap"]
        E1{Any non-core rows?}
        E1 -->|yes| E2[Delete coldest non-core row]
        E1 -->|no - all-core set| E3[Delete coldest core row]
    end

    core["category: core - pinned"] --> Hydration
    core --> Eviction
    noncore["category: daily / conversation - windowed"] --> Hydration
    noncore --> Eviction
    custom["Custom or unknown category - windowed by recency"] --> Hydration

Loading

Comments Outside Diff (2)

1. memory.mdx, line 14 (link)

   The core lifetime description "permanent until forgotten" implies only explicit memory_forget calls can remove a core entry, but the new eviction section introduced in this same PR states a core entry is deleted when no non-core entries remain at the cap. A reader who only consults the categories table will form an incorrect mental model — they'll think core is unconditionally durable and may not heed habit fix: docs polish — external link check, OpenAPI card, navbar #3 about hoarding.

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: memory.mdx
   Line: 14
   
   Comment:
   The `core` lifetime description "permanent until forgotten" implies only explicit `memory_forget` calls can remove a `core` entry, but the new eviction section introduced in this same PR states a `core` entry is deleted when no non-core entries remain at the cap. A reader who only consults the categories table will form an incorrect mental model — they'll think `core` is unconditionally durable and may not heed habit #3 about hoarding.
   
   
   
   How can I resolve this? If you propose a fix, please make it concise.

   Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

2. memory.mdx, line 113 (link)

   The troubleshooting cause "No pruning on core (by design)" is now incomplete: the new section documents that cap eviction does prune core entries when only core rows remain. A user seeing "Memory grows forever" could follow this row's advice, call memory_forget on a few entries, and then be surprised when core facts start disappearing once the all-core cap is crossed. Adding the cap-eviction caveat here ties the troubleshooting table to the new eviction behaviour.

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: memory.mdx
   Line: 113
   
   Comment:
   The troubleshooting cause "No pruning on `core` (by design)" is now incomplete: the new section documents that cap eviction _does_ prune `core` entries when only `core` rows remain. A user seeing "Memory grows forever" could follow this row's advice, call `memory_forget` on a few entries, and then be surprised when core facts start disappearing once the all-`core` cap is crossed. Adding the cap-eviction caveat here ties the troubleshooting table to the new eviction behaviour.
   
   
   
   How can I resolve this? If you propose a fix, please make it concise.

_{Reviews (3): Last reviewed commit: "Merge remote-tracking branch 'origin/mai..." | Re-trigger Greptile}

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
megam	🟢 Ready	View Preview	Jun 12, 2026, 3:12 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[indykish]

Addressed both code-review issues in 06b620a — concise fixes, one at a time:

Issue 1 (memory.mdx categories table, core lifetime). Changed permanent until forgotten → durable; evicted last at the entry cap, so a reader consulting only the table doesn't form a "core is unconditionally durable" model that contradicts this PR's eviction section.

Issue 2 (memory.mdx troubleshooting, "Memory grows forever"). Changed the cause from No pruning on core (by design) → core has no time-based pruning; at the entry cap, coldest core entries are evicted when no non-core entries remain, tying the troubleshooting row to the new cap-eviction behaviour so a user isn't surprised when core facts start disappearing once the all-core cap is crossed.

Both are the verbatim suggested edits.