ispbills-icli 8.1.1 → 8.3.0

package/README.md

@@ -99,7 +99,8 @@ icli --reasoning "audit the config on olt#1"   # stream reasoning inline
 
 | Flag | Description |
 |---|---|
-| `--reasoning` | Stream the model's reasoning inline |
+| `--reasoning` | Stream the model's reasoning inline (on by default in the REPL) |
+| `--no-reasoning` | Hide the reasoning trace |
 | `--loader-style STYLE` | Thinking indicator: `spinner` (default), `gradient`, or `minimal` |
 | `--ascii` | Force ASCII-safe glyphs (use if symbols show as boxes) |
 | `--unicode` | Force full Unicode glyphs |
@@ -145,10 +146,29 @@ suggestion (accept with **Tab** or **→**), and runs the highlighted command on
 |---|---|
 | `/mac [addr]` | Locate a MAC address on the network |
 | `/arp [device]` · `/route [device]` | ARP / routing tables |
+| `/overlaps [ip/vlan/bgp/route]` | Find overlapping IP subnets, VLAN ids, interface assignments, BGP prefixes or routes |
+| `/flapping [device]` | List flapping interfaces (frequent up/down transitions) |
 | `/dhcp` | DHCP leases and pool usage |
 | `/ping [host]` · `/trace [host]` | Ping / traceroute a host |
 | `/customer [name/IP]` | Look up a customer |
 
+**Backups & version control**
+
+| Slash | Description |
+|---|---|
+| `/backup [device]` | Back up device config (all devices if omitted). Each answer is archived to your per-user git repo |
+| `/git [args]` | Run git in that backup repo — e.g. `/git status`, `/git log`, `/git commit -m "note"`, `/git remote add origin <url>`, `/git push` |
+| `/gist` | Save the last answer or the whole transcript to a **secret** GitHub gist (uses the `gh` CLI, or `/gist token <TOKEN>`) |
+
+**Memory**
+
+| Slash | Description |
+|---|---|
+| `/remember <note>` | Save a standing note the AI keeps in mind on every turn |
+| `/memory` | List your saved memory notes |
+| `/forget <n/all>` | Delete a note by number, matching text, or `all` |
+| `/copy` | Copy the last AI answer to the system clipboard |
+
 **Session**
 
 | Slash | Description |
@@ -165,7 +185,10 @@ suggestion (accept with **Tab** or **→**), and runs the highlighted command on
 |---|---|
 | **Enter** | Send message (or run the highlighted slash command) |
 | **/** then **↑/↓** | Open the slash menu and move the selection; **Tab** / **→** completes, **Enter** runs |
+| **@** | Mention a device/entity (e.g. `@olt:`, `@onu:`); **Tab** / **→** completes the tag |
 | **↑/↓** (empty input) | Navigate input history |
+| **Ctrl+Z** / **Ctrl+Y** | Undo / redo the input line |
+| **Paste** | Multi-line pastes are inserted as one line (never auto-submitted) |
 | **Shift+Tab** | Toggle autopilot mode |
 | **Ctrl+T** | Toggle reasoning display |
 | **Ctrl+L** | Clear the transcript |
@@ -194,8 +217,15 @@ iCli connects to the same AI engine as the in-browser terminal:
 - **Customer lookup** — find customers by name, IP, MAC, username, or invoice  
 - **Config audits** — review running config and get concrete suggestions  
 - **Web search** — looks up vendor CLI docs when it needs to  
-- **Streaming output** — answers stream live with a thinking indicator, reasoning, and step-by-step server progress  
-- **Plans & connect cards** — proposed fixes render as a reviewable plan (`apply fix` to confirm); device connections show as a connect card  
+- **Streaming output** — reasoning, thoughts, and multi-step plans all stream live as they form, with an animated working indicator and step-by-step server progress  
+- **Reasoning on by default** — the model's reasoning trace streams inline (toggle with **Ctrl+T** / `/reasoning`, or start with `--no-reasoning`)  
+- **Rich rendering** — Markdown tables, colored lists, headings, and code blocks; `@`-mentions are highlighted; long lists render as aligned tables  
+- **Interactive prompts** — when the AI needs a decision, it shows a selectable choice list (↑/↓, **Enter**) with an optional free-text answer (**Tab**)  
+- **Plans & connect cards** — proposed fixes stream in live as a reviewable plan (`apply fix` to confirm, or use the Apply/Explain/Cancel prompt); device connections show as a connect card  
+- **Bot memory** — `/remember` saves standing operator notes that are injected into every answer (`/memory`, `/forget` to manage)  
+- **Backups in git** — `/backup` archives config to a per-user git repo; run `/git status|log|commit|push` from the prompt  
+- **Share as a gist** — `/gist` publishes the last answer or transcript to a secret GitHub gist  
+- **Copy & paste** — `/copy` puts the last answer on the clipboard; multi-line pastes and **Ctrl+Z / Ctrl+Y** undo/redo work in the input  
 - **Full-screen terminal UI** — a full-height alternate-screen TUI (built on [Ink](https://github.com/vadimdemedes/ink)) with the banner pinned to the top, a bottom-pinned bordered input, a selectable slash-command menu, input history, and a bottom-anchored transcript — the same layout as GitHub Copilot CLI / Gemini CLI. Piped/non-interactive use falls back to plain streaming output  
 - **Terminal-aware rendering** — the layout reflows to your terminal width and resizes live; on classic Windows consoles (`cmd.exe` / legacy PowerShell) it auto-switches to ASCII-safe glyphs and borders so nothing shows as broken boxes  
 

package/bin/icli.js

@@ -54,9 +54,9 @@ if (has('--ascii')) process.env.ICLI_ASCII = '1';
 if (has('--unicode')) process.env.ICLI_UNICODE = '1';
 
 const display = {
-  reasoning: has('--reasoning'),
+  reasoning: !has('--no-reasoning'),
   loader: {
-    text: 'Thinking',
+    text: 'Working',
     style: flag('--loader-style') || 'spinner',
   },
 };
@@ -109,7 +109,8 @@ function printHelp() {
 
   console.log(`\n  ${BOLD}Flags${RESET}`);
   [
-    ['--reasoning',            'Stream the model\'s reasoning inline'],
+    ['--reasoning',            'Stream reasoning inline (on by default)'],
+    ['--no-reasoning',         'Hide the reasoning trace'],
     ['--loader-style STYLE',   'spinner | gradient | minimal'],
     ['--ascii',                'Force ASCII-safe glyphs (classic Windows cmd.exe)'],
     ['--unicode',              'Force full Unicode glyphs'],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ispbills-icli",
-  "version": "8.1.1",
+  "version": "8.3.0",
   "description": "iCli — IspBills AI network engineer in your terminal",
   "keywords": [
     "ispbills",

package/src/client.js

@@ -7,7 +7,11 @@ import { refreshToken } from './auth.js';
 function parseStreamText(raw) {
   const m = raw.match(/"text"\s*:\s*"((?:[^"\\]|\\.)*)/);
   if (!m) return raw.trimStart().startsWith('{') ? null : raw;
-  return m[1]
+  return unescapeJsonStr(m[1]);
+}
+
+function unescapeJsonStr(s) {
+  return s
     .replace(/\\n/g, '\n')
     .replace(/\\t/g, '\t')
     .replace(/\\r/g, '')
@@ -15,6 +19,53 @@ function parseStreamText(raw) {
     .replace(/\\\\/g, '\\');
 }
 
+/** Pull the value of a top-level string key out of a (possibly partial) JSON blob. */
+function grabString(raw, key) {
+  const m = raw.match(new RegExp('"' + key + '"\\s*:\\s*"((?:[^"\\\\]|\\\\.)*)"'));
+  return m ? unescapeJsonStr(m[1]) : null;
+}
+
+/**
+ * Extract a partially-streamed `plan` reply from the raw JSON.
+ * Returns { summary, steps:[{cmd, why, risk}] } using only the step objects
+ * that have finished streaming (balanced braces), so the plan can grow live.
+ */
+export function parsePartialPlan(raw) {
+  const summary = grabString(raw, 'summary') || '';
+  const steps = [];
+  const sm = raw.match(/"steps"\s*:\s*\[/);
+  if (sm) {
+    let i = sm.index + sm[0].length;
+    while (i < raw.length) {
+      // find next object start
+      while (i < raw.length && raw[i] !== '{' && raw[i] !== ']') i++;
+      if (i >= raw.length || raw[i] === ']') break;
+      // scan a balanced object, respecting strings
+      let depth = 0, inStr = false, esc = false, start = i;
+      for (; i < raw.length; i++) {
+        const ch = raw[i];
+        if (inStr) {
+          if (esc) esc = false;
+          else if (ch === '\\') esc = true;
+          else if (ch === '"') inStr = false;
+        } else if (ch === '"') inStr = true;
+        else if (ch === '{') depth++;
+        else if (ch === '}') { depth--; if (depth === 0) { i++; break; } }
+      }
+      if (depth !== 0) break; // object still streaming
+      const objRaw = raw.slice(start, i);
+      const cmd = grabString(objRaw, 'cmd');
+      if (cmd === null) continue;
+      steps.push({
+        cmd,
+        why: grabString(objRaw, 'why') || grabString(objRaw, 'reason') || '',
+        risk: grabString(objRaw, 'risk') || '',
+      });
+    }
+  }
+  return { type: 'plan', summary, steps };
+}
+
 /**
  * Stream a chat turn from the IspBills Terminal AI backend.
  *
@@ -82,10 +133,17 @@ export async function streamChat(cfg, messages, options = {}) {
         onEvent({ type: 'reasoning', delta: ev.reason_delta });
       } else if (ev.delta !== undefined) {
         rawAnswer += ev.delta;
-        const txt = parseStreamText(rawAnswer);
-        if (txt !== null && txt.length > answerText.length) {
-          onEvent({ type: 'text', delta: txt.slice(answerText.length) });
-          answerText = txt;
+        const trimmed = rawAnswer.trimStart();
+        const isPlan = /"type"\s*:\s*"plan"/.test(rawAnswer) ||
+          (trimmed.startsWith('{') && /"steps"\s*:/.test(rawAnswer));
+        if (isPlan) {
+          onEvent({ type: 'plan', reply: parsePartialPlan(rawAnswer) });
+        } else {
+          const txt = parseStreamText(rawAnswer);
+          if (txt !== null && txt.length > answerText.length) {
+            onEvent({ type: 'text', delta: txt.slice(answerText.length) });
+            answerText = txt;
+          }
         }
       } else if (ev.done) {
         finalResult = ev.result;

package/src/clipboard.js

@@ -0,0 +1,42 @@
+// Cross-platform "copy to system clipboard" helper. Best-effort: resolves to
+// false (rather than throwing) when no clipboard tool is available so the TUI
+// can show a friendly notice.
+import { spawn } from 'child_process';
+
+function candidates() {
+  if (process.platform === 'darwin') return [['pbcopy', []]];
+  if (process.platform === 'win32') return [['clip', []]];
+  // Linux / BSD: prefer Wayland, then X11 tools.
+  return [
+    ['wl-copy', []],
+    ['xclip', ['-selection', 'clipboard']],
+    ['xsel', ['--clipboard', '--input']],
+  ];
+}
+
+function tryCopy(cmd, args, text) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn(cmd, args, { stdio: ['pipe', 'ignore', 'ignore'] });
+    } catch {
+      resolve(false);
+      return;
+    }
+    child.on('error', () => resolve(false));
+    child.on('close', (code) => resolve(code === 0));
+    try {
+      child.stdin.end(text);
+    } catch {
+      resolve(false);
+    }
+  });
+}
+
+/** Copy `text` to the system clipboard. Returns the tool name on success, else null. */
+export async function copyToClipboard(text) {
+  for (const [cmd, args] of candidates()) {
+    if (await tryCopy(cmd, args, text)) return cmd;
+  }
+  return null;
+}

package/src/commands.js

@@ -34,11 +34,23 @@ export const SLASH_COMMANDS = [
   { cmd: '/mac',        hint: '[addr]',      desc: 'Locate a MAC address on the network',     group: 'Lookup'    },
   { cmd: '/arp',        hint: '[device]',    desc: 'ARP table for a device',                  group: 'Lookup'    },
   { cmd: '/route',      hint: '[device]',    desc: 'Routing table for a device',              group: 'Lookup'    },
+  { cmd: '/overlaps',   hint: '[ip/vlan/bgp/route]', desc: 'Find overlapping IP, VLAN, interface, BGP or routes', group: 'Lookup' },
+  { cmd: '/flapping',   hint: '[device]',    desc: 'List flapping interfaces (frequent up/down)', group: 'Lookup' },
   { cmd: '/dhcp',       hint: '',            desc: 'DHCP leases and pool usage',              group: 'Lookup'    },
   { cmd: '/ping',       hint: '[host]',      desc: 'Ping a host through the network',         group: 'Lookup'    },
   { cmd: '/trace',      hint: '[host]',      desc: 'Traceroute the path to a host',           group: 'Lookup'    },
   { cmd: '/customer',   hint: '[name/IP]',   desc: 'Look up a customer',                      group: 'Lookup'    },
 
+  // ── Backups & version control ──
+  { cmd: '/git',        hint: '[args]',      desc: 'Run git in your backup repo (status/commit/push/log)', group: 'Backups', local: true },
+  { cmd: '/gist',       hint: '',            desc: 'Save the last answer or transcript to a GitHub gist',  group: 'Backups', local: true },
+
+  // ── Memory ──
+  { cmd: '/remember',   hint: '<note>',      desc: 'Save a standing note the AI keeps in mind', group: 'Memory', local: true },
+  { cmd: '/memory',     hint: '',            desc: 'List saved memory notes',                 group: 'Memory', local: true },
+  { cmd: '/forget',     hint: '[n/all]',     desc: 'Delete a memory note (by number or all)', group: 'Memory', local: true },
+  { cmd: '/copy',       hint: '',            desc: 'Copy the last AI answer to the clipboard', group: 'Memory', local: true },
+
   // ── Session & app ──
   { cmd: '/autopilot',  hint: '',            desc: 'Toggle autopilot (auto-apply fixes)',     group: 'Session', local: true },
   { cmd: '/model',      hint: '[name]',      desc: 'Show or set the AI model',                group: 'Session', local: true },
@@ -106,6 +118,16 @@ export function slashToQuestion(line) {
     case '/mac':        return on(`locate MAC address ${arg} — which device and port is it on?`, 'how do I locate a MAC address? ask me for the address');
     case '/arp':        return on(`show the ARP table for ${arg}`, 'show ARP tables and flag any duplicate or suspicious entries');
     case '/route':      return on(`show the routing table for ${arg}`, 'show routing tables across the network');
+    case '/overlaps': {
+      const t = arg.toLowerCase();
+      if (/vlan/.test(t))                    return 'scan all devices for duplicate or overlapping VLAN ids and list each conflict with the devices/interfaces involved';
+      if (/bgp|prefix|as\b|peer/.test(t))    return 'check BGP for overlapping or conflicting prefixes and duplicate AS announcements across routers and list each conflict';
+      if (/route|routing/.test(t))           return 'find overlapping or conflicting routes across the routing tables and list each pair with the devices involved';
+      if (/int|port/.test(t))                return 'find interfaces/ports with overlapping or duplicate address or VLAN assignments and list each conflict';
+      if (/ip|subnet|network|cidr/.test(t))  return 'find overlapping or conflicting IP subnets and duplicate IP addresses across the network and list each conflict with the devices involved';
+      return 'scan the whole network for any overlapping or conflicting IP subnets, duplicate IPs, duplicate/overlapping VLAN ids, interface assignment conflicts, and overlapping BGP prefixes or routes — list each conflict grouped by type with the devices involved';
+    }
+    case '/flapping':   return on(`check ${arg} for flapping interfaces — list ports with frequent up/down transitions, their flap counts and last change time`, 'scan all devices for flapping interfaces (frequent up/down transitions) and list them with flap counts and the last state-change time');
     case '/dhcp':       return 'show DHCP leases and pool usage, and flag pools that are nearly exhausted';
     case '/ping':       return on(`ping ${arg} through the network and report latency and loss`, 'which hosts should I ping? list reachable devices');
     case '/trace':      return on(`traceroute the path to ${arg} and show each hop`, 'what host should I traceroute?');

package/src/gist.js

@@ -0,0 +1,90 @@
+// Create GitHub gists from the terminal. Prefers the `gh` CLI (uses its stored
+// auth); falls back to the REST API with a token from the icli config
+// (cfg.github_token) or the GITHUB_TOKEN / GH_TOKEN environment variables.
+import { spawn } from 'child_process';
+import { mkdtempSync, writeFileSync, rmSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+
+function sh(cmd, args, { input } = {}) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn(cmd, args, { stdio: ['pipe', 'pipe', 'pipe'] });
+    } catch (e) {
+      resolve({ code: 127, stdout: '', stderr: String(e.message || e) });
+      return;
+    }
+    let stdout = '', stderr = '';
+    child.stdout.on('data', (d) => (stdout += d));
+    child.stderr.on('data', (d) => (stderr += d));
+    child.on('error', (e) => resolve({ code: 127, stdout, stderr: String(e.message || e) }));
+    child.on('close', (code) => resolve({ code, stdout: stdout.trim(), stderr: stderr.trim() }));
+    if (input != null) { try { child.stdin.end(input); } catch {} }
+    else child.stdin.end();
+  });
+}
+
+async function hasGh() {
+  const res = await sh('gh', ['--version']);
+  return res.code === 0;
+}
+
+function token(cfg) {
+  return cfg?.github_token || process.env.GITHUB_TOKEN || process.env.GH_TOKEN || '';
+}
+
+/** True if any GitHub auth is available (gh CLI or a token). */
+export async function canGist(cfg) {
+  if (token(cfg)) return true;
+  return hasGh();
+}
+
+async function gistViaGh({ filename, content, description, isPublic }) {
+  const dir = mkdtempSync(join(tmpdir(), 'icli-gist-'));
+  const path = join(dir, filename);
+  try {
+    writeFileSync(path, content);
+    const args = ['gist', 'create', path, '-d', description];
+    if (isPublic) args.push('--public');
+    const res = await sh('gh', args);
+    if (res.code !== 0) throw new Error(res.stderr || 'gh gist create failed');
+    const url = (res.stdout.match(/https?:\/\/\S+/) || [res.stdout])[0];
+    return { url };
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+async function gistViaApi({ filename, content, description, isPublic }, tok) {
+  const res = await fetch('https://api.github.com/gists', {
+    method: 'POST',
+    headers: {
+      Authorization: 'Bearer ' + tok,
+      Accept: 'application/vnd.github+json',
+      'Content-Type': 'application/json',
+      'User-Agent': 'ispbills-icli',
+    },
+    body: JSON.stringify({ description, public: !!isPublic, files: { [filename]: { content } } }),
+  });
+  if (!res.ok) {
+    const txt = await res.text().catch(() => '');
+    throw new Error(`GitHub API ${res.status}: ${txt.slice(0, 160)}`);
+  }
+  const data = await res.json();
+  return { url: data.html_url };
+}
+
+/**
+ * Create a gist. `opts` = { filename, content, description, isPublic }.
+ * Returns { url }. Throws with a helpful message when no auth is available.
+ */
+export async function createGist(cfg, opts) {
+  const o = { isPublic: false, filename: 'icli.md', description: 'iCli export', ...opts };
+  const tok = token(cfg);
+  if (tok) return gistViaApi(o, tok);
+  if (await hasGh()) return gistViaGh(o);
+  throw new Error(
+    'No GitHub auth. Run `gh auth login`, or save a token with `/gist token <TOKEN>` (needs the "gist" scope).',
+  );
+}

package/src/gitrepo.js

@@ -0,0 +1,78 @@
+// Per-user local git repository for archiving device config backups and giving
+// the operator plain /git commands (status, log, commit, push, diff, …). The
+// repo lives under ~/.config/ispbills-icli/backups/<user>/ and is git-init'd on
+// first use with the operator's IspBills identity.
+import { spawn } from 'child_process';
+import { existsSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { userDir } from './userdir.js';
+
+// Sub-commands the operator may run through /git. Read-mostly plus the handful
+// needed to record and publish backups; anything else is refused.
+const ALLOWED = new Set([
+  'status', 'log', 'diff', 'show', 'add', 'commit', 'push', 'pull',
+  'fetch', 'remote', 'branch', 'checkout', 'init', 'config', 'ls-files', 'rev-parse',
+]);
+
+/** Absolute path to the user's backup git repo (created if missing). */
+export function repoDir(cfg) {
+  return userDir(cfg, 'backups');
+}
+
+function run(cfg, args, { input } = {}) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn('git', args, { cwd: repoDir(cfg), stdio: ['pipe', 'pipe', 'pipe'] });
+    } catch (e) {
+      resolve({ code: 127, stdout: '', stderr: String(e.message || e) });
+      return;
+    }
+    let stdout = '', stderr = '';
+    child.stdout.on('data', (d) => (stdout += d));
+    child.stderr.on('data', (d) => (stderr += d));
+    child.on('error', (e) => resolve({ code: 127, stdout, stderr: String(e.message || e) }));
+    child.on('close', (code) => resolve({ code, stdout, stderr }));
+    if (input != null) { try { child.stdin.end(input); } catch {} }
+    else child.stdin.end();
+  });
+}
+
+/** Initialise the repo on first use and set the local identity. */
+export async function ensureRepo(cfg) {
+  const dir = repoDir(cfg);
+  if (!existsSync(join(dir, '.git'))) {
+    await run(cfg, ['init', '-q']);
+    await run(cfg, ['config', 'user.name', cfg?.user?.name || 'IspBills operator']);
+    await run(cfg, ['config', 'user.email', cfg?.user?.email || 'operator@ispbills.local']);
+    await run(cfg, ['config', 'commit.gpgsign', 'false']);
+    writeFileSync(join(dir, 'README.md'), '# IspBills device backups\n\nManaged by iCli (`/backup`, `/git`).\n');
+    await run(cfg, ['add', 'README.md']);
+    await run(cfg, ['commit', '-q', '-m', 'Initialise backup repository']);
+  }
+  return dir;
+}
+
+/** Run a whitelisted git sub-command; returns { ok, code, stdout, stderr }. */
+export async function git(cfg, args) {
+  const sub = (args[0] || '').toLowerCase();
+  if (!sub) return { ok: false, code: 2, stdout: '', stderr: 'Usage: /git <status|log|commit|push|diff|…>' };
+  if (!ALLOWED.has(sub)) {
+    return { ok: false, code: 2, stdout: '', stderr: `git ${sub} is not allowed from iCli. Allowed: ${[...ALLOWED].join(', ')}` };
+  }
+  await ensureRepo(cfg);
+  const res = await run(cfg, args);
+  return { ok: res.code === 0, ...res };
+}
+
+/** Save backup content to a file and commit it. Returns { file, committed, stderr }. */
+export async function commitBackup(cfg, label, content) {
+  await ensureRepo(cfg);
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const safe = String(label || 'fleet').toLowerCase().replace(/[^a-z0-9._-]+/g, '-').slice(0, 40) || 'fleet';
+  const name = `${stamp}__${safe}.txt`;
+  writeFileSync(join(repoDir(cfg), name), String(content));
+  await run(cfg, ['add', name]);
+  const res = await run(cfg, ['commit', '-q', '-m', `Backup ${safe} @ ${stamp}`]);
+  return { file: name, committed: res.code === 0, stderr: res.stderr };
+}

package/src/memory.js

@@ -0,0 +1,72 @@
+// Per-user persistent "bot memory": short operator notes that are injected
+// into the AI context on every turn so the assistant remembers preferences,
+// naming conventions, standing instructions, etc. Managed with /remember,
+// /forget and /memory.
+import { readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { userDir } from './userdir.js';
+
+const MAX_NOTES = 50;
+
+function file(cfg) {
+  return join(userDir(cfg, 'memory'), 'notes.json');
+}
+
+/** Load the user's notes as an array of { at, text }. */
+export function loadNotes(cfg) {
+  try {
+    const data = JSON.parse(readFileSync(file(cfg), 'utf8'));
+    return Array.isArray(data?.notes) ? data.notes : [];
+  } catch {
+    return [];
+  }
+}
+
+function save(cfg, notes) {
+  writeFileSync(file(cfg), JSON.stringify({ notes }, null, 2), { mode: 0o600 });
+  return notes;
+}
+
+/** Append a note. Returns the updated list. */
+export function addNote(cfg, text) {
+  const t = String(text || '').trim();
+  if (!t) return loadNotes(cfg);
+  const notes = loadNotes(cfg);
+  notes.push({ at: new Date().toISOString(), text: t });
+  return save(cfg, notes.slice(-MAX_NOTES));
+}
+
+/**
+ * Remove a note. `which` may be a 1-based index, the string 'all', or a
+ * substring to match. Returns { notes, removed }.
+ */
+export function forgetNote(cfg, which) {
+  const notes = loadNotes(cfg);
+  if (String(which).toLowerCase() === 'all') {
+    save(cfg, []);
+    return { notes: [], removed: notes.length };
+  }
+  const idx = Number(which);
+  if (Number.isInteger(idx) && idx >= 1 && idx <= notes.length) {
+    const [gone] = notes.splice(idx - 1, 1);
+    save(cfg, notes);
+    return { notes, removed: gone ? 1 : 0 };
+  }
+  const needle = String(which || '').toLowerCase();
+  const before = notes.length;
+  const kept = needle ? notes.filter((n) => !n.text.toLowerCase().includes(needle)) : notes;
+  save(cfg, kept);
+  return { notes: kept, removed: before - kept.length };
+}
+
+/** Build the preamble message injected ahead of the conversation, or null. */
+export function memoryPreamble(cfg) {
+  const notes = loadNotes(cfg);
+  if (!notes.length) return null;
+  const body = notes.map((n) => `- ${n.text}`).join('\n');
+  return {
+    role: 'user',
+    content:
+      `[operator memory — standing notes to keep in mind for every answer; do not reply to this message directly]\n${body}`,
+  };
+}