march-cli 0.1.26 → 0.1.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "march-cli",
-  "version": "0.1.26",
+  "version": "0.1.28",
   "description": "March CLI — terminal-native coding agent with context reconstruction",
   "type": "module",
   "main": "./src/main.mjs",

package/src/agent/runtime/remote-ui-client.mjs

@@ -13,7 +13,7 @@ export function createRemoteRuntimeUiClient(peer) {
     retryEnd: (event) => peer.notify("uiEvent", { type: "retry_end", ...event }),
     status: (text) => peer.notify("uiEvent", { type: "status", text }),
     debugLines: (lines) => peer.notify("uiEvent", { type: "debug_lines", lines }),
-    memoryHint: ({ source, hints }) => peer.notify("uiEvent", { type: "memory_hint", source, hints }),
+    recall: ({ source, hints }) => peer.notify("uiEvent", { type: "recall", source, hints }),
     editDiff: (path, diffLines) => peer.notify("uiEvent", { type: "edit_diff", path, diffLines }),
     requestPermission: (request) => peer.call("uiRequest", { type: "permission_request", ...request }),
   };

package/src/agent/runtime/ui-event-bridge.mjs

@@ -50,7 +50,7 @@ export function createRuntimeUiClient(eventBus) {
     retryEnd: (event) => eventBus.emit({ type: "retry_end", ...event }),
     status: (text) => eventBus.emit({ type: "status", text }),
     debugLines: (lines) => eventBus.emit({ type: "debug_lines", lines }),
-    memoryHint: ({ source, hints }) => eventBus.emit({ type: "memory_hint", source, hints }),
+    recall: ({ source, hints }) => eventBus.emit({ type: "recall", source, hints }),
     editDiff: (path, diffLines) => eventBus.emit({ type: "edit_diff", path, diffLines }),
     requestPermission: (request) => eventBus.request({ type: "permission_request", ...request }),
   };
@@ -71,7 +71,7 @@ export function dispatchRuntimeUiEvent(ui, event) {
     case "retry_end": return ui.retryEnd?.(pickRetryEnd(event));
     case "status": return ui.status?.(event.text);
     case "debug_lines": return writeDebugLines(ui, event.lines);
-    case "memory_hint": return ui.memoryHint?.({ source: event.source, hints: event.hints });
+    case "recall": return ui.recall?.({ source: event.source, hints: event.hints });
     case "edit_diff": return ui.editDiff?.(event.path, event.diffLines);
     case "permission_request": return ui.requestPermission?.({ toolName: event.toolName, params: event.params, category: event.category });
     default: return undefined;

package/src/agent/turn/turn-runner.mjs

@@ -42,7 +42,7 @@ export async function runRunnerTurn({
       if (hints.length > 0) {
         midTurnRecallHints.push(...hints);
         queueMidTurnRecallHints(activeSession, hints, logger);
-        ui.memoryHint?.({ source: "assistant", hints });
+        ui.recall?.({ source: "assistant", hints });
       }
     }
   });
@@ -93,7 +93,7 @@ function queueMidTurnRecallHints(session, hints, logger) {
   const content = formatRecallHints("assistant", hints);
   if (!content) return;
   const injected = session.sendCustomMessage?.({
-    customType: "march.memory_hint",
+    customType: "march.recall",
     content,
     display: false,
     details: { source: "assistant" },

package/src/cli/fallback-ui.mjs

@@ -1,6 +1,6 @@
 import { stdout } from "node:process";
 import { extractToolOutput } from "./tool-output.mjs";
-import { formatMemoryHintLines } from "./tui/recall-rendering.mjs";
+import { formatRecallLines } from "./tui/recall-rendering.mjs";
 import { formatToolStartLine } from "./tui/tool-rendering.mjs";
 import { brightBlack, dim, red, green, yellow } from "./tui/ui-theme.mjs";
 
@@ -32,7 +32,7 @@ export function createJsonUI() {
       stdout.write(delta);
     },
     status: () => {},
-    memoryHint: () => {},
+    recall: () => {},
     clearOutput: () => {},
     restoreTranscript: () => {},
     setStatusBar: () => {},
@@ -111,9 +111,9 @@ export function createPlainUI() {
     },
     textDelta: writeText,
     status: (text) => { ensureNewline(); stdout.write(`${brightBlack(`● ${text}`)}\n`); },
-    memoryHint: ({ hints }) => {
+    recall: ({ hints }) => {
       ensureNewline();
-      for (const line of formatMemoryHintLines(hints)) stdout.write(`${brightBlack(line)}\n`);
+      for (const line of formatRecallLines(hints)) stdout.write(`${brightBlack(line)}\n`);
     },
     clearOutput: () => {},
     restoreTranscript: () => {},

package/src/cli/repl-loop.mjs

@@ -27,8 +27,8 @@ export async function runSingleShotPrompt({
   const modePrompt = appendModeReminder(prompt, modeState?.get?.());
   const fullPrompt = appendPromptBlocks(modePrompt, recallBlock, carryoverRecallBlock, shellHints);
   ui.writeln(formatUserDisplayMessage(prompt));
-  ui.memoryHint?.({ source: "user", hints: userRecallHints });
-  if (carryoverRecallHints.length > 0 && !carryoverAlreadyRendered) ui.memoryHint?.({ source: "assistant", hints: carryoverRecallHints });
+  ui.recall?.({ source: "user", hints: userRecallHints });
+  if (carryoverRecallHints.length > 0 && !carryoverAlreadyRendered) ui.recall?.({ source: "assistant", hints: carryoverRecallHints });
   refreshStatusBar.startWorking?.();
   try {
     await runner.runTurn(fullPrompt, prompt, { userRecallHints, currentProject });
@@ -149,8 +149,8 @@ async function runReplTurn({ prompt, args, runner, memoryStore, currentProject,
   const fullPrompt = appendPromptBlocks(modePrompt, recallBlock, carryoverRecallBlock, shellHints);
   try {
     ui.writeln(formatUserDisplayMessage(prompt));
-    ui.memoryHint?.({ source: "user", hints: userRecallHints });
-    if (carryoverRecallHints.length > 0 && !carryoverAlreadyRendered) ui.memoryHint?.({ source: "assistant", hints: carryoverRecallHints });
+    ui.recall?.({ source: "user", hints: userRecallHints });
+    if (carryoverRecallHints.length > 0 && !carryoverAlreadyRendered) ui.recall?.({ source: "assistant", hints: carryoverRecallHints });
     setTurnRunning(true);
     refreshStatusBar.startWorking?.();
     await runner.runTurn(fullPrompt, prompt, { userRecallHints, currentProject });
@@ -178,6 +178,6 @@ function renderPendingAssistantRecallPreview({ runner, ui }) {
   if (runner.engine.hasRenderedPendingAssistantRecallHints?.()) return;
   const hints = runner.engine.peekPendingAssistantRecallHints?.() ?? [];
   if (hints.length === 0) return;
-  ui.memoryHint?.({ source: "assistant", hints });
+  ui.recall?.({ source: "assistant", hints });
   runner.engine.markPendingAssistantRecallHintsRendered?.();
 }

package/src/cli/tui/layout/main-pane-layout.mjs

@@ -10,7 +10,8 @@ export class MainPaneLayout {
   render(width) {
     const safeWidth = Math.max(1, Math.trunc(width));
     const statusTopLines = this.statusBar.renderTop?.(safeWidth) ?? this.statusBar.render(safeWidth);
-    const rawEditorLines = this.editor.render(safeWidth);
+    const editorWidth = this.statusBar.inputContentWidth?.(safeWidth) ?? safeWidth;
+    const rawEditorLines = this.editor.render(Math.max(1, editorWidth));
     const editorLines = this.statusBar.renderInputLines?.(rawEditorLines, safeWidth)
       ?? rawEditorLines.map((line) => this.statusBar.renderInputLine?.(line, safeWidth) ?? line);
     const statusBottomLines = this.statusBar.renderBottom?.(safeWidth) ?? [];

package/src/cli/tui/output/tool-card-renderer.mjs

@@ -1,5 +1,5 @@
 import { visibleWidth } from "@earendil-works/pi-tui";
-import { R, brightBlack, dim, red } from "../ui-theme.mjs";
+import { R, brightBlack, dim, red, warmAmber } from "../ui-theme.mjs";
 
 export function renderToolCardBlock(block, width) {
   const lines = [];
@@ -7,7 +7,7 @@ export function renderToolCardBlock(block, width) {
   const marker = block.state === "running" ? "▶" : block.expanded ? "▾" : "▸";
   const summary = block.summary ? ` · ${block.summary}` : "";
   const head = `${marker} ${block.title}${summary}`;
-  appendCardWrapped(lines, border, (block.isError ? red : dim)(head), width);
+  appendCardWrapped(lines, border, colorToolHead(block)(head), width);
 
   if (block.expanded && block.bodyLines?.length) {
     lines.push(border);
@@ -16,6 +16,12 @@ export function renderToolCardBlock(block, width) {
   return lines;
 }
 
+function colorToolHead(block) {
+  if (block.isError) return red;
+  if (block.name === "memory_open") return warmAmber;
+  return dim;
+}
+
 function appendCardWrapped(lines, border, text, width, indent = "") {
   const prefix = `${border} ${indent}`;
   const contentWidth = Math.max(8, width - visibleWidth(prefix));

package/src/cli/tui/recall-rendering.mjs

@@ -1,8 +1,8 @@
-import { brightBlack, warmAmber } from "./ui-theme.mjs";
+import { brightBlack } from "./ui-theme.mjs";
 
 const RECALL_ICON = "✦";
 
-export function formatMemoryHintLines(hints = []) {
+export function formatRecallLines(hints = []) {
   if (!hints.length) return [];
   const noun = hints.length === 1 ? "note" : "notes";
   return [
@@ -11,11 +11,10 @@ export function formatMemoryHintLines(hints = []) {
   ];
 }
 
-export function writeMemoryHint({ output, hints = [] }) {
-  const lines = formatMemoryHintLines(hints);
-  lines.forEach((line, index) => {
-    if (index === 0) output.writeln(warmAmber(line));
-    else if (line.startsWith("    ")) output.writeln(brightBlack(line));
+export function writeRecall({ output, hints = [] }) {
+  const lines = formatRecallLines(hints);
+  lines.forEach((line) => {
+    if (line.startsWith("    ")) output.writeln(brightBlack(line));
     else output.writeln(line);
   });
 }

package/src/cli/tui/status/status-bar.mjs

@@ -45,6 +45,10 @@ export class StatusBar {
     return [`${left}${line}${right}`, ""];
   }
 
+  inputContentWidth(width) {
+    return maxInputContentWidth(width);
+  }
+
   renderInputLines(lines, width) {
     if (width <= 0) return [""];
     const { left, innerWidth, right } = insetForWidth(width);
@@ -62,9 +66,7 @@ export class StatusBar {
     if (width <= 0) return "";
     const paintWidth = inputPaintWidth(width);
     const prompt = isFirst ? statusBar.prompt(INPUT_PROMPT) : "  ";
-    const promptWidth = visibleWidth(stripAnsi(INPUT_PROMPT));
-    const maxContentWidth = Math.max(0, paintWidth - promptWidth - 2);
-    const content = clipToWidth(line, maxContentWidth);
+    const content = clipToWidth(line, maxInputContentWidth(width));
     return applyInputBackground(padToWidth(`${prompt}${content}`, paintWidth));
   }
 
@@ -108,6 +110,12 @@ function inputPaintWidth(width) {
   return safeWidth > 1 ? safeWidth - 1 : safeWidth;
 }
 
+function maxInputContentWidth(width) {
+  const paintWidth = inputPaintWidth(width);
+  const promptWidth = visibleWidth(stripAnsi(INPUT_PROMPT));
+  return Math.max(0, paintWidth - promptWidth - 2);
+}
+
 function applyInputBackground(line) {
   return `${INPUT_BG}${String(line).replaceAll(R, `${R}${INPUT_BG}`)}${R}`;
 }

package/src/cli/tui/tui-input-controller.mjs

@@ -1,6 +1,6 @@
 import { resolveAttachmentTokens, uniqueAttachmentToken, withLeadingSpace } from "../input/attachment-tokens.mjs";
 
-export function createTuiInputController({ editor, requestRender, historyStore = null }) {
+export function createTuiInputController({ editor, requestRender, historyStore = null, onSubmit = null }) {
   let onSubmitResolve = null;
   const attachmentTokens = new Map();
 
@@ -17,6 +17,7 @@ export function createTuiInputController({ editor, requestRender, historyStore =
           }
           clearSubmitState();
           attachmentTokens.clear();
+          onSubmit?.();
           resolve(resolvedText);
         };
       });

package/src/cli/ui.mjs

@@ -20,7 +20,7 @@ import { createMouseSelectionController } from "./tui/input/mouse-selection-cont
 import { ScreenSelection } from "./tui/selection-screen.mjs";
 import { writeEditDiff } from "./tui/tui-diff-rendering.mjs";
 import { createTuiInputController } from "./tui/tui-input-controller.mjs";
-import { writeMemoryHint } from "./tui/recall-rendering.mjs";
+import { writeRecall } from "./tui/recall-rendering.mjs";
 import { writeToolEnd, writeToolStart } from "./tui/tool-rendering.mjs";
 import { EDITOR_THEME, brightBlack } from "./tui/ui-theme.mjs";
 import { createRenderScheduler } from "./tui/render/render-scheduler.mjs";
@@ -104,12 +104,6 @@ export function createTuiUI({
         if (copyKeyResult) return copyKeyResult;
         const dispatched = keybindingDispatcher.dispatch(data);
         if (dispatched) return dispatched;
-        // When output is scrolled up, the next render has fewer lines.
-        // On new input, reset scroll to tail so the editor stays at bottom.
-        if (output.scrollOffset > 0) {
-          output.resetScroll();
-          requestRender();
-        }
         if (shellDrawer.isInputActive()) {
           shellDrawer.sendInput(data);
           requestRender();
@@ -150,7 +144,12 @@ export function createTuiUI({
     retryStatus.end({ success, attempt, finalError });
   }
 
-  const inputController = createTuiInputController({ editor, requestRender, historyStore });
+  const resetOutputScrollOnSubmit = () => {
+    if (output.scrollOffset <= 0) return;
+    output.resetScroll();
+    requestRender();
+  };
+  const inputController = createTuiInputController({ editor, requestRender, historyStore, onSubmit: resetOutputScrollOnSubmit });
 
   return {
     readline: (_prompt) => {
@@ -205,8 +204,8 @@ export function createTuiUI({
     status: (text) => {
       ensureStarted(); flushStreamDeltas(); retryStatus.stop(); spinnerStatus.stop(); output.setOverlayStatus([brightBlack(`● ${text}`)]); requestRender();
     },
-    memoryHint: ({ hints }) => {
-      ensureStarted(); flushStreamDeltas(); retryStatus.stop(); spinnerStatus.stop(); output.ensureNewline(); writeMemoryHint({ output, hints }); requestRender();
+    recall: ({ hints }) => {
+      ensureStarted(); flushStreamDeltas(); retryStatus.stop(); spinnerStatus.stop(); output.ensureNewline(); writeRecall({ output, hints }); requestRender();
     },
 
     clearOutput: () => {

package/src/context/system-core/base.md

@@ -5,22 +5,31 @@ The user primarily asks for software engineering work: fixing bugs, adding behav
 
 <communication_contract>
 - Be concise and direct. Match the response shape to the task; simple questions get simple answers.
-- Surface assumptions and ambiguity before acting. If intent, constraints, or code organization are unclear, ask or state the uncertainty instead of guessing.
 - Assume users may not see tool calls. Before the first tool call, say in one sentence what you are about to do. While working, give brief updates when you find something important, change direction, or hit a blocker.
 - For multi-step work, checkpoint after meaningful milestones: what changed, what was verified, and what remains.
-- Keep context use bounded. If the task is sprawling or the conversation is losing state, summarize and restart the plan instead of pushing forward blindly.
 - Don't narrate hidden reasoning. State decisions, results, and relevant next steps.
 - End with a brief summary of what you did during the task, including what changed, verification status, and what's next if anything; keep it concise, but don't omit the execution overview.
 - Report outcomes truthfully. If tests fail, checks are skipped, data is ignored, or success is uncertain, say so plainly.
 </communication_contract>
 
+<discussion_contract>
+- For design, brainstorm, mechanism, planning, or ambiguous requests, act as a thinking partner before acting as an implementer.
+- First classify whether the user needs clarification, option exploration, scope splitting, or implementation; do not treat every unclear request as a coding task.
+- Distinguish the proposed solution from the underlying problem; restate the problem before accepting the solution when the user brings a design or implementation idea.
+- Surface assumptions and ambiguity before acting. If intent, constraints, or code organization are unclear, ask or state the uncertainty instead of guessing.
+- Challenge weak, over-engineered, or mis-scoped proposals directly and offer 1-2 concrete alternatives.
+- Ask one focused question at a time; when useful, provide 2-4 distinct options rather than open-ended questionnaires.
+- Keep context use bounded. If the task is sprawling or the conversation is losing state, summarize and restart the plan instead of pushing forward blindly.
+- Do not force discussion when the request is already clear; summarize the decision and move toward the appropriate next step.
+</discussion_contract>
+
 <operating_contract>
 - Default to doing the requested work in the repository, not giving abstract advice.
 - Define the success condition for non-trivial tasks, then iterate until it is actually met or a blocker is clear.
 - Build context from current project facts before editing. Inspect existing code, exports, direct callers, shared utilities, and conventions first.
 - Tool call history may be compacted when context is rebuilt. After receiving a new user reply, treat previously read file contents as unavailable or potentially stale, and re-read the key files before editing, explaining, or making design decisions based on them.
-- Keep the change scoped to the request. Don't add features, refactors, abstractions, files, or docs beyond what's needed.
-- Prefer the simplest correct solution. Three similar lines beats a premature abstraction; no speculative code and no half-finished implementations.
+- Keep the requested outcome scoped. Do not expand product behavior, refactors, files, or docs beyond the task, but allow structural changes when they are needed to keep responsibility boundaries correct.
+- Prefer the clearest correct solution. Small duplication is acceptable when it avoids premature abstraction, but do not use local simplicity as an excuse to add scattered conditionals or bypass the proper abstraction boundary.
 - When existing patterns conflict, do not blend them. Choose the newer, better-tested, or more local convention, state why, and note the other as cleanup if relevant.
 - Follow repository conventions even when another style seems preferable. Raise harmful conventions explicitly; don't silently introduce a second pattern.
 - Use model judgment only where judgment is needed, such as classification, drafting, summarization, or extracting from unstructured text. Deterministic routing, retry, status-code handling, and data transforms belong in code.
@@ -29,6 +38,26 @@ The user primarily asks for software engineering work: fixing bugs, adding behav
 - Default to add one short comment when the WHY is helpful.
 </operating_contract>
 
+<implementation_principles>
+- Prefer minimal coherent changes, not local minimal patches. The goal is correct responsibility boundaries, self-consistent behavior, and contained future complexity, not the fewest edited lines.
+- Before adding a branch for a new scenario, identify the variation dimension: external input shape, provider/model/tool behavior, business rule, platform boundary, or a new responsibility in the main flow.
+- Keep the main flow as stable orchestration. It should express steps and data movement, not accumulate provider, platform, mode, or format details.
+- Put compatibility logic only at real boundaries such as external APIs, historical data, platform differences, and user input. Do not use compatibility branches to hide missing internal abstractions.
+- When a condition represents a growing variation dimension, move it to the proper boundary with a registry, strategy, adapter, configuration mapping, or focused module instead of adding another inline if.
+- Do not keep parallel internal paths for half-compatible behavior. If the old path is no longer the right model, migrate to one unified model unless an external compatibility window truly requires both.
+- Implementation priority is: correct responsibility boundary > self-consistent system behavior > simple main flow > fewer local code changes.
+</implementation_principles>
+
+<coherence_contract>
+- After non-trivial changes, perform a post-change coherence check before finalizing or committing.
+- Re-state what the system is now, not only what changed locally.
+- Check whether responsibility boundaries became clearer or more confused; fix or surface boundary drift.
+- Look for duplicated rules, conflicting instructions, hidden priority changes, and parallel paths that now represent the same responsibility.
+- Notice module, prompt, or flow expansion; if one area starts absorbing too many responsibilities, either refactor within scope or call it out as follow-up.
+- Do not treat tests as a substitute for coherence. Tests verify behavior; coherence checks verify the system model.
+- In the final summary for architecture, prompt, context, memory, tool, or provider changes, briefly report the coherence result.
+</coherence_contract>
+
 <safety_contract>
 - Local, reversible actions such as reading files, editing files, and running tests are normally okay.
 - Confirm before actions that are hard to reverse, destructive, outward-facing, or affect shared state: deleting user work, force operations, dependency downgrades, CI/CD changes, pushing code, creating PRs/issues, sending messages, or publishing content to external services.
@@ -62,13 +91,14 @@ The user primarily asks for software engineering work: fixing bugs, adding behav
 </git_contract>
 
 <memory_system>
-- [memory_hint source="..."] blocks in recent_chat are lightweight recall hints matched from prior thinking output. Treat them as possibly relevant pointers, not as complete facts.
-- If a memory hint may help the current task, use memory_open(id) to read the full memory before relying on it. Ignore hints that are clearly unrelated or too low-value for the task.
+- [recall source="..."] blocks in recent_chat are lightweight recall hints matched from prior thinking output. Treat them as possibly relevant pointers, not as complete facts.
+- A recall hint's description may record key operational constraints, including when the full memory must be opened; factor those constraints into relevance before acting.
+- If a recall hint may help the current task, use memory_open(id) to read the full memory before relying on it. Ignore hints that are clearly unrelated or too low-value for the task.
 - Use memory_search(query) for full-text search across all memories.
 - To edit an existing memory, use memory_open(id) to get its path, then edit_file with mode="patch" for targeted edits.
 - Use memory_save() to create memories or update whole fields. Before creating a new memory, first search/open related memories and merge updates into an existing memory when they share the same topic, project, or decision thread; prefer modifying the existing memory file over creating a scattered new one. Tags are the primary retrieval key for future recall. Prefer lowercase kebab-case tags like 'march-cli', 'tooling', 'permissions'.
 - When learning multiple related external workflows or skills, maintain memory as an evolving domain library: start with the specific source name when only one item exists, then rename and rewrite the memory title/description as the scope grows; merge new related learnings into the same memory, preserving each source's unique traits while distilling reusable principles.
 - Distinguish "migrating a Skill to memory" from "learning a Skill": migration preserves the complete Skill folder under memory_root/skills/ and creates a memory entry as its index; that memory should describe what the Skill is for and reference the copied Skill folder path so future recall knows how to use it. Learning only reads and internalizes the Skill's methods, scenarios, and principles into ordinary memory without copying source files. Infer the action from the user's wording, and ask when ambiguous.
-- Unlike memory hints, this system-core center is always visible in every model call. Only update the center for instructions that must always be followed; use memory for contextual, project-specific, or recall-dependent knowledge.
+- Unlike recall blocks, this system-core center is always visible in every model call. Only update the center for instructions that must always be followed; use memory for contextual, project-specific, or recall-dependent knowledge.
 - If execution takes a meaningful detour, create or update a memory after the task. A detour means the initial plan or assumption failed, multiple approaches were tried, and the final successful path contains reusable project knowledge. Record the failed assumption, what was tried, and the successful approach. Prefer updating an existing related memory over creating a new one.
 </memory_system>

package/src/memory/markdown/markdown-recall.mjs

@@ -2,7 +2,7 @@ import { expandTags, normalizeText } from "./markdown-format.mjs";
 
 export function formatRecallHints(source, hints = []) {
   if (!hints.length) return "";
-  const lines = [`[memory_hint source="${source}"]`];
+  const lines = [`[recall source="${source}"]`];
   for (const hint of hints) {
     lines.push(`- ${hint.id} | ${hint.name} | ${hint.description}`);
   }

package/src/memory/markdown-store.mjs

@@ -59,7 +59,7 @@ export class MarkdownMemoryStore {
           continue;
         }
         if (!parsed.frontmatter.description) {
-          diagnostics.push({ type: "warning", path, message: "Memory file is missing description; excluded from memory hint recall" });
+          diagnostics.push({ type: "warning", path, message: "Memory file is missing description; excluded from passive recall" });
         }
         const tags = normalizeTags(parsed.frontmatter.tags ?? []);
         const entry = {

package/src/memory/markdown-tools.mjs

@@ -37,9 +37,9 @@ export function createMarkdownMemoryTools(store, { remoteSources = [] } = {}) {
     defineTool({
       name: "memory_open",
       label: "Memory Open",
-      description: "Open a Markdown memory by id or by path. Use this after memory hint or memory_search when you need more context. Local memories may be edited with edit_file; remote memories are read-only.",
+      description: "Open a Markdown memory by id or by path. Use this after recall hint or memory_search when you need more context. Local memories may be edited with edit_file; remote memories are read-only.",
       parameters: Type.Object({
-        id: Type.Optional(Type.String({ description: "Local memory id from memory hint, e.g. mem_..." })),
+        id: Type.Optional(Type.String({ description: "Local memory id from recall hint, e.g. mem_..." })),
         source: Type.Optional(Type.String({ description: "Memory source: omitted/local or a remote memory name" })),
         path: Type.Optional(Type.String({ description: "Path returned by memory_search" })),
         line: Type.Optional(Type.Number({ description: "Open around this 1-based line number" })),
@@ -70,13 +70,13 @@ export function createMarkdownMemoryTools(store, { remoteSources = [] } = {}) {
       name: "memory_save",
       label: "Memory Save",
       description:
-        "Create a Markdown memory or update whole fields on an existing memory. For targeted edits to an existing memory body or frontmatter, use memory_open to get the path, then edit_file. Before creating a new memory, merge related updates into an existing memory when they share the same topic or decision thread. New memories require name, description, body, and at least one tag because memory hints only use tags. When updating by id, omitted fields keep their existing values; passing tags replaces the full tag list.",
+        "Create a Markdown memory or update whole fields on an existing memory. For targeted edits to an existing memory body or frontmatter, use memory_open to get the path, then edit_file. Before creating a new memory, merge related updates into an existing memory when they share the same topic or decision thread. New memories require name, description, body, and at least one tag because recall hints only use tags. When updating by id, omitted fields keep their existing values; passing tags replaces the full tag list.",
       parameters: Type.Object({
         id: Type.Optional(Type.String({ description: "Existing memory id to update. Omit to create a new memory." })),
         name: Type.Optional(Type.String({ description: "Memory name. Required when creating." })),
-        description: Type.Optional(Type.String({ description: "Short natural-language summary shown in memory hint. Required when creating." })),
+        description: Type.Optional(Type.String({ description: "Short natural-language summary shown in recall hint. Required when creating." })),
         body: Type.Optional(Type.String({ description: "Markdown memory body. Required when creating." })),
-        tags: Type.Optional(Type.Array(Type.String(), { description: "Tags used for memory hint. Required and non-empty when creating; replaces tags when updating. Prefer stable retrieval keys: project name, technology, feature/domain, user/person, and decision topic. Use lowercase kebab-case when possible. Examples: ['march-cli', 'tooling', 'permissions'], ['memory', 'sqlite-index']." })),
+        tags: Type.Optional(Type.Array(Type.String(), { description: "Tags used for recall hint. Required and non-empty when creating; replaces tags when updating. Prefer stable retrieval keys: project name, technology, feature/domain, user/person, and decision topic. Use lowercase kebab-case when possible. Examples: ['march-cli', 'tooling', 'permissions'], ['memory', 'sqlite-index']." })),
       }),
       execute: async (_toolCallId, params) => {
         try {