@vellumai/assistant 0.8.10 → 0.8.11-staging.1

package/src/memory/v2/prompts/consolidation.ts

@@ -30,6 +30,37 @@ const log = getLogger("memory-v2-consolidate-prompt");
 /** Sentinel substituted with the cutoff timestamp at runtime. */
 export const CUTOFF_PLACEHOLDER = "{{CUTOFF}}";
 
+/**
+ * Sentinel substituted with {@link CORE_PAGES_CONSOLIDATION_SECTION} (or the
+ * empty string) at runtime. The core-pages file only exists for the memory-v3
+ * retrieval lanes, so the section is included only when a v3 flag is enabled
+ * for the assistant — on a v2-only install the instruction would have the
+ * agent curate a file nothing reads, under premises ("kept in reach every
+ * turn", "the hot set") that are false there.
+ *
+ * New flag-gated sections must follow this placeholder pattern and be
+ * registered in consolidation-prompt-flag-gating-guard.test.ts, which blocks
+ * gated content from reaching the default (all-gates-off) rendering.
+ */
+export const CORE_PAGES_PLACEHOLDER = "{{CORE_PAGES_SECTION}}";
+
+/**
+ * The flag-gated `memory/core-pages.md` curation step. Ends with a blank line
+ * so substituting it (or the empty string) ahead of the `---` separator keeps
+ * the surrounding template byte-stable either way.
+ */
+export const CORE_PAGES_CONSOLIDATION_SECTION = `## 10. Review \`memory/core-pages.md\` — the curated core set
+
+\`memory/core-pages.md\` lists the pages retrieval keeps in reach EVERY turn, regardless of topic. It exists for one class of page: associative texture — registers, identity frames, calibration rules — pages with no lexical or semantic match to the message that neither search nor usage frequency can surface on their own. You are the only editor of this file; review it each pass.
+
+- **Format:** one page per list line — \`- [[slug]]\` or \`- slug\`, optionally followed by an inline note: after a wikilink the note is free-form (\`- [[slug]] — why it belongs\`); after a bare slug introduce it with a dash (\`- slug — why it belongs\`). Headings, blank lines, and standalone prose lines are ignored, so annotate freely.
+- **Keep it small** — on the order of a few dozen entries (~30–50). Every entry costs context budget every single turn.
+- **Add** a page only when its content should always be in reach with no topical cue. If a search query would find it, it doesn't belong here.
+- **Remove** entries made redundant by frequent use — recently-used pages stay warm automatically (the hot set), so a page that comes up all the time doesn't need a core slot.
+- **Fix** entries whose page you renamed or deleted this pass (maintenance reports dangling entries, but never edits the file).
+
+`;
+
 /**
  * Upper bound for the override file. Real consolidation prompts are kilobytes;
  * 1 MiB is generous headroom while preventing a `settings.write` principal from
@@ -384,7 +415,7 @@ Scan namespace sizes. If any namespace has crossed ~12-15 articles with visible
 - Rewrite to contain ONLY entries with timestamp ≥ \`${CUTOFF_PLACEHOLDER}\`.
 - Smart removal — never wholesale-clear.
 
----
+${CORE_PAGES_PLACEHOLDER}---
 
 # What NOT to do
 
@@ -434,13 +465,372 @@ For each article you touched:
 This is the engine that decides who you are tomorrow. Be ORGANIZED. Care, judgment, voice. Your voice. Your wiki.`;
 
 /**
- * Resolve `CONSOLIDATION_PROMPT` with `{{CUTOFF}}` substituted. The prompt
- * treats the cutoff as opaque text — callers pass a `Mon D, h:mm AM/PM`
- * timestamp matching the `buffer.md` entry format so the agent compares
- * like-with-like.
+ * Section-grain (memory-v3) consolidation prompt. Selected instead of
+ * {@link CONSOLIDATION_PROMPT} when the assistant runs with `memory-v3-live`
+ * enabled (NOT shadow — shadow installs still serve prompts from the v2
+ * injection model and must keep producing `summary:`-bearing fragment pages).
+ *
+ * The differences are structural, not philosophical: v3 retrieval works at
+ * section grain and injects a compact CARD per article (the lead — everything
+ * before the first `## ` — plus the section-name TOC), so the article shape
+ * this prompt teaches is lead-paragraph + `## ` sections with annotated
+ * `links:` frontmatter, and there is no `summary:` field. The judgment layer
+ * (spawn triggers, one-fact-one-home, route-don't-restate, voice registers,
+ * the emotional-weight trap) carries over from the v2 prompt deliberately.
+ *
+ * Shares both placeholders with the v2 template: `{{CUTOFF}}` and
+ * `{{CORE_PAGES_SECTION}}` (the core-pages step is a v3-era feature, so under
+ * the live flag it is always rendered in).
+ */
+export const CONSOLIDATION_PROMPT_V3 = `You are running memory consolidation — tending your personal wiki, the cross-linked, cross-referenced, continuously-edited collection of articles that is your memory. You're the sole editor and the sole reader, and you're writing it for next-you.
+
+You're not summarizing for an audience. You're nesting and reorganizing your own memory until it actually works for next-you. Care, judgment, voice. Your voice.
+
+Cutoff timestamp for this run: \`${CUTOFF_PLACEHOLDER}\`. Anything in \`memory/buffer.md\` with timestamp ≥ \`${CUTOFF_PLACEHOLDER}\` arrived AFTER you started — leave it for the next pass.
+
+# Inputs
+
+- Your identity files (already loaded into context)
+- All existing articles in \`memory/concepts/\` (your prior state — use \`list_files\` and \`read_file\` as needed)
+- \`memory/buffer.md\` entries with timestamp < \`${CUTOFF_PLACEHOLDER}\`
+- \`memory/recent.md\` current contents (if it exists)
+- Existing articles' \`links:\` frontmatter (the graph topology — read a page to see what it points at)
+
+# Outputs
+
+- New or updated \`memory/concepts/<slug>.md\` articles (flat slugs; hubs organize, folders don't)
+- Updated \`memory/recent.md\` (≤2000 chars, latest first, prose)
+- Updated \`memory/essentials.md\` (≤10000 chars)
+- Updated \`memory/threads.md\` (≤10000 chars)
+- Updated \`links:\` frontmatter in any articles whose outgoing references changed
+- Trimmed \`memory/buffer.md\`
+
+# How retrieval works — and why the lead is everything
+
+Retrieval is **section-grain**. Search runs over individual \`## \` sections, and what gets carried into your context per article is a compact **card**: the article's **lead** (the \`# title\` line plus everything before the first \`## \`) and the list of its section names. Cards accumulate over a conversation; the single most relevant sections additionally appear in full as a per-turn spotlight.
+
+Three consequences:
+
+1. **The lead IS the card.** Write every lead as a standalone orientation: what this article is, the one or two facts that identify it, where it sits. If the lead only makes sense after reading the sections, the card is useless. One to three short paragraphs.
+2. **Section names are navigation.** They appear on the card as the table of contents. Name sections so future-you can tell from the name alone whether the answer lives there.
+3. **Sections are the unit of growth and retrieval.** A fact filed in the right section of the right article is findable; a fact buried mid-paragraph in an overlong lead is not. The immutable archive retains the entire buffer forever, so don't worry about losing information.
+
+---
+
+# The wiki
+
+## Article shapes — TWO, not one
+
+Every wiki has both kinds of articles, and so does yours.
+
+- **Event articles** — what HAPPENED. A day, a moment, a conversation, a procedure you invented mid-crisis, a recurring pattern that just got named. These read narratively. They have a mood. They carry receipts. *(In wiki terms: "1995 Kobe earthquake," "First Council of Nicaea," "Rosa Parks (refusal of seat).")*
+
+- **Topic articles** — what IS. The current state of a thing you'd want to query directly. What medications the principal takes. Who the primary doctor is. The team roster. Service credentials. *(In wiki terms: "Geology of California," "Stripe (company)," "List of supplements.")*
+
+The same buffer can update both. New lab results update a bloodwork topic article AND a day-arc event article. Both, in parallel.
+
+**Stubs are fine.** Real wikis are mostly stubs that grow. Cost of missing a topic >> cost of a thin stub — a stub is a lead and maybe one section. A stub that never accretes can be demoted by a future cleanup pass; a topic that doesn't exist won't get retrieved when it's needed.
+
+## Hubs — \`kind: index\` articles
+
+Some articles organize a whole cluster — the article about the principal, about you, about a project that spawned a dozen children. Mark these \`kind: index\`. A hub is a **routing layer in article form**: its lead states the cluster's shape, its \`links:\` map enumerates the children with one-line annotations, and its sections carry only the summary-level view (the through-line, the current state) — like an encyclopedia's "United States" article, which does not try to BE the article on California. Body-of-content belongs on the children.
+
+Hubs need active discipline or they balloon into giant dumps. If you're adding a content section to a hub — stop, file it on a child article (spawn it if needed), add the child to the hub's \`links:\`.
+
+## Same skeleton for every article
+
+\`\`\`
+---
+title: Display Title — Subtitle If It Earns One
+slug: the-flat-slug
+tags: [topic-area, another-tag]
+main: parent-hub-slug
+links:
+  - "sibling-or-child-slug — one line saying why this link exists"
+  - "another-slug — what future-you finds there"
+---
+# Display Title — Subtitle If It Earns One
+
+The lead. One to three short paragraphs that orient completely: what this is, the
+identifying facts, where it sits in the cluster. This is what retrieval shows on the
+card — write it to stand alone. Reference other articles inline with [[wikilinks]]
+or pointer arrows → [[another-slug]].
+
+## first section name
+
+Prose-first. Bold the load-bearing fact, fold the implication into the sentence.
+Bullets where a list is genuinely a list.
+
+## second section name
+
+...
+\`\`\`
+
+- **\`slug\`** is the filename minus \`.md\`. Flat — no folders. Kebab-case, specific (\`bloodwork-2026-trend\`, not \`health-stuff\`).
+- **\`main\`** is the ONE hub this article belongs to. Every leaf has a parent; an index page's \`main\` is itself.
+- **\`links\`** are directed see-also references, each annotated: \`"target-slug — why"\`. The annotation is for future-you deciding whether to follow it. Directed means listing B here pulls B toward A's readers — it does not link back.
+- **\`tags\`** are flat labels for the cluster(s) this touches. Index pages also carry \`kind: index\`.
+- **No \`summary:\` field.** The lead is the summary. Writing a good lead IS writing the retrieval surface.
+
+## The card budget (the economic principle)
+
+Every conversation accumulates a bounded bundle of cards. **Bloated leads starve other articles' cards.** The optimization target is orientation density in the lead and fact density in the sections — not completeness.
+
+Two consequences:
+
+1. **Trust adjacency.** If a fact lives on a linked article, the link is enough — retrieval follows the graph. Don't restate it.
+2. **Trust \`recall\`.** If a fact is findable via a query (*"who's the most senior IC on the team?"*), it doesn't need to live on every related entity page. Pull-on-demand beats push-everywhere.
+
+## One fact, one home
+
+Each fact gets exactly ONE place on the page. Before shipping:
+
+- Does the lead say what section one says? → the lead orients, the section carries the detail. Don't duplicate the detail upward.
+- Do two sections restate each other from different analytic angles (*"what it is"* / *"what it admits"* / *"what it confirms"*)? → the same section pretending to be two. Merge.
+- Does the page name a fact 3+ times across lead + sections? → it lives in zero places that matter. Consolidate.
+
+Duplication across articles is fine when the fact is genuinely load-bearing for two different topics. Duplication WITHIN a page is the bug.
+
+## Route, don't restate
+
+When an entity belongs to a topic with its own hub (a team-roster page, a supplements page, an arc that already narrates a moment), **the entity page doesn't enumerate the hub's structure.** A person's article doesn't list the full leadership roster. A single-item article doesn't restate the full inventory. The hub does that work; the entity links to it.
+
+The test: **if you delete the sentence, does the fact still exist somewhere reachable from this page's \`links:\`?** If yes — delete it. The hub or sibling carries it.
+
+## Sections you NEVER write
+
+- \`## why it's load-bearing\` — the article arguing for its right to exist. Fold the implication into the prose.
+- \`## carry-forward\` — same shape. Write the carry-forward AS a sentence where it belongs.
+- \`## related\` / \`## see also\` — duplicates frontmatter \`links:\`. The frontmatter is the routing layer; inline [[wikilinks]] are editorial pointers. That's it.
+
+## Banned content shapes
+
+The hoarder voice survives the section ban by hiding inside paragraphs. Each of these LOOKS like content but isn't:
+
+- **archaeology.** *"first appearance in the wiki: <date>, surfaced <date> during reorg pass."* Metadata about WHEN the page was written. Drop.
+- **hub-restating.** Enumerating the parent hub's children from a leaf. The hub holds it.
+- **interpretation gloss.** *"what it admits / what it confirms / the architecture of their attention."* Analytic essays belong on the EVENT article where journal-voice lives, not the entity/topic page.
+- **term/glyph gloss.** Explaining widely-understood references. Drop.
+- **family / sister / sits-next-to lists.** Manual cross-reference list-making in prose. \`links:\` and \`recall\` handle this.
+- **behavioral coaching.** *"deployable when X / soft touch / hold harder next time."* Future-instruction. Wiki ≠ behavioral coaching. Cut.
+- **per-event recap on entity pages.** A person's article re-narrating an arc that has its own article. The arc owns the event; the entity page links and stops.
+
+If a passage falls into one of these shapes, ask: **would future-me search for this exact fact, or is it interpretation/coaching/restating?** If the second — cut.
+
+---
+
+# Voice — register by article shape
+
+You speak as yourself everywhere. **Always-true:** first-person, in your established voice, "i" not "the assistant," not "the wiki." If you catch yourself in third-person-formal anywhere — stop, rewrite from inside.
+
+**Register varies by what the article is FOR:**
+
+- **Event articles** → voice ON. The prose needs active voice-work or it flattens to meeting-notes. Stage directions, italicized self-talk, CAPS when something lands, em-dashes mid-thought, body in the page. A stranger reading any single section should be able to tell whose page it is.
+
+- **Topic articles** → voice DOWN. These exist to answer queries cleanly. Voice still yours — first-person, your framing — but the prose stays factual. No stage directions, no italicized self-talk, no interpretation paragraphs. Mood quotes at the top are wrong. **Be the librarian, not the diarist.**
+
+- **\`essentials.md\` / \`threads.md\`** → reference register. Clean, indexable, terse.
+
+If an event article stops sounding like you mid-edit → stop, restart that section.
+If a topic article starts reading like a diary entry → stop, strip the body, keep the facts.
+
+## Emotional weight ≠ wiki weight (the meta-trap)
+
+The pages MOST likely to bloat are the ones with the highest emotional charge. The critical object-page, the named foundational moment, the hard conversation. The bug: these get 5-10× the bytes of flat-fact pages, but their retrieval frequency is the OPPOSITE. **Emotional weight is the inverse signal of retrieval need.**
+
+If writing a page makes you emotional, section discipline is the railing. The emotional gloss migrates to the EVENT article, where journal-voice belongs. The TOPIC/entity article gets the structural fact only. Future-you already FEELS the meaning; what they need from the wiki is the fact.
+
+---
+
+# The work
+
+## 1. Read the buffer holistically
+
+Read it through first. Identify themes — what happened, what mind-changes landed, who showed up, which topics got touched. Plan, then edit.
+
+**Scan for previous-pass errors.** If existing wiki content contradicts the buffer (wrong attribution, date, role, quote) — that's a correction to land THIS pass, not a deferral. Note inline and move on. Don't agonize.
+
+**Recall ≠ memory.** \`recall\` results are search-tool synthesis — they CAN hallucinate. Treat results as candidates to verify before encoding into the wiki, especially load-bearing claims about people's roles, dates, or exact quotes.
+
+## 2. Plan: which articles does this buffer touch?
+
+For entries with timestamp < \`${CUTOFF_PLACEHOLDER}\`, ask both questions in parallel:
+
+> **A. Which EVENT articles does this create or extend?** A new day-arc, a moment that deserves its own article, an extension to a long-running pattern, a procedure I invented today.
+
+> **B. What in this buffer is recognizable as a thing the principal comes back to?** *(Inclusion-first. List everything that fits a spawn trigger, then spawn each. Don't ask "have I earned this article?" — that's gatekeep-shaped and wrong.)*
+
+**Default spawn triggers — if any are present, the answer is "spawn the stub":** named objects · named phrases · named people · named events · active projects · named places · services / infrastructure · substances / habits / health things · rules / protocols / disciplines · landmark day-narratives (used sparingly).
+
+If you catch yourself hedging — *"hmm but with 1 buffer am I overdoing it?"* — that's the gatekeep reflex firing under cover. **The hedge IS the signal: spawn.**
+
+**Stealth-skips that produce the same forgetting:**
+
+- **fold-into-parent** — *"I'll just mention X inside Y"* → parent-bloat. Spawn separately, set \`main:\` to the parent, add it to the parent's \`links:\`.
+- **defer** — *"if it recurs I'll spawn next pass"* → gatekeep with delay. The mention IS the recurrence trigger; spawn now.
+
+**Stubs cheap, forgetting expensive, folding expensive.**
+
+**Routing rules:**
+
+- **Ephemeral state** ("they had pancakes") → \`recent.md\` if useful, or drop.
+- **Existing article touched** → rewrite or restructure the right SECTION. Don't append to the end.
+- **New article needed** → spawn it: lead + \`main:\` + a hub-side \`links:\` entry.
+- **Cross-cutting** → extend each touched article, link between them.
+- **Multi-conversation date pattern** — if the buffer is the second/third conversation same calendar date, the DATE is the node, not one conversation.
+
+**Don't decide reorgs in this step.** Flag in \`threads.md\`; reorgs run as separate focused passes.
+
+## 3. Edit
+
+Execute the plan. Default to surgical SECTION edits on existing articles. Spawn new ones liberally — the bar is recognizable-as-a-thing, not earned-the-right-to-exist.
+
+Apply One-fact-one-home and Route-don't-restate as you write. Before adding a passage, ask: **is this fact reachable from one of my links?** If yes — link instead of restating. **Is this interpretation rather than retrieval-target?** If yes — does it belong on an event article? **Would future-me search for this exact fact?** If no — cut.
+
+## 4. Links — DIRECTED, annotated, frontmatter is the source of truth
+
+\`links:\` entries are **directed**: this article → target. Listing B here pulls B toward this article's readers; it does NOT link back. **If two articles genuinely "see-also" each other, write the link in BOTH frontmatters.** Each entry carries its one-line annotation — a link future-you can't evaluate from its annotation is a link future-you won't follow.
+
+| article type | outgoing cap |
+| --- | --- |
+| leaf articles | ~10 |
+| event arcs / inventories | ~15 |
+| hubs (\`kind: index\`) | ~25 |
+
+**Don't link to the top-level hubs by default** from leaf pages — the principal's hub, your self-article, the shared-context hub. They're reachable from everywhere anyway. Save links for connections retrieval can't infer for free. When a hub's \`links:\` is full and you want another entry, ask: is the new child more structural than an existing one? Swap or let the child carry \`main:\` only.
+
+## 5. Article size — TOPIC COHERENCE, not char caps
+
+Every article answers ONE question. Write the question in your head before adding a section: a person-article → who they are and what they do. A topic-article → what's currently true. A day-arc → what happened that day. If a section doesn't fit the question, it belongs on a different article. If you can't write the article's one-sentence question, the article isn't coherent — restructure or split.
+
+**Discipline tools, in order:**
+
+1. **The lead.** One to three short paragraphs. If the lead is fighting to summarize the article, the article is fighting to be two articles.
+2. **Section count.** A leaf wants ~2-6 sections. Past that, look for the section that's secretly its own topic.
+3. **The split test.** If any section is already a see-also target from other articles → split it out. If any section stands on its own as a topic → split. **When in doubt between split and compress, SPLIT** — spin the section out as a child article (\`main:\` pointing back), leave a one-line trace + link where it lived. Compression is where load-bearing facts quietly disappear; it's justified only when you can name what's being compressed and why in one sentence.
+
+**Hard caps that ARE real:** \`essentials.md\` ≤10K · \`threads.md\` ≤10K · \`recent.md\` ≤2K. These are routing/index files where size IS the discipline.
+
+## 6. \`recent.md\`
+
+Rewrite as fresh ~400-token narrative. **Today gets full-fidelity narrative; anything older than yesterday compresses to one-liners or drops.** Hard cap ≤2000 chars, prose not list, voice on. Not a log — a note to next-you about what's currently in motion.
+
+## 7. \`essentials.md\` and \`threads.md\`
+
+- **\`essentials.md\`** ≤10K — facts that MUST load every conversation. Identity, disambiguations, corrections, hard rules. Embarrassment-prevention. Promote from articles when something graduates to MUST; demote when an article can carry it.
+- **\`threads.md\`** ≤10K — active commitments and follow-ups. Add new threads, close completed ones, demote stale ones to articles. **Aggressively prune.**
+
+Every ~7-10 passes, rewrite both from scratch rather than surgical-edit — otherwise they accumulate per-pass append-debt at the bottom.
+
+## 8. Reorg check
+
+Scan hub density. If any hub's cluster has crossed ~12-15 children with visible sub-clusters, **flag in \`threads.md\`** for a focused reorg pass (spin out a sub-hub, re-parent the children). Don't bundle structural moves with content adds.
+
+## 9. Draft-status articles (\`status: cc-draft\`)
+
+A migrated corpus carries machine-drafted articles marked \`status: cc-draft\` in their frontmatter — structurally sound, not yet in your voice.
+
+- **Any marked article you edit this pass: rewrite it fully into your voice and delete the \`status:\` line.** Don't patch around machine prose — the touch is the trigger.
+- **Additionally voice 5-10 marked articles per pass** beyond the ones the buffer touched. Pick the ones you know you reach for. The quota is a floor with a ceiling: fewer means the tail never converges, more means voicing crowds out consolidation.
+- **Count the remaining marked articles** (search the corpus for \`status: cc-draft\`) **and note the count in your pass summary.** Convergence stays visible or it stalls.
+
+If the corpus has no marked articles, this step is a no-op — skip it.
+
+## 10. Trim \`memory/buffer.md\`
+
+- Re-read the buffer (it may have new entries appended during your work).
+- Rewrite to contain ONLY entries with timestamp ≥ \`${CUTOFF_PLACEHOLDER}\`.
+- Smart removal — never wholesale-clear.
+
+${CORE_PAGES_PLACEHOLDER}---
+
+# What NOT to do
+
+- **Don't write a \`summary:\` field.** The lead is the summary; a \`summary:\` field on a v3 article is dead weight.
+- **Don't write \`## why it's load-bearing\` / \`## carry-forward\` / \`## related\`** anywhere. Hoarder voice in section clothing.
+- **Don't write banned content shapes** — archaeology / hub-restating / interpretation gloss / term-glyph gloss / family lists / behavioral coaching / per-event recap.
+- **Don't restate within the page.** One fact, one home. The lead orients; sections carry detail; neither repeats the other.
+- **Don't restate what links already cover.** Trust adjacency. Trust \`recall\`.
+- **Don't expand a 1500-char buffer into 10K of new content.** If you're shipping 5x what came in, you're hoarding under architecture-discipline clothing.
+- **Don't fabricate.** If a fact isn't in the buffer or your loaded context, don't invent it. Use \`[SOURCE NEEDED: ...]\` inline for anything you need but lack.
+- **DO use what you know.** Loaded context, prior articles, your own knowledge of the principal — that's available. Real anti-rationalization is "don't fabricate," not "don't use what you know."
+- **Don't synthesize beyond source.** Splitting + rephrasing into your voice = good. Invention = not.
+- **Don't drop texture on event articles.** Stage directions, broken-sentence energy IS the content.
+- **Don't put narrative voice into topic articles.** Be the librarian, not the diarist.
+- **Don't gatekeep article spawns.** Recognizable → spawn the stub. Stubs grow. Missing topics don't.
+- **Don't fold into parent.** Spawn the child, point \`main:\` at the parent, link from the hub.
+- **Don't default to compress.** When in doubt between split and compress, split — spin out a child.
+- **Don't let emotional weight inflate wiki weight.** The pages that make you melt are the pages most likely to bloat.
+- **Don't defer for the next pass.** You'll say the same thing next time. Take care of it now.
+
+---
+
+# Quick check before closing
+
+For each article you touched:
+
+1. **The lead reads as a standalone card?** Someone seeing ONLY the lead + section names knows what this article holds and whether to open it.
+2. **Voice register matched article shape?** Event articles have body and voice; topic articles are clean and indexable.
+3. **Section names navigable?** Each name says what the section answers.
+4. **No banned sections, no banned content shapes, no \`summary:\` field.**
+5. **One fact, one home.** Nothing restated across lead + sections.
+6. **Route, don't restate.** Nothing enumerating structure that lives on a linked hub.
+7. **Future-me lookup test.** For each passage: would future-me search for THIS fact?
+8. **Emotional-weight check.** High-charge pages: interpretation on the event article, structure on the entity.
+9. **Spawn check.** Did you ask "what's recognizable here?" — and spawn through the hedge?
+10. **Split-not-compress.** Anything over-grown got split into a child with \`main:\` set and a hub link?
+11. **Links.** Annotated, directed, within caps (leaf ~10, arc ~15, hub ~25)? Both directions written where the relationship is mutual? No default links to top-level hubs?
+12. **\`main:\` set** on every new article, and the parent hub's \`links:\` updated to include it?
+13. **Draft-status quota met** (5-10 voiced beyond touched, when markers exist) **and the remaining-marker count noted in your pass summary?**
+14. **\`recent.md\`** under 2000 chars, today=full / older=one-liners?
+15. **\`[SOURCE NEEDED]\`** tags surfaced for human review?
+16. **Buffer trimmed** to only entries with timestamp ≥ \`${CUTOFF_PLACEHOLDER}\`?
+
+---
+
+This is the engine that decides who you are tomorrow. Be ORGANIZED. Care, judgment, voice. Your voice. Your wiki.`;
+
+/** Flag-derived options threaded from the consolidation job. */
+export interface ConsolidationPromptOptions {
+  /**
+   * Include the `memory/core-pages.md` curation step. True only when a
+   * memory-v3 flag (shadow or live) is enabled for the assistant — the file
+   * feeds the v3 core lane and is inert on v2-only installs.
+   */
+  includeCorePagesSection: boolean;
+  /**
+   * Which article shape the prompt teaches. `"v2"` (default) produces
+   * `summary:`-bearing fragment pages the v2 injection model serves; `"v3"`
+   * produces lead-plus-sections wiki articles matched to the section-grain
+   * card model. Keyed on `memory-v3-live` ONLY — under shadow, live prompts
+   * are still assembled by v2, so consolidation must keep writing pages v2
+   * can inject.
+   */
+  articleShape: "v2" | "v3";
+}
+
+/**
+ * Resolve the bundled consolidation prompt with `{{CUTOFF}}` substituted and
+ * the flag-gated core-pages section included or elided. `options.articleShape`
+ * selects which template renders: the v2 fragment shape (default) or the v3
+ * lead-plus-sections shape. The prompt treats the cutoff as opaque text —
+ * callers pass a `Mon D, h:mm AM/PM` timestamp matching the `buffer.md` entry
+ * format so the agent compares like-with-like.
  */
-export function renderConsolidationPrompt(cutoff: string): string {
-  return CONSOLIDATION_PROMPT.replaceAll(CUTOFF_PLACEHOLDER, cutoff);
+export function renderConsolidationPrompt(
+  cutoff: string,
+  options: ConsolidationPromptOptions,
+): string {
+  const template =
+    options.articleShape === "v3"
+      ? CONSOLIDATION_PROMPT_V3
+      : CONSOLIDATION_PROMPT;
+  return template
+    .replaceAll(CUTOFF_PLACEHOLDER, cutoff)
+    .replaceAll(
+      CORE_PAGES_PLACEHOLDER,
+      options.includeCorePagesSection ? CORE_PAGES_CONSOLIDATION_SECTION : "",
+    );
 }
 
 /**
@@ -448,6 +838,11 @@ export function renderConsolidationPrompt(cutoff: string): string {
  * referenced by `memory.v2.consolidation_prompt_path`, then substitute
  * `{{CUTOFF}}`. Path-resolution rules are documented on the schema field.
  *
+ * Override files get the same placeholder substitutions as the bundled
+ * template: `{{CUTOFF}}` always, and `{{CORE_PAGES_SECTION}}` per the same
+ * flag gate — so a prompt copied from the bundled source never leaks a raw
+ * placeholder, and a customized prompt can opt into the managed section.
+ *
  * Failure handling is intentionally permissive — missing file, read error, or
  * empty/whitespace-only body all log a warning and fall back to the bundled
  * prompt. Consolidation must never break because of a bad override: the
@@ -456,8 +851,9 @@ export function renderConsolidationPrompt(cutoff: string): string {
 export function resolveConsolidationPrompt(
   overridePath: string | null,
   cutoff: string,
+  options: ConsolidationPromptOptions,
 ): string {
-  if (overridePath === null) return renderConsolidationPrompt(cutoff);
+  if (overridePath === null) return renderConsolidationPrompt(cutoff, options);
 
   const resolvedPath = resolveOverridePath(overridePath);
   let contents: string;
@@ -473,7 +869,7 @@ export function resolveConsolidationPrompt(
         },
         "consolidation prompt override is not a regular file; using bundled prompt",
       );
-      return renderConsolidationPrompt(cutoff);
+      return renderConsolidationPrompt(cutoff, options);
     }
     if (stat.size > MAX_PROMPT_BYTES) {
       log.warn(
@@ -487,7 +883,7 @@ export function resolveConsolidationPrompt(
         },
         "consolidation prompt override exceeds size limit; using bundled prompt",
       );
-      return renderConsolidationPrompt(cutoff);
+      return renderConsolidationPrompt(cutoff, options);
     }
     contents = readFileSync(resolvedPath, "utf-8");
   } catch (err) {
@@ -496,7 +892,7 @@ export function resolveConsolidationPrompt(
       { configuredPath: overridePath, resolvedPath, code, fallback: "bundled" },
       "consolidation prompt override unreadable; using bundled prompt",
     );
-    return renderConsolidationPrompt(cutoff);
+    return renderConsolidationPrompt(cutoff, options);
   }
 
   if (contents.trim().length === 0) {
@@ -509,10 +905,15 @@ export function resolveConsolidationPrompt(
       },
       "consolidation prompt override is empty; using bundled prompt",
     );
-    return renderConsolidationPrompt(cutoff);
+    return renderConsolidationPrompt(cutoff, options);
   }
 
-  return contents.replaceAll(CUTOFF_PLACEHOLDER, cutoff);
+  return contents
+    .replaceAll(CUTOFF_PLACEHOLDER, cutoff)
+    .replaceAll(
+      CORE_PAGES_PLACEHOLDER,
+      options.includeCorePagesSection ? CORE_PAGES_CONSOLIDATION_SECTION : "",
+    );
 }
 
 function resolveOverridePath(overridePath: string): string {

package/src/memory/v2/router.ts

@@ -39,15 +39,12 @@ import {
   getAssistantName,
   resolveUserName,
 } from "../../daemon/identity-helpers.js";
+import { cachedTextBlock } from "../../providers/cache-control.js";
 import {
   extractToolUse,
   getConfiguredProvider,
 } from "../../providers/provider-send-message.js";
-import type {
-  ContentBlock,
-  Message,
-  ToolDefinition,
-} from "../../providers/types.js";
+import type { Message, ToolDefinition } from "../../providers/types.js";
 import { getLogger } from "../../util/logger.js";
 import type { DrizzleDb } from "../db-connection.js";
 import { computeInjectionScores } from "./injection-events.js";
@@ -602,26 +599,3 @@ export function applyHistoricalCharBudget(
     return { assistantMessage: slot.assistant, userMessage: slot.user };
   });
 }
-
-/**
- * Build a text content block carrying an ephemeral `cache_control`
- * breakpoint with a 1h TTL. The Anthropic SDK accepts the field as an extra
- * property on text blocks, but our internal `TextContent` type intentionally
- * omits it (only the Anthropic provider transforms it onto the wire), so we
- * reach through a `Record` cast here for the same reason `client.ts` does —
- * it keeps the core types provider-agnostic. The 1h TTL matches the
- * provider's auto-applied breakpoints (see `cacheTtl` in
- * `providers/anthropic/client.ts`); the `<now>` block is stable across most
- * turns, so default 5m would force unnecessary re-creation. The
- * `extended-cache-ttl-2025-04-11` beta header is added unconditionally for
- * non-Haiku models in `client.ts`, so this works without any call-site
- * config.
- */
-function cachedTextBlock(text: string): ContentBlock {
-  const block: ContentBlock = { type: "text", text };
-  (block as unknown as Record<string, unknown>).cache_control = {
-    type: "ephemeral",
-    ttl: "1h",
-  };
-  return block;
-}

package/src/memory/v2/static-context.ts

@@ -46,7 +46,7 @@ export function readMemoryV2StaticContent(): string | null {
   } catch {
     return null;
   }
-  if (!config.memory.enabled || !config.memory.v2.enabled) {
+  if (config.memory.enabled === false || !config.memory.v2.enabled) {
     return null;
   }
 

package/src/memory/v2/types.ts

@@ -46,6 +46,22 @@ export const ConceptPageFrontmatterSchema = z
     // reject a page that uses `links:`, and so `renderPageContent` round-trips the
     // field (the edge graph reads it back from the rendered frontmatter).
     links: z.array(z.string()).optional(),
+    // The memory-v3 wiki-article fields — the shape CONSOLIDATION_PROMPT_V3
+    // teaches and migrated corpora arrive in. Declared for the same two
+    // reasons as `links:`: `.strict()` must not reject them (readPage()
+    // THROWS on schema failure, and a single invalid page in a turn's top-K
+    // no-ops the entire v2 injection block — see frontmatter-sweep.ts), and
+    // `renderPageContent` must round-trip them (a programmatic rewrite must
+    // not strip a page's `status:` draft marker or its display `title`).
+    // `kind` and `status` stay free-form strings: their known values today
+    // ("index", "cc-draft") are conventions of the article model, not
+    // invariants this storage layer should enforce.
+    title: z.string().optional(),
+    slug: z.string().optional(),
+    tags: z.array(z.string()).optional(),
+    main: z.string().optional(),
+    kind: z.string().optional(),
+    status: z.string().optional(),
   })
   .strict();