mindkeeper-openclaw 0.2.16 → 0.2.18

package/README.md

@@ -0,0 +1,54 @@
+# mindkeeper-openclaw
+
+**Time Machine for Your AI's Brain** — OpenClaw plugin that gives your AI version control for agent context files.
+
+Every change to AGENTS.md, SOUL.md, MEMORY.md, skills, and more is automatically tracked. Your AI can browse history, compare versions, create checkpoints, and roll back any file.
+
+## Install
+
+```bash
+openclaw plugins install mindkeeper-openclaw
+```
+
+Restart your Gateway once. The plugin auto-starts a background watcher and registers 5 tools.
+
+## Talk to Your AI
+
+Once installed, ask in natural language:
+
+- *"What changed in SOUL.md recently?"*
+- *"Compare my current AGENTS.md to last week's version"*
+- *"Roll back SOUL.md to yesterday"*
+- *"Save a checkpoint called 'perfect-personality' before I experiment"*
+
+## Agent Tools
+
+| Tool | What It Does |
+|------|--------------|
+| `mind_history` | Browse change history for any tracked file |
+| `mind_diff` | Compare any two versions with full unified diff |
+| `mind_rollback` | Two-step rollback: preview first, then execute after confirmation |
+| `mind_snapshot` | Create named checkpoints before risky changes |
+| `mind_status` | Show what files are tracked and what's changed |
+
+## OpenClaw CLI
+
+```bash
+openclaw mind status              # See what's tracked and pending
+openclaw mind history SOUL.md     # Browse SOUL.md change history
+openclaw mind snapshot stable-v2  # Save a named checkpoint
+```
+
+## Requirements
+
+- Node.js ≥ 22
+- OpenClaw with Gateway running
+
+## Links
+
+- [GitHub](https://github.com/seekcontext/mindkeeper)
+- [Core CLI](https://www.npmjs.com/package/mindkeeper) — Standalone version without OpenClaw
+
+## License
+
+MIT

package/dist/index.js

@@ -956,10 +956,13 @@ var Watcher = class {
     try {
       const content = await import_promises4.default.readFile(this.lockfilePath, "utf-8");
       const pid = parseInt(content.trim(), 10);
-      if (!isNaN(pid) && isProcessRunning(pid)) {
-        throw new Error(
-          `Another watcher is already running (PID: ${pid}). Stop it first or remove ${this.lockfilePath} if the process is dead.`
-        );
+      if (!isNaN(pid)) {
+        if (pid === process.pid) {
+        } else if (isProcessRunning(pid)) {
+          throw new Error(
+            `Another watcher is already running (PID: ${pid}). Stop it first or remove ${this.lockfilePath} if the process is dead.`
+          );
+        }
       }
     } catch (err) {
       if (err instanceof Error && err.message.includes("Another watcher")) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mindkeeper-openclaw",
-  "version": "0.2.16",
+  "version": "0.2.18",
   "description": "OpenClaw plugin for mindkeeper: auto-snapshot, diff, and rollback for agent context files",
   "keywords": [
     "openclaw",
@@ -26,7 +26,8 @@
     "dist",
     "skills",
     "openclaw.plugin.json",
-    "scripts/postinstall-merge-config.cjs"
+    "scripts/postinstall-merge-config.cjs",
+    "README.md"
   ],
   "scripts": {
     "build": "node build.mjs",

package/skills/mindkeeper/README.md

@@ -0,0 +1,48 @@
+# Mindkeeper Skill
+
+Time Machine for Your AI's Brain — version control for agent context files. This skill teaches your AI to use mindkeeper tools for history, diff, rollback, and snapshots.
+
+**Drop-in setup:** Add this skill alone — the AI will automatically install the mindkeeper-openclaw plugin and restart the Gateway when you first ask for mindkeeper capability. No manual steps required.
+
+## What It Does
+
+- **Browse history** — See what changed in SOUL.md, AGENTS.md, or any tracked file
+- **Compare versions** — Full unified diff between any two commits
+- **Rollback** — Restore any file to a previous version (with preview + confirmation)
+- **Named snapshots** — Create checkpoints before risky changes
+
+## Requirements
+
+- Node.js ≥ 22
+- OpenClaw with Gateway running
+
+The mindkeeper-openclaw plugin is installed automatically by the AI when you first use mindkeeper (see Bootstrap in SKILL.md).
+
+## How to Use
+
+1. Install this skill: `clawhub install mindkeeper`
+2. Ask your AI in natural language (plugin install + restart happen automatically on first use):
+   - "What changed in SOUL.md recently?"
+   - "Compare my current AGENTS.md to last week's version"
+   - "Roll back SOUL.md to yesterday"
+   - "Save a checkpoint called 'perfect-personality' before I experiment"
+
+## Examples
+
+| User says | AI action |
+|-----------|------------|
+| "What changed in SOUL.md?" | `mind_history` with file filter |
+| "Show me the diff from last week" | `mind_history` → find commit → `mind_diff` |
+| "Undo that change" | `mind_rollback` (preview first, then execute) |
+| "Save a checkpoint before I experiment" | `mind_snapshot` with descriptive name |
+
+## Troubleshooting
+
+- **History is empty** — Call `mind_status` to check if mindkeeper is initialized. Make a small edit to a tracked file to trigger the first snapshot.
+- **Tools not found** — Ensure the mindkeeper-openclaw plugin is installed and Gateway has been restarted.
+- **Rollback not applying** — After rollback, tell the user to run `/new` to reload the session with the restored file.
+
+## Links
+
+- [mindkeeper on GitHub](https://github.com/seekcontext/mindkeeper)
+- [mindkeeper-openclaw on npm](https://www.npmjs.com/package/mindkeeper-openclaw)

package/skills/mindkeeper/SCREENSHOT_GUIDELINE.md

@@ -0,0 +1,182 @@
+# Screenshot Preparation Guideline for ClawHub
+
+This guide walks you through preparing the environment and demo data before taking screenshots for the mindkeeper skill listing on ClawHub.
+
+See [CLAWHUB_PUBLISH.md](../../../../CLAWHUB_PUBLISH.md) for the full publishing workflow.
+
+## Prerequisites
+
+- **Node.js** ≥ 22
+- **OpenClaw** installed and configured
+- **Gateway** running (e.g. `openclaw start` or desktop app)
+- A **workspace** with agent context files (SOUL.md, AGENTS.md, etc.)
+
+---
+
+## Phase 1: Environment Setup
+
+### 1.1 Install mindkeeper plugin
+
+```bash
+openclaw plugins install mindkeeper-openclaw
+```
+
+Restart the Gateway so the plugin loads and the mind_* tools become available.
+
+### 1.2 Identify your workspace
+
+mindkeeper tracks files in your OpenClaw workspace. Typical locations:
+
+- `~/.openclaw/workspace/` (default)
+- Or the workspace configured in `~/.openclaw/openclaw.json`
+
+Ensure the workspace contains at least:
+
+- `SOUL.md`
+- `AGENTS.md` (optional but helpful)
+
+If these files don't exist, create minimal placeholder content:
+
+```bash
+# Example: create SOUL.md
+echo "# Agent Personality" > ~/.openclaw/workspace/SOUL.md
+echo "You are a helpful assistant." >> ~/.openclaw/workspace/SOUL.md
+```
+
+### 1.3 Verify mindkeeper is running
+
+```bash
+openclaw mind status
+```
+
+You should see workspace path, pending changes count, and named snapshots. The plugin uses your configured OpenClaw workspace automatically.
+
+---
+
+## Phase 2: Build Demo History
+
+mindkeeper auto-snapshots after changes with a **30-second debounce**. Plan edits with gaps or wait ~30s between edits.
+
+### 2.1 Create initial history (Day 1 simulation)
+
+**Edit 1** — Add content to SOUL.md:
+
+```markdown
+# Agent Personality
+
+You are a helpful assistant. You prefer concise answers.
+```
+
+Save and wait **≥30 seconds** for the auto-snapshot to run (mindkeeper debounces changes).
+
+**Edit 2** — Change SOUL.md:
+
+```markdown
+# Agent Personality
+
+You are a helpful assistant. You prefer concise answers and use markdown when useful.
+```
+
+Save and wait **≥30 seconds**.
+
+**Edit 3** — Add more:
+
+```markdown
+# Agent Personality
+
+You are a helpful assistant. You prefer concise answers and use markdown when useful.
+You avoid being overly verbose.
+```
+
+Save and wait **≥30 seconds**.
+
+### 2.2 Create a named snapshot (for Screenshot 3)
+
+```bash
+openclaw mind snapshot before-experiment
+```
+
+Or ask the AI: "Save a checkpoint called 'before-experiment' before I make changes."
+
+### 2.3 Verify history exists
+
+```bash
+openclaw mind history SOUL.md
+```
+
+You should see at least 3–4 commits with short hashes (e.g. `a1b2c3d4`). Note one or two hashes for the diff example.
+
+---
+
+## Phase 3: Screenshot Checklist
+
+Before taking screenshots, confirm:
+
+- [ ] Gateway is running
+- [ ] mindkeeper plugin is installed and loaded
+- [ ] `openclaw mind status` shows workspace and tracked info
+- [ ] `openclaw mind history SOUL.md` shows at least 3 commits
+- [ ] You have a named snapshot (e.g. `before-experiment`)
+- [ ] Screen resolution is 1920×1080 or 1280×720
+- [ ] UI is clean (close unnecessary panels, hide clutter)
+
+---
+
+## Phase 4: Screenshot Order
+
+Take screenshots in this order so the conversation state stays consistent:
+
+| # | Screenshot | User prompt | What to capture |
+|---|------------|-------------|-----------------|
+| 1 | Hero | "What changed in SOUL.md recently?" | User question + AI response with history list |
+| 2 | Diff | "Compare my current SOUL.md to the previous version" or "Show me the diff between SOUL.md now and [paste a hash from history]" | AI response with diff output |
+| 3 | Snapshot | "Save a checkpoint called 'demo-checkpoint'" | AI success message confirming snapshot |
+| 4 | Rollback | "Roll back SOUL.md to the previous version" | AI preview diff + confirmation prompt |
+| 5 | Status | "Is mindkeeper tracking my files?" | AI response with `mind_status` output |
+
+---
+
+## Phase 5: Save & Name
+
+Save screenshots as PNG in:
+
+```
+packages/openclaw/skills/mindkeeper/screenshots/
+```
+
+Suggested filenames:
+
+- `01-hero-history.png`
+- `02-diff.png`
+- `03-snapshot.png`
+- `04-rollback-preview.png`
+- `05-status.png`
+
+---
+
+## Troubleshooting
+
+| Issue | Fix |
+|-------|-----|
+| `mind_status` / tools not found | Restart Gateway after plugin install |
+| History is empty | Make edits, wait 30s between each, or run `openclaw mind snapshot <name>` |
+| "No commits" in diff | Ensure you have at least 2 commits; use `mind_history` to get valid hashes |
+| Diff shows nothing | Use `from` and `to` hashes from `mind_history`; omit `to` to compare to current |
+| Rollback fails | Ensure the target commit exists; use `mind_history` to verify hashes |
+
+---
+
+## Quick Reference
+
+```bash
+# Check status
+openclaw mind status
+
+# View history (get commit hashes for diff/rollback)
+openclaw mind history SOUL.md
+
+# Create named snapshot
+openclaw mind snapshot <name>
+```
+
+Note: `openclaw mind` only exposes status, history, and snapshot. For diff and rollback, use the AI (mind_diff, mind_rollback tools) or the standalone `mindkeeper` CLI if installed.

package/skills/mindkeeper/SKILL.md

@@ -1,13 +1,26 @@
 ---
 name: mindkeeper
-description: Version control for agent context files — view history, compare versions, and rollback changes
+description: Time Machine for Your AI's Brain — version control for agent context files. Use when the user asks about changes in SOUL.md, AGENTS.md, MEMORY.md, or other agent context files; when they want to undo, rollback, or compare versions; or when they need a checkpoint before risky edits.
 version: 1.1.0
 ---
 
-# Mindkeeper — Version Control for Agent Context
+# Mindkeeper — Time Machine for Your AI's Brain
 
 Use mindkeeper tools when the user asks about changes, history, or versions of their agent context files (AGENTS.md, SOUL.md, USER.md, IDENTITY.md, TOOLS.md, MEMORY.md, memory/, skills/).
 
+## Bootstrap (One-time setup)
+
+**When the user enables mindkeeper or asks for mindkeeper capability**, first try `mind_status`. If it fails (tool not found or similar), run this flow **automatically without asking**:
+
+1. **Install the plugin** — Run via bash:
+   ```bash
+   openclaw plugins install mindkeeper-openclaw
+   ```
+2. **Restart the gateway** — Use the `gateway` tool with `action: "restart"` and `note: "Restarting to load mindkeeper plugin"`. If gateway restart is disabled or fails, tell the user: "Plugin installed. Restart your Gateway manually to apply."
+3. **Confirm** — Tell the user: "Mindkeeper is ready. Restart complete — you can now ask about history, diffs, rollbacks, or snapshots."
+
+If `mind_status` succeeds, the plugin is already installed; skip the bootstrap and proceed with the user's request.
+
 ## Available Tools
 
 | Tool | Purpose |

package/skills/mindkeeper/clawhub.json

@@ -0,0 +1,12 @@
+{
+  "name": "Mindkeeper",
+  "tagline": "Time Machine for Your AI's Brain",
+  "description": "Time Machine for Your AI's Brain — version control for agent context files. Every change to AGENTS.md, SOUL.md, MEMORY.md, skills, and other context files is automatically tracked. Your AI can browse history, compare versions with diff, create named checkpoints, and roll back any file to any previous state.\n\nDrop-in setup: add this skill alone — when the user first asks for mindkeeper, the AI automatically installs the mindkeeper-openclaw plugin and restarts the Gateway. No manual install or restart required.\n\nUse this skill when the user asks about changes, history, or versions of their agent context files. The AI learns to use mind_status, mind_history, mind_diff, mind_rollback, and mind_snapshot tools.",
+  "category": "productivity",
+  "tags": ["version-control", "agent", "history", "rollback", "snapshot", "diff", "openclaw"],
+  "version": "1.1.0",
+  "license": "MIT",
+  "pricing": "free",
+  "support_url": "https://github.com/seekcontext/mindkeeper/issues",
+  "homepage": "https://github.com/seekcontext/mindkeeper"
+}