total-recall-brain 3.30.1 → 3.31.0

package/bin/total-recall.mjs

@@ -58,6 +58,7 @@ const COMMANDS = {
   status:   'status.mjs',
   remember: 'remember.mjs',
   forget:   'forget.mjs',
+  edit:     'edit.mjs',
   recall:   'recall.mjs',
   search:   'recall.mjs',
   research: 'research.mjs',
@@ -111,7 +112,7 @@ function printHelp() {
   Core (default product path):
     init [--project]    Bootstrap global or project brain + openwiki
     connect <client>    Wire IDE / Obsidian / http-api host
-    remember / forget   Write-path memory (SSSS vault)
+    remember / forget / edit   Write-path memory (SSSS vault)
     recall              Read-path hybrid search
     compile             Rebuild instruction surfaces
     dream               Memory consolidation cycle

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "total-recall-brain",
-  "version": "3.30.1",
+  "version": "3.31.0",
   "description": "Personal AI system — database-free, SSSS-powered intelligence engine deployable to any POSIX host.",
   "type": "module",
   "workspaces": [

package/scaffold/.agent/skills/total-recall/SKILL.md

@@ -71,7 +71,9 @@ Use the **MESH / CONTROL SERVER** section. Node details are entity fields on
 SSSS `mesh_node` documents — never hardcoded hostnames.
 
 ### 5d. When running tests, typechecks, or builds
-See **TESTS**. Heavy runs go to the Mac Mini or the droplet, never the laptop.
+See **TESTS**. The full suite and the quality gates run only on the Mac Mini —
+never on a laptop or the cloud droplet. A single spec file may run on any mesh node. Builds and installs are fine on any machine; build large apps
+on the Mac Mini.
 
 ### 6. When troubleshooting connections, port blocks, or sync errors
 *   **Trigger**: If the REST server is unreachable, ports are blocked, or the upstream sync tool encounters errors.
@@ -602,9 +604,11 @@ npx vitest run <path>       # one spec file
 
 Current baseline (3.30.1): **349 spec files / 2024 tests, ~160 s** on the Mac Mini.
 
-> **Never run the full suite, a full typecheck, or a production build on the
-> laptop.** These go to the Mac Mini or the droplet — local runs cause slowdowns
-> and OOM kills. Sync and run remotely:
+> **The full suite and the quality gates run only on the Mac Mini** — never on a
+> laptop or the cloud droplet; they cause slowdowns and OOM kills. A single spec
+> file may run on any mesh node. Builds
+> and installs are fine anywhere; build large apps on the Mac Mini. Sync and run
+> remotely:
 >
 > ```bash
 > REMOTE=build-host; REMOTE_DIR=code/total-recall   # your own host and path

package/src/cli/edit.mjs

@@ -0,0 +1,206 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import matter from 'gray-matter';
+import { resolveBrainDir, parseLayerFlag, getBothBrains } from './agent-dir.mjs';
+import { writeNodeValidatedAsync } from '../core/validated-write.mjs';
+import { isSafeVaultName } from '../core/vault.mjs';
+
+const PRIORITIES = ['absolute', 'high', 'normal', 'low'];
+const MODALITIES = ['must', 'must_not', 'should', 'should_not', 'descriptive', 'preference'];
+const STATUSES = ['active', 'archived', 'deprecated'];
+
+function printHelp() {
+  console.log(`
+  total-recall edit — Change an existing memory node in place (same slug)
+
+  Usage: total-recall edit <slug> ["<new content>"] [options]
+
+    Options:
+    --title <text>            Replace the title
+    --importance, -i <1-5>    Replace the importance
+    --priority, -p <level>    absolute | high | normal | low
+    --modality, -m <type>     must | must_not | should | should_not | descriptive | preference
+    --tags, -t <list>         Replace the tags (comma-separated)
+    --status <status>         active | archived | deprecated
+    --global                  Edit the node in the global brain
+    --project                 Edit the node in the project brain
+    --no-compile              Skip auto-recompilation after the edit
+    --help, -h                Show this help
+
+  Pass "-" as the content to read the new body from stdin. Omit the content to
+  keep the body and change only the options given.
+
+  If neither --global nor --project is specified, the node is looked up in the
+  project brain first (if one exists), then in the global brain.
+
+  Examples:
+    npx total-recall edit anti-patterns-7a7fb6a5 "Never run tests on the MacBook."
+    npx total-recall edit my-rule --priority absolute --modality must --global
+    cat new-body.md | npx total-recall edit my-fact -
+`);
+}
+
+/** Path of `<slug>.md` inside any category directory of `vaultDir`, or null. */
+export function findNodeFile(slug, vaultDir) {
+  if (!isSafeVaultName(slug) || !fs.existsSync(vaultDir)) return null;
+  for (const entry of fs.readdirSync(vaultDir, { withFileTypes: true })) {
+    if (!entry.isDirectory() || entry.name.startsWith('.')) continue;
+    const filePath = path.join(vaultDir, entry.name, `${slug}.md`);
+    if (fs.existsSync(filePath)) return filePath;
+  }
+  return null;
+}
+
+/**
+ * Parse edit arguments into { slug, body, changes, noCompile }.
+ * Throws with a user-facing message on invalid input.
+ */
+export function parseEditArgs(args) {
+  const result = { slug: null, body: undefined, changes: {}, noCompile: false };
+  const positional = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    const next = () => {
+      const value = args[++i];
+      if (value === undefined) throw new Error(`${arg} requires a value.`);
+      return value;
+    };
+    if (arg === '--no-compile') result.noCompile = true;
+    else if (arg === '--title') result.changes.title = next();
+    else if (arg === '--importance' || arg === '-i') {
+      const value = Number(next());
+      if (!Number.isInteger(value) || value < 1 || value > 5) {
+        throw new Error('--importance must be an integer from 1 to 5.');
+      }
+      result.changes.importance = value;
+    } else if (arg === '--priority' || arg === '-p') {
+      const value = next().toLowerCase();
+      if (!PRIORITIES.includes(value)) throw new Error(`--priority must be one of: ${PRIORITIES.join(', ')}.`);
+      result.changes.priority = value;
+    } else if (arg === '--modality' || arg === '-m') {
+      const value = next().toLowerCase();
+      if (!MODALITIES.includes(value)) throw new Error(`--modality must be one of: ${MODALITIES.join(', ')}.`);
+      result.changes.modality = value;
+    } else if (arg === '--tags' || arg === '-t') {
+      result.changes.tags = next().split(',').map((t) => t.trim()).filter(Boolean);
+    } else if (arg === '--status') {
+      const value = next().toLowerCase();
+      if (!STATUSES.includes(value)) throw new Error(`--status must be one of: ${STATUSES.join(', ')}.`);
+      result.changes.status = value;
+    } else if (/^--?[a-z]/i.test(arg)) {
+      throw new Error(`Unknown option: ${arg}`);
+    } else positional.push(arg);
+  }
+  if (positional.length > 2) throw new Error('Quote the new content as a single argument.');
+  [result.slug, result.body] = positional;
+  return result;
+}
+
+/**
+ * Apply an edit to a parsed node. Returns the updated node and the list of
+ * changed field names. `immutable` follows `priority`, as in `remember`.
+ */
+export function applyEdit(node, { body, changes }, now = new Date().toISOString()) {
+  const updated = { ...node };
+  const changed = [];
+  if (body !== undefined && body.trim() !== (node.body || '').trim()) {
+    updated.body = body.trim();
+    changed.push('body');
+  }
+  for (const [key, value] of Object.entries(changes)) {
+    if (JSON.stringify(node[key]) === JSON.stringify(value)) continue;
+    updated[key] = value;
+    changed.push(key);
+  }
+  if (changed.includes('title') && node.description === node.title) {
+    updated.description = updated.title;
+  }
+  if (changed.includes('priority')) {
+    if (updated.priority === 'absolute') updated.immutable = true;
+    else delete updated.immutable;
+  }
+  if (changed.length) updated.updated = now;
+  return { node: updated, changed };
+}
+
+function locate(slug, explicitLayer) {
+  const layers = explicitLayer === 'auto' ? ['project', 'global'] : [explicitLayer];
+  const brains = getBothBrains();
+  for (const layer of layers) {
+    if (layer === 'project' && !brains.project) continue;
+    const vaultDir = path.join(resolveBrainDir(layer), 'memory-vault');
+    const filePath = findNodeFile(slug, vaultDir);
+    if (filePath) return { layer, vaultDir, filePath };
+  }
+  return null;
+}
+
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+export default async function edit(args) {
+  const { layer: explicitLayer, remainingArgs } = parseLayerFlag(args);
+  if (!remainingArgs.length || remainingArgs.includes('--help') || remainingArgs.includes('-h')) {
+    printHelp();
+    return;
+  }
+
+  let parsed;
+  try {
+    parsed = parseEditArgs(remainingArgs);
+  } catch (err) {
+    console.error(`  ❌ ${err.message}`);
+    process.exitCode = 1;
+    return;
+  }
+  if (parsed.body === '-') parsed.body = await readStdin();
+  if (parsed.body !== undefined && !parsed.body.trim()) {
+    console.error('  ❌ The new content is empty. Use `total-recall forget` to delete a node.');
+    process.exitCode = 1;
+    return;
+  }
+
+  const found = locate(parsed.slug, explicitLayer);
+  if (!found) {
+    const where = explicitLayer === 'auto' ? 'project or global' : explicitLayer;
+    console.error(`  ❌ Node "${parsed.slug}" not found in the ${where} vault.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const { data, content } = matter(fs.readFileSync(found.filePath, 'utf8'));
+  const { node, changed } = applyEdit({ ...data, body: content.trim() }, parsed);
+  const layerLabel = `[${found.layer}]`;
+  const relPath = path.relative(path.dirname(found.vaultDir), found.filePath);
+
+  if (!changed.length) {
+    console.log(`  ℹ️  Nothing to change in ${layerLabel} ${relPath}.`);
+    return;
+  }
+
+  const result = await writeNodeValidatedAsync(node, found.vaultDir);
+  if (!result.success) {
+    const errors = result.validation?.errors || [result.error || 'unknown validation failure'];
+    console.error(`  ❌ Validation failed: ${errors.join('; ')}`);
+    process.exitCode = 1;
+    return;
+  }
+  console.log(`  ✅ Updated ${layerLabel} ${relPath} (${changed.join(', ')})`);
+
+  if (parsed.noCompile) return;
+  console.log('  ⏳ Recompiling active memory surfaces and indexes in the background...');
+  try {
+    const { spawn } = await import('node:child_process');
+    const child = spawn(process.argv[0], [process.argv[1], 'compile', `--${found.layer}`], {
+      detached: true,
+      stdio: 'ignore',
+    });
+    child.unref();
+    console.log('  ✅ Background compilation started.');
+  } catch (err) {
+    console.warn(`  ⚠️  Node updated, but background recompilation spawn failed: ${err.message}`);
+  }
+}

package/src/cli/help.mjs

@@ -146,7 +146,7 @@ function printGeneralHelp() {
     npx total-recall help architecture
 
   \x1b[1mCore Memory Operations:\x1b[0m
-    \x1b[33mremember\x1b[0m, \x1b[33mrecall\x1b[0m, \x1b[33mforget\x1b[0m, \x1b[33mbrain\x1b[0m, \x1b[33mmap\x1b[0m
+    \x1b[33mremember\x1b[0m, \x1b[33mrecall\x1b[0m, \x1b[33mforget\x1b[0m, \x1b[33medit\x1b[0m, \x1b[33mbrain\x1b[0m, \x1b[33mmap\x1b[0m
 
   \x1b[1mCompilation & System Rules:\x1b[0m
     \x1b[33mcompile\x1b[0m, \x1b[33mrebuild\x1b[0m, \x1b[33mconnect\x1b[0m, \x1b[33mskill\x1b[0m, \x1b[33mimport-rules\x1b[0m

package/src/cli/update.mjs

@@ -6,6 +6,7 @@
  *   npx total-recall update --apply      # install latest where needed
  *   npx total-recall update --apply --force
  *   npx total-recall update --repo /path/to/app
+ *   npx total-recall update --install-autopull [--port N] [--no-build]
  */
 
 import {
@@ -15,6 +16,7 @@ import {
   PACKAGE_NAME,
 } from '../core/package-auto-update.mjs';
 import { brainDir } from '../core/config.mjs';
+import { installAutoPull } from '../core/autopull-install.mjs';
 
 /** @param {string[]} args */
 export function parseArgs(args) {
@@ -24,6 +26,9 @@ export function parseArgs(args) {
     dryRun: false,
     help: false,
     repos: [],
+    installAutopull: false,
+    port: null,
+    noBuild: false,
   };
   for (let i = 0; i < args.length; i++) {
     const a = args[i];
@@ -32,6 +37,9 @@ export function parseArgs(args) {
     else if (a === '--force') opts.force = true;
     else if (a === '--dry-run') opts.dryRun = true;
     else if (a === '--repo' && args[i + 1]) opts.repos.push(args[++i]);
+    else if (a === '--install-autopull') opts.installAutopull = true;
+    else if (a === '--port' && args[i + 1]) opts.port = Number(args[++i]);
+    else if (a === '--no-build') opts.noBuild = true;
   }
   return opts;
 }
@@ -48,6 +56,15 @@ function printHelp() {
     total-recall update --apply --force Ignore throttle / disabled flag
     total-recall update --repo <path>   Include extra root (repeatable)
 
+  This brain's own checkout (git):
+    total-recall update --install-autopull [--port N] [--no-build] [--dry-run]
+        Every 5 minutes fast-forward this checkout to origin/main, install and
+        rebuild what changed, restart the brain and verify /health reports the
+        new version (scripts/auto-pull.sh). macOS: LaunchAgent
+        com.totalrecall.autopull; Linux: crontab. A dev checkout (other branch,
+        uncommitted or unpushed work) is never touched. --no-build: never build
+        the dashboard on this host (laptops).
+
   Env:
     TR_AUTO_UPDATE_PACKAGE=0   Disable daemon cron auto-update (default: on)
     TR_SYNC_REPOS=/a:/b       Extra project roots
@@ -63,6 +80,18 @@ export default async function update(args = []) {
     return;
   }
 
+  if (opts.installAutopull) {
+    const result = installAutoPull({ port: opts.port || undefined, noBuild: opts.noBuild, dryRun: opts.dryRun });
+    if (opts.dryRun) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+    const where = result.plistPath ? `LaunchAgent ${result.plistPath}` : `crontab: ${result.cronLine}`;
+    console.log(`\n  ✅ Auto-pull installed (${where}), checking port ${result.port} every 5 minutes.`);
+    console.log('  Log: ~/.agent/logs/auto-pull.log\n');
+    return;
+  }
+
   const latest = fetchLatestNpmVersion();
   console.log(`\n  Package: ${PACKAGE_NAME}`);
   console.log(`  Latest on npm: ${latest || '(unavailable)'}`);

package/src/core/autopull-install.mjs

@@ -0,0 +1,177 @@
+/**
+ * Install the auto-pull timer on a host that serves a brain from a git checkout.
+ *
+ * The daemon's package auto-update only reaches npm installs in registered
+ * projects; it deliberately skips source checkouts. A brain running from a
+ * checkout therefore never updated unless someone pulled and restarted it by
+ * hand, and the one host with a timer (a droplet cron) pointed at a script that
+ * could not restart anything. This installs scripts/auto-pull.sh — the repo's
+ * own copy, so the updater updates itself — on a 5-minute timer:
+ *   - macOS: a LaunchAgent (com.totalrecall.autopull) with StartInterval;
+ *   - Linux: a crontab line, replacing any earlier auto-pull line.
+ *
+ * Nothing here names a machine or a repository: paths come from where this
+ * package is running, ports from flags, the environment or the brain's own
+ * LaunchAgent.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execFileSync, spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+export const AUTOPULL_LABEL = 'com.totalrecall.autopull';
+export const AUTOPULL_INTERVAL_SECONDS = 300;
+
+/** The checkout this CLI runs from (…/src/core → repo root). */
+export function packageRoot() {
+  return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+}
+
+function xmlEscape(value) {
+  return String(value)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+/** LaunchAgent that runs the checkout's auto-pull.sh every `interval` seconds. */
+export function buildLaunchAgentPlist({ script, env = {}, logFile, interval = AUTOPULL_INTERVAL_SECONDS, label = AUTOPULL_LABEL }) {
+  const envEntries = Object.entries(env)
+    .filter(([, v]) => v !== undefined && v !== null && v !== '')
+    .map(([k, v]) => `\t\t<key>${xmlEscape(k)}</key>\n\t\t<string>${xmlEscape(v)}</string>`)
+    .join('\n');
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+\t<key>Label</key>
+\t<string>${xmlEscape(label)}</string>
+\t<key>ProgramArguments</key>
+\t<array>
+\t\t<string>/bin/bash</string>
+\t\t<string>${xmlEscape(script)}</string>
+\t</array>
+\t<key>EnvironmentVariables</key>
+\t<dict>
+${envEntries}
+\t</dict>
+\t<key>StartInterval</key>
+\t<integer>${Number(interval)}</integer>
+\t<key>RunAtLoad</key>
+\t<true/>
+\t<key>StandardOutPath</key>
+\t<string>${xmlEscape(logFile)}</string>
+\t<key>StandardErrorPath</key>
+\t<string>${xmlEscape(logFile)}</string>
+</dict>
+</plist>
+`;
+}
+
+function shellQuote(value) {
+  return `'${String(value).replace(/'/g, `'\\''`)}'`;
+}
+
+/** The crontab line that runs auto-pull.sh every 5 minutes. */
+export function buildCronLine({ script, env = {} }) {
+  const assignments = Object.entries(env)
+    .filter(([, v]) => v !== undefined && v !== null && v !== '')
+    .map(([k, v]) => `${k}=${shellQuote(v)}`)
+    .join(' ');
+  return `*/5 * * * * ${assignments ? `${assignments} ` : ''}/bin/bash ${shellQuote(script)} >/dev/null 2>&1`;
+}
+
+/** Replace every earlier auto-pull line with `line`; keep everything else. */
+export function mergeCrontab(existing, line) {
+  const kept = String(existing || '')
+    .split('\n')
+    .filter((l) => l.trim() && !/auto-pull\.sh/.test(l));
+  return `${[...kept, line].join('\n')}\n`;
+}
+
+/**
+ * The port the brain from `repoDir` serves: the PORT of the LaunchAgent that
+ * runs it (macOS), else null.
+ */
+export function detectLaunchAgentPort(repoDir, { home = os.homedir(), readPlist = readPlistValue } = {}) {
+  const dir = path.join(home, 'Library', 'LaunchAgents');
+  if (!fs.existsSync(dir)) return null;
+  for (const entry of fs.readdirSync(dir)) {
+    if (!entry.endsWith('.plist') || entry === `${AUTOPULL_LABEL}.plist`) continue;
+    const file = path.join(dir, entry);
+    const cwd = readPlist(file, 'WorkingDirectory');
+    const args = readPlist(file, 'ProgramArguments') || '';
+    if (cwd !== repoDir && !args.includes(`${repoDir}/`)) continue;
+    const port = readPlist(file, 'EnvironmentVariables:PORT');
+    if (port && /^\d+$/.test(port.trim())) return Number(port.trim());
+  }
+  return null;
+}
+
+function readPlistValue(file, key) {
+  try {
+    return execFileSync('/usr/libexec/PlistBuddy', ['-c', `Print :${key}`, file], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Install (or refresh) the timer. Returns what it did; `dryRun` returns the
+ * plan without writing.
+ */
+export function installAutoPull({
+  repoDir = packageRoot(),
+  port,
+  noBuild = false,
+  platform = process.platform,
+  home = os.homedir(),
+  dryRun = false,
+} = {}) {
+  const script = path.join(repoDir, 'scripts', 'auto-pull.sh');
+  if (!fs.existsSync(path.join(repoDir, '.git'))) {
+    throw new Error(`${repoDir} is not a git checkout; npm installs update through the daemon (total-recall update --apply).`);
+  }
+  if (!fs.existsSync(script)) throw new Error(`Missing ${script}`);
+
+  const resolvedPort =
+    port || Number(process.env.TR_PORT) || (platform === 'darwin' ? detectLaunchAgentPort(repoDir, { home }) : null) || 3000;
+  const env = {
+    TR_REPO_DIR: repoDir,
+    TR_PORT: String(resolvedPort),
+    TR_AUTOPULL_NO_BUILD: noBuild ? '1' : undefined,
+  };
+  const logDir = path.join(home, '.agent', 'logs');
+
+  if (platform === 'darwin') {
+    const plistPath = path.join(home, 'Library', 'LaunchAgents', `${AUTOPULL_LABEL}.plist`);
+    const plist = buildLaunchAgentPlist({
+      script,
+      env: { ...env, HOME: home, PATH: process.env.PATH },
+      logFile: path.join(logDir, 'auto-pull.launchd.log'),
+    });
+    if (dryRun) return { platform, plistPath, plist, port: resolvedPort };
+    fs.mkdirSync(logDir, { recursive: true });
+    fs.mkdirSync(path.dirname(plistPath), { recursive: true });
+    fs.writeFileSync(plistPath, plist, { mode: 0o644 });
+    const domain = `gui/${process.getuid()}`;
+    spawnSync('launchctl', ['bootout', `${domain}/${AUTOPULL_LABEL}`], { stdio: 'ignore' });
+    const boot = spawnSync('launchctl', ['bootstrap', domain, plistPath], { encoding: 'utf8' });
+    if (boot.status !== 0) throw new Error(`launchctl bootstrap failed: ${(boot.stderr || '').trim()}`);
+    return { platform, plistPath, port: resolvedPort, installed: true };
+  }
+
+  const line = buildCronLine({ script, env });
+  const current = spawnSync('crontab', ['-l'], { encoding: 'utf8' });
+  const merged = mergeCrontab(current.status === 0 ? current.stdout : '', line);
+  if (dryRun) return { platform, cronLine: line, crontab: merged, port: resolvedPort };
+  const write = spawnSync('crontab', ['-'], { input: merged, encoding: 'utf8' });
+  if (write.status !== 0) throw new Error(`crontab write failed: ${(write.stderr || '').trim()}`);
+  return { platform, cronLine: line, port: resolvedPort, installed: true };
+}

package/src/server/index.mjs

@@ -280,7 +280,10 @@ app.get('/health', requireAuthOrLocal, async (req, res) => {
   const unembeddedBrains = (embeddingCoverage || []).filter(c => c.nodes > 0 && c.embedded === 0);
 
   // Determine overall status
-  const hasCriticalIssue = emergencyAlerts.length > 0 || daemonStatus === 'dead' || cliAgents.length === 0
+  // No agent CLIs on PATH is normal for a headless server brain (a droplet has
+  // none), so it is reported in cli_agents but does not make the brain
+  // "degraded" — that status is for things that break memory itself.
+  const hasCriticalIssue = emergencyAlerts.length > 0 || daemonStatus === 'dead'
     || unembeddedBrains.length > 0;
 
   // Check Caddy and Cloudflare status