agent-from-zero 0.5.0 → 0.27.0

package/dist/memory.js

@@ -0,0 +1,186 @@
+import fs from "node:fs"; // memory lives in a file on disk
+import path from "node:path"; // path joining
+// Long-term memory: facts the agent should carry ACROSS sessions, not just
+// within one conversation. Session persistence (Day 12) restores "what we were
+// talking about"; this restores "what I should always know about this project".
+//
+// One Markdown file, project-local, human-readable and human-editable. Not a
+// vector database, not embeddings: a file you can open, read, and fix.
+//
+// Two ways facts get in: the model calls `remember` explicitly, OR — when
+// auto-extract is on — after each turn a cheap model call reads the conversation
+// and saves what's worth keeping (especially turns where the USER corrected the
+// assistant: 90% the model gets right isn't worth saving, the 10% it got wrong
+// and was corrected on is gold). Every fact is TYPED so the model can tell "this
+// is who the user is" from "this is a correction" from "this is a project fact".
+export const MEMORY_PATH = path.resolve(".mini-agent", "MEMORY.md");
+// The four memory types (handbook §17). feedback is the most valuable.
+export const MEMORY_TYPES = ["user", "feedback", "project", "reference"];
+// Bounds, because unbounded memory dilutes the model's attention (Ch6: too many
+// rules → worse compliance) and grows the cached prefix forever. On overflow we
+// drop the OLDEST — recent facts are likelier still true.
+const MAX_ENTRIES = 40; // at most this many remembered facts
+const MAX_BYTES = 12_000; // ...and at most this many bytes total
+const HEADER = "# mini-agent long-term memory\n# One fact per line: - [type] fact. Injected at session start. Edit freely.\n";
+// Coerce any string to a valid type, defaulting to "project".
+function asType(t) {
+    return MEMORY_TYPES.includes(t ?? "") ? t : "project";
+}
+// Parse one bullet's text into a typed entry. "[feedback] foo" → feedback; a
+// bare "foo" (legacy / hand-written) → project.
+function parseEntry(text) {
+    const m = text.match(/^\[(\w+)\]\s*(.*)$/);
+    if (m && MEMORY_TYPES.includes(m[1]))
+        return { type: m[1], fact: m[2].trim() };
+    return { type: "project", fact: text.trim() };
+}
+// Read facts WITH their types. The fiddly parsing lives here.
+export function readMemoryTyped() {
+    try {
+        return fs
+            .readFileSync(MEMORY_PATH, "utf8")
+            .split("\n")
+            .filter((l) => l.startsWith("- "))
+            .map((l) => parseEntry(l.slice(2).trim()))
+            .filter((e) => e.fact);
+    }
+    catch {
+        return []; // no memory file yet — fine
+    }
+}
+// Read just the fact text (no type). Kept for callers that only want the facts.
+export function readMemory() {
+    return readMemoryTyped().map((e) => e.fact);
+}
+// The block injected into the system message, grouped by type so the model can
+// weigh "a correction" differently from "a project fact". Empty when there's
+// nothing, so the cached prefix stays clean for projects that never use it.
+export function memoryContext() {
+    const entries = readMemoryTyped();
+    if (!entries.length)
+        return "";
+    const labels = {
+        user: "About the user",
+        feedback: "Guidance & corrections the user gave you (follow these)",
+        project: "Project facts & decisions",
+        reference: "References",
+    };
+    let out = "\n\nLong-term project memory (background from earlier sessions; verify against the code before relying on a specific claim):";
+    for (const type of MEMORY_TYPES) {
+        const group = entries.filter((e) => e.type === type);
+        if (group.length)
+            out += `\n[${labels[type]}]\n${group.map((e) => `- ${e.fact}`).join("\n")}`;
+    }
+    return out;
+}
+// Append a typed fact, then enforce the caps. Self-healing: every write re-applies
+// the bounds, so the file can never grow past them even if hand-edited huge.
+export function addFact(fact, type = "project") {
+    const clean = fact.replace(/\s+/g, " ").trim(); // one line, normalized whitespace
+    if (!clean)
+        return "[error] nothing to remember (empty fact).";
+    const t = asType(type); // coerce a bad type to "project" so the on-disk format stays parseable
+    let entries = readMemoryTyped();
+    if (entries.some((e) => e.fact === clean))
+        return "Already remembered — no change."; // idempotent
+    entries.push({ type: t, fact: clean });
+    if (entries.length > MAX_ENTRIES)
+        entries = entries.slice(entries.length - MAX_ENTRIES); // drop oldest
+    let body = entries.map((e) => `- [${e.type}] ${e.fact}`).join("\n");
+    while (Buffer.byteLength(HEADER + body, "utf8") > MAX_BYTES && entries.length > 1) {
+        entries.shift(); // still too big — drop the oldest until it fits
+        body = entries.map((e) => `- [${e.type}] ${e.fact}`).join("\n");
+    }
+    fs.mkdirSync(path.dirname(MEMORY_PATH), { recursive: true });
+    fs.writeFileSync(MEMORY_PATH, HEADER + body + "\n", "utf8");
+    return `Remembered (${t}). (${entries.length} fact${entries.length === 1 ? "" : "s"} stored.)`;
+}
+// The tool the model calls to save something worth keeping.
+export const rememberTool = {
+    definition: {
+        type: "function",
+        function: {
+            name: "remember",
+            description: `Save a durable fact to long-term memory (persists across sessions, shown to you at the start of every future session).
+Use it for things still true next time: the build/test command, a gotcha, a convention, a decision and its reason, a user preference, or a correction the user gave you.
+Do NOT use it for transient state (current task, today's bug). Keep each fact to one sentence. Pick the right "type".`,
+            parameters: {
+                type: "object",
+                properties: {
+                    fact: { type: "string", description: "One durable fact, as a single sentence" },
+                    type: { type: "string", enum: [...MEMORY_TYPES], description: "user (who they are/prefs) · feedback (a correction/guidance) · project (a decision/convention/gotcha) · reference (a URL/doc)" },
+                },
+                required: ["fact"],
+            },
+        },
+    },
+    run: (args) => addFact(args.fact ?? "", asType(args.type)),
+};
+// ---- auto-extract -----------------------------------------------------------
+// After a turn, read the conversation and save what's worth keeping. The high-
+// frequency write path from §17 — so memory captures itself instead of relying
+// on the model to remember to call `remember`.
+const EXTRACT_SYSTEM = `You extract DURABLE memories from a slice of a coding-assistant conversation — facts worth carrying into FUTURE sessions.
+Output ONLY a JSON array. Each item: {"type": "...", "fact": "one sentence"}. No prose, no markdown fences.
+"type" is one of:
+- "user": who the user is — role, preferences, how they like to work.
+- "feedback": guidance or a CORRECTION the user gave the assistant. These are the MOST valuable — prioritize any turn where the user corrected or redirected the assistant.
+- "project": a goal, decision, convention, or non-obvious gotcha about THIS project.
+- "reference": a pointer to an external resource (a URL, a doc, a ticket).
+Do NOT save: transient task state, the bug currently being fixed, or anything obvious from reading the code. Keep each fact to one sentence.
+If nothing is worth saving, output [].`;
+// Parse the model's extraction output into typed entries. Lenient: finds the
+// JSON array even if wrapped in prose/fences, drops malformed items. Pure.
+export function parseExtractedMemories(text) {
+    const m = text.match(/\[[\s\S]*\]/); // the first […] — tolerate surrounding chatter
+    if (!m)
+        return [];
+    let arr;
+    try {
+        arr = JSON.parse(m[0]);
+    }
+    catch {
+        return [];
+    }
+    if (!Array.isArray(arr))
+        return [];
+    return arr
+        .filter((x) => !!x && typeof x === "object")
+        .filter((x) => typeof x.fact === "string" && x.fact.trim())
+        .map((x) => ({ type: asType(x.type), fact: String(x.fact).replace(/\s+/g, " ").trim() }));
+}
+// Build the transcript handed to the extractor: the last few user/assistant
+// turns (string content only), each capped, so the extraction stays cheap.
+function buildTranscript(messages) {
+    const turns = messages
+        .filter((m) => (m.role === "user" || m.role === "assistant") && typeof m.content === "string" && m.content.trim())
+        .slice(-12) // recent context is what matters
+        .map((m) => `${m.role}: ${String(m.content).split("\n\n[Referenced files")[0].slice(0, 600)}`);
+    return turns.join("\n\n");
+}
+// Run one extraction pass: a single (cheap) model call, parse, save. Returns the
+// facts it saved. Never throws — a failed extraction must not break the session.
+export async function extractMemories(client, model, messages) {
+    const transcript = buildTranscript(messages);
+    if (!transcript.trim())
+        return [];
+    let text = "";
+    try {
+        const res = await client.chat.completions.create({
+            model,
+            messages: [
+                { role: "system", content: EXTRACT_SYSTEM },
+                { role: "user", content: transcript },
+            ],
+            stream: false,
+        });
+        text = res.choices?.[0]?.message?.content ?? "";
+    }
+    catch {
+        return []; // network/model error — skip silently, try again next turn
+    }
+    const extracted = parseExtractedMemories(text);
+    for (const e of extracted)
+        addFact(e.fact, e.type); // addFact dedups internally
+    return extracted;
+}

package/dist/mentions.js

@@ -0,0 +1,62 @@
+import fs from "node:fs"; // read referenced files
+import path from "node:path"; // resolve mention paths
+import { checkPermission } from "./permissions.js"; // reuse the read_file gate — secret files must never leak in
+// @file mentions: let the user pull a file into the conversation just by naming
+// it — "explain @src/loop.ts" attaches the file's content so the model sees it
+// without a separate read_file round-trip. The point is convenience, but the
+// SAME rule still holds: a secret file (.env, *.pem) must never enter the
+// context. So every mention is routed through the read_file permission gate
+// (Day 4) — if it would deny a read, the mention is refused, not read.
+// @ must start the token (line start or after whitespace) so emails (a@b) and
+// npm scopes inside words don't trigger. The path runs to the next space; we
+// trim trailing sentence punctuation so "see @cart.js." doesn't include the dot.
+const MENTION_RE = /(?:^|\s)@(\S+)/g;
+const MAX_MENTION_BYTES = 100_000; // a referenced file bigger than this is truncated
+// Pull the raw @tokens out of a line (trailing , ; : ! ? ) stripped).
+export function findMentions(line) {
+    const out = [];
+    for (const m of line.matchAll(MENTION_RE)) {
+        const raw = m[1].replace(/[.,;:!?)\]]+$/, ""); // drop trailing punctuation, keep inner dots (cart.js)
+        if (raw)
+            out.push(raw);
+    }
+    return out;
+}
+// Resolve one mention to a file we may attach. Never throws.
+function resolveMention(raw) {
+    const abs = path.resolve(raw);
+    // The gate decides if a read is allowed; a secret file comes back "deny".
+    if (checkPermission("read_file", JSON.stringify({ path: raw })).decision === "deny") {
+        return { raw, path: abs, status: "denied" };
+    }
+    try {
+        const stat = fs.statSync(abs);
+        if (stat.isDirectory())
+            return { raw, path: abs, status: "dir" };
+        let content = fs.readFileSync(abs, "utf8");
+        if (content.length > MAX_MENTION_BYTES)
+            content = content.slice(0, MAX_MENTION_BYTES) + `\n... (truncated, file is ${content.length} chars)`;
+        return { raw, path: abs, status: "ok", content };
+    }
+    catch {
+        return { raw, path: abs, status: "missing" }; // not a file — probably not a reference at all
+    }
+}
+// Expand a user line: find @mentions, attach the readable ones, and refuse the
+// secret ones out loud. Returns the augmented message (file blocks appended) and
+// the mention list (for the REPL to summarize). A line with no resolvable
+// mention is returned unchanged — @tokens that don't name a real file (an email,
+// a stray @) are ignored silently so we don't nag on every "@" in prose.
+export function expandMentions(line) {
+    const mentions = findMentions(line).map(resolveMention);
+    // Only attach files we actually read, and announce refusals (security-relevant).
+    // "missing"/"dir" are dropped silently — likely not file references.
+    const attach = mentions.filter((m) => m.status === "ok" || m.status === "denied");
+    if (!attach.length)
+        return { augmented: line, mentions };
+    const blocks = attach.map((m) => m.status === "ok"
+        ? `--- ${m.raw} ---\n${m.content}`
+        : `--- ${m.raw} (refused: secret file, not included) ---`);
+    const augmented = `${line}\n\n[Referenced files — the user attached these with @mentions]\n${blocks.join("\n\n")}`;
+    return { augmented, mentions };
+}

package/dist/menu.js

@@ -0,0 +1,154 @@
+import readline from "node:readline"; // raw-mode keypress events + the interface to pause
+import { renderMenu, MENU_HINT } from "./ui.js"; // the pure drawing + the footer hint
+import { initFormState, reduceForm, renderForm, collectAnswers } from "./form.js"; // the multi-question form
+// An arrow-key selection menu. The whole point: an approval is one keystroke
+// (↑/↓ then Enter), not "type y, then N, then realize you meant the other".
+// Selecting costs the user less than typing.
+//
+// Coordinating with the session's readline (which owns stdin) is the tricky
+// part: we pause it, switch stdin to raw mode, read keypresses ourselves, then
+// hand stdin back exactly as we found it. The `input` parameter is injected so
+// tests can drive it with a fake stream instead of a real terminal.
+//
+// Returns the chosen index, or -1 if cancelled (Esc / Ctrl+C) or not a TTY —
+// callers treat -1 as "no" (fail closed for an approval).
+export function promptSelect(rl, // the session's line reader, paused while we own the keys
+options, // the choices, top to bottom
+input = process.stdin) {
+    return new Promise((resolve) => {
+        if (!input.isTTY)
+            return resolve(-1); // no interactive selection without a terminal — caller falls back
+        let selected = 0;
+        let done = false;
+        const wasRaw = input.isRaw === true; // the session's readline keeps stdin raw — restore THIS, don't force false
+        // Redraw the menu in place: move the cursor back up over the previous
+        // render (options + the one footer line), clear downward, reprint. The
+        // question above the menu stays put.
+        const lineCount = options.length + 1; // options, plus the hint footer
+        const draw = (first) => {
+            if (!first)
+                process.stdout.write(`\x1b[${lineCount}A`); // up to the menu's top
+            process.stdout.write(`\x1b[J${renderMenu(options, selected)}\n${MENU_HINT}\n`); // clear down, repaint + hint
+        };
+        const finish = (result) => {
+            if (done)
+                return;
+            done = true;
+            input.off("keypress", onKey); // stop listening
+            try {
+                input.setRawMode(wasRaw); // restore the prior mode — forcing false breaks the live readline → it closes → the REPL exits
+            }
+            catch {
+                /* not all streams support it; ignore */
+            }
+            rl.resume(); // the line reader takes over again
+            resolve(result);
+        };
+        const onKey = (_str, key) => {
+            if (!key || done)
+                return;
+            switch (key.name) {
+                case "up":
+                case "k":
+                    selected = (selected - 1 + options.length) % options.length; // wrap around the top
+                    draw(false);
+                    break;
+                case "down":
+                case "j":
+                    selected = (selected + 1) % options.length; // wrap around the bottom
+                    draw(false);
+                    break;
+                case "return":
+                case "enter":
+                    finish(selected); // commit the choice
+                    break;
+                case "escape":
+                    finish(-1); // bail
+                    break;
+                default:
+                    if (key.ctrl && key.name === "c")
+                        finish(-1); // Ctrl+C in raw mode arrives as a keypress, not a signal
+            }
+        };
+        try {
+            rl.pause(); // stop the line reader from turning our keystrokes into lines
+            if (input === process.stdin)
+                readline.emitKeypressEvents(input); // turn raw bytes into named keys (real stdin only)
+            input.setRawMode(true); // keys arrive immediately, no Enter needed
+            input.resume(); // CRUCIAL: rl.pause() paused the stream — resume it or no keypresses reach us (menu hangs)
+            input.on("keypress", onKey);
+            draw(true); // first paint
+        }
+        catch {
+            finish(-1); // anything unexpected in setup → cancel, caller falls back to typing
+        }
+    });
+}
+// The multi-question form (Day 30): the agent asks several questions at once,
+// the user answers each and submits, and we hand back organized answers. Same
+// raw-mode borrow/return dance as promptSelect; the state machine is in form.ts.
+// Returns the answers, or null if cancelled / not a TTY.
+export function promptForm(rl, questions, input = process.stdin) {
+    return new Promise((resolve) => {
+        if (!input.isTTY || !questions.length)
+            return resolve(null); // no form without a terminal or questions
+        let state = initFormState(questions);
+        let done = false;
+        const wasRaw = input.isRaw === true; // restore this on exit, not false (see promptSelect)
+        const lineCount = renderForm(questions, state).split("\n").length; // constant for these questions
+        const draw = (first) => {
+            if (!first)
+                process.stdout.write(`\x1b[${lineCount}A`); // up over the whole form
+            process.stdout.write(`\x1b[J${renderForm(questions, state)}\n`); // clear down, repaint
+        };
+        const finish = (result) => {
+            if (done)
+                return;
+            done = true;
+            input.off("keypress", onKey);
+            try {
+                input.setRawMode(wasRaw); // restore prior mode; forcing false breaks the live readline → REPL exits
+            }
+            catch {
+                /* ignore */
+            }
+            rl.resume();
+            resolve(result);
+        };
+        const onKey = (_str, key) => {
+            if (!key || done)
+                return;
+            if (key.name === "up" || key.name === "k") {
+                state = reduceForm(questions, state, "up").state;
+                draw(false);
+            }
+            else if (key.name === "down" || key.name === "j" || key.name === "tab") {
+                state = reduceForm(questions, state, "down").state;
+                draw(false);
+            }
+            else if (key.name === "return" || key.name === "enter" || key.name === "space") {
+                const next = reduceForm(questions, state, "select");
+                state = next.state;
+                if (next.done)
+                    finish(collectAnswers(questions, state)); // submitted with all answered
+                else
+                    draw(false);
+            }
+            else if (key.name === "escape" || (key.ctrl && key.name === "c")) {
+                finish(null); // cancel
+            }
+        };
+        try {
+            rl.pause();
+            if (input === process.stdin)
+                readline.emitKeypressEvents(input);
+            input.setRawMode(true);
+            input.resume(); // resume the stream rl.pause() paused, or no keypresses reach the form
+            input.on("keypress", onKey);
+            draw(true);
+        }
+        catch {
+            finish(null);
+        }
+    });
+}

package/dist/permissions.js

@@ -80,9 +80,51 @@ function checkBash(command) {
     // Fail closed: a command we don't recognize is a question for the human.
     return { decision: "ask", reason: "unrecognized command", summary };
 }
+// ---- Plan mode (Day 20) ------------------------------------------------------
+// A research-only mode. While it is on, the agent may observe — read files,
+// search, run safe read-only shell — but every tool that mutates the world is
+// blocked, until it presents a plan and the user approves it. The state lives
+// here because the gate is what enforces it; the REPL toggles it with /plan, and
+// the exit_plan_mode tool turns it off once the user approves a plan.
+let planMode = false; // off by default — most sessions never touch it
+export const isPlanMode = () => planMode; // the REPL reads this to mark its prompt
+export const setPlanMode = (on) => { planMode = on; }; // /plan and exit_plan_mode flip it
+// In plan mode, is this call safe — i.e. does it only observe, never mutate?
+// run_bash is decided by its own classifier: a command the gate already rated
+// "allow" (ls, cat, git status) observes; "ask"/"deny" ones (rm, sudo) mutate.
+function planSafe(toolName, verdict) {
+    switch (toolName) {
+        case "read_file":
+        case "search":
+        case "task": // the sub-agent's own calls hit this same gate, still in plan mode
+        case "ask_user": // asking the user a question is safe in plan mode — it doesn't change anything
+        case "skill": // loading a skill's instructions is read-only; what it does is gated per-call
+        case "exit_plan_mode": // the way OUT of plan mode must never be blocked by plan mode
+            return true;
+        case "run_bash":
+            return verdict.decision === "allow"; // only the read-only commands the classifier cleared
+        default:
+            return false; // write_file, edit_file, MCP and unknown tools: all mutate-or-unknown
+    }
+}
 // ---- The single entry point ---------------------------------------------------
-// Called by the loop for EVERY tool call, before anything executes.
+// Called by the loop for EVERY tool call, before anything executes. Plan mode is
+// applied as an outer filter: it can only TIGHTEN the base decision (downgrade a
+// mutating allow/ask to deny), never loosen one — a base "deny" keeps its more
+// specific reason, because deny always wins.
 export function checkPermission(toolName, argsJson) {
+    const base = basePermission(toolName, argsJson);
+    if (planMode && base.decision !== "deny" && !planSafe(toolName, base)) {
+        return {
+            decision: "deny",
+            reason: "plan mode is on — investigate with read-only tools, then call exit_plan_mode to present a plan for the user to approve before you change anything",
+            summary: base.summary,
+        };
+    }
+    return base;
+}
+// The underlying rules, plan-mode-agnostic. Wrapped by checkPermission above.
+function basePermission(toolName, argsJson) {
     // A user-configured tool block beats everything, including built-in allows.
     if (CONFIG.permissions.deny.includes(`tool:${toolName}`)) {
         return { decision: "deny", reason: `tool blocked by your settings ("tool:${toolName}")`, summary: toolName };
@@ -102,6 +144,14 @@ export function checkPermission(toolName, argsJson) {
             // Spawning a sub-agent is orchestration, not action: every tool the
             // sub-agent uses goes through this same gate individually.
             return { decision: "allow", reason: "sub-agent tools are gated individually", summary: "task" };
+        case "ask_user":
+            // Asking the user a question has no side effects — it's the safest thing
+            // the model can do. Never gate it behind an approval prompt.
+            return { decision: "allow", reason: "asks the user, no side effects", summary: "ask_user" };
+        case "skill":
+            // Loading a skill just returns instructions; whatever the skill then DOES
+            // goes through this same gate, call by call. Loading itself is free.
+            return { decision: "allow", reason: "loads instructions, no side effects", summary: "skill" };
         case "read_file": {
             const p = args.path ?? ""; // the file the model wants to read
             if (SECRET_FILE_RE.test(path.resolve(p))) {
@@ -123,10 +173,32 @@ export function checkPermission(toolName, argsJson) {
             }
             return { decision: "ask", reason: "writes to your filesystem", summary: p }; // normal writes need a human yes
         }
-        case "run_bash":
-            return checkBash(args.command ?? ""); // bash gets input-aware analysis
+        case "run_bash": {
+            const verdict = checkBash(args.command ?? ""); // bash gets input-aware analysis
+            // "Don't ask again for run_bash this session" (chosen in the approval menu)
+            // upgrades an ASK to ALLOW — but a hard DENY (rm -rf /, .git, .env…) always
+            // stands. Convenience never overrides the no-fly rules.
+            if (verdict.decision === "ask" && CONFIG.permissions.allow.includes("tool:run_bash")) {
+                return { decision: "allow", reason: "bash pre-approved for this session", summary: verdict.summary };
+            }
+            return verdict;
+        }
+        case "exit_plan_mode": {
+            // Outside plan mode this tool does nothing — let it through silently. In
+            // plan mode it is the approval gate: ask the human, showing the plan, and
+            // only on yes does the tool run and flip plan mode off.
+            if (!planMode)
+                return { decision: "allow", reason: "not in plan mode (no-op)", summary: "exit_plan_mode" };
+            return { decision: "ask", reason: "leave plan mode and start implementing", summary: args.plan ?? "(no plan provided)" };
+        }
         default:
-            // A tool we don't know gets the most suspicious treatment, not the least.
-            return { decision: "ask", reason: "unknown tool", summary: toolName };
+            // Everything else — unknown tools and MCP tools (mcp__server__tool) —
+            // gets the most suspicious treatment, not the least: ask. The user can
+            // pre-approve a trusted MCP tool with "tool:mcp__server__tool" in
+            // settings, or block one with "tool:..." in deny (checked at the top).
+            if (CONFIG.permissions.allow.includes(`tool:${toolName}`)) {
+                return { decision: "allow", reason: "pre-approved by your settings", summary: toolName };
+            }
+            return { decision: "ask", reason: toolName.startsWith("mcp__") ? "external MCP tool" : "unknown tool", summary: toolName };
     }
 }

package/dist/prompt.js

@@ -1,5 +1,6 @@
 import fs from "node:fs"; // to load the optional AGENT.md project memory
 import path from "node:path"; // to resolve it from the current directory
+import { memoryContext } from "./memory.js"; // long-term cross-session memory block
 // The static constitution: identical for every session, every user, every day.
 // NOTHING session-specific belongs here — DeepSeek caches by prefix, and a
 // single changed byte (a date, a username, a cwd) would break the cache for
@@ -37,17 +38,21 @@ Rules:
 // equivalent of Claude Code's CLAUDE.md. Loaded once per session: stable
 // within a session (cache-friendly), different across projects (by design).
 const MEMORY_CAP_CHARS = 8000; // hard cap — a runaway memory file dilutes attention
-// Build the complete system message for this session.
+// Build the complete system message for this session: the constitution, then
+// optional AGENT.md instructions, then optional long-term memory. All three are
+// resolved once per session for a stable, cacheable prefix.
 export function buildSystemMessage() {
+    let msg = SYSTEM_PROMPT;
     const p = path.join(process.cwd(), "AGENT.md"); // only the current directory — V1 keeps lookup simple
-    if (!fs.existsSync(p))
-        return SYSTEM_PROMPT; // no project memory — constitution only
-    const memory = fs.readFileSync(p, "utf8").slice(0, MEMORY_CAP_CHARS); // read and cap
-    // The OVERRIDE/MUST wrapper is deliberate: advisory phrasing gets partial
-    // compliance; imperative wrappers measurably do better.
-    return `${SYSTEM_PROMPT}
-
-The user's project instructions from AGENT.md. These OVERRIDE any default behavior and you MUST follow them exactly as written:
-
-${memory}`;
+    if (fs.existsSync(p)) {
+        const agentMd = fs.readFileSync(p, "utf8").slice(0, MEMORY_CAP_CHARS); // read and cap
+        // The OVERRIDE/MUST wrapper is deliberate: advisory phrasing gets partial
+        // compliance; imperative wrappers measurably do better.
+        msg += `\n\nThe user's project instructions from AGENT.md. These OVERRIDE any default behavior and you MUST follow them exactly as written:\n\n${agentMd}`;
+    }
+    // Long-term memory is BACKGROUND, not an override: facts you established
+    // earlier, to be verified against the code — not hard rules. The different
+    // framing matters (see memory.ts).
+    msg += memoryContext();
+    return msg;
 }