mindkeeper-openclaw 0.2.25 → 0.2.27

package/README.md

@@ -2,15 +2,37 @@
 
 **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.
+
+On startup, the plugin also mirrors its built-in `mindkeeper` skill into the workspace so new sessions can still find the bootstrap instructions even if no separate ClawHub skill was installed.
+
+### 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 +47,39 @@ 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
 
+## Troubleshooting
+
+- If a fresh `/new` session says the plugin is missing right after install, restart Gateway once and retry. Some OpenClaw flows do not expose plugin tools or the built-in skill until startup finishes.
+- If tools still do not appear, verify that `mindkeeper-openclaw` is enabled in your OpenClaw config and that `mind_status`, `mind_history`, `mind_diff`, `mind_rollback`, and `mind_snapshot` are allowed tools.
+
+## 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

@@ -504,6 +504,7 @@ var SENSITIVE_FIELDS = ["commitMessage.llm.apiKey"];
 var DEFAULT_CONFIG = {
   tracking: {
     include: [
+      ".mindkeeper.json",
       "AGENTS.md",
       "SOUL.md",
       "USER.md",
@@ -1178,6 +1179,49 @@ function resolveModelFromConfig(config) {
   return { provider, model, baseUrl };
 }
 
+// src/skill-mirror.ts
+var import_node_fs2 = require("node:fs");
+var import_node_path6 = __toESM(require("node:path"));
+var SKILL_DIR_NAME = "mindkeeper";
+var SKILL_FILES = ["SKILL.md", "README.md", "clawhub.json"];
+function ensureWorkspaceSkillMirror(workspaceDir, options = {}) {
+  if (!workspaceDir) return;
+  const sourceDir = options.sourceDir ?? resolveBundledSkillDir();
+  const targetDir = import_node_path6.default.join(workspaceDir, SKILL_DIR_NAME);
+  if (!(0, import_node_fs2.existsSync)(sourceDir)) {
+    options.log?.warn?.(`[mindkeeper] Built-in skill directory not found: ${sourceDir}`);
+    return;
+  }
+  try {
+    (0, import_node_fs2.mkdirSync)(targetDir, { recursive: true });
+    const copied = [];
+    for (const file of SKILL_FILES) {
+      const sourceFile = import_node_path6.default.join(sourceDir, file);
+      const targetFile = import_node_path6.default.join(targetDir, file);
+      if (!(0, import_node_fs2.existsSync)(sourceFile)) {
+        options.log?.warn?.(`[mindkeeper] Built-in skill file missing: ${sourceFile}`);
+        continue;
+      }
+      if ((0, import_node_fs2.existsSync)(targetFile)) continue;
+      (0, import_node_fs2.copyFileSync)(sourceFile, targetFile);
+      copied.push(file);
+    }
+    if (copied.length > 0) {
+      options.log?.info?.(
+        `[mindkeeper] Mirrored built-in skill files to ${targetDir}: ${copied.join(", ")}`
+      );
+    }
+  } catch (err) {
+    options.log?.warn?.(`[mindkeeper] Failed to mirror built-in skill: ${String(err)}`);
+  }
+}
+function resolveBundledSkillDir() {
+  if (typeof __dirname !== "string" || __dirname.length === 0) {
+    throw new Error("mindkeeper: __dirname is unavailable while resolving the built-in skill");
+  }
+  return import_node_path6.default.resolve(__dirname, "..", "skills", SKILL_DIR_NAME);
+}
+
 // src/service.ts
 function createWatcherService(api, trackerRef) {
   let watcher = null;
@@ -1194,6 +1238,7 @@ function createWatcherService(api, trackerRef) {
         log.warn("[mindkeeper] No workspace directory in service context. Watcher disabled.");
         return;
       }
+      ensureWorkspaceSkillMirror(workspaceDir, { log: api.log });
       const llmProvider = await createOpenClawLlmProvider({
         config: ctx.config,
         log
@@ -1242,6 +1287,7 @@ function mindkeeperPlugin(api) {
   const trackerRef = { current: null };
   registerTrackerTools(api, trackerRef);
   registerTrackerCli(api, trackerRef);
+  ensureWorkspaceSkillMirror(api.getWorkspaceDir?.(), { log: api.log });
   const watcherService = createWatcherService(api, trackerRef);
   api.registerService?.(watcherService);
   ensureToolsInConfig(api);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mindkeeper-openclaw",
-  "version": "0.2.25",
+  "version": "0.2.27",
   "description": "OpenClaw plugin for mindkeeper: auto-snapshot, diff, and rollback for agent context files",
   "keywords": [
     "openclaw",

package/skills/mindkeeper/README.md

@@ -1,22 +1,42 @@
 # 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 the tools are not ready yet, it should first consider whether Gateway still needs to finish loading or restart before assuming the plugin is missing.
+
+## 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.
+
+In OpenClaw Plugin mode, the AI should prefer the `mind_*` tools for history, diff, snapshot, and rollback tasks. CLI commands are mainly for setup, troubleshooting, or manual terminal workflows.
+
+If you prefer to install the plugin yourself first:
 
 ```bash
 openclaw plugins install mindkeeper-openclaw
@@ -27,15 +47,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 +64,18 @@ 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 |
+| "Edit SOUL.md to change my tone" | Edit the file directly; mindkeeper should track the change automatically |
 
 ## 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. A brand-new `/new` session can briefly miss the tool context while startup is still finishing.
+- **Rollback not applying** — After rollback, run `/new` to reload the session with the restored file.
 
 ## Links
 

package/skills/mindkeeper/SKILL.md

@@ -1,33 +1,43 @@
 ---
 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.5
 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)
 
-**When the user enables mindkeeper or asks for mindkeeper capability**, first try `mind_status`. If it fails (tool not found or similar):
+**When the user enables mindkeeper or asks for mindkeeper capability**, first try `mind_status`. If it fails, do **not** assume the plugin is missing yet. It can also fail when Gateway has not finished loading the plugin, when tools are not exposed to the current session yet, or when the workspace copy of this skill is unavailable.
 
-1. **Ask for confirmation** — Tell the user: "Mindkeeper needs the mindkeeper-openclaw plugin to work. I'll need to run `openclaw plugins install mindkeeper-openclaw` and restart the Gateway. May I proceed?" **Do not install or restart until the user explicitly confirms.**
+1. **Diagnose conservatively** — Tell the user: "I can't access the mindkeeper tools yet. The plugin may be missing, Gateway may still need a restart, or the current session may not have loaded the skill/tool context yet." Only say the plugin is definitely missing if the runtime explicitly shows that `mindkeeper-openclaw` is not installed.
 
-2. **After user confirms** — Run this flow:
+2. **If the runtime confirms the plugin is missing and the user confirms**, run this flow:
    - **Install the plugin** — Run via bash:
      ```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."
+3. **If the plugin appears installed already** — Tell the user to retry after Gateway finishes loading or after a manual restart. If a workspace copy of the skill appears to be missing, mention that the session may not have loaded the built-in mindkeeper skill correctly yet.
+
+4. **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."
 
 If `mind_status` succeeds, the plugin is already installed; skip the bootstrap and proceed with the user's request.
 
+## Tool Preference
+
+In OpenClaw Plugin mode, prefer the `mind_*` tools over CLI commands for normal mindkeeper operations.
+
+- Use `mind_status`, `mind_history`, `mind_diff`, `mind_snapshot`, and `mind_rollback` whenever they are available.
+- Do not use `openclaw mind ...` or `mindkeeper ...` for routine history, diff, snapshot, or rollback requests if the plugin tools are available.
+- CLI commands are for one-time setup, troubleshooting, manual user workflows, or when the user explicitly asks for terminal commands.
+
 ## Available Tools
 
 | Tool | Purpose |
@@ -38,6 +48,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 |
@@ -49,14 +70,25 @@ If `mind_status` succeeds, the plugin is already installed; skip the bootstrap a
 | "Is mindkeeper tracking my files?" | `mind_status` |
 | "What does my history look like?" | `mind_history` without a file filter |
 
+## Direct Edit Requests
+
+If the user asks to directly edit a tracked file such as `SOUL.md`, `AGENTS.md`, or `MEMORY.md`, make the edit directly.
+
+- Do not block on CLI availability.
+- Do not mention unavailable CLI commands unless the user explicitly asked for a CLI-based workflow.
+- Mindkeeper's background watcher should capture the change automatically after the edit.
+- If relevant, you may mention that the change should now be tracked by mindkeeper.
+
 ## Tool Usage Guide
 
 ### mind_status
-Call this first if you're unsure whether mindkeeper is initialized or what files are being tracked.
+Call this first when the user asks about history, tracking state, snapshots, or rollback, or if you're unsure whether mindkeeper is initialized.
 ```
 mind_status → { initialized, workDir, pendingChanges, snapshots }
 ```
 
+You do not need to call `mind_status` before a simple direct edit request unless the user specifically asks about tracking or history.
+
 ### mind_history
 Returns a list of commits with short hash, date, and message.
 - `file` (optional): filter to a specific file path, e.g. `"SOUL.md"`
@@ -105,9 +137,13 @@ 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
+- **Use plugin tools first** — in OpenClaw Plugin mode, prefer `mind_*` tools over CLI commands for normal operations
 - **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.
+- **Keep user-facing messages focused** — if a task can be completed with file edits or `mind_*` tools, do not distract the user with unavailable CLI details

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.5",
   "license": "MIT",
   "pricing": "free",
   "homepage": "https://github.com/seekcontext/mindkeeper",