clawkeep 0.1.0 → 0.2.0

package/README.md

@@ -2,11 +2,11 @@
   <img src="assets/banner.jpg" alt="ClawKeep" width="100%" />
 </p>
 
-<h1 align="center">🐾 ClawKeep</h1>
+<h1 align="center">ClawKeep</h1>
 
 <p align="center">
-  <strong>Time-travel backups for AI agents and everything else.</strong><br>
-  <sub>Every change tracked. Every version recoverable. Set it and forget it.</sub>
+  <strong>Private, encrypted backups that just work.</strong><br>
+  <sub>Zero-knowledge. Time-travel restore. Set it and forget it.</sub>
 </p>
 
 <p align="center">
@@ -19,23 +19,47 @@
 
 ## The Problem
 
-You're running an AI agent. It rewrites its own memory files, edits configs, updates state. One bad run and your agent's personality is gone. Its memory, corrupted. Its config, overwritten.
+Your files are precious. Your AI agent's memory. Your dotfiles. Your configs. Your writing.
 
-You reach for a backup. All you have is a zip from three days ago.
+One bad edit. One corrupted file. One accidental delete. Gone.
 
-**That's not enough.**
+Cloud backups? They can read your data. Time Machine? No encryption. Manual exports? You'll forget.
+
+**You need backups that are automatic, encrypted, and private.**
 
 ## The Solution
 
-ClawKeep gives your files **full version history with encrypted backups**. Every change is tracked. Every state is recoverable. Back up to a local path, S3, or (soon) ClawKeep Cloud — all encrypted, all incremental. Built on git internally, but you never touch git.
+ClawKeep gives you **continuous, encrypted backups** with full version history. Every change is captured. Every version is recoverable. Everything is **AES-256 encrypted** before it leaves your machine.
 
 ```
-clawkeep init       →  start tracking
-clawkeep watch      →  auto-backup on every change
+clawkeep init       →  start protecting a directory
+clawkeep watch      →  auto-backup every change (encrypted)
 clawkeep restore    →  go back to any point in time
 ```
 
-That's it. Three commands. Your files are protected forever.
+Three commands. Your files are protected forever. **Nobody can read them but you.**
+
+## 🔐 Privacy First
+
+ClawKeep is built on a simple principle: **your data is yours**.
+
+- **AES-256-GCM encryption** — Military-grade encryption for all backups
+- **Zero-knowledge** — Your backup target only sees numbered `.enc` chunks
+- **No file names leaked** — Directory structure, file names, everything encrypted
+- **Local-first** — Works entirely offline, no account required
+- **Open source** — Audit the code yourself
+
+```
+What your NAS/cloud sees:     What's actually inside:
+├── chunk-000001.enc          ├── MEMORY.md
+├── chunk-000002.enc          ├── config/
+├── manifest.enc              │   ├── secrets.yaml
+                              │   └── api-keys.json
+                              └── notes/
+                                  └── journal.md
+```
+
+**Your backup target learns nothing.** Not file names, not sizes, not structure. Just opaque encrypted blobs.
 
 ## Quick Start
 
@@ -44,12 +68,12 @@ npm install -g clawkeep
 ```
 
 ```bash
-cd ~/my-project
+cd ~/my-important-files
 clawkeep init
 ```
 ```
 ✔ ClawKeep initialized!
-  🐾 Directory is now version-controlled
+  🐾 Directory is now protected
   Tracked     42 files
   Backup      a8f3c2d1
 ```
@@ -59,54 +83,74 @@ clawkeep init
 clawkeep watch --daemon
 ```
 
-Done. Every file change is now automatically versioned.
+Done. Every file change is now automatically versioned and ready for encrypted backup.
 
-## Commands
+## Encrypted Backup Targets
 
-| Command | What it does |
-|---|---|
-| `clawkeep init` | Start tracking a directory |
-| `clawkeep watch` | Auto-backup on file changes. `--daemon` for background mode |
-| `clawkeep snap` | Manual backup with optional `-m "message"` |
-| `clawkeep log` | Browse your backup timeline |
-| `clawkeep restore <ref>` | Time-travel to any backup |
-| `clawkeep diff` | See what changed since last backup |
-| `clawkeep backup` | Manage encrypted backup targets (local, S3, cloud) |
-| `clawkeep backup sync` | Sync encrypted backup to target |
-| `clawkeep backup restore` | Restore from encrypted backup |
-| `clawkeep export` | AES-256 encrypted portable archive |
-| `clawkeep import` | Restore from encrypted archive |
-| `clawkeep status` | Show tracking stats |
-| `clawkeep ui` | Launch the web dashboard |
-
-## Backup Targets
-
-Choose where your data goes. Configure once, sync automatically.
+Send your encrypted backups anywhere. They can't read them anyway.
 
 ```bash
-# Set encryption password (once)
+# Set your encryption password (once)
 clawkeep backup set-password
 
-# Back up to a local path (NAS, external drive, etc.)
+# Back up to a local path (NAS, external drive, USB)
 clawkeep backup local /mnt/nas/backups
 
-# Sync (incremental — only new changes)
+# Sync — only new changes are uploaded
 clawkeep backup sync
 
 # Check backup status
 clawkeep backup status
-
-# Restore from backup
-clawkeep backup restore /mnt/nas/backups/my-workspace/
 ```
 
-All backups are **AES-256-GCM encrypted** and **incremental** — only new changes are synced after the first backup.
+Your backup target receives **encrypted chunks only**. No metadata. No history. Nothing useful without your password.
 
 | Target | Status | Description |
 |---|---|---|
-| **Local path** | ✅ Available | Encrypted chunks on any folder, NAS, or mounted drive |
-| **S3 / R2** | 🔜 Coming soon | Encrypted chunks on object storage |
-| **ClawKeep Cloud** | 🔜 Coming soon | Managed encrypted backup at clawkeep.com |
+| **Local path** | ✅ Available | Any mounted folder — NAS, USB drive, network share |
+| **S3 / R2** | ✅ Available | Object storage (Cloudflare R2, AWS S3, MinIO, Backblaze B2, Wasabi) |
+| **ClawKeep Cloud** | 🔜 Coming soon | Managed zero-knowledge backup |
+
+### S3 / R2 Setup
+
+```bash
+# Configure S3-compatible target
+clawkeep backup s3 \
+  --endpoint https://your-account.r2.cloudflarestorage.com \
+  --bucket my-backups \
+  --access-key AKIAIOSFODNN7EXAMPLE \
+  --secret-key wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY \
+  --region auto \
+  --prefix clawkeep/
+
+# Or use environment variables for credentials
+export CLAWKEEP_S3_ACCESS_KEY=your-access-key
+export CLAWKEEP_S3_SECRET_KEY=your-secret-key
+clawkeep backup s3 --endpoint https://... --bucket my-backups
+
+# Sync encrypted chunks to S3
+clawkeep backup sync
+```
+
+Works with any S3-compatible service: **Cloudflare R2** (zero egress fees), **AWS S3**, **Backblaze B2**, **MinIO**, **Wasabi**, and more.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `clawkeep init` | Start protecting a directory |
+| `clawkeep watch` | Auto-backup on file changes. `--daemon` for background |
+| `clawkeep snap` | Manual backup with optional `-m "message"` |
+| `clawkeep log` | Browse your backup timeline |
+| `clawkeep restore <ref>` | Time-travel to any backup |
+| `clawkeep diff` | See what changed since last backup |
+| `clawkeep backup` | Manage encrypted backup targets |
+| `clawkeep backup sync` | Push encrypted backup to target |
+| `clawkeep backup restore` | Restore from encrypted backup |
+| `clawkeep export` | Portable encrypted archive |
+| `clawkeep import` | Restore from encrypted archive |
+| `clawkeep status` | Show protection stats |
+| `clawkeep ui` | Launch the web dashboard |
 
 ## Web Dashboard
 
@@ -118,62 +162,20 @@ clawkeep ui --daemon --port 3333
 
 **Four tabs, everything you need:**
 
-- **◉ Dashboard** — Protection status, recent changes, pending unsaved files, quick stats
-- **↻ History** — Full backup timeline with expandable diffs, compare any two backups side-by-side
-- **☁ Backup** — Configure backup targets, sync, test connections, download encrypted exports
-- **≡ Browse** — File browser with time-travel — view any file at any point in history
+- **◉ Dashboard** — Protection status, recent changes, pending files
+- **↻ History** — Full timeline with diffs, compare any two points
+- **☁ Backup** — Configure targets, sync, download encrypted exports
+- **≡ Browse** — File browser with time-travel — view any file at any point
 
 **Also includes:**
-- 🎨 Syntax highlighting for JS, Python, Go, Rust, JSON, YAML, CSS, HTML
+- 🎨 Syntax highlighting for code files
 - ✏️ Named backups from the UI
 - ⏪ One-click restore to any backup
-- 🔐 Token-based auth, runs as a background daemon
-
-## Framework Integrations
-
-ClawKeep works with any directory, but it's especially useful for AI agent frameworks that maintain persistent state:
-
-| Framework | What to track | How to integrate |
-|---|---|---|
-| **[Clawdbot](https://github.com/clawdbot/clawdbot)** | `MEMORY.md`, `SOUL.md`, `IDENTITY.md`, config, daily notes | Heartbeat task or watch daemon. See [SKILL.md](SKILL.md) |
-| **[OpenClaw](https://github.com/openclaw)** | `.openclaw/` memory, agent state, tool configs | `clawkeep init && clawkeep watch --daemon` in agent dir |
-| **[Nanobot](https://github.com/nicholasgriffintn/nanobot)** | `nanobot.yml`, conversation history, plugins | Watch daemon on nanobot workspace |
-| **[Claude Code](https://claude.ai/code)** | `CLAUDE.md`, project context, session artifacts | `clawkeep watch --daemon` in project root |
-| **[Codex CLI](https://github.com/openai/codex)** | `codex.md`, workspace files | Watch daemon on workspace |
-| **[CrewAI](https://github.com/joaomdmoura/crewAI)** | Agent memory, task outputs, crew configs | Watch daemon on crew workspace |
-| **[AutoGPT](https://github.com/Significant-Gravitas/AutoGPT)** | Agent state, auto_gpt_workspace, memory | Watch daemon on workspace root |
-| **Generic** | Any directory with files that change | `clawkeep init && clawkeep watch --daemon` |
-
-### Agent Skill
-
-ClawKeep ships with a [SKILL.md](SKILL.md) that any AI agent can read and follow. Drop it into your agent's skills directory and it will know how to:
-
-- Initialize ClawKeep on its own workspace
-- Run watch mode or periodic backups via heartbeat
-- Restore to previous versions when something goes wrong
-- Take named backups before risky operations
-- Configure backup targets for offsite protection
-
-See [SKILL.md](SKILL.md) for the full agent-readable integration guide.
-
-## Smart Ignore
-
-ClawKeep ships with sensible defaults. Your `node_modules`, build artifacts, and caches are never tracked:
-
-```bash
-# .clawkeepignore (auto-generated)
-node_modules/
-__pycache__/
-dist/
-.env
-*.log
-```
-
-Add your own patterns. They're automatically synced to `.gitignore` — you never think about it.
+- 🔐 Token-based auth
 
 ## Watch Mode
 
-The killer feature. Background daemon that auto-backs-up on file changes:
+The killer feature. Continuous protection without thinking about it:
 
 ```bash
 # Foreground (see live output)
@@ -185,15 +187,15 @@ clawkeep watch --daemon
 # Stop the daemon
 clawkeep watch --stop
 
-# Auto-push to remote after each backup
+# Auto-sync to backup target after each change
 clawkeep watch --daemon --push
 ```
 
-Debounced writes, stability detection, smart ignore patterns. Your files are continuously versioned without any manual intervention.
+Smart debouncing, stability detection, configurable ignore patterns. Your files are continuously protected.
 
-## Restore
+## Time-Travel Restore
 
-Go back to any point in time. Your current state is preserved in history — nothing is ever lost.
+Go back to any point in time. Your current state is preserved — nothing is ever lost.
 
 ```bash
 # See the timeline
@@ -206,90 +208,97 @@ clawkeep restore abc123f
 clawkeep restore HEAD~3
 ```
 
-Restores are **non-destructive** — ClawKeep checks out the old state and creates a new backup. Your full history is always intact.
+Restores are **non-destructive** — your full history is always intact.
 
-## Compare
+## Portable Encrypted Archives
 
-See exactly what changed between any two points in time:
+Take your backups anywhere with encrypted exports:
 
-- **Dashboard:** Click "Compare" in History tab, select two backups
-- **CLI:** `clawkeep diff` shows changes since last backup
-- **API:** `GET /api/compare?from=abc123&to=def456`
+```bash
+# Create encrypted archive
+clawkeep export -p "your-password"
+# → my-project.clawkeep.enc
 
-## Encrypted by Default
+# Restore on another machine
+clawkeep import backup.clawkeep.enc -p "your-password"
+```
 
-All backups are AES-256-GCM encrypted with scrypt key derivation. Your data is opaque on the target — no file names, no git history, nothing readable. Just numbered `.enc` chunks.
+One file. Fully encrypted. Restore anywhere.
 
-```bash
-# One-off encrypted export (portable archive)
-clawkeep export -p "strong-password"
+## Built for AI Agents
 
-# Import from archive
-clawkeep import backup.clawkeep.enc -p "strong-password"
-```
+ClawKeep was originally built to protect AI agent workspaces — memory files, personality configs, conversation history. One bad inference and your agent's identity is gone.
 
-## Programmatic API
+| Framework | What to protect |
+|---|---|
+| **[Clawdbot](https://github.com/clawdbot/clawdbot)** | `MEMORY.md`, `SOUL.md`, `IDENTITY.md`, daily notes |
+| **[Claude Code](https://claude.ai/code)** | `CLAUDE.md`, project context, artifacts |
+| **[CrewAI](https://github.com/joaomdmoura/crewAI)** | Agent memory, task outputs, crew configs |
+| **[AutoGPT](https://github.com/Significant-Gravitas/AutoGPT)** | Agent state, workspace, memory |
+| **Any agent** | Memory, config, state files |
 
-```javascript
-const { ClawGit } = require('clawkeep');
+ClawKeep ships with a [SKILL.md](SKILL.md) that AI agents can read and follow autonomously.
 
-const claw = new ClawGit('/path/to/project');
-await claw.init();
+## Works for Everything
 
-// Backup
-const snap = await claw.snap('pre-deploy checkpoint');
+AI agents are the origin story, but ClawKeep protects anything:
 
-// History
-const history = await claw.log(10);
+- **Dotfiles** — `~/.config`, shell rc files, SSH configs
+- **Writing** — Manuscripts, notes, journals
+- **Configs** — Server configs, infrastructure as code
+- **Development** — Project files, local databases
+- **Any directory** — If it changes, ClawKeep can protect it
 
-// Diff between any two backups
-const changes = await claw.diffBetween('abc123', 'def456');
+## Smart Ignore
 
-// Restore
-await claw.restore('abc123');
+Sensible defaults out of the box:
 
-// Time-travel file browsing
-const files = await claw.listFilesAtCommit('abc123', 'memory/');
-const content = await claw.showFileAtCommit('abc123', 'MEMORY.md');
+```bash
+# .clawkeepignore (auto-generated)
+node_modules/
+__pycache__/
+dist/
+.env
+*.log
 ```
 
-## Built for AI Agents, Works for Everything
+Add your own patterns. Large files and build artifacts stay out automatically.
 
-ClawKeep was built because AI agents break their own files. But it works for anything:
+## Programmatic API
 
-- **AI agent memory & config** — the original use case
-- **Dotfiles** — version your shell config without thinking
-- **Writing projects** — every draft saved, every version recoverable
-- **Config management** — track infrastructure config changes over time
-- **Any directory** — if files change, ClawKeep can track them
+```javascript
+const { ClawKeep } = require('clawkeep');
 
-## Why Not Just Git?
+const claw = new ClawKeep('/path/to/project');
+await claw.init();
 
-You *could* set up git, write a cron job, handle `.gitignore`, remember to commit, deal with merge conflicts, configure remotes...
+// Create backup
+const snap = await claw.snap('before risky changes');
 
-Or you could run `clawkeep watch --daemon` and never think about it again.
+// Browse history
+const history = await claw.log(10);
 
-| | Raw git | ClawKeep |
-|---|---|---|
-| Setup | Multiple commands | `clawkeep init` |
-| Auto-backup | DIY cron/hooks | `clawkeep watch --daemon` |
-| Ignore patterns | Manual `.gitignore` | Auto-managed `.clawkeepignore` |
-| Time travel | `git checkout` / `git stash` | `clawkeep restore` |
-| Visual history | External GUI needed | Built-in web dashboard |
-| Backup targets | Manual remote config | `clawkeep backup local /path` (encrypted) |
-| Encrypted export | Not built-in | `clawkeep export` |
-| Learning curve | Steep | Three commands |
+// Restore
+await claw.restore('abc123');
 
-ClawKeep *is* git underneath. You get all the power with none of the ceremony.
+// Time-travel file access
+const oldContent = await claw.showFileAtCommit('abc123', 'config.yaml');
+```
 
 ## Roadmap
 
-- [ ] `clawkeep.com` — hosted dashboard & remote storage
-- [ ] S3/R2 backend support
+- [x] S3 / R2 / MinIO backend
+- [ ] `clawkeep.com` — zero-knowledge cloud backup
+- [ ] End-to-end encrypted team sharing
 - [ ] Webhooks on file changes
-- [ ] Multi-directory sync
-- [ ] Team sharing & access control
+- [ ] Mobile app for backup status
 
 ## License
 
 MIT — [ClawKeep](https://clawkeep.com) 🐾
+
+---
+
+<p align="center">
+  <strong>Your files. Your encryption keys. Your privacy.</strong>
+</p>

package/bin/clawkeep.js

@@ -89,12 +89,29 @@ program
   .description('Manage backup target (local, cloud, s3, git)')
   .option('-d, --dir <path>', 'Target directory', '.')
   .option('-p, --password <pass>', 'Encryption password (or CLAWKEEP_PASSWORD env)')
+  .option('--endpoint <url>', 'S3 endpoint URL')
+  .option('--bucket <name>', 'S3 bucket name')
+  .option('--access-key <key>', 'S3 access key ID')
+  .option('--secret-key <key>', 'S3 secret access key')
+  .option('--region <region>', 'S3 region (default: auto)')
+  .option('--prefix <prefix>', 'S3 key prefix')
   .action((subcommand, targetPath, opts) => {
     opts.args = targetPath ? [targetPath] : [];
     opts.path = targetPath;
     require('../src/commands/backup')(subcommand, opts.args, opts);
   });
 
+// cloud
+program
+  .command('cloud [subcommand]')
+  .description('Connect to ClawKeep Cloud')
+  .option('-d, --dir <path>', 'Target directory', '.')
+  .option('--api-key <key>', 'API key (headless)')
+  .option('--workspace <id>', 'Workspace ID (headless)')
+  .option('--endpoint <url>', 'API endpoint')
+  .option('-p, --password <pass>', 'Encryption password')
+  .action((sub, opts) => require('../src/commands/cloud')(sub, opts));
+
 // watch
 program
   .command('watch')

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "clawkeep",
-  "version": "0.1.0",
-  "description": "Git-backed memory persistence for AI agents. Your agent's memory deserves version control.",
+  "version": "0.2.0",
+  "description": "Private, encrypted backups with time-travel restore. Zero-knowledge protection for AI agents, configs, and everything you care about.",
   "main": "src/index.js",
   "bin": {
     "clawkeep": "./bin/clawkeep.js"

package/src/commands/backup.js

@@ -69,7 +69,7 @@ async function showStatus(bm) {
     }
 
     // Encryption status
-    if (cfg.target === 'local') {
+    if (cfg.target === 'local' || cfg.target === 's3' || cfg.target === 'cloud') {
       console.log(`  Encrypted:   ${cfg.passwordSet ? chalk.green('\u2713 yes') : chalk.yellow('\u26a0 password not set')}`);
       if (cfg.chunkCount > 0) {
         console.log(`  Chunks:      ${cfg.chunkCount}`);
@@ -106,6 +106,21 @@ async function setTarget(bm, typeOrArgs, opts) {
       process.exit(1);
     }
     options.url = url;
+  } else if (type === 's3') {
+    const endpoint = opts.endpoint || process.env.CLAWKEEP_S3_ENDPOINT;
+    const bucket = opts.bucket || process.env.CLAWKEEP_S3_BUCKET;
+    const accessKey = opts.accessKey || process.env.CLAWKEEP_S3_ACCESS_KEY;
+    const secretKey = opts.secretKey || process.env.CLAWKEEP_S3_SECRET_KEY;
+    const region = opts.region || process.env.CLAWKEEP_S3_REGION || 'auto';
+    const prefix = opts.prefix || process.env.CLAWKEEP_S3_PREFIX || '';
+
+    if (!endpoint || !bucket || !accessKey || !secretKey) {
+      console.error(chalk.red('  Missing S3 config. Required: --endpoint, --bucket, --access-key, --secret-key'));
+      console.error(chalk.dim('  Or use env vars: CLAWKEEP_S3_ENDPOINT, CLAWKEEP_S3_BUCKET, CLAWKEEP_S3_ACCESS_KEY, CLAWKEEP_S3_SECRET_KEY'));
+      process.exit(1);
+    }
+
+    options = { endpoint, bucket, accessKey, secretKey, region, prefix };
   }
 
   const spinner = ora('Setting up backup target...').start();
@@ -123,8 +138,8 @@ async function setTarget(bm, typeOrArgs, opts) {
       console.log(`  ${chalk.yellow('\u26a0')} ${test.message}`);
     }
 
-    // Remind about password for local targets
-    if (type === 'local' && !bm.hasPassword()) {
+    // Remind about password for encrypted targets
+    if ((type === 'local' || type === 's3' || type === 'cloud') && !bm.hasPassword()) {
       console.log('');
       console.log(chalk.yellow('  \u26a0 Set a password before syncing:'));
       console.log(chalk.dim('  $ clawkeep backup set-password'));
@@ -161,9 +176,10 @@ async function doSetPassword(bm, opts) {
 
 async function doSync(bm, opts) {
   const cfg = bm.getConfig();
-  const password = cfg.target === 'local' ? getPassword(opts) : null;
+  const needsPassword = cfg.target === 'local' || cfg.target === 's3' || cfg.target === 'cloud';
+  const password = needsPassword ? getPassword(opts) : null;
 
-  if (cfg.target === 'local' && !password) {
+  if (needsPassword && !password) {
     console.error(chalk.red('  Password required for encrypted sync.'));
     console.error(chalk.dim('  Use: CLAWKEEP_PASSWORD=xxx clawkeep backup sync'));
     process.exit(1);