@agentprojectcontext/apx 1.0.3

package/src/cli/commands/config.js

@@ -0,0 +1,56 @@
+import { http } from "../http.js";
+import { resolveProjectId } from "./project.js";
+
+function parseValue(raw) {
+  // best-effort: try JSON first (covers numbers, bools, objects, arrays, null,
+  // and quoted strings). If that fails, treat as a literal string.
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return raw;
+  }
+}
+
+export async function cmdConfigShow(args) {
+  const pid = await resolveProjectId(args?.flags?.project);
+  const data = await http.get(`/projects/${pid}/config`);
+  if (args.flags.effective) {
+    process.stdout.write(JSON.stringify(data.effective, null, 2) + "\n");
+    return;
+  }
+  // `--only-overrides` shows just .apc/config.json contents.
+  // (Was previously `--project` but that collided with the global --project
+  // selector flag.)
+  if (args.flags["only-overrides"]) {
+    process.stdout.write(JSON.stringify(data.project_only, null, 2) + "\n");
+    return;
+  }
+  console.log(`# .apc/config.json (project-only overrides)`);
+  console.log(`# path: ${data.project_config_path}`);
+  console.log("");
+  console.log(JSON.stringify(data.project_only, null, 2));
+  console.log("");
+  console.log(`# effective (global merged with project)`);
+  console.log("");
+  console.log(JSON.stringify(data.effective, null, 2));
+}
+
+export async function cmdConfigSet(args) {
+  const key = args._[0];
+  const valueRaw = args._.slice(1).join(" ");
+  if (!key || !valueRaw) {
+    throw new Error('apx config set: usage: apx config set <key.path> <value>');
+  }
+  const pid = await resolveProjectId(args?.flags?.project);
+  const value = parseValue(valueRaw);
+  await http.patch(`/projects/${pid}/config`, { set: { [key]: value } });
+  console.log(`set ${key} = ${JSON.stringify(value)}`);
+}
+
+export async function cmdConfigUnset(args) {
+  const key = args._[0];
+  if (!key) throw new Error("apx config unset: usage: apx config unset <key.path>");
+  const pid = await resolveProjectId(args?.flags?.project);
+  await http.patch(`/projects/${pid}/config`, { unset: [key] });
+  console.log(`unset ${key}`);
+}

package/src/cli/commands/daemon.js

@@ -0,0 +1,148 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { ensureDaemon, http } from "../http.js";
+
+const PID_PATH = path.join(os.homedir(), ".apx", "daemon.pid");
+const LOG_PATH = path.join(os.homedir(), ".apx", "daemon.log");
+
+// ── ANSI helpers ─────────────────────────────────────────────────────────────
+const c = {
+  reset:  "\x1b[0m",
+  bold:   "\x1b[1m",
+  dim:    "\x1b[2m",
+  green:  "\x1b[32m",
+  red:    "\x1b[31m",
+  yellow: "\x1b[33m",
+  cyan:   "\x1b[36m",
+  white:  "\x1b[97m",
+  gray:   "\x1b[90m",
+};
+
+const fmt = {
+  bold:   (s) => `${c.bold}${s}${c.reset}`,
+  dim:    (s) => `${c.dim}${s}${c.reset}`,
+  green:  (s) => `${c.green}${s}${c.reset}`,
+  red:    (s) => `${c.red}${s}${c.reset}`,
+  yellow: (s) => `${c.yellow}${s}${c.reset}`,
+  cyan:   (s) => `${c.cyan}${s}${c.reset}`,
+  gray:   (s) => `${c.gray}${s}${c.reset}`,
+  kv:     (k, v) => `  ${c.gray}${k.padEnd(10)}${c.reset}  ${v}`,
+};
+
+function uptime(s) {
+  if (s < 60)   return `${s}s`;
+  if (s < 3600) return `${Math.floor(s / 60)}m ${s % 60}s`;
+  return `${Math.floor(s / 3600)}h ${Math.floor((s % 3600) / 60)}m`;
+}
+
+function debugRaw(label, data) {
+  console.log(fmt.gray(`\n── debug: ${label} ──`));
+  console.log(fmt.gray(JSON.stringify(data, null, 2)));
+}
+
+// ── Commands ──────────────────────────────────────────────────────────────────
+
+export async function cmdDaemonStart(args = {}) {
+  const debug = args.flags?.debug;
+  await ensureDaemon();
+  const status = await http.get("/health");
+  if (debug) debugRaw("/health", status);
+  console.log(
+    `\n  ${fmt.green("●")} ${fmt.bold("apx daemon")} ${fmt.dim("v" + status.version)}` +
+    `  ${fmt.gray("·")}  ${fmt.cyan("port")} ${status.port ?? (process.env.APX_PORT || 7430)}` +
+    `  ${fmt.gray("·")}  ${fmt.cyan("uptime")} ${uptime(status.uptime_s)}\n`
+  );
+}
+
+export async function cmdDaemonStatus(args = {}) {
+  const debug = args.flags?.debug;
+  const port = process.env.APX_PORT || 7430;
+
+  if (!(await http.ping())) {
+    console.log(
+      `\n  ${fmt.red("○")} ${fmt.bold("apx daemon")}  ${fmt.dim("stopped")}` +
+      `  ${fmt.gray("(no process on port " + port + ")")}\n`
+    );
+    process.exit(1);
+  }
+
+  const h        = await http.get("/health",   { autoStart: false });
+  const projects = await http.get("/projects", { autoStart: false });
+  const pid      = fs.existsSync(PID_PATH) ? fs.readFileSync(PID_PATH, "utf8").trim() : "?";
+
+  if (debug) {
+    debugRaw("/health",   h);
+    debugRaw("/projects", projects);
+  }
+
+  console.log(
+    `\n  ${fmt.green("●")} ${fmt.bold("apx daemon")} ${fmt.dim("v" + h.version)}  ${fmt.green("running")}`
+  );
+  console.log(fmt.kv("pid",     fmt.cyan(pid)));
+  console.log(fmt.kv("port",    fmt.cyan(port)));
+  console.log(fmt.kv("uptime",  fmt.cyan(uptime(h.uptime_s))));
+
+  if (projects.length === 0) {
+    console.log(fmt.kv("projects", fmt.dim("none registered")));
+  } else {
+    console.log(fmt.kv("projects", ""));
+    for (const p of projects) {
+      const agents = `${p.agents} agent${p.agents !== 1 ? "s" : ""}`;
+      console.log(
+        `    ${fmt.cyan("·")} ${fmt.bold(p.path)}  ${fmt.gray(agents)}`
+      );
+    }
+  }
+  console.log();
+}
+
+export async function cmdDaemonStop(args = {}) {
+  const debug = args.flags?.debug;
+
+  if (!(await http.ping())) {
+    console.log(`\n  ${fmt.yellow("○")} ${fmt.bold("apx daemon")}  ${fmt.dim("not running")}\n`);
+    return;
+  }
+
+  try {
+    const res = await http.post("/admin/shutdown", undefined, { autoStart: false });
+    if (debug) debugRaw("/admin/shutdown", res);
+    console.log(`\n  ${fmt.red("○")} ${fmt.bold("apx daemon")}  ${fmt.dim("stopped")}\n`);
+  } catch {
+    if (fs.existsSync(PID_PATH)) {
+      try {
+        const pid = parseInt(fs.readFileSync(PID_PATH, "utf8"), 10);
+        if (pid) {
+          process.kill(pid);
+          console.log(`\n  ${fmt.red("○")} ${fmt.bold("apx daemon")}  ${fmt.dim(`stopped (pid ${pid})`)}\n`);
+          return;
+        }
+      } catch {}
+    }
+    console.log(`\n  ${fmt.yellow("○")} ${fmt.bold("apx daemon")}  ${fmt.dim("not running")}\n`);
+  }
+}
+
+export function cmdDaemonLogs(args) {
+  const debug = args.flags?.debug;
+  if (!fs.existsSync(LOG_PATH)) {
+    console.log(fmt.gray(`  (no log file at ${LOG_PATH})`));
+    return;
+  }
+  const tail  = args.flags?.tail ? parseInt(args.flags.tail, 10) : 50;
+  const lines = fs.readFileSync(LOG_PATH, "utf8").split("\n");
+  const slice = lines.slice(-tail - 1).filter(Boolean);
+
+  if (debug) console.log(fmt.gray(`  log: ${LOG_PATH}  (last ${tail} lines)\n`));
+
+  for (const line of slice) {
+    // dim timestamps, highlight ERROR/WARN
+    const colored = line
+      .replace(/^(\d{4}-\d\d-\d\dT[\d:.Z]+)/, (m) => fmt.gray(m))
+      .replace(/\bERROR\b/g, fmt.red("ERROR"))
+      .replace(/\bWARN\b/g,  fmt.yellow("WARN"))
+      .replace(/\bINFO\b/g,  fmt.cyan("INFO"));
+    console.log(colored);
+  }
+}

package/src/cli/commands/exec.js

@@ -0,0 +1,56 @@
+import { http } from "../http.js";
+import { resolveProjectId } from "./project.js";
+
+function readStdinSync() {
+  if (process.stdin.isTTY) return "";
+  const chunks = [];
+  const buf = Buffer.alloc(65536);
+  try {
+    while (true) {
+      const n = require("node:fs").readSync(0, buf, 0, buf.length);
+      if (!n) break;
+      chunks.push(buf.slice(0, n).toString("utf8"));
+    }
+  } catch {}
+  return chunks.join("");
+}
+
+export async function cmdExec(args) {
+  const slug = args._[0];
+  if (!slug) throw new Error("apx exec: usage: apx exec <agent> \"<prompt>\"  [--model <id>]");
+  let prompt = args._.slice(1).join(" ").trim();
+  if (!prompt || prompt === "-") {
+    const fs = await import("node:fs");
+    if (!process.stdin.isTTY) {
+      const chunks = [];
+      const buf = Buffer.alloc(65536);
+      try {
+        while (true) {
+          const n = fs.readSync(0, buf, 0, buf.length);
+          if (!n) break;
+          chunks.push(buf.slice(0, n).toString("utf8"));
+        }
+      } catch {}
+      prompt = chunks.join("").trim();
+    }
+  }
+  if (!prompt) throw new Error("apx exec: prompt is empty (pass as args or via stdin)");
+
+  const pid = await resolveProjectId(args?.flags?.project);
+  const body = { prompt };
+  if (args.flags.model && args.flags.model !== true) body.model = args.flags.model;
+  if (args.flags.temperature) body.temperature = parseFloat(args.flags.temperature);
+  if (args.flags["max-tokens"]) body.maxTokens = parseInt(args.flags["max-tokens"], 10);
+
+  const result = await http.post(
+    `/projects/${pid}/agents/${slug}/exec`,
+    body
+  );
+
+  process.stdout.write(result.text + "\n");
+  if (process.stderr.isTTY || args.flags.verbose) {
+    process.stderr.write(
+      `\n— ${result.engine} | in=${result.usage?.input_tokens || "?"} out=${result.usage?.output_tokens || "?"} | conv=${result.conversation.id}\n`
+    );
+  }
+}

package/src/cli/commands/identity.js

@@ -0,0 +1,146 @@
+import readline from "node:readline";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { readIdentity, writeIdentity } from "../../core/identity.js";
+
+function ask(rl, question, defaultVal) {
+  return new Promise((resolve) => {
+    const hint = defaultVal ? ` (${defaultVal})` : "";
+    rl.question(`${question}${hint}: `, (ans) => {
+      resolve(ans.trim() || defaultVal || "");
+    });
+  });
+}
+
+function askYN(rl, question, defaultYes = false) {
+  const hint = defaultYes ? "Y/n" : "y/N";
+  return new Promise((resolve) => {
+    rl.question(`${question} [${hint}]: `, (ans) => {
+      const a = ans.trim().toLowerCase();
+      if (!a) return resolve(defaultYes);
+      resolve(a === "y" || a === "yes" || a === "s" || a === "si" || a === "sí");
+    });
+  });
+}
+
+const CLAUDE_SETTINGS_PATH = path.join(os.homedir(), ".claude", "settings.json");
+
+function setupClaudePermissions() {
+  try {
+    let existing = {};
+    if (fs.existsSync(CLAUDE_SETTINGS_PATH)) {
+      existing = JSON.parse(fs.readFileSync(CLAUDE_SETTINGS_PATH, "utf8"));
+    }
+    const updated = {
+      ...existing,
+      permissions: {
+        ...(existing.permissions || {}),
+        allow: [
+          ...(existing.permissions?.allow || []),
+          "Bash(*)",
+          "Read(*)",
+          "Write(*)",
+          "Edit(*)",
+        ].filter((v, i, arr) => arr.indexOf(v) === i),
+      },
+    };
+    fs.mkdirSync(path.dirname(CLAUDE_SETTINGS_PATH), { recursive: true });
+    fs.writeFileSync(CLAUDE_SETTINGS_PATH, JSON.stringify(updated, null, 2) + "\n");
+    return true;
+  } catch (e) {
+    return e.message;
+  }
+}
+
+// apx identity           — show
+// apx identity set       — interactive or --name/--owner/--context/--language flags
+// apx identity wizard    — full onboarding (called on first run)
+export async function cmdIdentity(args) {
+  const sub = args._[0];
+
+  if (!sub || sub === "show") {
+    const id = readIdentity();
+    if (!id) {
+      console.log("No identity configured. Run: apx identity wizard");
+      return;
+    }
+    console.log("");
+    console.log(`  Agent name  : ${id.agent_name}`);
+    console.log(`  Personality : ${id.personality || "(not set)"}`);
+    console.log(`  Owner       : ${id.owner_name}`);
+    console.log(`  Context     : ${id.owner_context || "(not set)"}`);
+    console.log(`  Language    : ${id.language || "(auto-detect)"}`);
+    console.log(`  Last wakeup : ${id.last_wakeup || "(never)"}`);
+    console.log(`  File        : ~/.apx/identity.json`);
+    console.log("");
+    return;
+  }
+
+  if (sub === "set") {
+    const fields = {};
+    if (args.flags.name && args.flags.name !== true) fields.agent_name = args.flags.name;
+    if (args.flags.owner && args.flags.owner !== true) fields.owner_name = args.flags.owner;
+    if (args.flags.context && args.flags.context !== true) fields.owner_context = args.flags.context;
+    if (args.flags.personality && args.flags.personality !== true) fields.personality = args.flags.personality;
+    if (args.flags.language && args.flags.language !== true) fields.language = args.flags.language;
+
+    if (Object.keys(fields).length === 0) {
+      console.log("Usage: apx identity set --name <name> --owner <name> --context <text> --personality <text> --language <lang>");
+      return;
+    }
+
+    const id = writeIdentity(fields);
+    console.log("Identity updated:");
+    for (const [k, v] of Object.entries(fields)) console.log(`  ${k}: ${v}`);
+    if (id.last_wakeup) {
+      writeIdentity({ last_wakeup: null });
+      console.log("  (wakeup cooldown reset — next daemon start will send a new message)");
+    }
+    return;
+  }
+
+  if (sub === "wizard") {
+    await runWizard();
+    return;
+  }
+
+  throw new Error(`unknown identity subcommand: ${sub}`);
+}
+
+export async function runWizard() {
+  const existing = readIdentity() || {};
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+
+  console.log("\n  APX Identity Setup\n");
+  console.log("  This defines who the agent is and who it works for.");
+  console.log("  Used for wake-up messages and agent self-description.\n");
+
+  const agent_name    = await ask(rl, "  Agent name", existing.agent_name || "APX");
+  const personality   = await ask(rl, "  Personality (comma-separated traits)", existing.personality || "direct, curious, helpful");
+  const owner_name    = await ask(rl, "  Your name", existing.owner_name || "");
+  const owner_context = await ask(rl, "  What are you building / working on", existing.owner_context || "");
+  const language      = await ask(rl, "  Language for agent messages (e.g. Spanish, English)", existing.language || "Spanish (Español)");
+
+  console.log("\n  Claude Code permissions");
+  console.log("  APX can configure Claude Code to allow terminal commands without prompts.");
+  console.log("  This adds Bash(*), Read(*), Write(*), Edit(*) to ~/.claude/settings.json\n");
+
+  const setupPerms = await askYN(rl, "  Set up Claude Code terminal permissions now?", false);
+
+  rl.close();
+
+  const id = writeIdentity({ agent_name, personality, owner_name, owner_context, language, last_wakeup: null });
+  console.log(`\n  Identity saved to ~/.apx/identity.json`);
+
+  if (setupPerms) {
+    const result = setupClaudePermissions();
+    if (result === true) {
+      console.log(`  Claude Code permissions updated at ~/.claude/settings.json`);
+    } else {
+      console.log(`  Could not update Claude Code settings: ${result}`);
+    }
+  }
+
+  console.log(`  ${id.agent_name} is ready. Restart the daemon to send a wake-up message.\n`);
+}

package/src/cli/commands/init.js

@@ -0,0 +1,23 @@
+import path from "node:path";
+import { initApf } from "../../core/scaffold.js";
+
+export function cmdInit(args) {
+  const dir = args._[0] || ".";
+  const name = args.flags.name === true ? undefined : args.flags.name;
+  const result = initApf(dir, { name });
+
+  console.log(`Initialized APC project at ${result.root}`);
+  console.log(`  ${path.relative(process.cwd(), result.agentsMd)}`);
+  console.log(`  ${path.relative(process.cwd(), result.projectJson)}`);
+
+  if (result.pendingMigration?.length > 0) {
+    console.log(`\napx: existing context files detected:`);
+    for (const { file, label } of result.pendingMigration) {
+      console.log(`  ${file.padEnd(44)} ${label}`);
+    }
+    console.log(`\n  .apc/migrate.md written.`);
+    console.log(`  Open this project in your AI assistant — it will offer to migrate.`);
+  } else {
+    console.log(`\nNext: apx agent add <slug> --role <role> --model <model>`);
+  }
+}

package/src/cli/commands/mcp.js

@@ -0,0 +1,147 @@
+import { http } from "../http.js";
+import { resolveProjectId } from "./project.js";
+
+export async function cmdMcpList(args = {}) {
+  const pid = await resolveProjectId(args?.flags?.project);
+  const mcps = await http.get(`/projects/${pid}/mcps`);
+  if (mcps.length === 0) {
+    console.log("(no MCPs registered for this project)");
+    return;
+  }
+  console.log("NAME".padEnd(24) + " EN " + "SOURCE".padEnd(8) + " TRANSPORT  COMMAND/URL");
+  for (const m of mcps) {
+    const target = m.transport === "http"
+      ? m.url
+      : (m.command || "") + (m.args?.length ? " " + m.args.join(" ") : "");
+    console.log(
+      m.name.padEnd(24) + " " +
+      (m.enabled ? "✓" : "✗").padEnd(2) + " " +
+      (m.source || "apc").padEnd(8) + " " +
+      (m.transport || "stdio").padEnd(10) + " " +
+      target
+    );
+  }
+}
+
+export async function cmdMcpAdd(args) {
+  const name = args._[0];
+  if (!name) throw new Error("apx mcp add: missing <name>");
+  const command = args.flags.command;
+  if (!command || command === true) throw new Error("apx mcp add: --command required");
+
+  // Args after `--` go to the MCP. `args._` already excludes the `--` separator
+  // when our parser strips it. We treat anything in args._ after [0] as args.
+  const mcpArgs = args._.slice(1);
+
+  const env = {};
+  if (args.flags.env) {
+    const entries = Array.isArray(args.flags.env) ? args.flags.env : [args.flags.env];
+    for (const e of entries) {
+      const [k, ...rest] = String(e).split("=");
+      env[k] = rest.join("=");
+    }
+  }
+
+  const pid = await resolveProjectId(args?.flags?.project);
+  const result = await http.post(`/projects/${pid}/mcps`, {
+    name,
+    command,
+    args: mcpArgs,
+    env,
+    enabled: true,
+  });
+  console.log(`Added MCP "${result.name}"`);
+}
+
+export async function cmdMcpRemove(args) {
+  const name = args._[0];
+  if (!name) throw new Error("apx mcp remove: missing <name>");
+  const pid = await resolveProjectId(args?.flags?.project);
+  await http.delete(`/projects/${pid}/mcps/${name}`);
+  console.log(`Removed MCP "${name}"`);
+}
+
+export async function cmdMcpEnable(args) {
+  await toggleEnabled(args, true);
+}
+export async function cmdMcpDisable(args) {
+  await toggleEnabled(args, false);
+}
+
+async function toggleEnabled(args, enabled) {
+  const name = args._[0];
+  if (!name) throw new Error(`apx mcp ${enabled ? "enable" : "disable"}: missing <name>`);
+  const pid = await resolveProjectId(args?.flags?.project);
+  const all = await http.get(`/projects/${pid}/mcps`);
+  const m = all.find((x) => x.name === name);
+  if (!m) throw new Error(`MCP "${name}" not registered`);
+  await http.post(`/projects/${pid}/mcps`, {
+    name: m.name,
+    command: m.command,
+    args: m.args,
+    env: m.env,
+    enabled,
+  });
+  console.log(`${enabled ? "Enabled" : "Disabled"} MCP "${name}"`);
+}
+
+export async function cmdMcpRun(args) {
+  const name = args._[0];
+  const tool = args._[1];
+  if (!name || !tool) throw new Error("apx mcp run: usage: apx mcp run <name> <tool> [<json-args>]");
+  let params = {};
+  if (args._[2]) {
+    try {
+      params = JSON.parse(args._[2]);
+    } catch (e) {
+      throw new Error(`invalid JSON args: ${e.message}`);
+    }
+  }
+  const pid = await resolveProjectId(args?.flags?.project);
+  const result = await http.post(`/projects/${pid}/mcps/${name}/call`, { tool, params });
+  process.stdout.write(JSON.stringify(result.result, null, 2) + "\n");
+}
+
+export async function cmdMcpTools(args) {
+  const name = args._[0];
+  if (!name) throw new Error("apx mcp tools: missing <name>");
+  // Daemon doesn't have a dedicated tools/list endpoint yet; we'd extend it in v0.2.
+  // For now, print a hint:
+  console.log(`(apx mcp tools — list of tools/list will arrive in v0.2)`);
+  console.log(`To call a tool: apx mcp run ${name} <tool> '<json>'`);
+}
+
+export async function cmdMcpCheck(args = {}) {
+  const pid = await resolveProjectId(args?.flags?.project);
+  const data = await http.get(`/projects/${pid}/mcps/check`);
+
+  console.log("Source files:");
+  for (const s of data.sources) {
+    console.log(`  ${s.present ? "✓" : "·"} ${s.id.padEnd(8)} ${s.file}`);
+  }
+  console.log("");
+
+  if (data.entries.length === 0) {
+    console.log("(no MCPs in any source)");
+  } else {
+    console.log("Active entries (after merge):");
+    console.log("  " + "NAME".padEnd(24) + " SOURCE   TRANSPORT  EN");
+    for (const m of data.entries) {
+      console.log(
+        "  " + m.name.padEnd(24) + " " +
+        (m.source || "apc").padEnd(8) + " " +
+        (m.transport || "stdio").padEnd(10) + " " +
+        (m.enabled ? "✓" : "✗")
+      );
+    }
+  }
+
+  if (data.conflicts && data.conflicts.length) {
+    console.log("\n⚠️  Conflicts (APC rule: first source wins):");
+    for (const c of data.conflicts) {
+      console.log(`  ${c.name}: kept "${c.winner}", ignored "${c.loser}"`);
+    }
+  } else {
+    console.log("\n✓ no conflicts");
+  }
+}

package/src/cli/commands/memory.js

@@ -0,0 +1,69 @@
+import fs from "node:fs";
+import path from "node:path";
+import { findApfRoot } from "../../core/parser.js";
+import { ensureAgentDir } from "../../core/scaffold.js";
+import { http } from "../http.js";
+
+function requireRoot() {
+  const root = findApfRoot();
+  if (!root) throw new Error("not inside an APC project (run `apx init` first)");
+  return root;
+}
+
+async function nudgeDaemon(root) {
+  try {
+    if (!(await http.ping())) return;
+    const projects = await http.get("/projects", { autoStart: false });
+    const me = projects.find((p) => p.path === root);
+    if (me) await http.post(`/projects/${me.id}/rebuild`, undefined, { autoStart: false });
+  } catch {}
+}
+
+export async function cmdMemory(args) {
+  const slug = args._[0];
+  if (!slug) throw new Error("apx memory: missing <agent-slug>");
+  const root = requireRoot();
+  const memPath = path.join(root, ".apc", "agents", slug, "memory.md");
+
+  if (args.flags.replace) {
+    const newBody = readStdinSync();
+    ensureAgentDir(root, slug);
+    fs.writeFileSync(memPath, newBody);
+    await nudgeDaemon(root);
+    console.log(`replaced memory for ${slug} (${Buffer.byteLength(newBody)} bytes)`);
+    return;
+  }
+
+  if (args.flags.append && args.flags.append !== true) {
+    const note = String(args.flags.append);
+    ensureAgentDir(root, slug);
+    let body = fs.existsSync(memPath) ? fs.readFileSync(memPath, "utf8") : "";
+    if (!/##\s+Recent context/i.test(body)) {
+      body += body.endsWith("\n") ? "\n## Recent context\n" : "\n\n## Recent context\n";
+    }
+    const today = new Date().toISOString().slice(0, 10);
+    body = body.replace(/(##\s+Recent context\s*\n)/i, `$1- ${today}: ${note}\n`);
+    fs.writeFileSync(memPath, body);
+    await nudgeDaemon(root);
+    console.log(`appended to ${slug} memory: ${note}`);
+    return;
+  }
+
+  if (!fs.existsSync(memPath)) {
+    throw new Error(`no memory for "${slug}" — agent dir not yet created`);
+  }
+  process.stdout.write(fs.readFileSync(memPath, "utf8"));
+}
+
+function readStdinSync() {
+  const chunks = [];
+  const buf = Buffer.alloc(65536);
+  try {
+    while (true) {
+      const bytes = fs.readSync(0, buf, 0, buf.length);
+      if (!bytes) break;
+      chunks.push(buf.slice(0, bytes).toString("utf8"));
+    }
+  } catch {}
+  return chunks.join("");
+}