@yeaft/webchat-agent 0.1.467 → 0.1.469

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeaft/webchat-agent",
-  "version": "0.1.467",
+  "version": "0.1.469",
   "description": "Remote agent for Yeaft WebChat — connects worker machines to the central server",
   "main": "index.js",
   "type": "module",

package/unify/engine.js

@@ -22,6 +22,7 @@ import { buildSystemPrompt } from './prompts.js';
 import { LLMContextError } from './llm/adapter.js';
 import { recall } from './memory/recall.js';
 import { shouldConsolidate, consolidate } from './memory/consolidate.js';
+import { buildMemoryInjection } from './memory/layout.js';
 import { runStopHooks } from './stop-hooks.js';
 
 /** Maximum number of turns before the engine stops to prevent infinite loops. */
@@ -167,9 +168,10 @@ export class Engine {
    * @param {{ profile?: string, entries?: object[] }} [memory]
    * @param {string} [compactSummary]
    * @param {string} [prompt] — user prompt (for skill relevance matching)
+   * @param {string} [memoryInjection] — task-287: prebuilt memory block (index + prefs + project)
    * @returns {string}
    */
-  #buildSystemPrompt(mode, memory, compactSummary, prompt) {
+  #buildSystemPrompt(mode, memory, compactSummary, prompt, memoryInjection) {
     // Get relevant skill content if SkillManager is wired
     let skillContent = '';
     if (this.#skillManager && prompt) {
@@ -186,6 +188,7 @@ export class Engine {
       mode,
       toolNames,
       memory,
+      memoryInjection,
       compactSummary,
       skillContent,
     });
@@ -333,14 +336,30 @@ export class Engine {
       return;
     }
 
-    // ─── Pre-query: Recall + Compact Summary ────────────────
-    const memory = await this.#recallMemory(prompt);
-    if (memory && memory.entries.length > 0) {
-      yield { type: 'recall', entryCount: memory.entries.length, cached: false };
+    // ─── Pre-query: Memory Injection (task-287) + Compact Summary ──
+    // New layout: always inject Memory Index + user-preferences + project
+    // header excerpt. No per-turn fuzzy recall — LLM calls memory_search /
+    // memory_query on demand.
+    let memoryInjection = '';
+    if (this.#yeaftDir) {
+      try {
+        const entryCount = this.#memoryStore?.stats?.().entryCount ?? 0;
+        memoryInjection = buildMemoryInjection({
+          yeaftDir: this.#yeaftDir,
+          cwd: process.cwd(),
+          entryCount,
+          language: this.#config.language || 'en',
+        });
+      } catch {
+        // Injection failure is non-critical — fall back to empty.
+      }
+    }
+    if (memoryInjection) {
+      yield { type: 'recall', entryCount: 0, cached: false };
     }
 
     const compactSummary = this.#getCompactSummary();
-    const systemPrompt = this.#buildSystemPrompt(mode, memory, compactSummary, prompt);
+    const systemPrompt = this.#buildSystemPrompt(mode, undefined, compactSummary, prompt, memoryInjection);
 
     // Build conversation: existing messages + new user message
     const conversationMessages = [

package/unify/memory/dream.js

@@ -16,6 +16,13 @@ import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, unlink
 import { join } from 'path';
 import { scanEntries, findStaleEntries, findDuplicateGroups, summarizeScan } from './scan.js';
 import { MAX_ENTRIES } from './store.js';
+import {
+  ensureLayout,
+  renderIndex,
+  readMemoryFile,
+  writeMemoryFile,
+  memoryDir,
+} from './layout.js';
 import {
   buildOrientPrompt,
   buildGatherPrompt,
@@ -325,6 +332,31 @@ export async function dream({ yeaftDir, memoryStore, conversationStore, adapter,
     // Rebuild scopes after all changes
     memoryStore.rebuildScopes();
 
+    // ── Phase 6: Classify (task-287) ─────────────────────
+    // Maintain the new-layout classification files:
+    //   - index.md                    (auto-regenerate from disk state)
+    //   - user-preferences.md         (merge gather/promote preferences)
+    //   - by-project/<slug>.md        (narrative summary per project)
+    //   - by-topic/<slug>.md          (narrative summary per topic)
+    //   - timeline/<YYYY-MM>.md       (monthly narrative digest)
+    onPhase?.('classify', 'starting');
+    try {
+      ensureLayout(yeaftDir);
+      const classifyResult = await runClassifyPhase({
+        yeaftDir,
+        memoryStore,
+        adapter,
+        config,
+        gatherResult,
+        promoteResult,
+      });
+      result.phases.classify = classifyResult;
+      result.classified = classifyResult;
+      onPhase?.('classify', classifyResult);
+    } catch (err) {
+      result.errors.push(`classify: ${err.message}`);
+    }
+
     // Update dream state
     const state = readDreamState(yeaftDir);
     state.lastDreamAt = new Date().toISOString();
@@ -466,3 +498,279 @@ function writeDreamLog(yeaftDir, result) {
  * @property {boolean} profileUpdated
  * @property {string[]} errors
  */
+
+// ─── Phase 6: Classify (task-287) ───────────────────────────
+
+/**
+ * Regenerate index.md, merge user-preferences.md, and generate narrative
+ * classification files (by-project, by-topic, timeline).
+ *
+ * Strategy:
+ *   1. Always regenerate index.md from current on-disk layout (cheap, no LLM).
+ *   2. Extract preferences from gather/promote results and merge (deduped)
+ *      into user-preferences.md. No LLM call — trust structured output.
+ *   3. Group entries by scope (project slug), topic tag, and YYYY-MM of
+ *      updated_at. For each group with ≥3 entries and no up-to-date file,
+ *      call the main model once to produce a narrative summary. Caps:
+ *      MAX_CLASSIFY_LLM_CALLS = 3 per dream.
+ *
+ * @param {{
+ *   yeaftDir: string,
+ *   memoryStore: import('./store.js').MemoryStore,
+ *   adapter: object,
+ *   config: object,
+ *   gatherResult?: object,
+ *   promoteResult?: object,
+ * }} params
+ * @returns {Promise<{ indexBytes: number, preferencesMerged: number, narrativeFiles: string[] }>}
+ */
+const MAX_CLASSIFY_LLM_CALLS = 3;
+
+async function runClassifyPhase({ yeaftDir, memoryStore, adapter, config, gatherResult, promoteResult }) {
+  const summary = { indexBytes: 0, preferencesMerged: 0, narrativeFiles: [] };
+
+  // 1. Regenerate index.md
+  const entryCount = memoryStore.listEntries().length;
+  const indexText = renderIndex(yeaftDir, entryCount);
+  writeMemoryFile(yeaftDir, 'index.md', indexText);
+  summary.indexBytes = indexText.length;
+
+  // 2. Merge preferences into user-preferences.md (deduped, no LLM call)
+  const newPreferences = extractPreferences(gatherResult, promoteResult);
+  if (newPreferences.length > 0) {
+    const merged = mergePreferences(readMemoryFile(yeaftDir, 'user-preferences.md'), newPreferences);
+    if (merged.changed) {
+      writeMemoryFile(yeaftDir, 'user-preferences.md', merged.text);
+      summary.preferencesMerged = merged.addedCount;
+    }
+  }
+
+  // 3. Group entries for narrative generation
+  const entries = memoryStore.listEntries();
+  const byProject = groupByProject(entries);
+  const byTopic = groupByTopic(entries);
+  const byMonth = groupByMonth(entries);
+
+  let llmCallsLeft = MAX_CLASSIFY_LLM_CALLS;
+
+  for (const [slug, group] of Object.entries(byProject)) {
+    if (llmCallsLeft <= 0) break;
+    if (group.length < 3) continue;
+    const relPath = `by-project/${slug}.md`;
+    if (isFresh(yeaftDir, relPath, group)) continue;
+    const narrative = await generateNarrative({ adapter, config, category: 'project', label: slug, entries: group });
+    if (narrative) {
+      writeMemoryFile(yeaftDir, relPath, narrative);
+      summary.narrativeFiles.push(relPath);
+      llmCallsLeft--;
+    }
+  }
+
+  for (const [tag, group] of Object.entries(byTopic)) {
+    if (llmCallsLeft <= 0) break;
+    if (group.length < 3) continue;
+    const relPath = `by-topic/${tag}.md`;
+    if (isFresh(yeaftDir, relPath, group)) continue;
+    const narrative = await generateNarrative({ adapter, config, category: 'topic', label: tag, entries: group });
+    if (narrative) {
+      writeMemoryFile(yeaftDir, relPath, narrative);
+      summary.narrativeFiles.push(relPath);
+      llmCallsLeft--;
+    }
+  }
+
+  for (const [ym, group] of Object.entries(byMonth)) {
+    if (llmCallsLeft <= 0) break;
+    if (group.length < 3) continue;
+    const relPath = `timeline/${ym}.md`;
+    if (isFresh(yeaftDir, relPath, group)) continue;
+    const narrative = await generateNarrative({ adapter, config, category: 'timeline', label: ym, entries: group });
+    if (narrative) {
+      writeMemoryFile(yeaftDir, relPath, narrative);
+      summary.narrativeFiles.push(relPath);
+      llmCallsLeft--;
+    }
+  }
+
+  // Regenerate index once more so new narrative files appear in it
+  const finalIndex = renderIndex(yeaftDir, entryCount);
+  writeMemoryFile(yeaftDir, 'index.md', finalIndex);
+  summary.indexBytes = finalIndex.length;
+
+  return summary;
+}
+
+/**
+ * Extract preference-like strings from gather/promote results.
+ * @returns {string[]}
+ */
+function extractPreferences(gatherResult, promoteResult) {
+  const out = [];
+  const pushFrom = (arr) => {
+    if (!Array.isArray(arr)) return;
+    for (const e of arr) {
+      if (!e) continue;
+      if (e.kind === 'preference' && typeof e.content === 'string' && e.content.trim()) {
+        out.push(e.content.trim());
+      }
+    }
+  };
+  pushFrom(gatherResult?.newEntries);
+  pushFrom(promoteResult?.promotedEntries);
+  // profileUpdates section `preferences`, if present
+  const prefUpdates = promoteResult?.profileUpdates?.preferences;
+  if (Array.isArray(prefUpdates)) {
+    for (const line of prefUpdates) {
+      if (typeof line === 'string' && line.trim()) out.push(line.trim());
+    }
+  }
+  return out;
+}
+
+/**
+ * Merge new preference lines into the existing user-preferences.md content.
+ * Dedupes on normalized text (lowercase + collapsed whitespace).
+ * @returns {{ text: string, changed: boolean, addedCount: number }}
+ */
+function mergePreferences(existing, newLines) {
+  const header = '# User Preferences\n\n';
+  const body = existing.trim().startsWith('# ')
+    ? existing.replace(/^# [^\n]*\n+/, '')
+    : existing;
+
+  const existingLines = body.split('\n').map(l => l.trim()).filter(l => l.startsWith('- '));
+  const norm = (s) => s.replace(/^[-*]\s*/, '').toLowerCase().replace(/\s+/g, ' ').trim();
+  const seen = new Set(existingLines.map(norm));
+
+  let addedCount = 0;
+  const added = [];
+  for (const line of newLines) {
+    const key = norm(line);
+    if (!key || seen.has(key)) continue;
+    seen.add(key);
+    added.push(`- ${line.replace(/^[-*]\s*/, '')}`);
+    addedCount++;
+  }
+
+  if (addedCount === 0) return { text: existing, changed: false, addedCount: 0 };
+
+  const allLines = [...existingLines, ...added];
+  const text = header + allLines.join('\n') + '\n';
+  return { text, changed: true, addedCount };
+}
+
+/**
+ * Group entries by project scope (first segment, or last if starts with 'work/').
+ */
+function groupByProject(entries) {
+  const out = {};
+  for (const e of entries) {
+    const scope = e.scope || '';
+    if (!scope || scope === 'global') continue;
+    const parts = scope.split('/').filter(Boolean);
+    const slug = parts[parts.length - 1];
+    if (!slug) continue;
+    const safe = slug.toLowerCase().replace(/[^a-z0-9._-]/g, '-');
+    if (!out[safe]) out[safe] = [];
+    out[safe].push(e);
+  }
+  return out;
+}
+
+function groupByTopic(entries) {
+  const out = {};
+  for (const e of entries) {
+    if (!Array.isArray(e.tags)) continue;
+    for (const t of e.tags) {
+      if (typeof t !== 'string' || !t.trim()) continue;
+      const safe = t.toLowerCase().replace(/[^a-z0-9._-]/g, '-');
+      if (!out[safe]) out[safe] = [];
+      out[safe].push(e);
+    }
+  }
+  return out;
+}
+
+function groupByMonth(entries) {
+  const out = {};
+  for (const e of entries) {
+    const ts = e.updated_at || e.created_at;
+    if (!ts) continue;
+    const d = new Date(ts);
+    if (Number.isNaN(d.getTime())) continue;
+    const ym = `${d.getUTCFullYear()}-${String(d.getUTCMonth() + 1).padStart(2, '0')}`;
+    if (!out[ym]) out[ym] = [];
+    out[ym].push(e);
+  }
+  return out;
+}
+
+/**
+ * Returns true if the existing classification file is newer than all entries
+ * in the group (within 1 hour tolerance). Avoids regenerating recently-written files.
+ */
+function isFresh(yeaftDir, relPath, group) {
+  const fp = join(memoryDir(yeaftDir), relPath);
+  if (!existsSync(fp)) return false;
+  try {
+    const stat = readFileSync(fp); // read to check existence, statless
+    // Use latest entry updated_at as the "need" mark
+    const latest = group.reduce((max, e) => {
+      const t = new Date(e.updated_at || e.created_at || 0).getTime();
+      return t > max ? t : max;
+    }, 0);
+    // Compare to file mtime via readdir; fallback to always-stale if unavailable
+    // Simpler: read first line of file and see if "updated: <ts>" is after latest
+    const firstLine = stat.toString('utf8').split('\n').slice(0, 5).join('\n');
+    const m = firstLine.match(/updated:\s*(\S+)/);
+    if (!m) return false;
+    const fileTime = new Date(m[1]).getTime();
+    return fileTime >= latest;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Call the main model to produce a narrative summary of a group of entries.
+ * @returns {Promise<string|null>}
+ */
+async function generateNarrative({ adapter, config, category, label, entries }) {
+  const entryLines = entries.slice(0, 40).map(e => {
+    const tags = (e.tags && e.tags.length) ? ` [${e.tags.join(', ')}]` : '';
+    return `- (${e.kind}) ${e.name}${tags}: ${String(e.content || '').slice(0, 300)}`;
+  }).join('\n');
+
+  const system = `You are a memory classifier for an AI assistant. Write a concise narrative summary (Markdown, 200-600 words) of the given memory entries grouped by ${category}. Focus on patterns, user preferences, decisions, and lessons — not on listing each entry.`;
+
+  const prompt = `Category: ${category}
+Label: ${label}
+Entry count: ${entries.length}
+
+Entries:
+${entryLines}
+
+Write the narrative as Markdown with:
+- A top heading (e.g. "# ${label}")
+- A metadata line: \`updated: ${new Date().toISOString()}\`
+- Then the narrative prose with short sub-sections as useful.`;
+
+  try {
+    const result = await adapter.call({
+      model: config.model,
+      system,
+      messages: [{ role: 'user', content: prompt }],
+      maxTokens: 2048,
+    });
+    const text = (result?.text || '').trim();
+    if (!text) return null;
+    // Ensure the `updated:` marker is present so isFresh() can parse it
+    if (!/updated:/.test(text.split('\n').slice(0, 5).join('\n'))) {
+      return `# ${label}\n\nupdated: ${new Date().toISOString()}\n\n${text}\n`;
+    }
+    return text.endsWith('\n') ? text : text + '\n';
+  } catch {
+    return null;
+  }
+}
+

package/unify/memory/layout.js

@@ -0,0 +1,358 @@
+/**
+ * layout.js — New-layout memory file helpers (tool-on-demand model)
+ *
+ * Directory layout:
+ *   ~/.yeaft/memory/
+ *     index.md                 — classification catalog (always injected into system prompt)
+ *     user-preferences.md      — merged user preferences (default-injected)
+ *     entries/*.md             — atomic entries (existing layout, read by memory_query)
+ *     by-project/<slug>.md     — per-project narrative summaries
+ *     by-topic/<slug>.md       — per-topic narrative summaries
+ *     timeline/<YYYY-MM>.md    — monthly narrative digests
+ *
+ * Design:
+ *   - index.md is a single human-readable file listing all classification files
+ *     with a one-line summary and entry count per section.
+ *   - Aggregate files (by-project / by-topic / timeline) are narrative prose,
+ *     not raw entry concat — produced by Dream.
+ *   - user-preferences.md is a deduped accumulation of preferences extracted
+ *     from conversations.
+ *   - Project header match: basename(cwd) is matched against by-project/<slug>.md
+ *     filenames (case-insensitive substring match either direction).
+ *
+ * This module lives alongside store.js; it does NOT replace MemoryStore.
+ * Old MEMORY.md / scopes.md continue to exist for backward compatibility
+ * but are no longer maintained by Dream after this refactor.
+ */
+
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync, statSync } from 'fs';
+import { basename, join } from 'path';
+import { isPermissionError } from '../init.js';
+
+// ─── Constants ──────────────────────────────────────────────
+
+/** Classification category dirnames. */
+export const CATEGORY_DIRS = ['by-project', 'by-topic', 'timeline'];
+
+/** Classification single-file names living directly under memory/. */
+export const SINGLE_FILES = ['index.md', 'user-preferences.md'];
+
+/** Approximate character budget for prompt injection (~1.5k tokens). */
+export const PROMPT_INJECTION_CHAR_BUDGET = 6000;
+
+/** Character budget for project header excerpt (~300 tokens). */
+export const PROJECT_HEADER_CHAR_BUDGET = 1200;
+
+// ─── Path helpers ───────────────────────────────────────────
+
+/**
+ * @param {string} yeaftDir — e.g. ~/.yeaft
+ * @returns {string} — absolute path to memory root
+ */
+export function memoryDir(yeaftDir) {
+  return join(yeaftDir, 'memory');
+}
+
+/**
+ * Ensure the new-layout directory skeleton exists (idempotent).
+ * @param {string} yeaftDir
+ */
+export function ensureLayout(yeaftDir) {
+  const root = memoryDir(yeaftDir);
+  const dirs = [root, ...CATEGORY_DIRS.map(d => join(root, d)), join(root, 'entries')];
+  for (const d of dirs) {
+    try {
+      if (!existsSync(d)) mkdirSync(d, { recursive: true, mode: 0o755 });
+    } catch (err) {
+      if (!isPermissionError(err)) throw err;
+    }
+  }
+}
+
+// ─── File I/O ───────────────────────────────────────────────
+
+/**
+ * Read a file under memory/ by relative path. Returns '' if missing.
+ * @param {string} yeaftDir
+ * @param {string} relPath — e.g. 'index.md', 'by-project/foo.md'
+ * @returns {string}
+ */
+export function readMemoryFile(yeaftDir, relPath) {
+  const fp = join(memoryDir(yeaftDir), relPath);
+  if (!existsSync(fp)) return '';
+  try {
+    return readFileSync(fp, 'utf8');
+  } catch (err) {
+    if (isPermissionError(err)) return '';
+    throw err;
+  }
+}
+
+/**
+ * Write a file under memory/ by relative path. Creates parent dir if needed.
+ * @param {string} yeaftDir
+ * @param {string} relPath
+ * @param {string} content
+ */
+export function writeMemoryFile(yeaftDir, relPath, content) {
+  ensureLayout(yeaftDir);
+  const fp = join(memoryDir(yeaftDir), relPath);
+  try {
+    writeFileSync(fp, content, { encoding: 'utf8', mode: 0o644 });
+  } catch (err) {
+    if (!isPermissionError(err)) throw err;
+  }
+}
+
+/**
+ * List all classification files (relative paths) that currently exist.
+ * Includes single files (index.md, user-preferences.md) and per-category files.
+ *
+ * @param {string} yeaftDir
+ * @returns {{ path: string, size: number }[]}
+ */
+export function listClassificationFiles(yeaftDir) {
+  const root = memoryDir(yeaftDir);
+  const out = [];
+
+  for (const f of SINGLE_FILES) {
+    const fp = join(root, f);
+    if (existsSync(fp)) {
+      try {
+        out.push({ path: f, size: statSync(fp).size });
+      } catch { /* ignore */ }
+    }
+  }
+
+  for (const dir of CATEGORY_DIRS) {
+    const dp = join(root, dir);
+    if (!existsSync(dp)) continue;
+    try {
+      for (const f of readdirSync(dp)) {
+        if (!f.endsWith('.md')) continue;
+        const fp = join(dp, f);
+        try {
+          out.push({ path: `${dir}/${f}`, size: statSync(fp).size });
+        } catch { /* ignore */ }
+      }
+    } catch { /* ignore */ }
+  }
+
+  return out;
+}
+
+// ─── Project header matching ────────────────────────────────
+
+/**
+ * Given a cwd, find the best-matching by-project/<slug>.md filename.
+ * Rule: case-insensitive substring match between basename(cwd) and slug
+ * (either direction). Returns the first match by sort order, or null.
+ *
+ * @param {string} yeaftDir
+ * @param {string} cwd
+ * @returns {string|null} — relative path like 'by-project/claude-web-chat.md', or null
+ */
+export function findProjectFile(yeaftDir, cwd) {
+  if (!cwd) return null;
+  const base = basename(cwd).toLowerCase();
+  if (!base) return null;
+
+  const dir = join(memoryDir(yeaftDir), 'by-project');
+  if (!existsSync(dir)) return null;
+
+  let files;
+  try {
+    files = readdirSync(dir).filter(f => f.endsWith('.md')).sort();
+  } catch {
+    return null;
+  }
+
+  for (const f of files) {
+    const slug = f.slice(0, -3).toLowerCase();
+    if (slug === base) return `by-project/${f}`;
+  }
+  for (const f of files) {
+    const slug = f.slice(0, -3).toLowerCase();
+    if (slug.includes(base) || base.includes(slug)) return `by-project/${f}`;
+  }
+
+  return null;
+}
+
+/**
+ * Return the leading excerpt of a file capped at charBudget.
+ * Trims to the last complete line boundary to avoid mid-line cutoff.
+ *
+ * @param {string} text
+ * @param {number} charBudget
+ * @returns {string}
+ */
+export function excerpt(text, charBudget) {
+  if (!text) return '';
+  if (text.length <= charBudget) return text;
+  const cut = text.slice(0, charBudget);
+  const lastNl = cut.lastIndexOf('\n');
+  return lastNl > charBudget * 0.6 ? cut.slice(0, lastNl) : cut;
+}
+
+// ─── Index rendering ────────────────────────────────────────
+
+/**
+ * Render an auto-generated index.md from the current on-disk layout.
+ *
+ * Format:
+ *   # Memory Index
+ *
+ *   ## Single files
+ *   - user-preferences.md (NNN bytes) — user-written/Dream-merged preferences
+ *
+ *   ## by-project
+ *   - by-project/foo.md (NNN bytes)
+ *   - by-project/bar.md (NNN bytes)
+ *
+ *   ## by-topic ...
+ *   ## timeline ...
+ *   ## entries
+ *   - N atomic entries (use memory_query to search)
+ *
+ * One-line summaries are pulled from the first non-empty, non-heading line
+ * of each file.
+ *
+ * @param {string} yeaftDir
+ * @param {number} entryCount — number of atomic entries (from MemoryStore)
+ * @returns {string}
+ */
+export function renderIndex(yeaftDir, entryCount) {
+  const root = memoryDir(yeaftDir);
+  const lines = ['# Memory Index', ''];
+
+  // Single files section
+  const singleLines = [];
+  for (const f of SINGLE_FILES) {
+    if (f === 'index.md') continue;
+    const fp = join(root, f);
+    if (!existsSync(fp)) continue;
+    const summary = firstSummary(fp);
+    const size = safeSize(fp);
+    singleLines.push(`- ${f} (${size} bytes)${summary ? ` — ${summary}` : ''}`);
+  }
+  if (singleLines.length) {
+    lines.push('## Single files', '', ...singleLines, '');
+  }
+
+  // Category sections
+  for (const cat of CATEGORY_DIRS) {
+    const dp = join(root, cat);
+    if (!existsSync(dp)) continue;
+    let files;
+    try {
+      files = readdirSync(dp).filter(f => f.endsWith('.md')).sort();
+    } catch {
+      continue;
+    }
+    if (!files.length) continue;
+    lines.push(`## ${cat}`, '');
+    for (const f of files) {
+      const fp = join(dp, f);
+      const summary = firstSummary(fp);
+      const size = safeSize(fp);
+      lines.push(`- ${cat}/${f} (${size} bytes)${summary ? ` — ${summary}` : ''}`);
+    }
+    lines.push('');
+  }
+
+  // Entries section (count only — atomic entries are searched via memory_query)
+  lines.push('## entries', '', `- ${entryCount} atomic entries (use memory_query to search)`, '');
+
+  lines.push(
+    '_Note: use the `memory_search` tool with one or more paths to load a classification',
+    'file in full, or `memory_query` to search atomic entries by keywords/tags._',
+  );
+
+  return lines.join('\n') + '\n';
+}
+
+/**
+ * First non-heading non-empty line of a file, trimmed to 120 chars.
+ */
+function firstSummary(fp) {
+  try {
+    const raw = readFileSync(fp, 'utf8');
+    for (const line of raw.split('\n')) {
+      const s = line.trim();
+      if (!s) continue;
+      if (s.startsWith('#')) continue;
+      if (s.startsWith('---')) continue;
+      return s.length > 120 ? s.slice(0, 120) + '…' : s;
+    }
+  } catch { /* ignore */ }
+  return '';
+}
+
+function safeSize(fp) {
+  try {
+    return statSync(fp).size;
+  } catch {
+    return 0;
+  }
+}
+
+// ─── Prompt injection builder ───────────────────────────────
+
+/**
+ * Build the memory section to inject into the system prompt every turn.
+ *
+ * Content, in order:
+ *   1. index.md (full text — auto-regenerated when missing/stale)
+ *   2. user-preferences.md (full text)
+ *   3. Project header excerpt (first PROJECT_HEADER_CHAR_BUDGET chars of
+ *      the matching by-project/<slug>.md, if cwd matches)
+ *
+ * Total output is capped at PROMPT_INJECTION_CHAR_BUDGET; later sections
+ * are dropped first if over budget.
+ *
+ * @param {{
+ *   yeaftDir: string,
+ *   cwd?: string,
+ *   entryCount?: number,
+ *   language?: 'en' | 'zh',
+ * }} params
+ * @returns {string}
+ */
+export function buildMemoryInjection({ yeaftDir, cwd, entryCount = 0, language = 'en' }) {
+  if (!yeaftDir) return '';
+
+  const heading = language === 'zh' ? '## 记忆索引' : '## Memory Index';
+  const prefHeading = language === 'zh' ? '## 用户偏好' : '## User Preferences';
+  const projectHeading = language === 'zh' ? '## 当前项目摘要' : '## Current Project Summary';
+
+  let indexText = readMemoryFile(yeaftDir, 'index.md');
+  if (!indexText.trim()) {
+    // Auto-generate an index on the fly so the LLM always sees something useful.
+    indexText = renderIndex(yeaftDir, entryCount);
+  }
+
+  const prefText = readMemoryFile(yeaftDir, 'user-preferences.md');
+
+  let projectText = '';
+  const projectRel = cwd ? findProjectFile(yeaftDir, cwd) : null;
+  if (projectRel) {
+    projectText = excerpt(readMemoryFile(yeaftDir, projectRel), PROJECT_HEADER_CHAR_BUDGET);
+  }
+
+  const sections = [];
+  sections.push(`${heading}\n${indexText.trim()}`);
+  if (prefText.trim()) sections.push(`${prefHeading}\n${prefText.trim()}`);
+  if (projectText.trim()) sections.push(`${projectHeading} (${projectRel})\n${projectText.trim()}`);
+
+  // Enforce total char budget — drop from the end.
+  let combined = sections.join('\n\n');
+  while (combined.length > PROMPT_INJECTION_CHAR_BUDGET && sections.length > 1) {
+    sections.pop();
+    combined = sections.join('\n\n');
+  }
+  if (combined.length > PROMPT_INJECTION_CHAR_BUDGET) {
+    combined = excerpt(combined, PROMPT_INJECTION_CHAR_BUDGET);
+  }
+  return combined;
+}

package/unify/prompts.js

@@ -11,6 +11,13 @@
  *   - Memory section (user profile + recalled entries)
  *   - Compact summary section (conversation history summary)
  *
+ * task-287 refactor (tool-on-demand memory):
+ *   - New `memoryInjection` param carries prebuilt "Memory Index + user
+ *     preferences + project header" text (~1.5k tokens). Engine builds this
+ *     via memory/layout.buildMemoryInjection() and passes it every turn.
+ *   - Legacy `memory={profile,entries}` param still supported for callers
+ *     (tests, CLI) that have not migrated.
+ *
  * Reference: yeaft-unify-system-prompt-budget.md — Static + Dynamic + Context layers
  */
 
@@ -155,6 +162,7 @@ export const SUPPORTED_LANGUAGES = Object.keys(PROMPTS);
  *   mode?: string,
  *   toolNames?: string[],
  *   memory?: { profile?: string, entries?: object[] },
+ *   memoryInjection?: string,
  *   compactSummary?: string,
  *   skillContent?: string,
  * }} params
@@ -165,6 +173,7 @@ export function buildSystemPrompt({
   mode = 'chat',
   toolNames = [],
   memory,
+  memoryInjection,
   compactSummary,
   skillContent,
 } = {}) {
@@ -218,7 +227,12 @@ export function buildSystemPrompt({
   }
 
   // ─── 6. Memory Section ─────────────────────────────────
-  if (memory && (memory.profile || (memory.entries && memory.entries.length > 0))) {
+  if (memoryInjection && memoryInjection.trim()) {
+    // New path (task-287): prebuilt injection from memory/layout.buildMemoryInjection()
+    // Contains index.md + user-preferences.md + optional project header excerpt.
+    parts.push(memoryInjection.trim());
+  } else if (memory && (memory.profile || (memory.entries && memory.entries.length > 0))) {
+    // Legacy path — kept for callers (tests, CLI) that have not migrated yet.
     const memoryParts = [lang.memoryHeader];
 
     if (memory.profile) {

package/unify/tools/agent.js

@@ -122,6 +122,56 @@ export function budgetExceededResult(agent, reason) {
   };
 }
 
+/**
+ * Apply an incremental delta to an agent's usage, then check budget.
+ * If exceeded: abort the agent's signal, set result to the budget envelope,
+ * flip status to 'completed', and return the envelope. Otherwise returns null.
+ *
+ * Call this at each turn boundary inside the sub-agent's execution loop.
+ *
+ * @param {string} agentId
+ * @param {{ tokens?: number, turns?: number, partial_output?: string }} [delta]
+ * @param {number} [now=Date.now()]
+ * @returns {object|null} — budget envelope if exceeded, else null
+ */
+export function tickAgent(agentId, delta = {}, now = Date.now()) {
+  const agent = agents.get(agentId);
+  if (!agent) return null;
+  if (agent.status === 'completed' || agent.status === 'closed') return null;
+
+  if (typeof delta.tokens === 'number' && delta.tokens > 0) {
+    agent.usage.tokens += delta.tokens;
+  }
+  if (typeof delta.turns === 'number' && delta.turns > 0) {
+    agent.usage.turns += delta.turns;
+  }
+  if (typeof delta.partial_output === 'string' && delta.partial_output) {
+    agent.partial_output = delta.partial_output;
+  }
+
+  const check = checkBudget(agent, now);
+  if (!check.exceeded) return null;
+
+  const envelope = budgetExceededResult(agent, check.reason);
+  agent.result = envelope;
+  agent.status = 'completed';
+  agent.diagnostics.push({
+    type: 'budget_exceeded',
+    limit: check.limit,
+    reason: check.reason,
+    at: now,
+  });
+  // Signal any in-flight sub-agent work to stop
+  if (agent.abortController && !agent.abortController.signal.aborted) {
+    try {
+      agent.abortController.abort(check.reason);
+    } catch {
+      // ignore double-abort
+    }
+  }
+  return envelope;
+}
+
 export default defineTool({
   name: 'Agent',
   description: `Create a sub-agent to work on an independent task in parallel.
@@ -219,6 +269,7 @@ Guidelines:
       usage: { tokens: 0, turns: 0, startedAt: now },
       createdAt: now,
       trace: [],
+      abortController: new AbortController(),
     };
 
     agents.set(agentId, agent);

package/unify/tools/index.js

@@ -21,6 +21,7 @@ import askUser from './ask-user.js';
 import memoryRead from './memory-read.js';
 import memoryWrite from './memory-write.js';
 import memorySearch from './memory-search.js';
+import memoryQuery from './memory-query.js';
 import webSearch from './web-search.js';
 import webFetch from './web-fetch.js';
 import historySearch from './history-search.js';
@@ -80,6 +81,7 @@ export const allTools = [
   memoryRead,
   memoryWrite,
   memorySearch,
+  memoryQuery,
   webSearch,
   webFetch,
   historySearch,

package/unify/tools/memory-query.js

@@ -0,0 +1,133 @@
+/**
+ * memory-query.js — Search atomic memory entries by keywords/tags/scope.
+ *
+ * New-layout tool (task-287 memory refactor).
+ *
+ * Delegates to MemoryStore.findByFilter + MemoryStore.search for the actual
+ * heavy lifting; this is a tool-exposed wrapper that:
+ *   1. Accepts flat `keywords[]` (used as tags AND as content keyword scan)
+ *   2. Optional tags[], scope, limit
+ *   3. Returns a compact list suitable for LLM consumption
+ *
+ * Use this for fuzzy discovery over atomic entries. For loading a known
+ * classification file in full, use `memory_search` instead.
+ */
+
+import { defineTool } from './types.js';
+
+const DEFAULT_LIMIT = 10;
+const MAX_LIMIT = 30;
+const SNIPPET_CHARS = 400;
+
+export default defineTool({
+  name: 'memory_query',
+  description: `Search Yeaft's atomic memory entries by keywords, tags, and scope.
+
+Scoring:
+  - Exact scope match: +3
+  - Ancestor/descendant scope: +2
+  - "global" scope (fallback): +1
+  - Each tag overlap: +1
+  - Keyword hit in entry content/name/tags: retained
+
+Use this when the system-prompt Memory Index suggests the info is in atomic
+entries (entries/) rather than in a classification file. Returns up to 'limit'
+results sorted by score descending.`,
+  parameters: {
+    type: 'object',
+    properties: {
+      keywords: {
+        type: 'array',
+        items: { type: 'string' },
+        description: 'Words to search in entry content/name/tags. Required.',
+      },
+      tags: {
+        type: 'array',
+        items: { type: 'string' },
+        description: 'Exact-tag filter (scored separately from keywords).',
+      },
+      scope: {
+        type: 'string',
+        description: 'Memory scope to prefer (e.g. "work/my-project").',
+      },
+      limit: {
+        type: 'number',
+        description: `Max results (default ${DEFAULT_LIMIT}, max ${MAX_LIMIT})`,
+      },
+    },
+    required: ['keywords'],
+  },
+  modes: ['chat', 'work'],
+  isConcurrencySafe: () => true,
+  isReadOnly: () => true,
+  async execute(input, ctx) {
+    const memoryStore = ctx?.memoryStore;
+    if (!memoryStore) {
+      return JSON.stringify({ error: 'Memory system not initialized' });
+    }
+
+    const keywords = Array.isArray(input?.keywords)
+      ? input.keywords.filter(k => typeof k === 'string' && k.trim())
+      : [];
+    if (keywords.length === 0) {
+      return JSON.stringify({ error: 'keywords is required and must be a non-empty string array' });
+    }
+
+    const tags = Array.isArray(input?.tags)
+      ? input.tags.filter(t => typeof t === 'string' && t.trim())
+      : [];
+    const scope = typeof input?.scope === 'string' ? input.scope : undefined;
+    const rawLimit = Number.isFinite(input?.limit) ? input.limit : DEFAULT_LIMIT;
+    const limit = Math.max(1, Math.min(MAX_LIMIT, Math.floor(rawLimit)));
+
+    try {
+      // Union tags: explicit tags[] + keywords (keywords double as tag hints)
+      const tagUnion = [...new Set([...tags, ...keywords])];
+
+      // Phase 1: scored filter by scope + tags
+      let results = memoryStore.findByFilter({
+        scope,
+        tags: tagUnion,
+        limit: limit * 3, // over-fetch for phase 2
+      });
+
+      // Phase 2: if any entries lack tag overlap, augment with keyword full-text
+      // scan so rare-word queries still surface entries with matching content.
+      const seen = new Set(results.map(e => e.name));
+      for (const kw of keywords) {
+        if (results.length >= limit * 3) break;
+        const extra = memoryStore.search(kw, limit);
+        for (const e of extra) {
+          if (!seen.has(e.name)) {
+            seen.add(e.name);
+            results.push({ ...e, _score: (e._score || 0) + 0.5 });
+          }
+        }
+      }
+
+      // Final sort + trim
+      results.sort((a, b) => (b._score || 0) - (a._score || 0));
+      results = results.slice(0, limit);
+
+      return JSON.stringify({
+        totalResults: results.length,
+        results: results.map(e => ({
+          name: e.name,
+          kind: e.kind,
+          scope: e.scope,
+          tags: e.tags || [],
+          importance: e.importance,
+          score: e._score,
+          snippet: e.content
+            ? (e.content.length > SNIPPET_CHARS
+                ? e.content.slice(0, SNIPPET_CHARS) + '…'
+                : e.content)
+            : '',
+          updated_at: e.updated_at,
+        })),
+      }, null, 2);
+    } catch (err) {
+      return JSON.stringify({ error: `memory_query failed: ${err.message}` });
+    }
+  },
+});

package/unify/tools/memory-search.js

@@ -1,101 +1,102 @@
 /**
- * memory-search.js — Search memory entries by scope, tags, and keywords.
+ * memory-search.js — Load memory classification files by path.
  *
- * Uses the MemoryStore's findByFilter for structured search.
+ * New-layout tool (task-287 memory refactor).
+ *
+ * The system prompt injects `index.md` every turn, which lists all available
+ * classification files under `~/.yeaft/memory/` (single files + by-project /
+ * by-topic / timeline categories). When the LLM sees a path it wants,
+ * it calls this tool with `paths: [...]` to load one or more of those files
+ * in full.
+ *
+ * This is NOT a fuzzy search. It is a precise file loader. Use `memory_query`
+ * for fuzzy search over atomic entries.
+ *
+ * Only paths under `memory/` are accepted. `..` segments are rejected.
  */
 
 import { defineTool } from './types.js';
+import { readMemoryFile, listClassificationFiles } from '../memory/layout.js';
+
+const MAX_FILES_PER_CALL = 5;
+const MAX_BYTES_PER_FILE = 32000;
 
 export default defineTool({
-  name: 'MemorySearch',
-  description: `Search Yeaft's persistent memory for relevant entries.
+  name: 'memory_search',
+  description: `Load one or more memory classification files in full.
+
+Paths are relative to ~/.yeaft/memory/. Allowed targets:
+  - user-preferences.md           — merged user preferences
+  - by-project/<slug>.md          — per-project narrative summary
+  - by-topic/<slug>.md            — per-topic narrative summary
+  - timeline/<YYYY-MM>.md         — monthly narrative digest
 
-Searches by scope, tags, kind, or keyword. Results are scored by relevance:
-- Exact scope match: highest score
-- Ancestor/descendant scope: medium score
-- Tag overlap: additional score per matching tag
-- Keyword in content: found via full-text scan
+See the "Memory Index" section of the system prompt for the current list
+of available files. Use this tool when the index suggests a file is relevant
+to the user's current request. For fuzzy search over atomic memory entries
+(facts, lessons, preferences), use the memory_query tool instead.
 
-Use this to find previously learned information before asking the user again.`,
+Up to ${MAX_FILES_PER_CALL} files per call. Each file is capped at ${MAX_BYTES_PER_FILE} bytes.`,
   parameters: {
     type: 'object',
     properties: {
-      scope: {
-        type: 'string',
-        description: 'Memory scope to search in (e.g. "global", "work/my-project")',
-      },
-      tags: {
+      paths: {
         type: 'array',
         items: { type: 'string' },
-        description: 'Tags to filter by',
-      },
-      kind: {
-        type: 'string',
-        enum: ['fact', 'preference', 'skill', 'lesson', 'context', 'relation'],
-        description: 'Filter by memory kind',
-      },
-      keyword: {
-        type: 'string',
-        description: 'Keyword to search in entry content',
-      },
-      limit: {
-        type: 'number',
-        description: 'Maximum number of results (default: 15)',
+        description: 'Relative paths under memory/. Example: ["by-project/claude-web-chat.md", "user-preferences.md"]',
       },
     },
+    required: ['paths'],
   },
   modes: ['chat', 'work'],
   isConcurrencySafe: () => true,
   isReadOnly: () => true,
   async execute(input, ctx) {
-    const memoryStore = ctx?.memoryStore;
-    if (!memoryStore) {
-      return JSON.stringify({ error: 'Memory system not initialized' });
+    const yeaftDir = ctx?.yeaftDir;
+    if (!yeaftDir) {
+      return JSON.stringify({ error: 'Memory system not initialized (no yeaftDir in context)' });
     }
 
-    try {
-      const limit = input.limit || 15;
-
-      // Use findByFilter for scope + tag search
-      let results = memoryStore.findByFilter({
-        scope: input.scope,
-        tags: input.tags || [],
-        limit: limit * 2, // over-fetch for post-filtering
+    const paths = Array.isArray(input?.paths) ? input.paths : [];
+    if (paths.length === 0) {
+      return JSON.stringify({
+        error: 'paths is required and must be a non-empty string array',
+        availablePaths: listClassificationFiles(yeaftDir).map(f => f.path),
       });
+    }
 
-      // Filter by kind if specified
-      if (input.kind) {
-        results = results.filter(e => e.kind === input.kind);
-      }
+    const results = [];
+    const errors = [];
 
-      // Filter by keyword if specified
-      if (input.keyword) {
-        const kw = input.keyword.toLowerCase();
-        results = results.filter(e =>
-          (e.content && e.content.toLowerCase().includes(kw)) ||
-          (e.name && e.name.toLowerCase().includes(kw)) ||
-          (e.tags && e.tags.some(t => t.toLowerCase().includes(kw)))
-        );
+    for (const rel of paths.slice(0, MAX_FILES_PER_CALL)) {
+      if (typeof rel !== 'string' || !rel.trim()) {
+        errors.push({ path: rel, error: 'not a non-empty string' });
+        continue;
+      }
+      if (rel.includes('..') || rel.startsWith('/')) {
+        errors.push({ path: rel, error: 'path must be relative and must not contain ..' });
+        continue;
+      }
+      if (!rel.endsWith('.md')) {
+        errors.push({ path: rel, error: 'only .md files are supported' });
+        continue;
       }
 
-      // Trim to limit
-      results = results.slice(0, limit);
+      const text = readMemoryFile(yeaftDir, rel);
+      if (!text) {
+        errors.push({ path: rel, error: 'file not found or empty' });
+        continue;
+      }
 
-      return JSON.stringify({
-        results: results.map(e => ({
-          name: e.name,
-          kind: e.kind,
-          scope: e.scope,
-          tags: e.tags,
-          importance: e.importance,
-          content: e.content?.slice(0, 500) + (e.content?.length > 500 ? '...' : ''),
-          updated_at: e.updated_at,
-          score: e._score,
-        })),
-        totalResults: results.length,
-      }, null, 2);
-    } catch (err) {
-      return JSON.stringify({ error: `Memory search failed: ${err.message}` });
+      const truncated = text.length > MAX_BYTES_PER_FILE;
+      results.push({
+        path: rel,
+        content: truncated ? text.slice(0, MAX_BYTES_PER_FILE) : text,
+        truncated,
+        size: text.length,
+      });
     }
+
+    return JSON.stringify({ results, errors }, null, 2);
   },
 });