mindkeeper-openclaw 0.2.24 → 0.2.26

package/README.md

@@ -2,15 +2,35 @@
 
 **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.
+Every change to `AGENTS.md`, `SOUL.md`, `MEMORY.md`, `memory/**/*.md`, and `skills/**/*.md` can be tracked automatically. Your AI can inspect history, compare versions, create checkpoints, and guide rollback safely.
+
+## Why Use It
+
+This is the best experience if you want your AI to inspect history, show diffs, create checkpoints, and guide rollback in natural language:
+
+- **Natural-language history** — ask your AI what changed and when
+- **Preview-first rollback** — inspect the diff before restoring a file
+- **Named checkpoints** — create safety points before risky edits
+- **Background snapshots** — watcher starts with Gateway
+- **LLM-powered commit messages** — reuse your existing OpenClaw model and auth settings
 
 ## Install
 
+### Option 1 — Install the plugin directly
+
 ```bash
 openclaw plugins install mindkeeper-openclaw
 ```
 
-Restart your Gateway once. The plugin auto-starts a background watcher and registers 5 tools.
+Then restart your Gateway once.
+
+### Option 2 — Install the skill and let the AI guide setup
+
+```bash
+clawhub install mindkeeper
+```
+
+On first use, the AI checks whether `mindkeeper-openclaw` is available. If it is missing, the AI asks for your confirmation before installing the plugin and before restarting Gateway. If automatic restart is unavailable, it tells you to restart Gateway manually.
 
 ## Talk to Your AI
 
@@ -25,29 +45,34 @@ Once installed, ask in natural language:
 
 | 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_history` | Browse change history for one file or all tracked files |
+| `mind_diff` | Compare two versions with a unified diff |
+| `mind_rollback` | Preview rollback first, then execute after confirmation |
 | `mind_snapshot` | Create named checkpoints before risky changes |
-| `mind_status` | Show what files are tracked and what's changed |
+| `mind_status` | Show what files are tracked and what is pending |
 
 ## 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
+openclaw mind status
+openclaw mind history SOUL.md
+openclaw mind snapshot stable-v2
 ```
 
 ## Requirements
 
-- Node.js ≥ 22
+- Node.js >= 22
 - OpenClaw with Gateway running
 
+## Commit Messages
+
+OpenClaw Plugin mode is currently the only mode that supports LLM-generated commit messages. If no supported model or API key is available, mindkeeper falls back to template messages automatically.
+
 ## Links
 
 - [GitHub](https://github.com/seekcontext/mindkeeper)
 - [Core CLI](https://www.npmjs.com/package/mindkeeper) — Standalone version without OpenClaw
+- [Mindkeeper Skill](https://github.com/seekcontext/mindkeeper/blob/main/packages/openclaw/skills/mindkeeper/SKILL.md)
 
 ## License
 

package/dist/index.js

@@ -405,12 +405,12 @@ var IsomorphicGitStore = class {
    * when gitdir is separated from the work directory.
    */
   async getChangedFiles(filepaths) {
-    const filesToCheck = filepaths ?? await this.listWorkdirFiles();
     let headOid = null;
     try {
       headOid = await import_isomorphic_git.default.resolveRef({ fs: import_node_fs.default, dir: this.workDir, gitdir: this.gitDir, ref: "HEAD" });
     } catch {
     }
+    const filesToCheck = filepaths ?? await this.listTrackedCandidates(headOid);
     const entries = [];
     for (const filepath of filesToCheck) {
       const fullPath = import_node_path.default.join(this.workDir, filepath);
@@ -443,6 +443,14 @@ var IsomorphicGitStore = class {
     }
     return entries;
   }
+  async listTrackedCandidates(headOid) {
+    const workdirFiles = await this.listWorkdirFiles();
+    if (!headOid) {
+      return workdirFiles;
+    }
+    const headFiles = await this.getCommitFiles(headOid);
+    return Array.from(/* @__PURE__ */ new Set([...workdirFiles, ...headFiles]));
+  }
   async listWorkdirFiles() {
     const files = [];
     await this.walkDir(this.workDir, this.workDir, files);
@@ -496,6 +504,7 @@ var SENSITIVE_FIELDS = ["commitMessage.llm.apiKey"];
 var DEFAULT_CONFIG = {
   tracking: {
     include: [
+      ".mindkeeper.json",
       "AGENTS.md",
       "SOUL.md",
       "USER.md",
@@ -684,6 +693,7 @@ var GITDIR_NAME = ".mindkeeper";
 var Tracker = class {
   store;
   config;
+  configLoaded;
   llmProvider;
   workDir;
   gitDir;
@@ -692,6 +702,7 @@ var Tracker = class {
     this.workDir = import_node_path3.default.resolve(options.workDir);
     this.gitDir = options.gitDir ? import_node_path3.default.resolve(options.gitDir) : import_node_path3.default.join(this.workDir, GITDIR_NAME);
     this.config = options.config ?? getDefaultConfig();
+    this.configLoaded = options.config !== void 0;
     this.configOverrides = options.configOverrides;
     this.llmProvider = options.llmProvider;
     this.store = new IsomorphicGitStore({
@@ -700,7 +711,7 @@ var Tracker = class {
     });
   }
   async init() {
-    this.config = await loadConfig(this.workDir, this.configOverrides);
+    await this.ensureConfigLoaded();
     await this.store.init();
     await this.ensureGitignore();
     const changed = await this.getTrackedChangedFiles();
@@ -712,6 +723,7 @@ var Tracker = class {
     return { initialFiles: changed.map((e) => e.filepath) };
   }
   async snapshot(options) {
+    await this.ensureConfigLoaded();
     const changed = await this.getTrackedChangedFiles();
     const filesToCommit = changed.map((e) => e.filepath);
     if (filesToCommit.length > 0) {
@@ -777,21 +789,11 @@ var Tracker = class {
     };
   }
   async status() {
-    let initialized = false;
-    try {
-      await this.resolveHead();
-      initialized = true;
-    } catch {
-      initialized = false;
-    }
+    await this.ensureConfigLoaded();
+    const initialized = await this.isInitialized();
     const pendingChanges = initialized ? await this.getTrackedChangedFiles() : [];
     const snapshots = initialized ? await this.store.listTags() : [];
-    const trackedPatterns = this.config.tracking.include;
-    let trackedFileCount = 0;
-    if (initialized) {
-      const allChanged = await this.store.getChangedFiles();
-      trackedFileCount = allChanged.length + pendingChanges.length;
-    }
+    const trackedFileCount = initialized ? await this.getTrackedFileCount() : 0;
     return {
       initialized,
       workDir: this.workDir,
@@ -802,6 +804,7 @@ var Tracker = class {
     };
   }
   async autoSnapshot() {
+    await this.ensureConfigLoaded();
     const changed = await this.getTrackedChangedFiles();
     if (changed.length === 0) return null;
     const filesToCommit = changed.map((e) => e.filepath);
@@ -842,6 +845,16 @@ var Tracker = class {
     const allChanged = await this.store.getChangedFiles();
     return allChanged.filter((entry) => this.isTracked(entry.filepath));
   }
+  async getTrackedFileCount() {
+    const files = new Set(await this.store.listWorkdirFiles());
+    const headOid = await this.resolveHead().catch(() => null);
+    if (headOid) {
+      for (const filepath of await this.store.getCommitFiles(headOid)) {
+        files.add(filepath);
+      }
+    }
+    return Array.from(files).filter((filepath) => this.isTracked(filepath)).length;
+  }
   isTracked(filepath) {
     const allExcluded = [...this.config.tracking.exclude, ...ALWAYS_EXCLUDED];
     for (const pattern of allExcluded) {
@@ -852,6 +865,21 @@ var Tracker = class {
     }
     return false;
   }
+  async ensureConfigLoaded() {
+    if (this.configLoaded) {
+      return;
+    }
+    this.config = await loadConfig(this.workDir, this.configOverrides);
+    this.configLoaded = true;
+  }
+  async isInitialized() {
+    try {
+      await import_promises3.default.access(import_node_path3.default.join(this.gitDir, "HEAD"));
+      return true;
+    } catch {
+      return false;
+    }
+  }
   async resolveHead() {
     const git2 = await import("isomorphic-git");
     const fs2 = await import("node:fs");
@@ -873,7 +901,11 @@ var Tracker = class {
 ${entry}
 `;
       await import_promises3.default.writeFile(gitignorePath, newContent, "utf-8");
-    } catch {
+    } catch (err) {
+      const code = err?.code;
+      if (code !== "ENOENT") {
+        throw err;
+      }
       await import_promises3.default.writeFile(gitignorePath, `${entry}
 `, "utf-8");
     }
@@ -1167,11 +1199,10 @@ function createWatcherService(api, trackerRef) {
         config: ctx.config,
         log
       });
-      const configOverrides = api.pluginConfig;
       const tracker = new Tracker({
         workDir: workspaceDir,
         llmProvider: llmProvider ?? void 0,
-        configOverrides: configOverrides ?? void 0
+        configOverrides: api.pluginConfig
       });
       await tracker.init();
       trackerRef.current = tracker;
@@ -1223,8 +1254,9 @@ function ensureToolsInConfig(api) {
   if (!cfg || !writeConfigFile) return;
   const allow = cfg.tools?.allow ?? [];
   const alsoAllow = cfg.tools?.alsoAllow ?? [];
-  const target = allow.length > 0 ? allow : alsoAllow;
-  const key = allow.length > 0 ? "allow" : "alsoAllow";
+  const hasAllow = Array.isArray(cfg.tools?.allow);
+  const target = hasAllow ? allow : alsoAllow;
+  const key = hasAllow ? "allow" : "alsoAllow";
   const existing = new Set(
     target.map((e) => String(e).trim().toLowerCase()).filter(Boolean)
   );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mindkeeper-openclaw",
-  "version": "0.2.24",
+  "version": "0.2.26",
   "description": "OpenClaw plugin for mindkeeper: auto-snapshot, diff, and rollback for agent context files",
   "keywords": [
     "openclaw",
@@ -29,6 +29,14 @@
     "scripts/postinstall-merge-config.cjs",
     "README.md"
   ],
+  "scripts": {
+    "build": "node build.mjs",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run clean && npm run build",
+    "postinstall": "node scripts/postinstall-merge-config.cjs"
+  },
   "openclaw": {
     "extensions": [
       "./dist/index.js"
@@ -43,18 +51,13 @@
   "devDependencies": {
     "@types/node": "^22.0.0",
     "esbuild": "^0.27.3",
-    "typescript": "^5.7.0"
+    "typescript": "^5.7.0",
+    "vitest": "^3.2.4"
   },
   "engines": {
     "node": ">=22.0.0"
   },
   "publishConfig": {
     "access": "public"
-  },
-  "scripts": {
-    "build": "node build.mjs",
-    "typecheck": "tsc --noEmit",
-    "clean": "rm -rf dist",
-    "postinstall": "node scripts/postinstall-merge-config.cjs"
   }
-}
+}

package/scripts/postinstall-merge-config.cjs

@@ -55,8 +55,9 @@ function run() {
 
   const allow = cfg.tools?.allow ?? [];
   const alsoAllow = cfg.tools?.alsoAllow ?? [];
-  const target = allow.length > 0 ? allow : alsoAllow;
-  const key = allow.length > 0 ? "allow" : "alsoAllow";
+  const hasAllow = Array.isArray(cfg.tools?.allow);
+  const target = hasAllow ? allow : alsoAllow;
+  const key = hasAllow ? "allow" : "alsoAllow";
 
   const existing = new Set(
     target.map((e) => String(e).trim().toLowerCase()).filter(Boolean),

package/skills/mindkeeper/README.md

@@ -1,22 +1,40 @@
 # 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.
+**Time Machine for Your AI's Brain** — install this skill if you want your AI to inspect history, show diffs, create checkpoints, and guide rollback in natural language.
 
-**Setup:** Add this skill alone. When you first ask for mindkeeper capability, the AI will ask for your confirmation before installing the mindkeeper-openclaw plugin and restarting the Gateway. You can also install the plugin manually (see Requirements).
+This skill teaches the AI how to bootstrap and use the `mindkeeper-openclaw` plugin. It is the easiest way to get the OpenClaw Plugin experience without manually setting everything up first.
 
-## What It Does
+## Why Use It
 
-- **Browse history** — See what changed in SOUL.md, AGENTS.md, or any tracked file
+- **Guided setup** — the AI checks whether the plugin is available and walks through first-use install
+- **Safe permissions model** — plugin install and Gateway restart always require explicit confirmation
+- **Natural-language usage** — ask about changes, diffs, rollback, and checkpoints conversationally
+- **Rollback guardrails** — preview first, confirm second
+
+## Install
+
+```bash
+clawhub install mindkeeper
+```
+
+On first use, the AI checks whether `mindkeeper-openclaw` is available. If it is missing, the AI asks for your confirmation before installing the plugin and before restarting Gateway. If automatic restart is unavailable, it tells you to restart Gateway manually.
+
+## What It Enables
+
+- **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)
+- **Rollback** — Restore any file to a previous version with preview + confirmation
 - **Named snapshots** — Create checkpoints before risky changes
+- **LLM commit messages** — Available in OpenClaw Plugin mode using your existing OpenClaw model and auth settings
 
 ## Requirements
 
-- Node.js ≥ 22
+- Node.js >= 22
 - OpenClaw with Gateway running
 
-The mindkeeper-openclaw plugin provides the mind_* tools. The AI will ask for your confirmation before running `openclaw plugins install mindkeeper-openclaw` and restarting the Gateway on first use. Alternatively, install it yourself:
+The `mindkeeper-openclaw` plugin provides the actual `mind_*` tools and background watcher. This skill provides the guidance and first-use bootstrap behavior.
+
+If you prefer to install the plugin yourself first:
 
 ```bash
 openclaw plugins install mindkeeper-openclaw
@@ -27,15 +45,15 @@ openclaw plugins install mindkeeper-openclaw
 
 | Action | Purpose |
 |--------|---------|
-| `openclaw plugins install mindkeeper-openclaw` | Fetches the official plugin from npm to add mind_status, mind_history, mind_diff, mind_rollback, mind_snapshot tools |
+| `openclaw plugins install mindkeeper-openclaw` | Fetches the official plugin and makes the `mind_*` tools available |
 | Gateway restart | Loads the newly installed plugin into the running Gateway |
 
-**User consent:** The AI will not run these commands until you explicitly confirm. This ensures you control when plugins are installed and when the Gateway restarts.
+**User consent is required** before either action runs.
 
 ## How to Use
 
-1. Install this skill: `clawhub install mindkeeper`
-2. Ask your AI in natural language. On first use, the AI will ask for confirmation before installing the plugin and restarting the Gateway:
+1. Install the skill: `clawhub install mindkeeper`
+2. Ask your AI 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"
@@ -44,17 +62,17 @@ openclaw plugins install mindkeeper-openclaw
 ## Examples
 
 | User says | AI action |
-|-----------|------------|
-| "What changed in SOUL.md?" | `mind_history` with file filter |
+|-----------|-----------|
+| "What changed in SOUL.md?" | `mind_history` with a 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 |
+| "Undo that change" | `mind_rollback` preview first, then execute after confirmation |
+| "Save a checkpoint before I experiment" | `mind_snapshot` with a 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.
+- **History is empty** — Call `mind_status` to check whether 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, run `/new` to reload the session with the restored file.
 
 ## Links
 

package/skills/mindkeeper/SKILL.md

@@ -1,14 +1,14 @@
 ---
 name: mindkeeper
 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.2.1
+version: 1.2.3
 homepage: https://github.com/seekcontext/mindkeeper
 repository: https://github.com/seekcontext/mindkeeper
 ---
 
 # 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/).
+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`, `HEARTBEAT.md`, `MEMORY.md`, `memory/`, `skills/`).
 
 ## Bootstrap (One-time setup)
 
@@ -21,8 +21,8 @@ Use mindkeeper tools when the user asks about changes, history, or versions of t
      ```bash
      openclaw plugins install mindkeeper-openclaw
      ```
-   - **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."
-   - **Confirm** — Tell the user: "Mindkeeper is ready. Restart complete — you can now ask about history, diffs, rollbacks, or snapshots."
+   - **Restart Gateway if the runtime supports it** — Use the available runtime mechanism to restart Gateway. If restart is unavailable or fails, tell the user: "Plugin installed. Restart your Gateway manually to apply."
+   - **Confirm** — If restart succeeded, tell the user: "Mindkeeper is ready. Restart complete — you can now ask about history, diffs, rollbacks, or snapshots." If restart did not happen, tell the user that the plugin is installed but Gateway must be restarted before the tools will appear.
 
 3. **Alternative** — If the user prefers to install manually, tell them: "Run `openclaw plugins install mindkeeper-openclaw` in your terminal, then restart your Gateway. After that, mindkeeper will be ready."
 
@@ -38,6 +38,17 @@ If `mind_status` succeeds, the plugin is already installed; skip the bootstrap a
 | `mind_rollback` | Restore a file to a previous version (always preview first) |
 | `mind_snapshot` | Save a named checkpoint before making significant changes |
 
+## Tracking Scope
+
+Mindkeeper tracks these files by default:
+
+- `AGENTS.md`, `SOUL.md`, `USER.md`, `IDENTITY.md`
+- `TOOLS.md`, `HEARTBEAT.md`, `MEMORY.md`
+- `memory/**/*.md`
+- `skills/**/*.md`
+
+Excluded by default: `BOOTSTRAP.md`, `canvas/**`, `.git/`, `.mindkeeper/`.
+
 ## When to Use
 
 | User says… | Action |
@@ -105,9 +116,11 @@ After success, tell the user: **"Run `/new` to apply the changes to your current
 
 ## Important Notes
 
+- **This skill is the guide, the plugin is the engine** — the `mindkeeper-openclaw` plugin provides the actual `mind_*` tools and watcher; this skill teaches the AI how to bootstrap and use them safely
 - **Rollback is per-file** — it only restores the specified file, not all files at once
 - **Rollbacks are non-destructive** — every rollback creates a new commit, so it can itself be undone
 - **Auto-snapshots run in the background** — the user doesn't need to manually save; mindkeeper captures every change automatically
+- **LLM commit messages are plugin-only for now** — currently supported only through the OpenClaw plugin; standalone CLI mode falls back to template messages
 - **Named snapshots are the safety net** — encourage users to snapshot before major personality or rule changes
 - **If history is empty** — mindkeeper may not have initialized yet, or no changes have been made since install. Call `mind_status` to check.
 - **Commit hashes** — always use the `oid` field from `mind_history` results. Short 8-character hashes are fine.

package/skills/mindkeeper/clawhub.json

@@ -1,10 +1,10 @@
 {
   "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\nSetup: add this skill alone. When the user first asks for mindkeeper, the AI will ask for explicit confirmation before installing the mindkeeper-openclaw plugin and restarting the Gateway. User consent is required for plugin install and Gateway restart.\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.",
+  "description": "Time Machine for Your AI's Brain — install this skill if you want your AI to inspect history, show diffs, create checkpoints, and guide rollback in natural language across agent context files.\n\nSetup: add this skill alone. On first use, the AI checks whether the mindkeeper-openclaw plugin is available. If it is not, the AI asks for explicit confirmation before installing the plugin and before restarting Gateway. User consent is required for plugin install and Gateway restart.\n\nUse this skill when the user asks about changes, history, or versions of their agent context files. The skill teaches the AI how to bootstrap and use the mind_status, mind_history, mind_diff, mind_rollback, and mind_snapshot tools safely.",
   "category": "productivity",
   "tags": ["version-control", "agent", "history", "rollback", "snapshot", "diff", "openclaw"],
-  "version": "1.2.1",
+  "version": "1.2.3",
   "license": "MIT",
   "pricing": "free",
   "homepage": "https://github.com/seekcontext/mindkeeper",

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 context-vault contributors
-
-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.