knight-os 0.1.0 → 0.1.2

package/bin/knight.js

@@ -8,6 +8,13 @@ const readline = require('readline');
 const { loadConfig, resolveWorkspace } = require('../src/config');
 const { chat } = require('../src/chat');
 const { setup } = require('../src/setup');
+const {
+  runMigrations,
+  checkVersion,
+  refreshTemplates,
+  backupWorkspace,
+  CURRENT_DATA_VERSION,
+} = require('../src/migrate');
 
 const VERSION = '0.1.0';
 const DEFAULT_WORKSPACE = path.join(process.env.HOME || '~', '.openclaw', 'workspace');
@@ -213,6 +220,52 @@ function commandVersion() {
   console.log(`knight-os v${VERSION}`);
 }
 
+async function commandUpgrade() {
+  const workspace = DEFAULT_WORKSPACE;
+
+  console.log(`\n🔄 Knight OS — Upgrade Check`);
+  console.log(`   Workspace: ${workspace}\n`);
+
+  if (!fs.existsSync(workspace)) {
+    console.log('   ❌ Workspace not found. Run "knight setup" first.\n');
+    process.exit(1);
+  }
+
+  // 1. Run data migrations
+  const { migrated, backupPath, error } = runMigrations(workspace);
+  if (error) {
+    console.error(`\n❌ Upgrade failed: ${error.message}\n`);
+    process.exit(1);
+  }
+
+  if (!migrated) {
+    const { currentVersion } = checkVersion(workspace);
+    console.log(`   ✅ Already up to date (data v${currentVersion}).\n`);
+  }
+
+  // 2. Refresh non-protected template files (add new ones, skip existing)
+  console.log('   Checking for new template files…');
+  const { added, skipped } = refreshTemplates(workspace, TEMPLATES_DIR);
+  if (added.length > 0) {
+    console.log(`   ✅ Added ${added.length} new file(s):`);
+    added.forEach((f) => console.log(`      + ${f}`));
+  } else {
+    console.log('   ✅ No new template files.');
+  }
+
+  const protectedSkipped = skipped.filter((s) => s.includes('(protected)'));
+  if (protectedSkipped.length > 0) {
+    console.log(`\n   🔒 Protected files untouched (your personal data is safe):`);
+    protectedSkipped.forEach((f) => console.log(`      ${f}`));
+  }
+
+  if (backupPath) {
+    console.log(`\n   📦 Backup kept at:\n      ${backupPath}`);
+  }
+
+  console.log(`\n✅ Upgrade complete. Workspace is at data v${CURRENT_DATA_VERSION}.\n`);
+}
+
 async function commandChat() {
   const config = loadConfig();
   const workspace = resolveWorkspace(config);
@@ -234,6 +287,9 @@ switch (command) {
   case 'status':
     commandStatus();
     break;
+  case 'upgrade':
+    commandUpgrade();
+    break;
   case 'version':
   case '--version':
   case '-v':
@@ -247,6 +303,7 @@ switch (command) {
     console.log('  init      Initialize a new workspace (standalone, no OpenClaw required)');
     console.log('  chat      Start interactive AI chat session');
     console.log('  status    Check workspace file status');
+    console.log('  upgrade   Migrate workspace data + refresh template files safely');
     console.log('  version   Show version number');
     console.log('');
     break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "knight-os",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "AI companion OS for OpenClaw — memory, reflection, and identity framework",
   "main": "bin/knight.js",
   "bin": {

package/src/migrate.js

@@ -0,0 +1,306 @@
+'use strict';
+
+/**
+ * migrate.js — Safe upgrade framework for knight-os
+ *
+ * Design principles:
+ *   1. Data and code live in different places — npm upgrades never touch user data
+ *   2. Version file (.knight-version) tracks the data format version
+ *   3. Before any migration: full backup to .knight-backups/<timestamp>/
+ *   4. Migrations only ADD or TRANSFORM — never delete user content
+ *   5. Protected files (SOUL/MEMORY/USER/REDLINES) are never touched
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// ─────────────────────────────────────────────────────────────
+// Constants
+// ─────────────────────────────────────────────────────────────
+
+/** Current data format version expected by this version of knight-os */
+const CURRENT_DATA_VERSION = 1;
+
+/** Version file stored in the workspace root */
+const VERSION_FILE = '.knight-version';
+
+/** Backup directory inside the workspace */
+const BACKUP_DIR = '.knight-backups';
+
+/** Files that must never be overwritten during migration */
+const PROTECTED_FILES = ['SOUL.md', 'MEMORY.md', 'USER.md', 'REDLINES.md'];
+
+// ─────────────────────────────────────────────────────────────
+// Version helpers
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * Read the data version from the workspace.
+ * Returns 0 if the file doesn't exist (pre-versioning install).
+ */
+function readDataVersion(workspace) {
+  const versionPath = path.join(workspace, VERSION_FILE);
+  if (!fs.existsSync(versionPath)) return 0;
+  const raw = fs.readFileSync(versionPath, 'utf8').trim();
+  const parsed = parseInt(raw, 10);
+  return isNaN(parsed) ? 0 : parsed;
+}
+
+/**
+ * Write the data version to the workspace.
+ */
+function writeDataVersion(workspace, version) {
+  const versionPath = path.join(workspace, VERSION_FILE);
+  fs.writeFileSync(versionPath, String(version) + '\n', 'utf8');
+}
+
+// ─────────────────────────────────────────────────────────────
+// Backup
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * Recursively copy files from src to dst, skipping .knight-backups itself.
+ */
+function copyDirRecursive(src, dst) {
+  fs.mkdirSync(dst, { recursive: true });
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.name === BACKUP_DIR) continue; // don't backup backups
+    const srcPath = path.join(src, entry.name);
+    const dstPath = path.join(dst, entry.name);
+    if (entry.isDirectory()) {
+      copyDirRecursive(srcPath, dstPath);
+    } else {
+      fs.copyFileSync(srcPath, dstPath);
+    }
+  }
+}
+
+/**
+ * Create a timestamped backup of the entire workspace.
+ * Returns the backup path so callers can report it to the user.
+ */
+function backupWorkspace(workspace) {
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+  const backupPath = path.join(workspace, BACKUP_DIR, timestamp);
+  console.log(`  📦 Backing up workspace to ${backupPath} …`);
+  copyDirRecursive(workspace, backupPath);
+  console.log(`  ✅ Backup complete.`);
+  return backupPath;
+}
+
+// ─────────────────────────────────────────────────────────────
+// Migration registry
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * Each migration:
+ *   from    — data version before this migration
+ *   to      — data version after this migration
+ *   desc    — human-readable description
+ *   run(workspace) — the actual migration function; must not throw on clean workspaces
+ */
+const MIGRATIONS = [
+  {
+    from: 0,
+    to: 1,
+    desc: 'Bootstrap versioning — record baseline data version for existing installs',
+    run(workspace) {
+      // Ensure memory subdirectories exist (previously optional)
+      const memoryDirs = [
+        'memory/logs',
+        'memory/projects',
+        'memory/templates',
+        'memory/references',
+      ];
+      for (const dir of memoryDirs) {
+        const fullPath = path.join(workspace, dir);
+        if (!fs.existsSync(fullPath)) {
+          fs.mkdirSync(fullPath, { recursive: true });
+          console.log(`  📁 Created missing directory: ${dir}/`);
+        }
+      }
+
+      // Add UPGRADE.md so users know migration ran
+      const upgradePath = path.join(workspace, 'UPGRADE.md');
+      if (!fs.existsSync(upgradePath)) {
+        fs.writeFileSync(
+          upgradePath,
+          [
+            '# Upgrade Log',
+            '',
+            'knight-os upgrade history for this workspace.',
+            'This file is auto-maintained — do not edit.',
+            '',
+          ].join('\n'),
+          'utf8'
+        );
+      }
+      // Append an entry
+      const entry = `\n## v1 — ${new Date().toISOString().slice(0, 10)}\n- Baseline version established\n- memory/ subdirectories ensured\n`;
+      fs.appendFileSync(upgradePath, entry, 'utf8');
+    },
+  },
+
+  // ── Future migrations go here ──────────────────────────────
+  //
+  // Example v1 → v2:
+  // {
+  //   from: 1,
+  //   to: 2,
+  //   desc: 'Rename ai-patterns.md → noa-patterns.md',
+  //   run(workspace) {
+  //     const oldPath = path.join(workspace, 'memory', 'ai-patterns.md');
+  //     const newPath = path.join(workspace, 'memory', 'noa-patterns.md');
+  //     if (fs.existsSync(oldPath) && !fs.existsSync(newPath)) {
+  //       fs.renameSync(oldPath, newPath);
+  //     }
+  //   },
+  // },
+];
+
+// ─────────────────────────────────────────────────────────────
+// Migration runner
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * Check if the workspace data is up to date.
+ * Returns { needsMigration: bool, currentVersion: number, targetVersion: number }
+ */
+function checkVersion(workspace) {
+  const currentVersion = readDataVersion(workspace);
+  return {
+    needsMigration: currentVersion < CURRENT_DATA_VERSION,
+    currentVersion,
+    targetVersion: CURRENT_DATA_VERSION,
+  };
+}
+
+/**
+ * Run all pending migrations for the workspace.
+ *
+ * - Skips silently if already up to date.
+ * - Creates a backup before running any migrations.
+ * - Runs migrations in order, updating the version file after each one.
+ * - If a migration throws, stops immediately (version file reflects last successful step).
+ *
+ * Returns { migrated: bool, backupPath: string|null, error: Error|null }
+ */
+function runMigrations(workspace) {
+  if (!fs.existsSync(workspace)) {
+    return { migrated: false, backupPath: null, error: null };
+  }
+
+  const { needsMigration, currentVersion, targetVersion } = checkVersion(workspace);
+
+  if (!needsMigration) {
+    return { migrated: false, backupPath: null, error: null };
+  }
+
+  const pending = MIGRATIONS.filter(
+    (m) => m.from >= currentVersion && m.to <= targetVersion
+  ).sort((a, b) => a.from - b.from);
+
+  if (pending.length === 0) {
+    // No migration steps defined yet — just bump the version
+    writeDataVersion(workspace, targetVersion);
+    return { migrated: true, backupPath: null, error: null };
+  }
+
+  console.log(`\n🔄 knight-os: workspace needs upgrade (v${currentVersion} → v${targetVersion})`);
+
+  // Backup before touching anything
+  let backupPath = null;
+  try {
+    backupPath = backupWorkspace(workspace);
+  } catch (err) {
+    return {
+      migrated: false,
+      backupPath: null,
+      error: new Error(`Backup failed, aborting migration: ${err.message}`),
+    };
+  }
+
+  // Run each pending migration
+  for (const migration of pending) {
+    console.log(`  ⚙️  Migration ${migration.from}→${migration.to}: ${migration.desc}`);
+    try {
+      migration.run(workspace);
+      writeDataVersion(workspace, migration.to);
+      console.log(`  ✅ Done.`);
+    } catch (err) {
+      return {
+        migrated: false,
+        backupPath,
+        error: new Error(
+          `Migration ${migration.from}→${migration.to} failed: ${err.message}\n` +
+            `Your data is backed up at: ${backupPath}`
+        ),
+      };
+    }
+  }
+
+  console.log(`\n✅ Workspace upgraded to v${targetVersion}. Backup kept at:\n   ${backupPath}\n`);
+  return { migrated: true, backupPath, error: null };
+}
+
+// ─────────────────────────────────────────────────────────────
+// Template refresh (for `knight upgrade` command)
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * Refresh non-protected template files in the workspace.
+ * Protected files (SOUL/MEMORY/USER/REDLINES) are always skipped.
+ * For all other files: only write if the file doesn't exist yet (safe default).
+ * Pass { force: true } to overwrite non-protected existing files.
+ *
+ * Returns { added: string[], skipped: string[] }
+ */
+function refreshTemplates(workspace, templatesDir, opts) {
+  opts = opts || {};
+  const added = [];
+  const skipped = [];
+
+  function walk(dir, base) {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const relPath = path.relative(base, path.join(dir, entry.name));
+      if (entry.isDirectory()) {
+        walk(path.join(dir, entry.name), base);
+        continue;
+      }
+      const isRoot = !relPath.includes(path.sep);
+      const isProtected = isRoot && PROTECTED_FILES.includes(entry.name);
+      if (isProtected) {
+        skipped.push(relPath + ' (protected)');
+        continue;
+      }
+      const dest = path.join(workspace, relPath);
+      fs.mkdirSync(path.dirname(dest), { recursive: true });
+      if (!fs.existsSync(dest) || opts.force) {
+        fs.copyFileSync(path.join(dir, entry.name), dest);
+        added.push(relPath);
+      } else {
+        skipped.push(relPath);
+      }
+    }
+  }
+
+  walk(templatesDir, templatesDir);
+  return { added, skipped };
+}
+
+// ─────────────────────────────────────────────────────────────
+// Exports
+// ─────────────────────────────────────────────────────────────
+
+module.exports = {
+  CURRENT_DATA_VERSION,
+  PROTECTED_FILES,
+  readDataVersion,
+  writeDataVersion,
+  backupWorkspace,
+  checkVersion,
+  runMigrations,
+  refreshTemplates,
+};

package/src/setup.js

@@ -5,6 +5,7 @@ const path = require('path');
 const os = require('os');
 const readline = require('readline');
 const { execSync, spawnSync } = require('child_process');
+const { runMigrations, writeDataVersion, CURRENT_DATA_VERSION } = require('./migrate');
 
 const DEFAULT_WORKSPACE = path.join(os.homedir(), '.openclaw', 'workspace');
 
@@ -214,14 +215,42 @@ async function setup() {
   const workspaceExists = fs.existsSync(workspace);
   const hasCoreFiles = workspaceExists && fs.existsSync(path.join(workspace, 'AGENTS.md'));
 
-  let overwrite = true;
+  // Files that contain user's personal memory/identity — never overwrite by default
+  const PROTECTED_FILES = ['SOUL.md', 'MEMORY.md', 'USER.md', 'REDLINES.md'];
+  const hasPersonalMemory = hasCoreFiles && PROTECTED_FILES.some(
+    f => fs.existsSync(path.join(workspace, f))
+  );
+
+  let overwrite = false;
+  let overwriteProtected = false;
+
   if (hasCoreFiles) {
-    console.log(`\n⚠️  Workspace already exists at: ${workspace}`);
-    const answer = await ask(rl, 'Overwrite existing files? (y/N)', 'N');
-    overwrite = answer.toLowerCase().startsWith('y');
-    if (!overwrite) {
-      console.log('\nSkipping template write. Continuing with other setup steps...');
+    if (hasPersonalMemory) {
+      console.log(`\n⚠️  Existing OpenClaw workspace detected at: ${workspace}`);
+      console.log('   Protected files found: SOUL.md, MEMORY.md, USER.md, REDLINES.md');
+      console.log('   These contain your personal memory and identity.\n');
+      console.log('   Knight OS will add missing files and update scripts/templates.');
+      console.log('   Your existing memory files will NOT be touched.\n');
+      const answer = await ask(rl, 'Also overwrite protected files? (y/N)', 'N');
+      overwriteProtected = answer.toLowerCase().startsWith('y');
+      if (overwriteProtected) {
+        console.log('\n  ⚠️  Protected files WILL be overwritten. Existing content will be lost.');
+      } else {
+        console.log('\n  ✅ Protected files preserved. Only missing/new files will be added.');
+      }
+      overwrite = true; // always write non-protected files (scripts, AGENTS.md, HEARTBEAT.md, PROJECTS.md)
+    } else {
+      console.log(`\n⚠️  Workspace already exists at: ${workspace}`);
+      const answer = await ask(rl, 'Overwrite existing files? (y/N)', 'N');
+      overwrite = answer.toLowerCase().startsWith('y');
+      overwriteProtected = overwrite;
+      if (!overwrite) {
+        console.log('\nSkipping template write. Continuing with other setup steps...');
+      }
     }
+  } else {
+    overwrite = true;
+    overwriteProtected = true;
   }
 
   // Create required dirs
@@ -297,15 +326,32 @@ async function setup() {
         .replace(/\{\{CHANNEL\}\}/g, 'direct');
     }
 
-    function copyTemplates(srcDir, destDir) {
+    function copyTemplates(srcDir, destDir, isRoot) {
       const entries = fs.readdirSync(srcDir, { withFileTypes: true });
       for (const entry of entries) {
         const src = path.join(srcDir, entry.name);
         const dest = path.join(destDir, entry.name);
         if (entry.isDirectory()) {
           fs.mkdirSync(dest, { recursive: true });
-          copyTemplates(src, dest);
+          copyTemplates(src, dest, false);
         } else {
+          // Check if this is a protected file (root level only)
+          const isProtected = isRoot && PROTECTED_FILES.includes(entry.name);
+          if (isProtected && !overwriteProtected) {
+            if (!fs.existsSync(dest)) {
+              // File doesn't exist yet — safe to create
+              try {
+                const content = fs.readFileSync(src, 'utf-8');
+                fs.writeFileSync(dest, fillTemplate(content, vars), 'utf-8');
+                console.log(`  ✅ ${path.relative(workspace, dest)}`);
+              } catch (e) {
+                console.log(`  ⚠️  ${path.relative(workspace, dest)}: ${e.message}`);
+              }
+            } else {
+              console.log(`  🔒 ${path.relative(workspace, dest)} (protected, skipped)`);
+            }
+            continue;
+          }
           try {
             const content = fs.readFileSync(src, 'utf-8');
             fs.writeFileSync(dest, fillTemplate(content, vars), 'utf-8');
@@ -317,7 +363,7 @@ async function setup() {
       }
     }
 
-    copyTemplates(TEMPLATES_DIR, workspace);
+    copyTemplates(TEMPLATES_DIR, workspace, true);
   } else {
     console.log('  ⏭️  Templates skipped (existing files preserved)');
   }
@@ -402,6 +448,9 @@ async function setup() {
     }
   }
 
+  // Record the data version so future upgrades know where to start
+  writeDataVersion(workspace, CURRENT_DATA_VERSION);
+
   console.log(`\n${separator}`);
   console.log('✅ Knight OS setup complete!\n');
   console.log(`Workspace: ${workspace}`);

package/templates/AGENTS.md

@@ -35,7 +35,30 @@ On session start, read files in this order:
 6. `memory/ai-patterns.md` (load own behavior rules)
 7. `USER.md` (load user profile)
 8. `TOOLS.md` (load available tools)
-9. `PROJECTS.md` (load project index — on-demand per project)
+9. `memory/YYYY-MM-DD.md` for today + yesterday (load recent context; skip if file doesn't exist)
+10. `PROJECTS.md` (load project index — on-demand per project)
+
+> **Why daily logs?** Without reading recent logs, the AI starts each session with no memory of what happened yesterday. Always load today + yesterday at boot.
+
+## On-Demand Loading Trigger Table
+
+Do NOT load everything at boot. Load these files only when the matching situation arises:
+
+| Trigger | Load |
+|---------|------|
+| Replying to a message / adjusting tone | `memory/ai-patterns.md` chat section |
+| Before executing a task | `memory/ai-patterns.md` exec section |
+| User mentions a project by name | `memory/projects/<name>/main.md` |
+| Executing a task tied to a project | `memory/projects/<name>/main.md` + latest log |
+| Heartbeat / daily review | `PROJECTS.md` index only (no main.md) |
+| Writing daily report | Update main.md → Current Sprint with today's progress |
+| Writing to memory / log / daily report | Check `memory/ai-patterns.md` memory section |
+| Received group message / someone @-mentioned | group handling rules |
+| Involves code / development / PR | `memory/ai-patterns.md` code section |
+| Using scripts / external tools | `memory/ai-patterns.md` tool section |
+| Writing copy / articles / presentations | `memory/user-patterns.md` writing style section |}
+
+> **Principle:** Static identity + rules → system prompt (always present). Long-term memory → load at session start. Project details + situational rules → lazy-load on demand. Per-turn context → conversation history only.
 
 ## Memory Structure Quick Reference
 

package/templates/PROJECTS.md

@@ -1,23 +1,31 @@
 # PROJECTS.md — {{AI_NAME}} Project Overview
 
-> Active projects index. Update when starting or closing a project.
-> Detailed notes → `memory/projects/<name>/main.md`
+> Active projects index. Load this file at every session start — keep it short (target: under 40 lines).
+> Full context lives in `memory/projects/<name>/main.md` — load on demand when the project is discussed.
 
 ---
 
 ## Active Projects
 
-| ID | Name | Status | Priority | Started | Note |
-|----|------|--------|----------|---------|------|
-| — | _(add your first project)_ | — | — | — | — |
+| Name | Status | Priority | One-liner |
+|------|--------|----------|-----------|
+| _(add your first project)_ | 🟢 | — | _(what is this?)_ |
+
+Status: 🟢 Active / 🟡 On Hold / 🔴 Blocked / ✅ Done
 
 ---
 
-## How to Use This File
+## Loading Rules
+
+{{AI_NAME}} follows these rules for project context:
 
-- One row per project. Keep it scannable.
-- Detail goes in `memory/projects/<name>/main.md`
-- Status: 🟢 Active / 🟡 On Hold / 🔴 Blocked / ✅ Done
+| When | Do |
+|------|----|
+| User mentions a project name | Load `memory/projects/<name>/main.md` |
+| Executing a task related to a project | Load main.md + most recent project log |
+| Heartbeat / daily review | Scan PROJECTS.md index only (no main.md) |
+| Writing daily report | Update main.md → Current Sprint section with today's progress |
+| Project not mentioned in session | Do NOT load main.md (save tokens) |
 
 ---
 
@@ -32,8 +40,8 @@ _(Move completed or abandoned projects here)_
 ```
 memory/projects/
 ├── <project-name>/
-│   ├── main.md       # Full project context (goals, decisions, roadmap)
-│   └── logs/         # Session logs specific to this project
+│   ├── main.md       # Project "workbench" — goals, current sprint, blockers, decisions
+│   └── logs/         # Deep history — load only when reviewing past decisions
 ```
 
 ### main.md template
@@ -43,18 +51,29 @@ memory/projects/
 
 **Status:** 🟢 Active
 **Started:** YYYY-MM-DD
-**Goal:** One sentence.
+**Goal:** One sentence. What does success look like?
 
-## Context
-[What is this? Why does it matter?]
+## Current Sprint / This Week
+- [ ] Task 1
+- [ ] Task 2
+_(Update this section at the end of each working session)_
+
+## Open Questions / Blockers
+- [YYYY-MM-DD] Question or blocker — owner or resolution
+
+## Next Actions (Top 3)
+1.
+2.
+3.
 
 ## Key Decisions
 - YYYY-MM-DD: [Decision and rationale]
 
-## Milestones
-- [ ] M1: [Description]
-- [ ] M2: [Description]
+## Context
+[What is this project? Why does it matter? Who is it for?]
 
-## Notes
-[Anything {{AI_NAME}} should remember between sessions]
+## Notes for {{AI_NAME}}
+[Anything the AI must remember between sessions — constraints, preferences, gotchas]
 ```
+
+> Keep main.md under 100 lines. If it grows longer, move older decisions/context to `logs/archive.md`.