Skip to content

sno-ai/sno-station-skills / skills/R-recursive-self-improvement/rem-reflect/skill

rem-reflect

Verified

Self Learning from this machine's Claude Code, Codex, Hermes, OpenClaw and Cursor sessions. Decide skill changes and lessons with accept/reject/tbd; recall lessons at session start.

FileKindSize
SKILL.mdskill md14.1 KB
references/labeler.mdmarkdown1.2 KB
references/labeler.schema.jsonconfig1.7 KB
references/local-settings.jsonconfig126 B
references/local-writer.schema.jsonconfig2.3 KB
references/proposal.schema.jsonconfig3.2 KB
references/render.jsonconfig245 B
references/signals.jsonconfig71 B
references/text.jsonconfig4.0 KB
scripts/adopt.test.tsscript13.0 KB
scripts/adopt.tsscript14.3 KB
scripts/agent-sessions.tsscript9.1 KB
scripts/allowance-fallback.test.tsscript16.0 KB
scripts/allowance-request-isolation.test.tsscript7.1 KB
scripts/backend.tsscript9.1 KB
scripts/calls.tsscript8.6 KB
scripts/catalogue-cloud.test.tsscript1.5 KB
scripts/catalogue.tsscript3.2 KB
scripts/chunk.tsscript2.1 KB
scripts/cloud-apply.test.tsscript25.2 KB
scripts/cloud-batch.test.tsscript11.2 KB
scripts/cloud-day.test.tsscript6.8 KB
scripts/cloud-verdict.test.tsscript12.1 KB
scripts/cloud-wait.test.tsscript1.3 KB
scripts/cloud.tsscript24.4 KB
scripts/config.tsscript8.1 KB
scripts/cursor.test.tsscript16.1 KB
scripts/cursor.tsscript6.7 KB
scripts/evidence.tsscript1.5 KB
scripts/first-message.test.tsscript10.3 KB
scripts/harvest.test.tsscript16.5 KB
scripts/harvest.tsscript22.6 KB
scripts/hermes-openclaw.test.tsscript25.6 KB
scripts/identity.test.tsscript3.3 KB
scripts/identity.tsscript3.5 KB
scripts/installed-roots.test.tsscript11.0 KB
scripts/journey-adopt-lesson.test.tsscript4.1 KB
scripts/journey-ops.test.tsscript8.0 KB
scripts/labeler.test.tsscript3.6 KB
scripts/labeler.tsscript9.5 KB
scripts/ledger.tsscript2.1 KB
scripts/lessons.tsscript4.7 KB
scripts/local-filter.test.tsscript3.9 KB
scripts/local-first-output.test.tsscript22.1 KB
scripts/local-settings.tsscript1.4 KB
scripts/local-writer.tsscript12.6 KB
scripts/login-in-place.test.tsscript5.8 KB
scripts/model-json.tsscript4.1 KB
scripts/no-network.test.tsscript5.0 KB
scripts/observe.tsscript1.4 KB
scripts/page-journey.test.tsscript6.7 KB
scripts/pages.test.tsscript4.1 KB
scripts/pages.tsscript4.8 KB
scripts/proposer-loop.test.tsscript1.5 KB
scripts/proposer-validate.test.tsscript9.1 KB
scripts/proposer.tsscript8.7 KB
scripts/recall-hook.test.tsscript20.9 KB
scripts/recall.test.tsscript31.4 KB
scripts/recall.tsscript18.2 KB
scripts/reflect.test.tsscript9.3 KB
scripts/reflect.tsscript14.3 KB
scripts/rem-reflectexecutablescript823 B
scripts/rem-reflect.tsscript17.8 KB
scripts/render-chunk.test.tsscript7.2 KB
scripts/render.tsscript9.7 KB
scripts/report.tsscript8.2 KB
scripts/run-status.test.tsscript19.1 KB
scripts/sampling.test.tsscript2.1 KB
scripts/sampling.tsscript915 B
scripts/selftest-guard.test.tsscript4.2 KB
scripts/selftest/bin/claudeexecutablescript94 B
scripts/selftest/bin/codexexecutablescript93 B
scripts/selftest/bin/shim-core.cjsscript4.6 KB
scripts/selftest/bin/snoexecutablescript5.7 KB
scripts/selftest/fixtures/hermes-session-export.jsonlother1.5 KB
scripts/selftest/fixtures/openclaw-events.jsonlother3.7 KB
scripts/selftest/fixtures/verdict-traces.jsonconfig16.6 KB
scripts/selftest/journey-e2e.shexecutablescript1.4 KB
scripts/selftest/journey.mjsscript9.5 KB
scripts/selftest/observe-journey.mjsscript12.5 KB
scripts/selftest/run-selftest.shexecutablescript7.0 KB
scripts/selftest/spawn-python.mjsexecutablescript765 B
scripts/session.test.tsscript5.2 KB
scripts/session.tsscript251 B
scripts/signal-local.test.tsscript7.0 KB
scripts/skill-impact.test.tsscript6.2 KB
scripts/station-settings.test.tsscript13.6 KB
scripts/store-memory.test.tsscript3.4 KB
scripts/store.tsscript7.7 KB
scripts/test-helpers.tsscript15.3 KB
scripts/text.tsscript760 B
scripts/trigger.test.tsscript3.6 KB
scripts/trigger.tsscript2.5 KB
scripts/verdicts.test.tsscript8.1 KB
scripts/verdicts.tsscript8.0 KB

scripts/rem-reflect.ts

View on GitHub
import { appendFileSync, existsSync, realpathSync } from 'node:fs';
import { join } from 'node:path';
import { pathToFileURL } from 'node:url';
import { execFileSync } from 'node:child_process';
import {
  calendar, commands, defaultConfig, isObject, loadConfig, messages, reflectionFiles, storePath,
  validateConfig, validateRoots,
} from './config.ts';
import { harvest } from './harvest.ts';
import { readUserId } from './identity.ts';
import {
  atomicWrite, commitStore, emptyState, headRevision, initializeStore, parseState, privateDirectory,
  processAlive, readHead, readLock, readState, releaseLock, takeOverLock, writeState,
} from './store.ts';
import type { Lock, State } from './store.ts';
import { RealBackend, seedLoopHomes } from './backend.ts';
import type { Backend } from './backend.ts';
import { reflect } from './reflect.ts';
import { lessonsFrom } from './lessons.ts';
import { observe } from './observe.ts';
import { flushCloudVerdicts } from './cloud.ts';
import { buildReport } from './report.ts';
import { verdictCommand } from './adopt.ts';
import { firstMessageRecall, installHooksPrint, lessonDetail, recall } from './recall.ts';
import { cursorRecall, installCursorHooks } from './cursor.ts';
import type { Harness } from './identity.ts';
import { readFileSync } from 'node:fs';

export interface CommandResult { code: number; lines: string[]; stderr?: string[] }

function held(lock: Lock): CommandResult {
  return { code: 0, lines: [`lock held by ${lock.command} ${lock.id} (pid ${lock.pid})`] };
}

// One committed SUCCESSFUL reflection per day. A run no-ops only when today already reached a
// terminal success ('no_action' is a successful reflection that proposed nothing); a day whose only
// run failed, timed out, or found no backend is not done, so a retry that day proceeds.
function succeededToday(store: string, date: string): string | undefined {
  const text = readHead(store, 'state.json');
  const t = text ? parseState(text).last_terminal : null;
  return t && t.date === date && (t.status === 'success' || t.status === 'no_action') ? t.id : undefined;
}

export function run(store: string, now: Date = new Date(), user?: string,
  backend: Backend = new RealBackend(undefined, { loopHomeBase: join(store, '.loop-home') }),
  clock: () => number = () => Date.now(), trigger: 'timer' | 'manual' = 'manual'): CommandResult {
  const started = clock();
  // Directory existence is not proof of a finished bootstrap: a first run killed after mkdir but
  // before config.json, or an empty directory the owner created, would send loadConfig straight
  // into a permanent "no config" error that no recovery path can reach. A store that has a commit
  // is established, so a config.json missing there stays the hard error it is meant to be.
  const bootstrapped = existsSync(join(store, 'config.json')) || headRevision(store) !== undefined;
  const fresh = !existsSync(store) || !bootstrapped;
  const config = fresh ? defaultConfig() : loadConfig(store);
  validateRoots(config, store);
  const start = calendar(now, config.time_zone);
  const prior = readLock(store);
  if (prior && processAlive(prior.pid)) return held(prior);
  let state = fresh ? emptyState() : readState(store);
  const cloudErrors = fresh ? [] : flushCloudVerdicts(store).errors;
  const succeeded = succeededToday(store, start.date);
  if (succeeded) return { code: 0, lines: [`no-op: ${succeeded} already succeeded on ${start.date}`, ...cloudErrors] };
  privateDirectory(store);
  // Finish the bootstrap before recovery touches git. A first run killed mid-initialization can
  // leave a store with no repository, or one with a repository and no config.json — recovering
  // either would fail outright, or commit a HEAD that every later run rejects for a missing config.
  if (fresh) initializeStore(store, config, state);
  const userId = user ?? readUserId(store);
  const lock: Lock = { pid: process.pid, command: 'run', id: start.id };
  // A dead holder is a stale file, not an incident: take the lock over and run. Whatever the dead
  // run left behind is in the store's own git history, where it can be inspected or dropped.
  const notice = prior ? `previous run ${prior.id} did not finish` : '';
  if (!takeOverLock(store, lock)) {
    const holder = readLock(store);
    return holder ? held(holder) : { code: 0, lines: ['no-op: concurrent store writer; retry later'] };
  }
  // The same-day guard above ran before the lock existed, so a run that started and finished while
  // this one waited is invisible to it. Read the state again now that the lock is held: otherwise
  // the day runs twice and the second run writes back a state it read before the first.
  if (existsSync(join(store, 'state.json'))) {
    state = readState(store);
    const succeeded = succeededToday(store, start.date);
    if (succeeded) {
      releaseLock(store);
      return { code: 0, lines: [`no-op: ${succeeded} already succeeded on ${start.date}`, ...cloudErrors] };
    }
  }
  const result = executeHarvest(store, config, state, start, now, userId, notice, backend, clock, started, trigger);
  result.lines.push(...cloudErrors);
  return result;
}

function executeHarvest(store: string, config: ReturnType<typeof defaultConfig>, state: State,
  start: ReturnType<typeof calendar>, now: Date, user: string, notice: string, backend: Backend,
  clock: () => number, started: number, trigger: 'timer' | 'manual'): CommandResult {
  let code = 0;
  let sessionsRead = 0;
  let lines: string[] = [];
  let committed = false;
  const runLog = join(store, 'staging', start.id, 'run.log');
  try {
    state.last_start = start;
    // Persist the date before initialization or harvest can change any other store data.
    writeState(store, state);
    initializeStore(store, config, state);
    atomicWrite(runLog, '');
    try {
      if (backend instanceof RealBackend && existsSync(config.cursor_root)) seedLoopHomes(store, config, lines);
      const result = harvest(store, config, state, user, now);
      sessionsRead = result.traces.length;
      lines = result.log;
      const reflection = reflect(store, config, start.id, backend, lines, now);
      state.last_terminal = { ...start, status: reflection.failed ? 'no_backend' : 'success' };
      if (reflection.failed) code = 1;
      const statusLines = lines.filter(line => line.includes('labeler-'));
      const report = buildReport({ store, config, runId: start.id, notice,
        labelerLines: statusLines, harvested: result.traces.length,
        reflectionReport: reflection.report });
      atomicWrite(join(store, 'staging', start.id, 'REPORT.md'), report);
    } catch (error) {
      code = 1;
      const message = error instanceof Error ? error.message : String(error);
      lines.push(`harvest failed: ${message}`);
      state.last_terminal = { ...start, status: 'failed' };
      atomicWrite(join(store, 'staging', start.id, 'REPORT.md'), `${notice ? `${notice}\n` : ''}Run ${start.id} failed\n${message}\n`);
    }
    appendFileSync(runLog, `${lines.join('\n')}\n`);
    writeState(store, state);
    commitStore(store, start.id);
    committed = true;
    observe('rsi.run', { sessions_read: sessionsRead, duration_ms: clock() - started, trigger,
      outcome: state.last_terminal?.status === 'success' || state.last_terminal?.status === 'no_action' ? 'ok' : 'fail' }, runLog);
    return { code, lines: [`${start.id} ${state.last_terminal?.status}`, ...lines] };
  } finally {
    // A failed commit keeps the lock and last_start as crash-recovery evidence.
    if (committed) releaseLock(store);
  }
}

export function heartbeatLine(output: string): string | undefined {
  return output.split('\n').find(line => /(?:^|\s)rem-reflect\s+\d+(?:\s|$)/.test(line));
}

function listedHeartbeat(): string {
  try {
    return execFileSync('sno', ['heartbeat', '--list'], {
      encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'ignore'],
    });
  } catch { return ''; }
}

// sno setup schedules the run with a systemd user timer (Linux) or a launchd agent (macOS) instead of a heartbeat.
function setupTimerOn(): boolean {
  try {
    if (process.platform === 'darwin') {
      execFileSync('launchctl', ['list', 'ai.sno.rem-reflect'], { timeout: 5000, stdio: 'ignore' });
      return true;
    }
    return execFileSync('systemctl', ['--user', 'show', 'sno-rem-reflect.timer', '--property=ActiveState', '--value'], {
      encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'ignore'],
    }).trim() === 'active';
  } catch { return false; }
}

export function status(store: string, now: Date = new Date(), heartbeat: string = listedHeartbeat(),
  timer: boolean = setupTimerOn()): CommandResult {
  const revision = headRevision(store);
  const stateText = readHead(store, 'state.json', revision);
  const configText = readHead(store, 'config.json', revision);
  const state = stateText ? parseState(stateText) : emptyState();
  const config = configText ? validateConfig(JSON.parse(configText)) : defaultConfig();
  const lines: string[] = ['Self Learning'];
  let code = 0;
  const terminal = state.last_terminal;
  if (!terminal) { lines.push('  Last run   never; start one now with: sno rem-reflect run'); code = 1; }
  else {
    const bad = ['failed', 'timed_out', 'no_backend', 'died'].includes(terminal.status);
    lines.push(`  Last run   ${terminal.date} · ${terminal.status.replace('_', ' ')} · run ${terminal.id}`);
    const today = calendar(now, config.time_zone).date;
    if ((Date.parse(today) - Date.parse(terminal.date)) / 86_400_000 > 2) {
      lines.push('             ! more than two days ago; the daily run is not happening'); code = 1;
    }
    if (bad) { lines.push(`             ! see what went wrong in ${join(store, 'staging', terminal.id, 'run.log')}`); code = 1; }
  }
  const lock = readLock(store);
  if (lock) {
    const alive = processAlive(lock.pid);
    lines.push(alive ? `  Running    ${lock.command} ${lock.id} (pid ${lock.pid})`
      : `  ! ${lock.command} ${lock.id} stopped halfway (pid ${lock.pid} is gone); the next run cleans it up`);
    if (!alive) code = 1;
  }
  const beat = timer || heartbeatLine(heartbeat);
  lines.push(beat ? '  Schedule   on, once a day in the background'
    : '  Schedule   off; turn on with: sno heartbeat --interval 24h --max-hours 0 --label rem-reflect -- sno rem-reflect run --trigger timer');
  if (!beat) code = 1;
  const lessons = lessonsFrom(readHead(store, reflectionFiles.lessons, revision) ?? '');
  const count = (...wanted: string[]) => lessons.filter(lesson => wanted.includes(lesson.status)).length;
  const waiting = count('candidate', 'under_review');
  lines.push(`  Lessons    ${count('accepted')} accepted · ${waiting} waiting for your yes · ${count('rejected')} rejected`);
  if (waiting) lines.push('             decide one with: sno rem-reflect accept <lesson id>  or  reject <lesson id>');
  return { code, lines };
}

function parseFlags(rest: string[]): { positional: string[]; opts: Record<string, string> } {
  const opts: Record<string, string> = {};
  const positional: string[] = [];
  for (let i = 0; i < rest.length; i++) {
    if (rest[i].startsWith('--')) { opts[rest[i].slice(2)] = rest[i + 1] ?? ''; i++; }
    else positional.push(rest[i]);
  }
  return { positional, opts };
}

function recallCommand(rest: string[]): CommandResult {
  const firstMessage = rest.includes('--first-message');
  const { opts } = parseFlags(rest.filter(arg => arg !== '--first-message'));
  const agent = opts.agent as Harness;
  if (rest[0] === 'install') return installCursorHooks();
  if (!['claude-code', 'codex', 'hermes', 'openclaw', 'cursor'].includes(agent)) return { code: 2, lines: ['recall: --agent claude-code|codex|hermes|openclaw|cursor is required'] };
  if (agent === 'cursor') {
    let stdin = '';
    try { stdin = readFileSync(0, 'utf8'); } catch { /* no stdin available */ }
    return cursorRecall(storePath(), firstMessage, stdin, listedHeartbeat);
  }
  let session: string | undefined = opts.session;
  let cwd: string | undefined = opts.cwd;
  let prompt: string | undefined;
  let hookEvent: string | undefined;
  let source: string | undefined;
  let hermesHook = false;
  if (firstMessage || !session || !cwd) {
    // the SessionStart hook pipes the harness's JSON on stdin; both harnesses pass session_id and cwd
    try {
      const value: unknown = JSON.parse(readFileSync(0, 'utf8'));
      if (isObject(value)) {
        hermesHook = agent === 'hermes' && value.hook_event_name === 'pre_llm_call';
        const fields = isObject(value.extra) ? value.extra : value;
        if (hermesHook && fields.is_first_turn !== true) return { code: 0, lines: [] };
        // The Cursor IDE also runs Claude-format hooks, with its own input; the Cursor entries own Cursor.
        if (agent === 'claude-code' && 'cursor_version' in value) return { code: 0, lines: [] };
        if (!session && typeof value.session_id === 'string') session = value.session_id;
        if (!cwd && typeof value.cwd === 'string') cwd = value.cwd;
        if (typeof value.prompt === 'string') prompt = value.prompt;
        if (typeof value.hook_event_name === 'string') hookEvent = value.hook_event_name;
        if (typeof value.source === 'string') source = value.source;
      }
    } catch { /* no stdin available */ }
  }
  // A compaction restart must resend every approved lesson, which only the first-message path does.
  const result = firstMessage || hookEvent === 'SessionStart' && source === 'compact' ? firstMessageRecall(storePath(), agent, { session_id: session, cwd, prompt, hook_event_name: hookEvent, source })
    : recall(storePath(), agent, { session_id: session, cwd }, new Date(), listedHeartbeat(), setupTimerOn());
  if (hermesHook) return { ...result, lines: result.code === 0 ? [JSON.stringify({ context: result.lines.join('\n') })] : [] };
  return result;
}

function lessonCommand(rest: string[]): CommandResult {
  const { positional, opts } = parseFlags(rest);
  if (!positional.length) return { code: 2, lines: ['lesson: a lesson id is required'] };
  const agent = opts.agent as Harness | undefined;
  if (agent && !['claude-code', 'codex', 'hermes', 'openclaw', 'cursor'].includes(agent)) return { code: 2, lines: ['lesson: --agent must be claude-code, codex, hermes, openclaw or cursor'] };
  return lessonDetail(storePath(), positional[0], { session: opts.session, cwd: opts.cwd, agent }, new Date());
}

export function main(args: string[] = process.argv.slice(2)): number {
  if (args.length === 0 || (args.length === 1 && (args[0] === '--help' || args[0] === '-h'))) {
    console.log(messages.help); return 0;
  }
  const [command, ...rest] = args;
  if (!commands.includes(command)) { console.error(messages.help); return 2; }
  const verdicts = ['accept', 'reject', 'tbd'];
  try {
    let result: CommandResult;
    if (command === 'run') {
      const opts: Record<string, string> = {};
      for (let i = 0; i < rest.length; i += 2) {
        const flag = rest[i];
        if (!['--now', '--trigger'].includes(flag) || !rest[i + 1] || flag in opts) {
          console.error(`run: unexpected argument ${flag}`); return 2;
        }
        opts[flag] = rest[i + 1];
      }
      const trigger = opts['--trigger'] ?? 'manual';
      if (trigger !== 'timer' && trigger !== 'manual') { console.error('run: --trigger requires timer|manual'); return 2; }
      const now = opts['--now'] ? new Date(opts['--now']) : new Date();
      if (Number.isNaN(now.getTime())) { console.error('run: --now requires a valid timestamp'); return 2; }
      const store = storePath();
      if (process.env.REM_SELFTEST && (!process.env.REM_REFLECT_STORE || !existsSync(store))) {
        throw new Error(`self-test store missing: ${process.env.REM_REFLECT_STORE || 'REM_REFLECT_STORE'}`);
      }
      result = run(store, now, undefined, undefined, undefined, trigger);
    }
    else if (command === 'status') { if (rest.length) { console.error(`status: unexpected argument ${rest[0]}`); return 2; } result = status(storePath()); }
    else if (verdicts.includes(command)) {
      const scopeFlags = ['--all-projects', '--this-project'];
      const flags = rest.filter(arg => scopeFlags.includes(arg));
      const ids = rest.filter(arg => !scopeFlags.includes(arg));
      if (flags.length > 1 || ids.length !== 1) { console.error(`${command}: one proposal id or lesson id is required`); return 2; }
      if (flags.length && (command !== 'accept' || !ids[0].startsWith('L-'))) {
        console.error(`${flags[0]} is valid only for lesson accept`); return 2;
      }
      result = verdictCommand(storePath(), command, ids[0], new Date(), flags[0] === '--all-projects', flags[0] === '--this-project');
      if (result.code === 0) {
        try {
          const sync = flushCloudVerdicts(storePath());
          result.lines.push(...sync.errors);
          if (sync.pending) result.lines.push(`${sync.pending} cloud verdict pending`);
        } catch (error) {
          result.lines.push(`local decision persisted; cloud verdict ${ids[0]} pending: ${String(error)}`);
        }
      }
    }
    else if (command === 'recall') result = recallCommand(rest);
    else if (command === 'lesson') result = lessonCommand(rest);
    else if (command === 'install-hooks') {
      if (rest[0] !== '--print') { console.error('install-hooks: only --print is supported'); return 2; }
      result = installHooksPrint();
    }
    else { console.error(messages.later); return 3; }
    if (result.lines.length) console.log(result.lines.join('\n'));
    if (result.stderr?.length) console.error(result.stderr.join('\n'));
    return result.code;
  } catch (error) {
    console.error(error instanceof Error ? error.message : String(error)); return 1;
  }
}

// Compare real paths: `import.meta.url` is symlink-resolved by Node, and the deployed skill lives under
// a symlinked harness root, so a raw resolve() of argv[1] would never match and main() would silently
// not run. realpathSync resolves the symlink on both sides.
if (process.argv[1] && pathToFileURL(realpathSync(process.argv[1])).href === import.meta.url) process.exitCode = main();
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexUnverifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall