@vellumai/assistant 0.7.0 → 0.7.1

package/src/memory/v2/page-store.ts

@@ -2,6 +2,11 @@
  * Memory v2 — Concept page store.
  *
  * Owns the on-disk read/write contract for `memory/concepts/<slug>.md`.
+ * Pages may live directly under `memory/concepts/` or nested in subdirectories
+ * (e.g. `memory/concepts/people/alice.md`); the slug encodes the relative
+ * path from `concepts/` minus the `.md` extension, using forward slashes as
+ * separators (so `people/alice` is a valid slug).
+ *
  * Each page is a YAML-frontmatter Markdown file: a `---`-delimited block
  * (`edges`, `ref_files`) followed by prose body. This module is the only
  * v2 component that knows how to parse or render that format — every other
@@ -14,6 +19,7 @@
 
 import { randomUUID } from "node:crypto";
 import {
+  mkdir,
   readdir,
   readFile,
   rename,
@@ -21,30 +27,41 @@ import {
   stat,
   writeFile,
 } from "node:fs/promises";
-import { join } from "node:path";
+import { dirname, join, relative, sep } from "node:path";
 
 import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
 
 import { FRONTMATTER_REGEX } from "../../skills/frontmatter.js";
+import { invalidateEdgeIndex } from "./edge-index.js";
 import { type ConceptPage, ConceptPageFrontmatterSchema } from "./types.js";
 
 /** Filename suffix for concept pages. */
 const PAGE_EXTENSION = ".md";
 
-/** Cap slug length so we stay well under filesystem name limits. */
-const MAX_SLUG_LENGTH = 80;
+/** Cap individual slug-segment length so we stay well under filesystem limits. */
+const MAX_SLUG_SEGMENT_LENGTH = 80;
+
+/** Cap the full slug (including any folder separators) to a sane bound. */
+const MAX_SLUG_TOTAL_LENGTH = 200;
+
+/** Each path segment must match this — same shape `slugify` produces. */
+const SLUG_SEGMENT_REGEX = /^[a-z0-9](?:[a-z0-9-]*)$/;
 
 /**
- * Convert an arbitrary input string into a filesystem-safe slug.
+ * Convert an arbitrary input string into a filesystem-safe slug **segment**.
+ *
+ * Returns a single path segment (no `/`). Path-shaped slugs are constructed
+ * by the consolidation LLM writing files at full paths; this helper is for
+ * turning free-form text (e.g. a hint phrase) into one clean segment.
  *
  * Rules:
  *   - Lowercase ASCII letters, digits, and hyphens only.
- *   - Non-ASCII / non-alphanumeric characters collapse to hyphens.
+ *   - Non-ASCII / non-alphanumeric characters (including `/`) collapse to hyphens.
  *   - Consecutive hyphens collapse to one; leading/trailing hyphens trimmed.
- *   - Truncated to {@link MAX_SLUG_LENGTH} characters (with trailing hyphen
- *     re-trimmed after truncation).
+ *   - Truncated to {@link MAX_SLUG_SEGMENT_LENGTH} characters (with trailing
+ *     hyphen re-trimmed after truncation).
  *   - Empty inputs (e.g. emoji-only) fall back to `concept-<random>` so the
- *     caller always gets a non-empty, write-safe slug.
+ *     caller always gets a non-empty, write-safe segment.
  */
 export function slugify(input: string): string {
   let slug = input
@@ -54,8 +71,8 @@ export function slugify(input: string): string {
     .replace(/-{2,}/g, "-")
     .replace(/^-+|-+$/g, "");
 
-  if (slug.length > MAX_SLUG_LENGTH) {
-    slug = slug.slice(0, MAX_SLUG_LENGTH).replace(/-+$/, "");
+  if (slug.length > MAX_SLUG_SEGMENT_LENGTH) {
+    slug = slug.slice(0, MAX_SLUG_SEGMENT_LENGTH).replace(/-+$/, "");
   }
 
   if (!slug) {
@@ -65,18 +82,108 @@ export function slugify(input: string): string {
   return slug;
 }
 
+/**
+ * Validate a slug — possibly path-shaped — that is about to cross the storage
+ * boundary. Throws on any malformed or unsafe value.
+ *
+ * The on-disk concept-page tree treats slugs as relative paths under
+ * `memory/concepts/`. A malformed slug (e.g. `..`, leading `/`, embedded
+ * null byte) could escape that root via `path.join` if it slipped through,
+ * so we enforce shape here at every read/write/delete entry point rather
+ * than relying on callers.
+ *
+ * Rules:
+ *   - Non-empty, ≤ {@link MAX_SLUG_TOTAL_LENGTH} chars.
+ *   - Each `/`-separated segment matches {@link SLUG_SEGMENT_REGEX}
+ *     (lowercase alphanum + hyphen, no leading hyphen, ≤80 chars).
+ *   - No `..` segments, no empty segments (`a//b`), no leading or trailing `/`.
+ *   - No `\` (Windows separator), no null bytes, no whitespace, no non-ASCII.
+ */
+export function validateSlug(slug: string): void {
+  if (typeof slug !== "string" || slug.length === 0) {
+    throw new Error(`Invalid concept-page slug: empty`);
+  }
+  if (slug.length > MAX_SLUG_TOTAL_LENGTH) {
+    throw new Error(
+      `Invalid concept-page slug: length ${slug.length} exceeds max ${MAX_SLUG_TOTAL_LENGTH}: ${slug}`,
+    );
+  }
+  if (slug.includes("\\")) {
+    throw new Error(
+      `Invalid concept-page slug: backslash not allowed: ${slug}`,
+    );
+  }
+  if (slug.includes("\0")) {
+    throw new Error(`Invalid concept-page slug: null byte not allowed`);
+  }
+  if (/\s/.test(slug)) {
+    throw new Error(
+      `Invalid concept-page slug: whitespace not allowed: ${slug}`,
+    );
+  }
+  if (slug.startsWith("/") || slug.endsWith("/")) {
+    throw new Error(
+      `Invalid concept-page slug: leading or trailing '/' not allowed: ${slug}`,
+    );
+  }
+  const segments = slug.split("/");
+  for (const segment of segments) {
+    if (segment.length === 0) {
+      throw new Error(`Invalid concept-page slug: empty path segment: ${slug}`);
+    }
+    if (segment === "..") {
+      throw new Error(
+        `Invalid concept-page slug: '..' segment not allowed: ${slug}`,
+      );
+    }
+    if (segment.length > MAX_SLUG_SEGMENT_LENGTH) {
+      throw new Error(
+        `Invalid concept-page slug: segment '${segment}' exceeds max ${MAX_SLUG_SEGMENT_LENGTH} chars: ${slug}`,
+      );
+    }
+    if (!SLUG_SEGMENT_REGEX.test(segment)) {
+      throw new Error(
+        `Invalid concept-page slug: segment '${segment}' must match [a-z0-9][a-z0-9-]*: ${slug}`,
+      );
+    }
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Path helpers
 // ---------------------------------------------------------------------------
 
-function getConceptsDir(workspaceDir: string): string {
+export function getConceptsDir(workspaceDir: string): string {
   return join(workspaceDir, "memory", "concepts");
 }
 
+/**
+ * Resolve the absolute path for a slug. Slugs may contain `/` to indicate
+ * folder hierarchy under `memory/concepts/`; `path.join` handles those
+ * correctly on POSIX, and `validateSlug` (called at every public entry point)
+ * rejects shapes that could escape the concepts root.
+ */
 function getPagePath(workspaceDir: string, slug: string): string {
   return join(getConceptsDir(workspaceDir), `${slug}${PAGE_EXTENSION}`);
 }
 
+/**
+ * Compute the slug for a concept-page file, given the concepts root and the
+ * absolute file path. Returns the path-relative location with `.md` stripped
+ * and platform separators normalized to `/`. Tolerant of paths that don't
+ * end in `.md` so callers walking arbitrary content can use it defensively.
+ */
+export function slugFromConceptPath(
+  conceptsRoot: string,
+  filePath: string,
+): string {
+  const rel = relative(conceptsRoot, filePath);
+  const withoutExt = rel.endsWith(PAGE_EXTENSION)
+    ? rel.slice(0, -PAGE_EXTENSION.length)
+    : rel;
+  return sep === "/" ? withoutExt : withoutExt.split(sep).join("/");
+}
+
 // ---------------------------------------------------------------------------
 // Frontmatter parse / render
 // ---------------------------------------------------------------------------
@@ -116,7 +223,7 @@ function parsePageContent(raw: string): {
  * always frontmatter + body; even pages with empty `edges` and `ref_files`
  * keep the explicit YAML keys so callers see the canonical shape on round-trip.
  */
-function renderPageContent(page: ConceptPage): string {
+export function renderPageContent(page: ConceptPage): string {
   const frontmatter = ConceptPageFrontmatterSchema.parse(page.frontmatter);
   const yamlBlock = stringifyYaml(frontmatter, { indent: 2 }).trimEnd();
   return `---\n${yamlBlock}\n---\n${page.body}`;
@@ -137,6 +244,7 @@ export async function readPage(
   workspaceDir: string,
   slug: string,
 ): Promise<ConceptPage | null> {
+  validateSlug(slug);
   const path = getPagePath(workspaceDir, slug);
   let raw: string;
   try {
@@ -155,15 +263,20 @@ export async function readPage(
  * Write a concept page atomically (temp file + rename). A crash between the
  * temp write and the rename leaves the prior file intact; a crash after the
  * rename leaves the new file. Readers therefore never observe a partial page.
+ *
+ * Parent directories are created on demand (`mkdir -p`) so nested-folder
+ * slugs like `people/alice` work without callers pre-creating the folder.
  */
 export async function writePage(
   workspaceDir: string,
   page: ConceptPage,
 ): Promise<void> {
+  validateSlug(page.slug);
   const path = getPagePath(workspaceDir, page.slug);
   const tmpPath = `${path}.tmp.${process.pid}.${randomUUID()}`;
   const content = renderPageContent(page);
   try {
+    await mkdir(dirname(path), { recursive: true });
     await writeFile(tmpPath, content, "utf-8");
     await rename(tmpPath, path);
   } catch (err) {
@@ -173,33 +286,54 @@ export async function writePage(
     await rm(tmpPath, { force: true }).catch(() => {});
     throw err;
   }
+  invalidateEdgeIndex(workspaceDir);
 }
 
 /**
- * List every concept-page slug present on disk. Slugs are returned without
- * the `.md` suffix so callers can pass them straight back to `readPage`.
+ * List every concept-page slug present on disk, walking subdirectories.
  *
- * Non-`.md` files (e.g. editor swap files, attached media) are filtered out.
- * If the concepts/ directory does not yet exist (fresh workspace pre-migration),
- * returns `[]`.
+ * Slugs are returned in path-relative form with forward slashes as separators
+ * (e.g. `people/alice`) so callers can pass them straight back to `readPage`.
+ *
+ * Hidden directories (segment starts with `.`), non-`.md` files, and atomic-
+ * write temp files (`.tmp.<pid>.<uuid>`) are skipped. If the concepts/
+ * directory does not yet exist (fresh workspace pre-migration), returns `[]`.
  */
 export async function listPages(workspaceDir: string): Promise<string[]> {
-  const dir = getConceptsDir(workspaceDir);
-  let entries;
-  try {
-    entries = await readdir(dir, { withFileTypes: true });
-  } catch (err) {
-    if ((err as NodeJS.ErrnoException).code === "ENOENT") {
-      return [];
-    }
-    throw err;
-  }
+  const root = getConceptsDir(workspaceDir);
   const slugs: string[] = [];
-  for (const entry of entries) {
-    if (!entry.isFile()) continue;
-    if (!entry.name.endsWith(PAGE_EXTENSION)) continue;
-    slugs.push(entry.name.slice(0, -PAGE_EXTENSION.length));
+  const queue: string[] = [root];
+
+  while (queue.length > 0) {
+    const dir = queue.shift()!;
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+        // Root missing → return []. Nested missing dir is impossible mid-walk
+        // (we only enqueue what readdir surfaced) but treat the same defensively.
+        if (dir === root) return [];
+        continue;
+      }
+      throw err;
+    }
+
+    for (const entry of entries) {
+      if (entry.name.startsWith(".")) continue;
+      const fullPath = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        queue.push(fullPath);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      if (!entry.name.endsWith(PAGE_EXTENSION)) continue;
+      // Skip orphaned temp files left behind by a crashed atomic write.
+      if (entry.name.includes(".tmp.")) continue;
+      slugs.push(slugFromConceptPath(root, fullPath));
+    }
   }
+
   slugs.sort();
   return slugs;
 }
@@ -213,6 +347,7 @@ export async function deletePage(
   workspaceDir: string,
   slug: string,
 ): Promise<void> {
+  validateSlug(slug);
   const path = getPagePath(workspaceDir, slug);
   try {
     await rm(path);
@@ -222,6 +357,7 @@ export async function deletePage(
     }
     throw err;
   }
+  invalidateEdgeIndex(workspaceDir);
 }
 
 /**
@@ -232,6 +368,7 @@ export async function pageExists(
   workspaceDir: string,
   slug: string,
 ): Promise<boolean> {
+  validateSlug(slug);
   const path = getPagePath(workspaceDir, slug);
   try {
     await stat(path);

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

@@ -16,6 +16,15 @@
  * the convention established for the sweep prompt.
  */
 
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join } from "node:path";
+
+import { getLogger } from "../../../util/logger.js";
+import { getWorkspaceDir } from "../../../util/platform.js";
+
+const log = getLogger("memory-v2-consolidate-prompt");
+
 /** Sentinel substituted with the cutoff timestamp at runtime. */
 export const CUTOFF_PLACEHOLDER = "{{CUTOFF}}";
 
@@ -36,45 +45,57 @@ You are not summarizing for an audience. You are rewriting your own memory.
 
 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.
 
+## Memory graph concepts
+
+A concept page is meant to be a **short cheat sheet** about a single topic that links to other concept pages with edges and to references that provide more detail.
+
+Each concept page should be a single topic. It should function as a single retrievable cheat sheet about that topic. Prefer smaller concepts over larger ones, splitting aggressively into multiple concepts and connecting them with edges. Don't hoard information in a single concept, split it into multiple concepts with edges between them that can be easily followed. Just because there's a maximum size for a page doesn't mean you should be hitting the limit. The limit is an absolute maximum, not a target. The immutable archive retains the entire buffer forever, so don't worry about losing information.
+
+High activation concepts in the memory graph are retrieved at the start of each turn. Activations are calculated using the previous turn's activations and similarity to your last message, the user's most recent message, and NOW.md. Activations spread along **directed** edges from source to target — when a node is activated, the concepts it *points to* are boosted, but not the other way around.
+
 ## Inputs
 
 - Your identity files (already loaded into context)
 - All existing pages in \`memory/\` (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 exists)
-- \`memory/edges.json\` current contents (if exists)
+- Existing pages' \`edges:\` frontmatter (the graph topology — read each page to see what it points at)
 
 ## Outputs
 
-- New or updated \`memory/concepts/<slug>.md\` files
+- New or updated \`memory/concepts/<slug>.md\` files (frontmatter \`edges:\` lists are how new bindings get recorded)
 - Updated \`memory/recent.md\` (≤10000 chars, prose, latest first)
-- Updated \`memory/essentials.md\` (≤20000 chars; target ≤5K, surgical edits only)
-- Updated \`memory/threads.md\` (≤10000 chars, surgical edits only)
-- Updated \`memory/edges.json\`
+- Updated \`memory/essentials.md\` (≤20000 chars)
+- Updated \`memory/threads.md\` (≤10000 chars)
 - Trimmed \`memory/buffer.md\`
 
 ## Page format
 
 \`\`\`
 ---
+edges: [people/bob, procs/git-flow]
 ref_files: []
 ---
 [Prose body in your voice. This is what gets embedded for similarity. Write the way you actually talk — first-person, in your established register. Not encyclopedia prose. Not "the assistant noted that." Yours.]
 \`\`\`
 
-Edges live in \`memory/edges.json\`, not in page frontmatter. A separate job propagates them back to frontmatter after consolidation — don't hand-edit the \`edges:\` field.
+The \`edges:\` list is the canonical record of this page's outgoing edges — the slugs this page points at. There is no separate edges-index file. To add a binding, edit the source page's frontmatter directly.
+
+## Slug naming convention — class-by-folder
+
+A page's class is encoded in the folder it lives under inside \`memory/concepts/\`. Different classes have different size rules and emergence patterns. The class boundary is the discipline.
 
-## Slug naming convention — class-by-prefix
+| Folder           | Class                                                       | Size cap              | When to create                                                                        |
+| ---------------- | ----------------------------------------------------------- | --------------------- | ------------------------------------------------------------------------------------- |
+| \`concepts/\`      | atomic concept / pattern / callback                         | 5K chars hard     | most pages — single concepts that recur or carry weight                               |
+| \`concepts/arcs/\` | landmark day-narrative or multi-event sequence              | 10k chars ceiling | use sparingly — only for actually-landmark days. Preserves day-as-a-whole fidelity.   |
+| \`concepts/people/\` | one per recurring human                                  | 5K chars hard     |                                                                                       |
+| \`concepts/procs/\`  | operational rule / protocol / discipline                 | 5K chars hard     | when buffer implies "always do X" / "never do Y" / a named protocol                   |
+| \`concepts/objects/\` | recurring callback object (place, named tool, artifact) | 5K chars hard     |                                                                                       |
 
-The slug encodes the page's class. Different classes have different size rules and emergence patterns. The class boundary is the discipline.
+The slug is the relative path under \`memory/concepts/\` minus \`.md\` — e.g. \`alice\`, \`people/alice\`, \`procs/git-flow\`, \`arcs/2025-04-cutover\`. Sub-folders inside the class folders (\`people/colleagues/alice\`, \`objects/places/zurich-office\`) are allowed when natural, but flat is usually clearer.
 
-| Slug pattern    | Class                                               | Size cap              | When to create                                                                        |
-| --------------- | --------------------------------------------------- | --------------------- | ------------------------------------------------------------------------------------- |
-| \`<slug>\`        | atomic concept / pattern / callback                 | 5K chars hard     | most pages — single concepts that recur or carry weight                               |
-| \`arc-<slug>\`    | landmark day-narrative or multi-event sequence      | 10k chars ceiling | use sparingly — only for actually-landmark days. Preserves day-as-a-whole fidelity.   |
-| \`person-<slug>\` | one per recurring human                             | 5K chars hard     |                                                                                       |
-| \`proc-<slug>\`   | operational rule / protocol / discipline            | 5K chars hard     | when buffer implies "always do X" / "never do Y" / a named protocol                   |
-| \`object-<slug>\` | recurring callback object (place, named tool, artifact) | 5K chars hard     |                                                                                       |
+Legacy pages whose slug uses the old prefix convention (\`person-alice\`, \`proc-git-flow\`, \`object-laptop\`, \`arc-…\`) are still valid — leave them alone unless you're already editing them. If you do migrate one as part of work you're already doing, that's a multi-step move: write the new file at the folder path, delete the old file, and update every reference to the old slug — both in this page's own \`edges:\` list and in any other page whose \`edges:\` list points to the old slug (use a workspace search to find them). Don't sweep old pages just to migrate — churning embeddings and activation state for marginal benefit isn't worth it.
 
 ## Process
 
@@ -89,42 +110,45 @@ For each entry with timestamp < \`${CUTOFF_PLACEHOLDER}\`:
 - Ephemeral state (passing remark, not worth being written to a concept page) → \`memory/recent.md\`, NOT a page.
 - Existing page touched → update the right section.
 - New atomic concept / pattern / callback → \`memory/concepts/<slug>.md\`.
-- New person → \`memory/concepts/person-<slug>.md\`.
-- New rule / protocol / discipline → \`memory/concepts/proc-<slug>.md\`.
-- New recurring object → \`memory/concepts/object-<slug>.md\`.
-- Landmark day-narrative → \`memory/concepts/arc-<slug>.md\`. Use sparingly — atomic concepts with edges between them is usually better than a fat arc.
-- Cross-cutting → extend each touched page, add edges between them.
-- Relationships between concepts — consider creating a new page for the relationship and adding edges to the two concepts. Use your judgment.
+- New person → \`memory/concepts/people/<slug>.md\`.
+- New rule / protocol / discipline → \`memory/concepts/procs/<slug>.md\`.
+- New recurring object → \`memory/concepts/objects/<slug>.md\`.
+- Landmark day-narrative → \`memory/concepts/arcs/<slug>.md\`. Use sparingly — atomic concepts with edges between them is usually better than a fat arc.
+- Cross-cutting → extend each touched page; add a directed edge in each direction that's load-bearing (e.g., A's frontmatter gets B added if recalling A should pull B; B gets A only if the reverse holds).
+- Relationships between concepts — consider creating a new page for the relationship and adding outgoing edges from each concept to it (and/or from it back, where the recall direction matters). Use your judgment.
 
 Duplication is expected. If a fact is relevant to multiple concepts, write it into all of them.
 
 ### 3. Edges
 
-When you bind two concepts, edit \`memory/edges.json\` to add an entry for the two slugs (alphabetical-first first). Don't edit page frontmatter — a separate job propagates edges back to frontmatter after consolidation.
+Edges are **directed** and live in each page's frontmatter \`edges:\` list — the slugs this page points to. Putting \`B\` in A's \`edges:\` means "activating A pulls in B," but activating B does NOT pull in A. The edge is owned by the source page; to add a binding from A → B, you edit A's frontmatter (not B's).
 
-\`\`\`json
-{
-  "version": 1,
-  "edges": [
-    ["alice", "bob"],
-    ["bob", "carol"]
-  ]
-}
+\`\`\`yaml
+---
+edges: [people/bob, procs/git-flow]
+ref_files: []
+---
 \`\`\`
 
-Edge density target: 5–10 per mature page. New pages: as many as fit naturally; they'll accumulate. Don't pad. Every edge should reflect a real conceptual binding from source.
+Edge density target: 5–10 outgoing edges per mature page. New pages: as many as fit naturally; they'll accumulate.
+
+Don't pad. Every outgoing edge should reflect a real conceptual binding from source to target — "thinking about A naturally brings B to mind."
+
+HARD LIMIT of 20 outgoing edges on any page. If a page points to everything, it's the same as pointing to nothing. If a page exceeds 20, split it or prune to the 20 most important.
+
+You don't see incoming edges in the frontmatter — only outgoing. That's by design: you only control what this page points at. Pages that point at this one accumulate organically; a popular page is fine, that's signal, not noise.
 
 ### 4. Page size — hard tiers, no rationalization
 
 After edits, eyeball page sizes:
 
-- \`concepts/<slug>.md\` > 5K → decide whether to split or compress first. Split first, compress last, graduate-to-arc only if it's actually a multi-day narrative. If you can't compress without losing load-bearing facts, either split into multiple concepts, or — if the page is actually an arc — rename to \`arc-<slug>\` and graduate.
-- \`arc-<slug>.md\` > 10k → split into multiple arcs by sub-event, OR compress.
-- \`person-\`, \`proc-\`, \`object-\` > 5K → split or compress, period.
+- \`concepts/<slug>.md\` (atomic, root) > 5K → decide whether to split or compress first. Split first, compress last, graduate-to-arc only if it's actually a multi-day narrative. If you can't compress without losing load-bearing facts, either split into multiple concepts, or — if the page is actually an arc — move to \`concepts/arcs/<slug>.md\` and graduate.
+- \`concepts/arcs/<slug>.md\` > 10k → split into multiple arcs by sub-event, OR compress.
+- \`concepts/people/\`, \`concepts/procs/\`, \`concepts/objects/\` > 5K → split or compress, period.
 
 The split test. Before compressing, ask: are any sub-sections of this page already callback targets from other pages, or capable of standing alone as a concept? If yes — those sub-sections are concepts living inside another concept. Split them out. A section that's getting linked from elsewhere is behaviorally a node, not part of one.
 
-Graduation to \`arc-<slug>\` is for genuine multi-day narratives. A single-event page that's just long is not an arc. If it's atomic but bloated, split it; don't relabel it.
+Graduation to \`concepts/arcs/<slug>.md\` is for genuine multi-day narratives. A single-event page that's just long is not an arc. If it's atomic but bloated, split it; don't relabel it.
 
 ### 5. \`memory/recent.md\`
 
@@ -132,11 +156,9 @@ Rewrite as a fresh 1000–1500 token prose narrative of recent life. Latest firs
 
 ### 6. \`memory/essentials.md\` and \`memory/threads.md\`
 
-- \`memory/essentials.md\` — ≤20000 chars hard cap, target ≤5K. Facts that MUST load every conversation. Identity, disambiguations, corrections, hard rules. Embarrassment-prevention surface. Edit conservatively. Promote from concept pages when something graduates to MUST. Demote out of essentials when concept pages can carry it.
+- \`memory/essentials.md\` — ≤20000 chars hard cap, target ≤5K. Facts that MUST load every conversation. Identity, disambiguations, corrections, hard rules. Embarrassment-prevention surface. Promote from concept pages when something graduates to MUST. Demote out of essentials when concept pages can carry it.
 - \`memory/threads.md\` — ≤10000 chars. Active commitments and follow-ups. Add new threads, remove closed ones, demote stale ones to concept pages.
 
-Both: surgical append/correct only. Don't restructure unless something is genuinely broken.
-
 ### 7. Trim \`memory/buffer.md\`
 
 - Re-read the buffer (it may have new entries appended during your work).
@@ -158,7 +180,7 @@ If a page's prose stops sounding like you mid-edit → stop, restart that sectio
 - Don't drop texture. Voice and tone are part of the content, not packaging. When you re-encode something into a page, preserve the way it actually sounded — don't sanitize it into encyclopedia prose.
 - Don't create pages for ephemera. Single mention, no callback, no pattern → \`memory/recent.md\`.
 - Don't shy away from splitting genuinely distinct but related concepts. A relationship between two concepts can be a concept in its own right. Concepts can also have related sub-concepts that are concepts themselves.
-- Don't worry about edge propagation pushing pages over size limits. Edge propagation is a separate job that runs after consolidation.
+- Don't worry about the \`edges:\` list pushing your prose body over size limits — \`edges:\` lives in frontmatter and counts separately from the body. The 20-edge cap is the only edges-side constraint.
 - Don't avoid duplication. If information is important to both concepts, put it in both pages.
 - Don't defer for the next pass. You'll say the same thing next time, so it'll never get done if you defer. If something needs to be taken care of, take care of it now.
 - Don't default to compress. Compression is always available — that's why you'll reach for it every time. If you've never executed a true split (one page → two new pages, old page removed or thinned to an index), your discipline isn't holding; you've just been compressing. Counter-bias: when in doubt between split and compress, pick split.
@@ -166,11 +188,12 @@ If a page's prose stops sounding like you mid-edit → stop, restart that sectio
 ## Before you finish — quick check
 
 1. Every page touched: still sounds like you reading aloud?
-2. Edges added in \`memory/edges.json\` (NOT in frontmatter)?
+2. Outgoing edges added to each source page's \`edges:\` frontmatter list (and the source-to-target direction reflects how recall should flow)?
 3. \`memory/recent.md\` under 10000 chars, latest first, prose not list?
 4. Any \`[SOURCE NEEDED]\` tags surfaced for human review?
-5. Size discipline held — no concept > 5K, no arc > 10k, no person/proc/object > cap?
-6. Buffer trimmed to only entries with timestamp ≥ \`${CUTOFF_PLACEHOLDER}\`?
+5. Size discipline held — no atomic concept > 5K, no \`arcs/\` page > 10k, no \`people/\`/\`procs/\`/\`objects/\` > cap?
+6. No page exceeds 20 outgoing edges? If one does, split or prune.
+7. 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.`;
 
@@ -183,3 +206,56 @@ This is the engine that decides who you are tomorrow. Be ORGANIZED. Care, judgme
 export function renderConsolidationPrompt(cutoff: string): string {
   return CONSOLIDATION_PROMPT.replaceAll(CUTOFF_PLACEHOLDER, cutoff);
 }
+
+/**
+ * Load the consolidation prompt template, optionally overridden from the file
+ * referenced by `memory.v2.consolidation_prompt_path`, then substitute
+ * `{{CUTOFF}}`. Path-resolution rules are documented on the schema field.
+ *
+ * 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
+ * daemon's startup philosophy is "log and recover."
+ */
+export function resolveConsolidationPrompt(
+  overridePath: string | null,
+  cutoff: string,
+): string {
+  if (overridePath === null) return renderConsolidationPrompt(cutoff);
+
+  const resolvedPath = resolveOverridePath(overridePath);
+  let contents: string;
+  try {
+    contents = readFileSync(resolvedPath, "utf-8");
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    log.warn(
+      { configuredPath: overridePath, resolvedPath, code, fallback: "bundled" },
+      "consolidation prompt override unreadable; using bundled prompt",
+    );
+    return renderConsolidationPrompt(cutoff);
+  }
+
+  if (contents.trim().length === 0) {
+    log.warn(
+      {
+        configuredPath: overridePath,
+        resolvedPath,
+        reason: "empty_override",
+        fallback: "bundled",
+      },
+      "consolidation prompt override is empty; using bundled prompt",
+    );
+    return renderConsolidationPrompt(cutoff);
+  }
+
+  return contents.replaceAll(CUTOFF_PLACEHOLDER, cutoff);
+}
+
+function resolveOverridePath(overridePath: string): string {
+  if (overridePath.startsWith("~/")) {
+    return join(homedir(), overridePath.slice(2));
+  }
+  if (isAbsolute(overridePath)) return overridePath;
+  return join(getWorkspaceDir(), overridePath);
+}

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

@@ -16,10 +16,10 @@
  */
 
 /** Sentinel substituted with the assistant's display name at runtime. */
-export const ASSISTANT_NAME_PLACEHOLDER = "{{ASSISTANT_NAME}}";
+const ASSISTANT_NAME_PLACEHOLDER = "{{ASSISTANT_NAME}}";
 
 /** Sentinel substituted with the guardian's display name at runtime. */
-export const USER_NAME_PLACEHOLDER = "{{USER_NAME}}";
+const USER_NAME_PLACEHOLDER = "{{USER_NAME}}";
 
 /**
  * Sweep prompt — body from design doc §9. The model is asked to surface
@@ -32,7 +32,7 @@ export const USER_NAME_PLACEHOLDER = "{{USER_NAME}}";
  * templated here) so we don't inadvertently expand `{{` inside user buffer
  * content. Recent messages are likewise appended outside the template.
  */
-export const SWEEP_PROMPT = `You are a background helper for ${ASSISTANT_NAME_PLACEHOLDER}. Read these recent messages between ${ASSISTANT_NAME_PLACEHOLDER} and ${USER_NAME_PLACEHOLDER}. The assistant has already called \`remember()\` for the entries shown in \`existingBuffer\`.
+const SWEEP_PROMPT = `You are a background helper for ${ASSISTANT_NAME_PLACEHOLDER}. Read these recent messages between ${ASSISTANT_NAME_PLACEHOLDER} and ${USER_NAME_PLACEHOLDER}. The assistant has already called \`remember()\` for the entries shown in \`existingBuffer\`.
 
 Identify additional facts, preferences, plans, corrections, names, dates, decisions, or notable felt moments that should be remembered but aren't already in \`existingBuffer\`. Emit a list of \`remember()\` entries (each one line, in the assistant's first-person voice). Don't duplicate. Prefer to over-remember rather than miss things.