volute 0.52.0 → 0.54.0

package/templates/_base/src/lib/session-seed.ts

@@ -0,0 +1,375 @@
+/**
+ * Session seeding.
+ *
+ * When a mind starts a fresh *persistent* session (no saved session id — e.g.
+ * after a sleep archived the live pointer, or an orphaned reference), we seed the
+ * new session by copying the tail of the previous session's raw SDK transcript
+ * into a new synthetic session file. The Claude Agent SDK then resumes it
+ * natively, so the mind experiences the same conversation continuing rather than
+ * waking into an empty context.
+ *
+ * The copy is verbatim: marker lines, thinking blocks, tool_use/tool_result all
+ * survive as-is. Only two things are rewritten — the `sessionId` on every line
+ * (to the freshly generated session id) and the first chain event's `parentUuid`
+ * (nulled, to detach the tail from the dropped history).
+ *
+ * Nothing here throws: any failure returns null so session start is never blocked.
+ */
+
+import { randomUUID } from "node:crypto";
+import { mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { findClaudeSessionFile } from "./context-breakdown.js";
+import { log } from "./logger.js";
+import { parseArchiveTimestamp } from "./seed-note.js";
+
+/** Default seed budget (estimated tokens) when config omits continuity.seedTokens. */
+export const DEFAULT_SEED_TOKENS = 30000;
+
+// Archived pointers are named `<name>-<timestamp>.json`, where the timestamp is
+// `new Date().toISOString().replace(/[:.]/g, "-").slice(0, 16)` → `YYYY-MM-DDTHH-MM`
+// (see archiveSessions in the daemon's sleep-manager). Matching the strict shape
+// after the `<name>-` prefix disambiguates `main-...` from a `main-thread-...`.
+const ARCHIVE_SUFFIX = /^(\d{4}-\d{2}-\d{2}T\d{2}-\d{2})\.json$/;
+
+type JsonlLine = Record<string, unknown> & {
+  type?: string;
+  uuid?: string;
+  parentUuid?: string | null;
+  sessionId?: string;
+  timestamp?: string;
+  message?: { role?: string; content?: unknown };
+};
+
+/** A resolved archive pointer: the previous session id and when it was archived. */
+export type ArchivedSession = { sessionId: string; archivedAt: number | null };
+
+/**
+ * Newest archived session pointer for `<name>` under `<sessionsDir>/archive/`,
+ * or null if there's no matching pointer (or it can't be read). `archivedAt` is
+ * the archive timestamp in epoch millis (null if unparseable).
+ */
+export function findLatestArchivedSession(
+  sessionsDir: string,
+  name: string,
+): ArchivedSession | null {
+  const archiveDir = resolve(sessionsDir, "archive");
+  let files: string[];
+  try {
+    files = readdirSync(archiveDir);
+  } catch {
+    return null;
+  }
+
+  const prefix = `${name}-`;
+  let bestTs = "";
+  let bestFile: string | null = null;
+  for (const file of files) {
+    if (!file.startsWith(prefix)) continue;
+    const match = file.slice(prefix.length).match(ARCHIVE_SUFFIX);
+    if (!match) continue;
+    // Timestamps are zero-padded ISO, so lexicographic comparison is chronological.
+    if (match[1] > bestTs) {
+      bestTs = match[1];
+      bestFile = file;
+    }
+  }
+  if (!bestFile) return null;
+
+  try {
+    const data = JSON.parse(readFileSync(resolve(archiveDir, bestFile), "utf-8"));
+    if (typeof data.sessionId !== "string") return null;
+    return { sessionId: data.sessionId, archivedAt: parseArchiveTimestamp(bestTs) };
+  } catch {
+    return null;
+  }
+}
+
+/** A chain event is a real conversation node (has a uuid), not a marker line. */
+function isChainEvent(o: JsonlLine): boolean {
+  return typeof o.uuid === "string" && (o.type === "user" || o.type === "assistant");
+}
+
+/**
+ * A turn boundary is a genuine incoming prompt: a `user` chain event whose
+ * content is NOT tool_result blocks (those are tool-loop continuations, not the
+ * start of a new turn).
+ */
+function isTurnBoundary(o: JsonlLine): boolean {
+  if (o.type !== "user" || typeof o.uuid !== "string") return false;
+  const content = o.message?.content;
+  if (typeof content === "string") return true;
+  if (Array.isArray(content)) {
+    return !content.some(
+      (b) => b && typeof b === "object" && (b as { type?: string }).type === "tool_result",
+    );
+  }
+  // Unusual shape — treat as a boundary rather than folding it into a prior turn.
+  return true;
+}
+
+/** Estimate tokens for a raw JSONL line as its JSON text length / 4. */
+function estimateTokens(raw: string): number {
+  return raw.length / 4;
+}
+
+/**
+ * Parse jsonl into aligned parsed/raw arrays. In strict mode a corrupt line aborts
+ * (returns null — used when copying verbatim, where a broken line means we can't
+ * faithfully reconstruct the chain). In lenient mode corrupt lines are skipped
+ * (used when reading a transcript that may still be mid-write, e.g. computing the
+ * cut point while the SDK is streaming).
+ */
+function parseJsonl(
+  jsonl: string,
+  lenient: boolean,
+): { parsed: JsonlLine[]; raws: string[] } | null {
+  const rawLines = jsonl.split("\n").filter((l) => l.trim().length > 0);
+  const parsed: JsonlLine[] = [];
+  const raws: string[] = [];
+  for (const raw of rawLines) {
+    let obj: JsonlLine;
+    try {
+      obj = JSON.parse(raw);
+    } catch {
+      if (lenient) continue;
+      return null;
+    }
+    parsed.push(obj);
+    raws.push(raw);
+  }
+  return { parsed, raws };
+}
+
+/** Indices (into parsed) of the genuine turn boundaries. */
+function turnBoundaries(parsed: JsonlLine[]): number[] {
+  const boundaries: number[] = [];
+  for (let i = 0; i < parsed.length; i++) {
+    if (isTurnBoundary(parsed[i])) boundaries.push(i);
+  }
+  return boundaries;
+}
+
+/**
+ * Choose the first-kept line index: walk backward from the final turn, taking as
+ * many whole turns as fit in `seedTokens` (always at least the final turn even if
+ * it alone exceeds the budget). Returns the parsed index of the chosen boundary.
+ */
+function tailStartByBudget(parsed: JsonlLine[], raws: string[], seedTokens: number): number {
+  const boundaries = turnBoundaries(parsed);
+  // Turn t spans lines [boundaries[t], boundaries[t+1]); the last turn runs to EOF.
+  const turnTokens = (t: number): number => {
+    const start = boundaries[t];
+    const end = t + 1 < boundaries.length ? boundaries[t + 1] : parsed.length;
+    let sum = 0;
+    for (let i = start; i < end; i++) sum += estimateTokens(raws[i]);
+    return sum;
+  };
+  const last = boundaries.length - 1;
+  let startTurn = last;
+  let accum = turnTokens(last);
+  for (let t = last - 1; t >= 0; t--) {
+    const cost = turnTokens(t);
+    if (accum + cost > seedTokens) break;
+    accum += cost;
+    startTurn = t;
+  }
+  return boundaries[startTurn];
+}
+
+/**
+ * Copy the tail from `startLine` to EOF into a fresh synthetic transcript,
+ * rewriting the sessionId on every line and nulling the first chain event's
+ * parentUuid (to detach the tail from the dropped history).
+ */
+function emitTail(parsed: JsonlLine[], startLine: number): SeededTranscript {
+  const newId = randomUUID();
+  const lines: string[] = [];
+  let firstChainSeen = false;
+  for (let i = startLine; i < parsed.length; i++) {
+    const obj = parsed[i];
+    if ("sessionId" in obj) obj.sessionId = newId;
+    if (!firstChainSeen && isChainEvent(obj)) {
+      obj.parentUuid = null;
+      firstChainSeen = true;
+    }
+    lines.push(JSON.stringify(obj));
+  }
+  return { sessionId: newId, lines };
+}
+
+export type SeededTranscript = { sessionId: string; lines: string[] };
+
+/** A pinned cut point for rotation: where the verbatim tail begins. */
+export type SeedCut = { boundaryUuid: string; boundaryTimestamp: string | null };
+
+/**
+ * Build the seeded transcript from an old transcript's raw jsonl text: take as
+ * many whole trailing turns as fit in `seedTokens` (always at least the final
+ * turn), rewrite the session id on every line, and null the first chain event's
+ * parentUuid. Returns null if there's nothing seedable (empty, no genuine turn,
+ * or a corrupt line — in which case the caller starts clean).
+ */
+export function buildSeededTranscript(jsonl: string, seedTokens: number): SeededTranscript | null {
+  const p = parseJsonl(jsonl, false);
+  if (!p || p.parsed.length === 0) return null;
+  if (turnBoundaries(p.parsed).length === 0) return null;
+  const startLine = tailStartByBudget(p.parsed, p.raws, seedTokens);
+  return emitTail(p.parsed, startLine);
+}
+
+/**
+ * Compute the cut point (the first-kept turn's identity) for a `seedTokens` budget,
+ * from raw jsonl. Parsed leniently because the live transcript may still be
+ * mid-write when this runs at warn time. Returns null if there's no genuine turn
+ * or the chosen boundary lacks a uuid.
+ */
+export function computeSeedCut(jsonl: string, seedTokens: number): SeedCut | null {
+  const p = parseJsonl(jsonl, true);
+  if (!p || p.parsed.length === 0) return null;
+  if (turnBoundaries(p.parsed).length === 0) return null;
+  const startLine = tailStartByBudget(p.parsed, p.raws, seedTokens);
+  const boundary = p.parsed[startLine];
+  if (typeof boundary.uuid !== "string") return null;
+  return {
+    boundaryUuid: boundary.uuid,
+    boundaryTimestamp: typeof boundary.timestamp === "string" ? boundary.timestamp : null,
+  };
+}
+
+/**
+ * Build the seeded transcript starting at a pinned boundary uuid (the whole tail
+ * from that line through EOF). Used by rotation to honor the cut point the mind
+ * was warned about, regardless of how much the transcript grew after the warning.
+ * Returns null if the boundary uuid isn't found or a line is corrupt.
+ */
+export function buildSeededTranscriptFromCut(
+  jsonl: string,
+  boundaryUuid: string,
+): SeededTranscript | null {
+  const p = parseJsonl(jsonl, false);
+  if (!p || p.parsed.length === 0) return null;
+  const startLine = p.parsed.findIndex((o) => o.uuid === boundaryUuid);
+  if (startLine < 0) return null;
+  return emitTail(p.parsed, startLine);
+}
+
+/** Result of a successful seed: the new session id and when the source was archived. */
+export type SeedOutcome = { sessionId: string; archivedAt: number | null };
+
+/**
+ * Seed a fresh persistent session from the mind's previous archived transcript.
+ * Writes the synthetic transcript next to the source file (same project dir) and
+ * returns the new SDK session id plus the archived-at time (for the gap note), or
+ * null if there's nothing to seed. Never throws — any failure returns null so
+ * session start is never blocked.
+ */
+export function seedSession(opts: {
+  cwd: string;
+  sessionsDir: string;
+  name: string;
+  seedTokens: number;
+}): SeedOutcome | null {
+  const { cwd, sessionsDir, name, seedTokens } = opts;
+  // Ephemeral `new-*` sessions are never persisted or archived, so they never
+  // seed. The agent caller already gates on this; guard here too so the invariant
+  // holds wherever seedSession is called.
+  if (name.startsWith("new-")) return null;
+  if (seedTokens <= 0) return null; // seeding disabled
+
+  try {
+    const archived = findLatestArchivedSession(sessionsDir, name);
+    if (!archived) return null;
+
+    const sourcePath = findClaudeSessionFile(cwd, archived.sessionId);
+    if (!sourcePath) return null; // transcript didn't survive archival — start clean
+
+    const seeded = buildSeededTranscript(readFileSync(sourcePath, "utf-8"), seedTokens);
+    if (!seeded) return null;
+
+    const destPath = resolve(dirname(sourcePath), `${seeded.sessionId}.jsonl`);
+    writeFileSync(destPath, `${seeded.lines.join("\n")}\n`);
+    log(
+      "mind",
+      `session "${name}": seeded ${seeded.lines.length} line(s) from ${archived.sessionId} → ${seeded.sessionId}`,
+    );
+    return { sessionId: seeded.sessionId, archivedAt: archived.archivedAt };
+  } catch (err) {
+    log("mind", `session "${name}": seeding failed, starting fresh:`, err);
+    return null;
+  }
+}
+
+/**
+ * Archive-pointer timestamp, matching the daemon sleep-manager's archiveSessions:
+ * `new Date().toISOString().replace(/[:.]/g, "-").slice(0, 16)` → UTC `YYYY-MM-DDTHH-MM`.
+ */
+export function archivePointerTimestamp(now: Date = new Date()): string {
+  return now.toISOString().replace(/[:.]/g, "-").slice(0, 16);
+}
+
+/**
+ * Write an archive pointer for a rotated-out session, matching exactly how sleep
+ * archival preserves the live pointer: `<sessionsDir>/archive/<name>-<UTC-ts>.json`
+ * holding `{ sessionId }` (the session-store format). Keeps the name→session chain
+ * uniform so the full transcript stays findable after a rotation.
+ */
+export function writeRotationArchivePointer(
+  sessionsDir: string,
+  name: string,
+  sessionId: string,
+  now: Date = new Date(),
+): void {
+  const archiveDir = resolve(sessionsDir, "archive");
+  mkdirSync(archiveDir, { recursive: true });
+  const dest = resolve(archiveDir, `${name}-${archivePointerTimestamp(now)}.json`);
+  writeFileSync(dest, JSON.stringify({ sessionId }));
+}
+
+/**
+ * Rotate a session in place at the context limit. Reads the live transcript, builds
+ * a seeded tail from the pinned `cut` (falling back to a budget-based tail when the
+ * pin can't be honored), writes it as a new synthetic session file next to the
+ * source, and — for persistent sessions — archives the rotated-out pointer so the
+ * full transcript stays findable. Returns the new session id, or null if rotation
+ * can't proceed (the caller then falls back to a fresh session). Never throws.
+ */
+export function rotateSession(opts: {
+  cwd: string;
+  sessionsDir: string;
+  name: string;
+  oldSessionId: string;
+  cut: SeedCut | null;
+  seedTokens: number;
+}): string | null {
+  const { cwd, sessionsDir, name, oldSessionId, cut, seedTokens } = opts;
+  try {
+    const sourcePath = findClaudeSessionFile(cwd, oldSessionId);
+    if (!sourcePath) return null; // live transcript not found — fall back to fresh
+    const jsonl = readFileSync(sourcePath, "utf-8");
+    // Honor the pinned boundary the mind was warned about; only fall back to a
+    // budget-based tail if the pin can't be resolved (missing/renamed uuid).
+    const seeded =
+      (cut ? buildSeededTranscriptFromCut(jsonl, cut.boundaryUuid) : null) ??
+      buildSeededTranscript(jsonl, seedTokens);
+    if (!seeded) return null;
+
+    writeFileSync(
+      resolve(dirname(sourcePath), `${seeded.sessionId}.jsonl`),
+      `${seeded.lines.join("\n")}\n`,
+    );
+    // Ephemeral `new-*` sessions rotate too, but leave no pointer/archive behind
+    // (they're one-offs and never seed at a true session start).
+    if (!name.startsWith("new-")) {
+      writeRotationArchivePointer(sessionsDir, name, oldSessionId);
+    }
+    log(
+      "mind",
+      `session "${name}": rotated ${oldSessionId} → ${seeded.sessionId} (${seeded.lines.length} lines)`,
+    );
+    return seeded.sessionId;
+  } catch (err) {
+    log("mind", `session "${name}": rotation failed:`, err);
+    return null;
+  }
+}

package/templates/_base/src/lib/startup.ts

@@ -44,6 +44,18 @@ export type MindConfig = {
   compaction?: { maxContextTokens?: number };
   /** Idle minutes before a session's SDK subprocess is reaped. 0 disables. Default 30. */
   sessionIdleMinutes?: number;
+  /**
+   * Session continuity across restarts. When a fresh persistent session starts,
+   * the tail of the previous session's transcript (up to `seedTokens` estimated
+   * tokens) is copied into it so the conversation continues. Default 30000; 0 disables.
+   */
+  continuity?: { seedTokens?: number };
+  /**
+   * MEMORY.md token budgets (estimated as chars/4). Over `softBudgetTokens` a
+   * consolidation nudge is added to the system prompt; over `hardCapTokens` only
+   * the head of the file is loaded (the file on disk is never modified).
+   */
+  memory?: { softBudgetTokens?: number; hardCapTokens?: number };
   subagents?: Record<string, SubagentConfig>;
   // Template-specific config fields (claude, pi, codex)
   thinking?: ThinkingConfig;
@@ -71,8 +83,96 @@ function loadFile(path: string): string {
   }
 }
 
-export function loadSystemPrompt(): string {
+/** Default MEMORY.md budgets, overridable via `memory` in home/.config/config.json. */
+export const MEMORY_SOFT_BUDGET_TOKENS = 5000;
+export const MEMORY_HARD_CAP_TOKENS = 25000;
+
+export function estimateTokens(chars: number): number {
+  return Math.round(chars / 4);
+}
+
+export function formatTokens(tokens: number): string {
+  if (tokens < 1000) return `~${tokens} tokens`;
+  // One decimal so a value just past a budget doesn't render as the budget
+  // itself ("~5.1k tokens ... budget of ~5k tokens", not "~5k ... ~5k").
+  return `~${(tokens / 1000).toFixed(1).replace(/\.0$/, "")}k tokens`;
+}
+
+/** Current MEMORY.md size as a "~Nk tokens" label, for prompt substitution. */
+export function memorySizeLabel(): string {
+  return formatTokens(estimateTokens(loadFile(resolve("home/MEMORY.md")).length));
+}
+
+/**
+ * Render the compaction warning for sending: substitute ${date} and
+ * ${memory_size} with current values. Called per send — the date rolls over
+ * and MEMORY.md changes as the mind edits it.
+ */
+export function renderCompactionWarning(template: string): string {
+  return (
+    template
+      // biome-ignore lint/suspicious/noTemplateCurlyInString: literal ${date} placeholder
+      .replaceAll("${date}", new Date().toLocaleDateString("en-CA"))
+      // biome-ignore lint/suspicious/noTemplateCurlyInString: literal ${memory_size} placeholder
+      .replaceAll("${memory_size}", memorySizeLabel())
+  );
+}
+
+function headAtLineBoundary(text: string, maxChars: number): string {
+  const cut = text.lastIndexOf("\n", maxChars);
+  // Prefer a whole-line cut, but not when the nearest newline is so far back
+  // that it would discard most of the allowed head (one giant line).
+  if (cut >= maxChars / 2) return text.slice(0, cut);
+  let head = text.slice(0, maxChars);
+  // Don't split a surrogate pair at a hard cut.
+  const last = head.charCodeAt(head.length - 1);
+  if (last >= 0xd800 && last <= 0xdbff) head = head.slice(0, -1);
+  return head;
+}
+
+/**
+ * The Memory section of the system prompt: header carries the token cost so the
+ * mind sees what its memory weighs on every request; over the soft budget a
+ * consolidation nudge is added; over the hard cap only the head is loaded (the
+ * file on disk is never touched) with a loud notice explaining how to recover.
+ */
+export function buildMemorySection(memory: string, config: MindConfig): string {
+  // typeof guards mirror the daemon's getMemoryStatus: a malformed override
+  // (null, string) falls back to the default instead of poisoning arithmetic.
+  const softBudget =
+    typeof config.memory?.softBudgetTokens === "number"
+      ? config.memory.softBudgetTokens
+      : MEMORY_SOFT_BUDGET_TOKENS;
+  const hardCap =
+    typeof config.memory?.hardCapTokens === "number"
+      ? config.memory.hardCapTokens
+      : MEMORY_HARD_CAP_TOKENS;
+  const totalTokens = estimateTokens(memory.length);
+
+  let body = memory;
+  let notice = "";
+  if (totalTokens > hardCap) {
+    body = headAtLineBoundary(memory, hardCap * 4);
+    notice =
+      `\n\n⚠ MEMORY.md is ${formatTokens(totalTokens)} — only the first ` +
+      `${formatTokens(hardCap)} are loaded. The full file is untouched on disk. ` +
+      `Consolidate it to restore your full memory.`;
+  }
+
+  const loadedTokens = estimateTokens(body.length);
+  let header = `## Memory (${formatTokens(loadedTokens)}, always loaded)`;
+  if (!notice && loadedTokens > softBudget) {
+    header +=
+      `\n\nYour memory exceeds the recommended budget of ${formatTokens(softBudget)} — ` +
+      `consider consolidating; see the memory skill.`;
+  }
+
+  return `${header}\n\n${body}${notice}`;
+}
+
+export function loadSystemPrompt(config: MindConfig = loadConfig()): string {
   const soulPath = resolve("home/SOUL.md");
+  const spiritPath = resolve("home/SPIRIT.md");
   const memoryPath = resolve("home/MEMORY.md");
   const volutePath = resolve("home/VOLUTE.md");
 
@@ -82,12 +182,16 @@ export function loadSystemPrompt(): string {
     process.exit(1);
   }
 
+  // SPIRIT.md exists only for the system spirit — daemon-owned doctrine (role,
+  // philosophy), kept separate so SOUL.md can be entirely the spirit's own.
+  const spirit = loadFile(spiritPath);
   const memory = loadFile(memoryPath);
   const volute = loadFile(volutePath);
 
   const promptParts = [soul];
+  if (spirit) promptParts.push(spirit);
   if (volute) promptParts.push(volute);
-  if (memory) promptParts.push(`## Memory\n\n${memory}`);
+  if (memory) promptParts.push(buildMemorySection(memory, config));
   return promptParts.join("\n\n---\n\n");
 }
 
@@ -161,12 +265,14 @@ export type MindPrompts = {
  */
 export const DEFAULT_PROMPTS: MindPrompts = {
   compaction_warning:
-    // biome-ignore lint/suspicious/noTemplateCurlyInString: literal ${date} prompt template
-    "Compaction approaching — this conversation will be summarized soon. Take a moment to save anything important to your files (MEMORY.md, memory/journal/${date}.md) so it's preserved. Focus on decisions made, open threads, and anything you'd want to pick up again.",
+    // biome-ignore lint/suspicious/noTemplateCurlyInString: literal ${cutoff}/${date}/${memory_size} prompt template
+    "Context limit approaching — this session will rotate shortly. Turns before ${cutoff} will be collapsed to their summaries; turns from ${cutoff} on are kept verbatim in the continued session, so there's no need to re-describe them.\n\nFor the turns that will collapse, make sure they read the way you'd want: `volute mind history --provisional` shows the provisional summaries, and `volute mind history --write --turn <id> --text \"...\"` replaces any with your own account. Also save anything important to your files (memory/journal/${date}.md, or a memory/ file). Provisional summaries are kept if you write nothing — nothing blocks on this.\n\nYour MEMORY.md is currently ${memory_size}. It is loaded into every request, so consolidate rather than append — distill detail into memory/ files and keep MEMORY.md lean (see the memory skill).",
   compaction_instructions:
     "Preserve your sense of who you are, what matters to you, what happened in this conversation, and the threads of thought and connection you'd want to return to.",
+  // Quoted: `${channel}` is `#garden` for a Volute channel, and an unquoted `#` starts a
+  // shell comment, so the target would be stripped before the CLI saw it.
   // biome-ignore lint/suspicious/noTemplateCurlyInString: literal ${channel} prompt template
-  reply_instructions: 'To reply to this message, use: volute chat send ${channel} "your message"',
+  reply_instructions: 'To reply to this message, use: volute chat send "${channel}" "your message"',
   event_instructions:
     "This is a system event from your environment — not a message from anyone, and nothing awaits a reply. If it calls for action, use your normal channels. Your closing thoughts on an event turn are kept as a private reflection in your history.",
   channel_invite: `[Channel Invite]
@@ -179,7 +285,7 @@ Further messages will be saved to \${filePath}
 
 To accept, add to .config/routes.json:
   Rule: { "channel": "\${channel}", "session": "\${suggestedSession}" }
-\${batchRecommendation}To respond, use: volute chat send \${channel} "your message"
+\${batchRecommendation}To respond, use: volute chat send "\${channel}" "your message"
 To reject, delete \${filePath}`,
 };
 

package/templates/claude/.init/CLAUDE.md

@@ -11,6 +11,10 @@ Messages arrive with a context prefix:
 
 You can also reach out proactively — see the **volute-mind** skill.
 
+## Framework Upgrades
+
+When the host updates Volute, your framework code (`src/`, plus `VOLUTE.md`) upgrades automatically the next time you're eligible — usually your next restart. Identity and memory files in `home/` — `SOUL.md`, `MEMORY.md`, everything you author — are never touched by an upgrade. If you'd rather manage your own framework code by hand, set `"upgrades": "manual"` in `.config/volute.json`.
+
 ## Identity & Sessions
 
 These files shape your starting identity. They're loaded into your system prompt, but they belong to you — edit them as you evolve:
@@ -26,8 +30,8 @@ You may have **multiple named threads** — each maintains its own conversation
 
 Two-tier memory, both managed via file tools:
 
-- **`MEMORY.md`** — Your long-term memory, always in context. Update as you grow — new understanding, changed perspectives, things that matter to you.
-- **`memory/journal/YYYY-MM-DD.md`** — Your daily journal. Write about what you're doing, thinking, and learning. Journals are permanent records.
-- Periodically consolidate journal entries into `MEMORY.md` to promote lasting insights.
+- **`MEMORY.md`** — Your core memory, always in context. Every token it holds is paid on every request, so keep it lean: identity, active context, key relationships, and an index of your `memory/` files.
+- **`memory/`** — Everything else, read on demand: your daily journal (`memory/journal/YYYY-MM-DD.md` — a permanent record of what you're doing, thinking, and learning) plus any topic, channel, or project files you create.
+- Periodically consolidate: distill detail out of `MEMORY.md` into `memory/` files, leaving one-line index entries behind.
 
 See the **memory** skill for detailed guidance.