mu-harness 0.27.0 → 0.28.0

package/esm/channels/channel.js

@@ -22,6 +22,9 @@ export const createChannel = (config) => {
         get messages() {
             return session?.messages ?? [];
         },
+        get session() {
+            return session;
+        },
         send: async (input) => (await ensure()).send(input),
         abort: () => session?.abort(),
         subscribe: emitter.subscribe,

package/esm/channels/types.d.ts

@@ -1,5 +1,5 @@
 import type { ContentPart, Message } from 'mu-core';
-import type { AgentSessionEvent } from '../session/index.js';
+import type { AgentSession, AgentSessionEvent } from '../session/index.js';
 export type ChannelEvent = AgentSessionEvent | {
     type: 'channel_open';
     title: string;
@@ -14,6 +14,8 @@ export interface Channel {
     readonly title: string;
     readonly started: boolean;
     readonly messages: readonly Message[];
+    /** The live AgentSession, once started — exposes `lastRequest` for inspection commands. */
+    readonly session?: AgentSession;
     send(input: string | ContentPart[]): Promise<void>;
     abort(): void;
     subscribe(listener: (event: AgentSessionEvent) => void): () => void;

package/esm/channels/ws/server.js

@@ -111,7 +111,7 @@ export function webSocketAdapter(opts) {
                 }
                 case 'command': {
                     const sessionId = msg.sessionId ?? client.sessionId;
-                    const result = await commands.run(msg.text, { sessionId });
+                    const result = await commands.run(msg.text, { sessionId, session: manager.get(sessionId)?.session });
                     if (result.ok) {
                         if (result.output != null) {
                             push({

package/esm/commands/defaults.d.ts

@@ -8,4 +8,13 @@ export declare const createSessionsCommand: (sessions: SessionManager, options?:
     cwd?: string;
 }) => Command;
 export declare const createQuitCommand: (onQuit: () => void | Promise<void>) => Command;
+/**
+ * Universal `/context` — the live session's context broken down into all categories
+ * (system / context / instructions / memory / tools / you / agent / tool-output), each
+ * counted with the model's own tokenizer, plus the context-window fill % and a colour
+ * heatmap. Works on every channel.
+ */
+export declare const createContextCommand: () => Command;
+/** Universal `/compact` — manually summarize older messages to free context now. */
+export declare const createCompactCommand: () => Command;
 export declare const createHelpCommand: (list: () => Command[]) => Command;

package/esm/commands/defaults.js

@@ -40,6 +40,133 @@ export const createQuitCommand = (onQuit) => ({
         return { ok: true };
     },
 });
+const estTokens = (chars) => Math.max(1, Math.round(chars / 4));
+const GRID_COLS = 24;
+const GRID_ROWS = 8;
+const GRID_CELLS = GRID_COLS * GRID_ROWS;
+const BLOCK = '█';
+const FREE = '·';
+// ANSI SGR colours — mu's TUI text utils are ANSI-aware so these render in the terminal;
+// the companion strips them (plain text), keeping the labelled breakdown readable.
+const RESET = '\x1b[0m';
+const DIM = '\x1b[2m';
+const paint = (s, color) => `${color}${s}${RESET}`;
+const fillColor = (pct) => (pct >= 80 ? '\x1b[31m' : pct >= 50 ? '\x1b[33m' : '\x1b[32m');
+/** Extract a `<tag>…</tag>` block (with tags), or '' when absent. */
+function tagBlock(s, tag) {
+    const i = s.indexOf(`<${tag}>`);
+    const j = s.indexOf(`</${tag}>`);
+    return i !== -1 && j > i ? s.slice(i, j + `</${tag}>`.length) : '';
+}
+/** Split the assembled system into its segments: agent prompt / env / instructions / memory / tool-prompts. */
+function splitSystem(system) {
+    const env = tagBlock(system, 'env');
+    const instructions = tagBlock(system, 'instructions');
+    const memory = tagBlock(system, 'memory');
+    const opens = ['<env>', '<instructions>', '<memory>'].map((t) => system.indexOf(t)).filter((i) => i !== -1);
+    const closes = [
+        [env, '</env>'],
+        [instructions, '</instructions>'],
+        [memory, '</memory>'],
+    ]
+        .filter(([b]) => b)
+        .map(([, c]) => system.indexOf(c) + c.length);
+    const firstOpen = opens.length ? Math.min(...opens) : -1;
+    const lastClose = closes.length ? Math.max(...closes) : -1;
+    return {
+        agent: (firstOpen === -1 ? system : system.slice(0, firstOpen)).trim(),
+        env,
+        instructions,
+        memory,
+        toolPrompts: lastClose === -1 ? '' : system.slice(lastClose).trim(),
+    };
+}
+/**
+ * Universal `/context` — the live session's context broken down into all categories
+ * (system / context / instructions / memory / tools / you / agent / tool-output), each
+ * counted with the model's own tokenizer, plus the context-window fill % and a colour
+ * heatmap. Works on every channel.
+ */
+export const createContextCommand = () => ({
+    name: 'context',
+    description: 'Show the live context: per-category tokens, window fill %, and a heatmap',
+    run: async (_args, ctx) => {
+        const last = await ctx.session?.assembleRequest?.();
+        if (!last)
+            return { ok: true, output: 'No session in memory yet — start a conversation first.' };
+        const sys = splitSystem(last.system);
+        const toolSchemas = last.tools
+            .map((t) => JSON.stringify({ name: t.name, description: t.description, parameters: t.parameters }))
+            .join('\n');
+        const body = last.messages.filter((m) => m.role !== 'system');
+        const byRole = (role) => body.filter((m) => m.role === role).map((m) => JSON.stringify(m.content)).join('\n');
+        const count = ctx.session?.countTokens;
+        const measure = async (text) => {
+            if (!text)
+                return { n: 0, exact: true };
+            if (count) {
+                const n = await count(text);
+                if (n !== undefined)
+                    return { n, exact: true };
+            }
+            return { n: estTokens(text.length), exact: false };
+        };
+        // label, text, ANSI colour — one per category, in render order.
+        const SPEC = [
+            ['system', sys.agent, '\x1b[36m'], // cyan — the agent prompt
+            ['context', sys.env, '\x1b[33m'], // yellow — the <env> block
+            ['instructions', sys.instructions, '\x1b[34m'], // blue — AGENTS.md / CLAUDE.md
+            ['memory', sys.memory, '\x1b[35m'], // magenta — MEMORY.md
+            ['tools', `${toolSchemas}\n${sys.toolPrompts}`, '\x1b[31m'], // red — schemas + tool prompts
+            ['you', byRole('user'), '\x1b[32m'], // green — your messages
+            ['agent', byRole('assistant'), '\x1b[94m'], // bright blue — assistant replies
+            ['tool-out', byRole('tool'), '\x1b[90m'], // grey — tool results
+        ];
+        const measured = await Promise.all(SPEC.map(([, text]) => measure(text)));
+        const cats = SPEC.map(([label, , color], i) => ({ label, n: measured[i].n, color })).filter((c) => c.n > 0);
+        const exact = measured.every((m) => m.exact);
+        const total = cats.reduce((s, c) => s + c.n, 0);
+        const window = (await ctx.session?.contextWindow?.()) ?? 0;
+        const mark = (n) => (exact ? `${n}` : `~${n}`);
+        const lines = [`context — tokens (${exact ? 'exact, model tokenizer' : 'estimated ≈ chars/4'}):`];
+        for (const c of cats)
+            lines.push(`  ${paint(BLOCK, c.color)} ${c.label.padEnd(13)} ${mark(c.n)}`);
+        const pctNum = window ? Math.round((total / window) * 100) : 0;
+        const pct = window ? ` / ${window} ${paint(`(${pctNum}%)`, fillColor(pctNum))}` : '';
+        lines.push(`  ${' '.repeat(15)}── ${mark(total)}${pct}`);
+        if (window > 0) {
+            const cellTokens = Math.max(1, window / GRID_CELLS);
+            const cells = [];
+            for (const c of cats) {
+                for (let i = 0; i < Math.round(c.n / cellTokens) && cells.length < GRID_CELLS; i++)
+                    cells.push(paint(BLOCK, c.color));
+            }
+            while (cells.length < GRID_CELLS)
+                cells.push(paint(FREE, DIM));
+            cells.length = GRID_CELLS;
+            lines.push('');
+            for (let r = 0; r < GRID_ROWS; r++)
+                lines.push(`  ${cells.slice(r * GRID_COLS, (r + 1) * GRID_COLS).join('')}`);
+        }
+        return { ok: true, output: lines.join('\n') };
+    },
+});
+/** Universal `/compact` — manually summarize older messages to free context now. */
+export const createCompactCommand = () => ({
+    name: 'compact',
+    description: 'Summarize older messages to free up context now',
+    run: async (_args, ctx) => {
+        if (!ctx.session?.compact)
+            return { ok: true, output: 'Compaction is not available on this session.' };
+        const before = ctx.session.messages?.length ?? 0;
+        await ctx.session.compact();
+        const after = ctx.session.messages?.length ?? 0;
+        return {
+            ok: true,
+            output: after < before ? `Compacted: ${before} → ${after} messages.` : 'Nothing to compact yet.',
+        };
+    },
+});
 export const createHelpCommand = (list) => ({
     name: 'help',
     description: 'Show available commands',

package/esm/commands/index.d.ts

@@ -1,4 +1,4 @@
-export { createAgentsCommand, createHelpCommand, createQuitCommand, createSessionsCommand, createSkillsCommand, } from './defaults.js';
+export { createAgentsCommand, createCompactCommand, createContextCommand, createHelpCommand, createQuitCommand, createSessionsCommand, createSkillsCommand, } from './defaults.js';
 export { createCommandRegistry } from './registry.js';
 export { createSkillCommand, type SkillCommandDeps } from './skill.js';
 export type { Command, CommandContext, CommandRegistry, CommandResult } from './types.js';

package/esm/commands/index.js

@@ -1,3 +1,3 @@
-export { createAgentsCommand, createHelpCommand, createQuitCommand, createSessionsCommand, createSkillsCommand, } from './defaults.js';
+export { createAgentsCommand, createCompactCommand, createContextCommand, createHelpCommand, createQuitCommand, createSessionsCommand, createSkillsCommand, } from './defaults.js';
 export { createCommandRegistry } from './registry.js';
 export { createSkillCommand } from './skill.js';

package/esm/commands/types.d.ts

@@ -1,3 +1,4 @@
+import type { AgentSession } from '../session/index.js';
 export interface CommandResult {
     ok: boolean;
     output?: unknown;
@@ -5,6 +6,8 @@ export interface CommandResult {
 }
 export interface CommandContext {
     sessionId?: string;
+    /** The live session for this invocation — lets a command inspect what the model actually saw. */
+    session?: AgentSession;
 }
 export interface Command {
     name: string;

package/esm/harness/compaction.d.ts

@@ -0,0 +1,14 @@
+import type { AgentSessionHooks } from '../hooks/index.js';
+export interface CompactionOptions {
+    /** Compact once estimated usage exceeds this fraction of the context window. Default 0.8. */
+    thresholdPct?: number;
+    /** Number of most-recent messages kept verbatim through a compaction. Default 6. */
+    keepLastTurns?: number;
+}
+/**
+ * An `afterTurn` hook that auto-compacts the conversation as it approaches the context
+ * window: when the estimated token usage crosses `thresholdPct`, older messages are
+ * summarized (keeping the system message + the last `keepLastTurns`). The gap between the
+ * threshold and the window is the reserved compaction buffer.
+ */
+export declare function createCompactionHook(opts?: CompactionOptions): AgentSessionHooks;

package/esm/harness/compaction.js

@@ -0,0 +1,21 @@
+/**
+ * An `afterTurn` hook that auto-compacts the conversation as it approaches the context
+ * window: when the estimated token usage crosses `thresholdPct`, older messages are
+ * summarized (keeping the system message + the last `keepLastTurns`). The gap between the
+ * threshold and the window is the reserved compaction buffer.
+ */
+export function createCompactionHook(opts = {}) {
+    const thresholdPct = opts.thresholdPct ?? 0.8;
+    const keepLastTurns = opts.keepLastTurns ?? 6;
+    return {
+        afterTurn: async ({ messages, contextWindow, compact }) => {
+            const window = await contextWindow();
+            if (!window)
+                return;
+            // Cheap chars/4 estimate — avoids a tokenizer round-trip on every turn.
+            const estimate = messages.reduce((n, m) => n + JSON.stringify(m.content).length, 0) / 4;
+            if (estimate > window * thresholdPct)
+                await compact({ keepLastTurns });
+        },
+    };
+}

package/esm/harness/create.js

@@ -2,7 +2,7 @@ import os from 'node:os';
 import { join } from 'node:path';
 import process from 'node:process';
 import { createAgentRegistry, grantArg, loadAgents, toolDecision, toolNames } from '../agents/index.js';
-import { createAgentsCommand, createCommandRegistry, createHelpCommand, createSessionsCommand, createSkillCommand, createSkillsCommand, } from '../commands/index.js';
+import { createAgentsCommand, createCommandRegistry, createCompactCommand, createContextCommand, createHelpCommand, createSessionsCommand, createSkillCommand, createSkillsCommand, } from '../commands/index.js';
 import { createHarnessConfig } from '../config/index.js';
 import { mergeHooks } from '../hooks/index.js';
 import { allowList } from '../permissions/index.js';
@@ -12,6 +12,9 @@ import { createAgentSession, createSessionCatalog, createSessionManager, createS
 import { createRunSkillTool, createSkillRegistry, createSkillTool, loadSkills, runSkill } from '../skills/index.js';
 import { createSubAgentRegistry, createSubAgentTool, runSubAgent } from '../subAgents/index.js';
 import { environmentBlock } from './environment.js';
+import { dirsForPath, loadInstructions } from './instructions.js';
+import { createMemoryStore, createRememberTool } from './memory.js';
+import { createCompactionHook } from './compaction.js';
 import { createModelRegistry } from './models.js';
 const TITLE_AGENT = {
     name: 'title',
@@ -19,6 +22,24 @@ const TITLE_AGENT = {
     prompt: 'Generate a concise title (3 to 6 words) for the conversation based on the user message. Reply with ONLY the title — no quotes, no trailing punctuation, no explanation.',
     tools: [],
 };
+/** Tool-input field names that carry filesystem paths — used to scope nested AGENTS.md. */
+const PATH_KEYS = new Set(['path', 'file', 'filename', 'file_path', 'filepath', 'dir', 'directory', 'cwd', 'paths', 'files']);
+function pathsFromInput(input) {
+    if (!input || typeof input !== 'object')
+        return [];
+    const out = [];
+    for (const [key, value] of Object.entries(input)) {
+        if (!PATH_KEYS.has(key.toLowerCase()))
+            continue;
+        if (typeof value === 'string')
+            out.push(value);
+        else if (Array.isArray(value))
+            for (const el of value)
+                if (typeof el === 'string')
+                    out.push(el);
+    }
+    return out;
+}
 export const createHarness = async (options) => {
     const { hostName, xdg, providers, model, agents: hostAgents = [], defaultAgents = [], skills: hostSkills = [], agentDirs, title, titleModel, scheduler: enableScheduler = false, approvals, ...sessionDefaults } = options;
     const cwd = options.cwd ?? process.cwd();
@@ -53,6 +74,42 @@ export const createHarness = async (options) => {
     const envHook = {
         prepareRequest: ({ system }) => ({ system: system ? `${system}\n\n${envBlock}` : envBlock }),
     };
+    // Project/global instructions (AGENTS.md / CLAUDE.md). Scopes: GLOBAL (configDir) + LOCAL
+    // (cwd & ancestors) + on-demand NESTED (subdirs the agent touches). `accessedDirs` grows as
+    // tools reference paths; the hook re-loads each turn so nested AGENTS.md appear when relevant.
+    const accessedDirs = new Set();
+    const trackPathsHook = {
+        beforeToolCall: ({ input }) => {
+            for (const p of pathsFromInput(input))
+                for (const d of dirsForPath(cwd, p))
+                    accessedDirs.add(d);
+        },
+    };
+    const instructionsHook = {
+        prepareRequest: async ({ system }) => {
+            const block = await loadInstructions(cwd, config.configDir, { accessed: accessedDirs });
+            if (!block)
+                return undefined;
+            const tagged = `<instructions>\n${block}\n</instructions>`;
+            return { system: system ? `${system}\n\n${tagged}` : tagged };
+        },
+    };
+    // Memory: GLOBAL (dataDir/MEMORY.md) + LOCAL (cwd/.mu/MEMORY.md), written via the `remember`
+    // tool. Re-loaded each turn so a memory saved this session shows up on the next.
+    const memory = createMemoryStore({ cwd, dataDir: config.dataDir });
+    const memoryHook = {
+        prepareRequest: async ({ system }) => {
+            const block = await memory.load();
+            if (!block)
+                return undefined;
+            const tagged = `<memory>\n${block}\n</memory>`;
+            return { system: system ? `${system}\n\n${tagged}` : tagged };
+        },
+    };
+    // Auto-compaction: summarize old messages as the context fills (enabled unless turned off).
+    const compactionHook = options.compaction === false
+        ? {}
+        : createCompactionHook(options.compaction || {});
     const pluginSkills = (sessionDefaults.plugins ?? []).flatMap((plugin) => plugin.skills ?? []);
     const mergedSkills = async () => [
         ...hostSkills,
@@ -74,6 +131,7 @@ export const createHarness = async (options) => {
         ...(sessionDefaults.tools ?? []),
         ...extra,
         createSkillTool(scopeSkills(agent)),
+        createRememberTool(memory),
         ...schedulerTools,
     ];
     const approvalHook = (getAgent) => approvals
@@ -99,7 +157,16 @@ export const createHarness = async (options) => {
     });
     const spawn = (agent) => persistTo(store, persona(agent, {
         tools: sessionTools(agent),
-        hooks: mergeHooks([sessionDefaults.hooks, allowList(toolNames(agent)), approvalHook(() => agent), envHook]),
+        hooks: mergeHooks([
+            sessionDefaults.hooks,
+            allowList(toolNames(agent)),
+            approvalHook(() => agent),
+            envHook,
+            instructionsHook,
+            memoryHook,
+            trackPathsHook,
+            compactionHook,
+        ]),
     }));
     const scheduler = enableScheduler && tasks
         ? createScheduler({
@@ -147,7 +214,15 @@ export const createHarness = async (options) => {
         },
         revive: ({ id, model: ref, messages }) => createAgentSession({
             ...sessionDefaults,
-            hooks: mergeHooks([sessionDefaults.hooks, approvalHook(() => approvals?.activeAgent()), envHook]),
+            hooks: mergeHooks([
+                sessionDefaults.hooks,
+                approvalHook(() => approvals?.activeAgent()),
+                envHook,
+                instructionsHook,
+                memoryHook,
+                trackPathsHook,
+                compactionHook,
+            ]),
             tools: sessionTools(undefined, [createSubAgentTool({ registry: agents, spawn, runs, parentId: id })]),
             ...models.resolve(ref),
             id,
@@ -158,6 +233,8 @@ export const createHarness = async (options) => {
         createAgentsCommand(agents),
         createSkillsCommand(skills),
         createSessionsCommand(sessions, { cwd }),
+        createContextCommand(),
+        createCompactCommand(),
         ...(tasks ? [createTasksCommand(tasks)] : []),
     ]);
     commands.register(createHelpCommand(() => commands.list()));

package/esm/harness/index.d.ts

@@ -1,3 +1,6 @@
 export type { Harness, HarnessOptions } from './types.js';
 export { createHarness } from './create.js';
+export { type CompactionOptions, createCompactionHook } from './compaction.js';
+export { createMemoryStore, createRememberTool, type MemoryScope, type MemoryStore } from './memory.js';
+export { loadInstructions } from './instructions.js';
 export { createModelRegistry, type ModelRegistry, type ModelRegistryOptions, type ResolvedModel } from './models.js';

package/esm/harness/index.js

@@ -1,2 +1,5 @@
 export { createHarness } from './create.js';
+export { createCompactionHook } from './compaction.js';
+export { createMemoryStore, createRememberTool } from './memory.js';
+export { loadInstructions } from './instructions.js';
 export { createModelRegistry } from './models.js';

package/esm/harness/instructions.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The directory chain from a file's directory UP to (and including) `cwd`. Used to scope
+ * nested AGENTS.md: touching `cwd/a/b/c.ts` makes `cwd`, `cwd/a`, `cwd/a/b` relevant.
+ * Returns [] when the path is outside `cwd`.
+ */
+export declare function dirsForPath(cwd: string, filePath: string): string[];
+/**
+ * Load project-instruction files (AGENTS.md / CLAUDE.md, opencode-style) across harness
+ * scopes: GLOBAL (configDir, every project) and LOCAL (cwd + ancestors, project-specific),
+ * plus on-demand NESTED scopes — any subdirectory the agent has touched (`accessed`) whose
+ * AGENTS.md should apply while working there. Concatenated shallow → deep so the most
+ * specific instructions land last. Returns undefined when nothing is found.
+ */
+export declare function loadInstructions(cwd: string, configDir: string, opts?: {
+    files?: readonly string[];
+    accessed?: Iterable<string>;
+}): Promise<string | undefined>;

package/esm/harness/instructions.js

@@ -0,0 +1,78 @@
+import { readFile } from 'node:fs/promises';
+import { dirname, isAbsolute, join, sep } from 'node:path';
+/** Filenames recognised as project/global instruction files, in priority order per directory. */
+const DEFAULT_FILES = ['AGENTS.md', 'CLAUDE.md'];
+const isUnder = (root, p) => p === root || p.startsWith(root.endsWith(sep) ? root : root + sep);
+/** Walk from `cwd` up to the filesystem root (capped), returning dirs root-first → cwd-last. */
+function ancestorDirs(cwd, max = 12) {
+    const dirs = [];
+    let dir = cwd;
+    for (let i = 0; i < max; i++) {
+        dirs.push(dir);
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return dirs.reverse();
+}
+/**
+ * The directory chain from a file's directory UP to (and including) `cwd`. Used to scope
+ * nested AGENTS.md: touching `cwd/a/b/c.ts` makes `cwd`, `cwd/a`, `cwd/a/b` relevant.
+ * Returns [] when the path is outside `cwd`.
+ */
+export function dirsForPath(cwd, filePath) {
+    if (!filePath)
+        return [];
+    const abs = isAbsolute(filePath) ? filePath : join(cwd, filePath);
+    if (!isUnder(cwd, abs))
+        return [];
+    const dirs = [];
+    let dir = dirname(abs);
+    while (isUnder(cwd, dir)) {
+        dirs.push(dir);
+        if (dir === cwd)
+            break;
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return dirs;
+}
+/** Read the first existing file (by `names`) in `dir`, returning its trimmed content. */
+async function readFirst(dir, names) {
+    for (const name of names) {
+        const text = await readFile(join(dir, name), 'utf-8').catch(() => undefined);
+        if (text && text.trim())
+            return { path: join(dir, name), text: text.trim() };
+    }
+    return undefined;
+}
+/**
+ * Load project-instruction files (AGENTS.md / CLAUDE.md, opencode-style) across harness
+ * scopes: GLOBAL (configDir, every project) and LOCAL (cwd + ancestors, project-specific),
+ * plus on-demand NESTED scopes — any subdirectory the agent has touched (`accessed`) whose
+ * AGENTS.md should apply while working there. Concatenated shallow → deep so the most
+ * specific instructions land last. Returns undefined when nothing is found.
+ */
+export async function loadInstructions(cwd, configDir, opts) {
+    const files = opts?.files ?? DEFAULT_FILES;
+    const parts = [];
+    const global = await readFirst(configDir, files);
+    if (global)
+        parts.push(`<!-- global: ${global.path} -->\n${global.text}`);
+    const dirSet = new Set(ancestorDirs(cwd));
+    for (const dir of opts?.accessed ?? [])
+        if (isUnder(cwd, dir))
+            dirSet.add(dir);
+    const dirs = [...dirSet]
+        .filter((d) => d !== configDir)
+        .sort((a, b) => a.split(sep).length - b.split(sep).length);
+    for (const dir of dirs) {
+        const local = await readFirst(dir, files);
+        if (local)
+            parts.push(`<!-- ${local.path} -->\n${local.text}`);
+    }
+    return parts.length > 0 ? parts.join('\n\n') : undefined;
+}

package/esm/harness/memory.d.ts

@@ -0,0 +1,18 @@
+import { type Tool } from 'mu-core';
+export type MemoryScope = 'local' | 'global';
+export interface MemoryStore {
+    /** Project-scoped memory file (cwd/.mu/MEMORY.md). */
+    readonly localPath: string;
+    /** Global memory file (dataDir/MEMORY.md), shared across all projects. */
+    readonly globalPath: string;
+    /** Concatenated memory (global then project), capped per scope, or undefined when empty. */
+    load(): Promise<string | undefined>;
+    /** Append a durable fact to the chosen scope's memory file. */
+    remember(fact: string, scope: MemoryScope): Promise<void>;
+}
+export declare function createMemoryStore(opts: {
+    cwd: string;
+    dataDir: string;
+}): MemoryStore;
+/** A `remember` tool the agent calls to persist durable facts to local or global memory. */
+export declare function createRememberTool(store: MemoryStore): Tool;

package/esm/harness/memory.js

@@ -0,0 +1,59 @@
+import { appendFile, mkdir, readFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { text } from 'mu-core';
+/** Cap per scope so a runaway memory file can't dominate the context (≈ Claude Code's 25KB). */
+const MAX_BYTES = 24 * 1024;
+export function createMemoryStore(opts) {
+    const localPath = join(opts.cwd, '.mu', 'MEMORY.md');
+    const globalPath = join(opts.dataDir, 'MEMORY.md');
+    const readCapped = async (path) => {
+        const raw = await readFile(path, 'utf-8').catch(() => undefined);
+        if (!raw || !raw.trim())
+            return undefined;
+        return raw.length > MAX_BYTES ? raw.slice(0, MAX_BYTES) : raw.trim();
+    };
+    return {
+        localPath,
+        globalPath,
+        async load() {
+            const parts = [];
+            const global = await readCapped(globalPath);
+            if (global)
+                parts.push(`<!-- global -->\n${global}`);
+            const project = await readCapped(localPath);
+            if (project)
+                parts.push(`<!-- project -->\n${project}`);
+            return parts.length > 0 ? parts.join('\n\n') : undefined;
+        },
+        async remember(fact, scope) {
+            const path = scope === 'global' ? globalPath : localPath;
+            await mkdir(dirname(path), { recursive: true });
+            await appendFile(path, `- ${fact.trim()}\n`, 'utf-8');
+        },
+    };
+}
+/** A `remember` tool the agent calls to persist durable facts to local or global memory. */
+export function createRememberTool(store) {
+    return {
+        name: 'remember',
+        description: 'Persist a durable fact to memory for future sessions (stable facts/preferences, not transient details). Scope: local = this project (default), global = all projects.',
+        parameters: {
+            type: 'object',
+            properties: {
+                fact: { type: 'string', description: 'One concise sentence to remember.' },
+                scope: { type: 'string', enum: ['local', 'global'], description: 'local (this project, default) or global (all projects).' },
+            },
+            required: ['fact'],
+            additionalProperties: false,
+        },
+        async run(input) {
+            const args = (input ?? {});
+            const fact = typeof args.fact === 'string' ? args.fact.trim() : '';
+            if (!fact)
+                return [text('Error: remember requires `fact` (string)')];
+            const scope = args.scope === 'global' ? 'global' : 'local';
+            await store.remember(fact, scope);
+            return [text(`Remembered (${scope}): ${fact}`)];
+        },
+    };
+}

package/esm/harness/types.d.ts

@@ -8,6 +8,7 @@ import type { Scheduler, TaskStore } from '../scheduler/index.js';
 import type { AgentSessionConfig, SessionManager } from '../session/index.js';
 import type { Skill, SkillRegistry } from '../skills/index.js';
 import type { SubAgentRegistry, SubAgentResult } from '../subAgents/index.js';
+import type { CompactionOptions } from './compaction.js';
 import type { ModelRegistry } from './models.js';
 export type HarnessOptions = HarnessConfigOptions & Omit<AgentSessionConfig, 'provider' | 'model' | 'id' | 'messages'> & {
     providers: Record<string, Provider>;
@@ -24,6 +25,8 @@ export type HarnessOptions = HarnessConfigOptions & Omit<AgentSessionConfig, 'pr
     cwd?: string;
     sourceUrl?: string;
     scheduler?: boolean;
+    /** Auto-compaction settings, or `false` to disable. Default: enabled at 80% of the window. */
+    compaction?: CompactionOptions | false;
     approvals?: {
         manager: ApprovalManager;
         activeAgent: () => Agent | undefined;

package/esm/hooks/merge-hooks.js

@@ -42,5 +42,11 @@ export const mergeHooks = (list) => {
             return result;
         };
     }
+    if (hooks.some((h) => h.afterTurn)) {
+        merged.afterTurn = async (ctx) => {
+            for (const h of hooks)
+                await h.afterTurn?.(ctx);
+        };
+    }
     return merged;
 };

package/esm/hooks/types.d.ts

@@ -4,6 +4,16 @@ export interface PreparedRequest {
     tools?: Tool[];
     messages?: Message[];
 }
+/** Context handed to `afterTurn` — inspect usage and trigger compaction without owning the message array. */
+export interface AfterTurnContext {
+    messages: readonly Message[];
+    countTokens(text: string): Promise<number | undefined>;
+    contextWindow(): Promise<number | undefined>;
+    /** Summarize older messages (keeping the system + last N), replacing them in place. */
+    compact(opts?: {
+        keepLastTurns?: number;
+    }): Promise<void>;
+}
 export interface AgentSessionHooks {
     sessionStart?(): void | Promise<void>;
     prepareRequest?(req: {
@@ -18,4 +28,6 @@ export interface AgentSessionHooks {
         name: string;
         result: ContentPart[];
     }): void | ContentPart[] | Promise<void | ContentPart[]>;
+    /** Fires after a turn completes (not on abort) — used for auto-compaction and memory writes. */
+    afterTurn?(ctx: AfterTurnContext): void | Promise<void>;
 }