knight-os 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) {{YEAR}} {{AUTHOR}}
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,194 @@
+# knight-os
+
+AI companion OS for OpenClaw — memory, reflection, and identity framework.
+
+Give your OpenClaw AI a name, a personality, and the ability to learn from experience.
+
+## Prerequisites
+
+Install [OpenClaw](https://github.com/openclaw/openclaw) first:
+
+```bash
+npm install -g openclaw
+```
+
+## Install
+
+```bash
+npm install -g knight-os
+```
+
+## Quick Start
+
+```bash
+knight setup
+```
+
+The setup wizard will:
+
+1. Verify OpenClaw is installed
+2. Ask for your AI's name, your name, and timezone
+3. Write all framework files into your OpenClaw workspace
+4. Optionally configure Telegram notifications
+5. Register the Heartbeat scheduler (macOS/Linux)
+
+After setup, start chatting via OpenClaw:
+
+```bash
+openclaw chat
+```
+
+### Custom workspace path
+
+If your OpenClaw workspace is not at the default `~/.openclaw/workspace`, enter your path when prompted:
+
+```
+Workspace directory [~/.openclaw/workspace]: /workspace/projects
+```
+
+Knight OS will write all files there and OpenClaw will pick them up automatically.
+
+---
+
+## How Memory Works
+
+This is the core of what knight-os adds. Your AI learns from experience through a simple loop:
+
+```
+You finish a task
+    ↓
+write-reflection.py  →  memory/reflections/YYYY-MM-DD.jsonl
+    ↓
+Heartbeat runs  →  reflection-analyzer.py  →  candidate rules extracted
+    ↓
+You confirm  →  rules written to memory/ai-patterns.md
+    ↓
+Next session  →  ai-patterns.md loaded in system prompt  →  AI behaves better
+```
+
+**In practice:**
+
+```bash
+# After completing any task, run:
+python3 ~/.openclaw/workspace/scripts/write-reflection.py \
+  --context "Deployed new feature" \
+  --what_worked "Clear requirements helped" \
+  --what_failed "Forgot to update tests" \
+  --next_time "Write tests first, then implement"
+
+# Every 6 hours (automatic), the heartbeat:
+#   1. Scans reflections for repeated failure patterns
+#   2. Extracts candidate rules
+#   3. Notifies you (if Telegram configured)
+
+# You review and add confirmed rules to:
+#   ~/.openclaw/workspace/memory/ai-patterns.md
+```
+
+Over time, `ai-patterns.md` accumulates rules your AI uses automatically in every session.
+
+---
+
+## Memory File Structure
+
+```
+~/.openclaw/workspace/
+├── SOUL.md              # AI identity and personality
+├── AGENTS.md            # Boot sequence, behavior norms, script reference
+├── MEMORY.md            # Long-term memory index
+├── REDLINES.md          # Safety boundaries
+├── USER.md              # Your profile and preferences
+├── TOOLS.md             # Tool reference and credentials map
+├── PROJECTS.md          # Active project index
+├── HEARTBEAT.md         # Heartbeat task configuration
+├── memory/
+│   ├── ai-patterns.md        # Learned behavior rules (grows over time)
+│   ├── user-patterns.md      # Observed user behavior
+│   ├── reflections/          # Task reflection logs (JSONL)
+│   ├── logs/                 # Session logs
+│   └── projects/<name>/      # Per-project context
+└── scripts/
+    ├── write-reflection.py   # Log a reflection after task completion
+    ├── reflection-analyzer.py # Extract rules from reflection patterns
+    ├── heartbeat.py          # Periodic maintenance tasks
+    ├── compress-memory.py    # Archive old logs
+    └── knight-status.py      # Workspace health check
+```
+
+---
+
+## Commands
+
+```bash
+knight setup      # Configure Knight OS (requires OpenClaw installed)
+knight init       # Initialize workspace standalone (no OpenClaw check)
+knight chat       # Interactive AI chat (Anthropic API directly)
+knight status     # Check workspace file status
+knight version    # Show version
+```
+
+### Standalone chat (`knight chat`)
+
+If you want to chat without OpenClaw, you can use the built-in chat command.  
+Requires `ANTHROPIC_API_KEY` in your workspace `.env`.
+
+---
+
+## Runtime Scripts
+
+```bash
+# Log a reflection after completing a task
+python3 scripts/write-reflection.py \
+  --context "Task title" \
+  --what_worked "What went well" \
+  --what_failed "What did not work" \
+  --next_time "How to improve"
+
+# Analyze reflection patterns (run by heartbeat automatically)
+python3 scripts/reflection-analyzer.py --min-count 2
+
+# Check workspace health
+python3 scripts/knight-status.py
+
+# Archive old logs
+python3 scripts/compress-memory.py --execute
+
+# Run heartbeat manually
+python3 scripts/heartbeat.py
+```
+
+---
+
+## Core Principles
+
+### Framework & Content Separation
+
+knight-os provides the **structure** — the files, the rules, the mechanisms.  
+You provide the **content** — your AI's personality, your preferences, your specific tools.
+
+### Learning from Feedback
+
+The system evolves. Corrections become rules (`ai-patterns.md`), observations become understanding (`user-patterns.md`), decisions become memory (`MEMORY.md`). Nothing is static.
+
+### Memory Layering
+
+| Layer | Location | When promoted |
+|-------|----------|--------------|
+| Working | In-context (current session) | — |
+| Short-term | `memory/YYYY-MM-DD.md` | End of session |
+| Long-term | `MEMORY.md` | Pattern repeats 3+ times or user confirms |
+| Patterns | `memory/ai-patterns.md` | After reflection analysis + confirmation |
+
+---
+
+## Contributing
+
+Contributions welcome. Keep templates generic — no personal data or tool credentials.
+
+1. Fork this repository
+2. Create a feature branch
+3. Submit a pull request
+
+## License
+
+MIT

package/bin/knight.js

@@ -0,0 +1,253 @@
+#!/usr/bin/env node
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+const { loadConfig, resolveWorkspace } = require('../src/config');
+const { chat } = require('../src/chat');
+const { setup } = require('../src/setup');
+
+const VERSION = '0.1.0';
+const DEFAULT_WORKSPACE = path.join(process.env.HOME || '~', '.openclaw', 'workspace');
+const TEMPLATES_DIR = path.join(__dirname, '..', 'templates');
+
+function ask(rl, question) {
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => resolve(answer.trim()));
+  });
+}
+
+function getAllTemplateFiles(dir, base) {
+  base = base || dir;
+  let results = [];
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results = results.concat(getAllTemplateFiles(fullPath, base));
+    } else {
+      results.push(path.relative(base, fullPath));
+    }
+  }
+  return results;
+}
+
+function replacePlaceholders(content, vars) {
+  return content
+    .replace(/\{\{AI_NAME\}\}/g, vars.aiName)
+    .replace(/\{\{USER_NAME\}\}/g, vars.userName)
+    .replace(/\{\{TIMEZONE\}\}/g, vars.timezone)
+    .replace(/\{\{LANGUAGE\}\}/g, vars.language || 'en')
+    .replace(/\{\{CHANNEL\}\}/g, vars.channel || 'direct');
+}
+
+async function commandInit() {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  console.log('\n🐉 Knight OS — OpenClaw Workspace Initializer\n');
+
+  const aiName = await ask(rl, "Your AI companion's name? (e.g. Aria, Nova, Kai): ");
+  if (!aiName) {
+    console.log('AI name is required.');
+    rl.close();
+    process.exit(1);
+  }
+
+  const userName = await ask(rl, 'Your name? (used to personalize the workspace): ');
+  if (!userName) {
+    console.log('Your name is required.');
+    rl.close();
+    process.exit(1);
+  }
+
+  const timezone = await ask(rl, 'Your timezone? (e.g. Asia/Tokyo, America/New_York): ');
+  if (!timezone) {
+    console.log('Timezone is required.');
+    rl.close();
+    process.exit(1);
+  }
+
+  const workspaceInput = await ask(rl, `Workspace directory? [${DEFAULT_WORKSPACE}]: `);
+  const workspace = workspaceInput || DEFAULT_WORKSPACE;
+
+  const apiKeyInput = await ask(
+    rl,
+    'Anthropic API key? (starts with sk-ant-, leave blank to skip): '
+  );
+
+  const modelInput = await ask(rl, 'Default model? [claude-sonnet-4-5]: ');
+  const modelName = modelInput || 'claude-sonnet-4-5';
+
+  console.log('\n--- Preview ---');
+  console.log(`  AI Name:    ${aiName}`);
+  console.log(`  User Name:  ${userName}`);
+  console.log(`  Timezone:   ${timezone}`);
+  console.log(`  Workspace:  ${workspace}`);
+  console.log(`  Model:      ${modelName}`);
+  if (apiKeyInput) console.log(`  API Key:    ${apiKeyInput.slice(0, 12)}...`);
+  console.log('---------------\n');
+
+  const confirm = await ask(rl, 'Press Enter to confirm, or type "no" to cancel: ');
+  if (confirm.toLowerCase() === 'no') {
+    console.log('Cancelled.');
+    rl.close();
+    process.exit(0);
+  }
+
+  rl.close();
+
+  const vars = { aiName, userName, timezone };
+  const templateFiles = getAllTemplateFiles(TEMPLATES_DIR);
+
+  fs.mkdirSync(workspace, { recursive: true });
+
+  let written = 0;
+  let skipped = 0;
+
+  for (const relPath of templateFiles) {
+    const srcPath = path.join(TEMPLATES_DIR, relPath);
+    const destPath = path.join(workspace, relPath);
+    const destDir = path.dirname(destPath);
+
+    fs.mkdirSync(destDir, { recursive: true });
+
+    if (fs.existsSync(destPath)) {
+      const rlConfirm = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+      });
+      const overwrite = await ask(rlConfirm, `  File exists: ${relPath} — overwrite? [y/N]: `);
+      rlConfirm.close();
+      if (overwrite.toLowerCase() !== 'y') {
+        skipped++;
+        continue;
+      }
+    }
+
+    const content = fs.readFileSync(srcPath, 'utf-8');
+    const processed = replacePlaceholders(content, vars);
+    fs.writeFileSync(destPath, processed, 'utf-8');
+    written++;
+  }
+
+  if (apiKeyInput) {
+    const envPath = path.join(workspace, '.env');
+    const envLine = `ANTHROPIC_API_KEY=${apiKeyInput}\n`;
+    if (fs.existsSync(envPath)) {
+      fs.appendFileSync(envPath, envLine, 'utf-8');
+    } else {
+      fs.writeFileSync(envPath, envLine, 'utf-8');
+    }
+  }
+
+  const configPath = path.join(workspace, 'knight.config.json');
+  let existingConfig = {};
+  if (fs.existsSync(configPath)) {
+    try {
+      existingConfig = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    } catch {}
+  }
+  existingConfig.model = {
+    provider: 'anthropic',
+    name: modelName,
+    max_tokens: 8096,
+    system_prompt_files: ['SOUL.md', 'AGENTS.md', 'MEMORY.md', 'REDLINES.md'],
+  };
+  fs.writeFileSync(configPath, JSON.stringify(existingConfig, null, 2) + '\n', 'utf-8');
+
+  console.log(`\n✅ Workspace initialized at ${workspace}`);
+  console.log(`   ${written} file(s) written, ${skipped} skipped.\n`);
+  console.log('Next steps:');
+  console.log(`  1. Review your workspace files in ${workspace}`);
+  console.log('  2. Customize SOUL.md and USER.md to match your preferences');
+  console.log('  3. Run \`knight chat\` to start talking to your AI companion');
+  console.log('');
+}
+
+function commandStatus() {
+  const workspace = DEFAULT_WORKSPACE;
+  const requiredFiles = [
+    'AGENTS.md',
+    'SOUL.md',
+    'MEMORY.md',
+    'HEARTBEAT.md',
+    'REDLINES.md',
+    'USER.md',
+    'TOOLS.md',
+    'memory/ai-patterns.md',
+    'memory/user-patterns.md',
+  ];
+
+  console.log(`\n📋 Knight OS — Workspace Status`);
+  console.log(`   Directory: ${workspace}\n`);
+
+  if (!fs.existsSync(workspace)) {
+    console.log('   ❌ Workspace directory does not exist.');
+    console.log('   Run "knight init" to create it.\n');
+    process.exit(1);
+  }
+
+  let ok = 0;
+  let missing = 0;
+
+  for (const file of requiredFiles) {
+    const fullPath = path.join(workspace, file);
+    if (fs.existsSync(fullPath)) {
+      console.log(`   ✅ ${file}`);
+      ok++;
+    } else {
+      console.log(`   ❌ ${file}`);
+      missing++;
+    }
+  }
+
+  console.log(`\n   Result: ${ok} present, ${missing} missing.\n`);
+}
+
+function commandVersion() {
+  console.log(`knight-os v${VERSION}`);
+}
+
+async function commandChat() {
+  const config = loadConfig();
+  const workspace = resolveWorkspace(config);
+  await chat(config, workspace);
+}
+
+const command = process.argv[2];
+
+switch (command) {
+  case 'setup':
+    setup();
+    break;
+  case 'init':
+    commandInit();
+    break;
+  case 'chat':
+    commandChat();
+    break;
+  case 'status':
+    commandStatus();
+    break;
+  case 'version':
+  case '--version':
+  case '-v':
+    commandVersion();
+    break;
+  default:
+    console.log(`knight-os v${VERSION}`);
+    console.log('\nUsage: knight <command>\n');
+    console.log('Commands:');
+    console.log('  setup     Configure Knight OS for an existing OpenClaw installation');
+    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('  version   Show version number');
+    console.log('');
+    break;
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "knight-os",
+  "version": "0.1.0",
+  "description": "AI companion OS for OpenClaw — memory, reflection, and identity framework",
+  "main": "bin/knight.js",
+  "bin": {
+    "knight": "./bin/knight.js"
+  },
+  "scripts": {
+    "test": "node bin/knight.js version"
+  },
+  "keywords": [
+    "openclaw",
+    "ai",
+    "workspace",
+    "agent",
+    "memory",
+    "reflection",
+    "identity",
+    "llm"
+  ],
+  "author": "Steve Wang <iloveopt@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/iloveopt/knight-os.git"
+  },
+  "homepage": "https://github.com/iloveopt/knight-os#readme",
+  "bugs": {
+    "url": "https://github.com/iloveopt/knight-os/issues"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "scripts/",
+    "templates/",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/scripts/compress-memory.py

@@ -0,0 +1,147 @@
+#!/usr/bin/env python3
+"""
+compress-memory.py — Archive and compress old log files.
+
+Usage:
+  python3 scripts/compress-memory.py             # Dry-run by default (report only)
+  python3 scripts/compress-memory.py --dry-run   # Explicit dry-run
+  python3 scripts/compress-memory.py --execute   # Actually move files to archive
+  python3 scripts/compress-memory.py --days 14   # Keep only last 14 days (default: 30)
+  python3 scripts/compress-memory.py --threshold 200  # Line threshold (default: 500)
+
+Scans {workspace}/memory/logs/ and archives files older than --days into memory/logs/archive/.
+"""
+
+import json
+import os
+import sys
+import argparse
+import shutil
+from datetime import datetime, timezone, timedelta
+from pathlib import Path
+
+
+def load_config():
+    config_paths = [
+        Path.cwd() / "knight.config.json",
+        Path.home() / ".knight" / "config.json",
+    ]
+    for p in config_paths:
+        if p.exists():
+            try:
+                return json.loads(p.read_text())
+            except (json.JSONDecodeError, OSError):
+                pass
+    return {}
+
+
+def resolve_workspace(config):
+    ws = config.get("workspace", "~/.openclaw/workspace")
+    return Path(ws).expanduser()
+
+
+def scan_logs(logs_dir: Path):
+    """Scan log files and return stats."""
+    files = []
+    total_lines = 0
+    total_size = 0
+
+    for f in sorted(logs_dir.iterdir()):
+        if f.is_file() and f.suffix in (".md", ".log", ".jsonl", ".txt"):
+            size = f.stat().st_size
+            mtime = datetime.fromtimestamp(f.stat().st_mtime, tz=timezone.utc)
+            try:
+                lines = sum(1 for _ in open(f, encoding="utf-8", errors="ignore"))
+            except OSError:
+                lines = 0
+
+            files.append({
+                "path": f,
+                "name": f.name,
+                "size": size,
+                "lines": lines,
+                "mtime": mtime,
+            })
+            total_lines += lines
+            total_size += size
+
+    return files, total_lines, total_size
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Archive and compress old log files.")
+    parser.add_argument("--dry-run", action="store_true", default=True, help="Report only (default)")
+    parser.add_argument("--execute", action="store_true", help="Actually archive old files")
+    parser.add_argument("--days", type=int, default=30, help="Keep files from last N days (default: 30)")
+    parser.add_argument("--threshold", type=int, default=500, help="Line count threshold for warning (default: 500)")
+    args = parser.parse_args()
+
+    if args.execute:
+        args.dry_run = False
+
+    config = load_config()
+    workspace = resolve_workspace(config)
+    local_cfg = config.get("storage", {}).get("local", {})
+    logs_dir = workspace / local_cfg.get("logs_dir", "memory/logs")
+
+    print(f"[knight] Memory compression — scanning {logs_dir}")
+
+    if not logs_dir.exists():
+        print(f"  Logs directory does not exist: {logs_dir}")
+        print("  Nothing to compress.")
+        return
+
+    files, total_lines, total_size = scan_logs(logs_dir)
+    size_mb = total_size / (1024 * 1024)
+
+    print(f"  Found {len(files)} log files")
+    print(f"  Total: {total_lines} lines, {size_mb:.2f} MB")
+
+    if total_lines <= args.threshold:
+        print(f"  Below threshold ({args.threshold} lines) — no compression needed.")
+        return
+
+    print(f"  Above threshold ({args.threshold} lines) — compression recommended.")
+
+    cutoff = datetime.now(timezone.utc) - timedelta(days=args.days)
+    to_archive = [f for f in files if f["mtime"] < cutoff]
+    to_keep = [f for f in files if f["mtime"] >= cutoff]
+
+    archive_lines = sum(f["lines"] for f in to_archive)
+    archive_size = sum(f["size"] for f in to_archive)
+
+    print(f"\n  Archive candidates (older than {args.days} days):")
+    print(f"    {len(to_archive)} files, {archive_lines} lines, {archive_size / 1024:.1f} KB")
+    print(f"  Keeping (recent {args.days} days):")
+    print(f"    {len(to_keep)} files, {sum(f['lines'] for f in to_keep)} lines")
+
+    if not to_archive:
+        print("\n  No files old enough to archive.")
+        return
+
+    if args.dry_run:
+        print("\n  [dry-run] Files that would be archived:")
+        for f in to_archive[:10]:
+            print(f"    {f['name']} ({f['lines']} lines, {f['mtime'].strftime('%Y-%m-%d')})")
+        if len(to_archive) > 10:
+            print(f"    ... and {len(to_archive) - 10} more")
+        print("\n  Run with --execute to perform archival.")
+        return
+
+    archive_dir = logs_dir / "archive"
+    archive_dir.mkdir(parents=True, exist_ok=True)
+
+    moved = 0
+    for f in to_archive:
+        dest = archive_dir / f["name"]
+        if dest.exists():
+            dest = archive_dir / f"{f['path'].stem}_{f['mtime'].strftime('%Y%m%d')}{f['path'].suffix}"
+        shutil.move(str(f["path"]), str(dest))
+        moved += 1
+
+    print(f"\n  Archived {moved} files to {archive_dir}")
+    print(f"  Freed {archive_lines} lines, {archive_size / 1024:.1f} KB")
+
+
+if __name__ == "__main__":
+    main()